@stigmer/react 3.1.1 → 3.1.3

package/src/internal/markdown-components.tsx

@@ -43,6 +43,14 @@ export function stripFrontmatter(content: string): string {
 const ENCLOSING_MARKDOWN_FENCE_RE =
   /^(`{3,})[ \t]*(?:markdown|md)[ \t]*\r?\n([\s\S]*?)\r?\n\1[ \t]*$/i;
 
+/**
+ * Matches content whose ENTIRE body is a single fenced code block with an
+ * EMPTY info string (no language tag). Only meaningful for surfaces that know
+ * the body is markdown by contract (a Plan-mode plan) — see
+ * {@link unwrapEnclosingMarkdownFence}'s `allowBareFence`.
+ */
+const ENCLOSING_BARE_FENCE_RE = /^(`{3,})[ \t]*\r?\n([\s\S]*?)\r?\n\1[ \t]*$/;
+
 /**
  * Unwraps a message the model wrapped entirely in a ```markdown / ```md fence.
  *
@@ -53,6 +61,14 @@ const ENCLOSING_MARKDOWN_FENCE_RE =
  * no-op for everything else (already-rich markdown, prose, or a reply that is
  * legitimately a single code block).
  *
+ * `allowBareFence` extends the unwrap to a whole-body fence with NO language
+ * tag. For an ordinary chat message a bare fence is ambiguous (it may be a
+ * legitimate single code block), so the default stays strict. A Plan-mode plan
+ * is different by contract: the turn's output IS a markdown document, so a
+ * reply that is one giant untagged fence is a wrapped plan, not code. Only
+ * plan-document surfaces pass `true`. A fence tagged with any other language
+ * (```python …) is never unwrapped in either mode.
+ *
  * Render-time only: callers pass it the text right before handing it to the
  * markdown renderer, so the transcript and the raw artifact stay faithful to
  * what the agent produced — a single source of truth for the unwrap, with no
@@ -60,9 +76,47 @@ const ENCLOSING_MARKDOWN_FENCE_RE =
  * arrived yet, so this no-ops and the live text renders as typed; it unwraps
  * once the block closes.
  */
-export function unwrapEnclosingMarkdownFence(content: string): string {
-  const match = ENCLOSING_MARKDOWN_FENCE_RE.exec(content.trim());
-  return match ? match[2] : content;
+export function unwrapEnclosingMarkdownFence(
+  content: string,
+  allowBareFence = false,
+): string {
+  const trimmed = content.trim();
+  const tagged = ENCLOSING_MARKDOWN_FENCE_RE.exec(trimmed);
+  if (tagged) return tagged[2];
+  if (allowBareFence) {
+    const bare = ENCLOSING_BARE_FENCE_RE.exec(trimmed);
+    if (bare) return bare[2];
+  }
+  return content;
+}
+
+/**
+ * Matches a document that OPENS with an `# H1` heading (optionally preceded by
+ * blank lines only). Group 1 is the heading text; the match spans through the
+ * heading's trailing newline(s) so `body` starts at the first content line.
+ */
+const LEADING_H1_RE = /^#[ \t]+(.+?)[ \t]*(?:\r?\n+|$)/;
+
+/**
+ * Splits a markdown document into its leading `# H1` title and the remaining
+ * body, for surfaces that render the title in their own chrome (the plan
+ * document header) instead of inside the prose flow.
+ *
+ * Only a heading at the very start of the document counts as the title — an
+ * `# H1` further down is document content and stays in the body. When there is
+ * no leading H1, `title` is `null` and `body` is the input unchanged.
+ *
+ * Render-time only, like {@link unwrapEnclosingMarkdownFence}: the stored
+ * message/artifact keeps its heading; only the presentation moves it.
+ */
+export function extractLeadingH1(markdown: string): {
+  readonly title: string | null;
+  readonly body: string;
+} {
+  const trimmed = markdown.trim();
+  const match = LEADING_H1_RE.exec(trimmed);
+  if (!match) return { title: null, body: markdown };
+  return { title: match[1], body: trimmed.slice(match[0].length) };
 }
 
 /**
@@ -77,7 +131,7 @@ export function unwrapEnclosingMarkdownFence(content: string): string {
 export const MARKDOWN_COMPONENTS: Components = {
   p({ children, ...props }: MdProps<"p">) {
     return (
-      <p className="text-sm text-foreground mb-3 last:mb-0 leading-relaxed" {...props}>
+      <p className="text-sm text-foreground mb-3 last:mb-0 leading-relaxed break-words" {...props}>
         {children}
       </p>
     );
@@ -87,7 +141,7 @@ export const MARKDOWN_COMPONENTS: Components = {
     return (
       <a
         href={href}
-        className="text-primary underline underline-offset-2 hover:text-primary-muted"
+        className="text-primary underline underline-offset-2 hover:text-primary-muted break-words"
         target="_blank"
         rel="noopener noreferrer"
         {...props}
@@ -99,7 +153,7 @@ export const MARKDOWN_COMPONENTS: Components = {
 
   h1({ children, ...props }: MdProps<"h1">) {
     return (
-      <h1 className="text-lg font-semibold text-foreground mt-5 mb-2 first:mt-0" {...props}>
+      <h1 className="text-lg font-semibold text-foreground mt-5 mb-2 first:mt-0 break-words" {...props}>
         {children}
       </h1>
     );
@@ -107,7 +161,7 @@ export const MARKDOWN_COMPONENTS: Components = {
 
   h2({ children, ...props }: MdProps<"h2">) {
     return (
-      <h2 className="text-base font-semibold text-foreground mt-5 mb-2 first:mt-0" {...props}>
+      <h2 className="text-base font-semibold text-foreground mt-5 mb-2 first:mt-0 break-words" {...props}>
         {children}
       </h2>
     );
@@ -115,7 +169,7 @@ export const MARKDOWN_COMPONENTS: Components = {
 
   h3({ children, ...props }: MdProps<"h3">) {
     return (
-      <h3 className="text-sm font-semibold text-foreground mt-4 mb-1.5 first:mt-0" {...props}>
+      <h3 className="text-sm font-semibold text-foreground mt-4 mb-1.5 first:mt-0 break-words" {...props}>
         {children}
       </h3>
     );
@@ -123,7 +177,7 @@ export const MARKDOWN_COMPONENTS: Components = {
 
   h4({ children, ...props }: MdProps<"h4">) {
     return (
-      <h4 className="text-sm font-medium text-foreground mt-3 mb-1 first:mt-0" {...props}>
+      <h4 className="text-sm font-medium text-foreground mt-3 mb-1 first:mt-0 break-words" {...props}>
         {children}
       </h4>
     );
@@ -147,7 +201,7 @@ export const MARKDOWN_COMPONENTS: Components = {
 
   li({ children, ...props }: MdProps<"li">) {
     return (
-      <li className="leading-relaxed" {...props}>
+      <li className="leading-relaxed break-words" {...props}>
         {children}
       </li>
     );
@@ -195,7 +249,7 @@ export const MARKDOWN_COMPONENTS: Components = {
 
     return (
       <code
-        className="font-mono text-xs bg-muted px-1 py-0.5 rounded text-foreground"
+        className="font-mono text-xs bg-muted px-1 py-0.5 rounded text-foreground break-words"
         {...props}
       >
         {children}
@@ -263,3 +317,54 @@ export const MARKDOWN_COMPONENTS: Components = {
     );
   },
 };
+
+/**
+ * Document-grade typography for a Plan-mode plan: one step up the heading
+ * scale from the chat-tuned {@link MARKDOWN_COMPONENTS}, wider section
+ * spacing, and a hairline under `##` section headings for scannability. The
+ * plan is a reviewable document, not a chat bubble — its headings must carry
+ * the structure at a glance.
+ *
+ * Everything except the headings is inherited from `MARKDOWN_COMPONENTS`, so
+ * body text, code, tables, and links render identically across chat and plan
+ * surfaces. Used by `PlanDocumentMessage` (thread) — the same treatment any
+ * plan-document surface should share.
+ */
+export const PLAN_DOCUMENT_MARKDOWN_COMPONENTS: Components = {
+  ...MARKDOWN_COMPONENTS,
+
+  h1({ children, ...props }: MdProps<"h1">) {
+    return (
+      <h1 className="text-lg font-semibold text-foreground mt-6 mb-3 first:mt-0 break-words" {...props}>
+        {children}
+      </h1>
+    );
+  },
+
+  h2({ children, ...props }: MdProps<"h2">) {
+    return (
+      <h2
+        className="text-base font-semibold text-foreground mt-6 mb-2.5 pb-1 border-b border-border-muted first:mt-0 break-words"
+        {...props}
+      >
+        {children}
+      </h2>
+    );
+  },
+
+  h3({ children, ...props }: MdProps<"h3">) {
+    return (
+      <h3 className="text-sm font-semibold text-foreground mt-5 mb-2 first:mt-0 break-words" {...props}>
+        {children}
+      </h3>
+    );
+  },
+
+  h4({ children, ...props }: MdProps<"h4">) {
+    return (
+      <h4 className="text-sm font-medium text-foreground mt-4 mb-1.5 first:mt-0 break-words" {...props}>
+        {children}
+      </h4>
+    );
+  },
+};

package/src/{workflow → internal}/motion-preference.ts

@@ -1,10 +1,13 @@
 /**
  * Utility for respecting the user's motion preference (prefers-reduced-motion)
- * in programmatic viewport animations (fitView, setCenter, etc.) that are NOT
- * covered by the CSS-level reduced-motion rule in styles.css.
+ * in programmatic viewport animations (fitView, setCenter, scrollIntoView, etc.)
+ * that are NOT covered by the CSS-level reduced-motion rule in styles.css.
  *
- * React Flow's JS-driven animations (duration parameter on fitView/setCenter)
- * bypass CSS media queries — they must be explicitly checked.
+ * JS-driven animations (React Flow's duration parameter on fitView/setCenter,
+ * smooth `scrollIntoView`) bypass CSS media queries — they must be explicitly
+ * checked. Lives in `internal/` because it is cross-cutting: the workflow graph
+ * and the workspace file viewer both depend on it, and `internal/` may not
+ * depend on a feature domain.
  */
 
 let cachedPreference: boolean | null = null;

package/src/internal/store/__tests__/workspace-editors-store.test.ts

@@ -0,0 +1,216 @@
+import { describe, it, expect, beforeEach } from "vitest";
+import { WorkspaceEditorsStore, editorKey } from "../workspace-editors-store";
+
+function paths(store: WorkspaceEditorsStore): string[] {
+  return store.getSnapshot().editors.map((e) => e.path);
+}
+
+let store: WorkspaceEditorsStore;
+beforeEach(() => {
+  store = new WorkspaceEditorsStore();
+});
+
+describe("WorkspaceEditorsStore", () => {
+  it("starts empty", () => {
+    const snap = store.getSnapshot();
+    expect(snap.editors).toEqual([]);
+    expect(snap.activeKey).toBeNull();
+    expect(snap.activeFile).toBeNull();
+  });
+
+  it("openPreview adds a preview tab and makes it active", () => {
+    store.openPreview("e1", "a.ts");
+    const snap = store.getSnapshot();
+    expect(snap.editors).toEqual([{ entryId: "e1", path: "a.ts", preview: true }]);
+    expect(snap.activeFile).toEqual({ entryId: "e1", path: "a.ts" });
+  });
+
+  it("openPreview reuses the single preview slot for a new file", () => {
+    store.openPreview("e1", "a.ts");
+    store.openPreview("e1", "b.ts");
+    // b.ts replaced a.ts in place — still one tab, now b.ts.
+    expect(paths(store)).toEqual(["b.ts"]);
+    expect(store.getSnapshot().activeFile).toEqual({ entryId: "e1", path: "b.ts" });
+  });
+
+  it("openPreview on an already-open editor just focuses it (no duplicate)", () => {
+    store.openPinned("e1", "a.ts");
+    store.openPinned("e1", "b.ts");
+    store.openPreview("e1", "a.ts");
+    expect(paths(store)).toEqual(["a.ts", "b.ts"]);
+    expect(store.getSnapshot().activeFile).toEqual({ entryId: "e1", path: "a.ts" });
+    // a.ts stays pinned — focusing does not turn it back into a preview.
+    expect(store.getSnapshot().editors[0].preview).toBe(false);
+  });
+
+  it("a pinned tab survives when a subsequent preview opens", () => {
+    store.openPinned("e1", "a.ts");
+    store.openPreview("e1", "b.ts");
+    store.openPreview("e1", "c.ts");
+    // a.ts pinned stays; the preview slot cycled b.ts -> c.ts.
+    expect(paths(store)).toEqual(["a.ts", "c.ts"]);
+  });
+
+  it("openPinned promotes an existing preview tab to persistent", () => {
+    store.openPreview("e1", "a.ts");
+    expect(store.getSnapshot().editors[0].preview).toBe(true);
+    store.openPinned("e1", "a.ts");
+    expect(store.getSnapshot().editors[0].preview).toBe(false);
+    expect(paths(store)).toEqual(["a.ts"]);
+  });
+
+  it("pin clears the preview flag", () => {
+    store.openPreview("e1", "a.ts");
+    store.pin("e1", "a.ts");
+    expect(store.getSnapshot().editors[0].preview).toBe(false);
+  });
+
+  it("activate focuses an open tab and no-ops for an unopened one", () => {
+    store.openPinned("e1", "a.ts");
+    store.openPinned("e1", "b.ts");
+    store.activate("e1", "a.ts");
+    expect(store.getSnapshot().activeFile).toEqual({ entryId: "e1", path: "a.ts" });
+    store.activate("e1", "missing.ts");
+    expect(store.getSnapshot().activeFile).toEqual({ entryId: "e1", path: "a.ts" });
+  });
+
+  it("close removes a tab and activates the right neighbor", () => {
+    store.openPinned("e1", "a.ts");
+    store.openPinned("e1", "b.ts");
+    store.openPinned("e1", "c.ts");
+    store.activate("e1", "b.ts");
+    store.close("e1", "b.ts");
+    expect(paths(store)).toEqual(["a.ts", "c.ts"]);
+    // The tab that shifted into b's slot (c.ts) becomes active.
+    expect(store.getSnapshot().activeFile).toEqual({ entryId: "e1", path: "c.ts" });
+  });
+
+  it("close activates the left neighbor when the last tab is closed", () => {
+    store.openPinned("e1", "a.ts");
+    store.openPinned("e1", "b.ts");
+    store.activate("e1", "b.ts");
+    store.close("e1", "b.ts");
+    expect(store.getSnapshot().activeFile).toEqual({ entryId: "e1", path: "a.ts" });
+  });
+
+  it("closing the only tab empties the group", () => {
+    store.openPreview("e1", "a.ts");
+    store.close("e1", "a.ts");
+    expect(store.getSnapshot().editors).toEqual([]);
+    expect(store.getSnapshot().activeFile).toBeNull();
+  });
+
+  it("closing an inactive tab keeps the active one", () => {
+    store.openPinned("e1", "a.ts");
+    store.openPinned("e1", "b.ts");
+    store.activate("e1", "b.ts");
+    store.close("e1", "a.ts");
+    expect(store.getSnapshot().activeFile).toEqual({ entryId: "e1", path: "b.ts" });
+  });
+
+  it("keys files by entry, so same path in two entries are distinct tabs", () => {
+    store.openPinned("e1", "a.ts");
+    store.openPinned("e2", "a.ts");
+    expect(store.getSnapshot().editors).toHaveLength(2);
+    expect(store.getSnapshot().activeFile).toEqual({ entryId: "e2", path: "a.ts" });
+  });
+
+  it("returns a stable snapshot ref between mutations", () => {
+    store.openPreview("e1", "a.ts");
+    const snapA = store.getSnapshot();
+    const snapB = store.getSnapshot();
+    expect(snapA).toBe(snapB);
+    store.openPreview("e1", "b.ts");
+    expect(store.getSnapshot()).not.toBe(snapA);
+  });
+
+  it("notifies subscribers on mutation", () => {
+    let count = 0;
+    const unsub = store.subscribe(() => {
+      count++;
+    });
+    store.openPreview("e1", "a.ts");
+    expect(count).toBe(1);
+    unsub();
+    store.openPreview("e1", "b.ts");
+    expect(count).toBe(1);
+  });
+
+  it("closeAll empties a populated group and is a no-op when empty", () => {
+    store.openPinned("e1", "a.ts");
+    let count = 0;
+    store.subscribe(() => {
+      count++;
+    });
+    store.closeAll();
+    expect(store.getSnapshot().editors).toEqual([]);
+    expect(count).toBe(1);
+    store.closeAll();
+    expect(count).toBe(1);
+  });
+
+  describe("reveal (jump-to-line)", () => {
+    it("starts with no reveal, and an open without a line sets none", () => {
+      expect(store.getSnapshot().reveal).toBeNull();
+      store.openPreview("e1", "a.ts");
+      expect(store.getSnapshot().reveal).toBeNull();
+    });
+
+    it("openPreview with a line sets a reveal targeting the active editor", () => {
+      store.openPreview("e1", "a.ts", { line: 42 });
+      const snap = store.getSnapshot();
+      expect(snap.reveal).toEqual({
+        key: editorKey("e1", "a.ts"),
+        line: 42,
+        nonce: expect.any(Number),
+      });
+      // The reveal always names the now-active editor.
+      expect(snap.reveal!.key).toBe(snap.activeKey);
+    });
+
+    it("bumps the nonce on every open-with-line, even for the same file+line", () => {
+      store.openPreview("e1", "a.ts", { line: 10 });
+      const first = store.getSnapshot().reveal!.nonce;
+      // A second search hit in the already-open, already-active file must still
+      // re-scroll — so the nonce advances.
+      store.openPreview("e1", "a.ts", { line: 10 });
+      expect(store.getSnapshot().reveal!.nonce).toBeGreaterThan(first);
+    });
+
+    it("clears the reveal when switching to another tab", () => {
+      store.openPinned("e1", "a.ts");
+      store.openPreview("e1", "b.ts", { line: 5 });
+      expect(store.getSnapshot().reveal).not.toBeNull();
+      store.activate("e1", "a.ts");
+      expect(store.getSnapshot().reveal).toBeNull();
+    });
+
+    it("clears the reveal on close and closeAll", () => {
+      store.openPreview("e1", "a.ts", { line: 5 });
+      store.close("e1", "a.ts");
+      expect(store.getSnapshot().reveal).toBeNull();
+
+      store.openPreview("e1", "b.ts", { line: 3 });
+      store.closeAll();
+      expect(store.getSnapshot().reveal).toBeNull();
+    });
+
+    it("preserves editors and activeFile refs on a reveal-only update", () => {
+      store.openPinned("e1", "a.ts");
+      const before = store.getSnapshot();
+      // Already open + active → only the reveal changes; the tab list and the
+      // active-file projection must keep their references (invariant #3).
+      store.openPreview("e1", "a.ts", { line: 9 });
+      const after = store.getSnapshot();
+      expect(after.editors).toBe(before.editors);
+      expect(after.activeFile).toBe(before.activeFile);
+      expect(after.reveal).toEqual({
+        key: editorKey("e1", "a.ts"),
+        line: 9,
+        nonce: expect.any(Number),
+      });
+      // Focusing-for-reveal must not turn a pinned tab back into a preview.
+      expect(after.editors[0].preview).toBe(false);
+    });
+  });
+});

package/src/internal/store/__tests__/workspace-file-selection-store.test.ts

@@ -0,0 +1,118 @@
+import { describe, it, expect, vi } from "vitest";
+import {
+  WorkspaceFileSelectionStore,
+  type SelectedWorkspaceFile,
+} from "../workspace-file-selection-store";
+
+function file(entryId: string, path: string): SelectedWorkspaceFile {
+  return { entryId, path };
+}
+
+describe("WorkspaceFileSelectionStore", () => {
+  it("starts with null selection", () => {
+    const store = new WorkspaceFileSelectionStore();
+    expect(store.getSelection()).toBeNull();
+  });
+
+  it("select sets the selection and notifies listeners", () => {
+    const store = new WorkspaceFileSelectionStore();
+    const listener = vi.fn();
+    store.subscribe(listener);
+
+    store.select(file("ws-1", "src/index.ts"));
+    expect(store.getSelection()).toEqual(file("ws-1", "src/index.ts"));
+    expect(listener).toHaveBeenCalledOnce();
+  });
+
+  it("select with an equal file does not notify", () => {
+    const store = new WorkspaceFileSelectionStore();
+    store.select(file("ws-1", "src/index.ts"));
+
+    const listener = vi.fn();
+    store.subscribe(listener);
+
+    store.select(file("ws-1", "src/index.ts"));
+    expect(listener).not.toHaveBeenCalled();
+  });
+
+  it("keeps a stable snapshot reference between mutations (getSnapshot safety)", () => {
+    const store = new WorkspaceFileSelectionStore();
+    store.select(file("ws-1", "a.ts"));
+    expect(store.getSelection()).toBe(store.getSelection());
+  });
+
+  it("select notifies when only the path differs within the same entry", () => {
+    const store = new WorkspaceFileSelectionStore();
+    store.select(file("ws-1", "a.ts"));
+
+    const listener = vi.fn();
+    store.subscribe(listener);
+
+    store.select(file("ws-1", "b.ts"));
+    expect(store.getSelection()).toEqual(file("ws-1", "b.ts"));
+    expect(listener).toHaveBeenCalledOnce();
+  });
+
+  it("deselect clears the selection and notifies", () => {
+    const store = new WorkspaceFileSelectionStore();
+    store.select(file("ws-1", "a.ts"));
+
+    const listener = vi.fn();
+    store.subscribe(listener);
+
+    store.deselect();
+    expect(store.getSelection()).toBeNull();
+    expect(listener).toHaveBeenCalledOnce();
+  });
+
+  it("deselect when already null does not notify", () => {
+    const store = new WorkspaceFileSelectionStore();
+    const listener = vi.fn();
+    store.subscribe(listener);
+
+    store.deselect();
+    expect(listener).not.toHaveBeenCalled();
+  });
+
+  it("toggle selects when nothing is selected", () => {
+    const store = new WorkspaceFileSelectionStore();
+    store.toggle(file("ws-1", "a.ts"));
+    expect(store.getSelection()).toEqual(file("ws-1", "a.ts"));
+  });
+
+  it("toggle deselects when the same file is selected", () => {
+    const store = new WorkspaceFileSelectionStore();
+    store.select(file("ws-1", "a.ts"));
+    store.toggle(file("ws-1", "a.ts"));
+    expect(store.getSelection()).toBeNull();
+  });
+
+  it("toggle switches to a different file", () => {
+    const store = new WorkspaceFileSelectionStore();
+    store.select(file("ws-1", "a.ts"));
+    store.toggle(file("ws-2", "b.ts"));
+    expect(store.getSelection()).toEqual(file("ws-2", "b.ts"));
+  });
+
+  it("unsubscribe removes the listener", () => {
+    const store = new WorkspaceFileSelectionStore();
+    const listener = vi.fn();
+    const unsub = store.subscribe(listener);
+
+    unsub();
+    store.select(file("ws-1", "a.ts"));
+    expect(listener).not.toHaveBeenCalled();
+  });
+
+  it("supports multiple listeners", () => {
+    const store = new WorkspaceFileSelectionStore();
+    const a = vi.fn();
+    const b = vi.fn();
+    store.subscribe(a);
+    store.subscribe(b);
+
+    store.select(file("ws-1", "a.ts"));
+    expect(a).toHaveBeenCalledOnce();
+    expect(b).toHaveBeenCalledOnce();
+  });
+});

package/src/internal/store/index.ts

@@ -3,6 +3,14 @@
 import { createContext, useContext, useRef, useSyncExternalStore } from "react";
 import type { AgentExecution } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/api_pb";
 import { ConversationStore, type StreamState } from "./conversation-store.js";
+import {
+  WorkspaceFileSelectionStore,
+  type SelectedWorkspaceFile,
+} from "./workspace-file-selection-store.js";
+import {
+  WorkspaceEditorsStore,
+  type WorkspaceEditorsSnapshot,
+} from "./workspace-editors-store.js";
 
 export { ConversationStore, type StreamState } from "./conversation-store.js";
 export { structuralShare } from "./structural-share.js";
@@ -16,6 +24,22 @@ export {
 export { SelectionStore } from "./selection-store.js";
 export type { SelectedThreadItem } from "./selection-store.js";
 
+export { WorkspaceFileSelectionStore } from "./workspace-file-selection-store.js";
+export type { SelectedWorkspaceFile } from "./workspace-file-selection-store.js";
+
+export {
+  WorkspaceEditorsStore,
+  editorKey,
+  virtualEntryId,
+  isVirtualEntryId,
+} from "./workspace-editors-store.js";
+export type {
+  OpenEditor,
+  OpenFileOptions,
+  EditorReveal,
+  WorkspaceEditorsSnapshot,
+} from "./workspace-editors-store.js";
+
 // ---------------------------------------------------------------------------
 // Context
 // ---------------------------------------------------------------------------
@@ -75,3 +99,73 @@ export function useStoreExecution(
 export function useStoreStreamState(store: ConversationStore): StreamState {
   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<WorkspaceFileSelectionStore | null>(null);
+
+/**
+ * Access the workspace-file selection store from context.
+ * Throws if called outside a `WorkspaceFileSelectionContext.Provider`.
+ */
+export function useWorkspaceFileSelectionStore(): WorkspaceFileSelectionStore {
+  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(): WorkspaceFileSelectionStore {
+  const ref = useRef<WorkspaceFileSelectionStore | null>(null);
+  if (!ref.current) {
+    ref.current = new WorkspaceFileSelectionStore();
+  }
+  return ref.current;
+}
+
+/** Subscribe to the currently-selected workspace file. */
+export function useWorkspaceFileSelection(
+  store: WorkspaceFileSelectionStore,
+): SelectedWorkspaceFile | null {
+  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(): WorkspaceEditorsStore {
+  const ref = useRef<WorkspaceEditorsStore | null>(null);
+  if (!ref.current) {
+    ref.current = new WorkspaceEditorsStore();
+  }
+  return ref.current;
+}
+
+/** Subscribe to the open-editor group snapshot. */
+export function useWorkspaceEditors(
+  store: WorkspaceEditorsStore,
+): WorkspaceEditorsSnapshot {
+  return useSyncExternalStore(store.subscribe, store.getSnapshot);
+}