@stigmer/react 3.1.1 → 3.1.3

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

@@ -0,0 +1,315 @@
+// 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.
+
+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;
+
+const EMPTY_SNAPSHOT: WorkspaceEditorsSnapshot = {
+  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: string, path: string): string {
+  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: string): string {
+  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: string): boolean {
+  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 {
+  private _snapshot: WorkspaceEditorsSnapshot = EMPTY_SNAPSHOT;
+  private _listeners = new Set<Listener>();
+  /** Monotonic reveal token — bumped on every open-with-line (see `openPreview`). */
+  private _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: string, path: string, options?: OpenFileOptions): void {
+    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: string, path: string): void {
+    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: string, path: string): void {
+    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: string, path: string): void {
+    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: string, path: string): void {
+    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(): void {
+    if (this._snapshot.editors.length === 0) return;
+    this._snapshot = EMPTY_SNAPSHOT;
+    this._notify();
+  }
+
+  // -- useSyncExternalStore contract ---------------------------------------
+
+  subscribe = (listener: Listener): (() => void) => {
+    this._listeners.add(listener);
+    return () => {
+      this._listeners.delete(listener);
+    };
+  };
+
+  /** Returns the current snapshot (stable ref between mutations). */
+  getSnapshot = (): WorkspaceEditorsSnapshot => this._snapshot;
+
+  // -- Internal ------------------------------------------------------------
+
+  private _setActive(key: string | null): void {
+    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. */
+  private _makeReveal(
+    key: string,
+    options: OpenFileOptions | undefined,
+  ): EditorReveal | null {
+    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).
+   */
+  private _commit(
+    editors: readonly OpenEditor[],
+    activeKey: string | null,
+    reveal: EditorReveal | null = null,
+  ): void {
+    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();
+  }
+
+  private _notify(): void {
+    for (const listener of this._listeners) {
+      listener();
+    }
+  }
+}

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

@@ -0,0 +1,88 @@
+// 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.
+
+/**
+ * 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 class WorkspaceFileSelectionStore {
+  private _selected: SelectedWorkspaceFile | null = null;
+  private _listeners = new Set<Listener>();
+
+  // -- Mutations -----------------------------------------------------------
+
+  select(file: SelectedWorkspaceFile): void {
+    if (selectedEqual(this._selected, file)) return;
+    this._selected = file;
+    this._notify();
+  }
+
+  deselect(): void {
+    if (this._selected === null) return;
+    this._selected = null;
+    this._notify();
+  }
+
+  toggle(file: SelectedWorkspaceFile): void {
+    if (selectedEqual(this._selected, file)) {
+      this.deselect();
+    } else {
+      this.select(file);
+    }
+  }
+
+  // -- useSyncExternalStore contract ---------------------------------------
+
+  subscribe = (listener: Listener): (() => void) => {
+    this._listeners.add(listener);
+    return () => {
+      this._listeners.delete(listener);
+    };
+  };
+
+  /** Returns the current selection (stable ref between mutations). */
+  getSelection = (): SelectedWorkspaceFile | null => {
+    return this._selected;
+  };
+
+  // -- Internal ------------------------------------------------------------
+
+  private _notify(): void {
+    for (const listener of this._listeners) {
+      listener();
+    }
+  }
+}
+
+function selectedEqual(
+  a: SelectedWorkspaceFile | null,
+  b: SelectedWorkspaceFile | null,
+): boolean {
+  if (a === b) return true;
+  if (a === null || b === null) return false;
+  return a.entryId === b.entryId && a.path === b.path;
+}

package/src/internal/useRevealLine.ts

@@ -0,0 +1,81 @@
+"use client";
+
+import { useCallback, useEffect, useRef, type RefObject } from "react";
+import { prefersReducedMotion } from "./motion-preference.js";
+
+/**
+ * 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 function useRevealLine<T extends HTMLElement = HTMLElement>(
+  reveal: RevealTarget | undefined,
+): UseRevealLineResult<T> {
+  const containerRef = useRef<T | null>(null);
+
+  useEffect(() => {
+    if (!reveal) return;
+    const container = containerRef.current;
+    if (!container) return;
+
+    const row = container.querySelector(`[data-line="${reveal.line}"]`);
+    // Optional call: jsdom (tests) implements no `scrollIntoView`.
+    row?.scrollIntoView?.({
+      block: "center",
+      behavior: prefersReducedMotion() ? "auto" : "smooth",
+    });
+    // Intentionally keyed only on the nonce: a repeat navigation to the same
+    // line (new nonce) must re-scroll, and `reveal.line` changes always ship a
+    // new nonce, so it is covered transitively.
+  }, [reveal?.nonce]);
+
+  const isRevealed = useCallback(
+    (line: number) => reveal?.line === line,
+    [reveal?.line],
+  );
+
+  return { containerRef, isRevealed };
+}

package/src/library/__tests__/detect-plan-artifact.test.ts

@@ -6,9 +6,12 @@ import {
 } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/api_pb";
 import { ExecutionArtifactSchema } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/artifact_pb";
 import { ExecutionArtifactKind } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+import { ApiResourceMetadataSchema } from "@stigmer/protos/ai/stigmer/commons/apiresource/metadata_pb";
 import {
   isPlanArtifact,
+  isPlanArtifactName,
   findPlanArtifact,
+  findLatestSessionPlan,
   PLAN_ARTIFACT_NAME,
 } from "../detect-plan-artifact";
 
@@ -26,11 +29,38 @@ function executionWith(...artifacts: ReturnType<typeof artifact>[]) {
   });
 }
 
+function executionWithId(id: string, ...artifacts: ReturnType<typeof artifact>[]) {
+  return create(AgentExecutionSchema, {
+    metadata: create(ApiResourceMetadataSchema, { id }),
+    status: create(AgentExecutionStatusSchema, { artifacts }),
+  });
+}
+
+describe("isPlanArtifactName", () => {
+  it("accepts the legacy exact name and any *.plan.md", () => {
+    expect(isPlanArtifactName(PLAN_ARTIFACT_NAME)).toBe(true);
+    expect(isPlanArtifactName("feature_x.plan.md")).toBe(true);
+    // The runner's current shape: hyphenated slug + content-hash discriminator.
+    expect(isPlanArtifactName("fix-the-download-ux_a1b2c3d4.plan.md")).toBe(true);
+    expect(isPlanArtifactName("a1b2c3d4.plan.md")).toBe(true);
+  });
+
+  it("rejects non-plan filenames", () => {
+    expect(isPlanArtifactName("report.md")).toBe(false);
+    expect(isPlanArtifactName("plan.txt")).toBe(false);
+    expect(isPlanArtifactName("myplan.md")).toBe(false);
+  });
+});
+
 describe("isPlanArtifact", () => {
   it("is true for a FILE artifact named plan.md", () => {
     expect(isPlanArtifact(artifact({ name: PLAN_ARTIFACT_NAME }))).toBe(true);
   });
 
+  it("is true for a FILE artifact named <slug>_<id>.plan.md", () => {
+    expect(isPlanArtifact(artifact({ name: "plan-card-ux-cleanup_a1b2c3d4.plan.md" }))).toBe(true);
+  });
+
   it("is false for a directory named plan.md", () => {
     expect(
       isPlanArtifact(artifact({ name: "plan.md", kind: ExecutionArtifactKind.DIRECTORY })),
@@ -73,3 +103,42 @@ describe("findPlanArtifact", () => {
     expect(findPlanArtifact(executionWith(artifact({ name: "report.md" })))).toBeUndefined();
   });
 });
+
+describe("findLatestSessionPlan", () => {
+  it("returns undefined when no execution published a plan", () => {
+    const execs = [
+      executionWithId("e1", artifact({ name: "report.md" })),
+      executionWithId("e2"),
+    ];
+    expect(findLatestSessionPlan(execs)).toBeUndefined();
+    expect(findLatestSessionPlan([])).toBeUndefined();
+  });
+
+  it("returns the newest plan across executions, with its execution id", () => {
+    const execs = [
+      executionWithId("e1", artifact({ name: PLAN_ARTIFACT_NAME, storageKey: "artifacts/e1/plan.md" })),
+      executionWithId("e2", artifact({ name: "notes.txt" })),
+      executionWithId("e3", artifact({ name: PLAN_ARTIFACT_NAME, storageKey: "artifacts/e3/plan.md" })),
+    ];
+
+    const plan = findLatestSessionPlan(execs);
+    expect(plan?.executionId).toBe("e3");
+    expect(plan?.artifact.storageKey).toBe("artifacts/e3/plan.md");
+  });
+
+  it("skips a newer plan-less execution and returns the older plan", () => {
+    const execs = [
+      executionWithId("e1", artifact({ name: PLAN_ARTIFACT_NAME })),
+      executionWithId("e2", artifact({ name: "data.json" })),
+    ];
+    expect(findLatestSessionPlan(execs)?.executionId).toBe("e1");
+  });
+
+  it("skips an execution whose plan artifact lacks a usable execution id", () => {
+    const execs = [
+      executionWithId("e1", artifact({ name: PLAN_ARTIFACT_NAME })),
+      executionWith(artifact({ name: PLAN_ARTIFACT_NAME })),
+    ];
+    expect(findLatestSessionPlan(execs)?.executionId).toBe("e1");
+  });
+});