Search: M8a snapshot store and nav history cap

- New `lib/search/snapshot-store.svelte.ts` per plan §3.7: refcounted map of
  search-result snapshots with monotonic `sr-N` ids, 10,000-entry cap with
  label annotation on truncation, and a "last dialog attempt" slot.
- `navigation-history.ts`: `MAX_HISTORY_PER_TAB = 100`, `push()` now returns
  `{ history, droppedEntries }` aggregating both truncated-forward and
  oldest-evicted entries. `pushPath` stays as a backward-compatible delegate.
- `tab-state-manager.svelte.ts`: new `pushHistoryEntry` and
  `transferSnapshotRefs` helpers wire snapshot refcounting in one place.
  Close transfers refs to the closed-tab stack; reopen pops without
  inc/dec; stack eviction (cap overflow / trim) is the actual release
  point. Non-recording `closeTab` / `closeOtherTabs` release immediately.
- `DualPaneExplorer.svelte`: 7 push callsites switched to `pushHistoryEntry`.
- Tests: 99 new/updated assertions across `snapshot-store.svelte.ts.test.ts`
  (refcount lifecycle, last-attempt slot swaps, entries cap),
  `navigation-history.test.ts` (cap eviction, dropped-entries surface,
  cross-volume cap, pushPath delegate), and `tab-state-manager.test.ts`
  (push releases dropped refs; close/reopen/evict/trim ref lifecycle for
  both recording and non-recording paths).
- Docs: search/CLAUDE.md gains a "Snapshot store (M8a)" section;
  navigation/CLAUDE.md documents the new `push()` return shape and cap;
  tabs/CLAUDE.md documents the transfer-then-release closed-stack model.

Author: vdavid

apps/desktop/src/lib/file-explorer/navigation/CLAUDE.md

@@ -27,13 +27,28 @@ Purely functional: all operations return new objects, never mutate.
 ```
 NavigationHistory = { stack: HistoryEntry[], currentIndex: number }
 HistoryEntry = { volumeId: string, path: string, networkHost?: NetworkHost }
+PushResult = { history: NavigationHistory, droppedEntries: HistoryEntry[] }
 ```
 
 Key functions: `createHistory`, `push`, `pushPath`, `back`, `forward`, `getCurrentEntry`, `getCurrentPath`, `canGoBack`,
-`canGoForward`, `setCurrentIndex`, `getEntryAt`.
-
-`push` returns the **same reference** when the new entry equals the current one (deduplication). Callers can use
-reference equality to skip re-renders.
+`canGoForward`, `setCurrentIndex`, `getEntryAt`. Plus the constant `MAX_HISTORY_PER_TAB = 100`.
+
+`push` returns `{ history, droppedEntries }`. `history` is the new stack; `droppedEntries` aggregates every entry the
+push removed: the truncated-forward tail (when pushing after `back()`) and the oldest entries evicted to honor
+`MAX_HISTORY_PER_TAB`. Callers that need to release per-entry resources iterate `droppedEntries`; the search-results
+snapshot store (`lib/search/snapshot-store.svelte.ts`) is the only consumer today. When the new entry equals the current
+entry, `push()` returns the **same `history` reference** with an empty `droppedEntries`, so callers using `===`
+deduplication still work.
+
+`pushPath` is a thin delegate that calls `push` and returns just the new history (discarding `droppedEntries`). It's
+backwards-compatible for callers that don't care about released resources. Callers that need refcount-decrements (the
+tab-state manager) must use `push()` directly — or, more conveniently, the `pushHistoryEntry` helper exposed by
+`lib/file-explorer/tabs/tab-state-manager.svelte.ts`, which wraps the `push()` call and releases search-results snapshot
+refs in one step.
+
+The cap (100) applies to every volume — local, network, MTP, search-results — uniformly. Tightening below 100 would
+start to hurt power users who navigate deeply and rely on `⌘[` for orientation. Bumping above 100 isn't necessary; each
+`HistoryEntry` is three string fields, so the memory headroom is comfortable.
 
 Entries carry full `volumeId` (navigating back can cross volume boundaries, for example from an external drive back to
 `root`).

apps/desktop/src/lib/file-explorer/navigation/navigation-history.test.ts

@@ -13,6 +13,19 @@
 
 import type { NetworkHost } from '../types'
 
+/**
+ * Per-tab cap on the navigation stack. When `push()` would grow the stack past this
+ * count, the oldest entries are dropped (FIFO) and returned in `droppedEntries` so
+ * the caller can release any per-entry resources (search-results snapshot refs, in
+ * the M8a wiring).
+ *
+ * 100 keeps a few sessions of casual browsing in reach while bounding memory: each
+ * `HistoryEntry` is ~3 string fields, so even 100 entries per tab × 10 tabs × 2
+ * panes is negligible. Tightening below 100 would start to hurt power users who
+ * navigate deeply and rely on `⌘[` for orientation.
+ */
+export const MAX_HISTORY_PER_TAB = 100
+
 /** A single entry in the navigation history */
 export interface HistoryEntry {
   /** The volume ID (like 'root', 'network', '/Volumes/MyDrive') */
@@ -30,6 +43,22 @@ export interface NavigationHistory {
   currentIndex: number
 }
 
+/**
+ * Result of `push()`. `history` is the new stack; `droppedEntries` aggregates
+ * everything `push()` removed in service of the call:
+ *   - forward entries truncated when pushing after a `back()`
+ *   - oldest entries evicted to honor `MAX_HISTORY_PER_TAB`
+ *
+ * Callers that don't care about released resources can ignore `droppedEntries`
+ * (and most do; the search-results snapshot store is the only consumer today).
+ * `pushPath` is one such caller — it discards the field and returns just the
+ * history for backwards compatibility.
+ */
+export interface PushResult {
+  history: NavigationHistory
+  droppedEntries: HistoryEntry[]
+}
+
 /**
  * Creates a new history with the initial entry.
  */
@@ -55,29 +84,53 @@ function entriesEqual(a: HistoryEntry, b: HistoryEntry): boolean {
 
 /**
  * Pushes a new entry to the history stack.
- * Truncates any forward history (entries after currentIndex).
- * If the new entry is the same as the current entry, returns unchanged history.
+ *
+ * - Truncates any forward history (entries after currentIndex) and reports the
+ *   removed entries in `droppedEntries`.
+ * - If the new entry equals the current entry, returns the unchanged history with
+ *   an empty `droppedEntries` (reference-equal on `history` so callers using `===`
+ *   dedup still work).
+ * - Caps the stack at `MAX_HISTORY_PER_TAB`. Overflow evicts the **oldest** entries
+ *   (front of the stack); evicted entries are included in `droppedEntries` and the
+ *   `currentIndex` is adjusted so it still points at the same logical position.
+ *
+ * `droppedEntries` covers both kinds of removals; callers that care about released
+ * resources (the search-results snapshot store, today) iterate the array once.
  */
-export function push(history: NavigationHistory, entry: HistoryEntry): NavigationHistory {
+export function push(history: NavigationHistory, entry: HistoryEntry): PushResult {
   const currentEntry = history.stack[history.currentIndex]
   if (entriesEqual(entry, currentEntry)) {
-    return history
+    return { history, droppedEntries: [] }
   }
 
-  // Truncate forward history and add the new entry
-  const newStack = [...history.stack.slice(0, history.currentIndex + 1), entry]
+  // 1. Truncate forward history (entries after currentIndex are dropped).
+  const truncated = history.stack.slice(history.currentIndex + 1)
+  // 2. Append the new entry.
+  let newStack = [...history.stack.slice(0, history.currentIndex + 1), entry]
+  // 3. Evict the oldest entries if the cap was exceeded.
+  let evictedFromFront: HistoryEntry[] = []
+  if (newStack.length > MAX_HISTORY_PER_TAB) {
+    const overflow = newStack.length - MAX_HISTORY_PER_TAB
+    evictedFromFront = newStack.slice(0, overflow)
+    newStack = newStack.slice(overflow)
+  }
   return {
-    stack: newStack,
-    currentIndex: newStack.length - 1,
+    history: {
+      stack: newStack,
+      currentIndex: newStack.length - 1,
+    },
+    droppedEntries: [...evictedFromFront, ...truncated],
   }
 }
 
 /**
  * Convenience function to push just a path change (same volume).
+ * Delegates to `push()` and returns only the new history (discards `droppedEntries`).
+ * Callers that need to release per-entry resources should use `push()` directly.
  */
 export function pushPath(history: NavigationHistory, path: string): NavigationHistory {
   const currentEntry = history.stack[history.currentIndex]
-  return push(history, { volumeId: currentEntry.volumeId, path })
+  return push(history, { volumeId: currentEntry.volumeId, path }).history
 }
 
 /**

apps/desktop/src/lib/file-explorer/navigation/navigation-history.ts

@@ -50,7 +50,6 @@
 
     import {
         createHistory,
-        push,
         pushPath,
         back,
         forward,
@@ -67,6 +66,7 @@
         getTabCount,
         closeTabRecording,
         closeOtherTabsRecording,
+        pushHistoryEntry,
         trimClosedStack,
         getClosedStackSize,
         MAX_TABS_PER_PANE,
@@ -510,7 +510,7 @@
     function handleNetworkHostChange(pane: 'left' | 'right', host: NetworkHost | null) {
         setPaneHistory(
             pane,
-            push(getPaneHistory(pane), {
+            pushHistoryEntry(getPaneHistory(pane), {
                 volumeId: 'network',
                 path: 'smb://',
                 networkHost: host ?? undefined,
@@ -648,7 +648,7 @@
         // In-place navigation (normal flow or pinned tab at cap)
         setPaneVolumeId(pane, volumeId)
         setPanePath(pane, targetPath)
-        setPaneHistory(pane, push(getPaneHistory(pane), { volumeId, path: targetPath }))
+        setPaneHistory(pane, pushHistoryEntry(getPaneHistory(pane), { volumeId, path: targetPath }))
         focusedPane = pane
 
         saveAppStatus({
@@ -677,7 +677,7 @@
             if (generation !== volumeChangeGeneration) return
             if (betterPath !== targetPath && betterPath !== getPanePath(pane)) {
                 setPanePath(pane, betterPath)
-                setPaneHistory(pane, push(getPaneHistory(pane), { volumeId, path: betterPath }))
+                setPaneHistory(pane, pushHistoryEntry(getPaneHistory(pane), { volumeId, path: betterPath }))
                 saveAppStatus({ [paneKey(pane, 'path')]: betterPath })
                 saveTabsForPaneSide(pane)
             }
@@ -758,7 +758,7 @@
 
         setPaneVolumeId(pane, defaultVolumeId)
         setPanePath(pane, defaultPath)
-        setPaneHistory(pane, push(getPaneHistory(pane), { volumeId: defaultVolumeId, path: defaultPath }))
+        setPaneHistory(pane, pushHistoryEntry(getPaneHistory(pane), { volumeId: defaultVolumeId, path: defaultPath }))
         saveAppStatus({ [paneKey(pane, 'volumeId')]: defaultVolumeId, [paneKey(pane, 'path')]: defaultPath })
         saveTabsForPaneSide(pane)
     }
@@ -780,7 +780,7 @@
         tab.unreachable = null
         setPaneVolumeId(pane, volumeId)
         setPanePath(pane, originalPath)
-        setPaneHistory(pane, push(getPaneHistory(pane), { volumeId, path: originalPath }))
+        setPaneHistory(pane, pushHistoryEntry(getPaneHistory(pane), { volumeId, path: originalPath }))
         saveTabsForPaneSide(pane)
 
         // Sync the volume selector; retry may have fixed a mount that was stale
@@ -800,7 +800,7 @@
         const homePath = '~'
         setPaneVolumeId(pane, defaultId)
         setPanePath(pane, homePath)
-        setPaneHistory(pane, push(getPaneHistory(pane), { volumeId: defaultId, path: homePath }))
+        setPaneHistory(pane, pushHistoryEntry(getPaneHistory(pane), { volumeId: defaultId, path: homePath }))
         saveTabsForPaneSide(pane)
         log.info('Unreachable tab opened home folder for {pane} pane', { pane })
     }
@@ -2478,7 +2478,7 @@
         targetPaneRef?.setNetworkHost(host)
         setPaneHistory(
             target,
-            push(getPaneHistory(target), {
+            pushHistoryEntry(getPaneHistory(target), {
                 volumeId: 'network',
                 path: 'smb://',
                 networkHost: host ?? undefined,

apps/desktop/src/lib/file-explorer/pane/DualPaneExplorer.svelte

@@ -98,6 +98,22 @@ Each entry stores `{ tab, originalIndex }` where `tab` is a `$state.snapshot` of
 `closeOtherTabsRecording` pushes closed tabs in right-to-left order (rightmost first). Popping in reverse and
 re-inserting at `originalIndex` restores the exact pre-close arrangement.
 
+**Search-results snapshot refs (M8a)**: the closed-tab stack also carries snapshot-ref obligations for any
+`search-results://<id>` paths in the closed tab's history. The model is "transfer on close, release on eviction":
+
+- `closeTabRecording` / `closeOtherTabsRecording` do **not** decrement snapshot refs when they push the closed tab onto
+  the stack. The refs effectively transfer ownership from the live tab's history to the closed-stack entry, keeping the
+  snapshot alive so a `⌘⇧T` reopen restores a usable pane.
+- `reopenLastClosedTab` just pops the entry back; refs are still alive, no inc/dec needed.
+- The stack's own eviction (`pushClosed` cap overflow or `trimClosedStack`) is the actual decrement point: each evicted
+  entry's history is walked and every `search-results://` path releases a ref.
+- The non-recording `closeTab` / `closeOtherTabs` (used in tests and programmatic flows) release refs immediately, since
+  the close isn't recorded anywhere.
+
+The bookkeeping is concentrated in `tab-state-manager.svelte.ts`'s
+`transferSnapshotRefs(closedTab, 'transfer' | 'release')` helper, called once at each transition. See
+`lib/search/CLAUDE.md` § "Snapshot store (M8a, §3.7)" for the broader picture.
+
 The Tab menu's "Reopen closed tab" item enables/disables based on the focused pane's stack via the
 `set_reopen_closed_tab_enabled` Tauri command (mirrors the `update_pin_tab_menu` pattern). Frontend pushes the state
 after every close, reopen, and focus change. Empty-stack reopen shows a toast ("No recently closed tabs in this pane.");