@stigmer/react 3.1.1 → 3.1.3

package/src/composer/SessionComposer.tsx

@@ -58,8 +58,9 @@ import {
  *
  * function handleBuildFromPlan() {
  *   // Switch to Agent mode and run immediately — no manual Send.
- *   composerRef.current?.submit("Implement the plan above", {
+ *   composerRef.current?.submit("Build from plan", {
  *     interactionMode: "agent",
+ *     buildFromPlan: true,
  *   });
  * }
  *
@@ -83,10 +84,23 @@ export interface SessionComposerHandle {
    * @param options.interactionMode - Force the interaction mode for this one
    *   submission, overriding the picker. Avoids the same-tick race when the
    *   caller also calls `onInteractionModeChange` just before submitting.
+   * @param options.attachments - Pre-uploaded attachments (storage keys from
+   *   `agentExecution.uploadAttachment`) to include with this one submission,
+   *   in addition to any files attached in the composer. Used by "Build from
+   *   plan" to deliver the approved `plan.md` to the implement execution.
+   * @param options.buildFromPlan - Marks this submission as the implement
+   *   turn of a Plan → Build handoff (`execution_config.build_from_plan`).
+   *   The runner injects the implement-plan directive and the thread hides
+   *   the turn's message; the message stays a short label for surfaces
+   *   without that treatment (the CLI, history).
    */
   submit(
     message: string,
-    options?: { interactionMode?: InteractionModeOption },
+    options?: {
+      interactionMode?: InteractionModeOption;
+      attachments?: AttachmentInput[];
+      buildFromPlan?: boolean;
+    },
   ): void;
 }
 
@@ -142,6 +156,18 @@ export interface SessionComposerSubmitContext {
    * Pass to execution creation as `workspaceFileRefs`.
    */
   readonly workspaceFileRefs?: string[];
+  /**
+   * The submission is a Build-from-plan turn.
+   *
+   * Only ever set through {@link SessionComposerHandle.submit} (the thread
+   * card / plan editor CTA) — there is no composer UI for it. Pass to
+   * execution creation as `execution_config.build_from_plan`; the runner
+   * injects the implement-plan directive and the thread hides the turn's
+   * machine-written message (the plan card above it is the visible cause).
+   *
+   * `undefined` for ordinary submissions.
+   */
+  readonly buildFromPlan?: boolean;
 }
 
 /** Props for {@link SessionComposer}. */
@@ -724,7 +750,14 @@ const SessionComposerInner = forwardRef<SessionComposerHandle, SessionComposerPr
   // ---------------------------------------------------------------------------
 
   const handleSubmit = useCallback(
-    async (message: string, modeOverride?: InteractionModeOption) => {
+    async (
+      message: string,
+      overrides?: {
+        interactionMode?: InteractionModeOption;
+        attachments?: AttachmentInput[];
+        buildFromPlan?: boolean;
+      },
+    ) => {
       // Persist save-for-future manual secrets before building runtimeEnv
       if (sessionVariables?.hasSaveForFutureEntries) {
         const saveVars = sessionVariables.toSaveForFutureEnv();
@@ -763,27 +796,34 @@ const SessionComposerInner = forwardRef<SessionComposerHandle, SessionComposerPr
         Object.assign(env, sessionVariables.toRuntimeEnv());
       }
 
-      const attachmentInputs = enableAttachments
+      // Composer-attached files plus caller-supplied extras (e.g. the approved
+      // plan.md from a Build-from-plan turn) travel as one attachment list.
+      const composerAttachments = enableAttachments
         ? attachments.toAttachmentInputs()
-        : undefined;
+        : [];
+      const attachmentInputs = [
+        ...composerAttachments,
+        ...(overrides?.attachments ?? []),
+      ];
 
       const hasEnv = Object.keys(env).length > 0;
-      const hasAttachments =
-        attachmentInputs !== undefined && attachmentInputs.length > 0;
+      const hasAttachments = attachmentInputs.length > 0;
       const effectiveMode =
-        modeOverride ??
+        overrides?.interactionMode ??
         (showInteractionModePicker && interactionMode
           ? interactionMode
           : undefined);
       const hasFileRefs = enableFileReferences && fileRefs.hasRefs;
+      const buildFromPlan = overrides?.buildFromPlan;
 
       const context: SessionComposerSubmitContext | undefined =
-        hasEnv || hasAttachments || effectiveMode || hasFileRefs
+        hasEnv || hasAttachments || effectiveMode || hasFileRefs || buildFromPlan
           ? {
               runtimeEnv: hasEnv ? env : undefined,
               attachments: hasAttachments ? attachmentInputs : undefined,
               interactionMode: effectiveMode,
               workspaceFileRefs: hasFileRefs ? [...fileRefs.refs] : undefined,
+              buildFromPlan,
             }
           : undefined;
 
@@ -813,7 +853,7 @@ const SessionComposerInner = forwardRef<SessionComposerHandle, SessionComposerPr
     submit: (message, options) => {
       const trimmed = message.trim();
       if (!trimmed || isDisabled) return;
-      void handleSubmit(trimmed, options?.interactionMode);
+      void handleSubmit(trimmed, options);
     },
   }), [composer.setMessage, composer.textareaRef, handleSubmit, isDisabled]);
 
@@ -1343,6 +1383,9 @@ const SessionComposerInner = forwardRef<SessionComposerHandle, SessionComposerPr
         className={cn(
           "rounded-xl border border-border bg-card shadow-sm",
           "focus-within:ring-2 focus-within:ring-ring",
+          // Plan mode tints the frame so the active mode is visible at a
+          // glance, without opening the picker. Themeable via --stgm-primary-muted.
+          interactionMode === "plan" && "border-primary-muted",
           isDisabled && !stopMode && "opacity-50",
           isDragOver && "ring-2 ring-primary/50",
         )}

package/src/composer/__tests__/SessionComposer-contract.test.tsx

@@ -125,7 +125,7 @@ describe("SessionComposer — public contract", () => {
   });
 });
 
-describe("SessionComposer — imperative submit (Implement plan)", () => {
+describe("SessionComposer — imperative submit (Build from plan)", () => {
   it("submits a message with the interactionMode override, even when the picker is 'plan'", async () => {
     const ref = createRef<SessionComposerHandle>();
     const { onSubmit } = renderComposer({
@@ -134,13 +134,13 @@ describe("SessionComposer — imperative submit (Implement plan)", () => {
       interactionMode: "plan",
     });
 
-    ref.current!.submit("Implement the plan above", { interactionMode: "agent" });
+    ref.current!.submit("Build from plan", { interactionMode: "agent" });
 
     await waitFor(() => {
       expect(onSubmit).toHaveBeenCalledOnce();
     });
     const [message, , context] = onSubmit.mock.calls[0];
-    expect(message).toBe("Implement the plan above");
+    expect(message).toBe("Build from plan");
     // The override must win over the current picker value ("plan") so the
     // implement run executes in Agent mode regardless of render timing.
     expect(context?.interactionMode).toBe("agent");
@@ -150,7 +150,7 @@ describe("SessionComposer — imperative submit (Implement plan)", () => {
     const ref = createRef<SessionComposerHandle>();
     const { onSubmit } = renderComposer({ ref, disabled: true });
 
-    ref.current!.submit("Implement the plan above", { interactionMode: "agent" });
+    ref.current!.submit("Build from plan", { interactionMode: "agent" });
 
     expect(onSubmit).not.toHaveBeenCalled();
   });
@@ -163,4 +163,58 @@ describe("SessionComposer — imperative submit (Implement plan)", () => {
 
     expect(onSubmit).not.toHaveBeenCalled();
   });
+
+  it("carries caller-supplied attachments into the submit context (approved plan.md)", async () => {
+    const ref = createRef<SessionComposerHandle>();
+    const { onSubmit } = renderComposer({ ref });
+
+    const planAttachment = {
+      filename: "plan.md",
+      storageKey: "attachments/01ABC/plan.md",
+      mountPath: ".stigmer/inputs/plan.md",
+      contentType: "text/markdown",
+    };
+    ref.current!.submit("Build from plan", {
+      interactionMode: "agent",
+      attachments: [planAttachment],
+    });
+
+    await waitFor(() => {
+      expect(onSubmit).toHaveBeenCalledOnce();
+    });
+    const [, , context] = onSubmit.mock.calls[0];
+    expect(context?.attachments).toEqual([planAttachment]);
+    expect(context?.interactionMode).toBe("agent");
+  });
+
+  it("carries the buildFromPlan flag into the submit context", async () => {
+    const ref = createRef<SessionComposerHandle>();
+    const { onSubmit } = renderComposer({ ref });
+
+    ref.current!.submit("Build from plan", {
+      interactionMode: "agent",
+      buildFromPlan: true,
+    });
+
+    await waitFor(() => {
+      expect(onSubmit).toHaveBeenCalledOnce();
+    });
+    const [, , context] = onSubmit.mock.calls[0];
+    expect(context?.buildFromPlan).toBe(true);
+    expect(context?.interactionMode).toBe("agent");
+  });
+
+  it("leaves buildFromPlan unset for ordinary submissions", async () => {
+    const { onSubmit } = renderComposer();
+
+    const textarea = screen.getByRole("textbox");
+    fireEvent.change(textarea, { target: { value: "Hello world" } });
+    fireEvent.keyDown(textarea, { key: "Enter", shiftKey: false });
+
+    await waitFor(() => {
+      expect(onSubmit).toHaveBeenCalledOnce();
+    });
+    const [, , context] = onSubmit.mock.calls[0];
+    expect(context?.buildFromPlan).toBeUndefined();
+  });
 });

package/src/execution/ArtifactContentRenderer.tsx

@@ -1,6 +1,6 @@
 "use client";
 
-import { useMemo, useState, type ReactNode } from "react";
+import { useEffect, useMemo, useState, type ReactNode } from "react";
 import Markdown from "react-markdown";
 import { cn } from "@stigmer/theme";
 import {
@@ -8,6 +8,7 @@ import {
   REMARK_PLUGINS,
   unwrapEnclosingMarkdownFence,
 } from "../internal/markdown-components.js";
+import { useRevealLine, type RevealTarget } from "../internal/useRevealLine.js";
 import {
   getArtifactRenderMode,
   type ArtifactRenderMode,
@@ -29,6 +30,15 @@ export interface ArtifactContentRendererProps {
   readonly contentType?: string | null;
   /** When `true`, shows a truncation warning below the content. */
   readonly isTruncated?: boolean;
+  /**
+   * Optional jump-to-line request. When set, the content is rendered
+   * **line-faithfully** so the line number maps to the file's real rows —
+   * Markdown defaults to its Source view (a line only exists in source) and
+   * JSON renders raw rather than pretty-printed (reformatting would shift line
+   * numbers) — and the target line is scrolled into view and highlighted. Absent
+   * (the default), rendering is unchanged. See {@link RevealTarget}.
+   */
+  readonly reveal?: RevealTarget;
   /** Additional CSS classes for the root element. */
   readonly className?: string;
 }
@@ -76,6 +86,7 @@ export function ArtifactContentRenderer({
   fileName,
   contentType,
   isTruncated = false,
+  reveal,
   className,
 }: ArtifactContentRendererProps) {
   const mode = getArtifactRenderMode(fileName, contentType);
@@ -83,13 +94,19 @@ export function ArtifactContentRenderer({
   return (
     <div className={cn(className)}>
       {mode === "markdown" ? (
-        <MarkdownView content={content} />
+        <MarkdownView content={content} reveal={reveal} />
       ) : mode === "yaml" ? (
-        <YamlView content={content} />
+        <YamlView content={content} reveal={reveal} />
       ) : mode === "json" ? (
-        <JsonView content={content} />
+        // A reveal needs raw, line-faithful JSON: pretty-printing reformats the
+        // file and would shift the target line off its real row.
+        reveal ? (
+          <LineNumberedPre content={content} reveal={reveal} />
+        ) : (
+          <JsonView content={content} />
+        )
       ) : (
-        <PlainTextView content={content} />
+        <PlainTextView content={content} reveal={reveal} />
       )}
 
       {isTruncated && <TruncationWarning />}
@@ -103,8 +120,21 @@ export function ArtifactContentRenderer({
 
 type MarkdownTab = "rendered" | "source";
 
-function MarkdownView({ content }: { readonly content: string }) {
-  const [tab, setTab] = useState<MarkdownTab>("rendered");
+function MarkdownView({
+  content,
+  reveal,
+}: {
+  readonly content: string;
+  readonly reveal?: RevealTarget;
+}) {
+  // A reveal targets a source line (the rendered HTML has no line concept), so
+  // default to — and, on every new reveal, return to — the Source view.
+  const [tab, setTab] = useState<MarkdownTab>(reveal ? "source" : "rendered");
+  // Keyed on the reveal nonce: each fresh jump-to-line returns to Source (where
+  // the line exists); switching to Rendered afterward sticks until the next hit.
+  useEffect(() => {
+    if (reveal) setTab("source");
+  }, [reveal?.nonce]);
 
   // A `.md` whose entire body is one ```markdown fence (e.g. a model-wrapped
   // plan) would render flat. Unwrap for the Rendered view only — Source stays
@@ -145,7 +175,7 @@ function MarkdownView({ content }: { readonly content: string }) {
           </Markdown>
         </div>
       ) : (
-        <LineNumberedPre content={content} />
+        <LineNumberedPre content={content} reveal={reveal} />
       )}
     </div>
   );
@@ -197,15 +227,6 @@ function TabButton({
  *
  * Values and block scalar content render in the default `text-foreground`.
  */
-function highlightYaml(content: string): ReactNode {
-  return content.split("\n").map((line, i) => (
-    <span key={i}>
-      {i > 0 && "\n"}
-      {highlightYamlLine(line)}
-    </span>
-  ));
-}
-
 function highlightYamlLine(line: string): ReactNode {
   if (!line.trim()) return line;
 
@@ -253,10 +274,38 @@ function highlightYamlValue(value: string): ReactNode {
   return <>{value}</>;
 }
 
-function YamlView({ content }: { readonly content: string }) {
+function YamlView({
+  content,
+  reveal,
+}: {
+  readonly content: string;
+  readonly reveal?: RevealTarget;
+}) {
+  const { containerRef, isRevealed } = useRevealLine(reveal);
+  const lines = content.split("\n");
+
   return (
     <pre className="overflow-x-auto p-4 font-mono text-xs leading-relaxed text-foreground">
-      <code>{highlightYaml(content)}</code>
+      <code ref={containerRef}>
+        {lines.map((line, i) => (
+          <span
+            key={i}
+            data-line={i + 1}
+            className={cn(
+              // Transparent left border by default so revealing a line only
+              // changes its color — never shifts the text (no layout jump).
+              "block border-l-2 border-transparent",
+              isRevealed(i + 1) && "border-primary bg-primary-subtle",
+            )}
+          >
+            {/* whitespace-pre inner + `\n` fallback preserves indentation and
+                the height of blank lines, mirroring LineNumberedPre. */}
+            <span className="whitespace-pre">
+              {line.trim() ? highlightYamlLine(line) : "\n"}
+            </span>
+          </span>
+        ))}
+      </code>
     </pre>
   );
 }
@@ -345,19 +394,47 @@ function JsonView({ content }: { readonly content: string }) {
 // Plain text view (monospace + line numbers)
 // ---------------------------------------------------------------------------
 
-function PlainTextView({ content }: { readonly content: string }) {
-  return <LineNumberedPre content={content} />;
+function PlainTextView({
+  content,
+  reveal,
+}: {
+  readonly content: string;
+  readonly reveal?: RevealTarget;
+}) {
+  return <LineNumberedPre content={content} reveal={reveal} />;
 }
 
-function LineNumberedPre({ content }: { readonly content: string }) {
+/**
+ * Line-numbered monospace view. The single line-faithful primitive behind plain
+ * text, Markdown Source, and reveal-mode JSON: every row is addressable
+ * (`data-line`), so a {@link RevealTarget} can scroll to and highlight a line
+ * (via {@link useRevealLine}). Absent a reveal it renders exactly as before.
+ */
+function LineNumberedPre({
+  content,
+  reveal,
+}: {
+  readonly content: string;
+  readonly reveal?: RevealTarget;
+}) {
+  const { containerRef, isRevealed } = useRevealLine(reveal);
   const lines = content.split("\n");
   const gutterWidth = String(lines.length).length;
 
   return (
     <pre className="overflow-x-auto font-mono text-xs leading-relaxed text-foreground">
-      <code>
+      <code ref={containerRef}>
         {lines.map((line, i) => (
-          <span key={i} className="flex">
+          <span
+            key={i}
+            data-line={i + 1}
+            className={cn(
+              // Transparent left border by default so a reveal only recolors the
+              // row — never shifts its text (no layout jump).
+              "flex border-l-2 border-transparent",
+              isRevealed(i + 1) && "border-primary bg-primary-subtle",
+            )}
+          >
             <span
               className="sticky left-0 select-none bg-background pr-4 text-right text-muted-foreground"
               style={{ minWidth: `${gutterWidth + 2}ch` }}

package/src/execution/ArtifactPreviewModal.tsx

@@ -47,10 +47,10 @@ export interface ArtifactPreviewContentProps {
    */
   readonly onApplied?: (result: ApplyResourceResult) => void;
   /**
-   * Optional plan-build action. When provided, a "Build from plan" primary
-   * button appears in the action bar (used for plan artifacts: turn the
-   * plan into an Agent run). Clicking it calls `onImplement` then closes
-   * the modal. Omit for non-actionable artifacts.
+   * Optional plan-build action. When provided, a "Build" primary button
+   * appears in the action bar (used for plan artifacts: turn the plan into
+   * an Agent run). Clicking it calls `onImplement` then closes the modal.
+   * Omit for non-actionable artifacts.
    */
   readonly onImplement?: () => void;
   /** Additional CSS classes for the root container. */
@@ -228,9 +228,9 @@ export function ArtifactPreviewContent({
     ctaLabel = `Push Skill to ${org}`;
   }
 
-  // "Build from plan" runs the plan; closing the modal lets the host's submit
-  // pipeline take over (switch to Agent + send). Single combined handler keeps
-  // the caller's contract simple ("just give me onImplement").
+  // "Build" runs the plan; closing the modal lets the host's submit pipeline
+  // take over (switch to Agent + send). Single combined handler keeps the
+  // caller's contract simple ("just give me onImplement").
   const handleImplement = useCallback(() => {
     onImplement?.();
     onClose();
@@ -329,7 +329,7 @@ export interface ArtifactPreviewModalProps {
   readonly onApplied?: (result: ApplyResourceResult) => void;
   /**
    * Optional plan-build action (see {@link ArtifactPreviewContentProps.onImplement}).
-   * When provided, a "Build from plan" primary button appears; clicking it calls
+   * When provided, a "Build" primary button appears; clicking it calls
    * `onImplement` then closes the modal.
    */
   readonly onImplement?: () => void;
@@ -701,7 +701,7 @@ function ActionBar({
             )}
           >
             <ImplementIcon />
-            Build from plan
+            Build
           </button>
         )}
         {applyResult ? (

package/src/execution/FileChangeProgressBar.tsx

@@ -0,0 +1,121 @@
+"use client";
+
+import { memo, useState } from "react";
+import type { FileChangeProgress } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/filereview_pb";
+import { cn } from "@stigmer/theme";
+import { FileKindBadge, FileLineStats } from "./FileReviewAtoms.js";
+import { FilePathLink } from "./FilePathLink.js";
+
+/** Props for {@link FileChangeProgressBar}. */
+export interface FileChangeProgressBarProps {
+  /**
+   * The transient mid-run progress snapshot for the active turn (DD-32). Feed
+   * this from `useSessionConversation().fileChangeProgress`. Renders nothing when
+   * undefined or when no files have changed yet — the server clears it once the
+   * turn's change set leaves CAPTURING, so the bar disappears exactly when the
+   * decision surface ({@link FileReviewDock}) takes over.
+   */
+  readonly progress: FileChangeProgress | undefined;
+  /** Additional CSS class names for the root container. */
+  readonly className?: string;
+}
+
+/**
+ * The live "N files changed so far" strip for a turn that is still running.
+ *
+ * WHY IT EXISTS. The transcript streams per-edit tool rows, but a change made by
+ * a shell command (a `sed`, a build step) has no tool row, and there is no
+ * running net-of-many-edits rollup until the turn ends. This bar fills that gap:
+ * a compact, NON-INTERACTIVE count of the workspace delta accumulating during
+ * the turn, pinned above the composer where the {@link FileReviewDock} will later
+ * appear. The two are mutually exclusive per turn (progress shows while CAPTURING;
+ * the dock shows once AWAITING_REVIEW), so the bar hands off cleanly to the dock.
+ *
+ * NEVER A DECISION SURFACE. Progress is non-authoritative and carries no file
+ * bodies — it is never reviewable or decidable. The reviewed diff is the
+ * turn-boundary candidate ({@link FileReviewDock} / the stamped transcript rows).
+ * A secret-like path is surfaced by name with its counts withheld (zeroed), so
+ * `FileLineStats` renders nothing for it.
+ *
+ * A11Y. Only the summary count is an `aria-live` region — the per-file list is
+ * not — so a screen reader hears "3 files changing" as the count moves, not a
+ * per-file barrage on every ~2s refresh.
+ *
+ * Purely presentational (headless-first, DD-003): the data lives in
+ * `useSessionConversation().fileChangeProgress`. `SessionViewer` mounts it above
+ * the dock by default.
+ *
+ * @example
+ * ```tsx
+ * const conv = useSessionConversation(sessionId);
+ * <FileChangeProgressBar progress={conv.fileChangeProgress} />
+ * ```
+ */
+export const FileChangeProgressBar = memo(function FileChangeProgressBar({
+  progress,
+  className,
+}: FileChangeProgressBarProps) {
+  const [expanded, setExpanded] = useState(false);
+
+  if (!progress || progress.filesChanged === 0) return null;
+
+  const { filesChanged, linesAdded, linesRemoved, entries } = progress;
+  const hiddenCount = filesChanged - entries.length;
+
+  return (
+    <div
+      role="region"
+      aria-label="File changes in progress"
+      data-cursor-target="file-change-progress-bar"
+      className={cn("border-t border-border-muted px-4 py-2", className)}
+    >
+      <div className="flex items-center gap-2">
+        <button
+          type="button"
+          onClick={() => setExpanded((prev) => !prev)}
+          aria-expanded={expanded}
+          className="flex min-w-0 flex-1 items-center gap-2 text-left text-xs text-muted-foreground hover:text-foreground"
+        >
+          <span
+            aria-hidden="true"
+            className={cn("shrink-0 transition-transform", expanded && "rotate-90")}
+          >
+            ▸
+          </span>
+          {/* Only the count is live: a screen reader hears the aggregate move,
+              not a per-file announcement on every refresh. */}
+          <span aria-live="polite" className="min-w-0 truncate">
+            {filesChanged} {filesChanged === 1 ? "file" : "files"} changing…
+          </span>
+        </button>
+        <FileLineStats linesAdded={linesAdded} linesRemoved={linesRemoved} />
+      </div>
+      {expanded && (
+        <ul className="mt-2 max-h-[30vh] space-y-1 overflow-y-auto">
+          {entries.map((entry) => {
+            const path = entry.pathAfter || entry.pathBefore;
+            return (
+              <li key={path} className="flex items-center gap-2">
+                <FileKindBadge kind={entry.kind} />
+                <FilePathLink
+                  path={path}
+                  dirDisplay="dim"
+                  className="min-w-0 flex-1 text-xs"
+                />
+                <FileLineStats
+                  linesAdded={entry.linesAdded}
+                  linesRemoved={entry.linesRemoved}
+                />
+              </li>
+            );
+          })}
+          {hiddenCount > 0 && (
+            <li className="text-xs text-muted-foreground-faint">
+              … and {hiddenCount} more
+            </li>
+          )}
+        </ul>
+      )}
+    </div>
+  );
+});

package/src/execution/FileChangesView.tsx

@@ -167,7 +167,13 @@ export function FileChangeDiff({
     if (change.captureLevel === FileChangeCaptureLevel.HUNK_ONLY) {
       return { additions: change.linesAdded, deletions: change.linesRemoved };
     }
-    return countHunks(hunks);
+    // Whole-file: count the rendered hunks (what the user actually sees). When
+    // there are none to count — the body is offloaded/loading/truncated — fall
+    // back to the capture-time counts, which are computed with the same diff
+    // algorithm and so agree with the hunks whenever both exist.
+    const computed = countHunks(hunks);
+    if (computed.additions > 0 || computed.deletions > 0) return computed;
+    return { additions: change.linesAdded, deletions: change.linesRemoved };
   }, [change.captureLevel, change.linesAdded, change.linesRemoved, hunks]);
 
   const showStatsRow = showStats && (stats.additions > 0 || stats.deletions > 0);
@@ -343,8 +349,11 @@ function countHunks(hunks: readonly DiffHunk[]): {
  * Projects a {@link FileChange} into a {@link FileDiffEntry} for the file list.
  *
  * Counts: hunk-only uses the runner's authoritative numbers; whole-file inline
- * is derived from the content; an offloaded whole-file side has no synchronous
- * content, so its count stays 0 until the file is opened and fetched.
+ * is derived from the content (identical to the runner's capture-time counts by
+ * construction — same diff algorithm). A whole-file side with no synchronous
+ * content (offloaded / binary) falls back to the runner's capture-time
+ * `linesAdded`/`linesRemoved` — zero when no count exists, which the list
+ * renders as no stat.
  */
 function toFileDiffEntry(change: FileChange): FileDiffEntry {
   const changeType =
@@ -370,7 +379,12 @@ function toFileDiffEntry(change: FileChange): FileDiffEntry {
     return { path: change.path, changeType, additions, deletions };
   }
 
-  return { path: change.path, changeType, additions: 0, deletions: 0 };
+  return {
+    path: change.path,
+    changeType,
+    additions: change.linesAdded,
+    deletions: change.linesRemoved,
+  };
 }
 
 /** Inline text of a side, or null when absent/offloaded/binary. */

package/src/execution/FilePathContext.tsx

@@ -18,11 +18,18 @@ export interface FilePathContextValue {
    * `FilePathLink` delegates to this callback instead of opening
    * a URL or copying to clipboard. Platform builders use this to
    * integrate their own file viewer or navigation.
+   *
+   * Return `false` to **decline** a specific path — `FilePathLink` then falls
+   * back to its default action (open the GitHub link / copy the path), so a
+   * handler that can only open *some* paths (e.g. resolvable workspace files)
+   * leaves the rest behaving as before. Returning `true` or `void` means the
+   * click was fully handled and the default is suppressed — preserving the
+   * behavior of existing `void`-returning handlers.
    */
   readonly onFilePathClick?: (
     path: string,
     resolved: ResolvedPathAction,
-  ) => void;
+  ) => boolean | void;
 }
 
 const DEFAULT_VALUE: FilePathContextValue = {