dsh-generative-ui 0.0.2 → 0.0.3

package/lib/types/card-failure.d.ts

@@ -0,0 +1,88 @@
+/**
+ * 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 declare 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 declare 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 declare const failureText: (failure: CardFailure) => string;
+/**
+ * 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 declare const WAKE_TEXT = "A ui4a card you wrote is not rendering \u2014 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 declare 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 declare class CardFailures {
+    private readonly bySession;
+    /**
+     * 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;
+    clear(session: string): void;
+    /** The context text for one session; empty contributes nothing to the assembly. */
+    text(session: string | undefined): string;
+}

package/lib/types/client/canvas/CanvasPanel.d.ts

@@ -16,7 +16,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;
 };
 /**
  * Rewrites a canvas's relative sub-page imports into blob URLs before it is compiled.

package/lib/types/client/canvas/index.d.ts

@@ -13,7 +13,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;
 };
 /**
  * A call whose arguments carry executable code rather than a file operation.

package/lib/types/client/runtime/GenUISurface.d.ts

@@ -4,29 +4,23 @@ export type GenUISurfaceProps = {
     /** True while `code` is still a prefix, so partial frames get normalized before compiling. */
     streaming?: boolean;
     /**
-     * Keep React state across recompiles. Right for a growing stream, where each frame is
-     * the previous one plus more text. Wrong for a whole-file replacement: the renderer
-     * decides reuse from the hook signature, so a rewrite that keeps the same hooks — an
-     * edited canvas usually does — is silently dropped rather than rendered.
+     * Keep React state across recompiles, by rendering through partial-react's stable slot
+     * wrapper so hooks stay on the same fiber. Off, every recompile renders a freshly
+     * compiled function type, which React remounts — a running timer restarts at zero.
+     *
+     * It does NOT risk dropping an edit: the renderer's two reuse branches only fire in
+     * `push` mode, so a whole-file replacement always renders.
      */
     preserveState?: boolean;
-    /** Real compile diagnostics. Transient streaming frames are filtered out — see TRANSIENT below. */
+    /** Real compile diagnostics. A streaming frame never reaches this — see `errorAction`. */
     onError?: (error: Error, phase: "transform" | "compile" | "render") => void;
     /** Fires whenever a frame actually painted. Use it to clear a previously shown error. */
-    onRendered?: () => void;
+    onRendered?: (restored: boolean) => void;
     className?: string;
 };
 /** Paired with `disposeCompiler`: the shared instance must go with the wasm behind it. */
 export declare const dropSharedCompiler: () => void;
 export declare const compiler: () => import("./compiler.ts").TsxCompiler;
-/**
- * Mid-stream frames legitimately fail: a prefix that has not reached `export default`
- * yet, or a half-written expression. partial-react treats these as transient and keeps
- * the last good frame, so surfacing them would just make the UI flash errors while the
- * model types. Only a failure that survives settling is the caller's business.
- */
-/** Exported for `test/transient.test.ts`: this decides whether the reader sees an error. */
-export declare const TRANSIENT: RegExp;
 /**
  * A dependency that failed to arrive, not code that is wrong. esm.sh cold-starts and the
  * network drops, and the symptom is identical to a broken component — a blank surface — so
@@ -41,15 +35,6 @@ export declare const TRANSIENT_LOAD: RegExp;
  * each of which sends the reader somewhere different when it is wrong. Exported for
  * `test/retry.test.ts`.
  */
-/**
- * Whether a mid-stream error is the stream not being finished yet.
- *
- * Both patterns come from the parse stages — `No default export found` is thrown inside
- * `importCompiledComponent` (compile), and an unexpected EOF is the transform rejecting a
- * prefix. A card whose own render throws a message that happens to match is a real error, so
- * the phase is part of the question rather than the message alone.
- */
-export declare const isUnfinishedFrame: (message: string, phase: string, streaming: boolean) => boolean;
 export declare const shouldRetry: (message: string, phase: string, streaming: boolean, attempts: number) => boolean;
 /**
  * What to do with a frame, given what the surface already holds.
@@ -95,6 +80,20 @@ export declare const deliver: (renderer: RendererCalls, delivery: Delivery) => b
  * code to get wrong than the re-probe costs.
  */
 export declare const importSignature: (code: string) => string;
+/**
+ * Whether a failure suppressed during streaming still has to be told to someone.
+ *
+ * The hole this closes: `errorAction` ignores every streaming frame (a truncated one is not a
+ * broken card), and `deliveryFor` answers `nothing` when the settled frame is byte-identical to
+ * the last streamed one. Both are right on their own, and together they mean a card that really
+ * is broken recompiles never and reports never.
+ *
+ * Pure, and exported, because it is three conditions and each one is a distinct bug when wrong:
+ * without `!streaming` it fires mid-stream and undoes the fix it belongs to; without `stranded`
+ * it reports nothing; without the `reportedFor` guard a settled card re-rendered by every later
+ * frame of the transcript reports on each one.
+ */
+export declare const reportStranded: (streaming: boolean, stranded: unknown, code: string, reportedFor: string) => boolean;
 /** Only what `deliver` touches — the real renderer has far more. */
 export type RendererCalls = {
     render: (code: string) => void;
@@ -110,12 +109,15 @@ export type RendererCalls = {
  * - `retry`   a dependency failed to arrive, and busting the import URLs is the fix
  * - `report`  tell the reader
  *
- * Only a SETTLED surface retries: while streaming, the next frame re-delivers on its own, and a
- * retry there would replace the growing buffer with a stale prefix. Compile phase only — a failed
- * dependency import is reported there (`importCompiledComponent` runs inside the compile `catch`,
- * `partial-react/src/runtime.ts:338`), whereas the same message from the RENDER phase is the
- * card's own `fetch` throwing inside its body, where re-importing changes nothing and costs three
- * retries and 2.4 seconds of blank surface before the reader is told anything.
+ * **A streaming frame is never reported, whatever it says.** This used to test the message
+ * against `TRANSIENT` (`No default export found`, unexpected EOF) and report anything else, on
+ * the theory that a truncated frame fails to parse. It does not have to: a cut that lands
+ * mid-identifier leaves valid syntax and throws at module evaluation instead. Measured on one
+ * real session — five consecutive reports, five regenerations, and every final card was fine:
+ * `Mouse is not defined` from a card whose only such name is `MousePointer2`, `type is not
+ * defined` from `type ToolGroup =`, and `icon is not defined` from a card containing no `icon` at
+ * all. The frame, not the card, was broken. There is no message that distinguishes the two, so
+ * the phase does it: only a settled surface has anything worth saying about.
  */
 export declare const errorAction: (message: string, phase: string, streaming: boolean, attempts: number) => "ignore" | "retry" | "report";
 /**
@@ -133,15 +135,26 @@ export declare const errorAction: (message: string, phase: string, streaming: bo
  *
  * - **stale** — a later frame's probe won the race. Applying this one reverts the map to an
  *   older import set, and the newer frame's packages go missing.
- * - **redeliver** — a settled surface has no next frame. `setImportMap` only stores; it
- *   schedules nothing, so without a re-render the card stays blank for good.
- * - **store** — while streaming, the very next frame applies the map. Re-delivering here instead
- *   would replace the buffer with whatever prefix was current when the probe fired, truncating
- *   the stream mid-flight.
+ * - **redeliver** — nothing else is going to apply the map. Always true of a settled surface,
+ *   and true while streaming too when no frame has been delivered since the probe fired:
+ *   `setImportMap` only stores, so that buffer stays compiled against a map without these
+ *   entries — and an unresolvable bare specifier kills the whole module graph, so the card is
+ *   blank rather than wrong. Measured 2026-08-27 on a card importing `@radix-ui/react-tabs`:
+ *   one delivery with `streaming: true` renders 0 characters **for good**, while the identical
+ *   code with `streaming: false` renders. The error is swallowed on top of it — `errorAction`
+ *   answers `ignore` while streaming, so the reader gets an empty card and the model gets no
+ *   report. A cold probe is 1.0s and the import behind it another 2.4s, so the window this
+ *   covers is seconds wide, not a frame.
+ * - **store** — a newer frame has already been delivered, and it will apply the map itself.
+ *   Re-delivering here instead would replace the buffer with the prefix that was current when
+ *   the probe fired, truncating the stream mid-flight.
+ *
+ * `redeliver` renders `deliveredRef.current`, which is read at SETTLE time — the newest buffer,
+ * not the captured one — so the append the next frame computes still lines up.
  *
  * The `delivered !== ""` part is not defensive: re-rendering an empty buffer clears the surface.
  */
-export declare const probeOutcome: (signature: string, current: string, streaming: boolean, delivered: string) => "stale" | "redeliver" | "store";
+export declare const probeOutcome: (signature: string, current: string, streaming: boolean, delivered: string, probed: string) => "stale" | "redeliver" | "store";
 export declare const dispatchError: (action: "ignore" | "retry" | "report", effects: {
     attempts: () => number;
     setAttempts: (n: number) => void;
@@ -155,5 +168,22 @@ export declare const dispatchError: (action: "ignore" | "retry" | "report", effe
  * fresh, and appending a query to a `blob:` URL makes it unresolvable — which would break every
  * card rather than fixing one.
  */
+/**
+ * The same import map with `bundle`/`external` dropped from every esm.sh entry.
+ *
+ * esm.sh serves two different builds and only one of them can fail: `?bundle` runs esbuild over
+ * the package's whole tree, and a version skew anywhere in it is a hard 500. Measured on
+ * `mermaid`, three attempts, deterministic — `?bundle&target=es2022&external=react,react-dom,scheduler`
+ * answers **500 `esbuild: No matching export in "node_modules/d3/src/index.js" for import
+ * "curveBumpX"`**, while the plain `https://esm.sh/mermaid?target=es2022` answers 200 and the
+ * module imports fine. The card meanwhile renders **completely blank with nothing in the
+ * console**, because an unresolvable import kills the whole module graph.
+ *
+ * So the retry that only busts the query re-requests the same broken build. Unbundling is a
+ * genuinely different artefact on esm.sh's side, which is what makes it a second chance rather
+ * than a second identical failure. It is not the first choice — the bundled build is one request
+ * instead of a waterfall — which is why this is on the retry path and not on the happy one.
+ */
+export declare const unbundleFetchedImports: (imports: Record<string, string>) => Record<string, string>;
 export declare const bustFetchedImports: (imports: Record<string, string>, attempt: number) => Record<string, string>;
 export declare function GenUISurface({ code, streaming, preserveState, onError, onRendered, className }: GenUISurfaceProps): import("react").JSX.Element;

package/lib/types/client/runtime/inline-fence.d.ts

@@ -1,5 +1,5 @@
 import type { ReactElement } from "react";
-import type { Ui4aSegment } from "./segments.ts";
+import { type Ui4aSegment } from "./segments.ts";
 /** Split out from `hasPainted` so the rule can be tested without a DOM. */
 export declare const isPaintedText: (text: string) => boolean;
 export declare const hasPainted: (mount: HTMLElement) => boolean;
@@ -14,10 +14,37 @@ export declare const matchSegment: (segments: readonly Ui4aSegment[], rendered:
 export type InlineFenceOptions = {
     /** Every ui4a segment currently in the transcript, in document order. */
     segments: () => readonly Ui4aSegment[];
+    /** `last` answers whether this card is still the transcript's newest — asked at report time, not render time. */
     render: (props: {
         code: string;
         streaming: boolean;
+        last: () => boolean;
     }) => ReactElement;
     scope?: HTMLElement;
 };
+/**
+ * Whether this card's code is the last ui4a segment in the transcript.
+ *
+ * **Only the last block's failure is worth telling the model about.** An earlier card that cannot
+ * render stays in the transcript and re-renders on every later frame, so it fails again, and
+ * again, for the rest of the session — measured on a real one where the model wrote a card
+ * importing `Github` from `lucide-react` (removed upstream), was told, fixed it to `GitBranch` in
+ * the very next reply, and the failure notice kept coming back from the reply it had already
+ * superseded. The model cannot act on it: editing a message it already sent is not a thing it
+ * can do.
+ *
+ * Evaluated when the report is about to be SENT, not when the error is raised. A card is the last
+ * one at the moment it breaks and stops being so as soon as the next card appears, which is
+ * exactly the second in between.
+ *
+ * **Segments, not mounts.** Comparing DOM nodes was wrong three separate ways, all of them
+ * silent: `release` calls `claim.mount.remove()` on every markdown re-render, so a broken card
+ * followed by any trailing prose compared a detached node and dropped its own report; `defer`
+ * parks a far-offscreen block without ever creating a mount, so a reader scrolled up while the fix
+ * streams left an older card holding the last mount and reporting as though it were newest; and an
+ * empty node list has to mean false, since a session switch inside the settle window empties it
+ * while `sendToModel` reads `currentSession()` at send time — session A's error into session B's
+ * store. The segment list is the transcript's own order and survives all three.
+ */
+export declare const isLastSegment: (segments: readonly Ui4aSegment[], code: string) => boolean;
 export declare function claimInlineFences({ segments, render, scope }: InlineFenceOptions): () => void;

package/lib/types/client/runtime/report-error.d.ts

@@ -1,17 +1,64 @@
+/**
+ * Sends a card's compile error back to the model as a chat message.
+ *
+ * Until this existed, `onError` had no consumer at all: a card that failed to compile painted a
+ * red panel for the reader and the model never learned anything. Measured on a real session —
+ * a card imported `MonacoEditor` from `modern-monaco`, the surface reported *"has no export named
+ * 'MonacoEditor'; module exports: Workspace, errors, hydrate, init, lazy"*, and the transcript
+ * ends there: `MonacoEditor` appears 6 times in the records after that point and `no export named`
+ * zero. The reader saw the answer on screen; the one party who could act on it did not.
+ *
+ * Four constraints, each of which this got wrong in an obvious first version:
+ *
+ * - **Only errors that survived.** `GenUISurface` already separates a mid-stream prefix failure
+ *   and a retryable network blip from a real one — the `report` branch of its error action. That
+ *   branch is the only caller, so a half-written expression never reaches the model.
+ *
+ *   It is not sufficient on its own, though. `isUnfinishedFrame` excludes the RENDER phase by
+ *   design — a card whose own render throws is usually a real error — but a half-written
+ *   component rendering mid-stream throws too, and the next frame is fine. Measured in a browser:
+ *   a card that ultimately rendered correctly reported `Cannot read properties of undefined
+ *   (reading 'getCurrentStack')`, a React internal, to the model. Painting a red panel for a
+ *   frame costs nothing; sending the model a message about a card that then worked costs it a
+ *   turn spent fixing what is not broken. So the send is DEFERRED, and a paint cancels it.
+ * - **Once per card, not once per frame.** A settled card that fails re-renders on every later
+ *   frame of the transcript, and a turn per render is a loop the user has to kill. Deduplication
+ *   lives HOST-side now (`CardFailures.set`), because this half is thrown away by every
+ *   navigation and a dedup set that resets on reload wakes the model about a card it already
+ *   knows. What stays here is the settling, which is about frames, not about turns.
+ * - **Recovery is reported too.** The report is state, not an event: a card that starts working
+ *   sends `null`, and the host drops it out of the model's context. As a chat message that was
+ *   impossible, which is why the old body had to carry a paragraph explaining that nobody had
+ *   typed it.
+ * - **Only the newest card counts.** An earlier card that cannot render stays in the transcript
+ *   and re-renders on every later frame, so it goes on failing for the rest of the session.
+ *   Measured on a real one: the model wrote a card importing `Github` from `lucide-react`
+ *   (removed upstream), was told, fixed it to `GitBranch` in its very next reply — and the
+ *   failure notice kept coming back from the message it had already superseded. There is nothing
+ *   the model can do with that; it cannot edit a reply it has sent. `isLastSegment` is the gate, on both the report and the retraction.
+ */
 /** Exported for the test: a fresh card in a fresh session should be able to report again. */
 export declare const forgetReportedErrors: () => void;
-export type ErrorReporter = (text: string) => void;
+/** `null` means the card recovered. */
+export type ErrorReporter = (report: {
+    message: string;
+    phase: string;
+} | null) => void;
+/** Drop a report the page is going away before it can deliver. NOT a recovery — nothing is fixed. */
+export declare function cancelPendingReport(): void;
 /**
- * The message body. Kept short and factual: it is spent from the user's context window, and the
- * one thing the model needs is what failed and that nobody typed it.
+ * Called when a surface paints. Cancels a report the very next frame made untrue.
  *
- * English, like the prompt and the skill it sits beside. This message is the only text this
- * plugin puts into the conversation, and writing it in Chinese did two things: it read as a
- * different voice from everything else the plugin says, and — because a card must be written in
- * the language the USER wrote in — it pushed the model toward answering a Spanish or French
- * speaker in the wrong language for the rest of the turn.
+ * **`restored` is not a detail.** partial-react answers a render throw by re-mounting the LAST
+ * GOOD component (`runtime.ts:416-419`, whenever `preserve` is on — which is every inline card),
+ * and that re-mount paints, and painting used to cancel the report that the very same throw had
+ * just armed. So the one case the reporting exists for — a card that worked, then broke on an
+ * edit — showed the reader stale content and told the model nothing. A paint only means the card
+ * is fine when it is the NEW code that painted.
+ */
+/**
+ * @param current whether the painting card is the one the gate would let report. Defaults to
+ *   permissive for the canvas path, which shows one card at a time.
  */
-export declare const reportBody: (message: string, phase: string) => string;
-/** Called when a surface paints. Cancels a report the very next frame made untrue. */
-export declare function cardRendered(): void;
-export declare function reportCardError(send: ErrorReporter | undefined, message: string, phase: string): void;
+export declare function cardRendered(restored?: boolean, current?: () => boolean): void;
+export declare function reportCardError(send: ErrorReporter | undefined, message: string, phase: string, current?: () => boolean): void;

package/lib/types/contract-assets.d.ts

@@ -39,3 +39,13 @@ export declare const EXEC_PATH = "/dsh-generative-ui/exec";
  * re-opening from here what the host closed for its own tools is not ours to do.
  */
 export declare const WEB_SEARCH_PATH = "/dsh-generative-ui/web-search";
+/**
+ * A card's surviving failure, reported by the browser half: `?session=<id>`, POST
+ * `{message, phase}` to set it and `{}` to clear it.
+ *
+ * The detail does NOT come back as a chat message. It becomes a runtime-context snapshot
+ * (`ui4a:card-failure`), which is re-evaluated per assembly and superseded by the next one, so a
+ * card that gets fixed stops being mentioned instead of leaving a stale complaint in history. The
+ * route only carries the state; `wakeAgent` is what asks the model to look at it.
+ */
+export declare const CARD_ERROR_PATH = "/dsh-generative-ui/card-error";

package/lib/types/index.d.ts

@@ -11,6 +11,24 @@
 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. */
@@ -20,13 +38,24 @@ export declare const SETTINGS_NAMESPACE: import("@deepseek-ai/dsh-settings").Set
  * `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 off by default and that default is the point. `$dsh/fs` is bounded — it takes a
- * workspace-relative path and runs under the session's sandbox policy, so the worst it reaches is
- * a file the user could have opened anyway. `$dsh/exec` takes an arbitrary command string, and a
- * card is code a MODEL wrote, running in the user's browser, firing on their keystrokes. The
- * sandbox policy still applies, but "whatever the agent's own bash tool may do" is a much larger
- * surface than a path — and the user never approves a card's commands the way they approve the
- * agent's.
+ * `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>;
@@ -253,3 +282,17 @@ type LlmCtx = {
 /** 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-generative-ui",
-  "version": "0.0.2",
+  "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",
@@ -94,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",
@@ -109,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);
+  }
+}