dsh-generative-ui 0.0.2 → 0.0.4

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

@@ -7,8 +7,9 @@ import { createElement } from "react";
 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 type {} from "@deepseek-ai/dsh-client-locale/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,8 +21,9 @@ 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"];
+export const inject = ["sessions", "locale"];
 
 /** Re-exported so `bun run smoke` can build the synthesized blob modules and parse them. */
 export { localImports };
@@ -84,6 +86,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 +136,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 +192,11 @@ 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 }),
+        t: ctx.locale.bind("common"),
+        subscribeLocale: (refresh) => ctx.locale.subscribe(refresh),
+        // 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",
   );

package/src/client/runtime/GenUISurface.tsx

@@ -16,16 +16,18 @@ 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;
 };
 
@@ -58,15 +60,6 @@ export const compiler = () => {
   return sharedCompiler;
 };
 
-/**
- * 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 const TRANSIENT = /No default export found|Unexpected (end of|eof)/i;
-
 /**
  * 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
@@ -83,16 +76,6 @@ const MAX_RETRIES = 3;
  * 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 const isUnfinishedFrame = (message: string, phase: string, streaming: boolean) => streaming && phase !== "render" && TRANSIENT.test(message);
-
 export const shouldRetry = (message: string, phase: string, streaming: boolean, attempts: number) => phase === "compile" && !streaming && TRANSIENT_LOAD.test(message) && attempts < MAX_RETRIES;
 /**
  * What to do with a frame, given what the surface already holds.
@@ -152,6 +135,21 @@ export const deliver = (renderer: RendererCalls, delivery: Delivery): boolean =>
  */
 export const importSignature = (code: string) => [...code.matchAll(/from\s+["']([^"']+)["']/g)].map((match) => match[1]).join(" ");
 
+/**
+ * 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 const reportStranded = (streaming: boolean, stranded: unknown, code: string, reportedFor: string) => !streaming && stranded !== null && reportedFor !== code;
+
 /** Only what `deliver` touches — the real renderer has far more. */
 export type RendererCalls = {
   render: (code: string) => void;
@@ -166,20 +164,34 @@ 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 const errorAction = (message: string, phase: string, streaming: boolean, attempts: number): "ignore" | "retry" | "report" => {
-  if (isUnfinishedFrame(message, phase, streaming)) return "ignore";
+  if (streaming) return "ignore";
   return shouldRetry(message, phase, streaming, attempts) ? "retry" : "report";
 };
 
-/** 0.4s / 0.8s / 1.2s covers an esm.sh cold start; past that the package itself is the problem. */
-const RETRY_BACKOFF_MS = 400;
+/**
+ * 0.5s / 2s / 8s. **Linear 0.4/0.8/1.2 did not cover a cold start** — it spends 2.4 seconds
+ * total, and a first request for a package esm.sh has never built waits on that build: measured
+ * 2.27s cold against 0.50s warm for the same URL, so all three attempts landed inside one
+ * unfinished build and the reader got `failed to fetch dynamically imported module` on a package
+ * that resolves fine a second later. Seen in a real session on `@headlessui/react`, twice in a
+ * row, on a card the model had been asked to write with it.
+ *
+ * Backing off ×4 spends 10.5s across the same three attempts, which covers a cold build with room
+ * and still gives up fast enough that a genuinely missing package does not hang the card.
+ */
+const RETRY_BACKOFF_MS = 500;
+const RETRY_FACTOR = 4;
 
 /**
  * What `onError` DOES with the three outcomes, separated from where they come from. The decision
@@ -196,17 +208,29 @@ const RETRY_BACKOFF_MS = 400;
  *
  * - **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 const probeOutcome = (signature: string, current: string, streaming: boolean, delivered: string): "stale" | "redeliver" | "store" => {
+export const probeOutcome = (signature: string, current: string, streaming: boolean, delivered: string, probed: string): "stale" | "redeliver" | "store" => {
   if (signature !== current) return "stale";
-  return !streaming && delivered !== "" ? "redeliver" : "store";
+  if (delivered === "") return "store";
+  return !streaming || delivered === probed ? "redeliver" : "store";
 };
 
 export const dispatchError = (action: "ignore" | "retry" | "report", effects: { attempts: () => number; setAttempts: (n: number) => void; schedule: (ms: number) => void; report: () => void }) => {
@@ -214,7 +238,7 @@ export const dispatchError = (action: "ignore" | "retry" | "report", effects: {
   if (action === "retry") {
     const next = effects.attempts() + 1;
     effects.setAttempts(next);
-    effects.schedule(RETRY_BACKOFF_MS * next);
+    effects.schedule(RETRY_BACKOFF_MS * RETRY_FACTOR ** (next - 1));
     return;
   }
   effects.report();
@@ -227,6 +251,56 @@ export const dispatchError = (action: "ignore" | "retry" | "report", effects: {
  * 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 const unbundleFetchedImports = (imports: Record<string, string>): Record<string, string> =>
+  Object.fromEntries(
+    Object.entries(imports).map(([key, url]) => {
+      if (!url.startsWith("https://esm.sh/")) return [key, url];
+      const parsed = new URL(url);
+      parsed.searchParams.delete("bundle");
+      // `external` STAYS. Dropping it was in this function for one day and it broke rendering in a
+      // way far worse than the 500 it was meant to route around. Measured on the real URLs:
+      //
+      //   ?bundle&target=es2022&external=react,react-dom,scheduler -> 500   (the bug being fixed)
+      //   ?target=es2022&external=react,react-dom,scheduler        -> 200   (fixed, react shared)
+      //   ?target=es2022                                           -> 200   (fixed, react NOT shared)
+      //
+      // The 500 comes from `bundle` alone; `external` has nothing to do with it. What `external`
+      // does do is make esm.sh emit a BARE `import … from "react"`, which the document import map
+      // resolves to the host's single instance. Without it the same build emits
+      // `import "/react@^16.5.1 || ^17.0.0 || ^18.0.0 || ^19.0.0?target=es2022"` — an ABSOLUTE URL
+      // an import map keyed on the bare specifier cannot redirect, so the package gets esm.sh's own
+      // React (19, against this host's 18). Elements it creates then carry a `$$typeof` the host
+      // React does not recognise, and the card dies on **`Minified React error #31`, args
+      // `object with keys {$$typeof, type, key, ref, props}`**.
+      //
+      // Seen end to end in one session: a card rendered correctly, a later retry re-fetched its
+      // icons without `external`, every lucide element became a foreign object, and the model was
+      // handed a render-failure notice for a card that had been fine — it rewrote it, blaming
+      // itself for "rendering icons/objects directly".
+      //
+      // `bundle` is a valueless flag, and `URLSearchParams` writes it back as `bundle=` — which
+      // esm.sh reads as the flag being present. Deleting is enough; re-serialising is what would
+      // put it back.
+      return [key, parsed.toString()];
+    }),
+  );
+
 export const bustFetchedImports = (imports: Record<string, string>, attempt: number): Record<string, string> => Object.fromEntries(Object.entries(imports).map(([key, url]) => [key, url.startsWith("https://esm.sh/") ? `${url}${url.includes("?") ? "&" : "?"}ui4a-retry=${attempt}` : url]));
 
 export function GenUISurface({ code, streaming = false, preserveState = true, onError, onRendered, className }: GenUISurfaceProps) {
@@ -238,6 +312,22 @@ export function GenUISurface({ code, streaming = false, preserveState = true, on
   // through refs rather than captured — a new handler identity must not re-attach it.
   const onErrorRef = useLatest(onError);
   const onRenderedRef = useLatest(onRendered);
+  // Set by a RENDER throw, consumed by the paint that follows it — see `onRendered` below.
+  const threwRef = useRef(false);
+  /**
+   * The last failure `errorAction` suppressed because the surface was still streaming.
+   *
+   * Suppressing them is right — a truncated frame is not a broken card — but it leaves a hole at
+   * the other end: when the settled frame is byte-identical to the last streamed one,
+   * `deliveryFor` answers `nothing`, nothing recompiles, and a card that really is broken reports
+   * NOTHING at all. The last streamed frame's failure is the surface's actual state at that
+   * point, so it is what gets reported. Cleared by a real paint, which is the proof it was
+   * transient after all.
+   */
+  const strandedRef = useRef<{ error: Error; phase: "transform" | "compile" | "render" } | null>(null);
+  /** The code a stranded failure was already reported for, so a re-render does not report it again. */
+  const strandedReportedRef = useRef("");
+  const retryTimers = useRef(new Set<ReturnType<typeof setTimeout>>());
   const streamingRef = useLatest(streaming);
   // Read once at attach: the renderer takes it as a construction option.
   const preserveStateRef = useRef(preserveState);
@@ -259,7 +349,10 @@ export function GenUISurface({ code, streaming = false, preserveState = true, on
     const attempt = retriesRef.current;
     void mergeFallbackImports(localImports(), code).then((imports) => {
       // Only the fetched esm.sh entries need busting; the local blob URLs are already fresh.
-      renderer.setImportMap({ imports: bustFetchedImports(imports, attempt) });
+      // From the second attempt the bundled build is dropped as well: if the first failure was a
+      // bundle-side 500 (see `unbundleFetchedImports`) no amount of cache-busting can clear it.
+      const fresh = attempt > 0 ? unbundleFetchedImports(imports) : imports;
+      renderer.setImportMap({ imports: bustFetchedImports(fresh, attempt) });
       renderer.clear({ preserveVisualState: true });
       renderer.render(code);
     });
@@ -276,18 +369,36 @@ export function GenUISurface({ code, streaming = false, preserveState = true, on
       preserveStateOnUpdate: preserveStateRef.current,
       callbacks: {
         onError: (error, phase) => {
-          dispatchError(errorAction(error.message, phase, streamingRef.current, retriesRef.current), {
+          if (phase === "render") threwRef.current = true;
+          const action = errorAction(error.message, phase, streamingRef.current, retriesRef.current);
+          // Remember what was swallowed. Only the newest matters: each frame supersedes the last,
+          // so this is the state of the buffer the stream stopped on.
+          if (action === "ignore") strandedRef.current = { error, phase };
+          dispatchError(action, {
             attempts: () => retriesRef.current,
             setAttempts: (n) => {
               retriesRef.current = n;
             },
-            schedule: (ms) => setTimeout(() => retryRef.current(), ms),
+            // Tracked so the cleanup below can cancel it: a retry is scheduled up to 1.2s out,
+            // and a surface can unmount well inside that (a canvas tab closed, a message scrolled
+            // out of the host's window). Firing after that runs the whole import-probe chain
+            // against a renderer that has already been detached.
+            schedule: (ms) => void retryTimers.current.add(setTimeout(() => retryRef.current(), ms)),
             report: () => onErrorRef.current?.(error, phase),
           });
         },
         onRendered: () => {
           retriesRef.current = 0;
-          onRenderedRef.current?.();
+          // partial-react repaints the LAST GOOD component after a render throw (`preserve` is on
+          // for every inline card), so this fires for a card whose new code is broken. The throw
+          // set `threwRef` a tick earlier; consuming it here is what tells the caller that this
+          // paint is a restore, not the new code working.
+          const restored = threwRef.current;
+          threwRef.current = false;
+          // A restore paints the LAST GOOD component, which says nothing about the current code —
+          // clearing on it would lose exactly the failure this exists to carry.
+          if (!restored) strandedRef.current = null;
+          onRenderedRef.current?.(restored);
         },
       },
     }).then((created) => {
@@ -304,6 +415,8 @@ export function GenUISurface({ code, streaming = false, preserveState = true, on
       attached?.detach();
       attached = null;
       setRenderer(null);
+      for (const timer of retryTimers.current) clearTimeout(timer);
+      retryTimers.current.clear();
     };
     // Attach exactly once. The refs above are how later prop values reach the renderer
     // without tearing it down, so they deliberately do not belong in these deps.
@@ -328,7 +441,7 @@ export function GenUISurface({ code, streaming = false, preserveState = true, on
       importedRef.current = signature;
       // A later frame's probe can settle first; without this the map reverts to an older import set.
       void mergeFallbackImports(localImports(), code).then((imports) => {
-        const settle = probeOutcome(signature, importedRef.current, streamingRef.current, deliveredRef.current);
+        const settle = probeOutcome(signature, importedRef.current, streamingRef.current, deliveredRef.current, code);
         if (settle === "stale") return;
         renderer.setImportMap({ imports });
         if (settle === "redeliver") renderer.render(deliveredRef.current);
@@ -340,7 +453,18 @@ export function GenUISurface({ code, streaming = false, preserveState = true, on
     // whatever is already mounted, so a card paints unstyled for at most a frame instead of
     // holding up every delivery behind a generator that has to boot on the first call.
     void ensureUnoStyles(code, streaming);
-    if (!deliver(renderer, deliveryFor(code, deliveredRef.current, streaming))) return;
+    if (!deliver(renderer, deliveryFor(code, deliveredRef.current, streaming))) {
+      // Nothing was delivered, so nothing will recompile and no error will be raised — but the
+      // buffer on screen may already have failed while streaming. This is the only moment that
+      // failure can still reach anyone. Keyed on the code so a settled card re-rendered by every
+      // later frame of the transcript reports once, not once per frame.
+      const stranded = strandedRef.current;
+      if (stranded !== null && reportStranded(streaming, stranded, code, strandedReportedRef.current)) {
+        strandedReportedRef.current = code;
+        onErrorRef.current?.(stranded.error, stranded.phase);
+      }
+      return;
+    }
     // `deliveredRef` must follow every delivery, or a later streaming frame diffs against a
     // prefix this render already superseded.
     deliveredRef.current = code;

package/src/client/runtime/bindings.ts

@@ -183,8 +183,9 @@ async function request<T>(method: "GET" | "POST", path: string, content?: string
   const response = await fetch(`${FS_PATH}?${query}`, content === undefined ? { method } : { method, headers: { "content-type": "application/json" }, body: JSON.stringify({ content }) });
   const body = (await response.json().catch(() => ({}))) as { error?: string };
   // A denial is not an outage. Naming it lets the card say "this session is read-only"
-  // rather than "something went wrong".
-  if (!response.ok) throw new Error(`[dsh-generative-ui] $dsh/fs ${path}: ${body.error ?? response.statusText}`);
+  // rather than "something went wrong" — and `denied` carries that as a field, because the
+  // alternative is every card string-matching our message, which then cannot be reworded.
+  if (!response.ok) throw Object.assign(new Error(`[dsh-generative-ui] $dsh/fs ${path}: ${body.error ?? response.statusText}`), { code: body.error, denied: response.status === 403 });
   return body as T;
 }
 

package/src/client/runtime/compiler.ts

@@ -49,6 +49,17 @@ export function disposeCompiler(): void {
   initPromise = null;
 }
 
+/**
+ * Does this source still export a component to mount?
+ *
+ * Deliberately a source test rather than a compile test: the failure being caught is a module that
+ * compiles perfectly and has nothing in it. Matches the two spellings the renderer accepts, and is
+ * written to ignore both comment forms so a `// export default` in prose cannot fake it.
+ */
+const hasDefaultExport = (source: string) =>
+  /^\s*export\s+default\s/m.test(source.replace(/\/\*[\s\S]*?\*\//g, "").replace(/^\s*\/\/.*$/gm, "")) ||
+  /\bexport\s*\{[^}]*\bas\s+default\b/.test(source);
+
 export function createBrowserTsxCompiler(): TsxCompiler {
   return {
     async compile(code, options = {}) {
@@ -68,12 +79,23 @@ export function createBrowserTsxCompiler(): TsxCompiler {
       if (options.partial === true) return build(normalizeGeneratedTsx(code, { mode: "streaming" }));
       try {
         return build(normalizeGeneratedTsx(code, { mode: "final" }));
-      } catch {
+      } catch (error) {
         // **The final compile must never be more fragile than a streaming frame.** The only
         // difference between the modes is that `streaming` first cuts back the still-being-typed
         // tail, and some damage (an unterminated string, typically) is only recoverable by
         // cutting. Losing the last half-sentence beats going blank on the last frame.
-        return build(normalizeGeneratedTsx(code, { mode: "streaming" }));
+        const cut = normalizeGeneratedTsx(code, { mode: "streaming" });
+        // **But only if anything is left to render.** The cut is bounded by the FIRST thing it
+        // cannot parse, so a card that puts its data above its component — the common shape when
+        // the data is long — loses the component too, and what comes back is a module of imports
+        // and type aliases. That compiles. It exports nothing, mounts nothing, and the surface
+        // reports no error, so the reader gets a card of zero height and the model is never told.
+        // Measured on a real session: the model wrote `{ name: "questions: "list[...]" }` in the
+        // first array element, `streaming` returned the same 265 characters for all 938 frames
+        // while the source grew to 13693, and the final frame took this fallback and went blank.
+        // The `final` error is the useful one here — it names the line and column of the typo.
+        if (!hasDefaultExport(cut)) throw error;
+        return build(cut);
       }
     },
   };