@stigmer/react 3.1.1 → 3.1.3

package/internal/store/index.js

@@ -1,10 +1,14 @@
 "use client";
 import { createContext, useContext, useRef, useSyncExternalStore } from "react";
 import { ConversationStore } from "./conversation-store.js";
+import { WorkspaceFileSelectionStore, } from "./workspace-file-selection-store.js";
+import { WorkspaceEditorsStore, } from "./workspace-editors-store.js";
 export { ConversationStore } from "./conversation-store.js";
 export { structuralShare } from "./structural-share.js";
 export { WorkflowExecutionEventStore, } from "./workflow-execution-event-store.js";
 export { SelectionStore } from "./selection-store.js";
+export { WorkspaceFileSelectionStore } from "./workspace-file-selection-store.js";
+export { WorkspaceEditorsStore, editorKey, virtualEntryId, isVirtualEntryId, } from "./workspace-editors-store.js";
 // ---------------------------------------------------------------------------
 // Context
 // ---------------------------------------------------------------------------
@@ -53,4 +57,59 @@ export function useStoreExecution(store) {
 export function useStoreStreamState(store) {
     return useSyncExternalStore(store.subscribe, store.getStreamState);
 }
+// ---------------------------------------------------------------------------
+// Workspace file selection — the DD-07 shared "which file is open" store
+// ---------------------------------------------------------------------------
+/**
+ * Internal context carrying the {@link WorkspaceFileSelectionStore} instance
+ * (stable ref) to both columns of the session viewer. Not exported from the
+ * public SDK barrel — consumed only within SDK components and `SessionViewer`.
+ */
+export const WorkspaceFileSelectionContext = createContext(null);
+/**
+ * Access the workspace-file selection store from context.
+ * Throws if called outside a `WorkspaceFileSelectionContext.Provider`.
+ */
+export function useWorkspaceFileSelectionStore() {
+    const store = useContext(WorkspaceFileSelectionContext);
+    if (!store) {
+        throw new Error("useWorkspaceFileSelectionStore must be used within a WorkspaceFileSelectionContext.Provider");
+    }
+    return store;
+}
+/**
+ * Create or reuse a `WorkspaceFileSelectionStore` instance, preserved across
+ * re-renders via ref. `SessionViewer` calls this and provides the result
+ * through {@link WorkspaceFileSelectionContext} (DD-07).
+ */
+export function useWorkspaceFileSelectionStoreRef() {
+    const ref = useRef(null);
+    if (!ref.current) {
+        ref.current = new WorkspaceFileSelectionStore();
+    }
+    return ref.current;
+}
+/** Subscribe to the currently-selected workspace file. */
+export function useWorkspaceFileSelection(store) {
+    return useSyncExternalStore(store.subscribe, store.getSelection);
+}
+// ---------------------------------------------------------------------------
+// Workspace editors — the surface's open-editor group (Slice B)
+// ---------------------------------------------------------------------------
+/**
+ * Create or reuse a `WorkspaceEditorsStore` instance, preserved across
+ * re-renders via ref. Owned by `SessionViewer` alongside the selection store;
+ * the surface subscribes to it for its tab group.
+ */
+export function useWorkspaceEditorsStoreRef() {
+    const ref = useRef(null);
+    if (!ref.current) {
+        ref.current = new WorkspaceEditorsStore();
+    }
+    return ref.current;
+}
+/** Subscribe to the open-editor group snapshot. */
+export function useWorkspaceEditors(store) {
+    return useSyncExternalStore(store.subscribe, store.getSnapshot);
+}
 //# sourceMappingURL=index.js.map

package/internal/store/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/internal/store/index.ts"],"names":[],"mappings":"AAAA,YAAY,CAAC;AAEb,OAAO,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,EAAE,oBAAoB,EAAE,MAAM,OAAO,CAAC;AAEhF,OAAO,EAAE,iBAAiB,EAAoB,MAAM,yBAAyB,CAAC;AAE9E,OAAO,EAAE,iBAAiB,EAAoB,MAAM,yBAAyB,CAAC;AAC9E,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AACxD,OAAO,EACL,2BAA2B,GAI5B,MAAM,qCAAqC,CAAC;AAE7C,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAGtD,8EAA8E;AAC9E,UAAU;AACV,8EAA8E;AAE9E;;;GAGG;AACH,MAAM,CAAC,MAAM,wBAAwB,GACnC,aAAa,CAA2B,IAAI,CAAC,CAAC;AAEhD,8EAA8E;AAC9E,QAAQ;AACR,8EAA8E;AAE9E;;;GAGG;AACH,MAAM,UAAU,oBAAoB;IAClC,MAAM,KAAK,GAAG,UAAU,CAAC,wBAAwB,CAAC,CAAC;IACnD,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,MAAM,IAAI,KAAK,CACb,8EAA8E,CAC/E,CAAC;IACJ,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,uBAAuB;IACrC,MAAM,GAAG,GAAG,MAAM,CAA2B,IAAI,CAAC,CAAC;IACnD,IAAI,CAAC,GAAG,CAAC,OAAO,EAAE,CAAC;QACjB,GAAG,CAAC,OAAO,GAAG,IAAI,iBAAiB,EAAE,CAAC;IACxC,CAAC;IACD,OAAO,GAAG,CAAC,OAAO,CAAC;AACrB,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,iBAAiB,CAC/B,KAAwB;IAExB,OAAO,oBAAoB,CAAC,KAAK,CAAC,SAAS,EAAE,KAAK,CAAC,YAAY,CAAC,CAAC;AACnE,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,mBAAmB,CAAC,KAAwB;IAC1D,OAAO,oBAAoB,CAAC,KAAK,CAAC,SAAS,EAAE,KAAK,CAAC,cAAc,CAAC,CAAC;AACrE,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/internal/store/index.ts"],"names":[],"mappings":"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"}

package/internal/store/workspace-editors-store.d.ts

@@ -0,0 +1,145 @@
+import type { RevealTarget } from "../useRevealLine.js";
+import type { SelectedWorkspaceFile } from "./workspace-file-selection-store.js";
+/**
+ * Options for opening a file in the surface (via `openPreview` / the surface's
+ * `onOpenFile` seam). `line` requests a jump-to-line reveal: the file opens in
+ * a line-faithful view scrolled to and highlighting that 1-based line. Absent,
+ * the file opens normally (top of file / diff-default). Deliberately an options
+ * object so future open-intents (e.g. a column) extend it without churning the
+ * callback signature.
+ */
+export interface OpenFileOptions {
+    /** 1-based line to reveal after opening. */
+    readonly line?: number;
+}
+/**
+ * A pending reveal request scoped to a specific editor. Extends the viewer-side
+ * {@link RevealTarget} with the `key` of the editor it targets, so a consumer
+ * applies the reveal only while that editor is the active one. Transient
+ * navigation, never editor identity (the line does not key the tab).
+ */
+export interface EditorReveal extends RevealTarget {
+    /** {@link editorKey} of the editor this reveal targets. */
+    readonly key: string;
+}
+/**
+ * One open editor tab.
+ *
+ * `preview` marks the single reusable "preview" tab (shown in italics): a
+ * single click opens or replaces it in place, so casual browsing never
+ * accumulates tabs. Pinning it (double-click, or opening the file explicitly)
+ * clears the flag and the tab becomes persistent. At most one editor is a
+ * preview at any time.
+ */
+export interface OpenEditor {
+    /** Stable-within-page id of the owning workspace entry. */
+    readonly entryId: string;
+    /** Repo-relative (git) or root-relative (local) file path. */
+    readonly path: string;
+    /** Whether this is the reusable preview tab (italic, single per group). */
+    readonly preview: boolean;
+}
+/** Immutable snapshot for the `useSyncExternalStore` contract. */
+export interface WorkspaceEditorsSnapshot {
+    /** Open editors in tab order. */
+    readonly editors: readonly OpenEditor[];
+    /** Key of the active editor, or `null` when the group is empty. */
+    readonly activeKey: string | null;
+    /**
+     * The active editor as a {@link SelectedWorkspaceFile} (stable ref between
+     * mutations), or `null`. This is what the viewer, diff correlation, and tree
+     * highlight consume — the editors store's projection into the selection shape.
+     */
+    readonly activeFile: SelectedWorkspaceFile | null;
+    /**
+     * A pending jump-to-line reveal, or `null`. Set only by an open-with-line
+     * (`openPreview` with a `line`); cleared by any other active-editor change so
+     * returning to a tab never re-scrolls to a stale line. Consumers honor it only
+     * while `reveal.key` matches {@link activeKey}. Transient — not part of any
+     * editor's identity.
+     */
+    readonly reveal: EditorReveal | null;
+}
+type Listener = () => void;
+/**
+ * Stable key for an editor. Uses NUL as the separator — legal in neither an
+ * entry id nor a file path — so `entryId`/`path` can never collide.
+ */
+export declare function editorKey(entryId: string, path: string): string;
+/**
+ * Entry id for a virtual document — an editor tab whose content is not a
+ * workspace file (e.g. the session's `plan.md`, an execution artifact).
+ * Virtual documents share the editor group with file tabs (same open / pin /
+ * close / activate semantics); only their *content rendering* differs, via the
+ * surface's `virtualDocuments` seam. `kind` names the document family
+ * (`"plan"` today) so future virtual documents get distinct identities.
+ */
+export declare function virtualEntryId(kind: string): string;
+/**
+ * True when an entry id names a virtual document rather than a workspace
+ * entry. Used by file-only consumers (diff correlation, tree highlight,
+ * reveal) to skip work that can only apply to real files.
+ */
+export declare function isVirtualEntryId(entryId: string): boolean;
+/**
+ * Framework-agnostic store for the surface's open-editor group.
+ *
+ * Implements the `useSyncExternalStore` contract like the sibling selection and
+ * conversation stores: the context/ref carries the instance, and `getSnapshot`
+ * returns a snapshot object that is replaced only inside a mutation — so it is a
+ * stable reference between mutations and never triggers a render loop.
+ *
+ * VS Code preview-tab semantics:
+ * - {@link openPreview} — single click: reuse the one preview slot (or focus an
+ *   already-open editor); casual browsing stays at one tab.
+ * - {@link openPinned} / {@link pin} — double-click or explicit open: the tab
+ *   becomes persistent.
+ * - {@link close} — remove a tab, activating a neighbor.
+ * - {@link activate} — focus an already-open tab.
+ */
+export declare class WorkspaceEditorsStore {
+    private _snapshot;
+    private _listeners;
+    /** Monotonic reveal token — bumped on every open-with-line (see `openPreview`). */
+    private _revealSeq;
+    /**
+     * Single-click open: reuse the preview slot, or focus if already open.
+     *
+     * When `options.line` is set, this also records a jump-to-line reveal for the
+     * opened editor. The reveal nonce is bumped **every** time — even when the
+     * file is already open and active — so a second search hit in the same file
+     * re-scrolls the already-mounted viewer. An open without a `line` clears any
+     * pending reveal.
+     */
+    openPreview(entryId: string, path: string, options?: OpenFileOptions): void;
+    /** Explicit open (double-click / open-to-keep): a persistent tab. */
+    openPinned(entryId: string, path: string): void;
+    /** Pin an open editor (clear its preview flag), keeping it active. */
+    pin(entryId: string, path: string): void;
+    /** Focus an already-open editor. No-op if it is not open. */
+    activate(entryId: string, path: string): void;
+    /**
+     * Close an editor. When the closed tab was active, the neighbor to its right
+     * (or, failing that, its left) becomes active — matching editor conventions.
+     */
+    close(entryId: string, path: string): void;
+    /** Close every editor. */
+    closeAll(): void;
+    subscribe: (listener: Listener) => (() => void);
+    /** Returns the current snapshot (stable ref between mutations). */
+    getSnapshot: () => WorkspaceEditorsSnapshot;
+    private _setActive;
+    /** Build a reveal for `key` from open options, or `null` when no line given. */
+    private _makeReveal;
+    /**
+     * Replace the snapshot. `reveal` defaults to `null`, so any mutation that does
+     * not explicitly carry one clears a pending reveal (invariant: returning to a
+     * tab must not re-scroll to a stale line). The `activeFile` object reference
+     * is preserved when the active editor is unchanged, so a reveal-only update
+     * doesn't churn downstream memoization (diff correlation, tree highlight).
+     */
+    private _commit;
+    private _notify;
+}
+export {};
+//# sourceMappingURL=workspace-editors-store.d.ts.map

package/internal/store/workspace-editors-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"workspace-editors-store.d.ts","sourceRoot":"","sources":["../../../src/internal/store/workspace-editors-store.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACxD,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,qCAAqC,CAAC;AAEjF;;;;;;;GAOG;AACH,MAAM,WAAW,eAAe;IAC9B,4CAA4C;IAC5C,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;CACxB;AAED;;;;;GAKG;AACH,MAAM,WAAW,YAAa,SAAQ,YAAY;IAChD,2DAA2D;IAC3D,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;CACtB;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,UAAU;IACzB,2DAA2D;IAC3D,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,8DAA8D;IAC9D,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,2EAA2E;IAC3E,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;CAC3B;AAED,kEAAkE;AAClE,MAAM,WAAW,wBAAwB;IACvC,iCAAiC;IACjC,QAAQ,CAAC,OAAO,EAAE,SAAS,UAAU,EAAE,CAAC;IACxC,mEAAmE;IACnE,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IAClC;;;;OAIG;IACH,QAAQ,CAAC,UAAU,EAAE,qBAAqB,GAAG,IAAI,CAAC;IAClD;;;;;;OAMG;IACH,QAAQ,CAAC,MAAM,EAAE,YAAY,GAAG,IAAI,CAAC;CACtC;AAED,KAAK,QAAQ,GAAG,MAAM,IAAI,CAAC;AAS3B;;;GAGG;AACH,wBAAgB,SAAS,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAE/D;AASD;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAEnD;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAEzD;AAED;;;;;;;;;;;;;;;GAeG;AACH,qBAAa,qBAAqB;IAChC,OAAO,CAAC,SAAS,CAA4C;IAC7D,OAAO,CAAC,UAAU,CAAuB;IACzC,mFAAmF;IACnF,OAAO,CAAC,UAAU,CAAK;IAIvB;;;;;;;;OAQG;IACH,WAAW,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,eAAe,GAAG,IAAI;IAsB3E,qEAAqE;IACrE,UAAU,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI;IAoB/C,sEAAsE;IACtE,GAAG,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI;IAWxC,6DAA6D;IAC7D,QAAQ,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI;IAQ7C;;;OAGG;IACH,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI;IAkB1C,0BAA0B;IAC1B,QAAQ,IAAI,IAAI;IAQhB,SAAS,GAAI,UAAU,QAAQ,KAAG,CAAC,MAAM,IAAI,CAAC,CAK5C;IAEF,mEAAmE;IACnE,WAAW,QAAO,wBAAwB,CAAmB;IAI7D,OAAO,CAAC,UAAU;IAKlB,gFAAgF;IAChF,OAAO,CAAC,WAAW;IASnB;;;;;;OAMG;IACH,OAAO,CAAC,OAAO;IA4Bf,OAAO,CAAC,OAAO;CAKhB"}

package/internal/store/workspace-editors-store.js

@@ -0,0 +1,208 @@
+// The set of workspace files open in the surface's editor group, plus which is
+// active — the VS Code "open editors" model. Sibling to
+// WorkspaceFileSelectionStore (which stays the single-file selection used by the
+// launcher's Viewer tab); this store owns the multi-tab surface. Its active
+// editor derives the same SelectedWorkspaceFile shape, so downstream diff
+// correlation and tree highlight consume one selection regardless of source.
+const EMPTY_SNAPSHOT = {
+    editors: [],
+    activeKey: null,
+    activeFile: null,
+    reveal: null,
+};
+/**
+ * Stable key for an editor. Uses NUL as the separator — legal in neither an
+ * entry id nor a file path — so `entryId`/`path` can never collide.
+ */
+export function editorKey(entryId, path) {
+    return `${entryId}\u0000${path}`;
+}
+/**
+ * NUL-prefixed namespace for virtual-document entry ids — the same
+ * collision-proofing trick as {@link editorKey}: no real workspace entry id
+ * can contain NUL, so a virtual document can never alias a workspace file.
+ */
+const VIRTUAL_ENTRY_PREFIX = "\u0000virtual:";
+/**
+ * Entry id for a virtual document — an editor tab whose content is not a
+ * workspace file (e.g. the session's `plan.md`, an execution artifact).
+ * Virtual documents share the editor group with file tabs (same open / pin /
+ * close / activate semantics); only their *content rendering* differs, via the
+ * surface's `virtualDocuments` seam. `kind` names the document family
+ * (`"plan"` today) so future virtual documents get distinct identities.
+ */
+export function virtualEntryId(kind) {
+    return `${VIRTUAL_ENTRY_PREFIX}${kind}`;
+}
+/**
+ * True when an entry id names a virtual document rather than a workspace
+ * entry. Used by file-only consumers (diff correlation, tree highlight,
+ * reveal) to skip work that can only apply to real files.
+ */
+export function isVirtualEntryId(entryId) {
+    return entryId.startsWith(VIRTUAL_ENTRY_PREFIX);
+}
+/**
+ * Framework-agnostic store for the surface's open-editor group.
+ *
+ * Implements the `useSyncExternalStore` contract like the sibling selection and
+ * conversation stores: the context/ref carries the instance, and `getSnapshot`
+ * returns a snapshot object that is replaced only inside a mutation — so it is a
+ * stable reference between mutations and never triggers a render loop.
+ *
+ * VS Code preview-tab semantics:
+ * - {@link openPreview} — single click: reuse the one preview slot (or focus an
+ *   already-open editor); casual browsing stays at one tab.
+ * - {@link openPinned} / {@link pin} — double-click or explicit open: the tab
+ *   becomes persistent.
+ * - {@link close} — remove a tab, activating a neighbor.
+ * - {@link activate} — focus an already-open tab.
+ */
+export class WorkspaceEditorsStore {
+    _snapshot = EMPTY_SNAPSHOT;
+    _listeners = new Set();
+    /** Monotonic reveal token — bumped on every open-with-line (see `openPreview`). */
+    _revealSeq = 0;
+    // -- Mutations -----------------------------------------------------------
+    /**
+     * Single-click open: reuse the preview slot, or focus if already open.
+     *
+     * When `options.line` is set, this also records a jump-to-line reveal for the
+     * opened editor. The reveal nonce is bumped **every** time — even when the
+     * file is already open and active — so a second search hit in the same file
+     * re-scrolls the already-mounted viewer. An open without a `line` clears any
+     * pending reveal.
+     */
+    openPreview(entryId, path, options) {
+        const key = editorKey(entryId, path);
+        const { editors } = this._snapshot;
+        const reveal = this._makeReveal(key, options);
+        if (editors.some((e) => editorKey(e.entryId, e.path) === key)) {
+            // Already open — focus it (preserving pinned/preview state) and apply the
+            // reveal (or clear it). Reuse the same editors array ref so a reveal-only
+            // update doesn't churn the tab list.
+            this._commit(editors, key, reveal);
+            return;
+        }
+        const next = { entryId, path, preview: true };
+        const previewIndex = editors.findIndex((e) => e.preview);
+        const editorsNext = previewIndex >= 0
+            ? editors.map((e, i) => (i === previewIndex ? next : e))
+            : [...editors, next];
+        this._commit(editorsNext, key, reveal);
+    }
+    /** Explicit open (double-click / open-to-keep): a persistent tab. */
+    openPinned(entryId, path) {
+        const key = editorKey(entryId, path);
+        const { editors } = this._snapshot;
+        const index = editors.findIndex((e) => editorKey(e.entryId, e.path) === key);
+        if (index >= 0) {
+            if (editors[index].preview) {
+                this._commit(editors.map((e, i) => (i === index ? { ...e, preview: false } : e)), key);
+            }
+            else {
+                this._setActive(key);
+            }
+            return;
+        }
+        this._commit([...editors, { entryId, path, preview: false }], key);
+    }
+    /** Pin an open editor (clear its preview flag), keeping it active. */
+    pin(entryId, path) {
+        const key = editorKey(entryId, path);
+        const { editors } = this._snapshot;
+        const index = editors.findIndex((e) => editorKey(e.entryId, e.path) === key);
+        if (index < 0 || !editors[index].preview)
+            return;
+        this._commit(editors.map((e, i) => (i === index ? { ...e, preview: false } : e)), key);
+    }
+    /** Focus an already-open editor. No-op if it is not open. */
+    activate(entryId, path) {
+        const key = editorKey(entryId, path);
+        if (!this._snapshot.editors.some((e) => editorKey(e.entryId, e.path) === key)) {
+            return;
+        }
+        this._setActive(key);
+    }
+    /**
+     * Close an editor. When the closed tab was active, the neighbor to its right
+     * (or, failing that, its left) becomes active — matching editor conventions.
+     */
+    close(entryId, path) {
+        const key = editorKey(entryId, path);
+        const { editors, activeKey } = this._snapshot;
+        const index = editors.findIndex((e) => editorKey(e.entryId, e.path) === key);
+        if (index < 0)
+            return;
+        const editorsNext = editors.filter((_, i) => i !== index);
+        let nextActiveKey = activeKey;
+        if (activeKey === key) {
+            const neighbor = editorsNext[index] ?? editorsNext[index - 1] ?? null;
+            nextActiveKey = neighbor
+                ? editorKey(neighbor.entryId, neighbor.path)
+                : null;
+        }
+        this._commit(editorsNext, nextActiveKey);
+    }
+    /** Close every editor. */
+    closeAll() {
+        if (this._snapshot.editors.length === 0)
+            return;
+        this._snapshot = EMPTY_SNAPSHOT;
+        this._notify();
+    }
+    // -- useSyncExternalStore contract ---------------------------------------
+    subscribe = (listener) => {
+        this._listeners.add(listener);
+        return () => {
+            this._listeners.delete(listener);
+        };
+    };
+    /** Returns the current snapshot (stable ref between mutations). */
+    getSnapshot = () => this._snapshot;
+    // -- Internal ------------------------------------------------------------
+    _setActive(key) {
+        if (this._snapshot.activeKey === key)
+            return;
+        this._commit(this._snapshot.editors, key);
+    }
+    /** Build a reveal for `key` from open options, or `null` when no line given. */
+    _makeReveal(key, options) {
+        const line = options?.line;
+        if (line == null)
+            return null;
+        return { key, line, nonce: ++this._revealSeq };
+    }
+    /**
+     * Replace the snapshot. `reveal` defaults to `null`, so any mutation that does
+     * not explicitly carry one clears a pending reveal (invariant: returning to a
+     * tab must not re-scroll to a stale line). The `activeFile` object reference
+     * is preserved when the active editor is unchanged, so a reveal-only update
+     * doesn't churn downstream memoization (diff correlation, tree highlight).
+     */
+    _commit(editors, activeKey, reveal = null) {
+        const active = activeKey != null
+            ? editors.find((e) => editorKey(e.entryId, e.path) === activeKey) ?? null
+            : null;
+        const resolvedActiveKey = active ? activeKey : null;
+        const prev = this._snapshot;
+        const activeFile = active && prev.activeKey === resolvedActiveKey && prev.activeFile
+            ? prev.activeFile
+            : active
+                ? { entryId: active.entryId, path: active.path }
+                : null;
+        this._snapshot = {
+            editors,
+            activeKey: resolvedActiveKey,
+            activeFile,
+            reveal,
+        };
+        this._notify();
+    }
+    _notify() {
+        for (const listener of this._listeners) {
+            listener();
+        }
+    }
+}
+//# sourceMappingURL=workspace-editors-store.js.map

package/internal/store/workspace-editors-store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"workspace-editors-store.js","sourceRoot":"","sources":["../../../src/internal/store/workspace-editors-store.ts"],"names":[],"mappings":"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"}

package/internal/store/workspace-file-selection-store.d.ts

@@ -0,0 +1,38 @@
+/**
+ * A file selected for viewing.
+ *
+ * Keyed by `entryId` (not the entry value): the workspace entry id is stable
+ * within a page load but regenerated on reload, and selection is transient UI
+ * state anyway (reset on reload). Consumers must resolve the live entry via
+ * `workspace.entries.find(e => e.id === sel.entryId)` so a removed entry
+ * deselects naturally instead of holding a stale value.
+ */
+export interface SelectedWorkspaceFile {
+    /** Stable-within-page id of the owning workspace entry. */
+    readonly entryId: string;
+    /** Repo-relative (git) or root-relative (local) file path. */
+    readonly path: string;
+}
+type Listener = () => void;
+/**
+ * Framework-agnostic store for the currently-open workspace file.
+ *
+ * Implements the `useSyncExternalStore` contract identical to
+ * {@link import("./selection-store.js").SelectionStore}: the context carries the
+ * store instance (stable ref), and `getSelection` returns the stored object
+ * reference — a new object is allocated only inside `select` — so `getSnapshot`
+ * never triggers a re-render loop.
+ */
+export declare class WorkspaceFileSelectionStore {
+    private _selected;
+    private _listeners;
+    select(file: SelectedWorkspaceFile): void;
+    deselect(): void;
+    toggle(file: SelectedWorkspaceFile): void;
+    subscribe: (listener: Listener) => (() => void);
+    /** Returns the current selection (stable ref between mutations). */
+    getSelection: () => SelectedWorkspaceFile | null;
+    private _notify;
+}
+export {};
+//# sourceMappingURL=workspace-file-selection-store.d.ts.map

package/internal/store/workspace-file-selection-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"workspace-file-selection-store.d.ts","sourceRoot":"","sources":["../../../src/internal/store/workspace-file-selection-store.ts"],"names":[],"mappings":"AAIA;;;;;;;;GAQG;AACH,MAAM,WAAW,qBAAqB;IACpC,2DAA2D;IAC3D,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,8DAA8D;IAC9D,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED,KAAK,QAAQ,GAAG,MAAM,IAAI,CAAC;AAE3B;;;;;;;;GAQG;AACH,qBAAa,2BAA2B;IACtC,OAAO,CAAC,SAAS,CAAsC;IACvD,OAAO,CAAC,UAAU,CAAuB;IAIzC,MAAM,CAAC,IAAI,EAAE,qBAAqB,GAAG,IAAI;IAMzC,QAAQ,IAAI,IAAI;IAMhB,MAAM,CAAC,IAAI,EAAE,qBAAqB,GAAG,IAAI;IAUzC,SAAS,GAAI,UAAU,QAAQ,KAAG,CAAC,MAAM,IAAI,CAAC,CAK5C;IAEF,oEAAoE;IACpE,YAAY,QAAO,qBAAqB,GAAG,IAAI,CAE7C;IAIF,OAAO,CAAC,OAAO;CAKhB"}

package/internal/store/workspace-file-selection-store.js

@@ -0,0 +1,62 @@
+// Which workspace file is open in the viewer. Sibling to SelectionStore (which
+// owns thread-item inspect selection) — the two are orthogonal domains with
+// different lifecycles, so they stay separate stores rather than one fused FSM.
+/**
+ * Framework-agnostic store for the currently-open workspace file.
+ *
+ * Implements the `useSyncExternalStore` contract identical to
+ * {@link import("./selection-store.js").SelectionStore}: the context carries the
+ * store instance (stable ref), and `getSelection` returns the stored object
+ * reference — a new object is allocated only inside `select` — so `getSnapshot`
+ * never triggers a re-render loop.
+ */
+export class WorkspaceFileSelectionStore {
+    _selected = null;
+    _listeners = new Set();
+    // -- Mutations -----------------------------------------------------------
+    select(file) {
+        if (selectedEqual(this._selected, file))
+            return;
+        this._selected = file;
+        this._notify();
+    }
+    deselect() {
+        if (this._selected === null)
+            return;
+        this._selected = null;
+        this._notify();
+    }
+    toggle(file) {
+        if (selectedEqual(this._selected, file)) {
+            this.deselect();
+        }
+        else {
+            this.select(file);
+        }
+    }
+    // -- useSyncExternalStore contract ---------------------------------------
+    subscribe = (listener) => {
+        this._listeners.add(listener);
+        return () => {
+            this._listeners.delete(listener);
+        };
+    };
+    /** Returns the current selection (stable ref between mutations). */
+    getSelection = () => {
+        return this._selected;
+    };
+    // -- Internal ------------------------------------------------------------
+    _notify() {
+        for (const listener of this._listeners) {
+            listener();
+        }
+    }
+}
+function selectedEqual(a, b) {
+    if (a === b)
+        return true;
+    if (a === null || b === null)
+        return false;
+    return a.entryId === b.entryId && a.path === b.path;
+}
+//# sourceMappingURL=workspace-file-selection-store.js.map

package/internal/store/workspace-file-selection-store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"workspace-file-selection-store.js","sourceRoot":"","sources":["../../../src/internal/store/workspace-file-selection-store.ts"],"names":[],"mappings":"AAAA,+EAA+E;AAC/E,4EAA4E;AAC5E,gFAAgF;AAoBhF;;;;;;;;GAQG;AACH,MAAM,OAAO,2BAA2B;IAC9B,SAAS,GAAiC,IAAI,CAAC;IAC/C,UAAU,GAAG,IAAI,GAAG,EAAY,CAAC;IAEzC,2EAA2E;IAE3E,MAAM,CAAC,IAA2B;QAChC,IAAI,aAAa,CAAC,IAAI,CAAC,SAAS,EAAE,IAAI,CAAC;YAAE,OAAO;QAChD,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC;QACtB,IAAI,CAAC,OAAO,EAAE,CAAC;IACjB,CAAC;IAED,QAAQ;QACN,IAAI,IAAI,CAAC,SAAS,KAAK,IAAI;YAAE,OAAO;QACpC,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC;QACtB,IAAI,CAAC,OAAO,EAAE,CAAC;IACjB,CAAC;IAED,MAAM,CAAC,IAA2B;QAChC,IAAI,aAAa,CAAC,IAAI,CAAC,SAAS,EAAE,IAAI,CAAC,EAAE,CAAC;YACxC,IAAI,CAAC,QAAQ,EAAE,CAAC;QAClB,CAAC;aAAM,CAAC;YACN,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;QACpB,CAAC;IACH,CAAC;IAED,2EAA2E;IAE3E,SAAS,GAAG,CAAC,QAAkB,EAAgB,EAAE;QAC/C,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;QAC9B,OAAO,GAAG,EAAE;YACV,IAAI,CAAC,UAAU,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;QACnC,CAAC,CAAC;IACJ,CAAC,CAAC;IAEF,oEAAoE;IACpE,YAAY,GAAG,GAAiC,EAAE;QAChD,OAAO,IAAI,CAAC,SAAS,CAAC;IACxB,CAAC,CAAC;IAEF,2EAA2E;IAEnE,OAAO;QACb,KAAK,MAAM,QAAQ,IAAI,IAAI,CAAC,UAAU,EAAE,CAAC;YACvC,QAAQ,EAAE,CAAC;QACb,CAAC;IACH,CAAC;CACF;AAED,SAAS,aAAa,CACpB,CAA+B,EAC/B,CAA+B;IAE/B,IAAI,CAAC,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IACzB,IAAI,CAAC,KAAK,IAAI,IAAI,CAAC,KAAK,IAAI;QAAE,OAAO,KAAK,CAAC;IAC3C,OAAO,CAAC,CAAC,OAAO,KAAK,CAAC,CAAC,OAAO,IAAI,CAAC,CAAC,IAAI,KAAK,CAAC,CAAC,IAAI,CAAC;AACtD,CAAC"}

package/internal/useRevealLine.d.ts

@@ -0,0 +1,49 @@
+import { type RefObject } from "react";
+/**
+ * A transient request to scroll a line-faithful code view to a specific line
+ * and emphasize it — the "reveal" seam behind jump-to-line navigation (e.g. a
+ * content-search hit opening its file at the matched line).
+ *
+ * `line` is 1-based, matching the gutter and the grep's line numbers. `nonce`
+ * is a monotonic token bumped by the producer on every navigation — including a
+ * repeat navigation to the same `line` — so an already-mounted view re-scrolls
+ * even when the target line is unchanged. The line is deliberately NOT part of
+ * an editor's identity (see `WorkspaceEditorsStore`): it is navigation, not
+ * state, so it must not key a remount.
+ */
+export interface RevealTarget {
+    /** 1-based line to scroll to and highlight. */
+    readonly line: number;
+    /** Monotonic token; a change re-triggers the scroll (even for the same line). */
+    readonly nonce: number;
+}
+/** Return value of {@link useRevealLine}. */
+export interface UseRevealLineResult<T extends HTMLElement = HTMLElement> {
+    /**
+     * Attach to the element that wraps the addressable line rows. The hook scopes
+     * its `[data-line]` query to this subtree, so multiple viewers never collide.
+     */
+    readonly containerRef: RefObject<T | null>;
+    /** Whether a given 1-based line is the current reveal target (for the highlight). */
+    readonly isRevealed: (line: number) => boolean;
+}
+/**
+ * Scrolls a line-faithful code view to `reveal.line` and reports which line to
+ * highlight.
+ *
+ * The mechanics are centralized here (rather than duplicated into each line
+ * renderer) and mirror the established `data-attribute` scroll pattern used by
+ * the workflow waterfall: the consumer renders each row with `data-line="N"`
+ * and this hook, on every `reveal.nonce` change, finds the target row within
+ * `containerRef` and scrolls it into view. Smooth scroll yields to
+ * `prefers-reduced-motion` (a JS animation the CSS rule does not cover), and
+ * the scroll is an optional call so it is a no-op under jsdom, which has no
+ * `scrollIntoView`.
+ *
+ * Placement matters: mount this inside the line renderer, which exists only
+ * after the file content has loaded — never above the async content gate — so
+ * the `[data-line]` rows are present when the effect runs and a fresh open does
+ * not race the load. A missing or out-of-range line is a silent no-op.
+ */
+export declare function useRevealLine<T extends HTMLElement = HTMLElement>(reveal: RevealTarget | undefined): UseRevealLineResult<T>;
+//# sourceMappingURL=useRevealLine.d.ts.map

package/internal/useRevealLine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useRevealLine.d.ts","sourceRoot":"","sources":["../../src/internal/useRevealLine.ts"],"names":[],"mappings":"AAEA,OAAO,EAAkC,KAAK,SAAS,EAAE,MAAM,OAAO,CAAC;AAGvE;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,YAAY;IAC3B,+CAA+C;IAC/C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,iFAAiF;IACjF,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAED,6CAA6C;AAC7C,MAAM,WAAW,mBAAmB,CAAC,CAAC,SAAS,WAAW,GAAG,WAAW;IACtE;;;OAGG;IACH,QAAQ,CAAC,YAAY,EAAE,SAAS,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC;IAC3C,qFAAqF;IACrF,QAAQ,CAAC,UAAU,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC;CAChD;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,aAAa,CAAC,CAAC,SAAS,WAAW,GAAG,WAAW,EAC/D,MAAM,EAAE,YAAY,GAAG,SAAS,GAC/B,mBAAmB,CAAC,CAAC,CAAC,CAyBxB"}