dsh-generative-ui 0.0.1 → 0.0.3

package/lib/types/index.d.ts

@@ -0,0 +1,298 @@
+/**
+ * Host half — serves the @esm.sh/tsx wasm the browser half compiles TSX with.
+ *
+ * The shell's /plugins route hard-codes the `/client.js` and `/client.js.map`
+ * suffixes and 404s everything else, and dsh-host-frontend-static owns the sole
+ * fallback seat (and answers misses with index.html + 200, so dropping the wasm
+ * there would fail as a confusing magic-word error). A plugin-owned webServer
+ * route is the way to ship bytes; dsh-latex-tools serves MathJax the same way.
+ * @module dsh-generative-ui
+ */
+import type { IncomingMessage, ServerResponse } from "node:http";
+import type { Context } from "@deepseek-ai/cordis";
+import z from "@deepseek-ai/schemastery";
+import { CardFailures } from "./card-failure.ts";
+/**
+ * The one field of the assembling agent this plugin reads: its id, which IS the session id.
+ *
+ * Declared here rather than by importing `@deepseek-ai/dsh-agent`, which owns the real
+ * augmentation. That package also augments cordis `Context` with the HOST's `sessions` service,
+ * and the augmentation is global — pulling it in retyped `ctx.sessions` inside `src/client/`,
+ * where the session store is the browser runtime's and has `getSnapshot`/`binding` instead.
+ * Six type errors in files this change does not touch. One optional field is the whole
+ * dependency, so it is cheaper to state it than to import the package that carries it.
+ */
+declare module "@deepseek-ai/dsh-system-prompt" {
+    interface AssembleContext {
+        agent?: {
+            readonly id: string;
+        };
+    }
+}
+export declare const name = "dsh-generative-ui";
+export declare const inject: string[];
+/** The settings section this plugin owns; the key under `dsh-generative-ui:` in settings.yaml. */
+export declare const SETTINGS_NAMESPACE: import("@deepseek-ai/dsh-settings").SettingsNamespace;
+/**
+ * Plugin settings. A schemastery schema, not a TypeScript type: the host validates the
+ * `settings.yaml` section against it and builds the settings UI from it, so a plain interface
+ * would be a switch nobody can find and nobody can check.
+ *
+ * `allowExec` is ON by default, and the trade it makes is worth stating rather than assuming.
+ *
+ * What it is NOT: an escape from the fence. The route resolves `ctx.sandboxPolicy` for the session
+ * and hands it to `ctx.shell`, so a card's command opens nothing the agent's own bash has not
+ * already opened, in a workdir pinned to a live session's workspace, killed after 15s and on the
+ * reader closing the page.
+ *
+ * What it IS: the approval layer does not reach here. `approval.request()` needs an open turn and
+ * an agent, and a card fires on a reader's keystroke long after its turn ended — so the per-command
+ * fence is the sandbox policy alone. Under `workspace-write` a card can therefore delete inside the
+ * workspace with nobody agreeing to it command by command. The prompt answers that where it can
+ * ("observe, never change"; anything destructive belongs in a `sendMessage` the user agrees to),
+ * which is guidance, not a fence.
+ *
+ * Turned on because the capability it gates is the ordinary case, not the exotic one: search
+ * (`fd`, `rg`) that no `$dsh/fs` call expresses, `lint` / `check` / test runs whose output IS the
+ * card, `git log`, and the twenty-`readdir` walks a single `ls -R` replaces. Off, a model reasoning
+ * from a five-capability set writes those as file-by-file loops or does not write the card at all.
+ */
+export declare const Config: z<Schemastery.ObjectS<{
+    allowExec: z<boolean, boolean>;
+}>, Schemastery.ObjectT<{
+    allowExec: z<boolean, boolean>;
+}>>;
+export type Config = ReturnType<typeof Config>;
+export { ASSET_PREFIX, WASM_PATH } from "./contract-assets.ts";
+/**
+ * An absolute path to one of the package's import maps, or undefined when it is not there.
+ *
+ * `existsSync` is the point. `fileURLToPath` only rejects a malformed URL — it happily returns a
+ * path to a file that does not exist, which is what this used to do: installed in a shape where
+ * the package root is not two levels up, the skill was handed a path that resolves to nothing
+ * and told the model to pass it to `-i`. The failure then surfaces as `genui check` reporting
+ * `Cannot find module "$dsh/fs"` on correct code, and the model "fixes" imports that were right.
+ */
+export declare const resolvedMap: (relative: string, importMetaUrl: string) => string | undefined;
+/** Exported for `test/routes.test.ts`: a prefix route that stops checking its pathname serves the whole prefix. */
+export declare function serveAsset(req: IncomingMessage, res: ServerResponse, file: string): Promise<void>;
+/**
+ * Serves one canvas file's current contents, or — with no `id` — the ids of every canvas
+ * in the workspace.
+ *
+ * The client could reconstruct a canvas from `write` tool arguments alone, and does while
+ * a write streams — but a model routinely follows a write with several `edit` calls, whose
+ * arguments carry a patch rather than the file. Reading the file is the only source that
+ * stays correct across every way it can change, including edits made outside the agent.
+ *
+ * Confined to the canvas directory by construction — the id is a path segment and the path
+ * is built from the contract — and to a live session's own workspace by the `cwd` check.
+ *
+ * That check is the security boundary, not a formality. This route answers any page the
+ * user has open: a simple GET triggers no preflight, so without it `?cwd=/anywhere` turns
+ * the plugin into a file-existence oracle for the whole disk. The client only ever sends
+ * the cwd it read off the current session, so matching against live sessions costs nothing.
+ */
+/** Exported for `test/routes.test.ts`: the listing is the launcher's only source of truth and had no test. */
+export declare function serveCanvas(liveWorkspaces: () => ReadonlySet<string>, req: IncomingMessage, res: ServerResponse): Promise<void>;
+/** Context shape for the filesystem route; see the SessionStoreCtx note on why it is local. */
+type FsCtx = {
+    fs: {
+        resolve: (path: string, opts?: {
+            cwd?: string;
+        }) => Promise<FsTargetLike>;
+        readText: (target: FsTargetLike) => Promise<string>;
+        readBytes: (target: FsTargetLike, signal: AbortSignal | undefined, maxBytes: number) => Promise<Uint8Array>;
+        listDir: (target: FsTargetLike) => Promise<{
+            name: string;
+            type?: string;
+            size?: number;
+        }[]>;
+        writeText: (target: FsTargetLike, content: string, expected?: undefined, signal?: AbortSignal, policy?: unknown) => Promise<unknown>;
+    };
+    sandboxPolicy: {
+        resolve: (request?: {
+            session?: unknown;
+        }) => unknown;
+    };
+    sessions: {
+        list: () => readonly {
+            id?: string;
+            header: {
+                cwd?: string;
+            };
+        }[];
+    };
+};
+type FsTargetLike = {
+    targetKey: unknown;
+    displayPath: string;
+};
+/**
+ * Reads, lists, and writes on behalf of a generated card.
+ *
+ * Everything goes through the host's `ctx.fs` carrying the session's own
+ * `ctx.sandboxPolicy`, so **a card may do exactly what the session may do** — under
+ * `read-only` the write is refused by the same fence that refuses the model's, with the
+ * same structured denial. Inventing a narrower boundary here would mean a second policy to
+ * keep in sync with the one the user actually sees in the composer.
+ *
+ * The `cwd` allowlist is still required, for the reason the canvas route documents: any page
+ * the user has open can call this, so without it the workspace is not the workspace.
+ */
+/** Exported for `test/fs-route.test.ts`. */
+export declare function serveFs(ctx: FsCtx, liveWorkspaces: () => ReadonlySet<string>, req: IncomingMessage, res: ServerResponse): Promise<void>;
+/** Context shape for the shell route. `resolve` fills the executor's own defaults and caps. */
+type ExecCtx = {
+    shell: {
+        resolve: (request: {
+            command: string;
+            workdir?: string;
+            timeoutMs?: number;
+            sandboxPolicy?: unknown;
+            signal?: AbortSignal;
+        }) => unknown;
+        run: (spec: unknown) => Promise<{
+            exitCode: number | null;
+            signal?: string | null;
+            timedOut?: boolean;
+            stdout: {
+                text: string;
+                truncated: boolean;
+            };
+            stderr: {
+                text: string;
+                truncated: boolean;
+            };
+        }>;
+    };
+    sandboxPolicy: {
+        resolve: (request?: {
+            session?: unknown;
+        }) => unknown;
+    };
+    sessions: {
+        list: () => readonly {
+            id?: string;
+            header: {
+                cwd?: string;
+            };
+        }[];
+    };
+};
+/**
+ * Runs one command on behalf of a generated card.
+ *
+ * The whole point is that a card can answer questions only a command can answer — git
+ * history, a test run, ripgrep across a big tree — without us re-implementing each one as a
+ * route. It carries the session's own sandbox policy, so this opens no door the model's own
+ * bash tool does not already have open, and a read-only session gets a read-only shell.
+ *
+ * A non-zero exit is a RESULT, not an error: a card wants to show `git status` failing in a
+ * non-repo as much as it wants to show it succeeding. Only infrastructure failures reject.
+ *
+ * **Why this does not go through `ctx.approval`, which is the seam for "may this action
+ * proceed?".** It is the right question and dsh's own `tool-bash` asks it — but the service
+ * cannot answer it here. `approval.request()` takes an `agent` and throws outright when the
+ * session has no open turn: *"approval.request() outside an open turn … Ask from inside the turn
+ * that needs the decision."* A card's command is the opposite of that — it fires on the reader's
+ * keystroke, long after the turn that wrote the card ended, with no agent on whose behalf to ask.
+ * `ctx.userQuestions.ask()` DOES work outside a turn (its `agent` is optional), so a per-command
+ * prompt is buildable; what stops it is that a card runs one command per keystroke, and a dialog
+ * per keystroke is not a safety feature. The setting is therefore about whether the CAPABILITY
+ * exists, and the per-command fence remains the session's own sandbox policy, which this passes
+ * through unchanged. Anything genuinely destructive belongs in `sendMessage`, where the user's
+ * next turn — and with it the whole approval machinery — is what runs it.
+ */
+/** Exported for `test/exec-route.test.ts`. */
+export declare function serveExec(ctx: ExecCtx, liveWorkspaces: () => ReadonlySet<string>, req: IncomingMessage, res: ServerResponse): Promise<void>;
+/** Context shape for the search route. Only the two methods it calls, so a fake in a test is small. */
+type WebCtx = {
+    web: {
+        search: (request: {
+            query: string;
+            maxResults?: number;
+        }, signal?: AbortSignal) => Promise<{
+            content?: string;
+            sources: readonly {
+                url: string;
+                title?: string;
+                snippet?: string;
+                publishedAt?: string;
+            }[];
+            truncated: boolean;
+        }>;
+    };
+};
+/**
+ * Runs one web search on behalf of a generated card.
+ *
+ * A card that wants live information — a price, a release date, what a package exports — otherwise
+ * has nothing: `fetch` from inside the surface is not the shape (no credentials, no CORS, no
+ * provider selection), and routing the question through `$dsh/ai` asks a model to recall rather
+ * than to look. `ctx.web` already owns provider selection, the result shape, and the truncation
+ * bound, so this forwards and does not re-decide any of it.
+ *
+ * SEARCH ONLY — see `WEB_SEARCH_PATH` for why `fetch` is not forwarded.
+ *
+ * `WebError` carries a `code` and the seam's own contract calls that set OPEN: a provider may
+ * raise a code this build has never seen. So the error is passed through as text rather than
+ * matched on, and the card decides what to show.
+ */
+/** Exported for `test/web-search-route.test.ts`. */
+export declare function serveWebSearch(ctx: WebCtx, liveWorkspaces: () => ReadonlySet<string>, req: IncomingMessage, res: ServerResponse): Promise<void>;
+/** Context shape for the two services the AI route needs; see the SessionStoreCtx note. */
+type LlmCtx = {
+    llm: {
+        stream: (options: {
+            provider: string;
+            model: string;
+            messages: readonly unknown[];
+            system?: string;
+            signal?: AbortSignal;
+        }) => AsyncIterable<{
+            type: string;
+            text?: string;
+            reason?: {
+                kind: string;
+                failure?: {
+                    message?: string;
+                };
+            };
+        }>;
+    };
+    agentDefaultModel: {
+        currentSelection: () => {
+            provider: string;
+            model: string;
+        };
+    };
+};
+/**
+ * Streams one model call on behalf of a generated card.
+ *
+ * The card cannot call a provider itself — it has no credentials and should never be given
+ * any. `ctx.llm` already owns the adapter registry, the retry policy and the keys, and
+ * `agentDefaultModel` owns which model the app is set to, so this route is a forwarder:
+ * it converts a small JSON request into `llm.stream` and pipes the text deltas back.
+ *
+ * Same `cwd` allowlist as the canvas route, and for the same reason: any page the user has
+ * open can POST here, so without it this is an open model proxy for anything on the machine.
+ */
+/** Exported for `test/ai-route.test.ts`. */
+export declare function serveAi(ctx: LlmCtx, liveWorkspaces: () => ReadonlySet<string>, req: IncomingMessage, res: ServerResponse): Promise<void>;
+export declare function apply(ctx: Context, config?: Config): void;
+/**
+ * Record or clear one session's failing card, and wake the model when the failure is news.
+ *
+ * `POST ?session=<id>` with `{message, phase}` to set it and `{}` to clear it. The detail never
+ * comes back as a chat message — it becomes the `ui4a:card-failure` runtime context, which the
+ * assembly re-reads each step. See `card-failure.ts` for why the two halves are split.
+ *
+ * The wake is looked up per request rather than captured: the agent registry is scoped, so the
+ * function it hands out can go away while this route stays up, and a stale capture would call
+ * into a disposed fiber.
+ *
+ * Exported for `test/card-error-route.test.ts`.
+ */
+export declare function serveCardError(failures: CardFailures, wake: () => ((session: string) => void) | null, req: IncomingMessage, res: ServerResponse): Promise<void>;

package/lib/types/prompt.d.ts

@@ -0,0 +1,13 @@
+export declare const PROMPT_SECTION_NAME = "dsh-generative-ui:inline";
+/** After tool guidance (100–199): this describes an output format, not the harness identity. */
+export declare const PROMPT_SECTION_ORDER = 210;
+/**
+ * The section, built for the capabilities this host actually exposes.
+ *
+ * `allowExec` is not cosmetic here. The closed-set sentence below ("these are the whole set") is
+ * load-bearing — it is what stops the model reasoning its way to a plausible sixth import — so it
+ * has to name the set that EXISTS. Documenting `$dsh/exec` on a host where the route is not
+ * registered teaches the model to write cards whose import fails, and a failed import takes the
+ * whole module down: the reader gets a blank card with nothing on screen naming the cause.
+ */
+export declare const inlinePrompt: (allowExec?: boolean) => string;

package/lib/types/skill.d.ts

@@ -0,0 +1,27 @@
+export declare const SKILL_NAME = "generative-ui";
+export declare const SKILL_DESCRIPTION = "How to decide between an inline ui4a/tsx block, a canvas file, and plain prose \u2014 and how to lay one out so it reads. Load it **before you decide**, not after \u2014 including when your first instinct is that prose is enough. Most of the questions that should have been an interface do not ask for one.";
+/**
+ * The skill body.
+ *
+ * A function of the import-map path because that path is only known at runtime — the plugin
+ * lives wherever the profile installed it, and the model runs the checker from the workspace.
+ * Without the map, `check` reports `Cannot find module "$dsh/chat"` on every card that uses
+ * one, and a false error is worse than no check: the model goes and "fixes" it.
+ */
+/**
+ * The paragraph about which import map serves which command.
+ *
+ * Built here rather than inline: nesting one template interpolation inside another inside the
+ * body is how this file broke twice, and the two maps have genuinely different lifetimes —
+ * the type one may exist while the stub one does not.
+ */
+/** Exported for `test/skill.test.ts`: three states, and this file has broken on them twice. */
+export declare function mapNotes(typesMap: string | undefined, standaloneMap: string | undefined): string;
+/**
+ * The skill, for the capabilities this host exposes.
+ *
+ * With commands off the whole `## Running a command` section is cut rather than softened: it is
+ * ~90 lines that all assume `bash()` exists, and half a section describing a capability the host
+ * does not have is worse than none — the model reads the surviving half as permission.
+ */
+export declare const skillBody: (typesMap: string | undefined, standaloneMap: string | undefined, allowExec?: boolean) => string;

package/package.json

@@ -1,15 +1,17 @@
 {
   "name": "dsh-generative-ui",
-  "version": "0.0.1",
+  "version": "0.0.3",
   "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"
@@ -51,8 +53,8 @@
     }
   },
   "scripts": {
-    "build": "bun scripts/gen-standalone.ts && bun scripts/build.ts",
-    "prepare": "bun scripts/gen-standalone.ts && bun scripts/build.ts",
+    "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",
@@ -92,6 +94,7 @@
     "react": "^18.2.0"
   },
   "devDependencies": {
+    "@babel/parser": "^8.0.4",
     "@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",
@@ -107,10 +110,11 @@
     "@types/node": "^26.3.0",
     "@types/react": "~18.3.31",
     "@types/react-dom": "~18.3.7",
+    "@types/scheduler": "^0.26.0",
     "micromatch": "^4.0.8",
     "minimatch": "^10.2.6",
     "motion": "^13.1.1",
-    "oxfmt": "^0.64.0",
+    "oxfmt": "^0.66.0",
     "oxlint": "^1.80.0",
     "picomatch": "^4.0.7",
     "pkg-pr-new": "^0.0.88",

package/src/card-failure.ts

@@ -0,0 +1,106 @@
+/**
+ * What the model is told about a card that will not render.
+ *
+ * Split in two, deliberately, because the two halves want opposite lifetimes:
+ *
+ * - **The detail is state.** It goes out as a runtime-context snapshot, re-evaluated on every
+ *   assembly and superseded by the next one. A card that gets fixed simply stops being mentioned.
+ *   As a chat message it was the opposite — permanent, and still there three turns after the card
+ *   started working.
+ * - **The nudge is an event.** One short line through `followup`, whose only job is to open a turn
+ *   so the model looks at the detail now rather than whenever the user next types.
+ *
+ * Neither is a user-role message any more, and that removes the paragraph the old body had to
+ * carry: *"This was sent by the renderer, not by the user — nobody typed it, so do not apologise
+ * or address it as a request."* That existed because the report arrived wearing the user's face.
+ * A `kind: "plugin"` source does not, so the model is told what happened and nothing else — the
+ * disclaimer cost more tokens than the error it was wrapped around.
+ */
+
+/** A card failure as the browser half reported it. */
+export type CardFailure = { readonly message: string; readonly phase: string };
+
+/** The runtime-context section name. Stable: it is how a later snapshot supersedes an earlier one. */
+export const CARD_FAILURE_CONTEXT = "ui4a:card-failure";
+
+/**
+ * Ordered after the plugin's own guidance so the model reads how cards work before it reads that
+ * one is broken.
+ */
+export const CARD_FAILURE_CONTEXT_ORDER = 250;
+
+/**
+ * The detail, as the model sees it.
+ *
+ * It says it is current state rather than an event on purpose: the same text is re-delivered on
+ * every step while the card stays broken, and a model that reads it as a fresh report tries to
+ * fix the card again on each one.
+ */
+export const failureText = (failure: CardFailure) =>
+  `A ui4a card in this session is not rendering. It failed at the ${failure.phase} step:\n\n${failure.message}\n\nThis is current state, not a new event — it is re-read every step and disappears once the card renders. If the error names the correct usage (the available exports, for instance), fix the card and send it again. If it does not, look it up before you change anything.`;
+
+/**
+ * The one line that opens a turn. The detail is already in context; this only asks for attention.
+ *
+ * The second sentence is not padding — it closes a race the split design makes possible. The nudge
+ * is an event and cannot be recalled once queued; the detail is state and is re-evaluated when the
+ * turn assembles. A card that recovers in between (a retry succeeding is the common way) clears
+ * the state, so the turn opens with "go read the runtime context" pointing at a context that says
+ * nothing about a card.
+ *
+ * Seen in a real session: two notices, and the SECOND one had no card-failure section anywhere in
+ * the turn that followed it. Without a defined outcome for that, the model has been told something
+ * is broken, cannot find it, and goes looking — in that session it rewrote a card that was fine.
+ */
+export const WAKE_TEXT =
+  "A ui4a card you wrote is not rendering — the failure is in the runtime context. If there is no card failure there, it recovered on its own between this notice and now: say nothing about it and carry on with what you were doing.";
+
+/** Shown as the context row's label in the transcript, so a reader can see what fired without opening it. */
+export const WAKE_SUMMARY = "ui4a card failed to render";
+
+/**
+ * The current failing card per session.
+ *
+ * Per session rather than per card: the nudge exists to get one turn spent on the problem, and a
+ * reply that breaks three cards does not want three turns. The newest failure wins because it is
+ * the one the model just wrote.
+ */
+export class CardFailures {
+  private readonly bySession = new Map<string, CardFailure>();
+
+  /**
+   * Record a failure.
+   *
+   * @returns whether the session went from HEALTHY to failing — the caller wakes the model only
+   * then. Dedup lives here rather than in the browser half because that half is reloaded by every
+   * navigation, and a dedup set that resets on reload wakes the model again for a card it already
+   * knows about.
+   *
+   * **Not "is this a different message".** That was the first version, and it is wrong for a
+   * nudge whose entire payload is *go read the context*: two different failures produce two
+   * BYTE-IDENTICAL notices, so a reader watching a long turn sees the same sentence queued twice
+   * and the model gets two turns pointed at one current-state snapshot. Measured on a real
+   * session — three genuinely different failures (`@react-three/fiber` unresolvable, `maps is not
+   * defined`, `@react-three/cannon` unresolvable) over eighty minutes, each "news" by the old
+   * test, and the third's notice was still sitting unsent in the composer beside the second.
+   *
+   * While a failure is already recorded the model is either about to look or has looked, and the
+   * detail it will read is re-evaluated every step anyway — so a changed message needs no second
+   * nudge. `clear()` on recovery is what re-arms this.
+   */
+  set(session: string, failure: CardFailure): boolean {
+    const wasHealthy = !this.bySession.has(session);
+    this.bySession.set(session, failure);
+    return wasHealthy;
+  }
+
+  clear(session: string): void {
+    this.bySession.delete(session);
+  }
+
+  /** The context text for one session; empty contributes nothing to the assembly. */
+  text(session: string | undefined): string {
+    const failure = session === undefined ? undefined : this.bySession.get(session);
+    return failure === undefined ? "" : failureText(failure);
+  }
+}

package/src/client/canvas/CanvasPanel.tsx

@@ -28,7 +28,7 @@ export type CanvasPanelProps = {
   /** 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;
+  onCardRendered?: (restored: boolean) => void;
 };
 
 /**
@@ -228,9 +228,15 @@ export function CanvasPanel({ canvases, offerable, cwd, onOpen, onClose, onWidth
         {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} />
+          // `preserveState` was false here, on the theory that a whole-file replace could
+          // "silently keep the old render". It cannot: both of partial-react's reuse branches
+          // (`runtime.ts:317` and `:404`) require `updateMode === "push"`, and a canvas arrives
+          // whole, so it always runs in `"render"` — measured, the edit lands either way.
+          // What preserving buys is the state: `:426` calls the generated component from inside
+          // a stable slot wrapper, so its hooks stay on the same fiber across a recompile, and
+          // `:424` keys the error boundary off the hook signature instead of the render round.
+          // Without it every edit remounted the tree and a running timer went back to zero.
+          <GenUISurface key={active.id} code={resolved} streaming={active.streaming} onError={(error, phase) => onCardError?.(error.message, phase)} onRendered={onCardRendered} />
         )}
       </div>
     </div>

package/src/client/canvas/index.ts

@@ -25,7 +25,7 @@ export type CanvasHostOptions = {
    */
   onCardError?: (message: string, phase: string) => void;
   /** A canvas that painted; cancels a deferred error report the next frame made untrue. */
-  onCardRendered?: () => void;
+  onCardRendered?: (restored: boolean) => void;
 };
 
 const EMPTY: ReadonlySet<string> = new Set();

package/src/client/index.ts

@@ -8,7 +8,7 @@ import type { ClientContext } from "@deepseek-ai/dsh-client-runtime/client";
 import type {} from "@deepseek-ai/dsh-client-ui-layout/client";
 import type {} from "@deepseek-ai/dsh-client-ui-conversation/client";
 import { GenUISurface } from "./runtime/GenUISurface.tsx";
-import { cardRendered, reportCardError } from "./runtime/report-error.ts";
+import { cancelPendingReport, cardRendered, reportCardError } from "./runtime/report-error.ts";
 import { disposeCompiler } from "./runtime/compiler.ts";
 import { dropSharedCompiler } from "./runtime/GenUISurface.tsx";
 import { disposeRegistry } from "./runtime/registry.ts";
@@ -20,6 +20,7 @@ import { chatNodes, perNode, type ChatNodeView } from "./session.ts";
 import { mountCanvasHost } from "./canvas/index.ts";
 import { toolCallsOf, type CallBlock, type ToolCallView } from "./canvas/collect.ts";
 import { canvasIdOf } from "../contract.ts";
+import { CARD_ERROR_PATH } from "../contract-assets.ts";
 
 export const inject = ["sessions"];
 
@@ -84,6 +85,11 @@ export function apply(ctx: ClientContext): void {
   // its URL is revoked (the module graph holds it), so this only reclaims URLs nothing can
   // reach any more. Without it every HMR round leaks one per registered specifier.
   ctx.effect(() => disposeRegistry, "dsh-generative-ui: blob module URLs");
+  // An error report waits a second before it is sent (see `SETTLE_MS`), and an unload inside that
+  // second leaves the timer holding a closure over a conversation that is being torn down. There
+  // is nothing to flush — a report nobody will read is not worth delivering — so cancelling is
+  // the whole disposer, and `cardRendered` already is one.
+  ctx.effect(() => () => cancelPendingReport(), "dsh-generative-ui: pending error report");
   // The wasm half of the same problem: ~16MB per instance, one per HMR round, and upstream
   // offers no dispose — dropping the reference is all there is (see `disposeCompiler`).
   ctx.effect(
@@ -129,14 +135,19 @@ export function apply(ctx: ClientContext): void {
   });
   // A card that fails to compile used to be a red panel the reader saw and the model never did.
   // `onError` fires only for a failure that survived settling and retries, so this is the real
-  // ones — see `report-error.ts` for why it is once per message and why it says it is automatic.
-  const sendToModel = (text: string) => {
+  // ones — see `report-error.ts` for why it is once per message and why it waits a beat.
+  //
+  // A route rather than `conversation.send`: the detail belongs in the model's CONTEXT, which is
+  // assembled host-side, and a chat message could never be taken back once the card was fixed.
+  // `card-failure.ts` has the rest.
+  const sendToModel = (report: { message: string; phase: string } | null) => {
     const id = currentSession();
-    const session = id === undefined ? undefined : ctx.sessions.scope(id);
-    if (session === undefined) return;
-    session.inject(["conversation"], (addressed) => {
-      void addressed.conversation.send(text).catch((error: unknown) => console.error("[dsh-generative-ui] card error report failed", error));
-    });
+    if (id === undefined) return;
+    void fetch(`${CARD_ERROR_PATH}?session=${encodeURIComponent(id)}`, {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify(report ?? {}),
+    }).catch((error: unknown) => console.error("[dsh-generative-ui] card error report failed", error));
   };
 
   // Mounted inside the effect, not beside it: `mountCanvasHost` reaches for MutationObserver
@@ -180,7 +191,9 @@ export function apply(ctx: ClientContext): void {
     () =>
       claimInlineFences({
         segments,
-        render: ({ code, streaming }) => createElement(GenUISurface, { code, streaming, onError: (error, phase) => reportCardError(sendToModel, error.message, phase), onRendered: cardRendered }),
+        // The SAME gate on both callbacks. A card that may not report a failure may not retract
+        // one either — see `cardRendered`.
+        render: ({ code, streaming, last }) => createElement(GenUISurface, { code, streaming, onError: (error, phase) => reportCardError(sendToModel, error.message, phase, last), onRendered: (restored) => cardRendered(restored, last) }),
       }),
     "dsh-generative-ui: inline fences",
   );