dsh-generative-ui 0.0.1 → 0.0.2

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

@@ -0,0 +1,35 @@
+import { type RendererImportMap } from "partial-react/import-map";
+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>;
+};
+/**
+ * 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 declare const warmCompiler: () => Promise<unknown>;
+/**
+ * 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 declare function disposeCompiler(): void;
+export declare function createBrowserTsxCompiler(): TsxCompiler;

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

@@ -0,0 +1,23 @@
+import type { ReactElement } from "react";
+import type { Ui4aSegment } from "./segments.ts";
+/** Split out from `hasPainted` so the rule can be tested without a DOM. */
+export declare const isPaintedText: (text: string) => boolean;
+export declare const hasPainted: (mount: HTMLElement) => boolean;
+/** CodeBlock trims one trailing newline for display, so compare on trimmed ends. */
+export declare const sameCode: (a: string, b: string) => boolean;
+/**
+ * The segment a rendered block belongs to.
+ *
+ * Mid-stream the block shows a prefix of its segment; once settled the two are equal.
+ */
+export declare const matchSegment: (segments: readonly Ui4aSegment[], rendered: string) => Ui4aSegment | undefined;
+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 declare function claimInlineFences({ segments, render, scope }: InlineFenceOptions): () => void;

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

@@ -0,0 +1,30 @@
+/**
+ * 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;
+declare const schedule: () => void;
+/**
+ * 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 declare function observeTranscript(listener: Listener): () => void;
+/** Requests a frame outside a mutation — for state that changed without the DOM changing. */
+export declare const scheduleSweep: typeof 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 declare function resetTranscriptObservers(): void;
+export {};

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

@@ -0,0 +1,2 @@
+export declare function registerRuntimeModules(): void;
+export declare const hostReactVersion: string;

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

@@ -0,0 +1,7 @@
+/** Exported for `test/registry.test.ts`: it generates code, so a bug here is a blank card with an empty console. */
+export declare function buildModuleSource(specifier: string): string;
+export declare function registerModules(modules: Record<string, Record<string, unknown>>): void;
+export declare function moduleUrl(specifier: string): string;
+export declare const registryImports: () => Record<string, string>;
+/** Drops every synthesized blob. The plugin's dispose path must call this or each HMR round leaks one URL per specifier. */
+export declare function disposeRegistry(): void;

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

@@ -0,0 +1,17 @@
+/** Exported for the test: a fresh card in a fresh session should be able to report again. */
+export declare const forgetReportedErrors: () => void;
+export type ErrorReporter = (text: string) => void;
+/**
+ * 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 declare const reportBody: (message: string, phase: string) => string;
+/** Called when a surface paints. Cancels a report the very next frame made untrue. */
+export declare function cardRendered(): void;
+export declare function reportCardError(send: ErrorReporter | undefined, message: string, phase: string): void;

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

@@ -0,0 +1,18 @@
+export type Ui4aSegment = {
+    code: string;
+    complete: boolean;
+};
+/**
+ * Tool-call markup the model leaked into its own prose. The reply ends mid-fence with the
+ * closing tags glued to the last line of TSX, so the body reaches the compiler with those tags
+ * in it and fails to parse — the whole card is lost, not just the closing fence.
+ *
+ * Two spellings, and the rarer one was found first: `</parameter></invoke>` appeared once in
+ * the corpus, while the model's own `</｜｜DSML｜｜parameter>` form accounts for three more and
+ * was invisible to a regex written from that single sample. Those full-width bars are U+FF5C,
+ * not ASCII `|`. Only stripped at the very end of an unterminated body, where nothing
+ * legitimate can follow — which is true of a closed fence too: the model leaks the tags and then
+ * still writes the closing fence, and stripping only the unterminated case loses that card outright.
+ */
+export declare const TOOL_CALL_MARKUP: RegExp;
+export declare function parseUi4aSegments(text: string): Ui4aSegment[];

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

@@ -0,0 +1,18 @@
+/**
+ * `$dsh/state` — the one capability the model asks for without being told it exists.
+ *
+ * Three runs of a habit-tracker prompt each wrote `import { usePersistedState } from "$dsh/state"`
+ * against a module that did not exist, which does not degrade: the browser refuses the module and
+ * the card renders blank. Rewording the skill to deny it did not help — the prior survives the
+ * denial. So the module exists now, with the signature all three runs assumed.
+ *
+ * Unlike the other capabilities this needs nothing from the host: `localStorage` and React are
+ * both already there. That is also why it is worth having — the alternative the skill used to
+ * prescribe is fifteen lines of try/catch that every card rewrites and half of them skip.
+ */
+import * as React from "react";
+/**
+ * `useState`, except the value survives a reload — and, more often, survives the remount that
+ * every canvas revision and every inline transcript re-render causes.
+ */
+export declare function usePersistedState<T>(key: string, initial: T | (() => T)): [T, React.Dispatch<React.SetStateAction<T>>];

package/lib/types/client/runtime/uno-config.d.ts

@@ -0,0 +1,16 @@
+import type { UserConfig } from "@unocss/core";
+/**
+ * Two things the host forces on this config, both non-negotiable:
+ *
+ * `important` receives a SELECTOR STRING, which is how UnoCSS scopes: every rule comes out
+ * `.ui4a-root :is(.gap-4){…}`. The runtime sheet is appended to `<head>` last, so an unscoped
+ * `hidden` written by a card would win over the shell's own `hidden` and make part of the app
+ * vanish. The playground has that bug on record (a sidebar disappearing); we start scoped.
+ *
+ * `preflights: { reset: false }` drops presetWind4's global reset — 3.5KB of `*, ::before,
+ * ::after { margin: 0; border: 0 solid }` that would land on the HOST's DOM, not just ours.
+ * The `theme` layer survives it and is the part we need: `--spacing` and `--radius-*`, which
+ * every `gap-*` and `rounded-*` resolves against. Without preflights entirely those rules
+ * generate but compute to nothing.
+ */
+export declare const unoConfig: (scope: string) => UserConfig;

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

@@ -0,0 +1,50 @@
+/**
+ * Runtime UnoCSS for generated cards.
+ *
+ * A build-time pass would scan OUR source, and the classes a card is written with do not exist
+ * there — they are typed by the model seconds ago. Responsive is where that shows worst: not one
+ * `@container` breakpoint would be generated, so every card would be single-column at any width.
+ * The CSS therefore has to be produced in the browser, as the code streams in.
+ *
+ * Accumulate rather than replace: several cards share one document, and each one's classes must
+ * stay in the sheet after another card is added.
+ */
+/**
+ * The class every generated rule is prefixed with, and the one the surface carries.
+ *
+ * Named after the contract rather than after this plugin: the same class exists in
+ * `ui4a-playground` under the same constant name, so the two runtimes can be diffed line for
+ * line. It is also the only marker on the surface node — a second `data-*` hook naming the same
+ * thing was removed because nothing read it.
+ */
+export declare const UI4A_ROOT_CLASS = "ui4a-root";
+/**
+ * Per frame this does the two cheap things only: EXTRACT the class names out of the code
+ * (no CSS generated), and generate CSS for the ones not seen before.
+ *
+ * The expensive spellings, both measured in the playground this is ported from:
+ * `uno.generate(code)` regenerates every class in the file each time — 119s of main thread over
+ * one streaming canvas; and regenerating the whole accumulated token set on each new class costs
+ * more the longer the file gets. Throttling does not help when a single call is what is
+ * expensive.
+ *
+ * Appended rules sort after existing ones, so two same-priority utilities can resolve differently
+ * than a single authoritative pass would. Once the stream settles we regenerate the whole set to
+ * restore that order.
+ */
+export declare function ensureUnoStyles(code: string, streaming?: boolean): Promise<void>;
+/**
+ * Split a rule whose selector list mixes vendor pseudo-elements into one rule per vendor.
+ *
+ * UnoCSS merges selectors that share a declaration, so a card styling a slider for both engines
+ * gets `…::-moz-range-thumb, …::-webkit-slider-thumb { height: … }` as ONE rule — and Chromium
+ * drops the whole rule because it does not recognise the `-moz-` half. Measured: the browser
+ * parsed 75 of the 87 rules in a real card's sheet, the slider came out `height: 0px`, and the
+ * card shipped three invisible controls. Order does not matter and neither does which vendor is
+ * first; one unknown pseudo-element poisons the list.
+ *
+ * The model is doing the right thing by writing both prefixes, so the fix belongs here.
+ */
+export declare function splitVendorRules(css: string): string;
+/** Drops the sheet and the generator. HMR reloads the module; the old sheet must not survive it. */
+export declare function disposeUnoStyles(): void;

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

@@ -0,0 +1,26 @@
+/**
+ * Reading the current session's chat nodes.
+ *
+ * Both consumers — inline fences and canvases — need the same unwrap, and both run it on
+ * every frame while a reply streams. Sharing it keeps the guards in one place, and lets
+ * the per-node work be cached against a node's identity rather than redone per frame.
+ */
+import type { ClientContext } from "@deepseek-ai/dsh-client-runtime/client";
+export type ChatNodeView = {
+    readonly kind: string;
+    readonly data: unknown;
+    readonly anchorSeq: number;
+};
+/** The current session's chat nodes, or an empty list when no session is open. */
+export declare function chatNodes(ctx: ClientContext): readonly ChatNodeView[];
+/**
+ * Derives a value per chat node, reusing the previous result when the node has not changed.
+ *
+ * A sweep runs on every frame of a streaming reply, but only the tail node is actually
+ * growing — re-deriving finished nodes means re-scanning the whole transcript dozens of
+ * times a second, which grows with session length rather than with what changed.
+ *
+ * @param key - identity of a node's current content; equal keys must mean equal results.
+ * @param derive - the per-node work to memoize.
+ */
+export declare function perNode<T>(key: (node: ChatNodeView) => string, derive: (node: ChatNodeView) => T): (nodes: readonly ChatNodeView[]) => T[];

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

@@ -0,0 +1,41 @@
+/**
+ * Asset URLs shared by both halves. Kept apart from index.ts so the browser half
+ * can import them without dragging node:fs and createRequire into its bundle.
+ */
+export declare const ASSET_PREFIX = "/dsh-generative-ui/assets";
+export declare const WASM_PATH = "/dsh-generative-ui/assets/tsx_bg.wasm";
+/** Reads one canvas file from the session's workspace: `?cwd=<workspace>&id=<canvas>`. */
+export declare const CANVAS_READ_PATH = "/dsh-generative-ui/canvas";
+/**
+ * Streams one model call for a generated card: POST `{prompt|messages, system?}`.
+ *
+ * The host owns the credentials and the provider route, so this forwards to `ctx.llm`
+ * rather than carrying a key of its own.
+ */
+export declare const AI_STREAM_PATH = "/dsh-generative-ui/ai";
+/**
+ * Filesystem access for a generated card: `?cwd=<workspace>&path=<path>`.
+ *
+ * GET reads (or lists, with `?list=1`), POST writes. Both go through the host's `ctx.fs`
+ * and carry the session's own sandbox policy, so what a card may do is exactly what the
+ * session may do — `read-only` denies the write at the fence rather than here.
+ */
+export declare const FS_PATH = "/dsh-generative-ui/fs";
+/**
+ * Runs one command for a generated card: `?cwd=<workspace>&session=<id>`, POST `{command}`.
+ *
+ * Under the session's own sandbox policy, exactly as `FS_PATH` is — a read-only session gets
+ * a read-only shell rather than a different fence. Foreground only: a card that wants a
+ * long-running process wants a different product.
+ */
+export declare const EXEC_PATH = "/dsh-generative-ui/exec";
+/**
+ * One web search for a generated card: `?cwd=<workspace>`, POST `{query, maxResults?}`.
+ *
+ * Search only. `ctx.web` also exposes `fetch`, and this deliberately does not forward it: the
+ * deployment's own `tool-web` is configured `fetch: false`, and the doc says why — *"the local
+ * backend does not block private-network targets; do not enable web_fetch where it can reach
+ * sensitive internal ones."* A card is model-written code firing on a reader's keystrokes, so
+ * re-opening from here what the host closed for its own tools is not ours to do.
+ */
+export declare const WEB_SEARCH_PATH = "/dsh-generative-ui/web-search";

package/lib/types/contract.d.ts

@@ -0,0 +1,56 @@
+/**
+ * The ui4a path contract — the single place that decides what counts as a canvas.
+ * Shared by both halves; never re-derive these patterns with an inline regex.
+ */
+/**
+ * Where generated files live, under the workspace's own dsh directory.
+ *
+ * `.dsh/` is the harness's project convention, not ours — `dsh-skill-filesystem` reads
+ * `join(projectRoot, ".dsh/skills")` and labels that source `project-dsh`. Sitting beside
+ * it keeps a plain `ls` of the user's repo clean and puts our files where they would look
+ * for anything dsh wrote. `ui4a` beneath it names the format, which is the honest nesting:
+ * this is a dsh plugin writing ui4a files, not a ui4a project with a dsh corner.
+ */
+export declare const UI4A_DIR = ".dsh/ui4a";
+export declare const CANVAS_DIR = ".dsh/ui4a/canvases";
+export declare const CANVAS_SUFFIX = ".ui4a.tsx";
+/**
+ * Info string of an inline fence, as the model writes it. Slash, not dash — matches
+ * ui4a-playground. Note the host's markdown renderer truncates it at the first
+ * non-identifier character, so it reaches the DOM as `ui4a`; nothing matches on it.
+ */
+export declare const FENCE_LANG = "ui4a/tsx";
+/**
+ * Import prefix for the capabilities the plugin lends to generated code.
+ *
+ * `$dsh/`, not `$ui4a/`: what these expose is the harness — the conversation, its model,
+ * its filesystem — and none of it is part of the ui4a rendering contract that `FENCE_LANG`
+ * and the canvas paths above define. A card written against them only runs inside dsh.
+ */
+export declare const CAPABILITY_PREFIX = "$dsh";
+export declare const capabilityModule: (group: string) => string;
+export declare const isCanvasId: (id: string) => boolean;
+export declare const canvasPath: (id: string) => string;
+export declare const canvasChildDir: (id: string) => string;
+/**
+ * Resolves a relative specifier written inside a canvas to a workspace path.
+ *
+ * `from` is the path the specifier was written in — the canvas file itself, or one of its
+ * children — because **a relative specifier is relative to its importer, not to the canvas
+ * root**. The entry writes `./<id>/board`; a child of that entry writes `./types` for its
+ * sibling, and resolving both against the canvases directory sends the second one nowhere.
+ * Measured on a real split: the model produced 7 files whose cross-imports are all sibling
+ * form, and every one of them resolved to null before `from` existed.
+ *
+ * Every segment goes through the same exclusion test as an id, and the result must stay
+ * inside `canvasChildDir(id)` — `..` is rejected outright rather than normalised, so there
+ * is no arithmetic that could walk out.
+ *
+ * Returns null for anything outside that shape rather than throwing: the caller is a route
+ * answering an arbitrary page, and a bad specifier is a 400, not a crash.
+ */
+export declare function canvasChildPath(id: string, specifier: string, from?: string): string | null;
+/** The canvas id of an entry path, or null when the path is not a canvas entry. */
+export declare function canvasIdOf(path: string): string | null;
+/** The owning canvas of any path under the contract — entry file or child module. */
+export declare function owningCanvasIdOf(path: string): string | null;

package/lib/types/index.d.ts

@@ -0,0 +1,255 @@
+/**
+ * Host half — serves the @esm.sh/tsx wasm the browser half compiles TSX with.
+ *
+ * The shell's /plugins route hard-codes the `/client.js` and `/client.js.map`
+ * suffixes and 404s everything else, and dsh-host-frontend-static owns the sole
+ * fallback seat (and answers misses with index.html + 200, so dropping the wasm
+ * there would fail as a confusing magic-word error). A plugin-owned webServer
+ * route is the way to ship bytes; dsh-latex-tools serves MathJax the same way.
+ * @module dsh-generative-ui
+ */
+import type { IncomingMessage, ServerResponse } from "node:http";
+import type { Context } from "@deepseek-ai/cordis";
+import z from "@deepseek-ai/schemastery";
+export declare const name = "dsh-generative-ui";
+export declare const inject: string[];
+/** The settings section this plugin owns; the key under `dsh-generative-ui:` in settings.yaml. */
+export declare const SETTINGS_NAMESPACE: import("@deepseek-ai/dsh-settings").SettingsNamespace;
+/**
+ * Plugin settings. A schemastery schema, not a TypeScript type: the host validates the
+ * `settings.yaml` section against it and builds the settings UI from it, so a plain interface
+ * would be a switch nobody can find and nobody can check.
+ *
+ * `allowExec` is off by default and that default is the point. `$dsh/fs` is bounded — it takes a
+ * workspace-relative path and runs under the session's sandbox policy, so the worst it reaches is
+ * a file the user could have opened anyway. `$dsh/exec` takes an arbitrary command string, and a
+ * card is code a MODEL wrote, running in the user's browser, firing on their keystrokes. The
+ * sandbox policy still applies, but "whatever the agent's own bash tool may do" is a much larger
+ * surface than a path — and the user never approves a card's commands the way they approve the
+ * agent's.
+ */
+export declare const Config: z<Schemastery.ObjectS<{
+    allowExec: z<boolean, boolean>;
+}>, Schemastery.ObjectT<{
+    allowExec: z<boolean, boolean>;
+}>>;
+export type Config = ReturnType<typeof Config>;
+export { ASSET_PREFIX, WASM_PATH } from "./contract-assets.ts";
+/**
+ * An absolute path to one of the package's import maps, or undefined when it is not there.
+ *
+ * `existsSync` is the point. `fileURLToPath` only rejects a malformed URL — it happily returns a
+ * path to a file that does not exist, which is what this used to do: installed in a shape where
+ * the package root is not two levels up, the skill was handed a path that resolves to nothing
+ * and told the model to pass it to `-i`. The failure then surfaces as `genui check` reporting
+ * `Cannot find module "$dsh/fs"` on correct code, and the model "fixes" imports that were right.
+ */
+export declare const resolvedMap: (relative: string, importMetaUrl: string) => string | undefined;
+/** Exported for `test/routes.test.ts`: a prefix route that stops checking its pathname serves the whole prefix. */
+export declare function serveAsset(req: IncomingMessage, res: ServerResponse, file: string): Promise<void>;
+/**
+ * Serves one canvas file's current contents, or — with no `id` — the ids of every canvas
+ * in the workspace.
+ *
+ * The client could reconstruct a canvas from `write` tool arguments alone, and does while
+ * a write streams — but a model routinely follows a write with several `edit` calls, whose
+ * arguments carry a patch rather than the file. Reading the file is the only source that
+ * stays correct across every way it can change, including edits made outside the agent.
+ *
+ * Confined to the canvas directory by construction — the id is a path segment and the path
+ * is built from the contract — and to a live session's own workspace by the `cwd` check.
+ *
+ * That check is the security boundary, not a formality. This route answers any page the
+ * user has open: a simple GET triggers no preflight, so without it `?cwd=/anywhere` turns
+ * the plugin into a file-existence oracle for the whole disk. The client only ever sends
+ * the cwd it read off the current session, so matching against live sessions costs nothing.
+ */
+/** Exported for `test/routes.test.ts`: the listing is the launcher's only source of truth and had no test. */
+export declare function serveCanvas(liveWorkspaces: () => ReadonlySet<string>, req: IncomingMessage, res: ServerResponse): Promise<void>;
+/** Context shape for the filesystem route; see the SessionStoreCtx note on why it is local. */
+type FsCtx = {
+    fs: {
+        resolve: (path: string, opts?: {
+            cwd?: string;
+        }) => Promise<FsTargetLike>;
+        readText: (target: FsTargetLike) => Promise<string>;
+        readBytes: (target: FsTargetLike, signal: AbortSignal | undefined, maxBytes: number) => Promise<Uint8Array>;
+        listDir: (target: FsTargetLike) => Promise<{
+            name: string;
+            type?: string;
+            size?: number;
+        }[]>;
+        writeText: (target: FsTargetLike, content: string, expected?: undefined, signal?: AbortSignal, policy?: unknown) => Promise<unknown>;
+    };
+    sandboxPolicy: {
+        resolve: (request?: {
+            session?: unknown;
+        }) => unknown;
+    };
+    sessions: {
+        list: () => readonly {
+            id?: string;
+            header: {
+                cwd?: string;
+            };
+        }[];
+    };
+};
+type FsTargetLike = {
+    targetKey: unknown;
+    displayPath: string;
+};
+/**
+ * Reads, lists, and writes on behalf of a generated card.
+ *
+ * Everything goes through the host's `ctx.fs` carrying the session's own
+ * `ctx.sandboxPolicy`, so **a card may do exactly what the session may do** — under
+ * `read-only` the write is refused by the same fence that refuses the model's, with the
+ * same structured denial. Inventing a narrower boundary here would mean a second policy to
+ * keep in sync with the one the user actually sees in the composer.
+ *
+ * The `cwd` allowlist is still required, for the reason the canvas route documents: any page
+ * the user has open can call this, so without it the workspace is not the workspace.
+ */
+/** Exported for `test/fs-route.test.ts`. */
+export declare function serveFs(ctx: FsCtx, liveWorkspaces: () => ReadonlySet<string>, req: IncomingMessage, res: ServerResponse): Promise<void>;
+/** Context shape for the shell route. `resolve` fills the executor's own defaults and caps. */
+type ExecCtx = {
+    shell: {
+        resolve: (request: {
+            command: string;
+            workdir?: string;
+            timeoutMs?: number;
+            sandboxPolicy?: unknown;
+            signal?: AbortSignal;
+        }) => unknown;
+        run: (spec: unknown) => Promise<{
+            exitCode: number | null;
+            signal?: string | null;
+            timedOut?: boolean;
+            stdout: {
+                text: string;
+                truncated: boolean;
+            };
+            stderr: {
+                text: string;
+                truncated: boolean;
+            };
+        }>;
+    };
+    sandboxPolicy: {
+        resolve: (request?: {
+            session?: unknown;
+        }) => unknown;
+    };
+    sessions: {
+        list: () => readonly {
+            id?: string;
+            header: {
+                cwd?: string;
+            };
+        }[];
+    };
+};
+/**
+ * Runs one command on behalf of a generated card.
+ *
+ * The whole point is that a card can answer questions only a command can answer — git
+ * history, a test run, ripgrep across a big tree — without us re-implementing each one as a
+ * route. It carries the session's own sandbox policy, so this opens no door the model's own
+ * bash tool does not already have open, and a read-only session gets a read-only shell.
+ *
+ * A non-zero exit is a RESULT, not an error: a card wants to show `git status` failing in a
+ * non-repo as much as it wants to show it succeeding. Only infrastructure failures reject.
+ *
+ * **Why this does not go through `ctx.approval`, which is the seam for "may this action
+ * proceed?".** It is the right question and dsh's own `tool-bash` asks it — but the service
+ * cannot answer it here. `approval.request()` takes an `agent` and throws outright when the
+ * session has no open turn: *"approval.request() outside an open turn … Ask from inside the turn
+ * that needs the decision."* A card's command is the opposite of that — it fires on the reader's
+ * keystroke, long after the turn that wrote the card ended, with no agent on whose behalf to ask.
+ * `ctx.userQuestions.ask()` DOES work outside a turn (its `agent` is optional), so a per-command
+ * prompt is buildable; what stops it is that a card runs one command per keystroke, and a dialog
+ * per keystroke is not a safety feature. The setting is therefore about whether the CAPABILITY
+ * exists, and the per-command fence remains the session's own sandbox policy, which this passes
+ * through unchanged. Anything genuinely destructive belongs in `sendMessage`, where the user's
+ * next turn — and with it the whole approval machinery — is what runs it.
+ */
+/** Exported for `test/exec-route.test.ts`. */
+export declare function serveExec(ctx: ExecCtx, liveWorkspaces: () => ReadonlySet<string>, req: IncomingMessage, res: ServerResponse): Promise<void>;
+/** Context shape for the search route. Only the two methods it calls, so a fake in a test is small. */
+type WebCtx = {
+    web: {
+        search: (request: {
+            query: string;
+            maxResults?: number;
+        }, signal?: AbortSignal) => Promise<{
+            content?: string;
+            sources: readonly {
+                url: string;
+                title?: string;
+                snippet?: string;
+                publishedAt?: string;
+            }[];
+            truncated: boolean;
+        }>;
+    };
+};
+/**
+ * Runs one web search on behalf of a generated card.
+ *
+ * A card that wants live information — a price, a release date, what a package exports — otherwise
+ * has nothing: `fetch` from inside the surface is not the shape (no credentials, no CORS, no
+ * provider selection), and routing the question through `$dsh/ai` asks a model to recall rather
+ * than to look. `ctx.web` already owns provider selection, the result shape, and the truncation
+ * bound, so this forwards and does not re-decide any of it.
+ *
+ * SEARCH ONLY — see `WEB_SEARCH_PATH` for why `fetch` is not forwarded.
+ *
+ * `WebError` carries a `code` and the seam's own contract calls that set OPEN: a provider may
+ * raise a code this build has never seen. So the error is passed through as text rather than
+ * matched on, and the card decides what to show.
+ */
+/** Exported for `test/web-search-route.test.ts`. */
+export declare function serveWebSearch(ctx: WebCtx, liveWorkspaces: () => ReadonlySet<string>, req: IncomingMessage, res: ServerResponse): Promise<void>;
+/** Context shape for the two services the AI route needs; see the SessionStoreCtx note. */
+type LlmCtx = {
+    llm: {
+        stream: (options: {
+            provider: string;
+            model: string;
+            messages: readonly unknown[];
+            system?: string;
+            signal?: AbortSignal;
+        }) => AsyncIterable<{
+            type: string;
+            text?: string;
+            reason?: {
+                kind: string;
+                failure?: {
+                    message?: string;
+                };
+            };
+        }>;
+    };
+    agentDefaultModel: {
+        currentSelection: () => {
+            provider: string;
+            model: string;
+        };
+    };
+};
+/**
+ * Streams one model call on behalf of a generated card.
+ *
+ * The card cannot call a provider itself — it has no credentials and should never be given
+ * any. `ctx.llm` already owns the adapter registry, the retry policy and the keys, and
+ * `agentDefaultModel` owns which model the app is set to, so this route is a forwarder:
+ * it converts a small JSON request into `llm.stream` and pipes the text deltas back.
+ *
+ * Same `cwd` allowlist as the canvas route, and for the same reason: any page the user has
+ * open can POST here, so without it this is an open model proxy for anything on the machine.
+ */
+/** Exported for `test/ai-route.test.ts`. */
+export declare function serveAi(ctx: LlmCtx, liveWorkspaces: () => ReadonlySet<string>, req: IncomingMessage, res: ServerResponse): Promise<void>;
+export declare function apply(ctx: Context, config?: Config): void;

package/lib/types/prompt.d.ts

@@ -0,0 +1,13 @@
+export declare const PROMPT_SECTION_NAME = "dsh-generative-ui:inline";
+/** After tool guidance (100–199): this describes an output format, not the harness identity. */
+export declare const PROMPT_SECTION_ORDER = 210;
+/**
+ * The section, built for the capabilities this host actually exposes.
+ *
+ * `allowExec` is not cosmetic here. The closed-set sentence below ("these are the whole set") is
+ * load-bearing — it is what stops the model reasoning its way to a plausible sixth import — so it
+ * has to name the set that EXISTS. Documenting `$dsh/exec` on a host where the route is not
+ * registered teaches the model to write cards whose import fails, and a failed import takes the
+ * whole module down: the reader gets a blank card with nothing on screen naming the cause.
+ */
+export declare const inlinePrompt: (allowExec?: boolean) => string;

package/lib/types/skill.d.ts

@@ -0,0 +1,27 @@
+export declare const SKILL_NAME = "generative-ui";
+export declare const SKILL_DESCRIPTION = "How to decide between an inline ui4a/tsx block, a canvas file, and plain prose \u2014 and how to lay one out so it reads. Load it **before you decide**, not after \u2014 including when your first instinct is that prose is enough. Most of the questions that should have been an interface do not ask for one.";
+/**
+ * The skill body.
+ *
+ * A function of the import-map path because that path is only known at runtime — the plugin
+ * lives wherever the profile installed it, and the model runs the checker from the workspace.
+ * Without the map, `check` reports `Cannot find module "$dsh/chat"` on every card that uses
+ * one, and a false error is worse than no check: the model goes and "fixes" it.
+ */
+/**
+ * The paragraph about which import map serves which command.
+ *
+ * Built here rather than inline: nesting one template interpolation inside another inside the
+ * body is how this file broke twice, and the two maps have genuinely different lifetimes —
+ * the type one may exist while the stub one does not.
+ */
+/** Exported for `test/skill.test.ts`: three states, and this file has broken on them twice. */
+export declare function mapNotes(typesMap: string | undefined, standaloneMap: string | undefined): string;
+/**
+ * The skill, for the capabilities this host exposes.
+ *
+ * With commands off the whole `## Running a command` section is cut rather than softened: it is
+ * ~90 lines that all assume `bash()` exists, and half a section describing a capability the host
+ * does not have is worse than none — the model reads the surviving half as permission.
+ */
+export declare const skillBody: (typesMap: string | undefined, standaloneMap: string | undefined, allowExec?: boolean) => string;