@kitn.ai/ui 0.26.0 → 0.27.0

package/dist/mcp.es.js

@@ -3,34 +3,34 @@ import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { ListToolsRequestSchema, CallToolRequestSchema } from "@modelcontextprotocol/sdk/types.js";
 import { createRequire } from "node:module";
 import { z as z$1 } from "zod";
-import { readFileSync, readdirSync, existsSync } from "node:fs";
+import { existsSync, readFileSync, readdirSync } from "node:fs";
 import { fileURLToPath } from "node:url";
-import { join, dirname, resolve } from "node:path";
+import { join, resolve, dirname } from "node:path";
 var z = Object.defineProperty;
 var M = (e, t, i) => t in e ? z(e, t, { enumerable: true, configurable: true, writable: true, value: i }) : e[t] = i;
-var w = (e, t, i) => M(e, typeof t != "symbol" ? t + "" : t, i);
-const U = "https://json-schema.org/draft/2020-12/schema", F = "https://kitn.ai/schemas/card/artifact.schema.json", J = "ArtifactCardData", B = "Generated-artifact viewer payload: a framed preview plus the source files behind it. A deliberately NARROW subset of the Artifact component's props — it says WHAT to show, never how the viewer behaves. Toolbar composition, view-state and the iframe `sandbox` are host-owned and stay off the wire, so a model cannot widen its own sandbox or hide the chrome the user needs to inspect what it built.", Y = "object";
-const H = [{ required: ["src"] }, { required: ["files"] }], K = { src: { type: "string", format: "uri", description: "URL the preview iframe frames, and the target of the Home button. Omit for a source-only artifact (`tab: 'code'` with `files`).", "x-kai-format": "url" }, files: { type: "array", description: "Files behind the artifact: the Code tab's tree, each optionally carrying its own preview url and source.", maxItems: 500, items: { type: "object", required: ["path"], additionalProperties: false, properties: { path: { type: "string", description: "Tree label/key. Folders are built from `/`-delimited segments.", maxLength: 1024 }, url: { type: "string", format: "uri", description: "Where the preview loads this file. Defaults to `path` resolved against `src`.", "x-kai-format": "url" }, code: { type: "string", description: "Source shown in the Code tab. Omit for binary files (image/pdf), which have no code view." }, language: { type: "string", description: "Language id for syntax highlighting (e.g. 'html', 'css', 'tsx').", maxLength: 40 }, type: { type: "string", enum: ["html", "pdf", "image", "other"], description: "File kind. Drives the tree icon and whether the Code view applies; 'pdf' also routes the preview to the inline PDF viewer.", "x-kai-control": "select" }, additions: { type: "integer", minimum: 0, description: "Lines added vs the base. Rendered as a trailing '+N' stat." }, deletions: { type: "integer", minimum: 0, description: "Lines removed vs the base. Rendered as a trailing '-N' stat." }, status: { type: "string", enum: ["added", "modified", "deleted", "renamed", "untracked"], description: "Change status vs the base. Drives a trailing status letter in the conventional VCS hue.", "x-kai-control": "select" } } } }, tab: { type: "string", enum: ["preview", "code"], default: "preview", description: "Which view the card OPENS on. SEED ONLY: the user can switch freely afterwards and a revision of this card will NOT move them back, because the user's choice wins over the model's. A switch is reported back as a `state` patch.", "x-kai-control": "select" }, activeFile: { type: "string", description: "Path of the file selected in the tree when the card FIRST renders (must match a `files[].path`). Seeds the tree highlight, the Code source and the preview. SEED ONLY, like `tab`: revising this card will not move a user who has since selected a different file.", maxLength: 1024 }, displayUrl: { type: "string", description: "Friendly address shown in the path field INSTEAD of the real url, which also makes the field read-only. Use when `src` is not consumer-facing (e.g. a `data:` blob) so a clean address is shown rather than leaking it.", maxLength: 2048 }, height: { description: "Frame height. A bare number is px; a string is any CSS length. Defaults to 420px. REQUIRED CONCEPT, not decoration: the viewer is built to fill its container, and a message thread supplies no height, so the card sets one explicitly or the artifact collapses to zero and renders invisible.", oneOf: [{ type: "number", minimum: 1 }, { type: "string", maxLength: 32 }] } }, W = {
+var $ = (e, t, i) => M(e, typeof t != "symbol" ? t + "" : t, i);
+const U = "https://json-schema.org/draft/2020-12/schema", F = "https://kitn.ai/schemas/card/artifact.schema.json", J = "ArtifactCardData", B = "Generated-artifact viewer payload: a framed preview plus the source files behind it. A deliberately NARROW subset of the Artifact component's props — it says WHAT to show, never how the viewer behaves. Toolbar composition, view-state and the iframe `sandbox` are host-owned and stay off the wire, so a model cannot widen its own sandbox or hide the chrome the user needs to inspect what it built.", H = "object";
+const Y = [{ required: ["src"] }, { required: ["files"] }], K = { src: { type: "string", format: "uri", description: "URL the preview iframe frames, and the target of the Home button. Omit for a source-only artifact (`tab: 'code'` with `files`).", "x-kai-format": "url" }, files: { type: "array", description: "Files behind the artifact: the Code tab's tree, each optionally carrying its own preview url and source.", maxItems: 500, items: { type: "object", required: ["path"], additionalProperties: false, properties: { path: { type: "string", description: "Tree label/key. Folders are built from `/`-delimited segments.", maxLength: 1024 }, url: { type: "string", format: "uri", description: "Where the preview loads this file. Defaults to `path` resolved against `src`.", "x-kai-format": "url" }, code: { type: "string", description: "Source shown in the Code tab. Omit for binary files (image/pdf), which have no code view." }, language: { type: "string", description: "Language id for syntax highlighting (e.g. 'html', 'css', 'tsx').", maxLength: 40 }, type: { type: "string", enum: ["html", "pdf", "image", "other"], description: "File kind. Drives the tree icon and whether the Code view applies; 'pdf' also routes the preview to the inline PDF viewer.", "x-kai-control": "select" }, additions: { type: "integer", minimum: 0, description: "Lines added vs the base. Rendered as a trailing '+N' stat." }, deletions: { type: "integer", minimum: 0, description: "Lines removed vs the base. Rendered as a trailing '-N' stat." }, status: { type: "string", enum: ["added", "modified", "deleted", "renamed", "untracked"], description: "Change status vs the base. Drives a trailing status letter in the conventional VCS hue.", "x-kai-control": "select" } } } }, tab: { type: "string", enum: ["preview", "code"], default: "preview", description: "Which view the card OPENS on. SEED ONLY: the user can switch freely afterwards and a revision of this card will NOT move them back, because the user's choice wins over the model's. A switch is reported back as a `state` patch.", "x-kai-control": "select" }, activeFile: { type: "string", description: "Path of the file selected in the tree when the card FIRST renders (must match a `files[].path`). Seeds the tree highlight, the Code source and the preview. SEED ONLY, like `tab`: revising this card will not move a user who has since selected a different file.", maxLength: 1024 }, displayUrl: { type: "string", description: "Friendly address shown in the path field INSTEAD of the real url, which also makes the field read-only. Use when `src` is not consumer-facing (e.g. a `data:` blob) so a clean address is shown rather than leaking it.", maxLength: 2048 }, height: { description: "Frame height. A bare number is px; a string is any CSS length. Defaults to 420px. REQUIRED CONCEPT, not decoration: the viewer is built to fill its container, and a message thread supplies no height, so the card sets one explicitly or the artifact collapses to zero and renders invisible.", oneOf: [{ type: "number", minimum: 1 }, { type: "string", maxLength: 32 }] } }, W = {
   $schema: U,
   $id: F,
   title: J,
   description: B,
-  type: Y,
+  type: H,
   additionalProperties: false,
-  anyOf: H,
+  anyOf: Y,
   properties: K
-}, ue = "https://json-schema.org/draft/2020-12/schema", le = "https://kitn.ai/schemas/card/choice.schema.json", me = "ChoiceCardData", he = "Data payload for a `choice` card (CardEnvelope.data when type='choice'). A single-select 'pick one of N rich options' card; activating an option emits the `action` verb.", fe = "object", ye = ["options"], ge = { prompt: { type: "string", description: "Optional question/body text rendered above the options. Distinct from CardEnvelope.title (the card chrome heading)." }, submitLabel: { type: "string", description: "Label for the Submit button; default 'Submit'." }, options: { type: "array", minItems: 1, description: "The selectable options, rendered in order. Exactly one can be chosen.", items: { type: "object", required: ["id", "label"], properties: { id: { type: "string", minLength: 1, description: "Emitted as CardEvent.action. Must be unique within `options`. (The reserved id '__other__' is used by the allowOther escape.)", "x-kai-unique": true }, label: { type: "string", minLength: 1, description: "Visible option label." }, description: { type: "string", description: "Optional secondary line under the label." }, media: { type: "object", description: "Optional leading media: an image URL or a named icon.", properties: { image: { type: "string", description: "Image URL rendered as a leading thumbnail in the row." }, imageAlt: { type: "string", description: "Accessible alt text for `image` (decorative if omitted)." }, icon: { type: "string", description: "Named icon rendered as a leading glyph." } } }, meta: { type: "string", description: "Trailing freeform text (e.g. a price or badge), right-aligned in the row." }, recommended: { type: "boolean", default: false, description: "Renders a small 'Recommended' pill near the label." }, disabled: { type: "boolean", default: false, description: "Option is shown but not selectable, and skipped in keyboard nav." }, payload: { description: "Optional opaque payload echoed back in CardEvent.payload (any JSON)." } } } }, allowOther: { description: "Optional free-text escape ('none of these / specify'). `true` appends a final 'Other…' option; an object customizes its `label`/`placeholder`. Selecting it reveals a text input; the shared Submit button then emits `{ kind:'action', action:'__other__', payload:{ text } }`.", "x-kai-control": "allow-other" }, dismissible: { type: "boolean", default: false, description: "Show a close affordance that emits the `dismiss` verb. The card collapses to a re-openable 'dismissed' stub; the host decides via `onReopen` whether it comes back live or `expired`." } }, be = {
-  $schema: ue,
-  $id: le,
+}, le = "https://json-schema.org/draft/2020-12/schema", ue = "https://kitn.ai/schemas/card/choice.schema.json", me = "ChoiceCardData", he = "Data payload for a `choice` card (CardEnvelope.data when type='choice'). A single-select 'pick one of N rich options' card; activating an option emits the `action` verb.", fe = "object", ye = ["options"], ge = { prompt: { type: "string", description: "Optional question/body text rendered above the options. Distinct from CardEnvelope.title (the card chrome heading)." }, submitLabel: { type: "string", description: "Label for the Submit button; default 'Submit'." }, options: { type: "array", minItems: 1, description: "The selectable options, rendered in order. Exactly one can be chosen.", items: { type: "object", required: ["id", "label"], properties: { id: { type: "string", minLength: 1, description: "Emitted as CardEvent.action. Must be unique within `options`. (The reserved id '__other__' is used by the allowOther escape.)", "x-kai-unique": true }, label: { type: "string", minLength: 1, description: "Visible option label." }, description: { type: "string", description: "Optional secondary line under the label." }, media: { type: "object", description: "Optional leading media: an image URL or a named icon.", properties: { image: { type: "string", description: "Image URL rendered as a leading thumbnail in the row." }, imageAlt: { type: "string", description: "Accessible alt text for `image` (decorative if omitted)." }, icon: { type: "string", description: "Named icon rendered as a leading glyph." } } }, meta: { type: "string", description: "Trailing freeform text (e.g. a price or badge), right-aligned in the row." }, recommended: { type: "boolean", default: false, description: "Renders a small 'Recommended' pill near the label." }, disabled: { type: "boolean", default: false, description: "Option is shown but not selectable, and skipped in keyboard nav." }, payload: { description: "Optional opaque payload echoed back in CardEvent.payload (any JSON)." } } } }, allowOther: { description: "Optional free-text escape ('none of these / specify'). `true` appends a final 'Other…' option; an object customizes its `label`/`placeholder`. Selecting it reveals a text input; the shared Submit button then emits `{ kind:'action', action:'__other__', payload:{ text } }`.", "x-kai-control": "allow-other" }, dismissible: { type: "boolean", default: false, description: "Show a close affordance that emits the `dismiss` verb. The card collapses to a re-openable 'dismissed' stub; the host decides via `onReopen` whether it comes back live or `expired`." } }, be = {
+  $schema: le,
+  $id: ue,
   title: me,
   description: he,
   type: fe,
   required: ye,
   properties: ge
-}, ve = "https://json-schema.org/draft/2020-12/schema", $e = "https://kitn.ai/schemas/card/confirm.schema.json", we = "ConfirmCardData", xe = "Data payload for a `confirm` card (CardEnvelope.data when type='confirm').", ke = "object", Oe = ["actions"], je = { heading: { type: "string", description: "Optional in-body heading. Distinct from CardEnvelope.title (the card chrome title)." }, body: { type: "string", description: "Body text. Plain text in v1 (rendered safely; no HTML injection)." }, tone: { type: "string", enum: ["default", "warning", "danger"], default: "default", description: "Overall card tone; 'danger' adds a warning icon + accent for destructive approvals.", "x-kai-control": "tone" }, actions: { type: "array", minItems: 1, maxItems: 4, description: "The choice set. Rendered as buttons in order; max 4 keeps it a decision, not a menu.", items: { type: "object", required: ["id", "label"], properties: { id: { type: "string", minLength: 1, description: "Emitted as CardEvent.action. Must be unique within `actions`.", "x-kai-unique": true }, label: { type: "string", minLength: 1, description: "Visible button label." }, style: { type: "string", enum: ["primary", "default", "destructive"], default: "default", description: "Button emphasis. 'destructive' = red/danger; 'primary' = filled accent.", "x-kai-control": "button-style" }, payload: { description: "Optional opaque payload echoed back in CardEvent.payload (any JSON)." }, default: { type: "boolean", default: false, description: "If true, this action is the keyboard default (Enter) and gets initial focus. At most one should be true; the card uses the first if several are.", "x-kai-default-action": true } } } }, dismissible: { type: "boolean", default: false, description: "Show a close affordance that emits the `dismiss` verb." } }, Se = {
+}, ve = "https://json-schema.org/draft/2020-12/schema", we = "https://kitn.ai/schemas/card/confirm.schema.json", $e = "ConfirmCardData", xe = "Data payload for a `confirm` card (CardEnvelope.data when type='confirm').", ke = "object", Oe = ["actions"], je = { heading: { type: "string", description: "Optional in-body heading. Distinct from CardEnvelope.title (the card chrome title)." }, body: { type: "string", description: "Body text. Plain text in v1 (rendered safely; no HTML injection)." }, tone: { type: "string", enum: ["default", "warning", "danger"], default: "default", description: "Overall card tone; 'danger' adds a warning icon + accent for destructive approvals.", "x-kai-control": "tone" }, actions: { type: "array", minItems: 1, maxItems: 4, description: "The choice set. Rendered as buttons in order; max 4 keeps it a decision, not a menu.", items: { type: "object", required: ["id", "label"], properties: { id: { type: "string", minLength: 1, description: "Emitted as CardEvent.action. Must be unique within `actions`.", "x-kai-unique": true }, label: { type: "string", minLength: 1, description: "Visible button label." }, style: { type: "string", enum: ["primary", "default", "destructive"], default: "default", description: "Button emphasis. 'destructive' = red/danger; 'primary' = filled accent.", "x-kai-control": "button-style" }, payload: { description: "Optional opaque payload echoed back in CardEvent.payload (any JSON)." }, default: { type: "boolean", default: false, description: "If true, this action is the keyboard default (Enter) and gets initial focus. At most one should be true; the card uses the first if several are.", "x-kai-default-action": true } } } }, dismissible: { type: "boolean", default: false, description: "Show a close affordance that emits the `dismiss` verb." } }, Se = {
   $schema: ve,
-  $id: $e,
-  title: we,
+  $id: we,
+  title: $e,
   description: xe,
   type: ke,
   required: Oe,
@@ -45,14 +45,14 @@ const H = [{ required: ["src"] }, { required: ["files"] }], K = { src: { type: "
   additionalProperties: Ce,
   properties: Re,
   allOf: Ne
-}, Je = "https://json-schema.org/draft/2020-12/schema", Be = "https://kitn.ai/schemas/card/form.schema.json", Ye = "kai-form data (a form definition)", He = "The CardEnvelope.data for a card of type 'form': a JSON Schema (type:'object') describing the fields kai-form renders, plus optional x-kai-* UI hints. The same schema validates the submission.", Ke = "object", We = ["type", "properties"], Ve = { type: { const: "object" }, title: { type: "string" }, description: { type: "string" }, required: { type: "array", items: { type: "string" } }, properties: { type: "object" }, "x-kai-order": { type: "array", items: { type: "string" } }, "x-kai-inlineMax": { type: "integer", minimum: 1 }, "x-kai-submitLabel": { type: "string" }, "x-kai-dismissible": { type: "boolean" }, "x-kai-actions": { type: "array", items: { type: "object", required: ["id", "label"], properties: { id: { type: "string" }, label: { type: "string" }, variant: { enum: ["default", "ghost", "outline"] } } } } }, Ge = {
+}, Je = "https://json-schema.org/draft/2020-12/schema", Be = "https://kitn.ai/schemas/card/form.schema.json", He = "kai-form data (a form definition)", Ye = "The CardEnvelope.data for a card of type 'form': a JSON Schema (type:'object') describing the fields kai-form renders, plus optional x-kai-* UI hints. The same schema validates the submission.", Ke = "object", We = ["type", "properties"], Ge = { type: { const: "object" }, title: { type: "string" }, description: { type: "string" }, required: { type: "array", items: { type: "string" } }, properties: { type: "object", description: "The fields to collect, keyed by property name. Each value is a JSON Schema field definition (type, title, description, enum, minimum/maximum, minLength/maxLength, pattern, items) plus optional x-kai-* UI hints. Only the display-format hints are spelled out below; the rest of a field definition is ordinary JSON Schema.", additionalProperties: { type: "object", properties: { "x-kai-format": { description: "Display format for a string field. `tel`, `ssn` and `credit-card` apply that type's standard mask and submit digits only; `custom` masks with `x-kai-mask` and submits the formatted value. Omit it for a plain text field.", enum: ["tel", "ssn", "credit-card", "custom"] }, "x-kai-mask": { description: 'The mask pattern, used only with `x-kai-format: "custom"`: `#` one digit, `@` one letter or digit, `*` one letter or digit that may be obscured; every other character is a literal shown as typed, e.g. `CHG-####`.', type: "string", maxLength: 64 }, "x-kai-mask-guide": { description: "Placeholder text shown at the unfilled positions of the mask, aligned character for character with the pattern (`mm/dd/yyyy` for `##/##/####`). Derived from the pattern when omitted.", type: "string", maxLength: 64 } } } }, "x-kai-order": { type: "array", items: { type: "string" } }, "x-kai-inlineMax": { type: "integer", minimum: 1 }, "x-kai-submitLabel": { type: "string" }, "x-kai-dismissible": { type: "boolean" }, "x-kai-actions": { type: "array", items: { type: "object", required: ["id", "label"], properties: { id: { type: "string" }, label: { type: "string" }, variant: { enum: ["default", "ghost", "outline"] } } } } }, Ve = {
   $schema: Je,
   $id: Be,
-  title: Ye,
-  description: He,
+  title: He,
+  description: Ye,
   type: Ke,
   required: We,
-  properties: Ve
+  properties: Ge
 }, Xe = "https://json-schema.org/draft/2020-12/schema", Qe = "https://kitn.ai/schemas/card/link.schema.json", Ze = "LinkPreviewData", et = "Rich link / Open-Graph preview payload. The card renders from this; it never fetches.", tt = "object", it = ["url"], nt = false, ot = { url: { type: "string", format: "uri", description: "Canonical destination. Opened via the contract `open` verb (target 'tab').", "x-kai-format": "url" }, title: { type: "string", description: "OG title (og:title). Falls back to the domain when absent.", maxLength: 300 }, description: { type: "string", description: "OG description (og:description). Clamped to 3 lines in the UI.", maxLength: 1e3 }, image: { type: "string", format: "uri", description: "Preview image (og:image). Optional; the card degrades gracefully when missing or it fails to load.", "x-kai-format": "url" }, imageAlt: { type: "string", description: "Alt text for the preview image. Defaults to the title (or empty = decorative) when omitted.", maxLength: 300 }, favicon: { type: "string", format: "uri", description: "Site favicon shown next to the domain.", "x-kai-format": "url" }, domain: { type: "string", description: "Display domain (e.g. 'example.com'). Derived from `url` when omitted.", maxLength: 253 }, siteName: { type: "string", description: "OG site name (og:site_name). Shown in place of the domain when present.", maxLength: 200 } }, rt = {
   $schema: Xe,
   $id: Qe,
@@ -62,14 +62,14 @@ const H = [{ required: ["src"] }, { required: ["files"] }], K = { src: { type: "
   required: it,
   additionalProperties: nt,
   properties: ot
-}, ht = "https://json-schema.org/draft/2020-12/schema", ft = "https://kitn.ai/schemas/card/tasks.schema.json", yt = "TasksCardData", gt = "Data payload for a `tasks` card (CardEnvelope.data when type='tasks').", bt = "object", vt = ["tasks"], $t = { mode: { type: "string", enum: ["select", "progress"], default: "select", description: "'select' (default) = toggle + a confirm button that emits `submit`. 'progress' = an onboarding-checklist look (header `done / total` count, circular indicators, per-item title/description, no confirm button, where checking a row IS the action). Both share the selection model.", "x-kai-mode": true }, heading: { type: "string", description: "Optional in-body heading; distinct from CardEnvelope.title." }, tasks: { type: "array", minItems: 1, description: "The selectable rows, rendered in order.", items: { type: "object", required: ["id", "label"], properties: { id: { type: "string", minLength: 1, description: "Stable id; the selected ids are returned in the result. Unique within `tasks`.", "x-kai-unique": true }, label: { type: "string", minLength: 1, description: "Row label." }, description: { type: "string", description: "Optional secondary line under the label." }, checked: { type: "boolean", default: false, description: "Initial checked state of the row." }, disabled: { type: "boolean", default: false, description: "Row is shown but not toggleable (and excluded from select-all)." } } } }, selectAll: { type: "boolean", default: false, description: "Render a master select-all checkbox above the list.", "x-kai-control": "select-all" }, confirmLabel: { type: "string", default: "Confirm", description: "Label for the confirm button." }, allowEmpty: { type: "boolean", default: false, description: "If true, confirm is enabled with zero selected (emits { selected: [] }). If false, confirm is disabled until >=1 selected." }, min: { type: "integer", minimum: 0, description: "Optional minimum number that must be selected to confirm.", "x-kai-select-min": true }, max: { type: "integer", minimum: 1, description: "Optional maximum selectable; further toggles are blocked once reached.", "x-kai-select-max": true }, dismissible: { type: "boolean", default: false, description: "Show a close affordance that emits the `dismiss` verb. The card collapses to a re-openable 'dismissed' stub; the host decides via `onReopen` whether it comes back live or `expired`." } }, wt = {
+}, ht = "https://json-schema.org/draft/2020-12/schema", ft = "https://kitn.ai/schemas/card/tasks.schema.json", yt = "TasksCardData", gt = "Data payload for a `tasks` card (CardEnvelope.data when type='tasks').", bt = "object", vt = ["tasks"], wt = { mode: { type: "string", enum: ["select", "progress"], default: "select", description: "'select' (default) = toggle + a confirm button that emits `submit`. 'progress' = an onboarding-checklist look (header `done / total` count, circular indicators, per-item title/description, no confirm button, where checking a row IS the action). Both share the selection model.", "x-kai-mode": true }, heading: { type: "string", description: "Optional in-body heading; distinct from CardEnvelope.title." }, tasks: { type: "array", minItems: 1, description: "The selectable rows, rendered in order.", items: { type: "object", required: ["id", "label"], properties: { id: { type: "string", minLength: 1, description: "Stable id; the selected ids are returned in the result. Unique within `tasks`.", "x-kai-unique": true }, label: { type: "string", minLength: 1, description: "Row label." }, description: { type: "string", description: "Optional secondary line under the label." }, checked: { type: "boolean", default: false, description: "Initial checked state of the row." }, disabled: { type: "boolean", default: false, description: "Row is shown but not toggleable (and excluded from select-all)." } } } }, selectAll: { type: "boolean", default: false, description: "Render a master select-all checkbox above the list.", "x-kai-control": "select-all" }, confirmLabel: { type: "string", default: "Confirm", description: "Label for the confirm button." }, allowEmpty: { type: "boolean", default: false, description: "If true, confirm is enabled with zero selected (emits { selected: [] }). If false, confirm is disabled until >=1 selected." }, min: { type: "integer", minimum: 0, description: "Optional minimum number that must be selected to confirm.", "x-kai-select-min": true }, max: { type: "integer", minimum: 1, description: "Optional maximum selectable; further toggles are blocked once reached.", "x-kai-select-max": true }, dismissible: { type: "boolean", default: false, description: "Show a close affordance that emits the `dismiss` verb. The card collapses to a re-openable 'dismissed' stub; the host decides via `onReopen` whether it comes back live or `expired`." } }, $t = {
   $schema: ht,
   $id: ft,
   title: yt,
   description: gt,
   type: bt,
   required: vt,
-  properties: $t
+  properties: wt
 }, S = "kai_";
 function R(e) {
   return `${S}${e}`;
@@ -267,8 +267,8 @@ function x(e, t, i, n, r) {
     return;
   }
   for (const [p, c] of Object.entries(e)) {
-    const l = t.keywords[p];
-    if (!l) {
+    const u = t.keywords[p];
+    if (!u) {
       r.push({
         path: i,
         keyword: p,
@@ -276,12 +276,12 @@ function x(e, t, i, n, r) {
       });
       continue;
     }
-    if (l.status === "unsupported") {
-      r.push({ path: i, keyword: p, reason: `not supported (${l.note})` });
+    if (u.status === "unsupported") {
+      r.push({ path: i, keyword: p, reason: `not supported (${u.note})` });
       continue;
     }
-    if (l.status === "supported" && l.value) {
-      const h = l.value(c);
+    if (u.status === "supported" && u.value) {
+      const h = u.value(c);
       h && r.push({ path: i, keyword: p, reason: h });
     }
   }
@@ -295,11 +295,11 @@ function x(e, t, i, n, r) {
     keyword: "properties",
     reason: `a free-form object (\`type: "object"\` with no \`properties\`) has no grammar under ${t.label}; with the mandatory \`additionalProperties: false\` it can only ever be \`{}\`, which is not what the schema means`
   }), a && t.requireAllPropertiesRequired && o) {
-    const p = Array.isArray(e.required) ? e.required.map(String) : [], c = Object.keys(e.properties).filter((l) => !p.includes(l));
+    const p = Array.isArray(e.required) ? e.required.map(String) : [], c = Object.keys(e.properties).filter((u) => !p.includes(u));
     c.length > 0 && r.push({
       path: i,
       keyword: "required",
-      reason: `${t.label} requires every property in \`required\`; missing ${c.map((l) => `\`${l}\``).join(", ")} (emulate optional with a \`null\` union)`
+      reason: `${t.label} requires every property in \`required\`; missing ${c.map((u) => `\`${u}\``).join(", ")} (emulate optional with a \`null\` union)`
     });
   }
   n && !t.allowRootAnyOf && "anyOf" in e && r.push({
@@ -314,25 +314,25 @@ function x(e, t, i, n, r) {
     keyword: "type",
     reason: `unconstrained subschema (annotations only); ${t.label} compiles the schema to a grammar and has no way to express "any JSON". Give it a \`type\``
   });
-  const u = (p) => {
+  const l = (p) => {
     var c;
     return ((c = t.keywords[p]) == null ? void 0 : c.status) === "unsupported";
   };
   for (const p of kt) {
     const c = e[p];
-    if (!(!O(c) || u(p)))
-      for (const [l, h] of Object.entries(c))
-        x(h, t, p === "properties" ? jt(i, l) : `${i}/${p}[${l}]`, false, r);
+    if (!(!O(c) || l(p)))
+      for (const [u, h] of Object.entries(c))
+        x(h, t, p === "properties" ? jt(i, u) : `${i}/${p}[${u}]`, false, r);
   }
   for (const p of xt) {
-    if (!(p in e) || u(p)) continue;
+    if (!(p in e) || l(p)) continue;
     const c = e[p];
     typeof c != "boolean" && x(c, t, p === "items" ? `${i === "(root)" ? "(root)" : i}[]` : `${i}/${p}`, false, r);
   }
   O(e.additionalProperties) && x(e.additionalProperties, t, `${i}/additionalProperties`, false, r);
   for (const p of Ot) {
     const c = e[p];
-    !Array.isArray(c) || u(p) || c.forEach((l, h) => x(l, t, `${i}/${p}[${h}]`, false, r));
+    !Array.isArray(c) || l(p) || c.forEach((u, h) => x(u, t, `${i}/${p}[${h}]`, false, r));
   }
 }
 const At = Object.freeze({
@@ -347,10 +347,10 @@ const At = Object.freeze({
 class qt extends Error {
   constructor(i, n) {
     super(It(i, n));
-    w(this, "name", "UnsupportedCardToolSchemaError");
-    w(this, "provider");
-    w(this, "source");
-    w(this, "cards");
+    $(this, "name", "UnsupportedCardToolSchemaError");
+    $(this, "provider");
+    $(this, "source");
+    $(this, "cards");
     this.provider = i.id, this.source = i.source, this.cards = n;
   }
   /** Every distinct keyword named across every failing card, deduped, in order. */
@@ -393,19 +393,19 @@ function Rt(e, t) {
   for (const o of t) {
     const a = Ct(o, e[o]);
     if (a.length === 0) continue;
-    for (const u of a)
-      if (f(u.properties))
-        for (const [p, c] of Object.entries(u.properties))
+    for (const l of a)
+      if (f(l.properties))
+        for (const [p, c] of Object.entries(l.properties))
           p in i || (i[p] = c);
     const s = a.map(
-      (u) => new Set(Array.isArray(u.required) ? u.required.map(String) : [])
+      (l) => new Set(Array.isArray(l.required) ? l.required.map(String) : [])
     );
     if (o === "allOf")
-      for (const u of s) for (const p of u) n.add(p);
+      for (const l of s) for (const p of l) n.add(p);
     else {
-      const [u, ...p] = s;
-      for (const c of u)
-        p.every((l) => l.has(c)) && n.add(c);
+      const [l, ...p] = s;
+      for (const c of l)
+        p.every((u) => u.has(c)) && n.add(c);
     }
   }
   Object.keys(i).length > 0 && (e.properties = i);
@@ -435,12 +435,12 @@ function _t(e, t, i) {
     let r = e;
     if (n.path !== "")
       for (const a of n.path.split(".")) {
-        const s = f(r.properties) ? r.properties : void 0, u = s == null ? void 0 : s[a];
-        if (!f(u))
+        const s = f(r.properties) ? r.properties : void 0, l = s == null ? void 0 : s[a];
+        if (!f(l))
           throw new TypeError(
             `cardTools: require on '${t}': path '${n.path}' does not resolve in the schema`
           );
-        r = u;
+        r = l;
       }
     const o = r.type === "array" || r.type === void 0 && "items" in r;
     if (o && n.minItems !== void 0 && (r.minItems = n.minItems), !o && n.minItems !== void 0)
@@ -454,8 +454,8 @@ function _t(e, t, i) {
           throw new TypeError(
             `cardTools: require on '${t}' at path '${n.path}': '${p}' is not a property of that node — a required name with no property would make the tool unsatisfiable`
           );
-      const u = Array.isArray(a.required) ? a.required.map(String) : [];
-      a.required = [.../* @__PURE__ */ new Set([...u, ...n.required])];
+      const l = Array.isArray(a.required) ? a.required.map(String) : [];
+      a.required = [.../* @__PURE__ */ new Set([...l, ...n.required])];
     }
   }
 }
@@ -472,7 +472,7 @@ function k(e, t) {
     const a = i[o];
     if (!f(a)) continue;
     const s = {};
-    for (const [u, p] of Object.entries(a)) s[u] = k(p, t);
+    for (const [l, p] of Object.entries(a)) s[l] = k(p, t);
     i[o] = s;
   }
   for (const o of zt)
@@ -516,18 +516,18 @@ function Bt(e, t, i) {
   return typeof o == "string" && o.length > 0 ? o : `Render a \`${e}\` card.`;
 }
 function v(e, t) {
-  var l;
+  var u;
   const i = t === void 0, n = i ? e : t;
   if (!f(n) || typeof n.provider != "string")
     throw new TypeError('cardTools: an options object with a `provider` is required, e.g. cardTools({ provider: "openai" })');
   const { schemas: r, descriptions: o } = Jt(
-    i ? Yt() : e
+    i ? Ht() : e
   ), a = n.strict === true;
   if (n.provider === "jsonschema" && a)
     throw new TypeError(
       'cardTools: `strict: true` is provider-specific and cannot be checked for `provider: "jsonschema"`, because the two documented strict subsets differ (see @kitn.ai/ui/schemas provider-subsets). Pass provider "openai" or "anthropic" to project and check strictly, or drop `strict`.'
     );
-  const s = a ? n.provider === "openai" ? P : _ : null, u = {
+  const s = a ? n.provider === "openai" ? P : _ : null, l = {
     closeObjects: s !== null,
     requireEveryProperty: s !== null && s.requireAllPropertiesRequired
   }, p = [], c = [];
@@ -538,8 +538,8 @@ function v(e, t) {
           `cardTools: require names card type '${h}', which this call does not carry (carries: ${Object.keys(r).join(", ") || "none"})`
         );
   }
-  for (const [h, $] of Object.entries(r)) {
-    const g = R(h), b = Bt(h, $, o), d = k($, u), m = s === null && n.provider !== "jsonschema" ? Pt(d, h) : void 0, I = m ? `${b} ${m}` : b, L = (l = n.require) == null ? void 0 : l[h];
+  for (const [h, w] of Object.entries(r)) {
+    const g = R(h), b = Bt(h, w, o), d = k(w, l), m = s === null && n.provider !== "jsonschema" ? Pt(d, h) : void 0, I = m ? `${b} ${m}` : b, L = (u = n.require) == null ? void 0 : u[h];
     if (L !== void 0 && _t(d, h, L), s) {
       const E = St(d, s);
       if (E.length > 0) {
@@ -552,10 +552,10 @@ function v(e, t) {
   if (s && c.length > 0) throw new qt(s, c);
   return p;
 }
-function Yt() {
+function Ht() {
   return j;
 }
-const li = {
+const ui = {
   form: "kai-form",
   confirm: "kai-confirm",
   tasks: "kai-tasks",
@@ -568,16 +568,16 @@ const li = {
   choice: y(be),
   confirm: y(Se),
   embed: y(Pe),
-  form: y(Ge),
+  form: y(Ve),
   link: y(rt),
-  tasks: y(wt)
+  tasks: y($t)
 }), hi = Object.freeze(
   Object.keys(j)
 );
 function ii(e) {
   return Object.prototype.hasOwnProperty.call(j, e);
 }
-const tags = { "kai-conversations": "conversation-list", "kai-conversation-item": "conversation-item", "kai-prompt-input": "prompt-input", "kai-chat": "chat", "kai-workspace": "chat-workspace", "kai-thread": "thread", "kai-thinking-bar": "thinking-bar", "kai-model-switcher": "model-switcher", "kai-attachments": "attachments", "kai-message": "message", "kai-markdown": "markdown", "kai-code-block": "code-block", "kai-reasoning": "reasoning", "kai-tool": "tool", "kai-context": "context-meter", "kai-feedback-bar": "feedback-bar", "kai-scope-picker": "chat-scope-picker", "kai-suggestions": "prompt-suggestions", "kai-file-upload": "file-upload", "kai-voice-input": "voice-input", "kai-audio-visualizer": "audio-visualizer", "kai-loader": "loader", "kai-text-shimmer": "text-shimmer", "kai-image": "image", "kai-checkpoint": "checkpoint", "kai-skills": "message-skills", "kai-source": "source", "kai-sources": "source", "kai-response-stream": "response-stream", "kai-empty": "empty", "kai-status": "status", "kai-nav": "nav", "kai-progress-bar": "progress-bar", "kai-coachmark": "coachmark", "kai-tabs": "tabs", "kai-voice-output": "voice-output", "kai-screen": "screen", "kai-chain-of-thought": "chain-of-thought", "kai-resizable": "resizable", "kai-resizable-item": "resizable", "kai-file-tree": "file-tree", "kai-artifact": "artifact", "kai-scroll-button": "scroll-button", "kai-popover": "popover", "kai-switch": "switch", "kai-button": "button", "kai-avatar": "avatar", "kai-badge": "badge", "kai-tooltip": "tooltip", "kai-notice": "notice", "kai-icon": "icon", "kai-separator": "separator", "kai-scroll-area": "scroll-area", "kai-hover-card": "hover-card", "kai-skeleton": "skeleton", "kai-toast-region": "toast", "kai-card": "card", "kai-form": "form", "kai-link-preview": "link-preview", "kai-embed": "embed", "kai-confirm": "confirm-card", "kai-tasks": "tasks", "kai-choice": "choice", "kai-cards": "cards", "kai-compare": "compare", "kai-composer": "composer", "kai-menu": "menu", "kai-dropdown": "dropdown", "kai-command": "command", "kai-prompt-dock": "prompt-dock", "kai-segmented": "segmented", "kai-settings-group": "settings-group", "kai-setting-item": "setting-item", "kai-pane": "pane", "kai-pane-group": "pane-group", "kai-agent-card": "agent-card", "kai-dialog": "dialog", "kai-dock": "dock", "kai-input": "input", "kai-search": "search", "kai-kbd": "kbd", "kai-editable-label": "editable-label" };
+const tags = { "kai-conversations": "conversation-list", "kai-conversation-item": "conversation-item", "kai-prompt-input": "prompt-input", "kai-chat": "chat", "kai-workspace": "chat-workspace", "kai-thread": "thread", "kai-thinking-bar": "thinking-bar", "kai-model-switcher": "model-switcher", "kai-attachments": "attachments", "kai-message": "message", "kai-markdown": "markdown", "kai-code-block": "code-block", "kai-reasoning": "reasoning", "kai-tool": "tool", "kai-context": "context-meter", "kai-feedback-bar": "feedback-bar", "kai-scope-picker": "chat-scope-picker", "kai-suggestions": "prompt-suggestions", "kai-file-upload": "file-upload", "kai-voice-input": "voice-input", "kai-audio-visualizer": "audio-visualizer", "kai-loader": "loader", "kai-text-shimmer": "text-shimmer", "kai-image": "image", "kai-checkpoint": "checkpoint", "kai-skills": "message-skills", "kai-source": "source", "kai-sources": "source", "kai-response-stream": "response-stream", "kai-empty": "empty", "kai-status": "status", "kai-nav": "nav", "kai-progress-bar": "progress-bar", "kai-coachmark": "coachmark", "kai-tabs": "tabs", "kai-voice-output": "voice-output", "kai-screen": "screen", "kai-chain-of-thought": "chain-of-thought", "kai-resizable": "resizable", "kai-resizable-item": "resizable", "kai-file-tree": "file-tree", "kai-artifact": "artifact", "kai-scroll-button": "scroll-button", "kai-popover": "popover", "kai-switch": "switch", "kai-checkbox": "checkbox", "kai-checkbox-group": "checkbox-group", "kai-radio-group": "radio-group", "kai-slider": "slider", "kai-select": "select", "kai-button": "button", "kai-avatar": "avatar", "kai-badge": "badge", "kai-tooltip": "tooltip", "kai-notice": "notice", "kai-icon": "icon", "kai-separator": "separator", "kai-scroll-area": "scroll-area", "kai-hover-card": "hover-card", "kai-skeleton": "skeleton", "kai-toast-region": "toast", "kai-card": "card", "kai-form": "form", "kai-link-preview": "link-preview", "kai-embed": "embed", "kai-confirm": "confirm-card", "kai-tasks": "tasks", "kai-choice": "choice", "kai-cards": "cards", "kai-compare": "compare", "kai-composer": "composer", "kai-menu": "menu", "kai-dropdown": "dropdown", "kai-command": "command", "kai-prompt-dock": "prompt-dock", "kai-segmented": "segmented", "kai-settings-group": "settings-group", "kai-setting-item": "setting-item", "kai-pane": "pane", "kai-pane-group": "pane-group", "kai-pane-grid": "pane-grid", "kai-agent-card": "agent-card", "kai-dialog": "dialog", "kai-dock": "dock", "kai-input": "input", "kai-search": "search", "kai-kbd": "kbd", "kai-editable-label": "editable-label" };
 const PACKAGE_NAME$1 = "@kitn.ai/ui";
 const MANIFEST_FILE = "custom-elements.json";
 const SOURCE_TO_PACKAGE_ROOT = ["..", "..", ".."];
@@ -669,7 +669,7 @@ let _cardHosts;
 function cardTagForType(type) {
   if (!_cardTags) {
     const present = new Set(listElements());
-    _cardTags = new Map(Object.entries(li).filter(([, tag]) => present.has(tag)));
+    _cardTags = new Map(Object.entries(ui).filter(([, tag]) => present.has(tag)));
   }
   return _cardTags.get(type);
 }
@@ -860,7 +860,7 @@ const invariants = [
       {
         wrong: "window.open(card.url, '_blank');",
         right: "const isNavigable = (u) => { try { return ['http:', 'https:', 'mailto:'].includes(new URL(u, location.href).protocol); } catch { return false; } };\nif (isNavigable(card.url)) window.open(card.url, '_blank', 'noopener,noreferrer');",
-        note: "THE try/catch IS NOT OPTIONAL: new URL() THROWS on an unparseable input like 'http://[', and an uncaught throw here crashes the render instead of blocking the link — worse than the bug you are fixing. Returning false is the whole contract. Resolving against location.href is deliberate: a relative or fragment href inherits http: and is allowed, which is what makes ordinary links keep working. REPO-INTERNAL ONLY: contributors inside this package use isSafeUrl/SAFE_SCHEMES from src/primitives/card-routing.ts, which has this exact shape — neither is reachable from the published package, so never emit an import for them."
+        note: "THE try/catch IS NOT OPTIONAL: new URL() THROWS on an unparseable input like 'http://[', and an uncaught throw here crashes the render instead of blocking the link — worse than the bug you are fixing. Returning false is the whole contract. Resolving against location.href is deliberate: a relative or fragment href inherits http: and is allowed, which is what makes ordinary links keep working. REPO-INTERNAL ONLY: contributors inside this package use isSafeUrl/SAFE_SCHEMES from src/primitives/url-scheme-policy.ts (re-exported from src/primitives/card-routing.ts for the existing call sites), which has this exact shape — neither is reachable from the published package, so never emit an import for them."
       },
       {
         wrong: "<a href={source.url}>{source.title}</a>",
@@ -1064,8 +1064,755 @@ const surfaceRecipes = [
       "untrusted-model-output"
     ],
     corpus: ["packages/ui/README.md"]
+  },
+  {
+    // The hand-composed thread (rung-6 F-49): kai-chat deliberately absent —
+    // kai-thread renders the transcript, kai-composer takes input, and the
+    // HOST is every line of wiring between them. This record is the catalog
+    // half; the full compiling host module is the `composed-thread` CODE
+    // recipe (../recipes/composed-thread.ts, served by component_reference
+    // { name: "composed-thread" } and compiled by verify:scaffold), which is
+    // also this record's corpus. Ingredients with no wiring edge below are
+    // still real members of the composition: kai-feedback-bar's events
+    // terminate in the host rather than setting another element's property.
+    // (kai-conversation-item used to be in that list as "presentational
+    // standalone"; since F-45 tier 2 a standalone row activates itself, so
+    // the rail is a real kai-select edge below.)
+    id: "composed-thread",
+    intent: "A full chat surface composed by hand from standalone elements — no <kai-chat>. The host module owns the store, streams through createAssistantStream + the wire reader, stages attachments as data: URIs, and drives the toast region as data.",
+    archetypes: ["full-screen"],
+    targets: ["bundler"],
+    ingredients: [
+      "kai-thread",
+      "kai-composer",
+      "kai-attachments",
+      "kai-toast-region",
+      "kai-conversation-item",
+      "kai-feedback-bar"
+    ],
+    backend: { endpoint: "consumer-owned", reader: "readOpenAIStream" },
+    wiring: [
+      {
+        from: "kai-composer",
+        event: "kai-submit",
+        to: "kai-thread",
+        property: "messages",
+        note: "detail is {doc, text, entities} — read detail.text (NOT detail.value, which is kai-chat/kai-prompt-input's shape). The host appends the user turn plus any staged file parts and assigns a NEW array; the reply then streams onto the same property via createAssistantStream"
+      },
+      {
+        from: "kai-attachments",
+        event: "kai-remove",
+        to: "kai-attachments",
+        property: "items",
+        note: "detail is {id}; the tray never mutates its own list — the host filters and reassigns items, and a data: URI needs no revocation on removal (attachment-blob-url is the rule this recipe corrects: F-44)"
+      },
+      {
+        from: "kai-toast-region",
+        event: "kai-dismiss",
+        to: "kai-toast-region",
+        property: "toasts",
+        note: "detail is {id}; the region is driven as DATA because this app places its own and owns the array — the imperative toast() would ADOPT this markup-placed region (it mounts its own only when none exists) and bind its store over the toasts property, so pick one API per region"
+      },
+      {
+        from: "kai-conversation-item",
+        event: "kai-select",
+        to: "kai-thread",
+        property: "messages",
+        note: "detail is {id}; STANDALONE rows only (F-45 tier 2) — outside <kai-conversations> the row body is a tabbable button and click / Enter / Space fire kai-select on the item (non-bubbling: listen on the row). Inside a container this never fires; the container's kai-conversation-select is the one activation event. The container's list story (roving tabindex, arrow keys) stays the host's job in a hand-rolled rail"
+      }
+    ],
+    invariants: [
+      "reactivity-two-halves",
+      "props-not-attributes",
+      "events-non-bubbling",
+      "host-coordinates",
+      "kit-parses-consumer-fetches",
+      "untrusted-model-output"
+    ],
+    corpus: [
+      "packages/ui/src/agent-tooling/recipes/composed-thread.ts",
+      "packages/ui/src/agent-tooling/catalog/surfaces.test.ts"
+    ]
   }
 ];
+const composedThread = {
+  id: "composed-thread",
+  title: "Hand-composed thread (no kai-chat)",
+  intent: "A full chat surface composed from standalone elements — kai-thread renders the transcript, kai-composer takes input, kai-attachments stages files, kai-toast-region notifies, kai-conversation-item rows form the rail — with a host module doing every bit of wiring (host-coordinates: the kit has no store). Streams through createAssistantStream + createMockResponder, so it runs with no backend and no key; swapping the mock for a real /api/chat changes one line.",
+  ingredients: [
+    "kai-thread",
+    "kai-composer",
+    "kai-attachments",
+    "kai-toast-region",
+    "kai-conversation-item",
+    "kai-feedback-bar"
+  ],
+  notes: [
+    "`<kai-composer>` is the BARE editing surface — no send button, no attachments. The paperclip, the hidden file input, the staging tray and the send button here are the host's. For the batteries-included composer row, use `<kai-prompt-input>` instead.",
+    "Attachments are staged as `data:` URIs, NEVER as object URLs (`createObjectURL`). A `blob:` URL resolves only inside the tab that minted it; `toOpenAIMessages` / `toAnthropicMessages` refuse it with a written reason, and before they refused it an attachment-only turn reached the model as nothing at all.",
+    "The HOST resolves tool calls. The mock (like a real provider) only ANNOUNCES one — walk `result.toolCalls` after the read and call `stream.upsertTool(id, { state: 'output-available', output })`, or the panel sits at input-available forever.",
+    "The toast region is driven as DATA (`toasts` property, `kai-dismiss` event) because this app places its own `<kai-toast-region>` and owns the array. Note: `toast()` ADOPTS a markup-placed region (it creates its own only when none exists) and binds its store over `toasts`, replacing a data-driven array — so per region, own the array or call `toast()`, not both.",
+    "A standalone `<kai-conversation-item>` (outside `<kai-conversations>`) activates itself: its body is a tabbable button and click / Enter / Space fire `kai-select` on the item with `{ id }` (non-bubbling — listen on the item). What it does NOT carry is the container's list story — roving tabindex and arrow-key traversal stay yours in a hand-rolled rail.",
+    "`<kai-thread>` fills the height its parent gives it and scrolls internally, which is why `.pane` is a flex column and `.thread` is `flex: 1; min-height: 0`."
+  ],
+  files: [
+    {
+      path: "index.html",
+      lang: "html",
+      code: `<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Composed thread</title>
+    <link rel="stylesheet" href="/src/styles.css" />
+  </head>
+  <body>
+    <!-- The thread is composed by hand from standalone kai-* elements;
+         the kai-chat drop-in is deliberately absent from this app. -->
+    <div class="app">
+      <aside class="rail">
+        <div class="rail-head">
+          <span class="rail-title">Conversations</span>
+          <button id="new-chat" class="ghost-btn" type="button">New</button>
+        </div>
+        <!-- kai-conversation-item rows are created in src/main.ts -->
+        <nav id="conversations" class="rail-list" aria-label="Conversations"></nav>
+      </aside>
+
+      <main class="pane">
+        <header class="pane-head">
+          <h1 id="pane-title">New chat</h1>
+          <span class="badge">mock responder — no provider contacted</span>
+        </header>
+
+        <kai-thread id="thread" class="thread" prose-size="sm">
+          <div slot="empty" class="empty">
+            <strong>Compose a message</strong>
+            <p>Attach a file with the paperclip and send it — it renders on your message.</p>
+          </div>
+        </kai-thread>
+
+        <!-- Shown once an assistant turn settles. -->
+        <kai-feedback-bar
+          id="feedback"
+          class="feedback"
+          hidden
+          bar-title="Was this reply helpful?"
+          collect-detail
+          detail-title="What went wrong?"
+          detail-placeholder="Optional details…"
+          submit-label="Send feedback"
+          thanks-message="Thanks — logged locally."
+        ></kai-feedback-bar>
+
+        <div class="composer-bar">
+          <!-- Staged (not yet sent) attachments. kai-composer has no attachment
+               support of its own, so the tray + the picker below are ours. -->
+          <kai-attachments
+            id="staged"
+            class="staged"
+            variant="inline"
+            removable
+            hover-card
+            show-media-type
+            hidden
+          ></kai-attachments>
+
+          <div class="composer-row">
+            <button id="attach" class="icon-btn" type="button" title="Attach a file" aria-label="Attach a file">
+              <svg viewBox="0 0 24 24" width="18" height="18" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M21.44 11.05l-9.19 9.19a6 6 0 01-8.49-8.49l9.19-9.19a4 4 0 015.66 5.66l-9.2 9.19a2 2 0 01-2.83-2.83l8.49-8.48"/></svg>
+            </button>
+            <input id="file-input" type="file" multiple hidden />
+            <kai-composer
+              id="composer"
+              class="composer"
+              placeholder="Ask anything…  (Enter to send)"
+            ></kai-composer>
+            <button id="send" class="send-btn" type="button">Send</button>
+          </div>
+        </div>
+      </main>
+    </div>
+
+    <!-- Placed explicitly rather than letting toast() auto-mount one. -->
+    <kai-toast-region id="toasts" position="bottom-right" appearance="card"></kai-toast-region>
+
+    <script type="module" src="/src/main.ts"><\/script>
+  </body>
+</html>
+`
+    },
+    {
+      path: "src/main.ts",
+      lang: "ts",
+      code: `// The whole app: a chat surface composed by hand from standalone kai-*
+// elements. <kai-chat> is deliberately not used — kai-thread renders the
+// transcript, kai-composer takes input, and this module is the host that
+// wires one to the other (the kit has no store: host-coordinates).
+import '@kitn.ai/ui/elements'; // registers every <kai-*>; must come first
+import '@kitn.ai/ui/theme.tokens.css';
+
+import type {
+  AttachmentData,
+  ChatMessage,
+  KaiAttachmentsElement,
+  KaiComposerElement,
+  KaiConversationItemElement,
+  KaiFeedbackBarElement,
+  KaiThreadElement,
+  KaiToastRegionElement,
+  MessagePart,
+  ToastItem,
+} from '@kitn.ai/ui/elements';
+import { createAssistantStream, createMockResponder } from '@kitn.ai/ui/state';
+import { readOpenAIStream } from '@kitn.ai/ui/wire';
+
+// ── the fake model ──────────────────────────────────────────────────────────
+// No key, no network, no provider. createMockResponder yields real OpenAI
+// chat-completions SSE frames that readOpenAIStream parses on exactly the path
+// a live route would take. Replies cycle one per turn; the third scripts a
+// tool call so the thread's tool panel gets exercised too.
+const mockResponse = createMockResponder({
+  replies: [
+    'Hey — this thread is composed from standalone \`kai-*\` elements: ' +
+      '\`kai-thread\` for the transcript, \`kai-composer\` for input, and a host ' +
+      'module wiring them together.\\n\\nAttach a file with the paperclip and send it.',
+    'Got it. Anything you attach is staged in \`kai-attachments\` next to the ' +
+      'composer, then rides along as a \`file\` part on the message you send.',
+    {
+      text: 'Let me look that up.',
+      toolCalls: [
+        { name: 'search_docs', arguments: { query: 'composing a kai thread', limit: 3 } },
+      ],
+    },
+    'Streaming, tool calls, attachments and toasts all run through the same ' +
+      'host wiring — swapping the mock for a real \`/api/chat\` changes one line.',
+  ],
+  chunkSize: 2,
+});
+
+// ── conversations ───────────────────────────────────────────────────────────
+
+interface Conversation {
+  id: string;
+  title: string;
+  messages: ChatMessage[];
+}
+
+const conversations: Conversation[] = [
+  { id: crypto.randomUUID(), title: 'New chat', messages: [] },
+];
+let activeId = conversations[0].id;
+
+const active = (): Conversation =>
+  conversations.find((c) => c.id === activeId) ?? conversations[0];
+
+// ── element handles (typed once, after upgrade) ─────────────────────────────
+
+const el = <T extends HTMLElement>(id: string): T =>
+  document.getElementById(id) as T;
+
+/** A picked File as a \`data:\` URI — the ONE form every consumer of
+ *  \`AttachmentData.url\` accepts.
+ *
+ *  NOT an object URL: a \`blob:\` URL resolves only inside the tab that minted
+ *  it, so it renders a perfect preview here and is meaningless to anything
+ *  downstream — \`toOpenAIMessages\` / \`toAnthropicMessages\` refuse it with a
+ *  written reason, and before they refused it an attachment-only turn reached
+ *  the model as nothing at all. A data URI previews identically, survives a
+ *  reload, needs no revocation bookkeeping, and is what both providers take. */
+const readAsDataUrl = (file: File): Promise<string> =>
+  new Promise((resolve, reject) => {
+    const reader = new FileReader();
+    reader.onload = () => resolve(String(reader.result));
+    reader.onerror = () => reject(reader.error ?? new Error('Could not read ' + file.name));
+    reader.readAsDataURL(file);
+  });
+
+let staged: AttachmentData[] = [];
+let sending = false;
+
+async function main() {
+  // kai-* register through an async dynamic import (SSR-safety), so a property
+  // set before the upgrade is dropped. Wait for every element this host drives.
+  await Promise.all(
+    [
+      'kai-thread',
+      'kai-composer',
+      'kai-attachments',
+      'kai-conversation-item',
+      'kai-feedback-bar',
+      'kai-toast-region',
+    ].map((tag) => customElements.whenDefined(tag)),
+  );
+
+  const thread = el<KaiThreadElement>('thread');
+  const composer = el<KaiComposerElement>('composer');
+  const stagedEl = el<KaiAttachmentsElement>('staged');
+  const feedback = el<KaiFeedbackBarElement>('feedback');
+  const toastRegion = el<KaiToastRegionElement>('toasts');
+  const rail = el<HTMLElement>('conversations');
+  const title = el<HTMLElement>('pane-title');
+  const sendBtn = el<HTMLButtonElement>('send');
+  const attachBtn = el<HTMLButtonElement>('attach');
+  const fileInput = el<HTMLInputElement>('file-input');
+
+  // ── toasts ────────────────────────────────────────────────────────────────
+  // Driven as data rather than through the imperative toast(), because this app
+  // places its own <kai-toast-region> and owns the list. Don't ALSO call
+  // toast(): it would adopt this region and bind its own store over the
+  // toasts property, replacing the array this module owns.
+  let toasts: ToastItem[] = [];
+  const setToasts = (next: ToastItem[]) => {
+    toasts = next;
+    toastRegion.toasts = toasts; // new array reference every time
+  };
+  const notify = (message: string, item: Partial<ToastItem> = {}) =>
+    setToasts([...toasts, { id: crypto.randomUUID(), message, duration: 4000, ...item }]);
+
+  toastRegion.addEventListener('kai-dismiss', (event) => {
+    const { id } = (event as CustomEvent<{ id: string }>).detail;
+    setToasts(toasts.filter((t) => t.id !== id));
+  });
+
+  // ── rendering ─────────────────────────────────────────────────────────────
+
+  // Reassign, never mutate: the array reference is what tells the element
+  // something changed, and the row keys are the message objects themselves.
+  const setMessages = (next: ChatMessage[]) => {
+    active().messages = next;
+    thread.messages = next;
+  };
+
+  function renderRail() {
+    rail.replaceChildren(
+      ...conversations.map((conversation) => {
+        const row = document.createElement(
+          'kai-conversation-item',
+        ) as KaiConversationItemElement;
+        row.conversationId = conversation.id;
+        row.active = conversation.id === activeId;
+        row.compact = true;
+        row.textContent = conversation.title;
+
+        const meta = document.createElement('span');
+        meta.slot = 'meta';
+        meta.textContent = conversation.messages.length
+          ? conversation.messages.length + ' messages'
+          : 'Empty';
+        row.append(meta);
+
+        // Standalone rows activate THEMSELVES: outside <kai-conversations>
+        // the item's body is a tabbable button and click / Enter / Space fire
+        // kai-select on the item (non-bubbling — listen on the row, and take
+        // the id from detail rather than re-deriving it). What standalone rows
+        // do not get is the container's LIST story: roving tabindex and
+        // arrow-key traversal stay yours in a hand-rolled rail.
+        row.addEventListener('kai-select', (e) => {
+          select((e as CustomEvent<{ id: string }>).detail.id);
+        });
+        return row;
+      }),
+    );
+  }
+
+  function select(id: string) {
+    activeId = id;
+    const conversation = active();
+    title.textContent = conversation.title;
+    thread.messages = conversation.messages;
+    feedback.hidden = true;
+    renderRail();
+    composer.focus();
+  }
+
+  function renderStaged() {
+    stagedEl.items = staged; // JS property, new array each time
+    stagedEl.hidden = staged.length === 0;
+  }
+
+  // ── attaching a file ──────────────────────────────────────────────────────
+  // kai-composer has no attachment affordance of its own (unlike
+  // kai-prompt-input), so the picker and the staging tray are the host's.
+
+  attachBtn.addEventListener('click', () => fileInput.click());
+
+  fileInput.addEventListener('change', () => {
+    const picked = [...(fileInput.files ?? [])];
+    fileInput.value = ''; // so the same file can be picked twice
+    if (!picked.length) return;
+    void (async () => {
+      const added = await Promise.all(
+        picked.map(
+          async (file): Promise<AttachmentData> => ({
+            id: crypto.randomUUID(),
+            type: 'file',
+            filename: file.name,
+            mediaType: file.type || 'application/octet-stream',
+            url: await readAsDataUrl(file), // data: URI — see readAsDataUrl
+          }),
+        ),
+      );
+      staged = [...staged, ...added];
+      renderStaged();
+      notify(
+        picked.length === 1 ? 'Attached ' + picked[0].name : 'Attached ' + picked.length + ' files',
+        { variant: 'success' },
+      );
+    })();
+    composer.focus();
+  });
+
+  stagedEl.addEventListener('kai-remove', (event) => {
+    const { id } = (event as CustomEvent<{ id: string }>).detail;
+    // A data: URI needs no revocation — dropping the item is the whole cleanup.
+    staged = staged.filter((item) => item.id !== id);
+    renderStaged();
+  });
+
+  // ── sending ───────────────────────────────────────────────────────────────
+
+  sendBtn.addEventListener('click', () => composer.send());
+
+  composer.addEventListener('kai-submit', (event) => {
+    const { text } = (event as CustomEvent<{ text: string }>).detail;
+    void send(text);
+  });
+
+  async function send(rawText: string) {
+    const text = rawText.trim();
+    // An attachment on its own is a legitimate message; empty + empty is not.
+    if (sending || (!text && !staged.length)) return;
+
+    const attachments = staged;
+    staged = [];
+    renderStaged();
+    composer.clear();
+
+    // A message's content is an ordered parts array — the file parts sit after
+    // the text, which is how kai-message renders them under the bubble.
+    const parts: MessagePart[] = [
+      ...(text ? [{ type: 'text', text } as const] : []),
+      ...attachments.map((attachment) => ({ type: 'file', attachment }) as const),
+    ];
+
+    const history: ChatMessage[] = [
+      ...active().messages,
+      { id: crypto.randomUUID(), role: 'user', parts },
+    ];
+    setMessages(history);
+
+    // First real message names the conversation.
+    if (active().title === 'New chat') {
+      active().title = text
+        ? text.slice(0, 40)
+        : (attachments[0]?.filename ?? 'Attachment');
+      title.textContent = active().title;
+    }
+    renderRail();
+
+    setBusy(true);
+    feedback.hidden = true;
+
+    // createAssistantStream appends the in-flight assistant message and folds
+    // every delta onto the right part, handing back a fresh array each time.
+    const stream = createAssistantStream((update) => setMessages(update(active().messages)));
+
+    try {
+      const prompt = text || (attachments[0]?.filename ?? '');
+      const result = await readOpenAIStream(mockResponse(prompt), stream);
+      if (result.error) notify('Model error: ' + result.error.message, { variant: 'error' });
+
+      // The mock announces tool calls but nothing executes them, so the panel
+      // would sit in \`input-available\` forever. Resolve each one here — the
+      // same place a real app would put its tool result.
+      for (const call of result.toolCalls) {
+        stream.upsertTool(call.id, {
+          state: 'output-available',
+          output: {
+            note: 'Local stub result — the mock responder announces the call, this app answers it.',
+            query: call.input?.query ?? call.argumentsText,
+          },
+        });
+      }
+    } catch (error) {
+      // abort() settles the message AND puts the reason where the user can see
+      // it, instead of leaving a permanently blank bubble.
+      stream.abort(
+        error instanceof Error && error.message ? error.message : 'Request failed',
+      );
+      notify('The reply failed.', { variant: 'error' });
+      console.error(error);
+    } finally {
+      stream.done(); // settles the turn; sink calls after this are dropped
+      setBusy(false);
+      feedback.hidden = false;
+      renderRail();
+    }
+  }
+
+  function setBusy(busy: boolean) {
+    sending = busy;
+    thread.loading = busy;
+    composer.loading = busy;
+    sendBtn.disabled = busy;
+  }
+
+  // ── message actions & feedback ────────────────────────────────────────────
+
+  thread.addEventListener('kai-message-action', (event) => {
+    const { action, state } = (event as CustomEvent<{
+      messageId: string;
+      action: string;
+      state?: 'on' | 'off';
+    }>).detail;
+    if (action === 'copy') notify('Copied to clipboard');
+    else if (state === 'on') notify(action === 'like' ? 'Marked helpful' : 'Marked unhelpful');
+  });
+
+  feedback.categories = ['Wrong answer', 'Too slow', 'Missed my attachment', 'Other'];
+
+  feedback.addEventListener('kai-feedback', (event) => {
+    const { value } = (event as CustomEvent<{ value: 'helpful' | 'not-helpful' }>).detail;
+    if (value === 'helpful') notify('Thanks for the feedback', { variant: 'success' });
+  });
+
+  feedback.addEventListener('kai-feedback-detail', (event) => {
+    const { category } = (event as CustomEvent<{ category?: string }>).detail;
+    notify(category ? 'Feedback filed: ' + category : 'Feedback filed', {
+      variant: 'success',
+    });
+  });
+
+  feedback.addEventListener('kai-close', () => {
+    feedback.hidden = true;
+  });
+
+  // ── new chat ──────────────────────────────────────────────────────────────
+
+  el<HTMLButtonElement>('new-chat').addEventListener('click', () => {
+    const conversation: Conversation = {
+      id: crypto.randomUUID(),
+      title: 'New chat',
+      messages: [],
+    };
+    conversations.unshift(conversation);
+    select(conversation.id);
+  });
+
+  // ── boot ──────────────────────────────────────────────────────────────────
+
+  renderRail();
+  renderStaged();
+  select(activeId);
+}
+
+void main();
+`
+    },
+    {
+      path: "src/styles.css",
+      lang: "css",
+      code: `:root {
+  color-scheme: light;
+  --rail-w: 15rem;
+}
+
+* { box-sizing: border-box; }
+
+html, body { height: 100%; }
+
+body {
+  margin: 0;
+  font-family: ui-sans-serif, system-ui, -apple-system, "Segoe UI", sans-serif;
+  background: var(--color-background, #fff);
+  color: var(--color-foreground, #111);
+}
+
+.app {
+  position: fixed;
+  inset: 0;
+  display: grid;
+  grid-template-columns: var(--rail-w) 1fr;
+  text-align: start;
+  /* Stays below the toast region's z-index (var(--kai-toast-z, 100)). */
+  z-index: 90;
+}
+
+/* ── sidebar ─────────────────────────────────────────────── */
+
+.rail {
+  display: flex;
+  flex-direction: column;
+  min-height: 0;
+  border-right: 1px solid var(--color-border, #e5e5e5);
+  background: var(--color-muted, #fafafa);
+}
+
+.rail-head {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 0.5rem;
+  padding: 0.75rem 0.75rem 0.5rem;
+}
+
+.rail-title {
+  font-size: 0.75rem;
+  font-weight: 600;
+  letter-spacing: 0.04em;
+  text-transform: uppercase;
+  opacity: 0.6;
+}
+
+.rail-list {
+  flex: 1;
+  min-height: 0;
+  overflow-y: auto;
+  padding: 0 0.5rem 0.75rem;
+  display: flex;
+  flex-direction: column;
+  gap: 0.125rem;
+}
+
+kai-conversation-item { display: block; }
+kai-conversation-item::part(row) { border-radius: 0.5rem; }
+
+/* ── main pane ───────────────────────────────────────────── */
+
+.pane {
+  display: flex;
+  flex-direction: column;
+  min-height: 0;
+  min-width: 0;
+}
+
+.pane-head {
+  display: flex;
+  align-items: baseline;
+  gap: 0.75rem;
+  padding: 0.75rem 1rem;
+  border-bottom: 1px solid var(--color-border, #e5e5e5);
+}
+
+.pane-head h1 {
+  margin: 0;
+  font-size: 0.9375rem;
+  font-weight: 600;
+}
+
+.badge {
+  font-size: 0.6875rem;
+  padding: 0.125rem 0.5rem;
+  border-radius: 999px;
+  border: 1px solid var(--color-border, #e5e5e5);
+  opacity: 0.7;
+}
+
+/* kai-thread fills the height its parent gives it and scrolls internally,
+   so the pane is a flex column and the thread is the flexing row. */
+.thread {
+  display: block;
+  flex: 1;
+  min-height: 0;
+}
+
+.empty {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  gap: 0.25rem;
+  padding: 3rem 1rem;
+  text-align: center;
+  font-size: 0.875rem;
+  opacity: 0.75;
+}
+
+.empty p { margin: 0; }
+
+.feedback {
+  display: block;
+  padding: 0 1rem 0.5rem;
+}
+
+.feedback[hidden] { display: none; }
+
+/* ── composer ────────────────────────────────────────────── */
+
+.composer-bar {
+  border-top: 1px solid var(--color-border, #e5e5e5);
+  padding: 0.625rem 1rem 0.875rem;
+  display: flex;
+  flex-direction: column;
+  gap: 0.5rem;
+}
+
+.staged { display: block; }
+.staged[hidden] { display: none; }
+
+.composer-row {
+  display: flex;
+  align-items: flex-end;
+  gap: 0.5rem;
+}
+
+.composer {
+  display: block;
+  flex: 1;
+  min-width: 0;
+}
+
+.icon-btn,
+.send-btn,
+.ghost-btn {
+  font: inherit;
+  cursor: pointer;
+  border-radius: 0.5rem;
+  border: 1px solid var(--color-border, #e5e5e5);
+  background: var(--color-background, #fff);
+  color: inherit;
+}
+
+.icon-btn {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  width: 2.25rem;
+  height: 2.25rem;
+  flex: none;
+}
+
+.send-btn {
+  height: 2.25rem;
+  padding: 0 0.875rem;
+  flex: none;
+  font-weight: 600;
+  background: var(--color-primary, #111);
+  color: var(--color-primary-foreground, #fff);
+  border-color: transparent;
+}
+
+.send-btn:disabled { opacity: 0.5; cursor: default; }
+
+.ghost-btn {
+  padding: 0.25rem 0.5rem;
+  font-size: 0.75rem;
+}
+
+.icon-btn:hover,
+.ghost-btn:hover { background: var(--color-accent, #f0f0f0); }
+`
+    }
+  ]
+};
+const codeRecipes = [composedThread];
+function listCodeRecipes() {
+  return codeRecipes;
+}
+function getCodeRecipe(id) {
+  return codeRecipes.find((r) => r.id === id);
+}
 const JS_ONLY_TYPE_PATTERNS = /\[\]|\{|Record</;
 function isJsOnlyType(typeText) {
   return typeText ? JS_ONLY_TYPE_PATTERNS.test(typeText) : false;
@@ -1255,8 +2002,8 @@ function catalogSectionLines(tag) {
         // `renderRecipeAppendix` carries the notes exactly once.
         "- **Wiring** — event out of A, property into B, wired by the host:"
       );
-      for (const w2 of r.wiring) {
-        lines.push(`  - \`<${w2.from}>\` fires \`${w2.event}\` → host sets \`${w2.to}.${w2.property}\``);
+      for (const w of r.wiring) {
+        lines.push(`  - \`<${w.from}>\` fires \`${w.event}\` → host sets \`${w.to}.${w.property}\``);
       }
     }
   }
@@ -1279,9 +2026,9 @@ function renderRecipeAppendix() {
       ...compositionLines(r, " — "),
       "- **Wiring** — event out of A, property into B, wired by the host:"
     );
-    for (const w2 of r.wiring) {
+    for (const w of r.wiring) {
       lines.push(
-        `  - \`<${w2.from}>\` fires \`${w2.event}\` → host sets \`${w2.to}.${w2.property}\`` + (w2.note ? ` — ${w2.note}` : "")
+        `  - \`<${w.from}>\` fires \`${w.event}\` → host sets \`${w.to}.${w.property}\`` + (w.note ? ` — ${w.note}` : "")
       );
     }
   }
@@ -1304,6 +2051,43 @@ function renderInvariantAppendix() {
   }
   return lines;
 }
+const PROGRAMMATIC_ALIASES = ["programmatic", "state", "wire", "state-wire"];
+const PROGRAMMATIC_START = "<!-- kai:programmatic:start -->";
+const PROGRAMMATIC_END = "<!-- kai:programmatic:end -->";
+function renderProgrammaticAppendix() {
+  const path = join(dirname(resolveManifestPath()), "..", "llms-full.txt");
+  const missing = (what) => `Missing build artifact: ${what}
+
+The programmatic-layer reference is generated from the shipped dist/*.d.ts by the build (a marker-fenced section of the package-root llms-full.txt). Run \`nx build ui\` (or \`npm run build:api\` in packages/ui) and ask again. It is deliberately not restated here: a hand-typed copy would drift from the declarations your editor shows.`;
+  if (!existsSync(path)) return missing(path);
+  const full = readFileSync(path, "utf-8");
+  const start = full.indexOf(PROGRAMMATIC_START);
+  const end = full.indexOf(PROGRAMMATIC_END);
+  if (start === -1 || end === -1 || end <= start) {
+    return missing(`the ${PROGRAMMATIC_START} section inside ${path}`);
+  }
+  return full.slice(start + PROGRAMMATIC_START.length, end).trim();
+}
+function renderCodeRecipe(r) {
+  const lines = [
+    `## Recipe: ${r.title} (\`${r.id}\`)`,
+    "",
+    r.intent,
+    "",
+    `**Elements composed:** ${r.ingredients.map((t) => `\`<${t}>\``).join(", ")}`,
+    "",
+    "**Read these before pasting:**",
+    ...r.notes.map((n) => `- ${n}`)
+  ];
+  for (const f2 of r.files) {
+    lines.push("", `### \`${f2.path}\``, "", "```" + f2.lang, f2.code.trimEnd(), "```");
+  }
+  lines.push(
+    "",
+    `The wiring topology, invariants and composition claims behind this recipe are the surface recipe of the same id — call component_reference with { name: "recipes" }.`
+  );
+  return lines.join("\n");
+}
 function eventDetail(typeText) {
   const m = /^CustomEvent<([\s\S]*)>$/.exec(typeText?.trim() ?? "");
   return m ? m[1].trim() || void 0 : void 0;
@@ -1458,10 +2242,10 @@ Call component_reference with no name (or name: "list") to list all ${all.length
 }
 const reference = {
   name: "component_reference",
-  description: "Look up AI/UI (kai-*) web components: their tags, props, events, imperative methods, and usage examples. For a card-backed element it also returns the card's JSON Schema and a ready-to-send tool definition generated from it — pass `provider` to get that provider's envelope.",
+  description: 'Look up AI/UI (kai-*) web components: their tags, props, events, imperative methods, and usage examples. For a card-backed element it also returns the card\'s JSON Schema and a ready-to-send tool definition generated from it — pass `provider` to get that provider\'s envelope. Also serves the programmatic layer (name: "programmatic" — the @kitn.ai/ui/state + @kitn.ai/ui/wire streaming/mock/encode API) and complete code recipes (e.g. name: "composed-thread" — a hand-composed thread with no <kai-chat>).',
   inputSchema: z$1.object({
     name: z$1.string().optional().describe(
-      'The element tag, e.g. "kai-chat". Omit it (or pass "list") to get the index of every element with a one-line summary, then ask again for the one you want. Pass "invariants" for the full diagnosis and wrong/right examples behind every invariant id an element lookup shows. Pass "recipes" for the full wiring notes behind every surface recipe an element lookup names.'
+      'The element tag, e.g. "kai-chat". Omit it (or pass "list") to get the index of every element with a one-line summary, then ask again for the one you want. Pass "invariants" for the full diagnosis and wrong/right examples behind every invariant id an element lookup shows. Pass "recipes" for the full wiring notes behind every surface recipe an element lookup names. Pass "programmatic" (or "state" / "wire") for the @kitn.ai/ui/state + @kitn.ai/ui/wire API — streaming folds, the mock responder, the SSE readers/encoders. Pass a code-recipe id (e.g. "composed-thread") for a complete pasteable composition.'
     ),
     provider: z$1.enum(PROVIDERS).optional().describe(
       `Which tool-definition envelope to project for a card-backed element. Defaults to "${DEFAULT_PROVIDER}", the provider-neutral { name, description, schema } form.`
@@ -1500,11 +2284,19 @@ The elements that HOST them (and carry the \`cardTypes\` / \`cardSchemas\` props
 
 Call component_reference with { name: "invariants" } for the full diagnosis and wrong/right examples behind every invariant id shown on an element lookup.
 
-Call component_reference with { name: "recipes" } for the full wiring notes behind every surface recipe an element lookup names.`;
+Call component_reference with { name: "recipes" } for the full wiring notes behind every surface recipe an element lookup names.
+
+Call component_reference with { name: "programmatic" } for the @kitn.ai/ui/state + @kitn.ai/ui/wire API — createAssistantStream, the part folds, createMockResponder (and its scripted tool calls), the SSE readers and the provider encoders. That layer is what a host wires when it composes elements by hand instead of using <kai-chat>.
+
+Complete pasteable compositions (code recipes): ${listCodeRecipes().map((r) => `{ name: "${r.id}" } — ${r.title}`).join("; ")}.`;
     } else if (name === "invariants") {
       text2 = renderInvariantAppendix().join("\n");
     } else if (name === "recipes") {
       text2 = renderRecipeAppendix().join("\n");
+    } else if (PROGRAMMATIC_ALIASES.includes(name)) {
+      text2 = renderProgrammaticAppendix();
+    } else if (getCodeRecipe(name)) {
+      text2 = renderCodeRecipe(getCodeRecipe(name));
     } else {
       text2 = formatReference(name, provider);
     }
@@ -4541,8 +5333,8 @@ function slottedInChat(components) {
   });
 }
 function railSiblingNote(tag, placement) {
-  const w2 = conversationsWiring();
-  const handler = `on${toPascalCase(w2.event)}`;
+  const w = conversationsWiring();
+  const handler = `on${toPascalCase(w.event)}`;
   return [
     `      {/* NOT WIRED, and NOT SLOTTED — both deliberate, both fixable here.`,
     `          COMPOSITION: the kit composes this as <${tag} slot="${placement.slot}"> INSIDE`,
@@ -4550,7 +5342,7 @@ function railSiblingNote(tag, placement) {
     `          The generated React wrappers take no \`slot\` prop (see WebComponentProps`,
     `          in @kitn.ai/ui/react), so this renders as a sibling instead. Drop to the`,
     `          raw <${placement.parent}> custom element if you want the slotted layout.`,
-    `          WIRING: set ${w2.property}={...} and ${handler}={...} — the handler`,
+    `          WIRING: set ${w.property}={...} and ${handler}={...} — the handler`,
     `          reads event.detail.id and calls setMessages with that thread. */}`
   ];
 }
@@ -4560,7 +5352,7 @@ function htmlComment(lines, pad) {
   );
 }
 function slottedChildMarkup(components, pad, opts) {
-  const w2 = conversationsWiring();
+  const w = conversationsWiring();
   return slottedInChat(components).flatMap((s) => [
     // What the shell DOES, and — the half a comment gets wrong by being generous
     // — what it does not. `<kai-chat>`'s sidebar region is one fixed-width aside
@@ -4577,7 +5369,7 @@ function slottedChildMarkup(components, pad, opts) {
       ],
       pad
     ),
-    ...opts.wired ? [] : htmlComment(notWiredNote(s.tag, w2.property, w2.event), pad),
+    ...opts.wired ? [] : htmlComment(notWiredNote(s.tag, w.property, w.event), pad),
     `${pad}<${s.tag}${opts.ids ? ` id="${s.tag.replace(/^kai-/, "")}"` : ""} slot="${s.slot}" style="display:block;height:100%"></${s.tag}>`
   ]);
 }
@@ -4590,7 +5382,7 @@ function notWiredNote(tag, property, event) {
   ];
 }
 function conversationsWiring() {
-  const edge = surfaceRecipes.flatMap((r) => r.wiring).find((w2) => w2.from === "kai-conversations" && w2.to === "kai-chat" && w2.property === "messages");
+  const edge = surfaceRecipes.flatMap((r) => r.wiring).find((w) => w.from === "kai-conversations" && w.to === "kai-chat" && w.property === "messages");
   return { property: "conversations", event: edge?.event ?? "kai-conversation-select" };
 }
 const ATTACHMENT_TAGS = /* @__PURE__ */ new Set(["kai-file-upload", "kai-attachments"]);
@@ -8205,7 +8997,7 @@ const scaffold = {
     );
   }
 };
-const themeCss = "/* @kitn.ai/ui design system — import after `@import \"tailwindcss\"`.\n   Defines ONLY namespaced (--color-*) tokens, component keyframes, animation\n   utilities, and the .chat-markdown styles. Contains NO global base/reset rules,\n   so importing it restyles nothing on its own — a host opts in via the kit's\n   components + classes. Rebrand by overriding the --color-* values (optionally\n   scoped to a subtree).\n   NOTE: This file is Tailwind-v4 source (requires tailwindcss as a peer). For\n   bundler-based apps that don't use Tailwind, import @kitn.ai/ui/theme.tokens.css\n   instead — it is plain compiled CSS with no toolchain requirements. */\n\n@custom-variant dark (&:is(.dark *));\n\n@theme {\n  --color-background: var(--kai-color-background, hsl(0 0% 100%));\n  --color-foreground: var(--kai-color-foreground, hsl(240 10% 3.9%));\n  --color-card: var(--kai-color-card, hsl(0 0% 100%));\n  --color-card-foreground: var(--kai-color-card-foreground, hsl(240 10% 3.9%));\n  --color-popover: var(--kai-color-popover, hsl(0 0% 100%));\n  --color-popover-foreground: var(--kai-color-popover-foreground, hsl(240 10% 3.9%));\n  --color-primary: var(--kai-color-primary, hsl(240 5.9% 10%));\n  --color-primary-foreground: var(--kai-color-primary-foreground, hsl(0 0% 98%));\n  --color-secondary: var(--kai-color-secondary, hsl(240 4.8% 95.9%));\n  --color-secondary-foreground: var(--kai-color-secondary-foreground, hsl(240 5.9% 10%));\n  --color-muted: var(--kai-color-muted, hsl(240 4.8% 95.9%));\n  --color-muted-foreground: var(--kai-color-muted-foreground, hsl(240 3.8% 43%));\n  /* Subtle SURFACE — an opaque \"muted panel\" for things that sit OVER content\n     (the prompt input, message bubbles, artifact/card headers, chips). CALCULATED\n     from existing tokens — `--color-muted` blended 40% onto `--color-background`\n     — so it tracks the theme (incl. dark) automatically and needs no hand-picked\n     value. SOLID (no alpha), so nothing behind it bleeds through. This replaces\n     ad-hoc `bg-muted/40` surfaces. Retint via the --kai-color-surface knob (or a\n     bare value); --color-surface-strong is the stronger step (hover/raised) and\n     --color-surface-sunken is recessed BELOW the base surface (wells, or a banner\n     that sits behind a card). Sunken is theme-specific: \"darker than the card\"\n     means a LOWER muted% in dark but a HIGHER one in light, so the two scopes\n     can't share a number — see the .dark block. */\n  --color-surface: var(--kai-color-surface, color-mix(in srgb, var(--color-muted) 40%, var(--color-background)));\n  --color-surface-strong: var(--kai-color-surface-strong, color-mix(in srgb, var(--color-muted) 60%, var(--color-background)));\n  --color-surface-sunken: var(--kai-color-surface-sunken, color-mix(in srgb, var(--color-muted) 85%, var(--color-background)));\n  --color-accent: var(--kai-color-accent, hsl(240 4.8% 95.9%));\n  --color-accent-foreground: var(--kai-color-accent-foreground, hsl(240 5.9% 10%));\n  --color-destructive: var(--kai-color-destructive, hsl(0 72% 45%));\n  --color-destructive-foreground: var(--kai-color-destructive-foreground, hsl(0 0% 98%));\n  /* Semantic status colors - solid fills with a legible foreground, matched to\n     the kit's tool-green / -amber / -blue hues so they read on-brand. Use\n     bg-success / bg-warning / bg-info with the matching -foreground for badges,\n     banners, and buttons; or text-success / -warning / -info on a soft tint\n     (below). destructive (above) is the danger/error member of the same family.\n     Light uses darker hues so the color carries a light foreground AND stays\n     legible as text on a pale tint; dark (see .dark) flips to brighter hues over\n     a near-black foreground. Override via --kai-color-success / -warning / -info\n     (+ -foreground). */\n  --color-success: var(--kai-color-success, hsl(142 71% 30%));\n  --color-success-foreground: var(--kai-color-success-foreground, hsl(0 0% 98%));\n  --color-warning: var(--kai-color-warning, hsl(38 92% 30%));\n  --color-warning-foreground: var(--kai-color-warning-foreground, hsl(0 0% 98%));\n  --color-info: var(--kai-color-info, hsl(217 91% 42%));\n  --color-info-foreground: var(--kai-color-info-foreground, hsl(0 0% 98%));\n  /* Soft tinted status surfaces - OPAQUE, theme-tracking fills derived as ~14% of\n     the status hue blended onto the background. Use these for subtle callouts /\n     banners instead of an eyeballed bg-success/10; pair with text-success /\n     -warning / -info / -destructive. Derived, so declared in BOTH light and dark\n     (a color-mix resolves where it's declared - see the surface tokens above). A\n     bare bg- utility for a color-mix token is added at the bottom (see bg-surface). */\n  --color-success-soft: var(--kai-color-success-soft, color-mix(in oklab, var(--color-success) 14%, var(--color-background)));\n  --color-warning-soft: var(--kai-color-warning-soft, color-mix(in oklab, var(--color-warning) 14%, var(--color-background)));\n  --color-info-soft: var(--kai-color-info-soft, color-mix(in oklab, var(--color-info) 14%, var(--color-background)));\n  --color-destructive-soft: var(--kai-color-destructive-soft, color-mix(in oklab, var(--color-destructive) 14%, var(--color-background)));\n  /* Interaction-state backgrounds - opaque, theme-tracking fills for row/control\n     states so consumers stop eyeballing /10 opacities. --color-hover is a subtle\n     neutral (a little --color-muted on the background); --color-selected is a\n     faint --color-primary tint so a selected row tracks the brand. Use bg-hover /\n     bg-selected. Derived, so declared in BOTH light and dark; bare bg- utilities\n     added at the bottom. */\n  --color-hover: var(--kai-color-hover, color-mix(in oklab, var(--color-muted) 60%, var(--color-background)));\n  --color-selected: var(--kai-color-selected, color-mix(in oklab, var(--color-primary) 8%, var(--color-background)));\n  --color-border: var(--kai-color-border, hsl(240 5.9% 90%));\n  --color-input: var(--kai-color-input, hsl(240 5.9% 90%));\n  /* Focus ring — a deliberate blue (not a neutral) so keyboard focus is always\n     obvious and on-brand in both modes. Light uses a strong blue; dark uses a\n     brighter one for contrast on dark surfaces. Both clear WCAG 2.1 non-text\n     contrast (≥3:1) against the kit's backgrounds. Override via --kai-color-ring. */\n  --color-ring: var(--kai-color-ring, hsl(217 91% 53%));\n  /* Custom scrollbars — thin, rounded, subtle; thumb strengthens on hover. A\n     consistent cross-platform look (the kit styles its OWN scroll regions inside\n     the shadow root; the track stays transparent so nothing is forced where no\n     scrollbar is needed). Override via --kai-color-scrollbar-thumb(-hover). */\n  --color-scrollbar-thumb: var(--kai-color-scrollbar-thumb, hsl(240 5% 80%));\n  --color-scrollbar-thumb-hover: var(--kai-color-scrollbar-thumb-hover, hsl(240 4% 64%));\n  --color-sidebar: var(--kai-color-sidebar, hsl(0 0% 100%));\n\n  /* Inline `code` accent. Blue text on a translucent blue chip. */\n  --color-code-foreground: var(--kai-color-code-foreground, hsl(224.3 76.3% 48%));\n\n  /* Tool/status chip hues. Each chip is hue text over a 15% translucent fill of\n     the SAME hue (set in tool.tsx). The bare hue is too light to reach WCAG AA\n     (4.5:1) on the faint fill in LIGHT mode, so the light values are darkened;\n     dark mode keeps brighter hues for AA on the dark fill. Override via\n     --kai-color-tool-* to retheme. */\n  --color-tool-blue: var(--kai-color-tool-blue, hsl(217 91% 38%));\n  --color-tool-amber: var(--kai-color-tool-amber, hsl(38 92% 28%));\n  --color-tool-green: var(--kai-color-tool-green, hsl(142 71% 26%));\n  --color-tool-red: var(--kai-color-tool-red, hsl(0 72% 42%));\n\n  --radius: var(--kai-radius, 0.6rem);\n  --radius-sm: calc(var(--radius) - 4px);\n  --radius-md: calc(var(--radius) - 2px);\n  --radius-lg: var(--radius);\n  --radius-xl: calc(var(--radius) + 4px);\n\n  /* Typography scale — semantic sizes shared by all components. Each generates a\n     Tailwind utility (text-caption / text-meta / text-body / text-title). To\n     restyle the kit's typography, override the namespaced --kai-text-* token on\n     :root (e.g. `--kai-text-body: 0.9375rem`) — it pierces the Shadow DOM via the\n     var() fallback, exactly like the --kai-color-* tokens. The bare --text-*\n     names stay internal so a host's own --text-* can't collide. (Message/markdown/\n     input reading size also scales with the `proseSize` prop; these tokens cover\n     the fixed chrome & controls.) */\n  --text-caption: var(--kai-text-caption, 0.6875rem);  --text-caption--line-height: 1rem;      /* 11px — micro labels, badges, sub-counts */\n  --text-meta: var(--kai-text-meta, 0.75rem);     --text-meta--line-height: 1.1rem;       /* 12px — controls, toggles, switchers, captions */\n  --text-body: var(--kai-text-body, 0.875rem);    --text-body--line-height: 1.45rem;      /* 14px — primary reading text */\n  --text-title: var(--kai-text-title, 1rem);        --text-title--line-height: 1.5rem;      /* 16px — emphasis / headers */\n\n  @keyframes typing { 0%,100% { transform: translateY(0); opacity: .5 } 50% { transform: translateY(-2px); opacity: 1 } }\n  @keyframes loading-dots { 0%,100% { opacity: 0 } 50% { opacity: 1 } }\n  @keyframes wave { 0%,100% { transform: scaleY(1) } 50% { transform: scaleY(.6) } }\n  @keyframes blink { 0%,100% { opacity: 1 } 50% { opacity: 0 } }\n  @keyframes text-blink { 0%,100% { color: var(--color-primary) } 50% { color: var(--color-muted-foreground) } }\n  @keyframes bounce-dots { 0%,100% { transform: scale(.8); opacity: .5 } 50% { transform: scale(1.2); opacity: 1 } }\n  @keyframes thin-pulse { 0%,100% { transform: scale(.95); opacity: .8 } 50% { transform: scale(1.05); opacity: .4 } }\n  @keyframes pulse-dot { 0%,100% { transform: scale(1); opacity: .8 } 50% { transform: scale(1.5); opacity: 1 } }\n  @keyframes shimmer-text { 0% { background-position: 150% center } 100% { background-position: -150% center } }\n  @keyframes wave-bars { 0%,100% { transform: scaleY(1); opacity: .5 } 50% { transform: scaleY(.6); opacity: 1 } }\n  @keyframes shimmer { 0% { background-position: 200% 50% } 100% { background-position: -200% 50% } }\n  @keyframes spinner-fade { 0% { opacity: 0 } 100% { opacity: 1 } }\n  @keyframes collapsible-down { from { height: 0; opacity: 0 } to { height: var(--kb-collapsible-content-height); opacity: 1 } }\n  @keyframes collapsible-up { from { height: var(--kb-collapsible-content-height); opacity: 1 } to { height: 0; opacity: 0 } }\n}\n\n.dark {\n  --color-background: var(--kai-color-background, hsl(50 2% 9%));\n  --color-foreground: var(--kai-color-foreground, hsl(0 0% 98%));\n  --color-card: var(--kai-color-card, hsl(45 4% 12%));\n  --color-card-foreground: var(--kai-color-card-foreground, hsl(0 0% 98%));\n  --color-popover: var(--kai-color-popover, hsl(45 4% 12%));\n  --color-popover-foreground: var(--kai-color-popover-foreground, hsl(0 0% 98%));\n  --color-primary: var(--kai-color-primary, hsl(0 0% 98%));\n  --color-primary-foreground: var(--kai-color-primary-foreground, hsl(45 4% 11%));\n  --color-secondary: var(--kai-color-secondary, hsl(45 4% 17%));\n  --color-secondary-foreground: var(--kai-color-secondary-foreground, hsl(0 0% 98%));\n  --color-muted: var(--kai-color-muted, hsl(45 4% 17%));\n  --color-muted-foreground: var(--kai-color-muted-foreground, hsl(45 4% 64%));\n  /* Re-declared in the dark scope so the color-mix recomputes with the DARK\n     muted/background (a derived token is computed where it's declared, not where\n     it's used — see the light --color-surface for the full note). */\n  --color-surface: var(--kai-color-surface, color-mix(in srgb, var(--color-muted) 40%, var(--color-background)));\n  --color-surface-strong: var(--kai-color-surface-strong, color-mix(in srgb, var(--color-muted) 60%, var(--color-background)));\n  /* Sunken: in dark a LOWER muted% is darker (blends toward the dark background). */\n  --color-surface-sunken: var(--kai-color-surface-sunken, color-mix(in srgb, var(--color-muted) 18%, var(--color-background)));\n  --color-accent: var(--kai-color-accent, hsl(45 4% 17%));\n  --color-accent-foreground: var(--kai-color-accent-foreground, hsl(0 0% 98%));\n  --color-destructive: var(--kai-color-destructive, hsl(0 62.8% 30.6%));\n  --color-destructive-foreground: var(--kai-color-destructive-foreground, hsl(0 0% 98%));\n  /* Semantic status colors - dark mode flips to the brighter tool-* dark hues\n     (matching the chip values) carried over a near-black foreground, so the color\n     both reads as text on a dark soft tint AND backs a legible foreground. See\n     the light @theme note. */\n  --color-success: var(--kai-color-success, hsl(142 71% 45%));\n  --color-success-foreground: var(--kai-color-success-foreground, hsl(45 4% 11%));\n  --color-warning: var(--kai-color-warning, hsl(38 92% 50%));\n  --color-warning-foreground: var(--kai-color-warning-foreground, hsl(45 4% 11%));\n  --color-info: var(--kai-color-info, hsl(217 91% 70%));\n  --color-info-foreground: var(--kai-color-info-foreground, hsl(45 4% 11%));\n  /* Soft status surfaces + interaction states - re-declared so each color-mix\n     recomputes with the DARK hues/background (a derived token resolves where it's\n     declared; see the light block for the full note). */\n  --color-success-soft: var(--kai-color-success-soft, color-mix(in oklab, var(--color-success) 14%, var(--color-background)));\n  --color-warning-soft: var(--kai-color-warning-soft, color-mix(in oklab, var(--color-warning) 14%, var(--color-background)));\n  --color-info-soft: var(--kai-color-info-soft, color-mix(in oklab, var(--color-info) 14%, var(--color-background)));\n  --color-destructive-soft: var(--kai-color-destructive-soft, color-mix(in oklab, var(--color-destructive) 14%, var(--color-background)));\n  --color-hover: var(--kai-color-hover, color-mix(in oklab, var(--color-muted) 60%, var(--color-background)));\n  --color-selected: var(--kai-color-selected, color-mix(in oklab, var(--color-primary) 8%, var(--color-background)));\n  --color-border: var(--kai-color-border, hsl(45 4% 17%));\n  --color-input: var(--kai-color-input, hsl(45 4% 17%));\n  --color-ring: var(--kai-color-ring, hsl(217 91% 68%));\n  --color-scrollbar-thumb: var(--kai-color-scrollbar-thumb, hsl(45 3% 30%));\n  --color-scrollbar-thumb-hover: var(--kai-color-scrollbar-thumb-hover, hsl(45 3% 42%));\n  --color-sidebar: var(--kai-color-sidebar, hsl(50 2% 7%));\n  --color-code-foreground: var(--kai-color-code-foreground, hsl(213 94% 78%));\n\n  /* Tool/status chip hues — dark mode. Brighter hues reach AA on the dark fill. */\n  --color-tool-blue: var(--kai-color-tool-blue, hsl(217 91% 70%));\n  --color-tool-amber: var(--kai-color-tool-amber, hsl(38 92% 50%));\n  --color-tool-green: var(--kai-color-tool-green, hsl(142 71% 45%));\n  --color-tool-red: var(--kai-color-tool-red, hsl(0 84% 70%));\n}\n\n/* Self-contained markdown styling — replaces the typography plugin's `prose`.\n   Keyed on --color-* tokens so it themes with the rest of the kit. */\n.chat-markdown { color: var(--color-foreground); line-height: 1.6; }\n.chat-markdown > div:first-child > :first-child { margin-top: 0; }\n.chat-markdown > div:last-child > :last-child { margin-bottom: 0; }\n.chat-markdown p { margin: 0 0 0.75em; }\n.chat-markdown p:last-child { margin-bottom: 0; }\n.chat-markdown h1, .chat-markdown h2, .chat-markdown h3, .chat-markdown h4 {\n  margin: 1.2em 0 0.5em; font-weight: 600; line-height: 1.3; color: var(--color-foreground);\n}\n.chat-markdown h1 { font-size: 1.4em; } .chat-markdown h2 { font-size: 1.25em; }\n.chat-markdown h3 { font-size: 1.1em; } .chat-markdown h4 { font-size: 1em; }\n.chat-markdown ul, .chat-markdown ol { margin: 0 0 0.75em; padding-left: 1.4em; }\n.chat-markdown li { margin: 0.2em 0; }\n.chat-markdown ul { list-style: disc; } .chat-markdown ol { list-style: decimal; }\n.chat-markdown a { color: var(--color-primary); text-decoration: underline; text-underline-offset: 2px; }\n.chat-markdown strong { font-weight: 600; color: var(--color-foreground); }\n.chat-markdown em { font-style: italic; }\n.chat-markdown blockquote {\n  margin: 0 0 0.75em; padding-left: 0.9em; border-left: 2px solid var(--color-border);\n  color: var(--color-muted-foreground);\n}\n.chat-markdown hr { margin: 1em 0; border: 0; border-top: 1px solid var(--color-border); }\n.chat-markdown code:not(pre code) {\n  background: color-mix(in oklab, var(--color-code-foreground) 15%, transparent);\n  color: var(--color-code-foreground);\n  border-radius: 4px; padding: 0.1em 0.35em; font-size: 0.875em;\n  font-family: var(--kai-font-code, ui-monospace, \"SF Mono\", Menlo, monospace);\n}\n.chat-markdown table { width: 100%; border-collapse: collapse; margin: 0 0 0.75em; font-size: 0.9em; }\n.chat-markdown th, .chat-markdown td { border: 1px solid var(--color-border); padding: 0.4em 0.6em; text-align: left; }\n.chat-markdown th { font-weight: 600; background: color-mix(in oklab, var(--color-muted-foreground) 8%, transparent); }\n\n/* Themeable elevation. The kit is mostly flat (borders), but a few surfaces lift\n   off the page — popovers, dropdowns, hover cards, cards. The shadow COLOR is a\n   token (--kai-shadow-color, default near-black); set it transparent for a fully\n   flat look, or tint it to match a theme. Defined here (not as a Tailwind shadow\n   utility) so the color stays overridable and works in both the web-component and\n   SolidJS layers. */\n.kai-elevation {\n  box-shadow:\n    0 4px 12px -2px color-mix(in oklab, var(--kai-shadow-color, oklch(0 0 0)) 14%, transparent),\n    0 2px 6px -2px color-mix(in oklab, var(--kai-shadow-color, oklch(0 0 0)) 10%, transparent);\n}\n.kai-elevation-sm {\n  box-shadow: 0 1px 2px 0 color-mix(in oklab, var(--kai-shadow-color, oklch(0 0 0)) 8%, transparent);\n}\n\n/* Cross-platform thin scrollbar utility (Firefox + WebKit). Used by ScrollArea\n   and any scroll region in the SolidJS-component build (web components also get\n   this globally inside their shadow root — see src/elements/styles.css). */\n.scrollbar-thin {\n  scrollbar-width: thin;\n  scrollbar-color: var(--color-scrollbar-thumb) transparent;\n}\n.scrollbar-thin::-webkit-scrollbar { width: 8px; height: 8px; }\n.scrollbar-thin::-webkit-scrollbar-track { background: transparent; }\n.scrollbar-thin::-webkit-scrollbar-thumb {\n  background-color: var(--color-scrollbar-thumb);\n  border-radius: 9999px;\n  border: 2px solid transparent;\n  background-clip: padding-box;\n}\n.scrollbar-thin::-webkit-scrollbar-thumb:hover { background-color: var(--color-scrollbar-thumb-hover); }\n.scrollbar-thin::-webkit-scrollbar-corner { background: transparent; }\n\n/* Surface utilities — `bg-surface` / `bg-surface-strong` paint the opaque,\n   theme-derived surface tokens (see --color-surface above). Defined explicitly\n   because a color-mix-valued @theme token does NOT emit a bare `bg-` utility on\n   its own (only opacity variants). Use these for panels that sit OVER content\n   instead of `bg-muted/NN`. */\n@utility bg-surface {\n  background-color: var(--color-surface);\n}\n@utility bg-surface-strong {\n  background-color: var(--color-surface-strong);\n}\n@utility bg-surface-sunken {\n  background-color: var(--color-surface-sunken);\n}\n\n/* Soft-status + interaction-state utilities. Same reason as bg-surface above: a\n   color-mix-valued @theme token does NOT emit a bare `bg-` utility on its own, so\n   bg-success-soft / bg-warning-soft / bg-info-soft / bg-destructive-soft and\n   bg-hover / bg-selected are declared here. (The SOLID tokens - success / warning\n   / info + their -foreground - are plain hsl values, so bg-success / text-success\n   etc. ARE auto-generated by @theme and need no explicit utility.) */\n@utility bg-success-soft {\n  background-color: var(--color-success-soft);\n}\n@utility bg-warning-soft {\n  background-color: var(--color-warning-soft);\n}\n@utility bg-info-soft {\n  background-color: var(--color-info-soft);\n}\n@utility bg-destructive-soft {\n  background-color: var(--color-destructive-soft);\n}\n@utility bg-hover {\n  background-color: var(--color-hover);\n}\n@utility bg-selected {\n  background-color: var(--color-selected);\n}\n";
+const themeCss = "/* @kitn.ai/ui design system — import after `@import \"tailwindcss\"`.\n   Defines ONLY namespaced (--color-*) tokens, component keyframes, animation\n   utilities, and the .chat-markdown styles. Contains NO global base/reset rules,\n   so importing it restyles nothing on its own — a host opts in via the kit's\n   components + classes. Rebrand by overriding the --color-* values (optionally\n   scoped to a subtree).\n   NOTE: This file is Tailwind-v4 source (requires tailwindcss as a peer). For\n   bundler-based apps that don't use Tailwind, import @kitn.ai/ui/theme.tokens.css\n   instead — it is plain compiled CSS with no toolchain requirements. */\n\n@custom-variant dark (&:is(.dark *));\n\n@theme {\n  --color-background: var(--kai-color-background, hsl(0 0% 100%));\n  --color-foreground: var(--kai-color-foreground, hsl(240 10% 3.9%));\n  --color-card: var(--kai-color-card, hsl(0 0% 100%));\n  --color-card-foreground: var(--kai-color-card-foreground, hsl(240 10% 3.9%));\n  --color-popover: var(--kai-color-popover, hsl(0 0% 100%));\n  --color-popover-foreground: var(--kai-color-popover-foreground, hsl(240 10% 3.9%));\n  --color-primary: var(--kai-color-primary, hsl(240 5.9% 10%));\n  --color-primary-foreground: var(--kai-color-primary-foreground, hsl(0 0% 98%));\n  --color-secondary: var(--kai-color-secondary, hsl(240 4.8% 95.9%));\n  --color-secondary-foreground: var(--kai-color-secondary-foreground, hsl(240 5.9% 10%));\n  --color-muted: var(--kai-color-muted, hsl(240 4.8% 95.9%));\n  --color-muted-foreground: var(--kai-color-muted-foreground, hsl(240 3.8% 43%));\n  /* Subtle SURFACE — an opaque \"muted panel\" for things that sit OVER content\n     (the prompt input, message bubbles, artifact/card headers, chips). CALCULATED\n     from existing tokens — `--color-muted` blended 40% onto `--color-background`\n     — so it tracks the theme (incl. dark) automatically and needs no hand-picked\n     value. SOLID (no alpha), so nothing behind it bleeds through. This replaces\n     ad-hoc `bg-muted/40` surfaces. Retint via the --kai-color-surface knob (or a\n     bare value); --color-surface-strong is the stronger step (hover/raised) and\n     --color-surface-sunken is recessed BELOW the base surface (wells, or a banner\n     that sits behind a card). Sunken is theme-specific: \"darker than the card\"\n     means a LOWER muted% in dark but a HIGHER one in light, so the two scopes\n     can't share a number — see the .dark block. */\n  --color-surface: var(--kai-color-surface, color-mix(in srgb, var(--color-muted) 40%, var(--color-background)));\n  --color-surface-strong: var(--kai-color-surface-strong, color-mix(in srgb, var(--color-muted) 60%, var(--color-background)));\n  --color-surface-sunken: var(--kai-color-surface-sunken, color-mix(in srgb, var(--color-muted) 85%, var(--color-background)));\n  --color-accent: var(--kai-color-accent, hsl(240 4.8% 95.9%));\n  --color-accent-foreground: var(--kai-color-accent-foreground, hsl(240 5.9% 10%));\n  --color-destructive: var(--kai-color-destructive, hsl(0 72% 45%));\n  --color-destructive-foreground: var(--kai-color-destructive-foreground, hsl(0 0% 98%));\n  /* Semantic status colors - solid fills with a legible foreground, matched to\n     the kit's tool-green / -amber / -blue hues so they read on-brand. Use\n     bg-success / bg-warning / bg-info with the matching -foreground for badges,\n     banners, and buttons; or text-success / -warning / -info on a soft tint\n     (below). destructive (above) is the danger/error member of the same family.\n     Light uses darker hues so the color carries a light foreground AND stays\n     legible as text on a pale tint; dark (see .dark) flips to brighter hues over\n     a near-black foreground. Override via --kai-color-success / -warning / -info\n     (+ -foreground). */\n  --color-success: var(--kai-color-success, hsl(142 71% 30%));\n  --color-success-foreground: var(--kai-color-success-foreground, hsl(0 0% 98%));\n  --color-warning: var(--kai-color-warning, hsl(38 92% 30%));\n  --color-warning-foreground: var(--kai-color-warning-foreground, hsl(0 0% 98%));\n  --color-info: var(--kai-color-info, hsl(217 91% 42%));\n  --color-info-foreground: var(--kai-color-info-foreground, hsl(0 0% 98%));\n  /* Soft tinted status surfaces - OPAQUE, theme-tracking fills derived as ~14% of\n     the status hue blended onto the background. Use these for subtle callouts /\n     banners instead of an eyeballed bg-success/10; pair with text-success /\n     -warning / -info / -destructive. Derived, so declared in BOTH light and dark\n     (a color-mix resolves where it's declared - see the surface tokens above). A\n     bare bg- utility for a color-mix token is added at the bottom (see bg-surface). */\n  --color-success-soft: var(--kai-color-success-soft, color-mix(in oklab, var(--color-success) 14%, var(--color-background)));\n  --color-warning-soft: var(--kai-color-warning-soft, color-mix(in oklab, var(--color-warning) 14%, var(--color-background)));\n  --color-info-soft: var(--kai-color-info-soft, color-mix(in oklab, var(--color-info) 14%, var(--color-background)));\n  --color-destructive-soft: var(--kai-color-destructive-soft, color-mix(in oklab, var(--color-destructive) 14%, var(--color-background)));\n  /* Interaction-state backgrounds - opaque, theme-tracking fills for row/control\n     states so consumers stop eyeballing /10 opacities. --color-hover is a subtle\n     neutral (a little --color-muted on the background); --color-selected is a\n     faint --color-primary tint so a selected row tracks the brand. Use bg-hover /\n     bg-selected. Derived, so declared in BOTH light and dark; bare bg- utilities\n     added at the bottom. */\n  --color-hover: var(--kai-color-hover, color-mix(in oklab, var(--color-muted) 60%, var(--color-background)));\n  --color-selected: var(--kai-color-selected, color-mix(in oklab, var(--color-primary) 8%, var(--color-background)));\n  /* MARKED text — the fill behind a keyword the app has flagged (the composer's\n     `highlights` rules, decorated through the CSS Custom Highlight API). This is\n     `<mark>`, not a selection and not a status: a warm yellow, the convention\n     every browser already ships for <mark> and every reader already reads as\n     \"someone marked this\". Deliberately NOT derived from --color-primary — that\n     token is a NEUTRAL near-black in light and near-white in dark, so any tint of\n     it is grey, which is why the highlight used to be invisible. Also not blue\n     (the browser's own ::selection is blue — a highlight must not read as a\n     selection), not red (error) and not the skill/agent pill hues (blue/violet).\n     OPAQUE, so it composites predictably over whichever field it lands on.\n     Override via --kai-color-highlight. Light: near-black text over it is 15.6:1;\n     dark: near-white text over it is 6.7:1 — both well clear of WCAG AA. */\n  --color-highlight: var(--kai-color-highlight, hsl(45 96% 78%));\n  /* SELECTED text — the kit's own ::selection fill, applied inside every kai-*\n     shadow root (see src/elements/styles.css for the scoping rationale). The kit\n     owns this because leaving it to the UA meant the browser's blue outranked the\n     kit's own deliberate emphasis: a marked keyword was LESS prominent than an\n     incidental drag-select. Stays in the cool/blue family the UA trained everyone\n     to read as \"selected\", so it can never be confused with the warm --color-highlight\n     mark above; OPAQUE, so a selection over a mark composites cleanly (selection\n     paints on top of a custom highlight) instead of muddying into a third colour.\n     The FOREGROUND is set too, and that is not cosmetic: without it the selected\n     glyph keeps its own colour, and the kit's coloured text — muted text (3.8:1),\n     the skill/agent pill hues (3.6:1 / 4.0:1), inline code (4.7:1) — lands at or\n     under WCAG AA on this fill. Forcing the foreground token makes the guarantee\n     hold for every glyph regardless of what colour it had. Light 13.99:1,\n     dark 8.87:1. Override via --kai-color-selection(-foreground). */\n  --color-selection: var(--kai-color-selection, hsl(213 94% 87%));\n  --color-selection-foreground: var(--kai-color-selection-foreground, hsl(240 10% 3.9%));\n  --color-border: var(--kai-color-border, hsl(240 5.9% 90%));\n  /* CONTROL boundary — the visible edge of an interactive form control (text\n     input, textarea, select, the radio/checkbox ring). WCAG 2.1 SC 1.4.11\n     Non-text Contrast requires >=3:1 against the adjacent surface for exactly\n     this: a control whose boundary you cannot see is not perceivable. That is\n     why this is NOT --color-border: a divider or a card outline is decorative\n     and may sit below 3:1, a control's edge may not. Do NOT use border-input\n     for list wrappers or panel outlines — use border-border there.\n     Contrast is the requirement; a thicker border does not satisfy 1.4.11. */\n  --color-input: var(--kai-color-input, hsl(240 5% 53%));\n  /* Focus ring — a deliberate blue (not a neutral) so keyboard focus is always\n     obvious and on-brand in both modes. Light uses a strong blue; dark uses a\n     brighter one for contrast on dark surfaces. Both clear WCAG 2.1 non-text\n     contrast (≥3:1) against the kit's backgrounds. Override via --kai-color-ring. */\n  --color-ring: var(--kai-color-ring, hsl(217 91% 53%));\n  /* Custom scrollbars — thin, rounded, subtle; thumb strengthens on hover. A\n     consistent cross-platform look (the kit styles its OWN scroll regions inside\n     the shadow root; the track stays transparent so nothing is forced where no\n     scrollbar is needed). Override via --kai-color-scrollbar-thumb(-hover). */\n  --color-scrollbar-thumb: var(--kai-color-scrollbar-thumb, hsl(240 5% 80%));\n  --color-scrollbar-thumb-hover: var(--kai-color-scrollbar-thumb-hover, hsl(240 4% 64%));\n  --color-sidebar: var(--kai-color-sidebar, hsl(0 0% 100%));\n\n  /* Inline `code` accent. Blue text on a translucent blue chip. */\n  --color-code-foreground: var(--kai-color-code-foreground, hsl(224.3 76.3% 48%));\n\n  /* Tool/status chip hues. Each chip is hue text over a 15% translucent fill of\n     the SAME hue (set in tool.tsx). The bare hue is too light to reach WCAG AA\n     (4.5:1) on the faint fill in LIGHT mode, so the light values are darkened;\n     dark mode keeps brighter hues for AA on the dark fill. Override via\n     --kai-color-tool-* to retheme. */\n  --color-tool-blue: var(--kai-color-tool-blue, hsl(217 91% 38%));\n  --color-tool-amber: var(--kai-color-tool-amber, hsl(38 92% 28%));\n  --color-tool-green: var(--kai-color-tool-green, hsl(142 71% 26%));\n  --color-tool-red: var(--kai-color-tool-red, hsl(0 72% 42%));\n\n  --radius: var(--kai-radius, 0.6rem);\n  --radius-sm: calc(var(--radius) - 4px);\n  --radius-md: calc(var(--radius) - 2px);\n  --radius-lg: var(--radius);\n  --radius-xl: calc(var(--radius) + 4px);\n\n  /* Typography scale — ONE scale for the whole kit. Each semantic name\n     (text-micro / text-caption / text-meta / text-compact / text-body /\n     text-title / text-lg)\n     resolves through a namespaced --kai-text-* token, so overriding that token\n     on :root restyles the kit globally — it pierces the Shadow DOM via the\n     var() fallback, exactly like the --kai-color-* tokens. The bare --text-*\n     names stay internal so a host's own --text-* can't collide.\n\n     Tailwind's OWN scale is re-pointed at the same tokens: in Tailwind v4 the\n     `text-xs` / `text-sm` / `text-base` / `text-lg` utilities are generated FROM\n     --text-xs/sm/base/lg in this very @theme block, so aliasing them makes\n     text-xs ≡ text-meta, text-sm ≡ text-body, text-base ≡ text-title and\n     text-lg ≡ text-lg. That matters because the vast majority of the kit's call\n     sites spell the Tailwind name; without the alias the --kai-text-* knobs\n     reached ~12% of them and the \"globally\" promise in the theming guide was\n     false. Defaults are byte-identical to stock Tailwind, so nothing moves\n     until a consumer actually sets a --kai-text-* token — including in a\n     consumer's own Tailwind build that imports this file, which is the point:\n     one scale everywhere, kit and app moving together.\n\n     Line-heights are UNITLESS RATIOS (Tailwind's own), never fixed rem. A fixed\n     leading does not scale: --kai-text-body: 1.25rem under the old 1.45rem\n     leading gave 20px text on 23.2px leading — near solid-set — which made the\n     themable token unsafe to actually theme.\n     (Message/markdown reading size also scales with the `proseSize` prop; these\n     tokens cover the fixed chrome & controls.) */\n  --text-micro: var(--kai-text-micro, 0.625rem);      --text-micro--line-height: calc(0.875 / 0.625);   /* 10px — badges, pills, uppercase eyebrows */\n  --text-caption: var(--kai-text-caption, 0.6875rem); --text-caption--line-height: calc(1 / 0.6875);    /* 11px — micro labels, sub-counts, xs code */\n  --text-meta: var(--kai-text-meta, 0.75rem);         --text-meta--line-height: calc(1 / 0.75);         /* 12px — controls, toggles, switchers, captions */\n  --text-xs: var(--kai-text-meta, 0.75rem);           --text-xs--line-height: calc(1 / 0.75);           /* ≡ text-meta */\n  --text-compact: var(--kai-text-compact, 0.8125rem); --text-compact--line-height: calc(1.21875 / 0.8125); /* 13px — dense chrome & code: a notch below body */\n  --text-body: var(--kai-text-body, 0.875rem);        --text-body--line-height: calc(1.25 / 0.875);     /* 14px — primary reading text */\n  --text-sm: var(--kai-text-body, 0.875rem);          --text-sm--line-height: calc(1.25 / 0.875);       /* ≡ text-body */\n  --text-title: var(--kai-text-title, 1rem);          --text-title--line-height: calc(1.5 / 1);         /* 16px — emphasis / headers */\n  --text-base: var(--kai-text-title, 1rem);           --text-base--line-height: calc(1.5 / 1);          /* ≡ text-title */\n  --text-lg: var(--kai-text-lg, 1.125rem);            --text-lg--line-height: calc(1.75 / 1.125);       /* 18px — section headings, lg prose */\n\n  @keyframes typing { 0%,100% { transform: translateY(0); opacity: .5 } 50% { transform: translateY(-2px); opacity: 1 } }\n  @keyframes loading-dots { 0%,100% { opacity: 0 } 50% { opacity: 1 } }\n  @keyframes wave { 0%,100% { transform: scaleY(1) } 50% { transform: scaleY(.6) } }\n  @keyframes blink { 0%,100% { opacity: 1 } 50% { opacity: 0 } }\n  @keyframes text-blink { 0%,100% { color: var(--color-primary) } 50% { color: var(--color-muted-foreground) } }\n  @keyframes bounce-dots { 0%,100% { transform: scale(.8); opacity: .5 } 50% { transform: scale(1.2); opacity: 1 } }\n  @keyframes thin-pulse { 0%,100% { transform: scale(.95); opacity: .8 } 50% { transform: scale(1.05); opacity: .4 } }\n  @keyframes pulse-dot { 0%,100% { transform: scale(1); opacity: .8 } 50% { transform: scale(1.5); opacity: 1 } }\n  @keyframes shimmer-text { 0% { background-position: 150% center } 100% { background-position: -150% center } }\n  @keyframes wave-bars { 0%,100% { transform: scaleY(1); opacity: .5 } 50% { transform: scaleY(.6); opacity: 1 } }\n  @keyframes shimmer { 0% { background-position: 200% 50% } 100% { background-position: -200% 50% } }\n  @keyframes spinner-fade { 0% { opacity: 0 } 100% { opacity: 1 } }\n  @keyframes collapsible-down { from { height: 0; opacity: 0 } to { height: var(--kb-collapsible-content-height); opacity: 1 } }\n  @keyframes collapsible-up { from { height: var(--kb-collapsible-content-height); opacity: 1 } to { height: 0; opacity: 0 } }\n}\n\n.dark {\n  --color-background: var(--kai-color-background, hsl(50 2% 9%));\n  --color-foreground: var(--kai-color-foreground, hsl(0 0% 98%));\n  --color-card: var(--kai-color-card, hsl(45 4% 12%));\n  --color-card-foreground: var(--kai-color-card-foreground, hsl(0 0% 98%));\n  --color-popover: var(--kai-color-popover, hsl(45 4% 12%));\n  --color-popover-foreground: var(--kai-color-popover-foreground, hsl(0 0% 98%));\n  --color-primary: var(--kai-color-primary, hsl(0 0% 98%));\n  --color-primary-foreground: var(--kai-color-primary-foreground, hsl(45 4% 11%));\n  --color-secondary: var(--kai-color-secondary, hsl(45 4% 17%));\n  --color-secondary-foreground: var(--kai-color-secondary-foreground, hsl(0 0% 98%));\n  --color-muted: var(--kai-color-muted, hsl(45 4% 17%));\n  --color-muted-foreground: var(--kai-color-muted-foreground, hsl(45 4% 64%));\n  /* Re-declared in the dark scope so the color-mix recomputes with the DARK\n     muted/background (a derived token is computed where it's declared, not where\n     it's used — see the light --color-surface for the full note). */\n  --color-surface: var(--kai-color-surface, color-mix(in srgb, var(--color-muted) 40%, var(--color-background)));\n  --color-surface-strong: var(--kai-color-surface-strong, color-mix(in srgb, var(--color-muted) 60%, var(--color-background)));\n  /* Sunken: in dark a LOWER muted% is darker (blends toward the dark background). */\n  --color-surface-sunken: var(--kai-color-surface-sunken, color-mix(in srgb, var(--color-muted) 18%, var(--color-background)));\n  --color-accent: var(--kai-color-accent, hsl(45 4% 17%));\n  --color-accent-foreground: var(--kai-color-accent-foreground, hsl(0 0% 98%));\n  --color-destructive: var(--kai-color-destructive, hsl(0 62.8% 30.6%));\n  --color-destructive-foreground: var(--kai-color-destructive-foreground, hsl(0 0% 98%));\n  /* Semantic status colors - dark mode flips to the brighter tool-* dark hues\n     (matching the chip values) carried over a near-black foreground, so the color\n     both reads as text on a dark soft tint AND backs a legible foreground. See\n     the light @theme note. */\n  --color-success: var(--kai-color-success, hsl(142 71% 45%));\n  --color-success-foreground: var(--kai-color-success-foreground, hsl(45 4% 11%));\n  --color-warning: var(--kai-color-warning, hsl(38 92% 50%));\n  --color-warning-foreground: var(--kai-color-warning-foreground, hsl(45 4% 11%));\n  --color-info: var(--kai-color-info, hsl(217 91% 70%));\n  --color-info-foreground: var(--kai-color-info-foreground, hsl(45 4% 11%));\n  /* Soft status surfaces + interaction states - re-declared so each color-mix\n     recomputes with the DARK hues/background (a derived token resolves where it's\n     declared; see the light block for the full note). */\n  --color-success-soft: var(--kai-color-success-soft, color-mix(in oklab, var(--color-success) 14%, var(--color-background)));\n  --color-warning-soft: var(--kai-color-warning-soft, color-mix(in oklab, var(--color-warning) 14%, var(--color-background)));\n  --color-info-soft: var(--kai-color-info-soft, color-mix(in oklab, var(--color-info) 14%, var(--color-background)));\n  --color-destructive-soft: var(--kai-color-destructive-soft, color-mix(in oklab, var(--color-destructive) 14%, var(--color-background)));\n  --color-hover: var(--kai-color-hover, color-mix(in oklab, var(--color-muted) 60%, var(--color-background)));\n  --color-selected: var(--kai-color-selected, color-mix(in oklab, var(--color-primary) 8%, var(--color-background)));\n  /* Marked text — dark. A deep warm amber rather than the light yellow: a pale\n     highlighter on a near-black field would blow out and force the text to flip\n     colour. See the light block for the full note. */\n  --color-highlight: var(--kai-color-highlight, hsl(40 75% 26%));\n  /* Selected text — dark. A deep blue rather than the light one, for the same\n     reason the mark darkens. See the light block for the full note. */\n  --color-selection: var(--kai-color-selection, hsl(217 60% 32%));\n  --color-selection-foreground: var(--kai-color-selection-foreground, hsl(0 0% 98%));\n  --color-border: var(--kai-color-border, hsl(45 4% 17%));\n  /* Control boundary — see the light block. Lifted to clear 3:1 (SC 1.4.11)\n     against the dark background and card surfaces. */\n  --color-input: var(--kai-color-input, hsl(45 4% 48%));\n  --color-ring: var(--kai-color-ring, hsl(217 91% 68%));\n  --color-scrollbar-thumb: var(--kai-color-scrollbar-thumb, hsl(45 3% 30%));\n  --color-scrollbar-thumb-hover: var(--kai-color-scrollbar-thumb-hover, hsl(45 3% 42%));\n  --color-sidebar: var(--kai-color-sidebar, hsl(50 2% 7%));\n  --color-code-foreground: var(--kai-color-code-foreground, hsl(213 94% 78%));\n\n  /* Tool/status chip hues — dark mode. Brighter hues reach AA on the dark fill. */\n  --color-tool-blue: var(--kai-color-tool-blue, hsl(217 91% 70%));\n  --color-tool-amber: var(--kai-color-tool-amber, hsl(38 92% 50%));\n  --color-tool-green: var(--kai-color-tool-green, hsl(142 71% 45%));\n  --color-tool-red: var(--kai-color-tool-red, hsl(0 84% 70%));\n}\n\n/* Self-contained markdown styling — replaces the typography plugin's `prose`.\n   Keyed on --color-* tokens so it themes with the rest of the kit. */\n.chat-markdown { color: var(--color-foreground); line-height: 1.6; }\n.chat-markdown > div:first-child > :first-child { margin-top: 0; }\n.chat-markdown > div:last-child > :last-child { margin-bottom: 0; }\n.chat-markdown p { margin: 0 0 0.75em; }\n.chat-markdown p:last-child { margin-bottom: 0; }\n.chat-markdown h1, .chat-markdown h2, .chat-markdown h3, .chat-markdown h4 {\n  margin: 1.2em 0 0.5em; font-weight: 600; line-height: 1.3; color: var(--color-foreground);\n}\n.chat-markdown h1 { font-size: 1.4em; } .chat-markdown h2 { font-size: 1.25em; }\n.chat-markdown h3 { font-size: 1.1em; } .chat-markdown h4 { font-size: 1em; }\n.chat-markdown ul, .chat-markdown ol { margin: 0 0 0.75em; padding-left: 1.4em; }\n.chat-markdown li { margin: 0.2em 0; }\n.chat-markdown ul { list-style: disc; } .chat-markdown ol { list-style: decimal; }\n.chat-markdown a { color: var(--color-primary); text-decoration: underline; text-underline-offset: 2px; }\n.chat-markdown strong { font-weight: 600; color: var(--color-foreground); }\n.chat-markdown em { font-style: italic; }\n.chat-markdown blockquote {\n  margin: 0 0 0.75em; padding-left: 0.9em; border-left: 2px solid var(--color-border);\n  color: var(--color-muted-foreground);\n}\n.chat-markdown hr { margin: 1em 0; border: 0; border-top: 1px solid var(--color-border); }\n.chat-markdown code:not(pre code) {\n  background: color-mix(in oklab, var(--color-code-foreground) 15%, transparent);\n  color: var(--color-code-foreground);\n  border-radius: 4px; padding: 0.1em 0.35em; font-size: 0.875em;\n  font-family: var(--kai-font-code, ui-monospace, \"SF Mono\", Menlo, monospace);\n}\n.chat-markdown table { width: 100%; border-collapse: collapse; margin: 0 0 0.75em; font-size: 0.9em; }\n.chat-markdown th, .chat-markdown td { border: 1px solid var(--color-border); padding: 0.4em 0.6em; text-align: left; }\n.chat-markdown th { font-weight: 600; background: color-mix(in oklab, var(--color-muted-foreground) 8%, transparent); }\n\n/* Themeable elevation. The kit is mostly flat (borders), but a few surfaces lift\n   off the page — popovers, dropdowns, hover cards, cards. The shadow COLOR is a\n   token (--kai-shadow-color, default near-black); set it transparent for a fully\n   flat look, or tint it to match a theme. Defined here (not as a Tailwind shadow\n   utility) so the color stays overridable and works in both the web-component and\n   SolidJS layers. */\n.kai-elevation {\n  box-shadow:\n    0 4px 12px -2px color-mix(in oklab, var(--kai-shadow-color, oklch(0 0 0)) 14%, transparent),\n    0 2px 6px -2px color-mix(in oklab, var(--kai-shadow-color, oklch(0 0 0)) 10%, transparent);\n}\n.kai-elevation-sm {\n  box-shadow: 0 1px 2px 0 color-mix(in oklab, var(--kai-shadow-color, oklch(0 0 0)) 8%, transparent);\n}\n\n/* Cross-platform thin scrollbar utility (Firefox + WebKit). Used by ScrollArea\n   and any scroll region in the SolidJS-component build (web components also get\n   this globally inside their shadow root — see src/elements/styles.css). */\n.scrollbar-thin {\n  scrollbar-width: thin;\n  scrollbar-color: var(--color-scrollbar-thumb) transparent;\n}\n.scrollbar-thin::-webkit-scrollbar { width: 8px; height: 8px; }\n.scrollbar-thin::-webkit-scrollbar-track { background: transparent; }\n.scrollbar-thin::-webkit-scrollbar-thumb {\n  background-color: var(--color-scrollbar-thumb);\n  border-radius: 9999px;\n  border: 2px solid transparent;\n  background-clip: padding-box;\n}\n.scrollbar-thin::-webkit-scrollbar-thumb:hover { background-color: var(--color-scrollbar-thumb-hover); }\n.scrollbar-thin::-webkit-scrollbar-corner { background: transparent; }\n\n/* Surface utilities — `bg-surface` / `bg-surface-strong` paint the opaque,\n   theme-derived surface tokens (see --color-surface above). Defined explicitly\n   because a color-mix-valued @theme token does NOT emit a bare `bg-` utility on\n   its own (only opacity variants). Use these for panels that sit OVER content\n   instead of `bg-muted/NN`. */\n@utility bg-surface {\n  background-color: var(--color-surface);\n}\n@utility bg-surface-strong {\n  background-color: var(--color-surface-strong);\n}\n@utility bg-surface-sunken {\n  background-color: var(--color-surface-sunken);\n}\n\n/* Soft-status + interaction-state utilities. Same reason as bg-surface above: a\n   color-mix-valued @theme token does NOT emit a bare `bg-` utility on its own, so\n   bg-success-soft / bg-warning-soft / bg-info-soft / bg-destructive-soft and\n   bg-hover / bg-selected are declared here. (The SOLID tokens - success / warning\n   / info + their -foreground - are plain hsl values, so bg-success / text-success\n   etc. ARE auto-generated by @theme and need no explicit utility.) */\n@utility bg-success-soft {\n  background-color: var(--color-success-soft);\n}\n@utility bg-warning-soft {\n  background-color: var(--color-warning-soft);\n}\n@utility bg-info-soft {\n  background-color: var(--color-info-soft);\n}\n@utility bg-destructive-soft {\n  background-color: var(--color-destructive-soft);\n}\n@utility bg-hover {\n  background-color: var(--color-hover);\n}\n@utility bg-selected {\n  background-color: var(--color-selected);\n}\n";
 function declaredKaiTokens(css) {
   const names = /* @__PURE__ */ new Set();
   for (const m of css.matchAll(/var\(\s*(--kai-[a-zA-Z0-9-]+)\s*[,)]/g)) names.add(m[1]);
@@ -8620,11 +9412,54 @@ const RULES = [
     title: "`kai-compare` — two candidates, `data` as a JS property, terminal pick",
     cause: "`<kai-compare>` shows EXACTLY two assistant candidates for one prompt and lets the user pick the better one. The `data` value is an array/object, so it must be set as a JS PROPERTY (never an HTML attribute). Both candidates can stream — but, like `kai-chat`, that needs a NEW `data` reference per chunk (mutating in place will not re-render). The pick is a COMMIT (not a Submit): it fires once and the card collapses.",
     fix: "Set `data` in JS with two candidates, stream by reassigning a fresh `data` object per chunk, and listen for `kai-compare-select` directly on the element.\n\n```ts\nimport { toast } from '@kitn.ai/ui/elements';\nimport type { ResponseCompareData, CompareSelection } from '@kitn.ai/ui';\n\nconst el = document.querySelector('kai-compare')!;\n// data is a JS PROPERTY — exactly two candidates, each with a unique id.\nel.data = {\n  prompt: 'Summarise the report',\n  candidates: [\n    { id: 'a', content: '', streaming: true },\n    { id: 'b', content: '', streaming: true },\n  ],\n} satisfies ResponseCompareData;\n\n// Stream BOTH columns: replace data with a NEW object per chunk.\nel.data = { ...el.data, candidates: [{ ...a, content: aText }, { ...b, content: bText }] };\n// Clear `streaming` on a candidate when it settles — the pick stays disabled\n// until BOTH have settled, then `kai-ready` fires.\n\n// Picking is terminal: emits { chosenId, rejectedIds, at } and collapses.\nel.addEventListener('kai-compare-select', (e) => {\n  const { chosenId, rejectedIds } = (e as CustomEvent<CompareSelection>).detail;\n  recordPreference({ prompt, chosen: chosenId, rejected: rejectedIds });\n});\n```\n\nA malformed definition (not two candidates, missing/duplicate ids) fires `kai-error` instead. The event is non-bubbling — listen on the element, not on `document`."
+  },
+  {
+    // Rule 13 — kai-composer is the bare editor; attachments + send live on kai-prompt-input
+    // Source: src/elements/composer.tsx (element doc), src/elements/prompt-input.tsx,
+    // apps/docs components/composer.mdx (the taxonomy sentence). Rung-6 F-43.
+    id: "composer-attachments",
+    test: (t) => {
+      if (!/kai-composer|composer\b/i.test(t)) return false;
+      return /attach|paperclip|file.?upload|upload|send.?button|toolbar|staging|staged/i.test(t);
+    },
+    title: "`<kai-composer>` is the bare editor — attachments and the send button live on `<kai-prompt-input>`",
+    cause: "`<kai-composer>` is deliberately the bare editing surface: rich text, entity pills, triggers, Enter-to-submit — and nothing else. No send button, no toolbar, no attachment surface; its `kai-submit` detail is `{ doc, text, entities }` with no `attachments` field. Nothing is missing — the batteries-included wrapper is a different element.",
+    fix: "Reach for `<kai-prompt-input>`, which is built on the composer and adds the send button, the toolbar, and attachments: a paperclip that stages files as chips, a `kai-attachments-change` event, and `attachments` on its `kai-submit` detail.\n\n```html\n<kai-prompt-input placeholder=\"Send a message...\"></kai-prompt-input>\n```\n\n```js\ndocument.querySelector('kai-prompt-input').addEventListener('kai-submit', (e) => {\n  const { value, attachments } = e.detail; // attachments staged via the paperclip\n});\n```\n\nKeep `<kai-composer>` only when you are composing the input row yourself — then the picker, staging tray and send control are yours to build, and every staged file’s `url` must be a `data:` URI, never `URL.createObjectURL` (see the attachment-blob-url rule)."
+  },
+  {
+    // Rule 14 — blob: attachment URLs: the wire refuses them; use a data: URI
+    // Source: src/components/attachment-types.ts (AttachmentData.url doc),
+    // src/elements/default-input.tsx (readAsDataUrl), src/wire/files.ts (the refusal),
+    // apps/docs patterns/attachments-flow.mdx. Rung-6 F-44; the defect PR #186 shipped.
+    id: "attachment-blob-url",
+    test: (t) => {
+      if (/createObjectURL/.test(t) && /attachment|type:\s*'file'|filename|kai|@kitn/i.test(t)) return true;
+      if (/blob:/.test(t) && /attachment|toOpenAIMessages|toAnthropicMessages|wire|kai|@kitn/i.test(t)) return true;
+      return false;
+    },
+    title: "Never `URL.createObjectURL` in `AttachmentData.url` — read the file as a `data:` URI",
+    cause: "An object URL resolves only inside the browser tab that minted it, so `url: URL.createObjectURL(file)` renders a flawless local preview and is meaningless to any provider. `toOpenAIMessages` / `toAnthropicMessages` REFUSE a `blob:` URL rather than send an address the model cannot fetch — before they refused it, an attachment-only turn reached the model as nothing at all. A mock-only app hides the defect (`createMockResponder` never encodes the thread back); it surfaces the moment you point at a real provider.",
+    fix: "Read every staged file as a `data:` URI and put THAT in `url` — it previews identically and is the one form both provider wires actually take:\n\n```js\nconst readAsDataUrl = (file) =>\n  new Promise((resolve, reject) => {\n    const reader = new FileReader();\n    reader.onload = () => resolve(String(reader.result));\n    reader.onerror = () => reject(reader.error);\n    reader.readAsDataURL(file);\n  });\n\nconst url = await readAsDataUrl(file); // data: URI — never URL.createObjectURL\nreturn { id, type: 'file', filename: file.name, mediaType: file.type, url };\n```\n\n`<kai-prompt-input>`’s built-in paperclip already does this for you; the conversion is only yours when you stage files yourself. With `data:` URIs there is also nothing to revoke — no object-URL lifecycle to manage."
+  },
+  {
+    // Rule 15 — mock tool calls: MockTurn.toolCalls scripts them; the HOST resolves them
+    // Source: src/state/mock.ts (MockTurn/MockToolCall), src/wire/chunk.ts (ModelTurn.toolCalls),
+    // src/state/stream.ts (upsertTool). Rung-6 F-46/F-47/F-52.
+    id: "mock-tool-calls",
+    test: (t) => {
+      const toolContext = /tool.?call|toolCalls|input-available/i.test(t);
+      if (/createMockResponder|mock responder|MockTurn/i.test(t) && toolContext) return true;
+      if (toolContext && /\bmock\b/i.test(t) && /kai|@kitn|stream|responder/i.test(t)) return true;
+      return false;
+    },
+    title: "Scripting mock tool calls — `MockTurn.toolCalls`; the HOST resolves the announced call",
+    cause: "Two separate facts. (1) The default mock replies are text-only, so out of the box `createMockResponder()` never announces a tool call — scripting one takes a `MockTurn` reply. (2) A tool call — mock or real provider — is only ever ANNOUNCED by the stream: the part parks at `state: 'input-available'` and stays there. The kit parses and renders the call; EXECUTING it and answering is the host’s job.",
+    fix: "Script the call with a `MockTurn` reply (`{ text?, toolCalls? }`); the mock frames it announce-then-arguments with `finish_reason: 'tool_calls'`, exactly as a real OpenAI-wire turn, so it flows through `readOpenAIStream` unchanged:\n\n```js\nimport { createMockResponder } from '@kitn.ai/ui/state';\n\nconst mock = createMockResponder({\n  replies: [\n    'Plain text turn.',\n    { text: 'Checking…', toolCalls: [{ name: 'get_weather', arguments: { city: 'Oslo' } }] },\n  ],\n});\n```\n\nThen resolve each announced call yourself after the read settles — walk the returned `ModelTurn.toolCalls` and patch the part to `output-available`:\n\n```js\nconst result = await readOpenAIStream(response, stream);\nfor (const call of result.toolCalls) {\n  const output = await runTool(call.name, call.input); // your side of the seam\n  stream.upsertTool(call.id, { state: 'output-available', output });\n}\n```\n\nSkip any call with `providerExecuted: true` — the provider already ran it and its result arrived in-stream."
   }
 ];
 function buildText(matched) {
   if (matched.length === 0) {
-    return "No known failure pattern matched. Suggested next steps:\n\n1. Use the `component_reference` tool to look up the real API for the element (prop names, event names, attribute vs. property distinction).\n2. Check the **Streaming recipe** in `llms-full.txt` (`node_modules/@kitn.ai/ui/llms-full.txt` or https://ui.kitn.ai/llms-full.txt) for correct streaming wiring.\n3. Paste `https://ui.kitn.ai/llms.txt` into your prompt for a compact orientation.";
+    return 'No known failure pattern matched. Suggested next steps:\n\n1. Use the `component_reference` tool to look up the real API for the element (prop names, event names, attribute vs. property distinction).\n2. If the problem is in host code rather than an element — streaming, `createAssistantStream`, `createMockResponder`, the SSE readers, the encoders — call `component_reference` with `{ name: "programmatic" }` for the full `@kitn.ai/ui/state` + `@kitn.ai/ui/wire` API, and `{ name: "composed-thread" }` for a complete hand-composed surface to compare wiring against.\n3. Check the **Streaming recipe** and the **Programmatic layer** sections in `llms-full.txt` (`node_modules/@kitn.ai/ui/llms-full.txt` or https://ui.kitn.ai/llms-full.txt) for correct streaming wiring.\n4. Paste `https://ui.kitn.ai/llms.txt` into your prompt for a compact orientation.';
   }
   const sections = matched.map((rule, i) => {
     const n = i + 1;
@@ -8654,6 +9489,377 @@ const debug = {
     };
   }
 };
+const SAFE_SCHEMES = ["http:", "https:", "mailto:"];
+function schemeOf(url) {
+  try {
+    return new URL(url, "http://_invalid_base").protocol;
+  } catch {
+    return void 0;
+  }
+}
+function isSafeUrl(url) {
+  const scheme = schemeOf(url);
+  return scheme !== void 0 && SAFE_SCHEMES.includes(scheme);
+}
+const CONSTRUCT_SCHEMA_URL = "https://ui.kitn.ai/schemas/construct/v1.json";
+const TAG_RE = /^[a-z][a-z0-9]*-[a-z0-9-]+$/;
+const ProviderSchema = z$1.discriminatedUnion("mode", [
+  z$1.object({ mode: z$1.literal("mock") }).strict(),
+  z$1.object({
+    mode: z$1.literal("endpoint"),
+    /** The CONSUMER's chat route. Kit parses, consumer fetches. */
+    url: z$1.string().min(1),
+    wire: z$1.enum(["openai", "anthropic"])
+  }).strict()
+]);
+const ConstructSchema = z$1.object({
+  $schema: z$1.string().optional(),
+  /** The emitted tag: <acme-support>. Must satisfy customElements.define. */
+  name: z$1.string().regex(TAG_RE, 'must be a valid custom-element tag: lowercase, with a hyphen (e.g. "acme-support")'),
+  // Widened progressively: fullscreen/aside/split landed in Task 12, custom in Task 13.
+  layout: z$1.enum(["widget", "fullscreen", "aside", "split", "custom"]),
+  provider: ProviderSchema,
+  /** Plain (unsigned) identity passthrough — no signing/auth infra (owner
+   *  ruling, 2026-08-26: signed JWT/HMAC identity is later additive
+   *  vocabulary, not this field). TOP-LEVEL, not nested under `provider`:
+   *  local history scoping (`capabilities.history.persistence: 'local'`)
+   *  needs userId independent of provider mode — nesting it inside the
+   *  provider union would make it silently inert for `mode: 'mock'` +
+   *  local history, a real and common combination. Threaded as the
+   *  `x-kai-user-id` header on every emitted fetch to the CONSUMER's own
+   *  backend (the endpoint provider's chat POST, history's endpoint
+   *  GET/PUT), and folded into the localStorage key for `local` history so
+   *  different users on the same browser profile don't share one thread.
+   *  Constrained to printable-ASCII (no CR/LF, no non-ISO-8859-1 code
+   *  points) beyond the usual construct-authored-text escaping: this value
+   *  reaches an HTTP HEADER VALUE, not just a JS string literal, and
+   *  `fetch()` throws at RUNTIME on a header value containing CR/LF or
+   *  outside ISO-8859-1 — a bad userId would surface as an opaque crash in
+   *  the CONSUMER's generated app, not a construct-validation error. Reject
+   *  loudly here instead, where the author gets a path + message. */
+  userId: z$1.string().min(1).regex(
+    /^[\x20-\x7E]+$/,
+    "must be printable ASCII with no line breaks (it becomes an HTTP header value)"
+  ).optional(),
+  theme: z$1.object({
+    /** Any CSS color; becomes --kai-color-primary on the host. */
+    accent: z$1.string().optional(),
+    mode: z$1.enum(["light", "dark", "system"]).default("system")
+  }).strict().optional(),
+  /** Construct-wide header chrome, valid on every layout (not layout-scoped
+   *  like `widget`, and not a capability toggle — a header is a construct-
+   *  wide fact, like `theme`). Rendered inside ChatThread's own built-in
+   *  header bar; a logo/icon projects through the kit's EXISTING
+   *  `header-start` named slot (`slots` vocabulary above), not a second
+   *  image-prop convention here. */
+  header: z$1.object({
+    /** Rendered in ChatThread's built-in header bar (left side). Construct-
+     *  authored/untrusted text, like theme.accent/provider.url — JSON.stringify'd
+     *  at its one emit site, never a raw JSX attribute string. */
+    title: z$1.string().min(1).optional()
+  }).strict().optional(),
+  /** Greeting shown while the thread is empty (no messages yet) — the
+   *  proven "welcome screen" pattern (Intercom-class): title + optional
+   *  description + optional icon above, with `capabilities.starters`'
+   *  chips and the composer still rendering below (ChatThread's `empty`
+   *  REPLACE slot only stands in for the empty MESSAGE LIST — see
+   *  chat-thread.tsx's own doc comment on `empty` — so the chips are
+   *  never lost). Construct-wide like `header`, not a capability: it's a
+   *  fact about the empty state, not a toggleable affordance.
+   *  `title`/`description` are construct-authored/untrusted text, like
+   *  `header.title`/`theme.accent`/`provider.url` — JSON.stringify'd at
+   *  their one emit site, never a raw JSX attribute string. `icon` is a
+   *  URL reaching an `<img src>` sink in emitted code, exactly like
+   *  `widget.launcherIcon` — same `isSafeUrl` policy, same superRefine
+   *  shape, below. */
+  empty: z$1.object({
+    title: z$1.string().min(1),
+    description: z$1.string().min(1).optional(),
+    icon: z$1.string().min(1).optional()
+  }).strict().optional(),
+  // Capability vocabulary, widened one field at a time by later tasks.
+  capabilities: z$1.object({
+    /** Starter prompts shown on the empty thread; clicking one sends it.
+     *  1-6 non-empty strings — construct-authored text, escaped like
+     *  `theme.accent`/`provider.url` at every emit interpolation site. */
+    starters: z$1.array(z$1.string().min(1)).min(1).max(6).optional(),
+    /** Enables the paperclip attach affordance; accept is a non-empty
+     *  list of media types/globs, e.g. ["image/*", "application/pdf"] —
+     *  WHETHER stays with the construct author (this field), HOW stays
+     *  with the kit (ChatThread's own attach/accept props, threaded
+     *  through by codegen). */
+    attachments: z$1.object({
+      /** Accept-list of media types/globs, e.g. ["image/*", "application/pdf"]. */
+      accept: z$1.array(z$1.string().min(1)).min(1)
+    }).strict().optional(),
+    /** Conversation persistence. `none` (default, nothing emitted): the
+     *  thread lives only in memory for the tab's lifetime. `local`:
+     *  persisted to this browser's localStorage, keyed by the construct's
+     *  tag — a mechanism decision (WHERE); what to retain and for how
+     *  long stays an app decision (component-scope-boundary), so no
+     *  retention count/quota lands here. `endpoint`: the CONSUMER's own
+     *  thread route (GET returns ChatMessage[], PUT stores them) —
+     *  requires `url`; `url` is rejected for any other persistence
+     *  (superRefine below, both directions loud). */
+    history: z$1.object({
+      persistence: z$1.enum(["none", "local", "endpoint"]),
+      /** endpoint persistence only: the CONSUMER's thread routes (GET returns
+       *  ChatMessage[], PUT stores them). Refined below. */
+      url: z$1.string().min(1).optional()
+    }).strict().optional(),
+    /** How the model's thinking (reasoning parts) renders. `'full'`
+     *  (the default when omitted — see codegen.ts's emitReasoningProp)
+     *  is the collapsible "Thinking" disclosure, shimmering while it
+     *  streams. `'compact'` shows only a shimmer/typing loader while
+     *  reasoning streams, with no expandable detail. `'off'` hides
+     *  reasoning entirely. This is HOW an existing medium fact (the
+     *  model's thinking) displays — the kit's call — so it maps straight
+     *  onto ChatThread's own `reasoning` prop; there is no app-layer
+     *  quota or retention decision hiding in it. Left `.optional()`
+     *  rather than `.default('full')`, matching every sibling field in
+     *  this object: a zod `.default()` here would make `reasoning`
+     *  REQUIRED on the inferred input type (z.infer is the output type),
+     *  breaking every `capabilities: {...}` object literal in this file
+     *  and its tests that doesn't mention it. */
+    reasoning: z$1.enum(["full", "compact", "off"]).optional(),
+    /** Seeds the reasoning disclosure open AND keeps it tracking the
+     *  stream (open while streaming, closes when it settles) — the
+     *  pre-Task-19f `full` behavior. Default false/absent: the panel
+     *  starts closed (just the "Thinking" shimmer chip) and only opens
+     *  on click — the current default (owner ruling, 2026-08-26).
+     *  Meaningless when `reasoning` is `'compact'` (no expandable
+     *  content exists) or `'off'` (nothing renders); rejected on both,
+     *  loudly, below. */
+    reasoningOpen: z$1.boolean().optional()
+  }).strict().optional(),
+  /** Named generative-UI card definitions the model can emit as tool calls,
+   *  rendered in the thread. Top-level (not a capability): a card is
+   *  something the construct's model can DO at any point once a card is
+   *  declared, not a thread-affordance toggle like starters/attachments/
+   *  reasoning. Reuses the kit's own card-tool projection end to end
+   *  (`cardTools`/`toOpenAITools`/`toAnthropicTools`, `@kitn.ai/ui/schemas`)
+   *  — never a second one authored here. `schema` is validated structurally
+   *  only; deep card validation (incl. `x-kai-format` mask hints) is the
+   *  kit's own card contract at render time. */
+  cards: z$1.array(
+    z$1.object({
+      /** Tool-facing card name, e.g. "refund_approval". */
+      name: z$1.string().regex(/^[a-z][a-z0-9_]*$/),
+      /** The kit's card schema JSON (incl. x-kai-format mask hints).
+       *  Validated structurally here; deep card validation is the kit's
+       *  own card contract at render time. */
+      schema: z$1.record(z$1.string(), z$1.unknown())
+    }).strict()
+  ).min(1).optional(),
+  /** Named `<slot>` projection points the emitted web component exposes —
+   *  the format's ONLY escape hatch (named slots, no code-in-JSON). Each
+   *  name must be a valid HTML slot-attribute value AND a legible
+   *  identifier: kebab-case, starting with a letter (the same shape as a
+   *  CSS custom-ident) — `slot name="Header!"` is rejected, not sanitized,
+   *  matching the format's loud-rejection discipline everywhere else.
+   *  1-8 entries, no duplicates (superRefine below — a regex alone can't
+   *  see across array entries). `layout: 'custom'` requires at least one
+   *  declared slot (superRefine below): `custom` IS the slots grain — a
+   *  `custom` layout with nothing to project into is not meaningfully
+   *  different from `fullscreen`. */
+  slots: z$1.array(z$1.string().regex(/^[a-z][a-z0-9-]*$/, "slot names must be kebab-case, starting with a letter")).min(1).max(8).optional(),
+  /** Layout-scoped FAB chrome, `layout: 'widget'` only (superRefine below).
+   *  Purely additive sibling to `layout` (widen-never-restructure) — mirrors
+   *  Dock's own props verbatim, threaded through by codegen's emitLayoutOpen. */
+  widget: z$1.object({
+    /** Which corner. Mirrors Dock's own DockPosition enum verbatim — not a
+     *  new left/right binary. Omitted keeps Dock's own default (bottom-end). */
+    position: z$1.enum(["bottom-end", "bottom-start", "top-end", "top-start"]).optional(),
+    /** An image URL for the closed-state launcher glyph, replacing Dock's
+     *  built-in chat-bubble icon. Construct-authored/untrusted text, like
+     *  theme.accent and provider.url — escaped the same way at its one emit site. */
+    launcherIcon: z$1.string().min(1).optional(),
+    /** Seed Dock's open state at mount. Uncontrolled — never steals focus (Dock's
+     *  own focus contract, dock.tsx). Omitted keeps Dock's own default (closed). */
+    defaultOpen: z$1.boolean().optional()
+  }).strict().optional()
+}).strict().superRefine((construct, ctx) => {
+  if (construct.slots) {
+    const seen = /* @__PURE__ */ new Set();
+    construct.slots.forEach((name, i) => {
+      if (seen.has(name)) {
+        ctx.addIssue({
+          code: z$1.ZodIssueCode.custom,
+          path: ["slots", i],
+          message: `duplicate slot name "${name}"`
+        });
+      }
+      seen.add(name);
+    });
+  }
+  if (construct.layout === "custom" && (!construct.slots || construct.slots.length === 0)) {
+    ctx.addIssue({
+      code: z$1.ZodIssueCode.custom,
+      path: ["slots"],
+      message: '"custom" layout requires at least one declared slot — custom IS the slots grain'
+    });
+  }
+  if (construct.layout === "split" && construct.slots) {
+    const i = construct.slots.indexOf("pane");
+    if (i !== -1) {
+      ctx.addIssue({
+        code: z$1.ZodIssueCode.custom,
+        path: ["slots", i],
+        message: `"pane" collides with the "split" layout's own fixed <slot name="pane"> — choose a different slot name`
+      });
+    }
+  }
+  if (construct.widget && construct.layout !== "widget") {
+    ctx.addIssue({
+      code: z$1.ZodIssueCode.custom,
+      path: ["widget"],
+      message: '"widget" is only valid on layout: "widget"'
+    });
+  }
+  if (construct.widget?.launcherIcon && !isSafeUrl(construct.widget.launcherIcon)) {
+    ctx.addIssue({
+      code: z$1.ZodIssueCode.custom,
+      path: ["widget", "launcherIcon"],
+      message: "launcherIcon must be an http(s)/mailto or relative URL — no javascript:/data: schemes"
+    });
+  }
+  if (construct.empty?.icon && !isSafeUrl(construct.empty.icon)) {
+    ctx.addIssue({
+      code: z$1.ZodIssueCode.custom,
+      path: ["empty", "icon"],
+      message: "icon must be an http(s)/mailto or relative URL — no javascript:/data: schemes"
+    });
+  }
+  const reasoning = construct.capabilities?.reasoning;
+  const reasoningOpen = construct.capabilities?.reasoningOpen;
+  if (reasoningOpen !== void 0 && (reasoning === "compact" || reasoning === "off")) {
+    ctx.addIssue({
+      code: z$1.ZodIssueCode.custom,
+      path: ["capabilities", "reasoningOpen"],
+      message: '"reasoningOpen" only applies when reasoning is "full" or omitted — "compact"/"off" have no disclosure to open'
+    });
+  }
+  const history = construct.capabilities?.history;
+  if (!history) return;
+  if (history.persistence === "endpoint" && !history.url) {
+    ctx.addIssue({
+      code: z$1.ZodIssueCode.custom,
+      path: ["capabilities", "history", "url"],
+      message: '"endpoint" persistence requires a url'
+    });
+  }
+  if (history.persistence !== "endpoint" && history.url !== void 0) {
+    ctx.addIssue({
+      code: z$1.ZodIssueCode.custom,
+      path: ["capabilities", "history", "url"],
+      message: 'url is only valid with "endpoint" persistence'
+    });
+  }
+});
+function validateConstruct(input) {
+  const parsed = ConstructSchema.safeParse(input);
+  if (parsed.success) return { ok: true, construct: parsed.data };
+  return {
+    ok: false,
+    problems: parsed.error.issues.flatMap((issue) => {
+      if (issue.code === "unrecognized_keys") {
+        return issue.keys.map((key) => ({
+          path: [...issue.path.map(String), key].join("."),
+          message: `"${key}" is not construct vocabulary`
+        }));
+      }
+      return [
+        {
+          path: issue.path.map(String).join("."),
+          message: issue.message
+        }
+      ];
+    })
+  };
+}
+const inputSchema = z$1.object({
+  intent: z$1.string().min(1).optional().describe("What the author wants, in their words. Alone: returns a starter construct."),
+  construct: z$1.record(z$1.string(), z$1.unknown()).optional().describe("The FULL construct JSON for this turn. The harness owns the file; send all of it every turn.")
+}).strict();
+function starterFor(intent) {
+  const impliesWidget = /widget|embed|bubble|corner|launcher/i.test(intent);
+  const name = "my-chat";
+  return {
+    construct: {
+      $schema: CONSTRUCT_SCHEMA_URL,
+      name,
+      layout: "widget",
+      provider: { mode: "mock" }
+    },
+    stated: impliesWidget ? ["layout: widget (implied by your request)"] : [],
+    questions: [
+      `What should the element tag be? (kebab-case, e.g. "acme-support"; using "${name}" until you say)`,
+      ...impliesWidget ? [] : ["Layout: widget, fullscreen, aside, split, or custom?"]
+    ]
+  };
+}
+const constructTool = {
+  name: "construct",
+  description: `Author a kitn construct (one JSON file → one web component) turn by turn. Send the full construct each turn; invalid turns come back REJECTED with per-path reasons and the previous good construct stands. Schema: ${CONSTRUCT_SCHEMA_URL}. Preview with "kai dev <file>".`,
+  inputSchema,
+  handler: async (args) => {
+    const { intent, construct } = args;
+    if (!intent && !construct) {
+      return {
+        isError: true,
+        content: [{ type: "text", text: "construct: pass intent, construct, or both" }]
+      };
+    }
+    if (!construct) {
+      const s = starterFor(intent ?? "");
+      return {
+        content: [
+          {
+            type: "text",
+            text: [
+              "STARTER construct (mock provider — keyless, previews immediately):",
+              "```json",
+              JSON.stringify(s.construct, null, 2),
+              "```",
+              ...s.stated,
+              ...s.questions
+            ].join("\n")
+          }
+        ]
+      };
+    }
+    const out = validateConstruct(construct);
+    if (!out.ok) {
+      return {
+        content: [
+          {
+            type: "text",
+            text: [
+              "REJECTED — this turn does not change the file; the previous good construct stands.",
+              ...out.problems.map((p) => `  ${p.path || "(root)"}: ${p.message}`)
+            ].join("\n")
+          }
+        ]
+      };
+    }
+    const c = out.construct;
+    return {
+      content: [
+        {
+          type: "text",
+          text: [
+            `VALID: <${c.name}> (${c.layout}, ${c.provider.mode}).`,
+            "```json",
+            JSON.stringify(c, null, 2),
+            "```",
+            `Preview: kai dev <file>. Compile: kai compile <file>.`,
+            ...c.provider.mode === "endpoint" ? ["Backend route: use the scaffold tool — it emits a compiling route for your framework and wire."] : []
+          ].join("\n")
+        }
+      ]
+    };
+  }
+};
 function editDistance(a, b) {
   const prev = new Array(b.length + 1);
   for (let j2 = 0; j2 <= b.length; j2++) prev[j2] = j2;
@@ -8729,7 +9935,7 @@ Nothing was returned for this call — answering anyway could look like a reply
 Expected arguments for ${toolName}:
 ${argLines.join("\n")}`;
 }
-const tools = [reference, scaffold, theme, debug];
+const tools = [reference, scaffold, theme, debug, constructTool];
 const PACKAGE_NAME = "@kitn.ai/ui";
 function packageIdentity() {
   const specifier = `${PACKAGE_NAME}/package.json`;