dsh-generative-ui 0.0.1 → 0.0.2

package/README.md

@@ -1,5 +1,6 @@
 # dsh-generative-ui
 
+[![npm](https://img.shields.io/npm/v/dsh-generative-ui)](https://www.npmjs.com/package/dsh-generative-ui)
 [![pkg.pr.new](https://pkg.pr.new/badge/CNSeniorious000/dsh-generative-ui)](https://pkg.pr.new/~/CNSeniorious000/dsh-generative-ui)
 [![MIT](https://img.shields.io/badge/license-MIT-blue)](./LICENSE)
 
@@ -16,20 +17,25 @@ The `ui4a` in that fence is the harness this implements — **UI for Agent**, fr
 
 ## Install
 
-**Not on npm yet**, so install the preview build published on every push:
+```sh
+dsh plugin --profile web add dsh-generative-ui
+```
+
+Every release is published from CI over OIDC, so the tarball carries npm provenance. For an
+unreleased commit there is a preview build of every push:
 
 ```sh
 dsh plugin --profile web add https://pkg.pr.new/CNSeniorious000/dsh-generative-ui@main
 ```
 
-Or, working on it locally, point the profile at your checkout — `lib/` is built by `prepare`, so
+And working on it locally, point the profile at your checkout — `lib/` is built by `prepare`, so
 the profile does not care that this package uses bun and dsh uses pnpm:
 
 ```sh
 dsh plugin --profile web add link:/path/to/dsh-generative-ui
 ```
 
-`dsh plugin` forwards to the profile's package manager, so either form installs the package. Mounting it also takes one line in `~/.dsh/profiles/web/package.json` — the profile's bundle list is what dsh actually boots:
+`dsh plugin` forwards to the profile's package manager, so any of these installs the package. Mounting it also takes one line in `~/.dsh/profiles/web/package.json` — the profile's bundle list is what dsh actually boots:
 
 ```json
 {

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?: () => 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?: () => 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,159 @@
+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. 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.
+     */
+    preserveState?: boolean;
+    /** Real compile diagnostics. Transient streaming frames are filtered out — see TRANSIENT below. */
+    onError?: (error: Error, phase: "transform" | "compile" | "render") => void;
+    /** Fires whenever a frame actually painted. Use it to clear a previously shown error. */
+    onRendered?: () => void;
+    className?: string;
+};
+/** Paired with `disposeCompiler`: the shared instance must go with the wasm behind it. */
+export declare const dropSharedCompiler: () => void;
+export declare const compiler: () => import("./compiler.ts").TsxCompiler;
+/**
+ * Mid-stream frames legitimately fail: a prefix that has not reached `export default`
+ * yet, or a half-written expression. partial-react treats these as transient and keeps
+ * the last good frame, so surfacing them would just make the UI flash errors while the
+ * model types. Only a failure that survives settling is the caller's business.
+ */
+/** Exported for `test/transient.test.ts`: this decides whether the reader sees an error. */
+export declare const TRANSIENT: RegExp;
+/**
+ * A dependency that failed to arrive, not code that is wrong. esm.sh cold-starts and the
+ * network drops, and the symptom is identical to a broken component — a blank surface — so
+ * 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`.
+ */
+/**
+ * Whether a mid-stream error is the stream not being finished yet.
+ *
+ * Both patterns come from the parse stages — `No default export found` is thrown inside
+ * `importCompiledComponent` (compile), and an unexpected EOF is the transform rejecting a
+ * prefix. A card whose own render throws a message that happens to match is a real error, so
+ * the phase is part of the question rather than the message alone.
+ */
+export declare const isUnfinishedFrame: (message: string, phase: string, streaming: boolean) => boolean;
+export declare const shouldRetry: (message: string, phase: string, streaming: boolean, attempts: number) => boolean;
+/**
+ * What to do with a frame, given what the surface already holds.
+ *
+ * `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;
+/** 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
+ *
+ * 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.
+ */
+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** — 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.
+ *
+ * The `delivered !== ""` part is not defensive: re-rendering an empty buffer clears the surface.
+ */
+export declare const probeOutcome: (signature: string, current: string, streaming: boolean, delivered: string) => "stale" | "redeliver" | "store";
+export declare const 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.
+ */
+export declare const bustFetchedImports: (imports: Record<string, string>, attempt: number) => Record<string, string>;
+export declare function GenUISurface({ code, streaming, preserveState, onError, onRendered, className }: GenUISurfaceProps): import("react").JSX.Element;

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

@@ -0,0 +1,143 @@
+import { usePersistedState } from "./state.ts";
+/** What the plugin's client half lends to generated code. Registered once, at apply. */
+export type Ui4aHost = {
+    /** Sends a prompt into the current session, exactly as the composer would. */
+    send: (text: string) => void;
+    /** The current session's workspace, which the AI route authorizes against. */
+    cwd: () => string | undefined;
+    /** The open session, so a write runs under the access mode the composer shows. */
+    sessionId: () => string;
+};
+/** Named so the round trip can be tested against the real code rather than a copy of it. */
+export declare function decodeBase64(base64: string): Uint8Array<ArrayBuffer>;
+export declare function registerUi4aHost(next: Ui4aHost): () => void;
+/**
+ * The capability surface, one group per `$dsh/<group>` module.
+ *
+ * A function rather than a constant so the host can be swapped (or torn down) without the
+ * already-imported blob modules going stale — they close over `bind`, not over a host.
+ */
+export declare function bind(): {
+    chat: {
+        /**
+         * Drives the next turn from inside a card. The text is what the user would have typed:
+         * it lands in the transcript as their message, because a turn nobody can see arriving
+         * reads as the app talking to itself.
+         */
+        sendMessage: (text: string) => void;
+    };
+    ai: {
+        /**
+         * Streams text from the app's own model, one piece per network chunk.
+         *
+         * Nothing here holds a credential: the Node half forwards to `ctx.llm`, which owns the
+         * provider route and the keys. Reach for it when the *content* is the variable part —
+         * the recipe, the five candidate names — and skip it when the data is genuinely fixed.
+         */
+        streamText: (options: Ui4aStreamOptions | string) => AsyncIterable<string>;
+    };
+    fs: {
+        /** The file's text. Throws when it does not exist or the session may not read it. */
+        readFile: (path: string) => Promise<string>;
+        /**
+         * Directory entries: the name, whether it is a file or a directory, and a file's size.
+         *
+         * An array of objects rather than of names, because without `type` a card cannot draw a
+         * tree — it would have to probe every entry with a second call to find out whether it
+         * can be descended into. The host has all three already; we used to drop two of them.
+         */
+        readdir: (path: string) => Promise<Ui4aDirEntry[]>;
+        /**
+         * The file's bytes, for anything that is not text.
+         *
+         * `readFile` decodes as UTF-8, so a .mid, a wav or a png read that way comes back with
+         * every byte above 0x7f replaced by U+FFFD — corrupt, and silently so. Anything handed to
+         * `decodeAudioData`, a MIDI parser or an image decoder has to come through here.
+         */
+        readBytes: (path: string) => Promise<Uint8Array<ArrayBuffer>>;
+        /**
+         * Writes the file, subject to the session's own access mode.
+         *
+         * Under `Read Only` this rejects exactly as the model's own `write` would — the fence
+         * is the host's, not ours, so what a card may do never diverges from what the composer
+         * says the session may do.
+         */
+        writeFile: (path: string, content: string) => Promise<void>;
+    };
+    exec: {
+        /**
+         * Runs one command in the workspace and resolves with its output.
+         *
+         * A non-zero exit resolves rather than rejects: `git status` failing outside a repo is
+         * something a card wants to show, not an outage. Only a failure to run at all rejects.
+         * The session's own sandbox mode applies, so this is no wider than the model's own bash.
+         */
+        bash: (command: string, options?: {
+            signal?: AbortSignal;
+        }) => Promise<Ui4aExecResult>;
+    };
+    web: {
+        /**
+         * One web search, through whichever provider the host composed.
+         *
+         * Search only: `ctx.web` also does `fetch`, and this deployment turns that off for its own
+         * tools because the local backend can reach private-network addresses. A card wanting a page
+         * body should ask the user for it or search for a quotable source instead.
+         */
+        search: (query: string, options?: {
+            maxResults?: number;
+            signal?: AbortSignal;
+        }) => Promise<Ui4aSearchResult>;
+    };
+    state: {
+        usePersistedState: typeof usePersistedState;
+    };
+};
+/** What one search returns. Mirrors the seam's `WebSearchResult`, which is what the route forwards. */
+export type Ui4aSearchResult = {
+    /** A provider-generated answer or summary, when the provider makes one (Exa and DeepSeek do not). */
+    content?: string;
+    sources: readonly {
+        url: string;
+        title?: string;
+        snippet?: string;
+        publishedAt?: string;
+    }[];
+    /** True when the seam cut `sources` down to the requested bound. */
+    truncated: boolean;
+};
+/** What a command left behind. `truncated` means the output was cut, not that it failed. */
+export type Ui4aExecResult = {
+    stdout: string;
+    stderr: string;
+    exitCode: number | null;
+    truncated: {
+        stdout: boolean;
+        stderr: boolean;
+    };
+    timedOut: boolean;
+};
+/** One entry of a directory listing. `size` is absent for directories. */
+export type Ui4aDirEntry = {
+    name: string;
+    type?: "file" | "directory";
+    size?: number;
+};
+/** One user turn plus an optional system prompt — see the route's note on why not more. */
+export type Ui4aStreamOptions = {
+    prompt: string;
+    system?: string;
+    signal?: AbortSignal;
+};
+export declare function bindingImports(): Record<string, string>;
+export declare function releaseBindings(): void;
+/**
+ * Every module generated code can import without reaching the network: the shell's React
+ * family, plus the `$dsh/*` capabilities.
+ *
+ * Exported from the plugin's client entry as well, so `bun run smoke` can build the blob
+ * modules and parse them. They are synthesized strings that nothing type-checks, and a
+ * syntax error in one fails the way an unresolvable import does — the whole module graph
+ * dies and the card renders blank with no console error.
+ */
+export declare function localImports(): Record<string, string>;