dsh-generative-ui 0.0.1 → 0.0.3

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>;

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,50 @@
+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[];
+    /** `last` answers whether this card is still the transcript's newest — asked at report time, not render time. */
+    render: (props: {
+        code: string;
+        streaming: boolean;
+        last: () => boolean;
+    }) => ReactElement;
+    scope?: HTMLElement;
+};
+/**
+ * Whether this card's code is the last ui4a segment in the transcript.
+ *
+ * **Only the last block's failure is worth telling the model about.** An earlier card that cannot
+ * render stays in the transcript and re-renders on every later frame, so it fails again, and
+ * again, for the rest of the session — measured on a real one where the model wrote a card
+ * importing `Github` from `lucide-react` (removed upstream), was told, fixed it to `GitBranch` in
+ * the very next reply, and the failure notice kept coming back from the reply it had already
+ * superseded. The model cannot act on it: editing a message it already sent is not a thing it
+ * can do.
+ *
+ * Evaluated when the report is about to be SENT, not when the error is raised. A card is the last
+ * one at the moment it breaks and stops being so as soon as the next card appears, which is
+ * exactly the second in between.
+ *
+ * **Segments, not mounts.** Comparing DOM nodes was wrong three separate ways, all of them
+ * silent: `release` calls `claim.mount.remove()` on every markdown re-render, so a broken card
+ * followed by any trailing prose compared a detached node and dropped its own report; `defer`
+ * parks a far-offscreen block without ever creating a mount, so a reader scrolled up while the fix
+ * streams left an older card holding the last mount and reporting as though it were newest; and an
+ * empty node list has to mean false, since a session switch inside the settle window empties it
+ * while `sendToModel` reads `currentSession()` at send time — session A's error into session B's
+ * store. The segment list is the transcript's own order and survives all three.
+ */
+export declare const isLastSegment: (segments: readonly Ui4aSegment[], code: string) => boolean;
+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,64 @@
+/**
+ * Sends a card's compile error back to the model as a chat message.
+ *
+ * Until this existed, `onError` had no consumer at all: a card that failed to compile painted a
+ * red panel for the reader and the model never learned anything. Measured on a real session —
+ * a card imported `MonacoEditor` from `modern-monaco`, the surface reported *"has no export named
+ * 'MonacoEditor'; module exports: Workspace, errors, hydrate, init, lazy"*, and the transcript
+ * ends there: `MonacoEditor` appears 6 times in the records after that point and `no export named`
+ * zero. The reader saw the answer on screen; the one party who could act on it did not.
+ *
+ * Four constraints, each of which this got wrong in an obvious first version:
+ *
+ * - **Only errors that survived.** `GenUISurface` already separates a mid-stream prefix failure
+ *   and a retryable network blip from a real one — the `report` branch of its error action. That
+ *   branch is the only caller, so a half-written expression never reaches the model.
+ *
+ *   It is not sufficient on its own, though. `isUnfinishedFrame` excludes the RENDER phase by
+ *   design — a card whose own render throws is usually a real error — but a half-written
+ *   component rendering mid-stream throws too, and the next frame is fine. Measured in a browser:
+ *   a card that ultimately rendered correctly reported `Cannot read properties of undefined
+ *   (reading 'getCurrentStack')`, a React internal, to the model. Painting a red panel for a
+ *   frame costs nothing; sending the model a message about a card that then worked costs it a
+ *   turn spent fixing what is not broken. So the send is DEFERRED, and a paint cancels it.
+ * - **Once per card, not once per frame.** A settled card that fails re-renders on every later
+ *   frame of the transcript, and a turn per render is a loop the user has to kill. Deduplication
+ *   lives HOST-side now (`CardFailures.set`), because this half is thrown away by every
+ *   navigation and a dedup set that resets on reload wakes the model about a card it already
+ *   knows. What stays here is the settling, which is about frames, not about turns.
+ * - **Recovery is reported too.** The report is state, not an event: a card that starts working
+ *   sends `null`, and the host drops it out of the model's context. As a chat message that was
+ *   impossible, which is why the old body had to carry a paragraph explaining that nobody had
+ *   typed it.
+ * - **Only the newest card counts.** An earlier card that cannot render stays in the transcript
+ *   and re-renders on every later frame, so it goes on failing for the rest of the session.
+ *   Measured on a real one: the model wrote a card importing `Github` from `lucide-react`
+ *   (removed upstream), was told, fixed it to `GitBranch` in its very next reply — and the
+ *   failure notice kept coming back from the message it had already superseded. There is nothing
+ *   the model can do with that; it cannot edit a reply it has sent. `isLastSegment` is the gate, on both the report and the retraction.
+ */
+/** Exported for the test: a fresh card in a fresh session should be able to report again. */
+export declare const forgetReportedErrors: () => void;
+/** `null` means the card recovered. */
+export type ErrorReporter = (report: {
+    message: string;
+    phase: string;
+} | null) => void;
+/** Drop a report the page is going away before it can deliver. NOT a recovery — nothing is fixed. */
+export declare function cancelPendingReport(): void;
+/**
+ * Called when a surface paints. Cancels a report the very next frame made untrue.
+ *
+ * **`restored` is not a detail.** partial-react answers a render throw by re-mounting the LAST
+ * GOOD component (`runtime.ts:416-419`, whenever `preserve` is on — which is every inline card),
+ * and that re-mount paints, and painting used to cancel the report that the very same throw had
+ * just armed. So the one case the reporting exists for — a card that worked, then broke on an
+ * edit — showed the reader stale content and told the model nothing. A paint only means the card
+ * is fine when it is the NEW code that painted.
+ */
+/**
+ * @param current whether the painting card is the one the gate would let report. Defaults to
+ *   permissive for the canvas path, which shows one card at a time.
+ */
+export declare function cardRendered(restored?: boolean, current?: () => boolean): void;
+export declare function reportCardError(send: ErrorReporter | undefined, message: string, phase: string, current?: () => boolean): 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,51 @@
+/**
+ * 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";
+/**
+ * A card's surviving failure, reported by the browser half: `?session=<id>`, POST
+ * `{message, phase}` to set it and `{}` to clear it.
+ *
+ * The detail does NOT come back as a chat message. It becomes a runtime-context snapshot
+ * (`ui4a:card-failure`), which is re-evaluated per assembly and superseded by the next one, so a
+ * card that gets fixed stops being mentioned instead of leaving a stale complaint in history. The
+ * route only carries the state; `wakeAgent` is what asks the model to look at it.
+ */
+export declare const CARD_ERROR_PATH = "/dsh-generative-ui/card-error";

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;