File explorer: Add explorer-state module store

vdavid · vdavid · commit 062ebbb72ca9 · 2026-06-05T00:20:34.000+02:00
- New `explorer-state.svelte.ts`: a module store owning the dual-pane navigation + UI-chrome state that `DualPaneExplorer` traps in component closures today — `focusedPane`, `showHiddenFiles`, `leftPaneWidthPercent`, and the two tab-manager holders.
- State is module-private: `createExplorerState()` closes over `$state` locals and exposes only getters plus one named mutator per field (`setFocusedPane`, `setShowHiddenFiles`/`toggleHiddenFiles`, `setLeftPaneWidthPercent`, `getTabMgr`/`setTabMgr`). No writable surface leaks.
- `getTabMgr(pane)` returns the live `$state&lt;TabManager&gt;` holder, never a copy/snapshot, so a `$derived` reading through it keeps tracking when the holder is swapped or the held manager mutates — the reactivity-transparency contract the `PaneAccess` getters rely on.
- Factory-first for testability plus a module-level `explorerState` singleton (what the component will bind) and a `_resetForTesting()` reset, following the `snapshot-store` precedent.
- TDD tests in `explorer-state.svelte.test.ts`: defaults, getter/mutator round-trips, factory isolation, `_resetForTesting`, and the live-reference reactivity contract via `$effect.root` + `flushSync`.
- The tab managers stay values the store holds, not store fields: they keep their existing setter-based API, mutated via the `tab-state-manager` / `tab-operations` free functions. The store holds the holder reference and swaps it via `setTabMgr`. Documented the store, its writers list, and the scope boundary in `pane/CLAUDE.md`.
- Not yet wired into the component (consumed in the next milestone).
diff --git a/apps/desktop/src/lib/file-explorer/pane/CLAUDE.md b/apps/desktop/src/lib/file-explorer/pane/CLAUDE.md
@@ -32,6 +32,7 @@ list).
 
 | File                             | Purpose                                                                                 |
 | -------------------------------- | --------------------------------------------------------------------------------------- |
+| `explorer-state.svelte.ts`       | Explorer store: `focusedPane`, `showHiddenFiles`, layout split, the two tab-mgr holders |
 | `dialog-state.svelte.ts`         | Dialog props + handlers (transfer, delete, mkdir, alert, error); factory                |
 | `selection-state.svelte.ts`      | `SvelteSet<number>` of indices + range anchor/end + `applyIndices` helpers              |
 | `rename-flow.svelte.ts`          | Rename validation, conflict + extension dialogs, save / cancel                          |
@@ -98,6 +99,35 @@ that state is the explorer-store phase, not this factoring. `moveCursorByName*`
 though they're called from component-resident writers (`moveCursor`, `restoreCursorByFilename`, `navigateToPath`); 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
+two tab-manager holders. State is module-private (A1): `createExplorerState()` closes over `$state` locals and exposes
+only getters + one named mutator per field. There's no exported writable surface — callers can't assign a field, only
+call a mutator (A2; the `cmdr/no-explorer-state-writes` lint rule makes this a hard wall once it lands in M5).
+`createExplorerState()` is factory-first for testability; the module-level `explorerState` singleton is what the
+component binds, with `_resetForTesting()` for tests that touch it.
+
+The **writers** (A2 — exactly one mutator per field, all inside the store module):
+
+| Field                  | Mutator(s)                                |
+| ---------------------- | ----------------------------------------- |
+| `focusedPane`          | `setFocusedPane`                          |
+| `showHiddenFiles`      | `setShowHiddenFiles`, `toggleHiddenFiles` |
+| `leftPaneWidthPercent` | `setLeftPaneWidthPercent`                 |
+| `leftTabMgr`           | `setTabMgr('left', …)`                    |
+| `rightTabMgr`          | `setTabMgr('right', …)`                   |
+
+**A1/A2-vs-tab-manager scope boundary.** The private-state + one-mutator rules govern the store's **own** fields only.
+The tab managers are _values the store holds_, not store fields: they keep their existing setter-based API
+(`createTabManager`) and are mutated via the free functions in `tabs/tab-state-manager.svelte` / `tab-operations`. The
+store holds the holder reference and swaps it via `setTabMgr`; it never wraps tab-manager setters behind store intents.
+
+**Live-reference getters.** `getTabMgr(pane)` returns the live `$state<TabManager>` holder, never a copy or a
+`$state.snapshot` — a `$derived` reading `getActiveTab(getTabMgr(p))` keeps tracking both when the holder is swapped and
+when the held manager mutates in place. Returning a snapshot would silently sever reactivity at the seam (the same rule
+`pane-access.ts` documents). What the store does NOT own: `cursorIndex`, selection, and listing UI state stay local to
+`FilePane` (perf invariant P3).
+
 **Cross-pane drag.** `DualPaneExplorer.getFileAndPathUnderCursor()` prefers `FilePane.getPathUnderCursor()` over
 `${currentPath}/${filename}` so snapshot-pane drags carry real filesystem paths, not `search-results://sr-N/<name>`.
 
diff --git a/apps/desktop/src/lib/file-explorer/pane/explorer-state.svelte.test.ts b/apps/desktop/src/lib/file-explorer/pane/explorer-state.svelte.test.ts
@@ -0,0 +1,183 @@
+/**
+ * Tests for the explorer store (`explorer-state.svelte.ts`).
+ *
+ * The store un-traps `DualPaneExplorer`'s navigation + UI-chrome state into one
+ * module: `focusedPane`, `showHiddenFiles`, `leftPaneWidthPercent`, and the two
+ * tab-manager holders. State is module-private; only getters and named mutators
+ * cross the boundary (A1/A2).
+ *
+ * Coverage:
+ * - factory isolation (two instances never share state),
+ * - getter/mutator round-trips for every field,
+ * - `_resetForTesting` clears the default instance to defaults,
+ * - `getTabMgr` returns the LIVE `$state` holder reference, so a `$derived`
+ *   reading through it keeps tracking after `setTabMgr` swaps the holder (the
+ *   reactivity-transparency contract the Phase-0 `PaneAccess` getters rely on).
+ *
+ * This is a `.svelte.test.ts` so the test body itself gets rune compilation —
+ * the live-reference assertion needs a real `$derived` + `$effect.root`.
+ */
+
+import { describe, it, expect, beforeEach } from 'vitest'
+import { flushSync } from 'svelte'
+import { createExplorerState, explorerState, _resetForTesting } from './explorer-state.svelte'
+import { createTabManager, getActiveTab, type TabManager } from '../tabs/tab-state-manager.svelte'
+import { createInitialTabState } from './tab-operations'
+
+/** A throwaway tab manager rooted at `path` on the default volume. */
+function mgrAt(path: string): TabManager {
+  return createTabManager(createInitialTabState(path, 'root'))
+}
+
+describe('createExplorerState: defaults', () => {
+  it('starts left-focused, hidden files shown, panes split 50/50', () => {
+    const s = createExplorerState()
+    expect(s.getFocusedPane()).toBe('left')
+    expect(s.getShowHiddenFiles()).toBe(true)
+    expect(s.getLeftPaneWidthPercent()).toBe(50)
+  })
+
+  it('starts with a tab manager per pane, each at the home folder', () => {
+    const s = createExplorerState()
+    expect(getActiveTab(s.getTabMgr('left')).path).toBe('~')
+    expect(getActiveTab(s.getTabMgr('right')).path).toBe('~')
+    expect(s.getTabMgr('left')).not.toBe(s.getTabMgr('right'))
+  })
+})
+
+describe('createExplorerState: getter/mutator round-trips', () => {
+  it('setFocusedPane stores the focused pane', () => {
+    const s = createExplorerState()
+    s.setFocusedPane('right')
+    expect(s.getFocusedPane()).toBe('right')
+    s.setFocusedPane('left')
+    expect(s.getFocusedPane()).toBe('left')
+  })
+
+  it('setShowHiddenFiles stores the flag', () => {
+    const s = createExplorerState()
+    s.setShowHiddenFiles(false)
+    expect(s.getShowHiddenFiles()).toBe(false)
+    s.setShowHiddenFiles(true)
+    expect(s.getShowHiddenFiles()).toBe(true)
+  })
+
+  it('toggleHiddenFiles flips the flag', () => {
+    const s = createExplorerState()
+    expect(s.getShowHiddenFiles()).toBe(true)
+    s.toggleHiddenFiles()
+    expect(s.getShowHiddenFiles()).toBe(false)
+    s.toggleHiddenFiles()
+    expect(s.getShowHiddenFiles()).toBe(true)
+  })
+
+  it('setLeftPaneWidthPercent stores the layout split', () => {
+    const s = createExplorerState()
+    s.setLeftPaneWidthPercent(33)
+    expect(s.getLeftPaneWidthPercent()).toBe(33)
+  })
+
+  it('setTabMgr swaps the holder for the given pane only', () => {
+    // `$state<TabManager>` wraps the held object in a reactive proxy, so the
+    // contract is behavioral (the active tab read through the holder), not
+    // proxy identity — `getTabMgr` returns a live reference, which a `===`
+    // check against the pre-proxy object would wrongly reject.
+    const s = createExplorerState()
+    s.setTabMgr('left', mgrAt('/left'))
+    s.setTabMgr('right', mgrAt('/right'))
+    expect(getActiveTab(s.getTabMgr('left')).path).toBe('/left')
+    expect(getActiveTab(s.getTabMgr('right')).path).toBe('/right')
+  })
+})
+
+describe('createExplorerState: factory isolation', () => {
+  it('two instances do not share scalar state', () => {
+    const a = createExplorerState()
+    const b = createExplorerState()
+    a.setFocusedPane('right')
+    a.setShowHiddenFiles(false)
+    a.setLeftPaneWidthPercent(20)
+    expect(b.getFocusedPane()).toBe('left')
+    expect(b.getShowHiddenFiles()).toBe(true)
+    expect(b.getLeftPaneWidthPercent()).toBe(50)
+  })
+
+  it('two instances do not share tab-manager holders', () => {
+    const a = createExplorerState()
+    const b = createExplorerState()
+    a.setTabMgr('left', mgrAt('/a-left'))
+    expect(getActiveTab(a.getTabMgr('left')).path).toBe('/a-left')
+    expect(getActiveTab(b.getTabMgr('left')).path).toBe('~')
+  })
+})
+
+describe('explorerState default instance: _resetForTesting', () => {
+  beforeEach(() => {
+    _resetForTesting()
+  })
+
+  it('clears every field back to defaults', () => {
+    explorerState.setFocusedPane('right')
+    explorerState.setShowHiddenFiles(false)
+    explorerState.setLeftPaneWidthPercent(70)
+    explorerState.setTabMgr('left', mgrAt('/scratch'))
+
+    _resetForTesting()
+
+    expect(explorerState.getFocusedPane()).toBe('left')
+    expect(explorerState.getShowHiddenFiles()).toBe(true)
+    expect(explorerState.getLeftPaneWidthPercent()).toBe(50)
+    expect(getActiveTab(explorerState.getTabMgr('left')).path).toBe('~')
+    expect(getActiveTab(explorerState.getTabMgr('right')).path).toBe('~')
+  })
+})
+
+describe('getTabMgr live-reference reactivity', () => {
+  beforeEach(() => {
+    _resetForTesting()
+  })
+
+  it('a $derived reading through getTabMgr re-runs after setTabMgr swaps the holder', () => {
+    const s = createExplorerState()
+
+    let observed = ''
+    const dispose = $effect.root(() => {
+      // The derived reads the holder through the getter, exactly like the
+      // 12 per-pane component deriveds will after M2. If the getter returned a
+      // copy/snapshot, this would stop tracking once the holder is swapped.
+      const activePath = $derived(getActiveTab(s.getTabMgr('left')).path)
+      $effect(() => {
+        observed = activePath
+      })
+    })
+    flushSync()
+    expect(observed).toBe('~')
+
+    s.setTabMgr('left', mgrAt('/swapped'))
+    flushSync()
+    expect(observed).toBe('/swapped')
+
+    dispose()
+  })
+
+  it('a $derived re-runs when the held tab manager mutates in place', () => {
+    const s = createExplorerState()
+
+    let observed: number | undefined
+    const dispose = $effect.root(() => {
+      const tabCount = $derived(s.getTabMgr('left').tabs.length)
+      $effect(() => {
+        observed = tabCount
+      })
+    })
+    flushSync()
+    expect(observed).toBe(1)
+
+    // Mutating the live holder's reactive `tabs` array must reach the derived.
+    s.getTabMgr('left').tabs = [...s.getTabMgr('left').tabs, createInitialTabState('/extra', 'root')]
+    flushSync()
+    expect(observed).toBe(2)
+
+    dispose()
+  })
+})
diff --git a/apps/desktop/src/lib/file-explorer/pane/explorer-state.svelte.ts b/apps/desktop/src/lib/file-explorer/pane/explorer-state.svelte.ts
@@ -0,0 +1,148 @@
+/**
+ * Explorer store: the dual-pane explorer's navigation + UI-chrome state, lifted
+ * out of `DualPaneExplorer`'s component closures into one module so consumers
+ * read state directly instead of through `explorerRef` getters.
+ *
+ * Owns four of the component's fields:
+ * - `focusedPane` — which pane has focus (`'left' | 'right'`),
+ * - `showHiddenFiles` — the dotfile-visibility toggle,
+ * - `leftPaneWidthPercent` — the layout split (the right pane is the remainder),
+ * - the two **tab-manager holders** `leftTabMgr` / `rightTabMgr`, each a
+ *   `$state<TabManager>` reference.
+ *
+ * ## What this store does NOT own
+ *
+ * The tab managers are _values the store holds_, not store fields. They keep
+ * their existing setter-based API (`createTabManager`) and are mutated through
+ * the free functions in `tabs/tab-state-manager.svelte` / `tab-operations`. The
+ * store only holds the *holder reference* and swaps it via `setTabMgr`; the
+ * A1/A2 private-state + one-mutator rules govern the store's own fields, never
+ * the tab-manager internals. `cursorIndex`, selection, and listing UI state stay
+ * local to `FilePane` (perf invariant P3) — they're not here.
+ *
+ * ## Shape (A1/A2)
+ *
+ * State is module-private: `createExplorerState()` closes over `$state` locals
+ * and exposes only getters and one named mutator per field. There is no exported
+ * writable surface — callers can't assign a field, only call a mutator. The
+ * `cmdr/no-explorer-state-writes` lint rule (added in M5) makes that a hard wall;
+ * until then it's convention.
+ *
+ * ## Live references (reactivity transparency)
+ *
+ * `getTabMgr(pane)` returns the **live** `$state<TabManager>` holder, never a
+ * copy or a `$state.snapshot`. A `$derived` reading `getActiveTab(getTabMgr(p))`
+ * keeps tracking both when the holder is swapped (`setTabMgr`) and when the held
+ * manager mutates in place. This is the Phase-0 `PaneAccess` contract: the
+ * factories never see reactivity sever at the seam when state moves from the
+ * component into this store. Verified by `explorer-state.svelte.test.ts`.
+ *
+ * ## Factory + default instance
+ *
+ * `createExplorerState()` is factory-first for testability (vitest instantiates
+ * fresh instances that never share state). The module-level `explorerState`
+ * singleton is what the component binds. `_resetForTesting()` resets the
+ * singleton to defaults for tests that exercise it; `SvelteSet`/`SvelteMap`
+ * (none here yet) would reset via `.clear()`, never reassignment.
+ *
+ * Writers are enumerated in this module's colocated `pane/CLAUDE.md` (A2).
+ */
+
+import { DEFAULT_VOLUME_ID } from '$lib/tauri-commands'
+import { createTabManager, type TabManager } from '../tabs/tab-state-manager.svelte'
+import { createInitialTabState } from './tab-operations'
+
+/** Default left/right split: an even 50/50 layout. */
+const DEFAULT_PANE_WIDTH_PERCENT = 50
+
+/** Builds the per-pane starting tab manager: a single tab at the home folder. */
+function createDefaultTabMgr(): TabManager {
+  return createTabManager(createInitialTabState('~', DEFAULT_VOLUME_ID))
+}
+
+/**
+ * The explorer store's public surface: getters + one named mutator per field,
+ * plus the live-reference tab-manager holder accessors. No writable state leaks.
+ */
+export interface ExplorerState {
+  /** Returns the focused pane. Reactive. */
+  getFocusedPane: () => 'left' | 'right'
+  /** Sets the focused pane. The single writer of `focusedPane`. */
+  setFocusedPane: (pane: 'left' | 'right') => void
+
+  /** Returns whether hidden (dot) files are shown. Reactive. */
+  getShowHiddenFiles: () => boolean
+  /** Sets the hidden-files flag to an explicit value. */
+  setShowHiddenFiles: (value: boolean) => void
+  /** Flips the hidden-files flag. */
+  toggleHiddenFiles: () => void
+
+  /** Returns the left pane's width as a percentage; the right pane is the remainder. Reactive. */
+  getLeftPaneWidthPercent: () => number
+  /** Sets the left pane's width percentage. */
+  setLeftPaneWidthPercent: (percent: number) => void
+
+  /** Returns the LIVE tab-manager holder for `pane` (never a copy/snapshot). Reactive. */
+  getTabMgr: (pane: 'left' | 'right') => TabManager
+  /** Swaps the tab-manager holder for `pane` (e.g. when loading persisted tabs). */
+  setTabMgr: (pane: 'left' | 'right', mgr: TabManager) => void
+}
+
+/**
+ * Creates a fresh explorer-state instance. Tests use this for full isolation;
+ * the app binds the module-level `explorerState` singleton instead.
+ */
+export function createExplorerState(): ExplorerState {
+  let focusedPane = $state<'left' | 'right'>('left')
+  let showHiddenFiles = $state(true)
+  let leftPaneWidthPercent = $state(DEFAULT_PANE_WIDTH_PERCENT)
+  let leftTabMgr = $state<TabManager>(createDefaultTabMgr())
+  let rightTabMgr = $state<TabManager>(createDefaultTabMgr())
+
+  return {
+    getFocusedPane: () => focusedPane,
+    setFocusedPane: (pane) => {
+      focusedPane = pane
+    },
+
+    getShowHiddenFiles: () => showHiddenFiles,
+    setShowHiddenFiles: (value) => {
+      showHiddenFiles = value
+    },
+    toggleHiddenFiles: () => {
+      showHiddenFiles = !showHiddenFiles
+    },
+
+    getLeftPaneWidthPercent: () => leftPaneWidthPercent,
+    setLeftPaneWidthPercent: (percent) => {
+      leftPaneWidthPercent = percent
+    },
+
+    getTabMgr: (pane) => (pane === 'left' ? leftTabMgr : rightTabMgr),
+    setTabMgr: (pane, mgr) => {
+      if (pane === 'left') {
+        leftTabMgr = mgr
+      } else {
+        rightTabMgr = mgr
+      }
+    },
+  }
+}
+
+/** The app-wide explorer store. The component binds this; tests reset it via `_resetForTesting`. */
+export const explorerState = createExplorerState()
+
+/**
+ * Test-only reset of the `explorerState` singleton back to defaults: left-focused,
+ * hidden files shown, an even split, and a fresh home-folder tab manager per pane.
+ * Tests that touch the singleton call this in `beforeEach`. Not for production use;
+ * tests import it via the file path. Keep it in sync with the factory's defaults
+ * whenever a new field is added.
+ */
+export function _resetForTesting(): void {
+  explorerState.setFocusedPane('left')
+  explorerState.setShowHiddenFiles(true)
+  explorerState.setLeftPaneWidthPercent(DEFAULT_PANE_WIDTH_PERCENT)
+  explorerState.setTabMgr('left', createDefaultTabMgr())
+  explorerState.setTabMgr('right', createDefaultTabMgr())
+}
