dsh-generative-ui 0.0.0 → 0.0.2

package/src/client/runtime/segments.ts

@@ -0,0 +1,116 @@
+/**
+ * Splits assistant prose into markdown and inline-ui4a segments.
+ *
+ * Ported from ui4a-playground/src/components/chat/segments.ts. We only consume the ui4a
+ * side — the host renders the markdown — but the parser must still walk the whole text,
+ * because a fence's position depends on everything before it.
+ */
+import { FENCE_LANG } from "../../contract.ts";
+
+export type Ui4aSegment = { code: string; complete: boolean };
+
+/**
+ * Opening fence. Both tolerances here were measured; do not tighten them.
+ *
+ * - **The fence need not start a line.** The prompt says "on its own line", but the model
+ *   routinely continues it straight after a sentence (`……完整元素周期表。\`\`\`\`ui4a/tsx`).
+ *   Anchoring with `^` drops that whole reply back to markdown, and hundreds of lines of
+ *   TSX get pasted into the conversation as prose — far worse than a loose match. So the
+ *   only requirement is that a backtick does not precede it (which would cut a longer
+ *   fence in half).
+ * - **No newline is required after the language.** Same cause: the model glues the first
+ *   line of code onto the fence line. `[^\n]*` was there for meta like `title=`, and it
+ *   swallows that code too — hence `inlineCode` below hands it back.
+ */
+const FENCE = new RegExp(String.raw`(?<!\x60)(\x60{3,})${FENCE_LANG.replace("/", "\\/")}([^\n]*)(\n|$)`);
+
+/**
+ * Where the closing fence is, or `-1`.
+ *
+ * Try the line-anchored form first (nearly every case) and only then scan for an inline
+ * one. Running the permissive regex alone would make the lookbehind re-test at every
+ * character — and the closing fence is absent for the whole streaming phase, so that is
+ * the most expensive possible scan of the whole body, once per frame (measured on a 25KB
+ * body: 1µs → 121µs).
+ */
+function findClose(body: string, fence: string): number {
+  const anchored = body.indexOf(`\n${fence}`);
+  if (anchored >= 0 && /^[^\S\n]*(?:\n|$)/.test(body.slice(anchored + 1 + fence.length)) && body[anchored + 1 + fence.length] !== "`") return anchored + 1;
+  for (let at = body.indexOf(fence); at >= 0; at = body.indexOf(fence, at + 1)) {
+    if (body[at - 1] === "`" || body[at + fence.length] === "`") continue;
+    if (/^[^\S\n]*(?:\n|$)/.test(body.slice(at + fence.length))) return at;
+  }
+  // A closer SHORTER than the opener. Markdown says this does not close the fence, and the
+  // model writes it anyway: 18 of 385 openers in the corpus are closed by a shorter run
+  // (`open=6 close=4` nine times), and each one is a card that streams forever because nothing
+  // ever ends it. Accepting any standalone run of three-plus rescues 16 and cuts 0 short — the
+  // single card where a shorter run precedes the matching one had closed itself twice, so
+  // cutting at the first is the same body. Tried last so an exact match always wins.
+  const short = /(?:^|\n)[^\S\n]*(`{3,})[^\S\n]*(?:\n|$)/.exec(body);
+  return short === undefined || short === null ? -1 : short.index + (short[0].startsWith("\n") ? 1 : 0);
+}
+
+/**
+ * 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 const TOOL_CALL_MARKUP = /\n?(?:<\/(?:antml:|｜｜DSML｜｜)?(?:parameter|invoke|tool_calls)>\s*)+$/;
+
+/**
+ * The prompt asks for four backticks — generated TSX contains triple-backtick strings often
+ * enough that a triple-backtick fence would be closed early by its own body. Three or more
+ * are accepted anyway: models do not always comply, and one backtick short should not
+ * demote the whole block to a plain code listing. The closing fence matches the opening
+ * length, so the four-backtick form still tolerates triples inside.
+ *
+ * An unterminated fence still yields a segment with `complete: false` — that is exactly the
+ * frame a streaming reply is in, and rendering it is the entire point.
+ */
+const CODE_LINE = /^(import|export|const|function|type|interface|let|\/\/)\b/;
+const FENCE_META = /^[\w-]+=/;
+
+export function parseUi4aSegments(text: string): Ui4aSegment[] {
+  const segments: Ui4aSegment[] = [];
+  let rest = text;
+  while (true) {
+    const open = FENCE.exec(rest);
+    if (open === null) return segments;
+    // Leftovers after `ui4a/tsx` on the fence line: normally empty (or meta like `title=`),
+    // but the model sometimes puts the first line of code there. If it looks like code,
+    // hand it back as the body's first line rather than dropping it.
+    const trailing = open[2].trim();
+    const bodyStart = open.index + open[0].length;
+    // A fence opener the model is *talking about* rather than opening. Measured: 19 of 405
+    // openers in the corpus are prose, and 14 of them put the sentence right after the
+    // language (`\`\`\`\`ui4a/tsx\`\`\`\` 块，原地渲染成…`). Anything that is not code and not
+    // `key=value` meta is one; skipping the whole opener costs 0 of 390 real cards.
+    if (trailing !== "" && !CODE_LINE.test(trailing) && !FENCE_META.test(trailing)) {
+      rest = rest.slice(bodyStart);
+      continue;
+    }
+    // A wrapper: the model opened a wider fence and then opened the real one inside it, the way
+    // this project's own prompt shows the block (`\`\`\`\`\`` around `\`\`\`\`ui4a/tsx`). Taking the
+    // outer one gives a body that is the inner fence AS TEXT — which compiles, silently, to a
+    // card that renders nothing. Once in 389 corpus openers, and it costs the reader the card.
+    if (/^[^\S\n]*`{3,}ui4a\/tsx/.test(rest.slice(bodyStart))) {
+      rest = rest.slice(bodyStart);
+      continue;
+    }
+    const inlineCode = CODE_LINE.test(trailing) ? `${trailing}\n` : "";
+    const closeIndex = findClose(rest.slice(bodyStart), open[1]);
+    if (closeIndex === -1) {
+      segments.push({ code: (inlineCode + rest.slice(bodyStart)).replace(TOOL_CALL_MARKUP, ""), complete: false });
+      return segments;
+    }
+    segments.push({ code: (inlineCode + rest.slice(bodyStart, bodyStart + closeIndex)).replace(TOOL_CALL_MARKUP, ""), complete: true });
+    rest = rest.slice(bodyStart + closeIndex).replace(new RegExp(String.raw`^${open[1]}[^\n]*\n?`), "");
+  }
+}

package/src/client/runtime/state.ts

@@ -0,0 +1,47 @@
+/**
+ * `$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";
+
+/** Namespaced so two cards picking the same obvious key ("todos") do not read each other's data. */
+const scope = (key: string) => `dsh-genui:${key}`;
+
+function read<T>(key: string, initial: T | (() => T)): T {
+  // `initial` may be a lazy initialiser — the idiom `useState` teaches, and what a card writing
+  // `usePersistedState(KEY, loadFromSomewhere())` ends up passing by accident either way.
+  const fallback = () => (typeof initial === "function" ? (initial as () => T)() : initial);
+  try {
+    const raw = globalThis.localStorage?.getItem(scope(key));
+    return raw === null || raw === undefined ? fallback() : (JSON.parse(raw) as T);
+  } catch {
+    // Private mode, a full quota, or a value someone else wrote that is not JSON. A tracker that
+    // starts empty is worth more than one that throws during render.
+    return fallback();
+  }
+}
+
+/**
+ * `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 function usePersistedState<T>(key: string, initial: T | (() => T)): [T, React.Dispatch<React.SetStateAction<T>>] {
+  const [value, setValue] = React.useState<T>(() => read(key, initial));
+  React.useEffect(() => {
+    try {
+      globalThis.localStorage?.setItem(scope(key), JSON.stringify(value));
+    } catch {
+      // Quota or private mode. The card keeps working in memory; failing the write must not
+      // fail the render.
+    }
+  }, [key, value]);
+  return [value, setValue];
+}

package/src/client/runtime/uno-config.ts

@@ -0,0 +1,71 @@
+import { presetWind4 } from "@unocss/preset-wind4";
+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 const unoConfig = (scope: string): UserConfig => ({
+  presets: [presetWind4({ important: scope, preflights: { reset: false } })],
+  // The reset above is dropped because it targets `*` and would land on the HOST's DOM. But
+  // dropping it leaves form controls carrying the browser's own chrome, and that is not
+  // theme-aware: measured on a card in dark mode, two unselected `<button>`s rendered as light
+  // grey blocks with black text, because a button with no background class falls back to the UA's
+  // `buttonface`. The card looked right in light and broken in dark, which is the failure this
+  // whole colour system exists to prevent.
+  //
+  // So: the same normalisation, scoped to our root.
+  //
+  // `box-sizing: border-box` is in here for the same reason, and I left it out at first on the
+  // theory that cards set their own sizing. They cannot: `w-full` is `width: 100%`, and under the
+  // UA's `content-box` that 100% is the content alone, so every `<input className="w-full px-3
+  // border">` is padding-plus-border wider than its parent. Measured on wave 2 — every card with a
+  // text field overflowed its own edge by 10px at 320, 440 AND 720, which is the tell that it was
+  // never a breakpoint problem. The clip in a screenshot is taken at the card width, so the
+  // overflowing strip is not cut off, it is absent.
+  preflights: [
+    {
+      // Same class of bug as box-sizing: a card writes `<ul className="grid gap-1.5">`, which is
+      // correct — a grid list has no use for UA markers — and dropping the reset put them back, so
+      // a column of stray bullets sits OUTSIDE the card border at every width. Not something to
+      // ask the model to write `list-none` for on every list.
+      getCSS: () => `${scope} *, ${scope} *::before, ${scope} *::after { box-sizing: border-box; }
+      ${scope} ul, ${scope} ol { list-style: none; margin: 0; padding: 0; }
+      ${scope} button, ${scope} input, ${scope} select, ${scope} textarea {
+        background: transparent; color: inherit; font: inherit; border: 0 solid; cursor: pointer;
+      }
+      ${scope} input, ${scope} select, ${scope} textarea { cursor: auto; }`,
+    },
+  ],
+  theme: {
+    colors: {
+      // The host's 12 semantic tokens, under names short enough to write in a class.
+      // A card can still reach any variable through an arbitrary value: `bg-[var(--dsw-…)]`.
+      // NOT `base`: `text-base` is Wind4's body font size, and a colour of that name wins the
+      // token, so `<h2 className="text-base">` computed `color: #ffffff` on a white card — present,
+      // laid out, invisible, and no probe can see it. 18 corpus cards wrote `text-base`.
+      page: "var(--dsw-alias-bg-base)",
+      layer: "var(--dsw-alias-bg-layer-1)",
+      "layer-2": "var(--dsw-alias-bg-layer-2)",
+      line: "var(--dsw-alias-border-l1)",
+      "line-2": "var(--dsw-alias-border-l2)",
+      label: "var(--dsw-alias-label-primary)",
+      muted: "var(--dsw-alias-label-secondary)",
+      accent: "var(--dsw-alias-state-business-primary)",
+      hover: "var(--dsw-alias-interactive-bg-hover)",
+      danger: "var(--dsw-alias-state-error-primary)",
+      success: "var(--dsw-alias-state-success-primary)",
+      warn: "var(--dsw-alias-state-warn-primary)",
+    },
+  },
+});

package/src/client/runtime/uno.ts

@@ -0,0 +1,124 @@
+import { createGenerator, type UnoGenerator } from "@unocss/core";
+import { unoConfig } from "./uno-config.ts";
+
+/**
+ * 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 const UI4A_ROOT_CLASS = "ui4a-root";
+const PLUGIN_ID = "dsh-generative-ui";
+
+let generator: Promise<UnoGenerator> | null = null;
+const tokens = new Set<string>();
+let sheet: HTMLStyleElement | null = null;
+/** Whether the sheet already carries the preflight block. Reset with the sheet, not with the tokens. */
+let preflighted = false;
+
+/**
+ * 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 async function ensureUnoStyles(code: string, streaming = false): Promise<void> {
+  if (typeof document === "undefined") return;
+  const uno = await (generator ??= createGenerator(unoConfig(`.${UI4A_ROOT_CLASS}`)));
+  const extracted = await uno.applyExtractors(code);
+  const fresh = [...extracted].filter((token) => !tokens.has(token));
+  if (fresh.length === 0 && streaming && preflighted) return;
+  for (const token of fresh) tokens.add(token);
+  sheet ??= createSheet();
+  if (streaming) {
+    // Preflights FIRST, on the very first streaming frame, and never again. They were reachable
+    // only through the settled path, so for the whole of a stream the card rendered without
+    // `box-sizing: border-box` and without the button/list reset — measured on a first card in a
+    // fresh page: 31 seconds of streaming with `pre: false` and a painting card whose `<input>`
+    // computed `content-box`. That is not "unstyled until it settles", it is *wrongly* styled
+    // while the reader watches: a `w-full px-3 border` input is padding-plus-border wider than
+    // its parent, so the layout is visibly broken and then jumps when the stream ends.
+    //
+    // They are a fixed block that depends on nothing the model types, so there is no reason for
+    // them to wait for anything, and generating them once costs a single call.
+    if (!preflighted) {
+      preflighted = true;
+      const { css } = await uno.generate([], { preflights: true });
+      sheet.textContent += splitVendorRules(css);
+    }
+    if (fresh.length === 0) return;
+    const { css } = await uno.generate(fresh, { preflights: false });
+    sheet.textContent += splitVendorRules(css);
+    return;
+  }
+  preflighted = true;
+  const { css } = await uno.generate(tokens, { preflights: true });
+  sheet.textContent = splitVendorRules(css);
+}
+
+/**
+ * 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 function splitVendorRules(css: string): string {
+  return css.replaceAll(/(^|\})\s*([^{}]*::-moz-[^{}]*)\{([^}]*)\}/g, (whole, lead: string, selectors: string, body: string) => {
+    const parts = selectors
+      .split(",")
+      .map((s) => s.trim())
+      .filter(Boolean);
+    if (parts.length < 2) return whole;
+    const moz = parts.filter((s) => s.includes("::-moz-"));
+    const rest = parts.filter((s) => !s.includes("::-moz-"));
+    if (moz.length === 0 || rest.length === 0) return whole;
+    return `${lead}\n${rest.join(",\n")}{${body}}\n${moz.join(",\n")}{${body}}`;
+  });
+}
+
+/**
+ * `data-plugin` is required, not decorative — see `canvas/mount.ts`: the loader claims every
+ * unmarked `<style>` for whichever plugin is materializing, and would tear this one out with it.
+ */
+function createSheet(): HTMLStyleElement {
+  const style = document.createElement("style");
+  style.setAttribute("data-plugin", PLUGIN_ID);
+  style.setAttribute("data-plugin-css", `${PLUGIN_ID}/uno`);
+  return document.head.appendChild(style);
+}
+
+/** Drops the sheet and the generator. HMR reloads the module; the old sheet must not survive it. */
+export function disposeUnoStyles(): void {
+  sheet?.remove();
+  sheet = null;
+  generator = null;
+  preflighted = false;
+  tokens.clear();
+}

package/src/client/session.ts

@@ -0,0 +1,46 @@
+/**
+ * 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 function chatNodes(ctx: ClientContext): readonly ChatNodeView[] {
+  const sessionId = ctx.sessions.list.getSnapshot().current;
+  if (sessionId === undefined) return [];
+  const snapshot = ctx.sessions.binding(sessionId)?.session.getSnapshot();
+  if (snapshot === undefined) return [];
+  return [...snapshot.chat.nodes.values()] as 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 function perNode<T>(key: (node: ChatNodeView) => string, derive: (node: ChatNodeView) => T) {
+  let cache = new Map<string, T>();
+  return (nodes: readonly ChatNodeView[]): T[] => {
+    const next = new Map<string, T>();
+    const results: T[] = [];
+    for (const node of nodes) {
+      const id = key(node);
+      const value = cache.get(id) ?? derive(node);
+      next.set(id, value);
+      results.push(value);
+    }
+    // Replacing the map drops entries for nodes that left the loaded window.
+    cache = next;
+    return results;
+  };
+}

package/src/contract-assets.ts

@@ -0,0 +1,46 @@
+/**
+ * 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 const ASSET_PREFIX = "/dsh-generative-ui/assets";
+export const WASM_PATH = `${ASSET_PREFIX}/tsx_bg.wasm`;
+
+/** Reads one canvas file from the session's workspace: `?cwd=<workspace>&id=<canvas>`. */
+export 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 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 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 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 const WEB_SEARCH_PATH = "/dsh-generative-ui/web-search";

package/src/contract.ts

@@ -0,0 +1,111 @@
+/**
+ * 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 const UI4A_DIR = ".dsh/ui4a";
+export const CANVAS_DIR = `${UI4A_DIR}/canvases`;
+export 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 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 const CAPABILITY_PREFIX = "$dsh";
+export const capabilityModule = (group: string) => `${CAPABILITY_PREFIX}/${group}`;
+
+/**
+ * Canvas ids are path segments, so anything that could escape the directory is not one.
+ *
+ * Stated as an exclusion rather than an allowlist: `[\w-]+` reads as "safe" but is really
+ * "ASCII", and a model answering in Chinese names the file in Chinese — `背单词.ui4a.tsx`
+ * was silently not a canvas, so the panel never opened and the reply still said it had.
+ * What actually has to be barred is separators and traversal; the rest is a filename.
+ */
+const CANVAS_ID = /^[^/\\.\s]+$/;
+
+export const isCanvasId = (id: string) => CANVAS_ID.test(id);
+
+export const canvasPath = (id: string) => `${CANVAS_DIR}/${id}${CANVAS_SUFFIX}`;
+export const canvasChildDir = (id: string) => `${CANVAS_DIR}/${id}`;
+
+/**
+ * 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 function canvasChildPath(id: string, specifier: string, from?: string): string | null {
+  if (!isCanvasId(id)) return null;
+  const segments = specifier.replace(/^\.\//, "").split("/");
+  if (segments.length === 0 || !segments.every(isCanvasId)) return null;
+  const root = canvasChildDir(id);
+  // No `from`, or one naming the entry file: the specifier is written beside the canvas, so
+  // it must open with the id. With a `from` inside the child directory, it is written beside
+  // that file instead and the id never appears.
+  const within = from === undefined ? null : from.replace(/\\/g, "/").split(`${root}/`)[1];
+  if (within === undefined || within === null) {
+    if (segments.length < 2 || segments[0] !== id) return null;
+    return `${root}/${segments.slice(1).join("/")}`;
+  }
+  const dir = within.split("/").slice(0, -1);
+  return [root, ...dir, ...segments].join("/");
+}
+
+/**
+ * Reduces a path to its workspace-relative form.
+ *
+ * Tool arguments carry absolute paths, so the contract is matched on the trailing
+ * `ui4a/canvases/…` portion rather than anchored at the string start.
+ */
+const normalize = (path: string) => {
+  const at = path.replace(/\\/g, "/").lastIndexOf(`${CANVAS_DIR}/`);
+  return at === -1 ? path.replace(/^\.?\//, "") : path.slice(at);
+};
+
+/** The canvas id of an entry path, or null when the path is not a canvas entry. */
+export function canvasIdOf(path: string): string | null {
+  const relative = normalize(path);
+  if (!relative.startsWith(`${CANVAS_DIR}/`) || !relative.endsWith(CANVAS_SUFFIX)) return null;
+  const id = relative.slice(CANVAS_DIR.length + 1, -CANVAS_SUFFIX.length);
+  return isCanvasId(id) ? id : null;
+}
+
+/** The owning canvas of any path under the contract — entry file or child module. */
+export function owningCanvasIdOf(path: string): string | null {
+  const direct = canvasIdOf(path);
+  if (direct !== null) return direct;
+  const relative = normalize(path);
+  if (!relative.startsWith(`${CANVAS_DIR}/`)) return null;
+  const id = relative.slice(CANVAS_DIR.length + 1).split("/")[0];
+  return id !== undefined && isCanvasId(id) ? id : null;
+}