dsh-generative-ui 0.0.0 → 0.0.2

package/src/client/runtime/compiler.ts

@@ -0,0 +1,80 @@
+import initTsx, { transform as transformTsx } from "@esm.sh/tsx";
+import { normalizeGeneratedTsx } from "partial-tsx";
+import { rewriteImportMetaResolveSpecifiers, type RendererImportMap } from "partial-react/import-map";
+import { WASM_PATH } from "../../contract-assets.ts";
+
+// Structurally equivalent to `partial-react/compiler`'s three types. Deliberately not
+// imported from there: that module has a Vite-only `...tsx_bg.wasm?url` at the top level
+// plus a node:fs read path and a `Bun` global, none of which survive a plugin bundle.
+export type CompileOptions = { importMap?: RendererImportMap; partial?: boolean; previousCode?: string; filename?: string };
+export type CompileResult = { code: string; source: string; changed: boolean };
+export type TsxCompiler = { compile: (code: string, options?: CompileOptions) => Promise<CompileResult> };
+
+let initPromise: Promise<unknown> | null = null;
+
+/** The wasm is served by this plugin's own webServer route; /plugins only serves client.js. */
+const initCompiler = () =>
+  (initPromise ??= initTsx(WASM_PATH).catch((error: unknown) => {
+    initPromise = null;
+    throw error;
+  }));
+
+/**
+ * Starts loading the 2.6 MB wasm file so it is warm before the first real frame (a cold init
+ * costs 400-500 ms). The *file* is 2.6 MB; an instantiated compiler costs roughly 16 MB of
+ * heap, which is why `disposeCompiler` exists — the two numbers have been confused before.
+ *
+ * Never throws: `apply()` calls this and nothing else awaits it, so a
+ * synchronous failure inside `initTsx` — an unfetchable wasm path, say — would otherwise
+ * take the whole plugin's registration down with it and leave the shell loading forever.
+ * A cold compile on the first card is a far better outcome than no plugin at all.
+ */
+export const warmCompiler = (): Promise<unknown> => {
+  try {
+    return initCompiler().catch(() => undefined);
+  } catch {
+    initPromise = null;
+    return Promise.resolve();
+  }
+};
+
+/**
+ * Drops the wasm instance so GC can take it. `@esm.sh/tsx` exports no dispose — only
+ * `init`/`initSync`/`transform` — so releasing the reference is the whole of what we can do.
+ * Measured 2026-08-23: an instance costs ~16MB, and each HMR round made a fresh one while the
+ * previous stayed reachable through this module-level promise. Dev-only, but a dozen reloads
+ * is 200MB.
+ */
+export function disposeCompiler(): void {
+  initPromise = null;
+}
+
+export function createBrowserTsxCompiler(): TsxCompiler {
+  return {
+    async compile(code, options = {}) {
+      await initCompiler();
+      const importMap = options.importMap;
+      const build = (source: string): CompileResult => {
+        const resolved = importMap?.imports ? rewriteImportMetaResolveSpecifiers(source, importMap.imports) : source;
+        const result = transformTsx({ filename: options.filename ?? "_.tsx", code: resolved, target: "es2022", importMap, jsxImportSource: "react" });
+        const compiled = new TextDecoder().decode(result.code);
+        return { code: compiled, source, changed: compiled !== options.previousCode };
+      };
+
+      // Normalization runs for `final` too. The model does not reliably close its trailing
+      // `)` and `}` before writing the fence, so compiling the raw source renders every
+      // streaming frame fine and then throws `Expected ',', got '<eof>'` at the very moment
+      // the block completes — measured on exactly that shape.
+      if (options.partial === true) return build(normalizeGeneratedTsx(code, { mode: "streaming" }));
+      try {
+        return build(normalizeGeneratedTsx(code, { mode: "final" }));
+      } catch {
+        // **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" }));
+      }
+    },
+  };
+}

package/src/client/runtime/inline-fence.ts

@@ -0,0 +1,222 @@
+/**
+ * Renders ```` ```ui4a/tsx ```` blocks in assistant prose live, in place, between the
+ * surrounding paragraphs — the ui4a-playground inline contract.
+ *
+ * Two sources, each doing what only it can:
+ *
+ * - **The session snapshot owns the code.** The host's markdown renderer withholds a
+ *   fence's info string until the closing fence arrives, so a DOM-only implementation
+ *   cannot tell a half-written ui4a block from any other code block, and can only claim
+ *   it after the model has stopped typing. The raw assistant text has the opening fence
+ *   from its very first token, so that is where the code and its language come from.
+ * - **The DOM owns the position.** There is no slot for a markdown code block, so the
+ *   rendered block is what tells us where in the prose to mount. `md-code-block` is a
+ *   hard-coded class on the host's CodeBlock wrapper.
+ *
+ * Blocks are matched to segments by content (a rendered block's text is a prefix of, or
+ * equal to, its segment's code), not by order, so unrelated code blocks in the same reply
+ * are left alone.
+ *
+ * The claimed block is hidden rather than removed: it belongs to the host's React tree,
+ * and detaching a node React still owns invites a NotFoundError on its next commit.
+ */
+import { createRoot, type Root } from "react-dom/client";
+import { createElement } from "react";
+import { CodeBlock } from "@deepseek-ai/dsh-client-ui-primitives";
+import type { ReactElement } from "react";
+import type { Ui4aSegment } from "./segments.ts";
+import { observeTranscript } from "./observe.ts";
+
+const CLAIMED = "data-ui4a-claimed";
+const MOUNT = "data-ui4a-mount";
+const PREVIEW = "data-ui4a-preview";
+
+/** Unmounting a root during React's own commit throws; defer it like every other teardown here. */
+const dropPreview = (claim: { preview: { host: HTMLElement; root: Root } | null }) => {
+  const preview = claim.preview;
+  if (preview === null) return;
+  claim.preview = null;
+  queueMicrotask(() => {
+    preview.root.unmount();
+    preview.host.remove();
+  });
+};
+
+type Claim = { block: HTMLElement; mount: HTMLElement; root: Root; code: string; complete: boolean; rendered: string; painted: MutationObserver | null; preview: { host: HTMLElement; root: Root } | null };
+
+/**
+ * Whether the card has actually painted something a reader can see.
+ *
+ * **Compiling is not the same as having something to look at.** Mid-stream the default
+ * export usually exists while the body is still an empty shell, so hiding the source block
+ * at claim time leaves a blank gap that fills in with a pop seconds later — and the source
+ * was sitting right there the whole time. Text, or an element that draws its own
+ * pixels **and has a box**, is the signal; a wrapper with layout classes is not.
+ *
+ * Measured against the alternatives: a bare `getBoundingClientRect()` test passes a styled-but-
+ * empty `div` — `height: 200px`, a grid with a gap, a padded skeleton card — which is precisely
+ * the mid-stream shell this exists to reject. Enumerating tags alone missed `<video>`, custom
+ * elements and iframes. Requiring both catches everything the tag list caught, plus those three,
+ * and still rejects all three empty shells.
+ */
+/** Elements that paint their own pixels; a custom element (any tag with a dash) counts too. */
+const DRAWS = new Set(["SVG", "CANVAS", "IMG", "VIDEO", "IFRAME", "PICTURE"]);
+
+/**
+ * partial-react's error boundary renders a bare text node — `ERROR` or `ERROR: <message>`.
+ * That is text, so a naive check reads it as a painted card and hides the source block
+ * underneath it, leaving the reader one red line and no way to see what the model wrote.
+ * Measured: exactly the case where the source is most worth keeping.
+ */
+const BOUNDARY_ERROR = /^ERROR(:|$)/;
+
+/** Split out from `hasPainted` so the rule can be tested without a DOM. */
+export const isPaintedText = (text: string) => {
+  const trimmed = text.trim();
+  return trimmed !== "" && !BOUNDARY_ERROR.test(trimmed);
+};
+
+export const hasPainted = (mount: HTMLElement) => {
+  if (isPaintedText(mount.textContent ?? "")) return true;
+  for (const el of mount.querySelectorAll("*")) {
+    const tag = el.tagName.toUpperCase();
+    if (!DRAWS.has(tag) && !tag.includes("-")) continue;
+    const box = el.getBoundingClientRect();
+    if (box.width > 0 && box.height > 0) return true;
+  }
+  return false;
+};
+
+/** The block's source. `pre` when the grammar was unknown, the highlighted div otherwise. */
+const codeOf = (block: HTMLElement) => block.querySelector("pre")?.textContent ?? "";
+
+/** CodeBlock trims one trailing newline for display, so compare on trimmed ends. */
+export const sameCode = (a: string, b: string) => a.trimEnd() === b.trimEnd();
+
+/**
+ * The segment a rendered block belongs to.
+ *
+ * Mid-stream the block shows a prefix of its segment; once settled the two are equal.
+ */
+export const matchSegment = (segments: readonly Ui4aSegment[], rendered: string) => segments.find((segment) => sameCode(segment.code, rendered) || segment.code.startsWith(rendered));
+
+export type InlineFenceOptions = {
+  /** Every ui4a segment currently in the transcript, in document order. */
+  segments: () => readonly Ui4aSegment[];
+  render: (props: { code: string; streaming: boolean }) => ReactElement;
+  scope?: HTMLElement;
+};
+
+export function claimInlineFences({ segments, render, scope }: InlineFenceOptions): () => void {
+  const claims = new Map<HTMLElement, Claim>();
+  const root = scope ?? document.body;
+
+  const release = (claim: Claim, restore: boolean) => {
+    claim.painted?.disconnect();
+    claim.root.unmount();
+    claim.mount.remove();
+    dropPreview(claim);
+    if (restore && claim.block.isConnected) {
+      claim.block.style.display = "";
+      claim.block.removeAttribute(CLAIMED);
+    }
+    claims.delete(claim.block);
+  };
+
+  const sweep = () => {
+    const current = segments();
+
+    for (const block of root.querySelectorAll<HTMLElement>(`.md-code-block:not([${CLAIMED}])`)) {
+      const code = codeOf(block);
+      if (code === "") continue;
+      // A streaming block's rendered text is a prefix of its segment; a settled one equals it.
+      const segment = matchSegment(current, code);
+      if (segment === undefined) continue;
+      block.setAttribute(CLAIMED, "");
+      const mount = document.createElement("div");
+      mount.setAttribute(MOUNT, "");
+      block.parentElement?.insertBefore(mount, block.nextSibling);
+      // Swap the host's block for our own CodeBlock while the card is still compiling. Two
+      // reasons, both reported from a real transcript: the host keys highlighting on the fence
+      // language, and its markdown parser truncates `ui4a/tsx` at the slash — so `ui4a` reaches
+      // shiki, matches no grammar, and the source renders as unhighlighted plain text. Passing
+      // `lang="tsx"` is all it takes; `dsh-client-ui-primitives` is in the platform table, so
+      // this resolves to the shell's own component and costs nothing to bundle. The second
+      // reason is height: a 300-line card streams for over a minute with all of it on screen,
+      // and this preview is capped.
+      const previewHost = document.createElement("div");
+      previewHost.setAttribute(PREVIEW, "");
+      block.parentElement?.insertBefore(previewHost, block);
+      block.style.display = "none";
+      const claim: Claim = { block, mount, root: createRoot(mount), code: "", complete: false, rendered: "", painted: null, preview: { host: previewHost, root: createRoot(previewHost) } };
+      // The source stays visible until the card paints. Checked at most once per frame and
+      // torn down the moment it fires: a streaming card mutates thousands of times, and
+      // `textContent` walks the whole subtree, so a per-mutation check would be
+      // O(mutations x subtree). The cost only exists during the gap it closes.
+      let queued = 0;
+      claim.painted = new MutationObserver(() => {
+        if (queued !== 0) return;
+        queued = requestAnimationFrame(() => {
+          queued = 0;
+          if (!hasPainted(mount)) return;
+          claim.painted?.disconnect();
+          claim.painted = null;
+          dropPreview(claim);
+        });
+      });
+      claim.painted.observe(mount, { childList: true, subtree: true, characterData: true });
+      claims.set(block, claim);
+    }
+
+    for (const claim of claims.values()) {
+      if (!claim.block.isConnected) {
+        release(claim, false);
+        continue;
+      }
+      const rendered = codeOf(claim.block);
+      // The block's own text is what locates its segment, so an unchanged block cannot
+      // have changed its match — skip the scan rather than re-run it every frame.
+      //
+      // Only once it has settled, though. `complete` flips on the segment, not in the block, so
+      // a card whose last token closes the fence without changing the rendered text would never
+      // leave the streaming path — and the streaming path cuts back the still-being-typed tail,
+      // so it would keep rendering a card with its last statement missing. The skip is an
+      // optimization for the steady state (most blocks in a long transcript), and a claim that
+      // is still streaming is being re-scanned every frame regardless.
+      if (rendered === claim.rendered && claim.code !== "" && claim.complete) continue;
+      claim.rendered = rendered;
+      const segment = matchSegment(current, rendered);
+      // The snapshot is authoritative while it still describes this block: mid-stream its
+      // code runs ahead of what markdown has painted. Once it stops describing it — an
+      // older page dropped out of the loaded window — the last good frame stands, because
+      // re-deriving from the hidden block would hand the renderer a truncated prefix and
+      // blank a card that was already complete.
+      //
+      // Unless the block stopped being this card's at all: React reconciles `.md-code-block`
+      // wrappers positionally, so a re-render can drop unrelated content into the very node
+      // we hid. Its text is then no longer a prefix of what we rendered, and holding the
+      // claim would leave a stale card on screen with the real block invisible behind it.
+      if (segment === undefined) {
+        if (claim.code.startsWith(rendered)) continue;
+        release(claim, true);
+        continue;
+      }
+      const { code, complete } = segment;
+      if (code === claim.code && complete === claim.complete) continue;
+      claim.code = code;
+      claim.complete = complete;
+      claim.root.render(render({ code, streaming: !complete }));
+      // The preview follows the SEGMENT, not the block: mid-stream the snapshot runs ahead of
+      // what markdown has painted, so this is the newer text and the one the reader wants while
+      // waiting. Dropped the moment the card paints.
+      claim.preview?.root.render(createElement(CodeBlock, { code, lang: "tsx" }));
+    }
+  };
+
+  const stop = observeTranscript(sweep);
+
+  return () => {
+    stop();
+    for (const claim of claims.values()) release(claim, true);
+  };
+}

package/src/client/runtime/observe.ts

@@ -0,0 +1,65 @@
+/**
+ * One document observer, shared by every consumer that reacts to transcript mutations.
+ *
+ * Both the inline-fence claimer and the canvas host are driven by the same event — a
+ * streamed token landing in the chat DOM — so a second observer over the same subtree only
+ * doubles the browser's mutation bookkeeping and the number of frames scheduled. The
+ * coalescing is not optional either: a streaming reply mutates the transcript dozens of
+ * times per second, and one sweep per mutation is how a renderer melts the main thread.
+ */
+type Listener = () => void;
+
+const listeners = new Set<Listener>();
+let observer: MutationObserver | null = null;
+let frame = 0;
+
+const flush = () => {
+  frame = 0;
+  for (const listener of listeners) listener();
+};
+
+const schedule = () => {
+  if (frame !== 0) return;
+  frame = requestAnimationFrame(flush);
+};
+
+/**
+ * Runs `listener` at most once per frame while the document changes, starting immediately.
+ * @returns a disposer that also tears the observer down once nothing is left listening.
+ */
+export function observeTranscript(listener: Listener): () => void {
+  listeners.add(listener);
+  if (observer === null) {
+    observer = new MutationObserver(schedule);
+    observer.observe(document.body, { subtree: true, childList: true, characterData: true });
+  }
+  schedule();
+  return () => {
+    listeners.delete(listener);
+    if (listeners.size > 0) return;
+    observer?.disconnect();
+    observer = null;
+    if (frame !== 0) cancelAnimationFrame(frame);
+    frame = 0;
+  };
+}
+
+/** Requests a frame outside a mutation — for state that changed without the DOM changing. */
+export const scheduleSweep = schedule;
+
+/**
+ * Drop every listener and tear the observer down.
+ *
+ * The set above is module scope, so it is shared by everything in a process — which is right in
+ * a browser (one transcript, one observer) and is a trap in a test run, where a listener left by
+ * one file goes on being swept by every later one. A sweep captures its root at registration, so
+ * a stale one runs against a document that has since been replaced.
+ *
+ * Nothing in the plugin calls this: the shell disposes each host and that is the real path.
+ */
+export function resetTranscriptObservers(): void {
+  listeners.clear();
+  observer?.disconnect();
+  observer = null;
+  frame = 0;
+}

package/src/client/runtime/register.ts

@@ -0,0 +1,57 @@
+/**
+ * Everything generated code may import as a "local" module.
+ *
+ * The react family MUST be here: generated code shares the shell's single React
+ * instance or hooks blow up with an invalid-hook-call. All five come from the
+ * shell's platform table (see tsdown.config.ts), so registering them costs no
+ * bundle weight — it only republishes the instances we already received.
+ *
+ * We deliberately pre-register no component library. Anything else resolves
+ * through the esm.sh fallback at compile time.
+ */
+import * as React from "react";
+import * as ReactJsxRuntime from "react/jsx-runtime";
+import * as ReactDom from "react-dom";
+import * as ReactDomClient from "react-dom/client";
+import { registerModules, registryImports } from "./registry.ts";
+
+let installed = false;
+
+/**
+ * Installs a real `<script type="importmap">`.
+ *
+ * Compile-time rewriting only covers the code we generate. Packages pulled from
+ * esm.sh arrive as already-compiled JS whose `import ... from "react"` survives
+ * verbatim, and the browser resolves those bare specifiers against the document
+ * import map alone — without it, any generated UI that uses a third-party
+ * package dies on `Failed to resolve module specifier "react"`.
+ *
+ * It can only be installed once, and only before the first module resolution.
+ */
+function installDocumentImportMap(): void {
+  if (installed || typeof document === "undefined") return;
+  installed = true;
+  // A host-owned map wins: overwriting it would break whoever installed it, and a
+  // second map is ignored by the browser anyway.
+  if (document.querySelector('script[type="importmap"]') !== null) {
+    console.warn("[dsh-generative-ui] the shell already installs an import map; bare specifiers from esm.sh packages may not resolve");
+    return;
+  }
+  const script = document.createElement("script");
+  script.type = "importmap";
+  script.textContent = JSON.stringify({ imports: registryImports() });
+  document.head.prepend(script);
+}
+
+export function registerRuntimeModules(): void {
+  registerModules({
+    react: React,
+    "react/jsx-runtime": ReactJsxRuntime,
+    "react/jsx-dev-runtime": ReactJsxRuntime,
+    "react-dom": ReactDom,
+    "react-dom/client": ReactDomClient,
+  });
+  installDocumentImportMap();
+}
+
+export const hostReactVersion = React.version;

package/src/client/runtime/registry.ts

@@ -0,0 +1,65 @@
+/**
+ * Generated TSX is imported as a blob URL, so an import map's targets must be real
+ * URLs. Vite hosts can point at `/src/lib/react.ts`; dsh plugin bundles have no
+ * such "source is a URL" escape hatch (and CJS factories have no `import.meta`).
+ *
+ * So this goes the other way round: register the module namespaces the shell has
+ * already loaded, then synthesize, per specifier, a blob module that reads the
+ * table and named-re-exports it. Export names are enumerated at runtime, so there
+ * is no hand-written list to drift. React is a singleton for free — everyone
+ * imports the same blob URL, and that URL reads the shell's instance.
+ * (Ported from ui4a-playground/src/runtime/registry.ts.)
+ */
+const REGISTRY_KEY = "__DSH_GENERATIVE_UI_MODULES__";
+type Registry = Record<string, Record<string, unknown>>;
+
+const registry: Registry = ((globalThis as Record<string, unknown>)[REGISTRY_KEY] ??= {}) as Registry;
+const urls = new Map<string, string>();
+
+const IDENTIFIER = /^[A-Za-z_$][\w$]*$/;
+
+/** Exported for `test/registry.test.ts`: it generates code, so a bug here is a blank card with an empty console. */
+export function buildModuleSource(specifier: string): string {
+  const namespace = registry[specifier] ?? {};
+  const lines = [`const ns = globalThis[${JSON.stringify(REGISTRY_KEY)}][${JSON.stringify(specifier)}];`];
+  // One `export const` per name rather than a spread: ESM export names must be statically visible.
+  // Freezing getters into consts is safe here — every registered namespace is a settled module.
+  for (const name of Object.keys(namespace)) {
+    if (name !== "default" && IDENTIFIER.test(name)) lines.push(`export const ${name} = ns[${JSON.stringify(name)}];`);
+  }
+  lines.push("default" in namespace ? "export default ns.default;" : "export default ns;");
+  return lines.join("\n");
+}
+
+export function registerModules(modules: Record<string, Record<string, unknown>>): void {
+  for (const [specifier, namespace] of Object.entries(modules)) {
+    // Re-registering the same namespace must keep the URL. The document import map is
+    // installed once and points at these blobs for the tab's life, so revoking one leaves
+    // every esm.sh package resolving `react` to a dead URL — the module graph dies and the
+    // card renders blank with nothing in the console. Only a genuine hot-swap invalidates.
+    if (registry[specifier] === namespace) continue;
+    registry[specifier] = namespace;
+    // A namespace that really changed: the old blob would re-export stale bindings.
+    const stale = urls.get(specifier);
+    if (stale !== undefined) {
+      URL.revokeObjectURL(stale);
+      urls.delete(specifier);
+    }
+  }
+}
+
+export function moduleUrl(specifier: string): string {
+  const cached = urls.get(specifier);
+  if (cached !== undefined) return cached;
+  const url = URL.createObjectURL(new Blob([buildModuleSource(specifier)], { type: "text/javascript" }));
+  urls.set(specifier, url);
+  return url;
+}
+
+export const registryImports = (): Record<string, string> => Object.fromEntries(Object.keys(registry).map((specifier) => [specifier, moduleUrl(specifier)]));
+
+/** Drops every synthesized blob. The plugin's dispose path must call this or each HMR round leaks one URL per specifier. */
+export function disposeRegistry(): void {
+  for (const url of urls.values()) URL.revokeObjectURL(url);
+  urls.clear();
+}

package/src/client/runtime/report-error.ts

@@ -0,0 +1,79 @@
+/**
+ * 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.
+ *
+ * Three 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 message per render is a loop the user has to kill. Keyed on
+ *   the message text.
+ * - **Announced as automatic.** The model is about to read a user-role message it was not sent.
+ *   Saying where it came from is what stops it replying "sorry about that" to a person who typed
+ *   nothing.
+ */
+const sent = new Set<string>();
+
+/** Exported for the test: a fresh card in a fresh session should be able to report again. */
+export const forgetReportedErrors = () => {
+  sent.clear();
+  cardRendered();
+};
+
+export type ErrorReporter = (text: string) => 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.
+ *
+ * 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.
+ */
+export const reportBody = (message: string, phase: string) =>
+  `[automatic] The card you just wrote did not render. It failed at the ${phase} step:\n\n${message}\n\nThis was sent by the renderer, not by the user — nobody typed it, so do not apologise or address it as a request. 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, and answer in the language the user has been writing in.`;
+
+/**
+ * How long an error must stand before the model hears about it. A streaming card recompiles many
+ * times a second, so a frame that throws and a frame that paints are milliseconds apart; a second
+ * is far longer than that gap and far shorter than a reader's patience with a broken card.
+ */
+const SETTLE_MS = 1000;
+
+let pending: ReturnType<typeof setTimeout> | null = null;
+
+/** Called when a surface paints. Cancels a report the very next frame made untrue. */
+export function cardRendered(): void {
+  if (pending === null) return;
+  clearTimeout(pending);
+  pending = null;
+}
+
+export function reportCardError(send: ErrorReporter | undefined, message: string, phase: string): void {
+  if (send === undefined) return;
+  if (sent.has(message)) return;
+  sent.add(message);
+  if (pending !== null) clearTimeout(pending);
+  pending = setTimeout(() => {
+    pending = null;
+    send(reportBody(message, phase));
+  }, SETTLE_MS);
+}