dsh-generative-ui 0.0.0 → 0.0.2

package/package.json

@@ -1,11 +1,137 @@
 {
   "name": "dsh-generative-ui",
-  "version": "0.0.0",
-  "description": "Placeholder for dsh-generative-ui",
-  "main": "index.js",
-  "scripts": {},
-  "keywords": [],
-  "author": "muspi-merol (https://www.npmjs.com/~muspi-merol)",
-  "license": "UNLICENSED",
-  "private": false
-}
+  "version": "0.0.2",
+  "description": "Generative UI for DeepSeek Harness — the agent writes TSX, dsh web renders it live, inline in chat and in a canvas panel",
+  "type": "module",
+  "license": "MIT",
+  "main": "lib/index.js",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./client": {
+      "types": "./lib/types/client/index.d.ts",
+      "default": "./lib/client.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib",
+    "src",
+    "types",
+    "cordis.patch.yml"
+  ],
+  "keywords": [
+    "generative-ui",
+    "genui",
+    "ui4a",
+    "artifacts",
+    "canvas",
+    "dsh",
+    "dsh-plugin",
+    "deepseek-harness",
+    "cordis",
+    "cordis-plugin",
+    "react",
+    "tsx",
+    "streaming",
+    "ai-agents",
+    "llm"
+  ],
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    },
+    "client": {
+      "inject": [
+        "@deepseek-ai/dsh-client-runtime",
+        "@deepseek-ai/dsh-client-locale",
+        "@deepseek-ai/dsh-client-ui-conversation"
+      ],
+      "platform": "web"
+    }
+  },
+  "scripts": {
+    "build": "bun scripts/gen-standalone.ts && bun scripts/build.ts && tsc -p tsconfig.types.json",
+    "prepare": "bun scripts/gen-standalone.ts && bun scripts/build.ts && tsc -p tsconfig.types.json",
+    "typecheck": "tsc --noEmit",
+    "test": "bun test",
+    "loads": "sh scripts/loads.sh",
+    "smoke": "bun scripts/smoke.ts",
+    "check": "bun run lint && bun run typecheck && bun run test && bun run test:shuffled && bun run audit && bun run replay && bun run cards && bun run paint && bun run build && bun run smoke && bun run loads",
+    "check:ci": "bun run lint && bun run typecheck && bun run test && bun run test:shuffled && bun run audit && bun run replay && bun run cards && bun run paint && bun run build && bun run smoke",
+    "lint": "oxlint",
+    "fmt": "oxfmt",
+    "gen:standalone": "bun scripts/gen-standalone.ts",
+    "audit": "bun scripts/fresh-rates.ts 2>/dev/null | head -1 > /tmp/fresh-total.txt; python3 scripts/audit-record.py CLAUDE.md && bun scripts/corpus-rates.ts 2>/dev/null | python3 scripts/audit-rates.py",
+    "replay": "bun scripts/replay-stream.ts",
+    "cards": "bun scripts/compile-cards.ts",
+    "paint": "bun scripts/paint-cards.ts",
+    "cross-tab": "bun scripts/cross-tab.ts",
+    "inject": "bun scripts/inject.ts",
+    "hollow": "bun scripts/hollow.ts",
+    "test:shuffled": "sh scripts/test-shuffled.sh"
+  },
+  "dependencies": {
+    "@esm.sh/tsx": "^1.5.3",
+    "@unocss/core": "^66.8.1",
+    "@unocss/preset-wind4": "^66.8.1",
+    "partial-react": "~0.0.6",
+    "partial-tsx": "~0.0.3"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "^4.0.1",
+    "@deepseek-ai/dsh-client-locale": "^0.1.0-rc.7",
+    "@deepseek-ai/dsh-client-runtime": "^0.1.0-rc.7",
+    "@deepseek-ai/dsh-client-ui-conversation": "^0.1.0-rc.7",
+    "@deepseek-ai/dsh-client-ui-slots": "^0.1.0-rc.7",
+    "@deepseek-ai/dsh-host-webserver": "^0.1.0-rc.7",
+    "@deepseek-ai/dsh-llm": "^0.1.0-rc.7",
+    "@deepseek-ai/dsh-settings": "^0.1.0-rc.7",
+    "@deepseek-ai/dsh-skill": "^0.1.0-rc.7",
+    "@deepseek-ai/schemastery": "^3.18.1",
+    "react": "^18.2.0"
+  },
+  "devDependencies": {
+    "@deepseek-ai/cordis": "^4.0.1",
+    "@deepseek-ai/dsh-client-locale": "0.1.0-rc.8",
+    "@deepseek-ai/dsh-client-runtime": "0.1.0-rc.8",
+    "@deepseek-ai/dsh-client-ui-conversation": "0.1.0-rc.8",
+    "@deepseek-ai/dsh-client-ui-layout": "0.1.0-rc.8",
+    "@deepseek-ai/dsh-client-ui-slots": "0.1.0-rc.8",
+    "@deepseek-ai/dsh-host-webserver": "0.1.0-rc.8",
+    "@deepseek-ai/dsh-llm": "0.1.0-rc.8",
+    "@deepseek-ai/dsh-settings": "0.1.0-rc.8",
+    "@deepseek-ai/dsh-skill": "0.1.0-rc.8",
+    "@deepseek-ai/dsh-system-prompt": "0.1.0-rc.8",
+    "@deepseek-ai/schemastery": "^3.18.1",
+    "@types/node": "^26.3.0",
+    "@types/react": "~18.3.31",
+    "@types/react-dom": "~18.3.7",
+    "micromatch": "^4.0.8",
+    "minimatch": "^10.2.6",
+    "motion": "^13.1.1",
+    "oxfmt": "^0.64.0",
+    "oxlint": "^1.80.0",
+    "picomatch": "^4.0.7",
+    "pkg-pr-new": "^0.0.88",
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1",
+    "typescript": "^7.0.2"
+  },
+  "peerDependenciesMeta": {
+    "@deepseek-ai/dsh-host-webserver": {
+      "optional": true
+    },
+    "@deepseek-ai/dsh-skill": {
+      "optional": true
+    }
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/CNSeniorious000/dsh-generative-ui.git"
+  },
+  "homepage": "https://github.com/CNSeniorious000/dsh-generative-ui#readme",
+  "bugs": "https://github.com/CNSeniorious000/dsh-generative-ui/issues"
+}

package/src/client/canvas/CanvasLauncher.tsx

@@ -0,0 +1,52 @@
+/**
+ * The way back after closing the panel.
+ *
+ * Closing a canvas hides it without deleting anything, and a canvas outlives the session
+ * that wrote it, so without an entry point the work is stranded: the file is still on
+ * disk, but nothing on screen reaches it and the only recovery is making the model write
+ * it again.
+ */
+import { useDismissable } from "./useDismissable.ts";
+
+export type CanvasLauncherProps = {
+  /** Every canvas in the workspace, including ones this session never wrote. */
+  ids: readonly string[];
+  onOpen: (id: string) => void;
+};
+
+export function CanvasLauncher({ ids, onOpen }: CanvasLauncherProps) {
+  const { open, setOpen, anchor } = useDismissable();
+  // One canvas needs no menu — the button is the canvas.
+  const single = ids.length === 1 ? ids[0] : undefined;
+  const label = single === undefined ? `打开画布（${ids.length}）` : `打开画布 ${single}`;
+
+  return (
+    <div className="dgu-launcher-dock" ref={anchor}>
+      {open && single === undefined && (
+        <ul className="dgu-launcher-menu">
+          {ids.map((id) => (
+            <li key={id}>
+              <button
+                type="button"
+                className="dgu-launcher-item"
+                onClick={() => {
+                  setOpen(false);
+                  onOpen(id);
+                }}
+              >
+                {id}
+              </button>
+            </li>
+          ))}
+        </ul>
+      )}
+      <button type="button" className="dgu-launcher" aria-label={label} title={label} aria-expanded={single === undefined ? open : undefined} onClick={() => (single === undefined ? setOpen(!open) : onOpen(single))}>
+        <svg width="14" height="14" viewBox="0 0 14 14" fill="none" aria-hidden="true">
+          <rect x="1.75" y="2.25" width="10.5" height="9.5" rx="1.75" stroke="currentColor" strokeWidth="1.3" />
+          <path d="M8.5 2.5v9" stroke="currentColor" strokeWidth="1.3" />
+        </svg>
+        {ids.length > 1 && <span className="dgu-launcher-count">{ids.length}</span>}
+      </button>
+    </div>
+  );
+}

package/src/client/canvas/CanvasPanel.tsx

@@ -0,0 +1,238 @@
+/**
+ * The canvas column: one mini app per `ui4a/canvases/<id>.ui4a.tsx`, rendered beside the
+ * conversation rather than inside it.
+ *
+ * Composed rather than configured — the panel owns chrome and selection, `GenUISurface`
+ * owns rendering, and the caller owns where canvases come from. That is what lets the
+ * same surface back both this and the inline cards.
+ */
+import { useEffect, useRef, useState } from "react";
+import { compiler, GenUISurface } from "../runtime/GenUISurface.tsx";
+import { canvasPath } from "../../contract.ts";
+import { readCanvasChild } from "./read.ts";
+import { importsSibling, inlineSubPages } from "./subpages.ts";
+import { useDismissable } from "./useDismissable.ts";
+
+export type Canvas = { id: string; code: string; streaming: boolean };
+
+export type CanvasPanelProps = {
+  canvases: readonly Canvas[];
+  /** Every canvas in the workspace, so the header can reach ones this session never wrote. */
+  offerable: readonly string[];
+  /** The session's workspace, needed to fetch a canvas's sub-page files. */
+  cwd: string | undefined;
+  onOpen: (id: string) => void;
+  onClose: () => void;
+  /** Reports the panel's width so the host frame can reserve matching space. */
+  onWidth: (width: number) => void;
+  /** A canvas that failed to compile; see `runtime/report-error.ts`. */
+  onCardError?: (message: string, phase: string) => void;
+  /** A canvas that painted; see `runtime/report-error.ts`. */
+  onCardRendered?: () => void;
+};
+
+/**
+ * Rewrites a canvas's relative sub-page imports into blob URLs before it is compiled.
+ *
+ * Only for a settled canvas: mid-stream the sibling files are usually not written yet, and a
+ * canvas does not stream under the default PTC mode anyway (see CLAUDE.md §3.6). Until the
+ * rewrite lands the original source is rendered, which fails exactly as it does today rather
+ * than blanking a canvas that was working.
+ */
+export function useSubPages(cwd: string | undefined, canvas: Canvas | undefined) {
+  const [resolved, setResolved] = useState<{ key: string; code: string } | null>(null);
+  // Destructured so the effect depends on scalars: the store rebuilds `canvas` on every sweep,
+  // and depending on the object would re-run the whole resolve for an unchanged canvas.
+  const id = canvas?.id;
+  const code = canvas?.code;
+  const streaming = canvas?.streaming;
+
+  useEffect(() => {
+    if (cwd === undefined || id === undefined || code === undefined) return;
+    if (!needsResolve(code, streaming)) return;
+    const key = `${id}:${code.length}`;
+    let live = true;
+    const urls: string[] = [];
+    const compile = async (filename: string, source: string) => (await compiler().compile(source, { filename })).code;
+    void inlineSubPages(code, canvasPath(id), (specifier, from) => readCanvasChild(cwd, id, specifier, from), compile, urls).then((next) => {
+      // Resolved after teardown: nobody will ever render these, so revoke them here — the
+      // disposer already ran and cannot see urls the pass appended after it.
+      if (!live) return void revokeAll(urls);
+      setResolved({ key, code: next });
+    });
+    return () => {
+      live = false;
+      // The surface holds the previous code, so its blobs stay reachable until it re-renders;
+      // revoking on the next resolve rather than here would leak one set per edit.
+      revokeAll(urls);
+    };
+  }, [cwd, id, code, streaming]);
+
+  if (id === undefined || code === undefined) return "";
+  return resolved !== null && resolved.key === `${id}:${code.length}` ? resolved.code : code;
+}
+
+/**
+ * Revoke every blob URL in a list, exactly once each.
+ *
+ * Both callers hand it the SAME array — the disposer, and the resolve that lands after it. The
+ * array is filled by `inlineSubPages` as it goes, so the two can see different lengths, and a
+ * URL revoked twice is harmless while one revoked never is a leak per edit. Emptying the list
+ * as it goes makes the pair idempotent regardless of which runs first or what arrived between.
+ */
+/**
+ * Whether this canvas needs the sub-page pass at all. Extracted from the effect because the
+ * mutation audit could not constrain it there — flipping `streaming` or dropping the
+ * `importsSibling` check survived every test, and both are load-bearing: resolving mid-stream
+ * inlines a prefix that the next frame supersedes, and a canvas with no sibling imports would
+ * pay a compile per frame to produce the code it already had.
+ *
+ * The `undefined` checks stay in the effect: a type predicate narrows only one parameter, and
+ * moving them here would cost the compiler its knowledge that `cwd` and `id` are strings after.
+ */
+export const needsResolve = (code: string, streaming: boolean | undefined): boolean => !streaming && importsSibling(code);
+
+export const revokeAll = (urls: string[]): void => {
+  while (urls.length > 0) URL.revokeObjectURL(urls.pop()!);
+};
+
+/** Cheap gate: only a canvas that actually writes a relative import pays for the pass. */
+const MIN_WIDTH = 320;
+const MAX_WIDTH = 720;
+/** Exported for `test/panel-css.test.ts`: the default must be draggable-to. */
+export { MIN_WIDTH as MIN_WIDTH_FOR_TEST, MAX_WIDTH as MAX_WIDTH_FOR_TEST };
+/**
+ * Must equal the `--dgu-panel-width` fallback in `panel.css`.
+ *
+ * The CSS default is what the panel is painted at before React's inline style lands; this is
+ * what the resize state starts from. Different values mean the panel visibly jumps on its first
+ * frame — a `panel-css.test.ts` assertion holds them together, since a stylesheet cannot import
+ * a constant.
+ */
+export const DEFAULT_WIDTH = 420;
+
+/**
+ * The panel's width for a pointer at `clientX`, clamped to what is usable.
+ *
+ * Extracted from the drag handler because it is the whole of the arithmetic and none of the
+ * DOM: a swapped bound or a flipped subtraction gives a panel that snaps shut or eats the
+ * conversation, and the drag itself cannot be exercised without a browser.
+ */
+/**
+ * Which canvas the panel shows, and which ids the "other canvases" menu offers.
+ *
+ * Both are pure functions of the props and both decide what the reader is looking at, so they
+ * are here rather than inline: the fallback is what covers a selected canvas disappearing
+ * mid-stream (no cleanup needed — clearing the state as well would be a second render saying
+ * the same thing), and `offerable` minus the tabs is what keeps the menu from listing what is
+ * already on screen.
+ */
+export const activeCanvas = (canvases: readonly Canvas[], activeId: string | null) => canvases.find((canvas) => canvas.id === activeId) ?? canvases[canvases.length - 1];
+
+export const otherCanvases = (canvases: readonly Canvas[], offerable: readonly string[]) => offerable.filter((id) => !canvases.some((canvas) => canvas.id === id));
+
+export const widthForPointer = (clientX: number, viewportWidth: number) => Math.min(MAX_WIDTH, Math.max(MIN_WIDTH, viewportWidth - clientX));
+
+/** Drag-to-resize on the panel's left edge, mirroring the host's own invisible hit strip. */
+export function useResize(initial: number) {
+  const [width, setWidth] = useState(initial);
+  const frame = useRef(0);
+  const start = (event: React.PointerEvent<HTMLDivElement>) => {
+    event.currentTarget.setPointerCapture(event.pointerId);
+    event.currentTarget.setAttribute("data-dragging", "");
+    const move = (moveEvent: PointerEvent) => {
+      // One update per frame: pointermove fires far faster than the panel can lay out.
+      if (frame.current !== 0) return;
+      frame.current = requestAnimationFrame(() => {
+        frame.current = 0;
+        setWidth(widthForPointer(moveEvent.clientX, window.innerWidth));
+      });
+    };
+    const stop = () => {
+      window.removeEventListener("pointermove", move);
+      window.removeEventListener("pointerup", stop);
+      document.querySelector("[data-dragging]")?.removeAttribute("data-dragging");
+      if (frame.current !== 0) cancelAnimationFrame(frame.current);
+      frame.current = 0;
+    };
+    window.addEventListener("pointermove", move);
+    window.addEventListener("pointerup", stop);
+  };
+  return { width, start };
+}
+
+export function CanvasPanel({ canvases, offerable, cwd, onOpen, onClose, onWidth, onCardError, onCardRendered }: CanvasPanelProps) {
+  const { width, start } = useResize(DEFAULT_WIDTH);
+  useEffect(() => onWidth(width), [width, onWidth]);
+  const [activeId, setActiveId] = useState<string | null>(null);
+  const { open: picking, setOpen: setPicking, anchor: picker } = useDismissable();
+  // Only what is not already a tab: the tabs cover this session, this covers the rest.
+  const elsewhere = otherCanvases(canvases, offerable);
+
+  // Follow the newest canvas unless the reader has picked one that still exists. A
+  // selection that disappears needs no cleanup: the fallback already covers it, and
+  // clearing the state as well would only be a second render saying the same thing.
+  const active = activeCanvas(canvases, activeId);
+  const resolved = useSubPages(cwd, active);
+
+  return (
+    <div className="dgu-panel" style={{ "--dgu-panel-width": `${width}px` } as React.CSSProperties}>
+      <div className="dgu-resize" onPointerDown={start} style={{ left: 0 }} />
+      <div className="dgu-header">
+        <span className="dgu-title">{active?.id ?? "Canvas"}</span>
+        <span className="dgu-spacer" />
+        {elsewhere.length > 0 && (
+          <div className="dgu-picker" ref={picker}>
+            <button type="button" className="dgu-icon-button" onClick={() => setPicking(!picking)} aria-expanded={picking} aria-label={`其他画布（${elsewhere.length}）`} title={`其他画布（${elsewhere.length}）`}>
+              <svg width="14" height="14" viewBox="0 0 14 14" fill="none" aria-hidden="true">
+                <path d="M3 5.5l4 3.5 4-3.5" stroke="currentColor" strokeWidth="1.4" strokeLinecap="round" strokeLinejoin="round" />
+              </svg>
+            </button>
+            {picking && (
+              <ul className="dgu-launcher-menu dgu-picker-menu">
+                {elsewhere.map((id) => (
+                  <li key={id}>
+                    <button
+                      type="button"
+                      className="dgu-launcher-item"
+                      onClick={() => {
+                        setPicking(false);
+                        setActiveId(id);
+                        onOpen(id);
+                      }}
+                    >
+                      {id}
+                    </button>
+                  </li>
+                ))}
+              </ul>
+            )}
+          </div>
+        )}
+        <button type="button" className="dgu-icon-button" onClick={onClose} aria-label="关闭画布" title="关闭画布">
+          <svg width="14" height="14" viewBox="0 0 14 14" fill="none" aria-hidden="true">
+            <path d="M3 3l8 8M11 3l-8 8" stroke="currentColor" strokeWidth="1.5" strokeLinecap="round" />
+          </svg>
+        </button>
+      </div>
+      {canvases.length > 1 && (
+        <div className="dgu-tabs" role="tablist">
+          {canvases.map((canvas) => (
+            <button key={canvas.id} type="button" role="tab" className="dgu-tab" aria-selected={canvas.id === active?.id} onClick={() => setActiveId(canvas.id)}>
+              {canvas.id}
+            </button>
+          ))}
+        </div>
+      )}
+      <div className="dgu-body">
+        {active === undefined ? (
+          <div className="dgu-empty">写入 ui4a/canvases/&lt;id&gt;.ui4a.tsx 后，画布会出现在这里</div>
+        ) : (
+          // A canvas arrives as whole files, so recompiles replace rather than extend —
+          // preserving state would make an edited canvas silently keep the old render.
+          <GenUISurface key={active.id} code={resolved} streaming={active.streaming} preserveState={false} onError={(error, phase) => onCardError?.(error.message, phase)} onRendered={onCardRendered} />
+        )}
+      </div>
+    </div>
+  );
+}

package/src/client/canvas/collect.ts

@@ -0,0 +1,188 @@
+/**
+ * Finds canvases in the transcript's tool calls.
+ *
+ * The model writes `ui4a/canvases/<id>.ui4a.tsx` with the host's ordinary file tools — no
+ * bespoke tool, no new session event, nothing for the node half to do. `argsRaw` grows
+ * token by token while the call streams, which is what makes a canvas render as it is
+ * written (the same "streaming from tool arguments" contract as ui4a-playground).
+ *
+ * Parsing has to survive half a JSON object. Rather than depend on a partial-JSON parser
+ * for two fields, the two we need are pulled out directly: the path decides whether this
+ * is a canvas at all, and the content is a JSON string literal we can decode up to
+ * wherever the stream currently ends.
+ */
+import { owningCanvasIdOf } from "../../contract.ts";
+import type { Canvas } from "./CanvasPanel.tsx";
+
+/**
+ * A call is classified by the SHAPE of its arguments, never by the tool's name.
+ *
+ * Enumerating names would mean a canvas silently stops rendering the day the host adds or
+ * renames a file tool — no error, no stale marker, just an invisible no-op. What actually
+ * matters is answerable from the arguments alone: does this call name a canvas path, and
+ * does it carry the whole file or only a patch of it.
+ */
+const PATH_KEYS = ["path", "file_path", "filename", "file", "target_file"];
+
+/**
+ * Keys that carry a whole file body.
+ *
+ * Deliberately excludes the patch-shaped keys (`old_str`/`new_str`, `old_string`/
+ * `new_string`, `diff`, `patch`): a call carrying one of those changes the canvas without
+ * describing it, so the file on disk becomes the only correct source. `str_replace_editor`
+ * is exactly this case — its `new_str` is the replacement snippet, not the file, and
+ * treating it as a body replaces the whole canvas with a few lines.
+ */
+const CONTENT_KEYS = ["content", "contents", "text", "file_text"];
+
+/**
+ * Keys that mean "this call changed the file without saying what it now contains".
+ *
+ * The counterpart to CONTENT_KEYS, and the thing that separates an edit from a read: both
+ * name a canvas path and neither carries a body, so without this a plain `read` would mark
+ * the canvas stale and — for a canvas this session never wrote — open a panel the user
+ * never asked for, just for looking at the file.
+ */
+const PATCH_KEYS = ["old_str", "new_str", "old_string", "new_string", "diff", "patch", "edits", "replacements"];
+
+const ESCAPES: Record<string, string> = { n: "\n", t: "\t", r: "\r", b: "\b", f: "\f" };
+
+/**
+ * The value of whichever key appears EARLIEST in the arguments, from complete JSON or a
+ * truncated prefix of it.
+ *
+ * Earliest position rather than first-in-`keys`: a file body routinely contains the
+ * literal text of another candidate key (a canvas that renders the word `"content"`, say),
+ * and scanning key by key would find that occurrence inside the body and decode the rest
+ * of the body as if it were the value — silently rendering a fragment as the whole canvas.
+ * The real key can only precede its own value, so the leftmost hit is the right one.
+ */
+function readString(argsRaw: string, keys: readonly string[]): string | undefined {
+  let at = -1;
+  let key: string | undefined;
+  for (const candidate of keys) {
+    const found = argsRaw.indexOf(`"${candidate}"`);
+    if (found !== -1 && (at === -1 || found < at)) {
+      at = found;
+      key = candidate;
+    }
+  }
+  if (key === undefined) return undefined;
+  const colon = argsRaw.indexOf(":", at + key.length + 2);
+  if (colon === -1) return undefined;
+  const quote = argsRaw.indexOf('"', colon + 1);
+  if (quote === -1) return undefined;
+  // Walk the string literal by hand: it may simply stop mid-escape while streaming.
+  let out = "";
+  for (let i = quote + 1; i < argsRaw.length; i += 1) {
+    const char = argsRaw[i];
+    if (char === "\\") {
+      const escape = argsRaw[i + 1];
+      if (escape === undefined) return out;
+      if (escape === "u") {
+        const hex = argsRaw.slice(i + 2, i + 6);
+        // A \u escape cut in half by the stream carries no character yet; the next frame has it.
+        if (hex.length < 4) return out;
+        out += String.fromCharCode(Number.parseInt(hex, 16) || 0);
+        i += 5;
+        continue;
+      }
+      out += ESCAPES[escape] ?? escape;
+      i += 1;
+      continue;
+    }
+    if (char === '"') return out;
+    out += char;
+  }
+  return out;
+}
+
+export type ToolCallView = { name: string; argsRaw: string; settled: boolean };
+
+/**
+ * One call in the tree a `tool-call` node owns.
+ *
+ * A running call carries its arguments inline; a settled one wraps them in `call`. Either
+ * may own `subCalls` — `run_code` dispatches the file tools as children, so a canvas
+ * written from inside a code block is nested rather than top-level.
+ */
+export type CallBlock = {
+  kind?: string;
+  name?: string;
+  argsRaw?: string;
+  call?: { name?: string; argsRaw?: string };
+  subCalls?: readonly CallBlock[];
+};
+
+/** The call's own identity, ignoring its children. */
+function viewOf(block: CallBlock): ToolCallView | null {
+  const name = block.call?.name ?? block.name;
+  const argsRaw = block.call?.argsRaw ?? block.argsRaw;
+  if (name === undefined || argsRaw === undefined) return null;
+  // `tool-result` is the settled shape; anything else is still running.
+  return { name, argsRaw, settled: block.kind === "tool-result" };
+}
+
+/**
+ * Every call a `tool-call` node contains, parents before children.
+ *
+ * Flattening rather than reading only the root is what lets a canvas written through
+ * `run_code` (or any other dispatching tool) be found: the write is a sub-call, and the
+ * root's own arguments are the code that ran, not the file.
+ */
+export function toolCallsOf(data: unknown): ToolCallView[] {
+  const root = (data as { root?: CallBlock } | undefined)?.root;
+  if (root === undefined) return [];
+  const found: ToolCallView[] = [];
+  const walk = (block: CallBlock) => {
+    const view = viewOf(block);
+    if (view !== null) found.push(view);
+    for (const child of block.subCalls ?? []) walk(child);
+  };
+  walk(root);
+  return found;
+}
+
+/**
+ * Latest canvas per id, in first-seen order.
+ * @param calls - every tool call in the transcript, oldest first.
+ */
+export type CollectedCanvases = {
+  canvases: Canvas[];
+  /**
+   * Canvases whose newest change was a patch, mapped to how many patches they have seen.
+   * The count is a cache version: the caller re-reads the file when it changes, and
+   * reuses what it already has when it does not.
+   */
+  stale: Map<string, number>;
+};
+
+export function collectCanvases(calls: readonly ToolCallView[]): CollectedCanvases {
+  const byId = new Map<string, Canvas>();
+  const stale = new Map<string, number>();
+  for (const call of calls) {
+    // Reads name a canvas too; only a call that writes one is interesting.
+    const path = readString(call.argsRaw, PATH_KEYS);
+    if (path === undefined) continue;
+    const id = owningCanvasIdOf(path);
+    if (id === null) continue;
+    const code = readString(call.argsRaw, CONTENT_KEYS);
+    const isWrite = code !== undefined && code !== "";
+
+    if (!isWrite) {
+      // A patch changed the file without describing it, so the body on disk is now the only
+      // correct source. A call with neither a body nor a patch only read it — leave it alone.
+      const patches = PATCH_KEYS.some((key) => call.argsRaw.includes(`"${key}"`));
+      if (patches && call.settled) stale.set(id, (stale.get(id) ?? 0) + 1);
+      continue;
+    }
+    // A later write to the same id replaces the earlier one; insertion order is kept.
+    byId.delete(id);
+    byId.set(id, { id, code, streaming: !call.settled });
+    // A whole-file write supersedes every patch before it.
+    stale.delete(id);
+  }
+  // An edit to a canvas never written in this session still deserves a panel.
+  for (const id of stale.keys()) if (!byId.has(id)) byId.set(id, { id, code: "", streaming: false });
+  return { canvases: [...byId.values()], stale };
+}