@stigmer/react 3.0.9-dev.20260616060535 → 3.1.0

package/src/execution/tool-categories.ts

@@ -1,4 +1,5 @@
 import type { ToolCall } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/message_pb";
+import { ToolCallStatus } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
 import type { JsonObject } from "@bufbuild/protobuf";
 import { ToolKind, resolveToolKind, resolveToolKindByName } from "@stigmer/sdk";
 
@@ -27,6 +28,96 @@ export type ToolCategory =
   | "mcp"
   | "unknown";
 
+/**
+ * How much of a settled tool call to reveal inline by default in the thread.
+ *
+ * - `"summary"` — a compact one-line row. Used when the label + primary arg +
+ *   result summary already tell the story (`Read foo.ts`, `Edit bar.ts +40 -0`,
+ *   `Search … 2 matches`). The full detail is one click away.
+ * - `"preview"` — the row renders its result body **always** (no card chevron),
+ *   because the one-liner cannot convey what happened so the content itself IS
+ *   the information (a shell command's output, an MCP result such as a
+ *   screenshot, a fetched page, a web-search answer, or an unrecognised tool's
+ *   output). The body's own in-place reveal expands it beyond the height budget.
+ *
+ * This is the *disclosure* axis (how much of a result to show); it is
+ * orthogonal to {@link isRunGroupableCategory} (whether consecutive same-kind
+ * calls fold into one chip). A category can be result-rich but never folded
+ * (`shell`), or foldable but never previewed (`read`).
+ */
+export type ToolDisclosure = "summary" | "preview";
+
+/**
+ * Categories whose result is foregrounded as a persistent bounded preview by
+ * default — those for which the compact one-liner cannot convey what happened,
+ * so the output itself carries the meaning. All other categories default to
+ * `"summary"`.
+ *
+ * File edits and writes are previewed: a `+N -M` summary says how much changed
+ * but not *what* — and the change is the decision-relevant content. Surfacing a
+ * bounded diff inline (Cursor-style) is the point of a code agent. The body is
+ * height-clamped with a single in-place reveal for the rest, so density stays
+ * under control even in turns with many edits.
+ */
+const PREVIEW_CATEGORIES: ReadonlySet<ToolCategory> = new Set<ToolCategory>([
+  "shell",
+  "edit",
+  "write",
+  "mcp",
+  "web-search",
+  "fetch",
+  "unknown",
+]);
+
+/**
+ * Low-signal categories whose consecutive runs fold into a single collapsible
+ * "Read 5 files" chip in the thread. These are the read-only, repetitive
+ * operations whose individual rows are noise in bulk; everything else renders
+ * as a persistent row. This is the *run-grouping* axis, orthogonal to
+ * {@link ToolDisclosure} — see {@link isRunGroupableCategory}.
+ */
+const RUN_GROUPABLE_CATEGORIES: ReadonlySet<ToolCategory> = new Set<ToolCategory>([
+  "read",
+  "list",
+  "search",
+]);
+
+/**
+ * Returns the default inline {@link ToolDisclosure} for a presentation
+ * category. This is the headless policy behind the thread's "keep a live
+ * preview for shell/MCP/unknown, keep generic tools compact" behaviour;
+ * consumers can override per {@link ToolKind} via {@link registerToolPresenter}.
+ */
+export function defaultDisclosureForCategory(
+  category: ToolCategory,
+): ToolDisclosure {
+  return PREVIEW_CATEGORIES.has(category) ? "preview" : "summary";
+}
+
+/**
+ * Returns whether a presentation category participates in run-grouping — i.e.
+ * whether a maximal run of consecutive calls of this category folds into one
+ * collapsible chip. See {@link RUN_GROUPABLE_CATEGORIES} and `segmentToolCalls`.
+ */
+export function isRunGroupableCategory(category: ToolCategory): boolean {
+  return RUN_GROUPABLE_CATEGORIES.has(category);
+}
+
+/**
+ * Returns whether a category's primary argument is a file path — the file
+ * tools (read / write / edit / delete). These render their path filename-first
+ * via {@link FilePathLink} (full path on hover) in headers and previews, rather
+ * than as a raw, often-absolute string.
+ */
+export function isFileCategory(category: ToolCategory): boolean {
+  return (
+    category === "read" ||
+    category === "write" ||
+    category === "edit" ||
+    category === "delete"
+  );
+}
+
 /** Resolved display metadata for a tool call, returned by {@link resolveToolCategory}. */
 export interface ToolCategoryInfo {
   /** Semantic category of the tool. */
@@ -72,6 +163,31 @@ export function isInternalTool(toolName: string): boolean {
   return resolveToolKindByName(toolName) === ToolKind.TODO;
 }
 
+/**
+ * Returns true for a tool call the runner collapsed in place — a superseded
+ * same-turn duplicate of an approval gate.
+ *
+ * When the agent emits one resource twice in a turn and both attempts are denied,
+ * the runner overlays the FIRST as the WAITING_APPROVAL gate and blanks the
+ * redundant twin to a content-less SKIPPED row (it cannot drop it — the backend's
+ * append-only-at-identity guard forbids removing a committed tool-call id). This
+ * predicate recognizes that blanked twin so the thread renders one card, not two.
+ *
+ * The signature is precise: a SKIPPED row with no approval flag, no result, no
+ * error, and no args preview. A genuinely user-skipped tool always retains the
+ * preview/args the user reviewed before skipping, so it is never blank and is
+ * never hidden by this.
+ */
+export function isCollapsedToolCall(toolCall: ToolCall): boolean {
+  return (
+    toolCall.status === ToolCallStatus.TOOL_CALL_SKIPPED &&
+    !toolCall.requiresApproval &&
+    !toolCall.result &&
+    !toolCall.error &&
+    !toolCall.argsPreview
+  );
+}
+
 /** Maps a {@link ToolKind} to its presentation metadata. */
 export function toolKindToCategoryInfo(
   kind: ToolKind,
@@ -226,11 +342,19 @@ export function extractPrimaryArg(toolCall: ToolCall): string | null {
  * Extracts the primary argument value from a JSON string
  * (typically `PendingApproval.argsPreview`). Returns `null` if
  * parsing fails or the expected field is not found.
+ *
+ * When the caller has the denormalized wire `tool_kind` (as `PendingApproval`
+ * does), pass it so resolution honors the same kind that drives the label/icon —
+ * a file tool whose NAME the classifier doesn't recognize still resolves to its
+ * `path` field. This mirrors {@link extractPrimaryArg}, which uses the wire kind
+ * via `resolveToolCategoryFromCall`. Falls back to name-based resolution when
+ * the kind is unset (legacy executions).
  */
 export function extractPrimaryArgFromPreview(
   toolName: string,
   argsPreview: string,
   mcpServerSlug?: string,
+  toolKind?: ToolKind,
 ): string | null {
   if (!argsPreview) return null;
 
@@ -238,7 +362,10 @@ export function extractPrimaryArgFromPreview(
     const parsed = JSON.parse(argsPreview);
     if (typeof parsed !== "object" || parsed === null) return null;
 
-    const info = resolveToolCategory(toolName, mcpServerSlug);
+    const info =
+      toolKind !== undefined
+        ? resolveToolCategoryFromKind(toolKind, toolName, mcpServerSlug)
+        : resolveToolCategory(toolName, mcpServerSlug);
     return extractArgValue(
       parsed as JsonObject,
       info.primaryArgField,

package/src/execution/tool-presenter.ts

@@ -16,16 +16,34 @@ import { useMemo } from "react";
 import type { ToolCall } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/message_pb";
 import { ToolKind, resolveToolKind, normalizeToolResult } from "@stigmer/sdk";
 import type { ToolResultView } from "@stigmer/sdk";
-import { resolveToolCategoryFromCall, extractPrimaryArg } from "./tool-categories";
-import type { ToolCategory } from "./tool-categories";
+import {
+  resolveToolCategoryFromCall,
+  extractPrimaryArg,
+  defaultDisclosureForCategory,
+  isRunGroupableCategory,
+} from "./tool-categories";
+import type { ToolCategory, ToolDisclosure } from "./tool-categories";
 import { summarizeResultView } from "./ResultView";
 
-/** Optional per-kind overrides for label and summary. */
+/** Optional per-kind overrides for label, summary, disclosure, and run-grouping. */
 export interface ToolPresenter {
   /** Overrides the display label (e.g. "Shell" -> "Run command"). */
   readonly label?: (toolCall: ToolCall) => string;
   /** Overrides the one-line result summary suffix. */
   readonly summary?: (toolCall: ToolCall, result: ToolResultView) => string | null;
+  /**
+   * Overrides the default inline disclosure. Use to keep a noisy MCP tool
+   * compact (`() => "summary"`) or to foreground a custom tool's output
+   * (`() => "preview"`) without forking the components.
+   */
+  readonly disclosure?: (toolCall: ToolCall, result: ToolResultView) => ToolDisclosure;
+  /**
+   * Overrides whether consecutive same-kind calls fold into one collapsible
+   * "Read 5 files" chip. Use to fold a chatty custom tool (`() => true`) or to
+   * keep a normally-folded category as standalone rows (`() => false`) without
+   * forking the thread layout. Defaults to {@link isRunGroupableCategory}.
+   */
+  readonly runGroupable?: (toolCall: ToolCall) => boolean;
 }
 
 const registry = new Map<ToolKind, ToolPresenter>();
@@ -72,6 +90,22 @@ export function getToolPresenter(kind: ToolKind): ToolPresenter | undefined {
   return registry.get(kind);
 }
 
+/**
+ * Resolves whether a tool call participates in run-grouping, honouring a
+ * registered {@link ToolPresenter.runGroupable} override before the
+ * category default ({@link isRunGroupableCategory}).
+ *
+ * This is the non-hook twin of the `runGroupable` field in
+ * {@link useToolPresentation}, so the pure `segmentToolCalls` layout pass and
+ * the component layer share one source of truth (and honour the same override).
+ */
+export function resolveRunGroupable(toolCall: ToolCall): boolean {
+  const kind = resolveToolKind(toolCall);
+  const override = registry.get(kind)?.runGroupable;
+  if (override) return override(toolCall);
+  return isRunGroupableCategory(resolveToolCategoryFromCall(toolCall).category);
+}
+
 /** The fully-resolved presentation for a tool call, returned by {@link useToolPresentation}. */
 export interface ToolPresentation {
   /** Harness-agnostic kind (wire field, with name fallback). */
@@ -86,6 +120,19 @@ export interface ToolPresentation {
   readonly result: ToolResultView;
   /** One-line result summary suffix for the collapsed row (e.g. "+40 -0"). */
   readonly resultSummary: string | null;
+  /**
+   * Default inline disclosure for this tool — `"preview"` keeps a bounded,
+   * persistent preview of the result, `"summary"` keeps a compact row. The
+   * active/awaiting state can still force a row open; this is the *settled*
+   * default.
+   */
+  readonly disclosure: ToolDisclosure;
+  /**
+   * Whether consecutive same-kind calls fold into one collapsible chip — the
+   * run-grouping axis, orthogonal to {@link disclosure}. See
+   * {@link isRunGroupableCategory}.
+   */
+  readonly runGroupable: boolean;
 }
 
 /**
@@ -105,6 +152,12 @@ export function useToolPresentation(toolCall: ToolCall): ToolPresentation {
     const label = override?.label?.(toolCall) ?? categoryInfo.label;
     const resultSummary =
       override?.summary?.(toolCall, result) ?? summarizeResultView(result);
+    const disclosure =
+      override?.disclosure?.(toolCall, result) ??
+      defaultDisclosureForCategory(categoryInfo.category);
+    const runGroupable =
+      override?.runGroupable?.(toolCall) ??
+      isRunGroupableCategory(categoryInfo.category);
 
     return {
       kind,
@@ -113,6 +166,8 @@ export function useToolPresentation(toolCall: ToolCall): ToolPresentation {
       primaryArg: extractPrimaryArg(toolCall),
       result,
       resultSummary,
+      disclosure,
+      runGroupable,
     };
   }, [toolCall]);
 }

package/src/execution/tool-rendering-primitives.tsx

@@ -2,6 +2,7 @@
 
 import { useState } from "react";
 import { cn } from "@stigmer/theme";
+import { RevealToggle } from "../internal/RevealToggle";
 
 /**
  * Shared truncation threshold for all collapsible tool rendering
@@ -48,13 +49,11 @@ export function CollapsibleCode({ label, content, className }: CollapsibleCodePr
         {displayContent}
       </pre>
       {needsTruncation && (
-        <button
-          type="button"
-          onClick={() => setIsExpanded((v) => !v)}
-          className="text-xs font-medium text-primary transition-colors hover:text-primary-muted"
-        >
-          {isExpanded ? "Show less" : `Show all ${lines.length} lines`}
-        </button>
+        <RevealToggle
+          expanded={isExpanded}
+          onToggle={() => setIsExpanded((v) => !v)}
+          moreLabel={`Show all ${lines.length} lines`}
+        />
       )}
     </div>
   );
@@ -97,13 +96,11 @@ export function CollapsiblePre({ content, className }: CollapsiblePreProps) {
         {displayContent}
       </pre>
       {needsTruncation && (
-        <button
-          type="button"
-          onClick={() => setIsExpanded((v) => !v)}
-          className="mt-1 text-xs font-medium text-primary transition-colors hover:text-primary-muted"
-        >
-          {isExpanded ? "Show less" : `Show all ${lines.length} lines`}
-        </button>
+        <RevealToggle
+          expanded={isExpanded}
+          onToggle={() => setIsExpanded((v) => !v)}
+          moreLabel={`Show all ${lines.length} lines`}
+        />
       )}
     </>
   );

package/src/execution/useArtifactDownload.ts

@@ -0,0 +1,109 @@
+"use client";
+
+import { useCallback, useMemo, useState } from "react";
+import { create } from "@bufbuild/protobuf";
+import { GetArtifactDownloadUrlRequestSchema } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/io_pb";
+import { useStigmer } from "../hooks";
+import { toError } from "../internal/toError";
+
+/** Return value of {@link useArtifactDownload}. */
+export interface UseArtifactDownloadReturn {
+  /**
+   * Mint a fresh presigned URL for `storageKey` and trigger a browser
+   * download. No-op when the execution id is unknown or a download is already
+   * in flight. Resolves once the download has been initiated.
+   *
+   * @param storageKey - Storage key of the artifact to download.
+   * @param fileName - Optional suggested file name for the saved file.
+   */
+  readonly download: (storageKey: string, fileName?: string) => Promise<void>;
+
+  /** `true` while a URL is being minted / the download is being initiated. */
+  readonly isDownloading: boolean;
+
+  /** Error from the last failed download attempt, or `null` when healthy. */
+  readonly error: Error | null;
+}
+
+/**
+ * Behavior hook that downloads an execution artifact on demand.
+ *
+ * Mirrors the click → mint fresh URL → browser download flow established by
+ * `WorkflowExecutionArtifactPanel`, generalized so every artifact "Download"
+ * affordance shares one implementation. The URL is minted at click time from
+ * the stable `storageKey` via `getArtifactDownloadUrl`, so it is always valid —
+ * unlike the previously persisted, short-lived URL that expired after an hour.
+ *
+ * Returns an imperative `download(storageKey, fileName?)` action rather than a
+ * URL, because a download is a user action, not render data. For rendering an
+ * image or showing a link, use {@link useArtifactDownloadUrl} instead.
+ *
+ * @param executionId - Execution that produced the artifacts, or `null` to
+ *   disable (the action becomes a no-op).
+ *
+ * @example
+ * ```tsx
+ * const { download, isDownloading } = useArtifactDownload(executionId);
+ * <button onClick={() => download(artifact.storageKey, artifact.name)} disabled={isDownloading}>
+ *   Download
+ * </button>
+ * ```
+ *
+ * @see useArtifactDownloadUrl — declarative URL resolver (image src, links)
+ */
+export function useArtifactDownload(
+  executionId: string | null,
+): UseArtifactDownloadReturn {
+  const stigmer = useStigmer();
+  const [isDownloading, setIsDownloading] = useState(false);
+  const [error, setError] = useState<Error | null>(null);
+
+  const download = useCallback(
+    async (storageKey: string, fileName?: string) => {
+      if (!executionId || !storageKey || isDownloading) return;
+      setIsDownloading(true);
+      setError(null);
+      try {
+        const result = await stigmer.agentExecution.getArtifactDownloadUrl(
+          create(GetArtifactDownloadUrlRequestSchema, { executionId, storageKey }),
+        );
+        if (result.downloadUrl) {
+          triggerBrowserDownload(result.downloadUrl, fileName);
+        }
+      } catch (err) {
+        setError(toError(err));
+      } finally {
+        setIsDownloading(false);
+      }
+    },
+    [executionId, stigmer, isDownloading],
+  );
+
+  return useMemo(
+    () => ({ download, isDownloading, error }),
+    [download, isDownloading, error],
+  );
+}
+
+/**
+ * Trigger a browser download for a URL via a transient anchor click. The
+ * `download` hint is best-effort: browsers ignore it for cross-origin URLs
+ * (e.g. R2), in which case the navigation still serves the file. Falls back to
+ * a new tab in non-DOM environments.
+ */
+function triggerBrowserDownload(url: string, fileName?: string): void {
+  if (typeof document === "undefined") {
+    if (typeof window !== "undefined") {
+      window.open(url, "_blank", "noopener,noreferrer");
+    }
+    return;
+  }
+  const anchor = document.createElement("a");
+  anchor.href = url;
+  if (fileName) anchor.download = fileName;
+  anchor.rel = "noopener noreferrer";
+  anchor.target = "_blank";
+  document.body.appendChild(anchor);
+  anchor.click();
+  document.body.removeChild(anchor);
+}

package/src/execution/useArtifactDownloadUrl.ts

@@ -0,0 +1,116 @@
+"use client";
+
+import { useMemo } from "react";
+import { create } from "@bufbuild/protobuf";
+import { GetArtifactDownloadUrlRequestSchema } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/io_pb";
+import { useStigmer } from "../hooks";
+import { useFetch } from "../internal/useFetch";
+
+/** Return value of {@link useArtifactDownloadUrl}. */
+export interface UseArtifactDownloadUrlReturn {
+  /**
+   * A freshly minted presigned download URL for the artifact, or `null` when:
+   * - Fetching is skipped (`enabled` is `false`, or `executionId`/`storageKey` is `null`)
+   * - The request is in-flight
+   * - The request failed
+   */
+  readonly url: string | null;
+
+  /** `true` while the URL request is in-flight (first load). */
+  readonly isLoading: boolean;
+
+  /** `true` while a background refetch is in flight. */
+  readonly isRefetching: boolean;
+
+  /** Error from the last failed attempt, or `null` when healthy. */
+  readonly error: Error | null;
+
+  /** Re-fetch the URL (e.g. to mint a fresh one after the previous expired). */
+  readonly refetch: () => void;
+}
+
+interface UrlData {
+  readonly url: string | null;
+}
+
+const EMPTY: UrlData = { url: null };
+
+/** Options for {@link useArtifactDownloadUrl}. */
+export interface UseArtifactDownloadUrlOptions {
+  /**
+   * Gate the request. When `false`, the hook stays idle and returns `null` —
+   * use this to defer minting a URL until it is actually needed (e.g. only
+   * when an image becomes visible, or after a truncation is detected).
+   * Defaults to `true`.
+   */
+  readonly enabled?: boolean;
+}
+
+/**
+ * Data hook that resolves a **fresh** presigned download URL for an execution
+ * artifact on demand via `stigmer.agentExecution.getArtifactDownloadUrl()`.
+ *
+ * This exists because presigned URLs expire. The runner once baked a
+ * short-lived URL into the persisted execution status and the UI rendered it
+ * verbatim — so any link opened after the URL's lifetime failed with
+ * `ExpiredRequest`. Minting the URL at view time from the stable `storageKey`
+ * guarantees it is always valid, and works for every historical execution
+ * (the `storageKey` never expires).
+ *
+ * Use this for surfaces that genuinely need a URL — an `<img src>` for an
+ * offloaded screenshot, or a direct browser download of a large/binary
+ * artifact. For text that should render in-app, prefer {@link useArtifactContent}
+ * (CORS-safe, no presign).
+ *
+ * The URL is cached cross-mount by `storageKey` (DD-014), so repeated renders
+ * and remounts reuse the same minted URL instead of re-hitting the API.
+ *
+ * Pass `enabled: false` (or `null` for either id) to skip fetching — consistent
+ * with the `useArtifactContent(null, null)` convention.
+ *
+ * @param executionId - Execution that produced the artifact, or `null` to skip.
+ * @param storageKey - Storage key from the artifact/output ref, or `null` to skip.
+ * @param options - Optional gating (`enabled`).
+ *
+ * @example
+ * ```tsx
+ * // Render an offloaded screenshot with an always-fresh URL.
+ * const { url, isLoading } = useArtifactDownloadUrl(executionId, storageKey);
+ * if (isLoading) return <Skeleton />;
+ * return url ? <img src={url} alt="Tool output" /> : null;
+ * ```
+ *
+ * @see useArtifactContent — reads artifact bytes through the API (text preview)
+ * @see useArtifactDownload — imperative click-to-download counterpart
+ */
+export function useArtifactDownloadUrl(
+  executionId: string | null,
+  storageKey: string | null,
+  options?: UseArtifactDownloadUrlOptions,
+): UseArtifactDownloadUrlReturn {
+  const stigmer = useStigmer();
+  const enabled = options?.enabled ?? true;
+  const active = enabled && !!executionId && !!storageKey;
+
+  const { data, isLoading, isRefetching, error, refetch } = useFetch(
+    active
+      ? () =>
+          stigmer.agentExecution
+            .getArtifactDownloadUrl(
+              create(GetArtifactDownloadUrlRequestSchema, {
+                executionId: executionId!,
+                storageKey: storageKey!,
+              }),
+            )
+            .then((result): UrlData => ({ url: result.downloadUrl || null }))
+      : null,
+    [executionId, storageKey, active, stigmer],
+    EMPTY,
+    { cacheKey: storageKey ? `artifact-url:${storageKey}` : undefined },
+  );
+
+  return useMemo(
+    () => ({ url: data.url, isLoading, isRefetching, error, refetch }),
+    [data.url, isLoading, isRefetching, error, refetch],
+  );
+}

package/src/execution/useFileChangeContent.ts

@@ -0,0 +1,149 @@
+"use client";
+
+import { useMemo } from "react";
+import type {
+  FileChange,
+  FileContent,
+} from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/message_pb";
+import { useArtifactContent } from "./useArtifactContent";
+import { useArtifactDownloadUrl } from "./useArtifactDownloadUrl";
+
+/** Return value of {@link useFileChangeContent}. */
+export interface UseFileChangeContentReturn {
+  /**
+   * Before-side text for diffing. `""` for an absent side (e.g. CREATE has no
+   * before). `null` while an offloaded side is in-flight or failed to load.
+   */
+  readonly beforeText: string | null;
+  /**
+   * After-side text for diffing. `""` for an absent side (e.g. DELETE has no
+   * after). `null` while an offloaded side is in-flight or failed to load.
+   */
+  readonly afterText: string | null;
+  /** `true` when either side is binary — render "binary file changed", not a diff. */
+  readonly isBinary: boolean;
+  /** `true` while an offloaded side's content request is in flight. */
+  readonly isLoading: boolean;
+  /** Error from a failed offloaded-side fetch, or `null`. */
+  readonly error: Error | null;
+  /**
+   * `true` when an offloaded side exceeded the server's content-size limit and
+   * was truncated — the inline diff would be incomplete; offer {@link downloadUrl}.
+   */
+  readonly isTruncated: boolean;
+  /**
+   * Direct download URL for an offloaded side (the after side preferred), used
+   * as the fallback when content is truncated. `null` when neither side is offloaded.
+   */
+  readonly downloadUrl: string | null;
+}
+
+/**
+ * Behavior hook that resolves a {@link FileChange}'s before/after sides to the
+ * text the diff renderer needs.
+ *
+ * Small bodies are carried inline on the proto and returned with zero cost.
+ * Large bodies were offloaded to artifact storage by the runner
+ * (`FileContent.ref`); this hook lazily fetches them via
+ * {@link useArtifactContent} through the server proxy (CORS-safe). The fetch's
+ * `executionId` is derived from the ref's own `storageKey`
+ * (`artifacts/{executionId}/...`), so a net diff whose two sides originated in
+ * different executions still resolves each side correctly.
+ *
+ * This is the single place offload refs are dereferenced — the SDK's
+ * `tool-view` deliberately stays fetch-free, deferring all ref handling here.
+ *
+ * Rules-of-hooks safe: both sides always issue a (possibly skipped)
+ * `useArtifactContent` call; inline/absent sides pass `null` and never fetch.
+ *
+ * @param change - The file change whose content to resolve.
+ *
+ * @see useSessionFileChanges — produces the changes this resolves
+ * @see FileChangeDiff — renders the resolved content
+ */
+export function useFileChangeContent(
+  change: FileChange,
+): UseFileChangeContentReturn {
+  const beforeRef = refOf(change.before);
+  const afterRef = refOf(change.after);
+
+  const beforeFetch = useArtifactContent(
+    beforeRef ? execIdFromStorageKey(beforeRef.storageKey) : null,
+    beforeRef ? beforeRef.storageKey : null,
+    null,
+    beforeRef?.contentHash,
+  );
+  const afterFetch = useArtifactContent(
+    afterRef ? execIdFromStorageKey(afterRef.storageKey) : null,
+    afterRef ? afterRef.storageKey : null,
+    null,
+    afterRef?.contentHash,
+  );
+
+  // The download fallback is needed only when an offloaded side was truncated.
+  // Resolve a fresh URL on demand from the stable storageKey (after side
+  // preferred), gated on truncation so we don't mint a URL we won't use.
+  const isTruncated = beforeFetch.isTruncated || afterFetch.isTruncated;
+  const downloadRef = afterRef ?? beforeRef;
+  const { url: downloadUrl } = useArtifactDownloadUrl(
+    downloadRef ? execIdFromStorageKey(downloadRef.storageKey) : null,
+    downloadRef ? downloadRef.storageKey : null,
+    { enabled: isTruncated },
+  );
+
+  return useMemo(
+    () => ({
+      beforeText: sideText(change.before, beforeFetch.content),
+      afterText: sideText(change.after, afterFetch.content),
+      isBinary: Boolean(change.before?.isBinary || change.after?.isBinary),
+      isLoading: beforeFetch.isLoading || afterFetch.isLoading,
+      error: beforeFetch.error ?? afterFetch.error,
+      isTruncated,
+      downloadUrl,
+    }),
+    [
+      change.before,
+      change.after,
+      beforeFetch.content,
+      afterFetch.content,
+      beforeFetch.isLoading,
+      afterFetch.isLoading,
+      beforeFetch.error,
+      afterFetch.error,
+      isTruncated,
+      downloadUrl,
+    ],
+  );
+}
+
+/** The offload pointer of a side, or null when the side is absent/inline/binary. */
+function refOf(side: FileContent | undefined) {
+  if (!side || side.isBinary) return null;
+  return side.body.case === "ref" ? side.body.value : null;
+}
+
+/**
+ * Resolves one side to text: absent → "" (empty file), inline → its value,
+ * offloaded → the fetched content (`null` until it loads).
+ */
+function sideText(
+  side: FileContent | undefined,
+  fetched: string | null,
+): string | null {
+  if (!side || side.isBinary) return "";
+  if (side.body.case === "inline") return side.body.value;
+  return fetched;
+}
+
+/**
+ * Extracts the execution id from an artifact storage key of the form
+ * `artifacts/{executionId}/...`. Returns `null` for an unexpected shape so the
+ * caller skips the fetch rather than issuing a request the server would reject.
+ */
+export function execIdFromStorageKey(storageKey: string): string | null {
+  const parts = storageKey.split("/");
+  if (parts.length >= 3 && parts[0] === "artifacts" && parts[1]) {
+    return parts[1];
+  }
+  return null;
+}