Navigation: wire navigate(), delete the old braid

- Migrate every coordinator handler + external write-caller onto `navigate(intent): NavigateResult`, then DELETE the four-function braid: `handlePathChange`, `applyPathChange`, `handleVolumeChange`, `applyVolumePathCorrection`, `handleNavigationAction`, `updatePaneAfterHistoryNavigation`, the coordinator `navigateToPath`, `volumeChangeGeneration`, and the `applyPathChange` volume-prefix forensics.
- Build the store-backed `NavigateDeps` + a per-pane `tokens` map + a global `correctionGen` holder in `DualPaneExplorer`, mirroring how `paneAccess` is built. `navigate()`'s `commit` is now the only writer of `setPaneVolumeId`/`setPanePath`/`setPaneHistory` outside the five M5 edge-flow handlers and the two network-host history pushes (`handleNetworkHostChange`, `mirrorNetworkStateToPane`).
- DPE render callbacks: `onPathChange` → `commitPathFromListing` (+ cursor-restore shim); `onVolumeChange` → `navigate({ volumeId, path })`. Bus `nav.back/forward/parent` → `navigate({ history })`. `mcp-nav-to-path` adapter calls `navigate()` directly and forwards the refusal `message` verbatim as the `mcp-response` error (L12, byte-identical). `navigate-and-select`, `go-to-latest`, `handleSearchNavigate`, `openSearchSnapshotInPane`, `selectVolumeBy*`, and the `copyPathBetweenPanes` mirrors all retire onto `navigate()`.
- `ExplorerAPI`: `navigateToPath` + `navigate(action)` collapse into `navigate(intent) => NavigateResult`.
- Move the in-place pinned-tab fork (L7) from `navigate()`'s in-place arm to `commitPathFromListing`, so FilePane-internal navigation (Enter on a folder) forks identically to coordinator-initiated nav. The volume-switch fork stays at the `navigate()` call.
- Fix two M2-missed behavior differences found via E2E, both adapting `navigate()` (M1 assertions untouched): the cross-volume snapshot arm now swallows a `resolveVolume` rejection into a no-op (matching the old try/catch) so a fire-and-forget `mcp-nav-to-path` can't raise an unhandled rejection; the background path-correction is gated by a SINGLE GLOBAL `correctionGen` (the old `volumeChangeGeneration` was global, not per-pane) so a simultaneous two-pane volume reset can't run both corrections and freeze the webview. Added regression tests for both.
- Re-point the M1 regression suites + `navigate-and-select`/`go-to-latest` tests onto the new wiring (plumbing only; refusal strings pinned byte-for-byte). Doc sweep: `snapshot-pane-navigation.ts`, `pane/CLAUDE.md`, and the `commitPathFromListing` doc line (it consults only the foreign-path policy, not the token).

Author: vdavid

apps/desktop/src/lib/downloads/go-to-latest.test.ts

@@ -1,4 +1,5 @@
 import { describe, it, expect, vi, beforeEach } from 'vitest'
+import type { NavigateResult } from '$lib/file-explorer/pane/navigate'
 
 // Hoisted mocks: vi.mock factories cannot reference top-level bindings, so we
 // declare the spy fns inside vi.hoisted() and reuse them from the mock factories
@@ -8,15 +9,16 @@ const {
   downloadsWatcherStatusMock,
   addToastMock,
   openPrivacySettingsMock,
-  navigateToPathMock,
+  navigateMock,
   moveCursorMock,
   getFocusedPaneMock,
 } = vi.hoisted(() => ({
   goToLatestDownloadMock: vi.fn(),
   downloadsWatcherStatusMock: vi.fn(),
   addToastMock: vi.fn(() => 'toast-id'),
   openPrivacySettingsMock: vi.fn(() => Promise.resolve()),
-  navigateToPathMock: vi.fn(() => Promise.resolve()),
+  // `navigate()` returns a `NavigateResult`; default to a started no-op.
+  navigateMock: vi.fn((): NavigateResult => ({ status: 'started', settled: Promise.resolve() })),
   moveCursorMock: vi.fn(() => Promise.resolve()),
   getFocusedPaneMock: vi.fn(() => 'left'),
 }))
@@ -61,7 +63,7 @@ function makeExplorerStub(): ExplorerAPI {
   // into the helper's call sites.
   return {
     getFocusedPane: getFocusedPaneMock,
-    navigateToPath: navigateToPathMock,
+    navigate: navigateMock,
     moveCursor: moveCursorMock,
   } as unknown as ExplorerAPI
 }
@@ -72,7 +74,7 @@ describe('goToLatestDownload', () => {
     downloadsWatcherStatusMock.mockReset()
     addToastMock.mockReset().mockReturnValue('toast-id')
     openPrivacySettingsMock.mockReset().mockResolvedValue(undefined)
-    navigateToPathMock.mockReset().mockResolvedValue(undefined)
+    navigateMock.mockReset().mockReturnValue({ status: 'started', settled: Promise.resolve() })
     moveCursorMock.mockReset().mockResolvedValue(undefined)
     getFocusedPaneMock.mockReset().mockReturnValue('left')
   })
@@ -90,7 +92,7 @@ describe('goToLatestDownload', () => {
 
     await goToLatestDownload(makeExplorerStub())
 
-    expect(navigateToPathMock).toHaveBeenCalledWith('right', '/Users/me/Downloads')
+    expect(navigateMock).toHaveBeenCalledWith({ pane: 'right', to: { path: '/Users/me/Downloads' }, source: 'user' })
     expect(moveCursorMock).toHaveBeenCalledWith('right', 'report.pdf')
     expect(addToastMock).not.toHaveBeenCalled()
   })
@@ -122,7 +124,7 @@ describe('goToLatestDownload', () => {
     expect(typeof options.props?.onGoToDownloads).toBe('function')
     // Invoking the prop triggers the snapshotted navigation.
     options.props?.onGoToDownloads()
-    expect(navigateToPathMock).toHaveBeenCalledWith('left', '/Users/me/Downloads')
+    expect(navigateMock).toHaveBeenCalledWith({ pane: 'left', to: { path: '/Users/me/Downloads' }, source: 'user' })
     expect(moveCursorMock).not.toHaveBeenCalled()
   })
 
@@ -188,42 +190,41 @@ describe('goToLatestDownload', () => {
 
     expect(goToLatestDownloadMock).not.toHaveBeenCalled()
     expect(addToastMock).not.toHaveBeenCalled()
-    expect(navigateToPathMock).not.toHaveBeenCalled()
+    expect(navigateMock).not.toHaveBeenCalled()
   })
 })
 
 describe('goToDownload', () => {
   beforeEach(() => {
     addToastMock.mockReset().mockReturnValue('toast-id')
-    navigateToPathMock.mockReset().mockResolvedValue(undefined)
+    navigateMock.mockReset().mockReturnValue({ status: 'started', settled: Promise.resolve() })
     moveCursorMock.mockReset().mockResolvedValue(undefined)
     getFocusedPaneMock.mockReset().mockReturnValue('left')
   })
 
   it('navigates the focused pane to parentDir and selects the file', async () => {
     await goToDownload(makeExplorerStub(), '/Users/me/Downloads', 'report.pdf')
 
-    expect(navigateToPathMock).toHaveBeenCalledWith('left', '/Users/me/Downloads')
+    expect(navigateMock).toHaveBeenCalledWith({ pane: 'left', to: { path: '/Users/me/Downloads' }, source: 'user' })
     expect(moveCursorMock).toHaveBeenCalledWith('left', 'report.pdf')
   })
 
   it('does nothing when the explorer handle is missing (HMR / pre-mount)', async () => {
     await goToDownload(undefined, '/Users/me/Downloads', 'report.pdf')
 
-    expect(navigateToPathMock).not.toHaveBeenCalled()
+    expect(navigateMock).not.toHaveBeenCalled()
     expect(moveCursorMock).not.toHaveBeenCalled()
   })
 
-  it('bails out without moving the cursor when navigateToPath refuses synchronously', async () => {
-    // `navigateToPath` returns `string | Promise<void>`; the mock factory's
-    // inferred type pins it to `Promise<void>`, so cast for this one return path.
-    ;(navigateToPathMock as unknown as { mockReturnValueOnce: (v: unknown) => void }).mockReturnValueOnce(
-      'snapshot pane on a missing volume',
-    )
+  it('bails out without moving the cursor when navigate refuses synchronously', async () => {
+    navigateMock.mockReturnValueOnce({
+      status: 'refused',
+      reason: { kind: 'no-volume-resolved', message: 'snapshot pane on a missing volume' },
+    })
 
     await goToDownload(makeExplorerStub(), '/Users/me/Downloads', 'report.pdf')
 
-    expect(navigateToPathMock).toHaveBeenCalledWith('left', '/Users/me/Downloads')
+    expect(navigateMock).toHaveBeenCalledWith({ pane: 'left', to: { path: '/Users/me/Downloads' }, source: 'user' })
     expect(moveCursorMock).not.toHaveBeenCalled()
   })
 })

apps/desktop/src/lib/downloads/go-to-latest.ts

@@ -100,9 +100,9 @@ async function showEmptyToast(explorer: ExplorerAPI): Promise<void> {
       log.warn('Go to Downloads pressed but Downloads dir is unresolved; no action')
       return
     }
-    const result = explorer.navigateToPath(focusedPane, downloadsDir)
-    if (typeof result === 'string') {
-      log.warn('Go to Downloads: navigateToPath refused: {reason}', { reason: result })
+    const result = explorer.navigate({ pane: focusedPane, to: { path: downloadsDir }, source: 'user' })
+    if (result.status === 'refused') {
+      log.warn('Go to Downloads: navigate refused: {reason}', { reason: result.reason.message })
     }
   }
   addToast(LatestDownloadEmptyToastContent, {

apps/desktop/src/lib/file-explorer/navigation/navigate-and-select.test.ts

@@ -1,24 +1,35 @@
 import { describe, it, expect, vi, beforeEach } from 'vitest'
 import { navigateToDirInPane, navigateToFileInPane } from './navigate-and-select'
 import type { ExplorerAPI } from '../../../routes/(main)/explorer-api'
+import type { NavigateResult } from '../pane/navigate'
 
-function makeExplorer(navResult: string | Promise<void>) {
-  const navigateToPath = vi.fn(() => navResult)
+/** A `started` result whose `settled` is the given promise (defaults to resolved). */
+function started(settled: Promise<void> = Promise.resolve()): NavigateResult {
+  return { status: 'started', settled }
+}
+
+/** A `refused` result carrying the given exact message. */
+function refused(message: string): NavigateResult {
+  return { status: 'refused', reason: { kind: 'no-volume-resolved', message } }
+}
+
+function makeExplorer(navResult: NavigateResult) {
+  const navigate = vi.fn(() => navResult)
   const moveCursor = vi.fn(() => Promise.resolve())
-  const explorer = { navigateToPath, moveCursor } as unknown as ExplorerAPI
-  return { explorer, navigateToPath, moveCursor }
+  const explorer = { navigate, moveCursor } as unknown as ExplorerAPI
+  return { explorer, navigate, moveCursor }
 }
 
 describe('navigateToDirInPane', () => {
   it('navigates to the dir and never moves the cursor', async () => {
-    const { explorer, navigateToPath, moveCursor } = makeExplorer(Promise.resolve())
+    const { explorer, navigate, moveCursor } = makeExplorer(started())
     await navigateToDirInPane(explorer, 'left', '/tmp/here')
-    expect(navigateToPath).toHaveBeenCalledWith('left', '/tmp/here')
+    expect(navigate).toHaveBeenCalledWith({ pane: 'left', to: { path: '/tmp/here' }, source: 'user' })
     expect(moveCursor).not.toHaveBeenCalled()
   })
 
-  it('bails on the sync-error string without throwing', async () => {
-    const { explorer, moveCursor } = makeExplorer('snapshot pane on a missing volume')
+  it('bails on a refusal without throwing', async () => {
+    const { explorer, moveCursor } = makeExplorer(refused('snapshot pane on a missing volume'))
     await expect(navigateToDirInPane(explorer, 'right', '/tmp')).resolves.toBeUndefined()
     expect(moveCursor).not.toHaveBeenCalled()
   })
@@ -32,34 +43,34 @@ describe('navigateToFileInPane', () => {
   })
 
   it('navigates to the parent, then moves the cursor onto the file', async () => {
-    const { explorer, navigateToPath, moveCursor } = makeExplorer(Promise.resolve())
+    const { explorer, navigate, moveCursor } = makeExplorer(started())
     await navigateToFileInPane(explorer, 'left', '/tmp', 'a.txt')
-    expect(navigateToPath).toHaveBeenCalledWith('left', '/tmp')
+    expect(navigate).toHaveBeenCalledWith({ pane: 'left', to: { path: '/tmp' }, source: 'user' })
     expect(moveCursor).toHaveBeenCalledWith('left', 'a.txt')
   })
 
-  it('awaits the listing before moving the cursor', async () => {
+  it('awaits the navigation settle before moving the cursor', async () => {
     let resolveListing!: () => void
     const listing = new Promise<void>((resolve) => {
       resolveListing = resolve
     })
-    const navigateToPath = vi.fn(() => listing)
+    const navigate = vi.fn(() => started(listing))
     const moveCursor = vi.fn(() => {
       moveCursorCalls.push(['called'])
       return Promise.resolve()
     })
-    const explorer = { navigateToPath, moveCursor } as unknown as ExplorerAPI
+    const explorer = { navigate, moveCursor } as unknown as ExplorerAPI
 
     const promise = navigateToFileInPane(explorer, 'left', '/tmp', 'a.txt')
-    // Cursor must NOT move before the listing settles.
+    // Cursor must NOT move before the navigation settles.
     expect(moveCursorCalls).toHaveLength(0)
     resolveListing()
     await promise
     expect(moveCursorCalls).toHaveLength(1)
   })
 
-  it('bails on the sync-error string and never moves the cursor', async () => {
-    const { explorer, moveCursor } = makeExplorer('cannot start')
+  it('bails on a refusal and never moves the cursor', async () => {
+    const { explorer, moveCursor } = makeExplorer(refused('cannot start'))
     await navigateToFileInPane(explorer, 'left', '/tmp', 'a.txt')
     expect(moveCursor).not.toHaveBeenCalled()
   })

apps/desktop/src/lib/file-explorer/navigation/navigate-and-select.ts

@@ -2,14 +2,19 @@
  * Shared navigation primitives for the "jump somewhere in the focused pane"
  * features: "Go to latest download" (⌘J) and "Go to path" (⌘G). Both want to
  * point a pane at a directory and (for files) land the cursor on a specific
- * entry, with the same careful handling of `navigateToPath`'s
- * `string | Promise<void>` return.
+ * entry, with the same careful handling of `navigate()`'s `NavigateResult`.
  *
- * `navigateToPath` returns a sync error string when navigation can't even
- * start (a snapshot pane on a missing volume, etc.); otherwise it returns a
- * Promise that settles when the listing completes. We await the Promise but
- * report-and-bail on the sync-error string — without the listing settled,
- * `moveCursor` would race against an empty cache.
+ * `navigate()` returns `{ status: 'refused', reason }` when navigation can't
+ * even start (a snapshot pane on a missing volume, the network/MTP refusals);
+ * otherwise `{ status: 'started', settled }` where `settled` resolves when the
+ * navigation settles. We await `settled` but report-and-bail on a refusal —
+ * without the listing settled, `moveCursor` would race against an empty cache.
+ *
+ * NOTE (L2-adjacent): for the cross-volume snapshot arm, `settled` resolves
+ * BEFORE the new listing loads (it resolves when the volume-switch commit is
+ * done). `navigateToFileInPane` relies on `moveCursor`'s own internal
+ * `whenLoadSettles` to bridge that gap — `settled` is the navigation-started
+ * gate, `whenLoadSettles` is the real listing gate. Don't try to collapse them.
  */
 
 import { getAppLogger } from '$lib/logging/logger'
@@ -24,16 +29,16 @@ type Pane = 'left' | 'right'
  * navigation lands the cursor on the 0th row (`..`).
  */
 export async function navigateToDirInPane(explorer: ExplorerAPI, pane: Pane, dir: string): Promise<void> {
-  const navResult = explorer.navigateToPath(pane, dir)
-  if (typeof navResult === 'string') {
-    log.warn('navigateToDirInPane: navigateToPath refused {pane} {dir}: {reason}', {
+  const result = explorer.navigate({ pane, to: { path: dir }, source: 'user' })
+  if (result.status === 'refused') {
+    log.warn('navigateToDirInPane: navigate refused {pane} {dir}: {reason}', {
       pane,
       dir,
-      reason: navResult,
+      reason: result.reason.message,
     })
     return
   }
-  await navResult
+  await result.settled
 }
 
 /**
@@ -46,15 +51,15 @@ export async function navigateToFileInPane(
   parentDir: string,
   fileName: string,
 ): Promise<void> {
-  const navResult = explorer.navigateToPath(pane, parentDir)
-  if (typeof navResult === 'string') {
-    log.warn('navigateToFileInPane: navigateToPath refused {pane} {parentDir}: {reason}', {
+  const result = explorer.navigate({ pane, to: { path: parentDir }, source: 'user' })
+  if (result.status === 'refused') {
+    log.warn('navigateToFileInPane: navigate refused {pane} {parentDir}: {reason}', {
       pane,
       parentDir,
-      reason: navResult,
+      reason: result.reason.message,
     })
     return
   }
-  await navResult
+  await result.settled
   await explorer.moveCursor(pane, fileName)
 }

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

@@ -58,6 +58,7 @@ list).
 | `transfer-operations.ts`      | Build `TransferDialogPropsData` (and snapshot variant) from a focused pane           |
 | `sorting-handlers.ts`         | `getNewSortOrder` (column click cycle), `toFrontendIndices` (`..` offset)            |
 | `index-events.ts`             | Throttled `index-dir-updated` handler with `/private/` symlink resolution            |
+| `navigate.ts`                 | `navigate(intent, deps)` transaction: the single coordinator-level pane-nav entry    |
 | `snapshot-pane-navigation.ts` | `isCrossVolumeNavigation` — snapshot-volume → real-path triggers volume switch       |
 | `has-parent.ts`               | `computeHasParent({ isSearchResultsView, currentPath, effectiveVolumeRoot })`        |
 | `search-results-keys.ts`      | Pure key→action dispatch for the flat snapshot pane                                  |
@@ -95,11 +96,12 @@ poisons the pane with `volumeId === 'search-results'` + real path.
 (`clipboard-operations`, `file-operation-commands`, `pane-commands`) that take a `PaneAccess` (live-reference read API)
 plus the dialog state. The component keeps one-line `export function` delegates so the `ExplorerAPI` surface is
 unchanged. Read-only / delegating bodies move; functions that WRITE component navigation state (`switchPane`,
-`swapPanes`, `toggleHiddenFiles`, `setViewMode`, `navigate`, `setSort*`, `navigateToPath`, `moveCursor`,
-`selectVolumeBy*`, `copyPathBetweenPanes`, the `mirror*`/`restoreFocus` helpers) stay in the component — un-trapping
-that state is the explorer-store phase, not this factoring. `moveCursorByName*` and `validateMtpNavigation` moved even
-though they're called from component-resident writers (`moveCursor`, `restoreCursorByFilename`, `navigateToPath`); those
-callers reach back via `paneCommands.*`.
+`swapPanes`, `toggleHiddenFiles`, `setViewMode`, `navigate`, `setSort*`, `moveCursor`, `selectVolumeBy*`,
+`copyPathBetweenPanes`, the `mirror*`/`restoreFocus` helpers) stay in the component — un-trapping that state is the
+explorer-store phase, not this factoring. The `navigate(intent)` transaction itself lives in `navigate.ts` (the
+component builds its `NavigateDeps` and wraps it as the `navigate` export). `moveCursorByName*` and
+`validateMtpNavigation` moved even though they're called from component-resident writers (`moveCursor`,
+`restoreCursorByFilename`); those callers reach back via `paneCommands.*`.
 
 **Explorer store (`explorer-state.svelte.ts`).** Module store owning the dual-pane navigation + UI-chrome state that
 `DualPaneExplorer` used to trap in component closures: `focusedPane`, `showHiddenFiles`, `leftPaneWidthPercent`, and the
@@ -196,10 +198,10 @@ other. See parent § "Live disk space".
 `PaneState.typeToJump` whenever the buffer or indicator is live, so MCP-driven E2E can assert without DOM poking. See
 `src-tauri/src/mcp/CLAUDE.md` § State stores.
 
-**Don't add `cd`-style heuristics in `applyPathChange`.** Stale `onPathChange` from a slow listing is dropped by the
-volume guard in `DualPaneExplorer.applyPathChange` (`smb://` prefix for `network`, `search-results://` prefix for
-snapshots, `isPathOnVolume` for everything else). Adding a new virtual-volume namespace? Extend the explicit prefix
-branch. See parent § "Gotchas".
+**Don't add `cd`-style heuristics in `commitPathFromListing`.** Stale `onPathChange` from a slow listing is dropped by
+the drop-foreign-listings policy in `navigate.ts::commitPathFromListing` (`smb://` prefix for `network`,
+`search-results://` prefix for snapshots, `isPathOnVolume` for everything else). Adding a new virtual-volume namespace?
+Extend the explicit prefix branch. See parent § "Gotchas".
 
 ## Gotchas