dsh-generative-ui 0.0.1 → 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/CanvasLauncher.d.ts

@@ -0,0 +1,6 @@
+export type CanvasLauncherProps = {
+    /** Every canvas in the workspace, including ones this session never wrote. */
+    ids: readonly string[];
+    onOpen: (id: string) => void;
+};
+export declare function CanvasLauncher({ ids, onOpen }: CanvasLauncherProps): import("react").JSX.Element;

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

@@ -0,0 +1,88 @@
+export type Canvas = {
+    id: string;
+    code: string;
+    streaming: boolean;
+};
+export type CanvasPanelProps = {
+    canvases: readonly Canvas[];
+    /** Every canvas in the workspace, so the header can reach ones this session never wrote. */
+    offerable: readonly string[];
+    /** The session's workspace, needed to fetch a canvas's sub-page files. */
+    cwd: string | undefined;
+    onOpen: (id: string) => void;
+    onClose: () => void;
+    /** Reports the panel's width so the host frame can reserve matching space. */
+    onWidth: (width: number) => void;
+    /** A canvas that failed to compile; see `runtime/report-error.ts`. */
+    onCardError?: (message: string, phase: string) => void;
+    /** A canvas that painted; see `runtime/report-error.ts`. */
+    onCardRendered?: (restored: boolean) => void;
+};
+/**
+ * Rewrites a canvas's relative sub-page imports into blob URLs before it is compiled.
+ *
+ * Only for a settled canvas: mid-stream the sibling files are usually not written yet, and a
+ * canvas does not stream under the default PTC mode anyway (see CLAUDE.md §3.6). Until the
+ * rewrite lands the original source is rendered, which fails exactly as it does today rather
+ * than blanking a canvas that was working.
+ */
+export declare function useSubPages(cwd: string | undefined, canvas: Canvas | undefined): string;
+/**
+ * Revoke every blob URL in a list, exactly once each.
+ *
+ * Both callers hand it the SAME array — the disposer, and the resolve that lands after it. The
+ * array is filled by `inlineSubPages` as it goes, so the two can see different lengths, and a
+ * URL revoked twice is harmless while one revoked never is a leak per edit. Emptying the list
+ * as it goes makes the pair idempotent regardless of which runs first or what arrived between.
+ */
+/**
+ * Whether this canvas needs the sub-page pass at all. Extracted from the effect because the
+ * mutation audit could not constrain it there — flipping `streaming` or dropping the
+ * `importsSibling` check survived every test, and both are load-bearing: resolving mid-stream
+ * inlines a prefix that the next frame supersedes, and a canvas with no sibling imports would
+ * pay a compile per frame to produce the code it already had.
+ *
+ * The `undefined` checks stay in the effect: a type predicate narrows only one parameter, and
+ * moving them here would cost the compiler its knowledge that `cwd` and `id` are strings after.
+ */
+export declare const needsResolve: (code: string, streaming: boolean | undefined) => boolean;
+export declare const revokeAll: (urls: string[]) => void;
+/** Cheap gate: only a canvas that actually writes a relative import pays for the pass. */
+declare const MIN_WIDTH = 320;
+declare const MAX_WIDTH = 720;
+/** Exported for `test/panel-css.test.ts`: the default must be draggable-to. */
+export { MIN_WIDTH as MIN_WIDTH_FOR_TEST, MAX_WIDTH as MAX_WIDTH_FOR_TEST };
+/**
+ * Must equal the `--dgu-panel-width` fallback in `panel.css`.
+ *
+ * The CSS default is what the panel is painted at before React's inline style lands; this is
+ * what the resize state starts from. Different values mean the panel visibly jumps on its first
+ * frame — a `panel-css.test.ts` assertion holds them together, since a stylesheet cannot import
+ * a constant.
+ */
+export declare const DEFAULT_WIDTH = 420;
+/**
+ * The panel's width for a pointer at `clientX`, clamped to what is usable.
+ *
+ * Extracted from the drag handler because it is the whole of the arithmetic and none of the
+ * DOM: a swapped bound or a flipped subtraction gives a panel that snaps shut or eats the
+ * conversation, and the drag itself cannot be exercised without a browser.
+ */
+/**
+ * Which canvas the panel shows, and which ids the "other canvases" menu offers.
+ *
+ * Both are pure functions of the props and both decide what the reader is looking at, so they
+ * are here rather than inline: the fallback is what covers a selected canvas disappearing
+ * mid-stream (no cleanup needed — clearing the state as well would be a second render saying
+ * the same thing), and `offerable` minus the tabs is what keeps the menu from listing what is
+ * already on screen.
+ */
+export declare const activeCanvas: (canvases: readonly Canvas[], activeId: string | null) => Canvas;
+export declare const otherCanvases: (canvases: readonly Canvas[], offerable: readonly string[]) => string[];
+export declare const widthForPointer: (clientX: number, viewportWidth: number) => number;
+/** Drag-to-resize on the panel's left edge, mirroring the host's own invisible hit strip. */
+export declare function useResize(initial: number): {
+    width: number;
+    start: (event: React.PointerEvent<HTMLDivElement>) => void;
+};
+export declare function CanvasPanel({ canvases, offerable, cwd, onOpen, onClose, onWidth, onCardError, onCardRendered }: CanvasPanelProps): import("react").JSX.Element;

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

@@ -0,0 +1,45 @@
+import type { Canvas } from "./CanvasPanel.tsx";
+export type ToolCallView = {
+    name: string;
+    argsRaw: string;
+    settled: boolean;
+};
+/**
+ * One call in the tree a `tool-call` node owns.
+ *
+ * A running call carries its arguments inline; a settled one wraps them in `call`. Either
+ * may own `subCalls` — `run_code` dispatches the file tools as children, so a canvas
+ * written from inside a code block is nested rather than top-level.
+ */
+export type CallBlock = {
+    kind?: string;
+    name?: string;
+    argsRaw?: string;
+    call?: {
+        name?: string;
+        argsRaw?: string;
+    };
+    subCalls?: readonly CallBlock[];
+};
+/**
+ * Every call a `tool-call` node contains, parents before children.
+ *
+ * Flattening rather than reading only the root is what lets a canvas written through
+ * `run_code` (or any other dispatching tool) be found: the write is a sub-call, and the
+ * root's own arguments are the code that ran, not the file.
+ */
+export declare function toolCallsOf(data: unknown): ToolCallView[];
+/**
+ * Latest canvas per id, in first-seen order.
+ * @param calls - every tool call in the transcript, oldest first.
+ */
+export type CollectedCanvases = {
+    canvases: Canvas[];
+    /**
+     * Canvases whose newest change was a patch, mapped to how many patches they have seen.
+     * The count is a cache version: the caller re-reads the file when it changes, and
+     * reuses what it already has when it does not.
+     */
+    stale: Map<string, number>;
+};
+export declare function collectCanvases(calls: readonly ToolCallView[]): CollectedCanvases;

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

@@ -0,0 +1,43 @@
+import { type Canvas } from "./CanvasPanel.tsx";
+import { type ToolCallView } from "./collect.ts";
+export type CanvasHostOptions = {
+    /** Every tool call in the current session, oldest first. */
+    calls: () => readonly ToolCallView[];
+    /** The current session's workspace directory, when it has one. */
+    cwd: () => string | undefined;
+    /** Identity of the current session; dismissals are remembered against it. */
+    sessionId: () => string;
+    /**
+     * Where a canvas's compile failure goes. Optional because a host may have no chat channel;
+     * absent, the error is still painted for the reader and simply reaches nobody else.
+     */
+    onCardError?: (message: string, phase: string) => void;
+    /** A canvas that painted; cancels a deferred error report the next frame made untrue. */
+    onCardRendered?: (restored: boolean) => void;
+};
+/**
+ * A call whose arguments carry executable code rather than a file operation.
+ *
+ * Matched on the argument text, not the tool name, for the same reason `collect.ts` classifies
+ * by shape: the day the host renames `run_code`, a name list stops matching and canvases
+ * silently stop appearing.
+ *
+ * It must also mention the canvases directory. All 29 opaque canvas writes in the corpus do,
+ * even the 27 whose path is built from a variable — and without that clause a session doing
+ * ordinary shell work re-lists once per command (measured: median 0, but one session hit 94).
+ */
+/**
+ * What a sweep would paint, as a string. Equal signatures mean nothing to do.
+ *
+ * The observer fires on every streamed token, so this is what stands between the panel and a
+ * React render per token. `code.length` rather than the code: a growing card changes length on
+ * every frame, which is exactly when it should repaint, and comparing megabytes of source per
+ * token would cost more than the render. The offerable list belongs in it too — closing the
+ * last canvas changes nothing about the visible list, and without it the launcher never paints.
+ */
+export declare const paintSignature: (canvases: readonly Canvas[], offerable: readonly string[]) => string;
+export declare const OPAQUE_WRITE: RegExp;
+export declare function mountCanvasHost({ calls, cwd, sessionId, onCardError, onCardRendered }: CanvasHostOptions): {
+    dispose: () => void;
+    show: (id: string) => void;
+};

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

@@ -0,0 +1,30 @@
+/**
+ * Injects the panel stylesheet.
+ *
+ * The `data-plugin` attribute is required, not decorative: the client module loader
+ * claims every `style:not([data-plugin])` for whichever plugin is currently
+ * materializing, so an unmarked sheet gets adopted by a stranger and torn out with them.
+ */
+export declare function injectStyles(css: string): () => void;
+/**
+ * Resolves the frame element, waiting for it when the shell has not painted yet.
+ * @param onFound - called once with the container; not called if disposed first.
+ */
+export declare function whenFrameReady(onFound: (frame: HTMLElement) => void): () => void;
+/**
+ * Creates the panel's host element and makes room for it.
+ *
+ * The frame's own columns are sized to fill the viewport exactly, so an extra flex child
+ * is laid out past the right edge no matter where it is inserted — present in the DOM,
+ * correctly sized, and entirely off screen (that is what the first attempt did). Instead
+ * the panel is fixed to the right edge and the frame is given matching right padding, so
+ * the conversation reflows into the remaining width and nothing overlaps.
+ *
+ * @param frame - the host's AppFrame element.
+ * @param width - the panel's current width in pixels.
+ */
+export declare function createColumn(frame: HTMLElement): {
+    element: HTMLElement;
+    setWidth: (width: number) => void;
+    remove: () => void;
+};

package/lib/types/client/canvas/panel-css.d.ts

@@ -0,0 +1 @@
+export declare const PANEL_CSS = "/*\n * The canvas column. Everything visual comes from the host's design tokens, so the panel\n * tracks theme changes for free and never introduces a second palette\n * (docs/web-styling.md: feature packages consume aliases, they do not define colors).\n */\n.dgu-panel {\n  --dgu-panel-width: 420px;\n  position: fixed;\n  top: 0;\n  right: 0;\n  bottom: 0;\n  z-index: 20;\n  display: flex;\n  flex-direction: column;\n  width: var(--dgu-panel-width);\n  background: var(--dsw-alias-bg-base);\n  border-left: 1px solid var(--dsw-alias-border-l1);\n  color: var(--dsw-alias-label-primary);\n  font-family: var(--dsw-font-family);\n  overflow: hidden;\n}\n\n.dgu-header {\n  display: flex;\n  align-items: center;\n  gap: 8px;\n  padding: 0 8px 0 14px;\n  height: 44px;\n  flex: none;\n}\n\n/* No hairline under either the title bar or the tab strip, and that is the host's own language,\n * not a preference: measured on dsh web's conversation header (`wSkVaW_header`), the computed\n * `border-bottom-color` is `rgba(0, 0, 0, 0)` on a transparent background with no box-shadow \u2014\n * it separates itself from the scroll area with 76px of height and nothing else. Two `border-l1`\n * rules here put lines across a panel that sits inside that same frame, which reads as chrome the\n * app does not otherwise have. */\n\n.dgu-title {\n  font-size: var(--dsw-font-s-14-font-size);\n  line-height: var(--dsw-font-s-14-line-height);\n  font-weight: var(--dsw-font-s-strong-14-font-weight);\n  white-space: nowrap;\n  overflow: hidden;\n  text-overflow: ellipsis;\n}\n\n.dgu-spacer {\n  flex: 1 1 auto;\n}\n\n.dgu-icon-button {\n  display: inline-flex;\n  align-items: center;\n  justify-content: center;\n  width: 28px;\n  height: 28px;\n  flex: none;\n  border: 0;\n  border-radius: 6px;\n  background: transparent;\n  color: var(--dsw-alias-label-secondary);\n  cursor: pointer;\n}\n.dgu-icon-button:hover {\n  background: var(--dsw-alias-interactive-bg-hover);\n  color: var(--dsw-alias-label-primary);\n}\n.dgu-icon-button:focus-visible {\n  outline: 2px solid var(--dsw-alias-state-business-primary);\n  outline-offset: -2px;\n}\n\n/* Tabs only appear from the second canvas on: one canvas needs no chooser. */\n.dgu-tabs {\n  display: flex;\n  gap: 2px;\n  padding: 6px 8px;\n  flex: none;\n  overflow-x: auto;\n  scrollbar-width: none;\n}\n.dgu-tabs::-webkit-scrollbar {\n  display: none;\n}\n\n.dgu-tab {\n  padding: 4px 10px;\n  border: 0;\n  border-radius: 6px;\n  background: transparent;\n  color: var(--dsw-alias-label-secondary);\n  font-family: inherit;\n  font-size: var(--dsw-font-xs-13-font-size);\n  line-height: var(--dsw-font-xs-13-line-height);\n  white-space: nowrap;\n  cursor: pointer;\n}\n.dgu-tab:hover {\n  background: var(--dsw-alias-interactive-bg-hover);\n}\n.dgu-tab[aria-selected=\"true\"] {\n  background: var(--dsw-specific-sidebar-nav-item-active);\n  color: var(--dsw-alias-label-primary);\n}\n\n/*\n * The canvas owns this space entirely \u2014 the panel already provides the frame, so the body\n * adds no padding and no background of its own. Generated UI is told to fill it.\n */\n.dgu-body {\n  flex: 1 1 auto;\n  min-height: 0;\n  overflow: auto;\n}\n.dgu-body > * {\n  min-height: 100%;\n}\n\n.dgu-empty {\n  display: flex;\n  align-items: center;\n  justify-content: center;\n  height: 100%;\n  padding: 24px;\n  text-align: center;\n  color: var(--dsw-alias-label-secondary);\n  font-size: var(--dsw-font-xs-13-font-size);\n  line-height: var(--dsw-font-xs-13-line-height);\n}\n\n/* Invisible hit strip, matching how the host draws its own sidebar boundary. */\n.dgu-resize {\n  position: absolute;\n  top: 0;\n  bottom: 0;\n  width: 8px;\n  cursor: col-resize;\n  z-index: 1;\n}\n.dgu-resize:hover,\n.dgu-resize[data-dragging] {\n  /* The foreground token on purpose: this wants a wash that contrasts with whatever is\n     behind it, and `brand-primary` tracks the body text colour in both themes. */\n  background: var(--dsw-alias-brand-primary);\n  opacity: 0.12;\n}\n\n/*\n * Sits where the panel's left edge was, so reopening is a click in the place it closed\n * from. Fixed like the panel because it shares the same \"outside the frame\" problem \u2014\n * an extra flex child in the frame's row lands off screen.\n */\n.dgu-launcher-dock {\n  position: fixed;\n  top: 50%;\n  right: 0;\n  transform: translateY(-50%);\n  z-index: 20;\n  display: flex;\n  align-items: center;\n  gap: 6px;\n}\n\n.dgu-launcher {\n  display: inline-flex;\n  align-items: center;\n  gap: 4px;\n  padding: 8px 6px;\n  border: 1px solid var(--dsw-alias-border-l1);\n  border-right: 0;\n  border-radius: 8px 0 0 8px;\n  background: var(--dsw-alias-bg-layer-1);\n  color: var(--dsw-alias-label-secondary);\n  font-family: var(--dsw-font-family);\n  font-size: var(--dsw-font-xs-13-font-size);\n  line-height: var(--dsw-font-xs-13-line-height);\n  cursor: pointer;\n}\n.dgu-launcher:hover {\n  background: var(--dsw-alias-interactive-bg-hover);\n  color: var(--dsw-alias-label-primary);\n}\n.dgu-launcher:focus-visible {\n  outline: 2px solid var(--dsw-alias-state-business-primary);\n  outline-offset: -2px;\n}\n\n.dgu-launcher-count {\n  font-variant-numeric: tabular-nums;\n}\n\n/* Opens leftward: the dock is already against the right edge, so there is nowhere else. */\n.dgu-launcher-menu {\n  display: flex;\n  flex-direction: column;\n  gap: 2px;\n  margin: 0;\n  padding: 4px;\n  max-height: 60vh;\n  overflow-y: auto;\n  list-style: none;\n  border: 1px solid var(--dsw-alias-border-l1);\n  border-radius: 8px;\n  /* A floating surface has to occlude: `bg-layer-1` is a tint over whatever it sits on, so\n     it needs the panel's own opaque ground underneath before the tint reads as a menu. */\n  background: var(--dsw-alias-bg-base);\n  background-image: linear-gradient(var(--dsw-alias-bg-layer-1), var(--dsw-alias-bg-layer-1));\n  box-shadow: 0 8px 24px rgb(0 0 0 / 0.24);\n}\n\n.dgu-launcher-item {\n  display: block;\n  width: 100%;\n  padding: 5px 10px;\n  border: 0;\n  border-radius: 6px;\n  background: transparent;\n  color: var(--dsw-alias-label-primary);\n  font-family: var(--dsw-font-family);\n  font-size: var(--dsw-font-xs-13-font-size);\n  line-height: var(--dsw-font-xs-13-line-height);\n  text-align: left;\n  white-space: nowrap;\n  cursor: pointer;\n}\n.dgu-launcher-item:hover {\n  background: var(--dsw-alias-interactive-bg-hover);\n}\n\n/* Anchors the header's canvas picker; the menu drops below the button. */\n.dgu-picker {\n  position: relative;\n  display: flex;\n}\n\n.dgu-picker-menu {\n  position: absolute;\n  top: calc(100% + 4px);\n  right: 0;\n  z-index: 1;\n}\n";

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

@@ -0,0 +1,12 @@
+/** Every canvas in the workspace, including ones this session never wrote. */
+export declare function listCanvasIds(cwd: string): Promise<readonly string[]>;
+export declare function readCanvasFile(cwd: string, id: string): Promise<string | null>;
+/**
+ * Reads one of a canvas's sub-page files, named by the relative specifier as written in the
+ * canvas source. The server resolves it through the contract; anything outside this canvas's
+ * own child directory comes back 400 and reads here as null.
+ */
+export declare function readCanvasChild(cwd: string, id: string, specifier: string, from: string): Promise<{
+    source: string;
+    filename: string;
+} | null>;

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

@@ -0,0 +1,20 @@
+/**
+ * Whether the card imports a sibling at all — the cheap question `CanvasPanel` asks before
+ * paying for a resolve pass. It had its own copy of the regex, identical but for the `g` flag;
+ * a widening applied to one and not the other means the panel never calls `inlineSubPages` and
+ * the card silently renders without its sub-pages. Sharing one pattern fixed that and introduced
+ * the `lastIndex` bug above — hence two derived regexes rather than two literals.
+ */
+export declare const importsSibling: (code: string) => boolean;
+/**
+ * @param read fetches one child by its specifier, returning its source and the real filename
+ * it was found under — the compiler picks its syntax from the extension, and a specifier is
+ * written without one, so passing the specifier makes a `.ts` file fail to parse.
+ * @param compile turns one child's TSX into JS. Children go through the same compiler as the
+ * card, so a sub-page may be TSX and may itself import a sibling.
+ * @param urls collects every blob created, so the caller can revoke them with the surface.
+ */
+export declare function inlineSubPages(code: string, entry: string, read: (specifier: string, from: string) => Promise<{
+    source: string;
+    filename: string;
+} | null>, compile: (filename: string, source: string) => Promise<string>, urls: string[]): Promise<string>;

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

@@ -0,0 +1,15 @@
+/**
+ * Closes on a pointerdown anywhere but `anchor`, while `open`. Returns its own disposer.
+ *
+ * Split out of the hook so the four things that matter are testable without a renderer: that it
+ * does not listen while closed, that an outside press closes, that a press inside the anchor
+ * does **not**, and that it unsubscribes. A `pointerdown` listener on the document rather than a
+ * backdrop element, because a backdrop would sit over the canvas and swallow the first click
+ * into it.
+ */
+export declare function dismissOnOutsidePointer(open: boolean, anchor: HTMLElement | null, close: () => void): (() => void) | undefined;
+export declare function useDismissable(): {
+    open: boolean;
+    setOpen: import("react").Dispatch<import("react").SetStateAction<boolean>>;
+    anchor: import("react").RefObject<HTMLDivElement>;
+};

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

@@ -0,0 +1,20 @@
+import type { ClientContext } from "@deepseek-ai/dsh-client-runtime/client";
+import { localImports } from "./runtime/bindings.ts";
+import { type ChatNodeView } from "./session.ts";
+export declare const inject: string[];
+/** Re-exported so `bun run smoke` can build the synthesized blob modules and parse them. */
+export { localImports };
+export declare function apply(ctx: ClientContext): void;
+/** All assistant prose in one node, concatenated; empty for every other node kind. */
+export declare function textOf(node: ChatNodeView): string;
+/**
+ * Cache key for a `tool-call` node: how far its arguments have streamed, plus which calls
+ * have settled. Read straight off the node rather than through `toolCallsOf`, so computing
+ * the key does not repeat the work the cache exists to avoid.
+ *
+ * The settled flags are part of the key, not a detail: a call's `argsRaw` is already
+ * complete when `tool-result` arrives, so a length-only key would never invalidate and the
+ * cached view would claim `streaming` forever — a canvas that never stops pulsing and an
+ * `edit` that never marks it stale.
+ */
+export declare function callsKeyOf(node: ChatNodeView): string;

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

@@ -0,0 +1,189 @@
+export type GenUISurfaceProps = {
+    /** Full source when settled; the growing prefix while streaming. */
+    code: string;
+    /** True while `code` is still a prefix, so partial frames get normalized before compiling. */
+    streaming?: boolean;
+    /**
+     * 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. 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?: (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;
+/**
+ * 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
+ * it is worth a few retries before anyone concludes the model wrote something wrong.
+ */
+/** Exported for `test/transient.test.ts`. */
+export declare const TRANSIENT_LOAD: RegExp;
+/**
+ * Whether a reported error is worth another attempt.
+ *
+ * Extracted because it is the whole of the decision and none of the React: three conditions,
+ * each of which sends the reader somewhere different when it is wrong. Exported for
+ * `test/retry.test.ts`.
+ */
+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.
+ *
+ * `pushCode` APPENDS but a session event carries the whole prefix so far, so the difference
+ * between these four answers is the difference between a correct surface and one whose buffer
+ * doubles on every frame. Pure, because the decision is, and because a state machine that only
+ * runs inside an effect with three refs is one nothing ever checks.
+ *
+ * - `nothing`   the frame adds no text, or a settled frame re-delivers what is already painted
+ * - `replace`   settled: render the whole thing outright
+ * - `append`    streaming and the buffer is a prefix of this frame: push only the delta
+ * - `restart`   the prefix was rewritten (a re-delivered history page, or an edit)
+ */
+export type Delivery = {
+    do: "nothing";
+} | {
+    do: "replace";
+    code: string;
+} | {
+    do: "append";
+    delta: string;
+} | {
+    do: "restart";
+    code: string;
+};
+export declare const deliveryFor: (code: string, delivered: string, streaming: boolean) => Delivery;
+/**
+ * Route a `Delivery` to the renderer. Returns whether anything was delivered, which is what tells
+ * the caller to advance its `delivered` marker.
+ *
+ * Split from the effect so the three calls can be constrained: `render` replaces the buffer,
+ * `pushCode` appends to it, and `clear({ preserveVisualState: true })` starts over WITHOUT
+ * blanking what is on screen. Getting `render` and `pushCode` the wrong way round doubles the
+ * buffer on every streamed frame, and the difference is one word inside an effect.
+ */
+export declare const deliver: (renderer: RendererCalls, delivery: Delivery) => boolean;
+/**
+ * What the card imports, as one string — the key the import-map probe is cached against.
+ *
+ * Compared by value rather than by set, so re-ordering the same imports re-probes. That is
+ * deliberate: the probe is cheap and cached downstream, and a set comparison here would be more
+ * 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;
+    pushCode: (delta: string) => void;
+    clear: (options: {
+        preserveVisualState: boolean;
+    }) => void;
+};
+/**
+ * What to do about an error the renderer reported.
+ *
+ * - `ignore`  the stream is not finished; the next frame supersedes this
+ * - `retry`   a dependency failed to arrive, and busting the import URLs is the fix
+ * - `report`  tell the reader
+ *
+ * **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";
+/**
+ * What `onError` DOES with the three outcomes, separated from where they come from. The decision
+ * was already a pure function; the dispatch was not, and the mutation audit could not constrain
+ * it — swapping `ignore` for `retry` survived every test, because the only caller lives inside a
+ * `GenUIRenderer.create` callback that needs a DOM to reach.
+ *
+ * Each branch is one line and each is load-bearing: `ignore` must not touch the counter (a
+ * streaming frame is not a failed attempt), `retry` must increment BEFORE scheduling (the delay
+ * is a function of the count), and `report` must not increment at all.
+ */
+/**
+ * What to do when an import probe settles. Three outcomes and every one is a bug if wrong:
+ *
+ * - **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** — 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, probed: string) => "stale" | "redeliver" | "store";
+export declare const dispatchError: (action: "ignore" | "retry" | "report", effects: {
+    attempts: () => number;
+    setAttempts: (n: number) => void;
+    schedule: (ms: number) => void;
+    report: () => void;
+}) => void;
+/**
+ * The same import map with a fresh query on every fetched entry.
+ *
+ * Only `https://esm.sh/` URLs are touched. Local blob URLs are minted per render and already
+ * 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;