@kitn.ai/ui 0.25.2 → 0.26.0

package/dist/mcp.es.js

@@ -1,79 +1,80 @@
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 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, existsSync } from "node:fs";
+import { readFileSync, readdirSync, existsSync } from "node:fs";
 import { fileURLToPath } from "node:url";
-import { join, resolve, dirname } from "node:path";
-var R = Object.defineProperty;
-var P = (e, t, i) => t in e ? R(e, t, { enumerable: true, configurable: true, writable: true, value: i }) : e[t] = i;
-var w = (e, t, i) => P(e, typeof t != "symbol" ? t + "" : t, i);
-const N = "https://json-schema.org/draft/2020-12/schema", _ = "https://kitn.ai/schemas/card/artifact.schema.json", D = "ArtifactCardData", z = "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.", M = "object";
-const U = [{ required: ["src"] }, { required: ["files"] }], F = { 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 }] } }, J = {
-  $schema: N,
-  $id: _,
-  title: D,
-  description: z,
-  type: M,
+import { join, dirname, resolve } 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 = {
+  $schema: U,
+  $id: F,
+  title: J,
+  description: B,
+  type: Y,
   additionalProperties: false,
-  anyOf: U,
-  properties: F
-}, re = "https://json-schema.org/draft/2020-12/schema", ae = "https://kitn.ai/schemas/card/choice.schema.json", pe = "ChoiceCardData", de = "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.", ce = "object", ue = ["options"], le = { 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`." } }, me = {
-  $schema: re,
-  $id: ae,
-  title: pe,
-  description: de,
-  type: ce,
-  required: ue,
-  properties: le
-}, he = "https://json-schema.org/draft/2020-12/schema", ye = "https://kitn.ai/schemas/card/confirm.schema.json", fe = "ConfirmCardData", ge = "Data payload for a `confirm` card (CardEnvelope.data when type='confirm').", be = "object", $e = ["actions"], ve = { 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." } }, we = {
-  $schema: he,
-  $id: ye,
-  title: fe,
-  description: ge,
-  type: be,
-  required: $e,
-  properties: ve
-}, xe = "https://json-schema.org/draft/2020-12/schema", ke = "https://kitn.ai/schemas/card/embed.schema.json", Oe = "EmbedCardData", je = "Lazy media-embed payload (YouTube / Vimeo / generic player URL).", Se = "object", Ae = ["provider"], Ie = false, qe = { provider: { type: "string", enum: ["youtube", "vimeo", "generic"], description: "Media provider. 'generic' frames `url` directly (must be an https embeddable player URL whose origin is app-allowlisted).", "x-kai-control": "select" }, id: { type: "string", description: "Provider video id (required for youtube/vimeo when `url` is absent). e.g. 'dQw4w9WgXcQ'.", maxLength: 64, pattern: "^[A-Za-z0-9_-]+$" }, url: { type: "string", format: "uri", description: "Full media/watch URL. For youtube/vimeo it is parsed to an id; for 'generic' it is the embeddable player src (https only).", "x-kai-format": "url" }, title: { type: "string", description: "Accessible title for the player iframe + the poster label. Strongly recommended for a11y.", maxLength: 300 }, poster: { type: "string", format: "uri", description: "Thumbnail shown before play. When omitted, youtube/vimeo derive a default thumbnail; 'generic' shows a neutral play placeholder.", "x-kai-format": "url" }, start: { type: "integer", minimum: 0, description: "Optional start offset in seconds.", "x-kai-unit": "seconds" }, aspectRatio: { type: "string", enum: ["16:9", "4:3", "1:1", "9:16"], default: "16:9", description: "Player box aspect ratio (CSS aspect-ratio).", "x-kai-control": "select" } }, Le = [{ if: { properties: { provider: { const: "generic" } } }, then: { required: ["url"] } }, { if: { properties: { provider: { enum: ["youtube", "vimeo"] } } }, then: { anyOf: [{ required: ["id"] }, { required: ["url"] }] } }], Ce = {
-  $schema: xe,
-  $id: ke,
-  title: Oe,
-  description: je,
-  type: Se,
-  required: Ae,
-  additionalProperties: Ie,
-  properties: qe,
-  allOf: Le
-}, De = "https://json-schema.org/draft/2020-12/schema", ze = "https://kitn.ai/schemas/card/form.schema.json", Me = "kai-form data (a form definition)", Ue = "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.", Fe = "object", Je = ["type", "properties"], Ye = { 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"] } } } } }, Be = {
-  $schema: De,
-  $id: ze,
-  title: Me,
-  description: Ue,
-  type: Fe,
-  required: Je,
-  properties: Ye
-}, He = "https://json-schema.org/draft/2020-12/schema", Ke = "https://kitn.ai/schemas/card/link.schema.json", We = "LinkPreviewData", Ve = "Rich link / Open-Graph preview payload. The card renders from this; it never fetches.", Ge = "object", Qe = ["url"], Xe = false, Ze = { 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 } }, et = {
-  $schema: He,
-  $id: Ke,
-  title: We,
-  description: Ve,
-  type: Ge,
-  required: Qe,
-  additionalProperties: Xe,
-  properties: Ze
-}, dt = "https://json-schema.org/draft/2020-12/schema", ct = "https://kitn.ai/schemas/card/tasks.schema.json", ut = "TasksCardData", lt = "Data payload for a `tasks` card (CardEnvelope.data when type='tasks').", mt = "object", ht = ["tasks"], yt = { 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`." } }, ft = {
-  $schema: dt,
-  $id: ct,
-  title: ut,
-  description: lt,
-  type: mt,
-  required: ht,
-  properties: yt
+  anyOf: H,
+  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,
+  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 = {
+  $schema: ve,
+  $id: $e,
+  title: we,
+  description: xe,
+  type: ke,
+  required: Oe,
+  properties: je
+}, Ae = "https://json-schema.org/draft/2020-12/schema", qe = "https://kitn.ai/schemas/card/embed.schema.json", Ie = "EmbedCardData", Le = "Lazy media-embed payload (YouTube / Vimeo / generic player URL).", Ee = "object", Te = ["provider"], Ce = false, Re = { provider: { type: "string", enum: ["youtube", "vimeo", "generic"], description: "Media provider. 'generic' frames `url` directly (must be an https embeddable player URL whose origin is app-allowlisted).", "x-kai-control": "select" }, id: { type: "string", description: "Provider video id (required for youtube/vimeo when `url` is absent). e.g. 'dQw4w9WgXcQ'.", maxLength: 64, pattern: "^[A-Za-z0-9_-]+$" }, url: { type: "string", format: "uri", description: "Full media/watch URL. For youtube/vimeo it is parsed to an id; for 'generic' it is the embeddable player src (https only).", "x-kai-format": "url" }, title: { type: "string", description: "Accessible title for the player iframe + the poster label. Strongly recommended for a11y.", maxLength: 300 }, poster: { type: "string", format: "uri", description: "Thumbnail shown before play. When omitted, youtube/vimeo derive a default thumbnail; 'generic' shows a neutral play placeholder.", "x-kai-format": "url" }, start: { type: "integer", minimum: 0, description: "Optional start offset in seconds.", "x-kai-unit": "seconds" }, aspectRatio: { type: "string", enum: ["16:9", "4:3", "1:1", "9:16"], default: "16:9", description: "Player box aspect ratio (CSS aspect-ratio).", "x-kai-control": "select" } }, Ne = [{ if: { properties: { provider: { const: "generic" } } }, then: { required: ["url"] } }, { if: { properties: { provider: { enum: ["youtube", "vimeo"] } } }, then: { anyOf: [{ required: ["id"] }, { required: ["url"] }] } }], Pe = {
+  $schema: Ae,
+  $id: qe,
+  title: Ie,
+  description: Le,
+  type: Ee,
+  required: Te,
+  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 = {
+  $schema: Je,
+  $id: Be,
+  title: Ye,
+  description: He,
+  type: Ke,
+  required: We,
+  properties: Ve
+}, 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,
+  title: Ze,
+  description: et,
+  type: tt,
+  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 = {
+  $schema: ht,
+  $id: ft,
+  title: yt,
+  description: gt,
+  type: bt,
+  required: vt,
+  properties: $t
 }, S = "kai_";
-function gt(e) {
+function R(e) {
   return `${S}${e}`;
 }
-const L = (e) => Object.freeze(e), C = Object.freeze({
+const N = (e) => Object.freeze(e), P = Object.freeze({
   id: "openai",
   label: "OpenAI strict",
   source: "https://developers.openai.com/api/docs/guides/structured-outputs",
@@ -82,7 +83,7 @@ const L = (e) => Object.freeze(e), C = Object.freeze({
   requireAllPropertiesRequired: true,
   allowRootAnyOf: false,
   allowRecursion: true,
-  keywords: L({
+  keywords: N({
     // core
     type: { status: "supported", note: "String, Number, Boolean, Integer, Object, Array are the supported types" },
     properties: { status: "supported", note: "objects are a supported type" },
@@ -161,7 +162,7 @@ const L = (e) => Object.freeze(e), C = Object.freeze({
     dependentRequired: { status: "unsupported", note: "explicitly listed as not supported under Composition" },
     dependentSchemas: { status: "unsupported", note: "explicitly listed as not supported under Composition" }
   })
-}), E = Object.freeze({
+}), _ = Object.freeze({
   id: "anthropic",
   label: "Anthropic strict",
   source: "https://platform.claude.com/docs/en/build-with-claude/structured-outputs#json-schema-limitations",
@@ -171,7 +172,7 @@ const L = (e) => Object.freeze(e), C = Object.freeze({
   requireAllPropertiesRequired: false,
   allowRootAnyOf: true,
   allowRecursion: false,
-  keywords: L({
+  keywords: N({
     // core
     type: { status: "supported", note: "all basic types: object, array, string, integer, number, boolean, null" },
     properties: { status: "supported", note: "objects are a supported type" },
@@ -251,90 +252,90 @@ const L = (e) => Object.freeze(e), C = Object.freeze({
     dependentRequired: { status: "unsupported", note: "not in the supported list" },
     dependentSchemas: { status: "unsupported", note: "not in the supported list" }
   })
-}), bt = ["items", "if", "then", "else", "not", "contains", "propertyNames", "unevaluatedItems", "additionalItems"], $t = ["properties", "patternProperties", "$defs", "definitions", "dependentSchemas"], vt = ["allOf", "anyOf", "oneOf", "prefixItems"], O = (e) => typeof e == "object" && e !== null && !Array.isArray(e);
-function wt(e, t) {
+}), xt = ["items", "if", "then", "else", "not", "contains", "propertyNames", "unevaluatedItems", "additionalItems"], kt = ["properties", "patternProperties", "$defs", "definitions", "dependentSchemas"], Ot = ["allOf", "anyOf", "oneOf", "prefixItems"], O = (e) => typeof e == "object" && e !== null && !Array.isArray(e);
+function jt(e, t) {
   return e === "(root)" ? t : `${e}.${t}`;
 }
-function xt(e, t) {
+function St(e, t) {
   const i = [];
   return x(e, t, "(root)", true, i), i;
 }
-function x(e, t, i, s, a) {
+function x(e, t, i, n, r) {
   if (typeof e == "boolean") return;
   if (!O(e)) {
-    a.push({ path: i, keyword: "(schema)", reason: `expected a schema object, got ${e === null ? "null" : typeof e}` });
+    r.push({ path: i, keyword: "(schema)", reason: `expected a schema object, got ${e === null ? "null" : typeof e}` });
     return;
   }
   for (const [p, c] of Object.entries(e)) {
-    const u = t.keywords[p];
-    if (!u) {
-      a.push({
+    const l = t.keywords[p];
+    if (!l) {
+      r.push({
         path: i,
         keyword: p,
         reason: p.startsWith("x-") ? `vendor extension keyword, not in the ${t.label} subset` : `unknown keyword, not classified by the ${t.label} subset`
       });
       continue;
     }
-    if (u.status === "unsupported") {
-      a.push({ path: i, keyword: p, reason: `not supported (${u.note})` });
+    if (l.status === "unsupported") {
+      r.push({ path: i, keyword: p, reason: `not supported (${l.note})` });
       continue;
     }
-    if (u.status === "supported" && u.value) {
-      const h = u.value(c);
-      h && a.push({ path: i, keyword: p, reason: h });
+    if (l.status === "supported" && l.value) {
+      const h = l.value(c);
+      h && r.push({ path: i, keyword: p, reason: h });
     }
   }
-  const n = O(e.properties), r = e.type === "object" || n;
-  if (r && t.requireAdditionalPropertiesFalse && e.additionalProperties !== false && a.push({
+  const o = O(e.properties), a = e.type === "object" || o;
+  if (a && t.requireAdditionalPropertiesFalse && e.additionalProperties !== false && r.push({
     path: i,
     keyword: "additionalProperties",
     reason: `missing; ${t.label} requires \`additionalProperties: false\` on every object`
-  }), r && !n && a.push({
+  }), a && !o && r.push({
     path: i,
     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`
-  }), r && t.requireAllPropertiesRequired && n) {
-    const p = Array.isArray(e.required) ? e.required.map(String) : [], c = Object.keys(e.properties).filter((u) => !p.includes(u));
-    c.length > 0 && a.push({
+  }), a && t.requireAllPropertiesRequired && o) {
+    const p = Array.isArray(e.required) ? e.required.map(String) : [], c = Object.keys(e.properties).filter((l) => !p.includes(l));
+    c.length > 0 && r.push({
       path: i,
       keyword: "required",
-      reason: `${t.label} requires every property in \`required\`; missing ${c.map((u) => `\`${u}\``).join(", ")} (emulate optional with a \`null\` union)`
+      reason: `${t.label} requires every property in \`required\`; missing ${c.map((l) => `\`${l}\``).join(", ")} (emulate optional with a \`null\` union)`
     });
   }
-  s && !t.allowRootAnyOf && "anyOf" in e && a.push({
+  n && !t.allowRootAnyOf && "anyOf" in e && r.push({
     path: i,
     keyword: "anyOf",
     reason: `${t.label} forbids \`anyOf\` at the ROOT ("Root level object of a schema must be an object, and not use anyOf")`
   }), Object.keys(e).filter((p) => {
     var c;
     return ((c = t.keywords[p]) == null ? void 0 : c.status) !== "annotation";
-  }).length === 0 && a.push({
+  }).length === 0 && r.push({
     path: i,
     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 m = (p) => {
+  const u = (p) => {
     var c;
     return ((c = t.keywords[p]) == null ? void 0 : c.status) === "unsupported";
   };
-  for (const p of $t) {
+  for (const p of kt) {
     const c = e[p];
-    if (!(!O(c) || m(p)))
-      for (const [u, h] of Object.entries(c))
-        x(h, t, p === "properties" ? wt(i, u) : `${i}/${p}[${u}]`, false, a);
+    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);
   }
-  for (const p of bt) {
-    if (!(p in e) || m(p)) continue;
+  for (const p of xt) {
+    if (!(p in e) || u(p)) continue;
     const c = e[p];
-    typeof c != "boolean" && x(c, t, p === "items" ? `${i === "(root)" ? "(root)" : i}[]` : `${i}/${p}`, false, a);
+    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, a);
-  for (const p of vt) {
+  O(e.additionalProperties) && x(e.additionalProperties, t, `${i}/additionalProperties`, false, r);
+  for (const p of Ot) {
     const c = e[p];
-    !Array.isArray(c) || m(p) || c.forEach((u, h) => x(u, t, `${i}/${p}[${h}]`, false, a));
+    !Array.isArray(c) || u(p) || c.forEach((l, h) => x(l, t, `${i}/${p}[${h}]`, false, r));
   }
 }
-const kt = Object.freeze({
+const At = Object.freeze({
   confirm: "Show the user an approval card and wait for their decision before you act. Use this whenever you are about to do something consequential, destructive or irreversible.",
   choice: "Ask the user to pick exactly one option from a list of rich choices. Use this instead of asking in prose when the options are known and finite.",
   tasks: "Show the user a checklist they can tick, either to select several items for you to act on or to track progress through a sequence of steps.",
@@ -343,125 +344,218 @@ const kt = Object.freeze({
   embed: "Embed a video player (YouTube, Vimeo, or a direct player URL) inline in the conversation.",
   artifact: "Show something you built (a page, an app, a set of files) in a framed preview with its source alongside, so the user can look at both."
 });
-class Ot extends Error {
-  constructor(i, s) {
-    super(jt(i, s));
+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.provider = i.id, this.source = i.source, this.cards = s;
+    this.provider = i.id, this.source = i.source, this.cards = n;
   }
   /** Every distinct keyword named across every failing card, deduped, in order. */
   get keywords() {
     const i = /* @__PURE__ */ new Set();
-    for (const s of this.cards) for (const a of s.violations) i.add(a.keyword);
+    for (const n of this.cards) for (const r of n.violations) i.add(r.keyword);
     return [...i];
   }
 }
-function jt(e, t) {
-  const i = [], s = t.length === 1 ? "card type" : "card types";
-  i.push(`${t.length} ${s} cannot be a STRICT tool definition under ${e.label}:`);
-  for (const a of t) {
-    i.push(""), i.push(`  ${a.toolName} (card type "${a.cardType}") — ${a.violations.length} problem(s):`);
-    for (const n of a.violations)
-      i.push(`    ${n.path}: \`${n.keyword}\` — ${n.reason}`);
+function It(e, t) {
+  const i = [], n = t.length === 1 ? "card type" : "card types";
+  i.push(`${t.length} ${n} cannot be a STRICT tool definition under ${e.label}:`);
+  for (const r of t) {
+    i.push(""), i.push(`  ${r.toolName} (card type "${r.cardType}") — ${r.violations.length} problem(s):`);
+    for (const o of r.violations)
+      i.push(`    ${o.path}: \`${o.keyword}\` — ${o.reason}`);
   }
   return i.push(""), i.push(`  subset source: ${e.source} (read ${e.checkedOn})`), i.push(
-    "  Fix: drop `strict: true`. Non-strict is the default and is the mode the kit's cards are proven in; both providers accept a loose schema there and ignore what they do not compile. Rewriting a built-in card schema to fit a strict subset would change what a valid card IS, which is a card-contract change, not a projection setting."
+    "  Fix: drop `strict: true`. Non-strict mode projects a provider-valid schema (root combinators are relaxed with the constraint restated in the description and still enforced by card validation). Rewriting a built-in card schema to fit a strict subset would change what a valid card IS, which is a card-contract change, not a projection setting."
   ), i.join(`
 `);
 }
-const g = (e) => typeof e == "object" && e !== null && !Array.isArray(e);
-function St(e) {
+const f = (e) => typeof e == "object" && e !== null && !Array.isArray(e), Lt = {
+  artifact: "Provide `src` (a preview URL) or `files` — at least one. An envelope with neither is rejected.",
+  embed: "For provider 'generic', include `url`. For 'youtube'/'vimeo', include `id` or `url`."
+}, Et = "The root constraint of this schema was relaxed for this provider; consult the card registry for what a valid payload is.", Tt = ["anyOf", "allOf", "oneOf", "not", "enum", "const"];
+function T(e) {
+  if (!f(e)) return null;
+  const t = {};
+  for (const [i, n] of Object.entries(e)) t[i] = { const: n };
+  return { type: "object", properties: t, required: Object.keys(e) };
+}
+function Ct(e, t) {
+  return e === "anyOf" || e === "oneOf" || e === "allOf" ? Array.isArray(t) ? t.filter(f) : [] : e === "const" ? [T(t)].filter((i) => i !== null) : e === "enum" ? Array.isArray(t) ? t.map(T).filter((i) => i !== null) : [] : [];
+}
+function Rt(e, t) {
+  const i = f(e.properties) ? { ...e.properties } : {}, n = new Set(
+    Array.isArray(e.required) ? e.required.map(String) : []
+  );
+  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))
+          p in i || (i[p] = c);
+    const s = a.map(
+      (u) => new Set(Array.isArray(u.required) ? u.required.map(String) : [])
+    );
+    if (o === "allOf")
+      for (const u of s) for (const p of u) n.add(p);
+    else {
+      const [u, ...p] = s;
+      for (const c of u)
+        p.every((l) => l.has(c)) && n.add(c);
+    }
+  }
+  Object.keys(i).length > 0 && (e.properties = i);
+  const r = [...n].filter((o) => o in i);
+  r.length > 0 && (e.required = r);
+}
+function Nt(e, t) {
+  const i = e.type;
+  if (i !== void 0 && i !== "object")
+    throw new TypeError(
+      `cardTools: the '${t}' card schema declares root type '${String(i)}', but a provider tool schema root must be an object (OpenAI and Anthropic reject anything else with HTTP 400). Wrap the payload in an object, or project this card with provider 'jsonschema'.`
+    );
+  e.type = "object";
+}
+function Pt(e, t) {
+  const i = Lt[t], n = Tt.filter((r) => r in e);
+  if (Nt(e, t), n.length !== 0) {
+    Rt(e, n);
+    for (const r of n) delete e[r];
+    return console.warn(
+      `[kai-card-tools] relaxed root ${n.join("/")} on the projected '${R(t)}' tool schema for this provider (it would be refused with HTTP 400); the constraint now lives in the description and is still enforced by card validation.`
+    ), i ?? Et;
+  }
+}
+function _t(e, t, i) {
+  for (const n of 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))
+          throw new TypeError(
+            `cardTools: require on '${t}': path '${n.path}' does not resolve in the schema`
+          );
+        r = u;
+      }
+    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)
+      throw new TypeError(
+        `cardTools: minItems at require path '${n.path}' applies to array nodes only, but '${n.path}' in the '${t}' schema is not one`
+      );
+    if (n.required !== void 0) {
+      const a = o && f(r.items) ? r.items : r, s = f(a.properties) ? a.properties : void 0;
+      for (const p of n.required)
+        if (!s || !(p in s))
+          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])];
+    }
+  }
+}
+function Dt(e) {
   return e === "$schema" || e === "$id" || e.startsWith("x-");
 }
-const At = ["items", "if", "then", "else", "not", "contains", "propertyNames", "unevaluatedItems", "additionalItems"], It = ["properties", "patternProperties", "$defs", "definitions", "dependentSchemas"], qt = ["allOf", "anyOf", "oneOf", "prefixItems"];
+const zt = ["items", "if", "then", "else", "not", "contains", "propertyNames", "unevaluatedItems", "additionalItems"], Mt = ["properties", "patternProperties", "$defs", "definitions", "dependentSchemas"], Ut = ["allOf", "anyOf", "oneOf", "prefixItems"];
 function k(e, t) {
-  if (!g(e)) return e;
+  if (!f(e)) return e;
   const i = {};
-  for (const [n, r] of Object.entries(e))
-    St(n) || (i[n] = r);
-  for (const n of It) {
-    const r = i[n];
-    if (!g(r)) continue;
-    const o = {};
-    for (const [m, p] of Object.entries(r)) o[m] = k(p, t);
-    i[n] = o;
-  }
-  for (const n of At)
-    !(n in i) || typeof i[n] == "boolean" || (i[n] = k(i[n], t));
-  g(i.additionalProperties) && (i.additionalProperties = k(i.additionalProperties, t));
-  for (const n of qt) {
-    const r = i[n];
-    Array.isArray(r) && (i[n] = r.map((o) => k(o, t)));
-  }
-  const s = g(i.properties) ? i.properties : void 0, a = i.type === "object" || s !== void 0;
-  if (a && t.closeObjects && !("additionalProperties" in i) && (i.additionalProperties = false), a && t.requireEveryProperty && s) {
-    const n = Array.isArray(i.required) ? i.required.map(String) : [], r = Object.keys(s);
-    for (const o of r)
-      n.includes(o) || (s[o] = Lt(s[o]));
-    i.required = r;
+  for (const [o, a] of Object.entries(e))
+    Dt(o) || (i[o] = a);
+  for (const o of Mt) {
+    const a = i[o];
+    if (!f(a)) continue;
+    const s = {};
+    for (const [u, p] of Object.entries(a)) s[u] = k(p, t);
+    i[o] = s;
+  }
+  for (const o of zt)
+    !(o in i) || typeof i[o] == "boolean" || (i[o] = k(i[o], t));
+  f(i.additionalProperties) && (i.additionalProperties = k(i.additionalProperties, t));
+  for (const o of Ut) {
+    const a = i[o];
+    Array.isArray(a) && (i[o] = a.map((s) => k(s, t)));
+  }
+  const n = f(i.properties) ? i.properties : void 0, r = i.type === "object" || n !== void 0;
+  if (r && t.closeObjects && !("additionalProperties" in i) && (i.additionalProperties = false), r && t.requireEveryProperty && n) {
+    const o = Array.isArray(i.required) ? i.required.map(String) : [], a = Object.keys(n);
+    for (const s of a)
+      o.includes(s) || (n[s] = Ft(n[s]));
+    i.required = a;
   }
   return i;
 }
-function Lt(e) {
-  if (!g(e)) return e;
+function Ft(e) {
+  if (!f(e)) return e;
   const t = { ...e };
   if ("type" in t) {
     const i = Array.isArray(t.type) ? t.type.map(String) : [String(t.type)];
     i.includes("null") || (t.type = [...i, "null"]);
   } else if (Array.isArray(t.anyOf))
-    t.anyOf.some((i) => g(i) && i.type === "null") || (t.anyOf = [...t.anyOf, { type: "null" }]);
+    t.anyOf.some((i) => f(i) && i.type === "null") || (t.anyOf = [...t.anyOf, { type: "null" }]);
   else
     return t;
   return Array.isArray(t.enum) && !t.enum.includes(null) && (t.enum = [...t.enum, null]), t;
 }
-function Ct(e) {
+function Jt(e) {
   const t = e;
-  return g(t.schemas) ? { schemas: t.schemas, descriptions: t.descriptions ?? {} } : { schemas: e, descriptions: {} };
+  return f(t.schemas) ? { schemas: t.schemas, descriptions: t.descriptions ?? {} } : { schemas: e, descriptions: {} };
 }
-function Et(e, t, i) {
-  const s = i[e];
-  if (typeof s == "string" && s.length > 0) return s;
-  const a = kt[e];
-  if (typeof a == "string" && a.length > 0) return a;
-  const n = t.description;
-  return typeof n == "string" && n.length > 0 ? n : `Render a \`${e}\` card.`;
+function Bt(e, t, i) {
+  const n = i[e];
+  if (typeof n == "string" && n.length > 0) return n;
+  const r = At[e];
+  if (typeof r == "string" && r.length > 0) return r;
+  const o = t.description;
+  return typeof o == "string" && o.length > 0 ? o : `Render a \`${e}\` card.`;
 }
 function v(e, t) {
-  const i = t === void 0, s = i ? e : t;
-  if (!g(s) || typeof s.provider != "string")
+  var l;
+  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: a, descriptions: n } = Ct(
-    i ? Tt() : e
-  ), r = s.strict === true;
-  if (s.provider === "jsonschema" && r)
+  const { schemas: r, descriptions: o } = Jt(
+    i ? Yt() : 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 o = r ? s.provider === "openai" ? C : E : null, m = {
-    closeObjects: o !== null,
-    requireEveryProperty: o !== null && o.requireAllPropertiesRequired
+  const s = a ? n.provider === "openai" ? P : _ : null, u = {
+    closeObjects: s !== null,
+    requireEveryProperty: s !== null && s.requireAllPropertiesRequired
   }, p = [], c = [];
-  for (const [u, h] of Object.entries(a)) {
-    const b = gt(u), f = Et(u, h, n), $ = k(h, m);
-    if (o) {
-      const d = xt($, o);
-      if (d.length > 0) {
-        c.push({ cardType: u, toolName: b, violations: d });
+  if (n.require !== void 0) {
+    for (const h of Object.keys(n.require))
+      if (!(h in r))
+        throw new TypeError(
+          `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];
+    if (L !== void 0 && _t(d, h, L), s) {
+      const E = St(d, s);
+      if (E.length > 0) {
+        c.push({ cardType: h, toolName: g, violations: E });
         continue;
       }
     }
-    s.provider === "openai" ? p.push({ type: "function", function: { name: b, description: f, parameters: $, ...r ? { strict: true } : {} } }) : s.provider === "anthropic" ? p.push({ name: b, description: f, input_schema: $, ...r ? { strict: true } : {} }) : p.push({ name: b, description: f, schema: $ });
+    n.provider === "openai" ? p.push({ type: "function", function: { name: g, description: I, parameters: d, ...a ? { strict: true } : {} } }) : n.provider === "anthropic" ? p.push({ name: g, description: I, input_schema: d, ...a ? { strict: true } : {} }) : p.push({ name: g, description: b, schema: d });
   }
-  if (o && c.length > 0) throw new Ot(o, c);
+  if (s && c.length > 0) throw new qt(s, c);
   return p;
 }
-function Tt() {
+function Yt() {
   return j;
 }
-const ei = {
+const li = {
   form: "kai-form",
   confirm: "kai-confirm",
   tasks: "kai-tasks",
@@ -470,27 +564,28 @@ const ei = {
   embed: "kai-embed",
   artifact: "kai-artifact"
 }, y = (e) => e, j = Object.freeze({
-  artifact: y(J),
-  choice: y(me),
-  confirm: y(we),
-  embed: y(Ce),
-  form: y(Be),
-  link: y(et),
-  tasks: y(ft)
-}), ii = Object.freeze(
+  artifact: y(W),
+  choice: y(be),
+  confirm: y(Se),
+  embed: y(Pe),
+  form: y(Ge),
+  link: y(rt),
+  tasks: y(wt)
+}), hi = Object.freeze(
   Object.keys(j)
 );
-function Yt(e) {
+function ii(e) {
   return Object.prototype.hasOwnProperty.call(j, e);
 }
-const PACKAGE_NAME = "@kitn.ai/ui";
+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 PACKAGE_NAME$1 = "@kitn.ai/ui";
 const MANIFEST_FILE = "custom-elements.json";
 const SOURCE_TO_PACKAGE_ROOT = ["..", "..", ".."];
 function isThisPackage(root) {
   const manifest = join(root, "package.json");
   if (!existsSync(manifest)) return false;
   try {
-    return JSON.parse(readFileSync(manifest, "utf-8")).name === PACKAGE_NAME;
+    return JSON.parse(readFileSync(manifest, "utf-8")).name === PACKAGE_NAME$1;
   } catch {
     return false;
   }
@@ -502,14 +597,14 @@ function resolveManifestPath(fromDir = dirname(fileURLToPath(import.meta.url)))
   const expected = join(packageRoot, "dist", MANIFEST_FILE);
   if (!isThisPackage(packageRoot)) {
     throw new Error(
-      `[${PACKAGE_NAME}] Cannot locate the Custom Elements Manifest: ${packageRoot} is not the ${PACKAGE_NAME} package root, so ${expected} would not be this package's manifest even if it existed.
+      `[${PACKAGE_NAME$1}] Cannot locate the Custom Elements Manifest: ${packageRoot} is not the ${PACKAGE_NAME$1} package root, so ${expected} would not be this package's manifest even if it existed.
 Resolved from: ${fromDir}
 This module must live at <package>/src/agent-tooling/mcp/ (or be bundled beside ${MANIFEST_FILE} in dist/). Resolution deliberately does NOT search parent directories — finding some other checkout's manifest is worse than failing.`
     );
   }
   if (!existsSync(expected)) {
     throw new Error(
-      `[${PACKAGE_NAME}] Missing build artifact: ${expected}
+      `[${PACKAGE_NAME$1}] Missing build artifact: ${expected}
 Resolved from: ${fromDir}
 The Custom Elements Manifest is generated by the build. Run \`nx build ui\` (or \`npm run build:api\` in packages/ui) and try again.
 Resolution deliberately does NOT search parent directories: binding to a neighbouring checkout's manifest would make this succeed against stale data.`
@@ -535,17 +630,51 @@ function getElement(tag) {
 function listElements() {
   return getDeclarations().filter((d) => d.tagName).map((d) => d.tagName).sort();
 }
+function entryForTag(tag) {
+  return tags[tag];
+}
+function optInEntryForTag(tag) {
+  if (entryForTag(tag)) return void 0;
+  return optInEntries().get(tag);
+}
+const NON_ELEMENT_ENTRIES = /* @__PURE__ */ new Set(["index", "autoloader"]);
+let _optInEntries;
+function optInEntries() {
+  if (_optInEntries) return _optInEntries;
+  _optInEntries = /* @__PURE__ */ new Map();
+  const dir = join(dirname(resolveManifestPath()), "elements");
+  let candidates;
+  try {
+    const registered = new Set(Object.values(tags));
+    candidates = readdirSync(dir).filter((f2) => f2.endsWith(".js")).map((f2) => f2.slice(0, -".js".length)).filter((base) => !registered.has(base) && !NON_ELEMENT_ENTRIES.has(base));
+  } catch {
+    return _optInEntries;
+  }
+  const unclaimed = listElements().filter((t) => !entryForTag(t));
+  for (const base of candidates) {
+    let code;
+    try {
+      code = readFileSync(join(dir, `${base}.js`), "utf-8");
+    } catch {
+      continue;
+    }
+    for (const tag of unclaimed) {
+      if (!_optInEntries.has(tag) && code.includes(`"${tag}"`)) _optInEntries.set(tag, base);
+    }
+  }
+  return _optInEntries;
+}
 let _cardTags;
 let _cardHosts;
 function cardTagForType(type) {
   if (!_cardTags) {
     const present = new Set(listElements());
-    _cardTags = new Map(Object.entries(ei).filter(([, tag]) => present.has(tag)));
+    _cardTags = new Map(Object.entries(li).filter(([, tag]) => present.has(tag)));
   }
   return _cardTags.get(type);
 }
 function cardTypeForTag(tag) {
-  for (const name of ii) {
+  for (const name of hi) {
     if (cardTagForType(name) === tag) return name;
   }
   return void 0;
@@ -560,6 +689,383 @@ function cardHostTags() {
   }
   return _cardHosts;
 }
+const invariants = [
+  {
+    id: "reactivity-two-halves",
+    statement: "A new array reference NOTIFIES; a new object for each changed item makes the change VISIBLE. Editing an existing item needs both. Adds and removes need only the fresh array. Setting the same array back is a no-op even if an item inside it was swapped. The test pins how the KIT behaves — it will render stale unless both arrive — but nothing checks CONSUMER code, so this is a rule you apply, not a guarantee you will be warned about. Reorders follow the same rule as adds and removes; the test names reorders in its title but exercises only an add and a remove, so treat that half as reasoned rather than pinned.",
+    appliesTo: { tags: ["kai-chat", "kai-conversations"] },
+    enforcedBy: { kind: "test", paths: ["packages/ui/src/components/reactivity-contract.test.tsx"] },
+    status: "enforced",
+    diagnosis: [
+      {
+        symptom: "messages render once but never update while streaming",
+        cause: "the same array reference is being set back; the element is never notified"
+      },
+      {
+        symptom: "the list re-renders but an edited item shows stale content",
+        cause: "the array is new but the item object identity is unchanged; the reference-keyed <For> keeps the old row"
+      }
+    ],
+    examples: [
+      {
+        wrong: "chat.messages.push({ id, role: 'user', parts: [{ type: 'text', text }] });",
+        right: "chat.messages = [...chat.messages, { id, role: 'user', parts: [{ type: 'text', text }] }];",
+        note: "Mutating in place never notifies. Neither does assigning the same array reference back — the setter compares references."
+      },
+      {
+        wrong: "messages[last].parts.push(part);",
+        right: "chat.messages = messages.map((m, i) => (i === last ? { ...m, parts: [...m.parts, part] } : m));",
+        note: "This is the half that gets missed. A fresh array alone notifies, but the reference-keyed <For> keeps the old row until the EDITED ITEM is a new object too. createAssistantStream from @kitn.ai/ui/state already does both."
+      }
+    ]
+  },
+  {
+    id: "props-not-attributes",
+    statement: "Set arrays, objects and functions as JS PROPERTIES on the element instance. Only scalars (strings, numbers, booleans) belong in attributes, and the derived layer's scalar flag records which prop is which. What actually goes wrong, because the mechanism is not the obvious one: a framework template binding or String() stringifies an array to '[object Object]', which is not JSON, and the attribute path falls back to handing the element that raw STRING — so the prop is silently a string and the list renders nothing. A function cannot survive JSON at all: JSON.stringify({ onSubmit }) is '{}', so every callback is dropped. And an attribute re-set is not how updates are delivered — see reactivity-two-halves. A hand-written, valid-JSON attribute does happen to parse today, because a transitive dependency JSON.parses attributes whose declared default is not a string, but that is that dependency's behaviour and not this kit's contract; do not build on it. NOTHING IN THIS REPO ENFORCES THIS — it is a consumer contract, and the scalar flag in the derived layer is how the catalog SERVES the fact, which is not the same as checking it.",
+    appliesTo: {},
+    // kind:'none' after measurement, replacing a `structural` pointer at
+    // define.tsx that did not contain the claimed mechanism. What define.tsx
+    // actually does is install non-reflecting accessors for the handful of props
+    // colliding with reflected global IDL attributes (role/hidden/autofocus), in
+    // the OPPOSITE direction: it stops property writes reflecting TO attributes.
+    // The attribute->property path lives in component-register, a transitive
+    // dependency, and measured in the real jsdom project against the real
+    // element it PARSES a JSON attribute onto the property rather than rejecting
+    // it. Nothing here checks consumer code for the contract; S1's scoring
+    // exercises a property update on kai-chat.messages, but no scenario names
+    // this invariant, so it is not claimed as a measurement either.
+    enforcedBy: { kind: "none" },
+    status: "open",
+    diagnosis: [
+      {
+        symptom: "an element renders empty and the data looks right in devtools",
+        cause: "the property holds the STRING '[object Object]', not an array; it arrived through an attribute that was stringified rather than assigned"
+      },
+      {
+        symptom: "everything renders but no callback ever fires",
+        cause: "the object went through JSON into an attribute, and JSON drops functions silently"
+      }
+    ],
+    examples: [
+      {
+        wrong: "el.setAttribute('messages', String(messages));",
+        right: "el.messages = messages;",
+        note: "Measured against the real element: the attribute becomes '[object Object]', JSON.parse fails, and the fallback leaves a STRING on the prop. messages is scalar:false in the derived layer; placeholder, loading and theme are scalar:true and do belong in attributes."
+      },
+      {
+        wrong: "cards.setAttribute('policy', JSON.stringify({ onSubmit }));",
+        right: "cards.policy = { onSubmit };",
+        note: "Measured: JSON.stringify({ onSubmit }) is '{}', so the handler is gone before the attribute is even set. No attribute can carry a function."
+      }
+    ]
+  },
+  {
+    id: "events-non-bubbling",
+    statement: "Non-bubbling is the default: public kai-* events are dispatched through the one helper that hard-codes bubbles:false and composed:false, so listen on the element itself, never on a parent or document. The protocol exceptions (kai-maximize-intent, kai-maximize-state and kai-card) bubble or compose deliberately and are listed in the derived layer under eventExceptions — do not generalise from them to the rest.",
+    appliesTo: {},
+    enforcedBy: { kind: "structural", path: "packages/ui/src/elements/define.tsx" },
+    status: "enforced",
+    diagnosis: [
+      {
+        symptom: "a delegated listener on document or a parent never fires",
+        cause: "kai-* events do not bubble; attach the listener to the element that dispatches it"
+      },
+      {
+        symptom: "a listener on the element works, but the same one on a wrapper div does not",
+        cause: "same cause; only the three eventExceptions cross the element boundary"
+      }
+    ],
+    examples: [
+      {
+        wrong: "document.addEventListener('kai-submit', (e) => send(e.detail.value));",
+        right: "chat.addEventListener('kai-submit', (e) => send(e.detail.value));",
+        note: "The dispatch helper in src/elements/define.tsx passes { bubbles: false, composed: false }, so nothing above the host ever sees the event."
+      },
+      {
+        wrong: "wrapper.addEventListener('kai-message-action', handleAction);",
+        right: "chat.addEventListener('kai-message-action', handleAction);",
+        note: "Delegating from a wrapper is the most common shape of this bug, because it is the habit every DOM framework teaches."
+      }
+    ]
+  },
+  {
+    id: "host-coordinates",
+    statement: "There is no store. Data flows in via properties, out via events, and the host wires element A to element B. Solid context does not cross element boundaries, so nothing coordinates elements except the host application, and no element owns another. Placing two elements in the same subtree wires nothing.",
+    appliesTo: {},
+    enforcedBy: { kind: "none" },
+    status: "open",
+    diagnosis: [
+      {
+        symptom: "two elements are expected to sync but do not",
+        cause: "nothing auto-coordinates; the host must listen on one element and set properties on the other"
+      },
+      {
+        symptom: "a property assignment is silently ignored and the prop is not in the reference",
+        cause: "the data was put on the element that displays the conversation rather than the one that owns the list"
+      }
+    ],
+    examples: [
+      {
+        wrong: "chat.conversations = rows;",
+        right: "conversations.conversations = rows;",
+        note: "kai-chat has no conversations prop — the sidebar is its own element. One element never holds the whole app state."
+      },
+      {
+        wrong: "chat.addEventListener('kai-conversation-select', (e) => load(e.detail.id));",
+        right: "conversations.addEventListener('kai-conversation-select', (e) => { chat.messages = threadsById[e.detail.id]; });",
+        note: "Event out of A, property into B, wired by the host. The event is dispatched by the element that owns the list, so that is where the listener goes."
+      }
+    ]
+  },
+  {
+    id: "untrusted-model-output",
+    statement: "Everything the model produced is untrusted input: a MessagePart, card envelope or tool argument reaching innerHTML, an href or src, window.open or an iframe is a vulnerability. THE DEFECT IS NEVER A MISSING GUARD, IT IS WHICH PATH GOT IT — every one found so far sat on a path the CONSUMER controls while the model-controlled path beside it had none. So put a policy on the sink, and MATCH THE LIST TO THE SINK rather than reaching for one universal list: http:, https: and mailto: for anything navigable the user may click, resolved against the page so ordinary relative links still work; http: and https: ONLY for a model-supplied citation, which is a reference to a page on the public web and has no business being relative. Those are two lists because there are two sinks — it is the same split the kit makes internally between SAFE_SCHEMES and RENDERABLE_SCHEMES, not a variant invented here. Whichever you use, parse inside a try/catch and RETURN FALSE on an unparseable URL: new URL() throws, and a throw at a sink crashes the render. And render model text as TEXT. Escaping is the correct rendering: the source text must stay VISIBLE as well as inert, because a filter that deleted it would pass the security check and be a worse UI. COVERAGE, and read this before trusting CI here: the three XSS suites are tests and ONLY tests. They run in the required test job, so the vectors they pin cannot come back — but NOTHING structural stops a NEW sink landing unguarded. No lint script in the package is about sinks, and the coupling map's unenforced list has no entry for the class. A new sink is caught in review or not at all.",
+    appliesTo: {},
+    // WHAT THE THREE SUITES DO NOT CATCH: they pin the vectors that were FOUND
+    // (#246 markdown innerHTML, #247 the artifact's three URL sinks, and the
+    // hostile-stream path), so they are regression guards, not a guard over the
+    // CLASS. A newly written component that puts model text on a fresh
+    // unguarded sink adds no failing test anywhere. Verified against
+    // HANDOFF-2026-08-13 §13.2 ("They are tests and only tests... nothing
+    // structural stops a NEW sink landing unguarded"), and re-checked against
+    // the tree: none of packages/ui/scripts/lint-*.mjs concerns sinks, and
+    // docs/coupling-map.md has no row for the class. Kept as kind:'test'
+    // because the regression coverage is real; status is `partial` because the
+    // class is not covered, and the statement carries the gap.
+    enforcedBy: {
+      kind: "test",
+      paths: [
+        "packages/ui/tests/components/markdown-xss.test.tsx",
+        "packages/ui/tests/components/artifact-url-xss.test.tsx",
+        "packages/ui/tests/components/hostile-model-output.test.tsx"
+      ]
+    },
+    status: "partial",
+    diagnosis: [
+      {
+        symptom: "a custom renderer for a tool result or a card body executes markup the model emitted",
+        cause: "model text reached innerHTML on a hand-written path; the guarded path is the one every real message flows through, and this one bypassed it"
+      },
+      {
+        symptom: "a citation or card link navigates to javascript: or data:",
+        cause: "a model-supplied URL reached an href, a src or window.open with no scheme check"
+      }
+    ],
+    examples: [
+      {
+        wrong: "el.innerHTML = part.text;",
+        right: "el.textContent = part.text;",
+        note: "For rich text render the part through <kai-markdown>, which escapes rather than sanitizes (src/components/markdown.tsx) and filters link and image URLs. Never hand-roll a second markdown-to-innerHTML path."
+      },
+      {
+        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."
+      },
+      {
+        wrong: "<a href={source.url}>{source.title}</a>",
+        right: `const isCitationUrl = (u) => { try { return ['http:', 'https:'].includes(new URL(u).protocol); } catch { return false; } };
+{isCitationUrl(source.url) ? <a href={source.url} rel="noopener noreferrer">{source.title}</a> : <span>{source.title}</span>}`,
+        note: "No base here, unlike the navigable case: a model-supplied citation is a reference to a page on the public web, so a relative path is not a citation and returns false. It must RETURN false, not throw — a throw escapes the ternary and the fallback never renders, which is exactly the deleted-text failure this invariant's own statement forbids. The <span> keeps the title VISIBLE. REPO-INTERNAL equivalent: isRenderableLink in src/primitives/link-preview.ts, also not exported."
+      }
+    ]
+  },
+  {
+    id: "kit-parses-consumer-fetches",
+    statement: "The kit parses; the consumer fetches. Two halves, covered differently. KIT SIDE: every MessagePart variant the wire encodes must be accounted for, or a variant is gone once the request leaves — that half is enforced by lint:silent-drops in CI. CONSUMER SIDE: never hand-roll an SSE reader; import readOpenAIStream, readAnthropicStream or readModelStream from @kitn.ai/ui/wire, and fetch from your own endpoint, because there is no client, no key handling and no provider SDK below wire/. NO CI CHECK COVERS THAT SECOND HALF — no guard reads consumer or scaffolded code for a hand-rolled reader; it is measured by the acceptance deck instead, at scenario S2, whose scoring line is 'imports readOpenAIStream from @kitn.ai/ui/wire; no hand-rolled SSE reader anywhere in the output'.",
+    appliesTo: {},
+    // WHAT lint:silent-drops DOES NOT CATCH: it analyzes src/wire, so it covers
+    // the kit-side half only. A consumer or a scaffold that hand-rolls its own
+    // SSE loop never enters its scan, and the lint stays green. That gap is
+    // stated in the statement above so no reader concludes CI catches it, and
+    // scenario S2 is what actually measures it. Recorded rather than closed:
+    // flipping this to kind:'none' would discard a real guard over a real half,
+    // which is what `status: 'partial'` exists to express.
+    enforcedBy: { kind: "lint", script: "lint:silent-drops" },
+    status: "partial",
+    diagnosis: [
+      {
+        symptom: "streaming works for one provider and silently drops parts for another",
+        cause: "a hand-rolled reader misses part variants the wire layer already handles; replace it with the wire import"
+      },
+      {
+        symptom: "tokens arrive glued together, or a multibyte character renders as garbage mid-stream",
+        cause: "a hand-rolled reader split on a data: prefix and assumed one frame per chunk; keep-alive comments, multi-line frames and codepoints split across a socket boundary are all real"
+      }
+    ],
+    examples: [
+      {
+        wrong: "text += JSON.parse(line.replace('data: ', '')).choices[0].delta.content;",
+        right: "const turn = await readOpenAIStream(res, stream);",
+        note: "import { readOpenAIStream } from '@kitn.ai/ui/wire'; createAssistantStream from '@kitn.ai/ui/state' owns the message, the reader fills it. readAnthropicStream and readModelStream are the other two entry points."
+      },
+      {
+        wrong: "await fetch('https://api.openai.com/v1/chat/completions', { headers: { Authorization: 'Bearer ' + apiKey } });",
+        right: "await fetch('/api/chat', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ messages: toOpenAIMessages(history) }) });",
+        note: "The consumer fetches, from their own endpoint. A provider key in the browser is a leaked key; toOpenAIMessages/toAnthropicMessages encode the thread for the wire."
+      }
+    ]
+  },
+  {
+    id: "upgrade-race",
+    statement: "A property set before the element upgrades is lost. On script-tag targets, load order is not ours. Until issue #99 option B (upgrade-property preservation in defineWebComponent) lands, every script-tag recipe must state this race loudly and set properties only after registration — await customElements.whenDefined(tag), which is the guarantee. A timer, or DOMContentLoaded, is a guess about load order rather than a guarantee: registration can land later, from an async chunk or a dynamically inserted script.",
+    appliesTo: { targets: ["script-tag"] },
+    enforcedBy: { kind: "none", until: "issue #99 option B lands in defineWebComponent" },
+    status: "open",
+    diagnosis: [
+      {
+        symptom: "properties set in inline script are ignored on a CDN page",
+        cause: "the element had not upgraded yet; the set landed on a plain HTMLElement and was lost"
+      },
+      {
+        symptom: "the same code works under a bundler and not from a script tag",
+        cause: "the bundler happened to order the registration first; a script tag gives no such guarantee"
+      }
+    ],
+    examples: [
+      {
+        wrong: "setTimeout(() => { chat.messages = messages; }, 0);",
+        right: "customElements.whenDefined('kai-chat').then(() => { chat.messages = messages; });",
+        note: "A timer bets on load order. whenDefined resolves when the registry actually has the tag, which is the thing you need to be true."
+      },
+      {
+        wrong: "document.addEventListener('DOMContentLoaded', () => { chat.messages = messages; });",
+        right: "customElements.whenDefined('kai-chat').then(() => { chat.messages = messages; });",
+        note: "DOMContentLoaded is about the parser, not the registry. It says the markup is there, never that the element behind the tag has been defined."
+      }
+    ]
+  }
+];
+const surfaceRecipes = [
+  {
+    id: "workspace-chat",
+    intent: "Full-screen chat with a conversations sidebar; assistant replies can open artifacts in a resizable side panel.",
+    archetypes: ["full-screen"],
+    targets: ["bundler"],
+    ingredients: ["kai-chat", "kai-conversations", "kai-resizable", "kai-artifact"],
+    backend: { endpoint: "consumer-owned", reader: "readModelStream" },
+    // WHERE the parts go, which the wiring edges below never said. Until this
+    // field existed a builder could read the whole recipe, the whole element
+    // reference and the whole scaffold and still not know whether the rail was a
+    // child of the chat or a sibling beside it — and the two answers lay out
+    // differently, so it is not a detail anyone can defer. One agent building
+    // from the MCP said so in as many words and then guessed.
+    //
+    // Slotted, and the tree decided it rather than taste: `<kai-chat>` declares a
+    // `sidebar` slot whose own description is "Left column (your nav /
+    // conversation list). Fixed width; use compose-your-own for resizable", and
+    // this recipe's own corpus story — chat-slots.stories.tsx — composes exactly
+    // `<kai-conversations slot="sidebar">` inside `<kai-chat>`.
+    //
+    // THE TREE ALSO PUBLISHES THE OTHER ANSWER, and an earlier version of this
+    // comment claimed it did not ("nothing in the tree composes them as
+    // siblings") — asserted without looking, which is the same defect as the
+    // over-generous `note` below it. The docs put the pair side by side in at
+    // least five places: guides/frameworks/html.mdx, svelte.mdx (a section
+    // titled "Add a conversation sidebar"), angular.mdx, vue.mdx, and
+    // examples/knowledge-base.mdx with its live demo. Every one of them is a
+    // layout the CONSUMER owns — a flex row they write, or `<kai-resizable>` —
+    // which is the compose-your-own path the slot's own description points at,
+    // and is what you want when the rail must resize. So the two are not in
+    // conflict about what is legal; this record says which one the RECIPE is,
+    // and the docs currently present the sibling form without saying that.
+    composition: [
+      {
+        child: "kai-conversations",
+        parent: "kai-chat",
+        slot: "sidebar",
+        // Every clause here is checked against chat-thread.tsx, not inferred
+        // from the slot's name. The shell's whole sidebar implementation is one
+        // `<aside part="sidebar" class="flex w-64 shrink-0 …">` around a
+        // `<slot name="sidebar" />`: fixed width, no responsive class in the
+        // file, no collapse logic, and `<kai-chat>` never listens for
+        // `kai-collapse-toggle`. Collapse belongs to the rail
+        // (`collapsed`/`collapse()`), and conversation-list.tsx says so in as
+        // many words: "the host owns the surrounding region". A note that
+        // credited the shell with collapse and a breakpoint would send a builder
+        // into a 16rem empty column holding a floating reopen button.
+        note: `the rail is a light-DOM child of <kai-chat> carrying slot="sidebar", not a sibling: the shell renders it into its own ::part(sidebar) aside, a FIXED-WIDTH column (w-64 in chat-thread.tsx, exposed as a part so you can restyle it) — and that is the whole of what the shell does. Collapse is the RAIL's own (collapsed / collapse() / kai-collapse-toggle) and <kai-chat> does not react to it, so a collapsed rail leaves the column at its fixed width; there is no responsive behaviour here either. Give the rail height (display:block;height:100%) and drive it through its own JS properties — being slotted changes where it renders, never how it is wired. If the COLUMN itself has to collapse, resize or respond to width, that is the <kai-workspace> layout shell (its start aside: startCollapsed / collapseBelow / drawer-below, widths via the --kai-workspace-start-* custom properties) or a layout you own`
+      }
+    ],
+    wiring: [
+      {
+        from: "kai-conversations",
+        event: "kai-conversation-select",
+        to: "kai-chat",
+        property: "messages",
+        note: "detail is {id}; the host looks the thread up and assigns it — a new array AND a new object per changed item (reactivity-two-halves)"
+      },
+      {
+        from: "kai-conversations",
+        event: "kai-new-chat",
+        to: "kai-chat",
+        property: "messages",
+        note: "detail is empty by design; the event is the whole signal and the host resets to an empty thread"
+      },
+      {
+        from: "kai-chat",
+        event: "kai-submit",
+        to: "kai-chat",
+        property: "messages",
+        note: "host reads event.detail.value, appends the user turn, streams the reply through the wire reader onto parts[]"
+      },
+      {
+        from: "kai-artifact",
+        event: "kai-maximize-change",
+        to: "kai-resizable",
+        property: "maximizedIndex",
+        note: "detail is {maximized}, NOT an index: the host knows which panel holds the artifact and mirrors the boolean onto that index (null to restore). Only needed when the panel is not an ancestor — an artifact INSIDE a kai-resizable-item already drives it through the bubbling kai-maximize-intent protocol, with no host code at all"
+      }
+    ],
+    invariants: [
+      "reactivity-two-halves",
+      "props-not-attributes",
+      "events-non-bubbling",
+      "host-coordinates",
+      "kit-parses-consumer-fetches",
+      "untrusted-model-output"
+    ],
+    // No single story composes all four ingredients, so the corpus names what
+    // each half is really proven by rather than one path that only half applies:
+    // chat-slots composes kai-chat with kai-conversations, split-workspace
+    // composes kai-resizable with kai-artifact, and surfaces.test.ts is where
+    // the four wiring edges above are actually executed.
+    corpus: [
+      "packages/ui/src/elements/chat-slots.stories.tsx",
+      "packages/ui/src/elements/split-workspace.stories.tsx",
+      "packages/ui/src/agent-tooling/catalog/surfaces.test.ts"
+    ]
+  },
+  {
+    // The script-tag instance. Without it, DeliveryTarget 'script-tag' and the
+    // whole upgrade-race invariant exist in the schema with no recipe using
+    // them, and S5 has nothing to reconstruct from.
+    id: "support-widget-script-tag",
+    intent: "A docked support chat widget added to a page with a script tag and no build step, talking to an endpoint the site owner already runs. The CMS case.",
+    archetypes: ["widget", "docked"],
+    targets: ["script-tag"],
+    ingredients: ["kai-chat"],
+    backend: { endpoint: "consumer-owned", reader: "readOpenAIStream" },
+    wiring: [
+      {
+        from: "kai-chat",
+        event: "kai-submit",
+        to: "kai-chat",
+        property: "messages",
+        note: "host reads event.detail.value, appends the user turn, streams the reply through the wire reader; on this target the host is an inline script, not a framework, so the listener must be attached after customElements.whenDefined (upgrade-race)"
+      }
+    ],
+    invariants: [
+      "upgrade-race",
+      "reactivity-two-halves",
+      "props-not-attributes",
+      "events-non-bubbling",
+      "kit-parses-consumer-fetches",
+      "untrusted-model-output"
+    ],
+    corpus: ["packages/ui/README.md"]
+  }
+];
 const JS_ONLY_TYPE_PATTERNS = /\[\]|\{|Record</;
 function isJsOnlyType(typeText) {
   return typeText ? JS_ONLY_TYPE_PATTERNS.test(typeText) : false;
@@ -591,7 +1097,7 @@ function loopWiring(example) {
   return [
     "",
     "#### Wiring the loop",
-    `- **Tool names are \`${S}<card type>\`.** \`${gt(example)}\` produces \`{ type: "${example}" }\`. Use \`isCardTool(name)\` to split card calls from your own tools; never match the prefix by hand.`,
+    `- **Tool names are \`${S}<card type>\`.** \`${R(example)}\` produces \`{ type: "${example}" }\`. Use \`isCardTool(name)\` to split card calls from your own tools; never match the prefix by hand.`,
     "- **`tool_call_id` becomes `CardEnvelope.id`, unchanged.** That is what makes a revision UPSERT: a model that re-sends the same tool call id replaces the card in place instead of rendering a second copy of it. Generating your own id breaks that silently.",
     "- **`cardFromToolCall(name, input, { id: call.id })`** turns the call into a renderable envelope, or returns `null` when it is one of your own tools so the loop falls through to it. It never throws.",
     `- **Everything above is one import:** \`import { cardTools, cardFromToolCall, isCardTool } from '@kitn.ai/ui/schemas'\`. The raw documents also ship as JSON (\`@kitn.ai/ui/schemas/${example}.schema.json\`) for a Python or Go backend.`
@@ -603,7 +1109,7 @@ function renderCardContract(tag, cardType, provider) {
   const lines = [
     "",
     "### Card contract",
-    `\`<${tag}>\` renders \`CardEnvelope.type: "${cardType}"\`. A model does not emit an envelope; it calls the tool \`${gt(cardType)}\`, and the kit turns that call back into one.`
+    `\`<${tag}>\` renders \`CardEnvelope.type: "${cardType}"\`. A model does not emit an envelope; it calls the tool \`${R(cardType)}\`, and the kit turns that call back into one.`
   ];
   lines.push(
     "",
@@ -623,25 +1129,185 @@ function renderCardContract(tag, cardType, provider) {
   return lines;
 }
 function renderCardHost(tag) {
-  const rows = ii.map((type) => {
+  const rows = hi.map((type) => {
     const cardTag = cardTagForType(type);
-    return `- \`${type}\` → \`<${cardTag ?? "(no element)"}>\`, tool \`${gt(type)}\``;
+    return `- \`${type}\` → \`<${cardTag ?? "(no element)"}>\`, tool \`${R(type)}\``;
   });
   return [
     "",
     "### Card contract",
     `\`<${tag}>\` renders generative-UI cards inside the thread. It is a HOST: it draws whatever envelopes arrive, and carries the two props that say what a card may be.`,
     "",
-    `- **\`cardTypes\`** — \`Record<envelope type, custom element tag>\`. What DRAWS a card. Merged over the built-ins, so your entry overrides ours and the other ${ii.length - 1} still render.`,
-    `- **\`cardSchemas\`** — \`Record<envelope type, JSON Schema>\`. What a VALID card looks like. This is the prop that carries YOUR OWN card schemas into the browser validator; the ${ii.length} built-ins are already known. Both are objects, so both are JS properties (\`el.cardSchemas = …\`), never HTML attributes.`,
+    `- **\`cardTypes\`** — \`Record<envelope type, custom element tag>\`. What DRAWS a card. Merged over the built-ins, so your entry overrides ours and the other ${hi.length - 1} still render.`,
+    `- **\`cardSchemas\`** — \`Record<envelope type, JSON Schema>\`. What a VALID card looks like. This is the prop that carries YOUR OWN card schemas into the browser validator; the ${hi.length} built-ins are already known. Both are objects, so both are JS properties (\`el.cardSchemas = …\`), never HTML attributes.`,
     "",
     "Write both once with `createCardRegistry({ use, custom })` from `@kitn.ai/ui/schemas` and thread it to both ends: `el.cardTypes = cards.tags` / `el.cardSchemas = cards.validationSchemas` on the client, `cardTools(cards, { provider })` on the route.",
     "",
     "Built-in card types (ask `component_reference` for one of these tags to get its schema and tool definition):",
     ...rows,
-    ...loopWiring(ii[0])
+    ...loopWiring(hi[0])
   ];
 }
+function invariantsFor(tag) {
+  return invariants.filter((i) => !i.appliesTo.tags || i.appliesTo.tags.includes(tag));
+}
+function compositionLines(r, noteSep) {
+  if (!r.composition) return [];
+  return [
+    "- **Composition** — where the parts go (a slotted child, not a sibling):",
+    ...r.composition.map(
+      (c) => `  - \`<${c.child} slot="${c.slot}">\` goes INSIDE \`<${c.parent}>\`` + (noteSep && c.note ? `${noteSep}${c.note}` : "")
+    )
+  ];
+}
+function recipesFor(tag) {
+  return surfaceRecipes.filter((r) => r.ingredients.includes(tag));
+}
+function coverageOf(inv) {
+  const by = inv.enforcedBy;
+  const guard = by.kind === "test" ? `the kit's own tests (${by.paths.join(", ")})` : by.kind === "lint" ? `the kit's \`${by.script}\` script, in required CI` : by.kind === "structural" ? `a structural guarantee in ${by.path}` : "";
+  switch (inv.status) {
+    case "enforced":
+      return `enforced by ${guard}`;
+    case "partial":
+      return `PARTIALLY ENFORCED: one half is covered, by ${guard}; the statement says which half is not`;
+    case "open":
+      return "NOT ENFORCED: nothing in the kit checks this" + (by.kind === "none" && by.until ? `, until ${by.until}` : "") + ". A rule you apply, not a guarantee you will be warned about";
+  }
+}
+function scopeOf(inv) {
+  const { tags: tags2, targets, parts: parts2 } = inv.appliesTo;
+  const bits = [];
+  if (tags2) bits.push(`only ${tags2.join(", ")}`);
+  if (targets) bits.push(`${targets.join(" / ")} delivery only`);
+  if (parts2) bits.push(`parts ${parts2.join(", ")}`);
+  return bits.join("; ");
+}
+function exampleLines(examples) {
+  if (examples.length === 0) return [];
+  const out = ["", "```js"];
+  examples.forEach((ex, i) => {
+    if (i > 0) out.push("");
+    out.push("// WRONG", ex.wrong, "// RIGHT", ex.right);
+    if (ex.note) out.push(...ex.note.split("\n").map((l) => `// ${l}`));
+  });
+  out.push("```");
+  return out;
+}
+function coverageSummary(applicable) {
+  const open = applicable.filter((i) => i.status === "open").length;
+  const partial = applicable.filter((i) => i.status === "partial").length;
+  if (open === 0 && partial === 0) return "";
+  const total = applicable.length;
+  const half = (n) => `only half of what ${n === 1 ? "it says" : "they say"}`;
+  const clauses = [];
+  if (open > 0) {
+    clauses.push(`${open} of the ${total} below ${open === 1 ? "is" : "are"} enforced by NOTHING at all`);
+  }
+  if (partial > 0) {
+    clauses.push(
+      open > 0 ? `${partial} more by ${half(partial)}` : `${partial} of the ${total} below ${partial === 1 ? "is" : "are"} enforced by ${half(partial)}`
+    );
+  }
+  return ` ${clauses.join(", and ")}.`;
+}
+function catalogSectionLines(tag) {
+  const applicable = invariantsFor(tag);
+  const lines = [];
+  if (applicable.length > 0) {
+    lines.push(
+      "",
+      "### Invariants",
+      "Rules that have already broken real consumers of this kit. Each block says what enforces it — read that line rather than assuming CI catches a violation, because nothing here reads YOUR code." + coverageSummary(applicable) + ' Diagnosis and wrong/right examples for every invariant are served once, not repeated per element — call component_reference with { name: "invariants" }.'
+    );
+    for (const inv of applicable) {
+      const scope = scopeOf(inv);
+      lines.push("", `#### ${inv.id}${scope ? ` (${scope})` : ""} — ${coverageOf(inv)}`, inv.statement);
+    }
+  }
+  const recipes = recipesFor(tag);
+  if (recipes.length > 0) {
+    lines.push(
+      "",
+      "### Appears in surface recipes",
+      'Compositions this element is part of, each with the whole ingredient list and the host wiring — nothing coordinates one element with another except your own code (host-coordinates). The WHY behind each wiring edge, and the caveats on the nesting below, are served once rather than repeated per ingredient — call component_reference with { name: "recipes" }.'
+    );
+    for (const r of recipes) {
+      lines.push(
+        "",
+        `#### ${r.id} — ${r.intent}`,
+        `- **Ingredients:** ${r.ingredients.map((t) => `\`<${t}>\``).join(", ")}`,
+        `- **Delivery:** ${r.targets.join(", ")} · archetype: ${r.archetypes.join(", ")}`,
+        `- **Backend:** your own endpoint, read with \`${r.backend.reader}\` from \`@kitn.ai/ui/wire\``,
+        ...compositionLines(r, ""),
+        // Bare ids, deliberately. This row is a DEPENDENCY list, not a coverage
+        // claim, and it can only ever be read a few lines below the full
+        // `### Invariants` section in the same response, where each of these ids
+        // already carries its own coverage line. Repeating the status here would
+        // print it a second (and, with two recipes, a third) time per element for
+        // no fact a reader does not already have on the page.
+        `- **Invariants it leans on:** ${r.invariants.join(", ")}`,
+        // Compact: the edge (event out of A, property into B) with no `note`.
+        // The note is the WHY — often a full sentence, sometimes several — and
+        // repeating it is the same shape of duplication task 4 removed from
+        // invariants: this recipe's ingredients (kai-chat, kai-conversations,
+        // kai-resizable, kai-artifact) all print this identical wiring list.
+        // `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}\``);
+      }
+    }
+  }
+  return lines;
+}
+function renderRecipeAppendix() {
+  const lines = [
+    `## Surface recipe catalog (${surfaceRecipes.length} total) — wiring notes`,
+    "",
+    "Every element lookup that appears in a recipe lists its ingredients, delivery, backend and a compact wiring list (event out of A, property into B). This is the long form: the WHY behind each wiring edge, written once here rather than repeated on every ingredient."
+  ];
+  for (const r of surfaceRecipes) {
+    lines.push(
+      "",
+      `#### ${r.id} — ${r.intent}`,
+      `- **Ingredients:** ${r.ingredients.map((t) => `\`<${t}>\``).join(", ")}`,
+      `- **Delivery:** ${r.targets.join(", ")} · archetype: ${r.archetypes.join(", ")}`,
+      `- **Backend:** your own endpoint, read with \`${r.backend.reader}\` from \`@kitn.ai/ui/wire\``,
+      `- **Invariants it leans on:** ${r.invariants.join(", ")}`,
+      ...compositionLines(r, " — "),
+      "- **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}\`` + (w2.note ? ` — ${w2.note}` : "")
+      );
+    }
+  }
+  return lines;
+}
+function renderInvariantAppendix() {
+  const lines = [
+    `## Invariant catalog (${invariants.length} total) — diagnosis and examples`,
+    "",
+    "Every element lookup lists the invariants that apply to it by id and one-line statement. This is the long form: full statement, diagnosis and wrong/right examples for each record, written once here rather than repeated on every element it applies to."
+  ];
+  for (const inv of invariants) {
+    const scope = scopeOf(inv);
+    lines.push("", `#### ${inv.id}${scope ? ` (${scope})` : ""} — ${coverageOf(inv)}`, inv.statement);
+    if (inv.diagnosis.length > 0) {
+      lines.push("", "If you are debugging:");
+      for (const d of inv.diagnosis) lines.push(`- ${d.symptom} → ${d.cause}`);
+    }
+    lines.push(...exampleLines(inv.examples));
+  }
+  return lines;
+}
+function eventDetail(typeText) {
+  const m = /^CustomEvent<([\s\S]*)>$/.exec(typeText?.trim() ?? "");
+  return m ? m[1].trim() || void 0 : void 0;
+}
 function formatReference(tag, provider) {
   const el = getElement(tag);
   if (!el) {
@@ -657,13 +1323,45 @@ Call component_reference with no name (or name: "list") to list all ${all.length
   if (el.description) {
     lines.push("", el.description.trim());
   }
+  const entry = entryForTag(tag);
+  const iface = el.name;
+  const neverUpgrades = `If you skip registering it the element never upgrades: nothing renders, **no error and no warning is logged**, a property you set assigns and reads back correctly, and \`customElements.whenDefined('${tag}')\` never resolves.`;
+  lines.push("", "### Getting the element");
+  if (entry) {
+    lines.push(
+      `Register it before you use it. ${neverUpgrades}`,
+      "",
+      "```ts",
+      "import '@kitn.ai/ui/elements';",
+      `import '@kitn.ai/ui/elements/${entry}'; // or just this one`,
+      "```"
+    );
+  } else {
+    const optIn = optInEntryForTag(tag);
+    lines.push(
+      `**\`${tag}\` is opt-in — it is not part of \`import '@kitn.ai/ui/elements'\` (register-all), and that import alone will NOT register it.** ` + (optIn ? `Import its own entry point instead. ${neverUpgrades}` : (
+        // No built module claims this tag, so there is no specifier to name.
+        // Stay honest rather than inventing one.
+        `Find its specific \`@kitn.ai/ui/elements/<name>\` entry point in the package's published exports before using it. ${neverUpgrades}`
+      ))
+    );
+    if (optIn) {
+      lines.push("", "```ts", `import '@kitn.ai/ui/elements/${optIn}';`, "```");
+    }
+  }
+  if (iface) {
+    lines.push(
+      "",
+      `TypeScript: \`import type { ${iface} } from '@kitn.ai/ui/elements';\` — the element interface ships with the package; do not hand-roll a structural type.`
+    );
+  }
   lines.push(
     "",
     "### AI/UI contract",
     '`kai-*` elements accept **array and object data as JavaScript properties** (set in JavaScript via `el.property = value`, not as HTML attributes). Events are native CustomEvents — listen with `el.addEventListener("event-name", handler)` and read `event.detail` for the payload.'
   );
   const cardType = cardTypeForTag(tag);
-  if (cardType !== void 0 && Yt(cardType)) {
+  if (cardType !== void 0 && ii(cardType)) {
     lines.push(...renderCardContract(tag, cardType, provider));
   } else if (cardHostTags().includes(tag)) {
     lines.push(...renderCardHost(tag));
@@ -701,7 +1399,10 @@ Call component_reference with no name (or name: "list") to list all ${all.length
     lines.push("", "### Events (CustomEvent, listen via addEventListener)");
     for (const ev of events) {
       const desc = ev.description?.trim() ?? "";
-      lines.push(`- **${ev.name}** — ${desc}`);
+      const detail = eventDetail(ev.type?.text);
+      lines.push(
+        detail ? `- **${ev.name}** — ${desc} \`detail\`: \`${detail}\`` : `- **${ev.name}** — ${desc}`
+      );
     }
   }
   const methods = (el.members ?? []).filter(isPublicMethod);
@@ -752,13 +1453,16 @@ Call component_reference with no name (or name: "list") to list all ${all.length
       }
     }
   }
+  lines.push(...catalogSectionLines(tag));
   return lines.join("\n");
 }
 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.",
   inputSchema: z$1.object({
-    name: z$1.string().optional(),
+    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.'
+    ),
     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.`
     )
@@ -782,17 +1486,25 @@ No tool definition was returned, because guessing which envelope you meant would
     const provider = rawProvider ?? DEFAULT_PROVIDER;
     let text2;
     if (!name || name === "list") {
-      const tags = listElements();
-      const cardRows = ii.map((t) => cardTagForType(t)).filter((t) => t !== void 0);
-      text2 = `AI/UI elements (${tags.length} total):
+      const tags2 = listElements();
+      const cardRows = hi.map((t) => cardTagForType(t)).filter((t) => t !== void 0);
+      text2 = `AI/UI elements (${tags2.length} total):
 
-` + tags.map((t) => `  ${t}`).join("\n") + `
+` + tags2.map((t) => `  ${t}`).join("\n") + `
 
 Call component_reference with a specific name (e.g. { name: "kai-chat" }) for full API details.
 
 Card-backed elements — ask for one of these to get its JSON Schema and a generated \`${S}*\` tool definition:
   ${cardRows.join(", ")}
-The elements that HOST them (and carry the \`cardTypes\` / \`cardSchemas\` props): ${cardHostTags().join(", ")}`;
+The elements that HOST them (and carry the \`cardTypes\` / \`cardSchemas\` props): ${cardHostTags().join(", ")}
+
+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.`;
+    } else if (name === "invariants") {
+      text2 = renderInvariantAppendix().join("\n");
+    } else if (name === "recipes") {
+      text2 = renderRecipeAppendix().join("\n");
     } else {
       text2 = formatReference(name, provider);
     }
@@ -1001,7 +1713,13 @@ const openai = {
   // Both model and tools come from the browser. \`tools\` is undefined unless the
   // front end declared any, and JSON.stringify drops it, so the same handler
   // serves a tool archetype and a plain chat.
-  const { model, messages, tools } = await readChatRequest(request);
+  let chatBody: ChatRequestBody;
+  try {
+    chatBody = await readChatRequest(request);
+  } catch (error) {
+    return toChatErrorResponse(error);
+  }
+  const { model, messages, tools } = chatBody;
 
   const upstream = await fetch('https://api.openai.com/v1/chat/completions', {
     method: 'POST',
@@ -1365,7 +2083,13 @@ function reframeToOpenAISse(body: ReadableStream<Uint8Array>): ReadableStream<Ui
 async function chatHandler(request: Request): Promise<Response> {
   // Both model and tools come from the browser. \`tools\` arrives in OpenAI
   // function form and is converted to this API's shape below.
-  const { model, messages, tools } = await readChatRequest(request);
+  let chatBody: ChatRequestBody;
+  try {
+    chatBody = await readChatRequest(request);
+  } catch (error) {
+    return toChatErrorResponse(error);
+  }
+  const { model, messages, tools } = chatBody;
   const { system, messages: anthropicMessages } = toAnthropicBody(messages);
   const anthropicTools = toAnthropicTools(tools);
 
@@ -1492,7 +2216,13 @@ const openrouter = {
   webRoute: `async function chatHandler(request: Request): Promise<Response> {
   // tools is undefined unless the front end sent one; JSON.stringify drops it,
   // so the same handler serves a tool archetype and a plain chat.
-  const { model, messages, tools } = await readChatRequest(request);
+  let chatBody: ChatRequestBody;
+  try {
+    chatBody = await readChatRequest(request);
+  } catch (error) {
+    return toChatErrorResponse(error);
+  }
+  const { model, messages, tools } = chatBody;
 
   const upstream = await fetch('https://openrouter.ai/api/v1/chat/completions', {
     method: 'POST',
@@ -1718,7 +2448,13 @@ const FINISH_REASONS: Record<string, string> = {
 };
 
 async function chatHandler(request: Request): Promise<Response> {
-  const { messages, tools } = await readChatRequest(request);
+  let chatBody: ChatRequestBody;
+  try {
+    chatBody = await readChatRequest(request);
+  } catch (error) {
+    return toChatErrorResponse(error);
+  }
+  const { messages, tools } = chatBody;
   const toolSet = toToolSet(tools);
   const prompt = toModelMessages(messages);
 
@@ -1966,7 +2702,13 @@ const agent = createReactAgent({
 
 // Stream a compiled LangGraph agent to the browser as OpenAI-format SSE.
 async function chatHandler(request: Request): Promise<Response> {
-  const { messages } = await readChatRequest(request);
+  let chatBody: ChatRequestBody;
+  try {
+    chatBody = await readChatRequest(request);
+  } catch (error) {
+    return toChatErrorResponse(error);
+  }
+  const { messages } = chatBody;
 
   // agent.stream() coerces plain {role, content} objects into BaseMessage
   // instances itself, including OpenAI-shaped tool_calls, so the wire messages
@@ -2082,9 +2824,44 @@ import type { OpenAIWireMessage } from '@kitn.ai/ui/wire';
  */
 type ChatRequestBody = { messages: OpenAIWireMessage[] };
 
+class ChatRequestError extends Error {
+  constructor(readonly status: number, message: string) { super(message); }
+}
+
+/** Narrow the JSON body once, at the edge. A bare GET, a malformed body, or a
+ *  missing messages array is a ChatRequestError with a status — NEVER an
+ *  unhandled SyntaxError (findings F-10). */
+async function readChatRequest(request: Request): Promise<ChatRequestBody> {
+  if (request.method !== 'POST') {
+    throw new ChatRequestError(405, \`Method \${request.method} not allowed — POST /api/chat.\`);
+  }
+  let parsed: unknown;
+  try { parsed = await request.json(); } catch {
+    throw new ChatRequestError(400, 'Request body is not valid JSON.');
+  }
+  const body = parsed as ChatRequestBody;
+  if (!Array.isArray(body?.messages)) {
+    throw new ChatRequestError(400, 'Request body must carry a messages array.');
+  }
+  return body;
+}
+
+/** Map a guard rejection to the Response its status demands; rethrow anything
+ *  else — an unexpected error should be loud, not laundered into a 400. */
+function toChatErrorResponse(error: unknown): Response {
+  if (error instanceof ChatRequestError) return Response.json({ error: error.message }, { status: error.status });
+  throw error;
+}
+
 export default {
   async fetch(req: Request, env: Env): Promise<Response> {
-    const { messages } = (await req.json()) as ChatRequestBody;
+    let chatBody: ChatRequestBody;
+    try {
+      chatBody = await readChatRequest(req);
+    } catch (error) {
+      return toChatErrorResponse(error);
+    }
+    const { messages } = chatBody;
 
     let nativeStream: ReadableStream<Uint8Array>;
     try {
@@ -2159,7 +2936,13 @@ export default {
   },
   webRoute: `async function chatHandler(request: Request): Promise<Response> {
   // Proxy Workers AI over its OpenAI-compatible HTTP endpoint, token server-side.
-  const { messages } = await readChatRequest(request);
+  let chatBody: ChatRequestBody;
+  try {
+    chatBody = await readChatRequest(request);
+  } catch (error) {
+    return toChatErrorResponse(error);
+  }
+  const { messages } = chatBody;
 
   const upstream = await fetch(
     \`https://api.cloudflare.com/client/v4/accounts/\${process.env.CF_ACCOUNT_ID}/ai/v1/chat/completions\`,
@@ -2250,7 +3033,13 @@ const ollama = {
   // The model is pinned here, not sent by the browser. tools IS forwarded:
   // it is undefined unless the front end declared any, and JSON.stringify
   // drops it, so the same handler serves a tool archetype and a plain chat.
-  const { messages, tools } = await readChatRequest(request);
+  let chatBody: ChatRequestBody;
+  try {
+    chatBody = await readChatRequest(request);
+  } catch (error) {
+    return toChatErrorResponse(error);
+  }
+  const { messages, tools } = chatBody;
 
   const upstream = await fetch('http://localhost:11434/v1/chat/completions', {
     method: 'POST',
@@ -2344,7 +3133,13 @@ const mastra = new MastraClient({ baseUrl: MASTRA_URL });
 
 // Proxy a Mastra agent to the browser as OpenAI-format SSE.
 async function chatHandler(request: Request): Promise<Response> {
-  const { messages } = await readChatRequest(request);
+  let chatBody: ChatRequestBody;
+  try {
+    chatBody = await readChatRequest(request);
+  } catch (error) {
+    return toChatErrorResponse(error);
+  }
+  const { messages } = chatBody;
 
   // MastraClient's Agent.stream() takes AI-SDK CoreMessage[], not the OpenAI
   // wire format: each message has ONE literal role (not a union) and content
@@ -2508,9 +3303,64 @@ import type { OpenAIWireMessage } from '@kitn.ai/ui/wire';
 const app = express();
 app.use(express.json());
 
+class ChatRequestError extends Error {
+  constructor(readonly status: number, message: string) { super(message); }
+}
+
+/** Narrow the JSON body once, at the edge. A bare GET or a missing messages
+ *  array is a ChatRequestError with a status — NEVER an unhandled throw
+ *  (findings F-10). Malformed JSON is rejected upstream by express.json(),
+ *  which the error handler below turns into a JSON 400. */
+function readChatRequest(req: express.Request): { messages: OpenAIWireMessage[] } {
+  if (req.method !== 'POST') {
+    throw new ChatRequestError(405, \`Method \${req.method} not allowed — POST /api/chat.\`);
+  }
+  const body = (req.body ?? {}) as { messages?: OpenAIWireMessage[] };
+  if (!Array.isArray(body.messages)) {
+    throw new ChatRequestError(400, 'Request body must carry a messages array.');
+  }
+  return body as { messages: OpenAIWireMessage[] };
+}
+
+/** Map a guard rejection to the response its status demands; rethrow anything
+ *  else — an unexpected error should be loud, not laundered into a 400. */
+function toChatErrorResponse(error: unknown, res: express.Response): void {
+  if (error instanceof ChatRequestError) {
+    res.status(error.status).json({ error: { message: error.message } });
+    return;
+  }
+  throw error;
+}
+
+// express.json() rejects a malformed body at the MIDDLEWARE level, before any
+// handler runs — without this it surfaces as Express's default HTML error page.
+app.use(
+  (
+    err: { status?: number; message?: string },
+    _req: express.Request,
+    res: express.Response,
+    _next: express.NextFunction,
+  ) => {
+    res.status(err?.status ?? 500).json({ error: { message: err?.message ?? 'Request failed.' } });
+  },
+);
+
+// A bare GET is a 405 with the method named, not Express's default 404 —
+// the resource exists, the verb is wrong.
+app.get('/api/chat', (_req, res) => {
+  res.status(405).json({ error: { message: 'Method not allowed — POST /api/chat.' } });
+});
+
 // POST /api/chat: bridge a Pi RPC session to the browser as SSE.
 app.post('/api/chat', (req, res) => {
-  const { messages } = req.body as { messages: OpenAIWireMessage[] };
+  let chatBody: { messages: OpenAIWireMessage[] };
+  try {
+    chatBody = readChatRequest(req);
+  } catch (error) {
+    toChatErrorResponse(error, res);
+    return;
+  }
+  const { messages } = chatBody;
   const last = messages.at(-1)?.content;
   // \`content\` is a plain string until the turn carries an attachment, at which
   // point it is an ARRAY of content parts. Pi's RPC mode takes a TEXT prompt and
@@ -2715,24 +3565,86 @@ const mock = {
   streamFormat: "native",
   envVars: [],
   routeTemplates: {},
-  streamMapping: "No backend and no provider, but a real wire. createMockResponder() from @kitn.ai/ui/state yields canned SSE frames and the scaffold reads them with readOpenAIStream from @kitn.ai/ui/wire, on the same code path a real route's response takes: same reader, same part folding, same abort handling. The frames carry the OpenAI chat-completions shape because the mock stands in for your /api/chat ROUTE, not for a provider (every other integration here re-frames its provider to that shape server-side), so going live replaces ONE expression: mockResponse(value) becomes the awaited response from your own chat route, and nothing else in the handler changes. Nothing here can be mistaken for a real turn: the stream opens with a ': kai-mock' SSE comment, every frame carries a _kai_mock field naming createMockResponder, model reports as 'kai-mock' (no provider serves it), and usage is all zeros.",
-  runNote: "No backend or API key needed: the reply is generated in the browser and parsed by the same reader a real route feeds. Run the front-end as-is; swap `integration` for a real provider (openai, anthropic, openrouter, ollama) when ready, and the emitted handler differs by one expression.",
+  webRoute: `import { createMockResponder } from '@kitn.ai/ui/state';
+
+// The kit's own mock responder — no provider, no key, no upstream. MODULE
+// scope, not per-request: the responder owns the cursor into its canned
+// replies, so rebuilding it per turn would answer with the first one forever.
+const mockResponse = createMockResponder();
+
+async function chatHandler(request: Request): Promise<Response> {
+  // The responder cycles its replies whatever you send, so the prompt is a
+  // courtesy — but the body is still read exactly the way a real route reads
+  // it, so swapping this handler for a provider's changes nothing upstream of
+  // this file.
+  let chatBody: ChatRequestBody;
+  try {
+    chatBody = await readChatRequest(request);
+  } catch (error) {
+    return toChatErrorResponse(error);
+  }
+  const { messages } = chatBody;
+  const last = [...messages].reverse().find((m) => m.role === 'user');
+  const prompt = last && typeof last.content === 'string' ? last.content : '';
+
+  // createMockResponder() yields COMPLETE OpenAI chat-completions SSE frames —
+  // the same strings the front end's local preview streams — so this route only
+  // writes them out verbatim. No framing is built here; the browser parses them
+  // with readOpenAIStream from @kitn.ai/ui/wire, exactly as it would a real
+  // route's response. Every frame is marked as a mock (a ': kai-mock' banner, a
+  // _kai_mock field, model 'kai-mock', zero usage).
+  const encoder = new TextEncoder();
+  let open = true;
+  const body = new ReadableStream<Uint8Array>({
+    async start(controller) {
+      for await (const frame of mockResponse(prompt)) {
+        // The browser hangs up when the user asks a new question mid-answer;
+        // stop producing frames rather than writing into a cancelled stream.
+        if (!open) return;
+        controller.enqueue(encoder.encode(frame));
+      }
+      controller.close();
+    },
+    cancel() {
+      open = false;
+    },
+  });
+
+  return new Response(body, {
+    status: 200,
+    headers: {
+      'Content-Type': 'text/event-stream; charset=utf-8',
+      // no-transform stops a proxy buffering the stream into one blob.
+      'Cache-Control': 'no-cache, no-transform',
+      Connection: 'keep-alive',
+      // A proxy in front of a preview build would otherwise buffer the whole
+      // stream and the reply would land all at once instead of streaming.
+      'X-Accel-Buffering': 'no',
+    },
+  });
+}`,
+  streamMapping: "No backend and no provider, but a real wire. createMockResponder() from @kitn.ai/ui/state yields canned SSE frames and the scaffold reads them with readOpenAIStream from @kitn.ai/ui/wire, on the same code path a real route's response takes: same reader, same part folding, same abort handling. The frames carry the OpenAI chat-completions shape because the mock stands in for your /api/chat ROUTE, not for a provider (every other integration here re-frames its provider to that shape server-side), so going live replaces ONE expression: mockResponse(value) becomes the awaited response from your own chat route, and nothing else in the handler changes. Nothing here can be mistaken for a real turn: the stream opens with a ': kai-mock' SSE comment, every frame carries a _kai_mock field naming createMockResponder, model reports as 'kai-mock' (no provider serves it), and usage is all zeros. Block (2) serves the same frames over HTTP as an OPTIONAL route, so the /api/chat seam can be stood up before any provider exists.",
+  runNote: "No backend or API key needed: the reply is generated in the browser and parsed by the same reader a real route feeds. Run the front-end as-is; swap `integration` for a real provider (openai, anthropic, openrouter, ollama) when ready, and the emitted handler differs by one expression. Block (2) is the OPTIONAL server half: the same mock frames served over HTTP, for standing up the /api/chat seam before any provider exists.",
   docsSlug: "integrations/mock",
-  // Nothing: there is no HTTP request at all. The frames are produced in-process
-  // by createMockResponder(), so there is no body to forward a model or a tools
-  // array on, and no route that would read one.
+  // Nothing: the front end makes no HTTP request at all, and the optional route
+  // reads only `messages` — and only as a courtesy prompt the responder is free
+  // to ignore. There is no model to pick and no tools array anything would run.
   forwardsFromClient: [],
-  // Nothing to install: there is no route to install anything for.
+  // Nothing to install: the route's one import is the kit itself, which every
+  // scaffold already depends on (registry.test.ts pins deps.npm to the route's
+  // imports minus @kitn.ai/ui).
   deps: { npm: [], pip: [] },
-  // The other 'frontend-safe' entry, and the only one that is true by absence:
-  // no routeTemplates, no webRoute, no envVars. There is no request, no upstream
-  // and no secret, so there is nothing a public bundle could give away. This is
-  // the one place where "declares nothing" genuinely means safe — which is
-  // precisely why it still has to SAY so rather than be left blank.
+  // The other 'frontend-safe' entry. The route now exists (G-04) but changes
+  // nothing here: it holds no credential, sends no auth header and reaches no
+  // upstream, so there is still nothing a public bundle could give away. The
+  // schema's own refinement re-checks that claim against the route source.
   keyExposure: "frontend-safe",
-  // Nothing at all, and here that is the literal truth rather than a shorthand:
-  // there is no route, no upstream and no process. This is the "No backend"
-  // group of create-kai's gateway prompt all by itself.
+  // Nothing to supply out of band: no upstream, no process, no runtime. The
+  // route is optional — the emitted app streams locally without it — which is
+  // what keeps mock in the "No backend" group of create-kai's gateway prompt
+  // (listGatewayGroups derives that from frontend-safe + outOfBand 'none', not
+  // from the absence of a route, precisely because this route is one nobody
+  // NEEDS).
   outOfBand: "none"
 };
 const archetypes$1 = [
@@ -2764,9 +3676,41 @@ const archetypes$1 = [
     defaultPlacement: "side",
     docsSlug: "examples/agentic-assistant"
   },
+  /**
+   * THE FIRST OFFICIAL BLOCK (recast spec 2026-08-20 § 3b; F-16).
+   *
+   * This preset used to carry `kai-artifact` + `kai-resizable` — an UNWIRED
+   * artifact split — while omitting the conversation rail, the one thing its
+   * name promised (rung-3 finding F-16). It now names the workspace BLOCK: the
+   * chat-agnostic `kai-workspace` layout shell, a WIRED `kai-conversations`
+   * rail, `kai-chat` in the main region, and the `@kitn.ai/ui/state` thread
+   * helpers (bindThreadMessages / createThreadSessions / createSaveScheduler /
+   * parseStoredThread) with the persistence POLICY left in consumer-owned
+   * lines. `examples/apps/workspace/` is the block's reference implementation.
+   *
+   * The artifact split did not vanish — it moved to `artifact-split` below, so
+   * its renderer branch keeps its cells in `verify:scaffold`.
+   */
   {
     id: "workspace",
     title: "Agentic workspace",
+    components: ["kai-chat", "kai-workspace", "kai-conversations"],
+    defaultPlacement: "full-page",
+    docsSlug: "examples/workspace"
+  },
+  /**
+   * THE PRESET THAT KEEPS A CAPABILITY ON THE AXIS — the same reason the
+   * `attachments` preset exists (see its comment below): `listCapabilityGroups`
+   * derives the gate's surface axis from this table, so when the recast moved
+   * the artifact pair off `workspace`, this entry is what kept
+   * `kai-artifact`+`kai-resizable` compiling in `verify:scaffold` instead of
+   * silently losing every cell. The pair is ONE capability because `isArtifactSplit`
+   * in scaffold.ts requires both: a split with no preview pane is an empty
+   * panel, and a preview with no split has nowhere to sit.
+   */
+  {
+    id: "artifact-split",
+    title: "Artifact preview split",
     components: ["kai-chat", "kai-artifact", "kai-resizable"],
     defaultPlacement: "side",
     docsSlug: "examples/workspace"
@@ -2868,9 +3812,33 @@ const CHAT_REQUEST_BODY_DECL = [
   `  tools?: unknown[];`,
   `};`,
   ``,
-  `/** Narrow the JSON body once, at the edge. */`,
+  `class ChatRequestError extends Error {`,
+  `  constructor(readonly status: number, message: string) { super(message); }`,
+  `}`,
+  ``,
+  `/** Narrow the JSON body once, at the edge. A bare GET, a malformed body, or a`,
+  ` *  missing messages array is a ChatRequestError with a status — NEVER an`,
+  ` *  unhandled SyntaxError: one killed a Vite dev server (findings F-10). */`,
   `async function readChatRequest(request: Request): Promise<ChatRequestBody> {`,
-  `  return (await request.json()) as ChatRequestBody;`,
+  `  if (request.method !== 'POST') {`,
+  `    throw new ChatRequestError(405, \`Method \${request.method} not allowed — POST /api/chat.\`);`,
+  `  }`,
+  `  let parsed: unknown;`,
+  `  try { parsed = await request.json(); } catch {`,
+  `    throw new ChatRequestError(400, 'Request body is not valid JSON.');`,
+  `  }`,
+  `  const body = parsed as ChatRequestBody;`,
+  `  if (!Array.isArray(body?.messages)) {`,
+  `    throw new ChatRequestError(400, 'Request body must carry a messages array.');`,
+  `  }`,
+  `  return body;`,
+  `}`,
+  ``,
+  `/** Map a guard rejection to the Response its status demands; rethrow anything`,
+  ` *  else — an unexpected error should be loud, not laundered into a 400. */`,
+  `function toChatErrorResponse(error: unknown): Response {`,
+  `  if (error instanceof ChatRequestError) return Response.json({ error: error.message }, { status: error.status });`,
+  `  throw error;`,
   `}`
 ];
 const CONTENT_PARTS_DECL = [
@@ -3022,8 +3990,9 @@ const text = (s) => ({
   content: [{ type: "text", text: s }]
 });
 const FLEX_FILL = "flex: 1; min-height: 0;";
+const TOAST_LAYER_NOTE = "The z-index stays BELOW 100: the kit's kai-toast-region (a body-level sibling toast() mounts) paints at z-index var(--kai-toast-z, 100), so a wrapper at or above it buries every toast.";
 const FULL_PAGE = {
-  style: "position: fixed; inset: 0; display: flex; flex-direction: column; text-align: start; z-index: 1000;",
+  style: "position: fixed; inset: 0; display: flex; flex-direction: column; text-align: start; z-index: 90;",
   chatFill: FLEX_FILL,
   note: "fills the viewport (fixed, inset 0)",
   altNote: [
@@ -3033,6 +4002,7 @@ const FULL_PAGE = {
     "TanStack Start starter wraps every route in a Header + Footer that pushed the composer 13px",
     "below the fold at 1280x800. Fixed positioning escapes both, `text-align: start` undoes the",
     "inherited centring, and z-index keeps a sticky header from painting over the thread.",
+    TOAST_LAYER_NOTE,
     "This DOES cover the chrome around it (nav included) — that is what full-page means here.",
     'Want the chat to sit INSIDE your own layout instead? Use placement: "inline".'
   ]
@@ -3049,18 +4019,20 @@ function placementStyle(placement) {
       };
     case "side":
       return {
-        style: "position: fixed; top: 0; inset-inline-end: 0; height: 100dvh; width: 380px; border-inline-start: 1px solid var(--kai-color-border); display: flex; flex-direction: column; z-index: 1000;",
+        style: "position: fixed; top: 0; inset-inline-end: 0; height: 100dvh; width: 380px; border-inline-start: 1px solid var(--kai-color-border); display: flex; flex-direction: column; z-index: 90;",
         chatFill: FLEX_FILL,
         note: "full-height side panel, docked to the trailing edge (100dvh)",
         altNote: [
+          TOAST_LAYER_NOTE,
           "In-flow alternative (push content instead of overlay): drop `position`/`z-index` and make this a `flex: 0 0 380px` column inside a `display: flex` row at `height: 100dvh`."
         ]
       };
     case "docked-widget":
       return {
-        style: "position: fixed; bottom: 1.5rem; inset-inline-end: 1.5rem; width: 380px; height: 600px; max-height: calc(100dvh - 3rem); border-radius: 16px; overflow: hidden; box-shadow: 0 12px 32px var(--kai-shadow-color, rgba(0,0,0,0.18)); display: flex; flex-direction: column; z-index: 1000;",
+        style: "position: fixed; bottom: 1.5rem; inset-inline-end: 1.5rem; width: 380px; height: 600px; max-height: calc(100dvh - 3rem); border-radius: 16px; overflow: hidden; box-shadow: 0 12px 32px var(--kai-shadow-color, rgba(0,0,0,0.18)); display: flex; flex-direction: column; z-index: 90;",
         chatFill: FLEX_FILL,
-        note: "fixed, floating bottom-right widget"
+        note: "fixed, floating bottom-right widget",
+        altNote: [TOAST_LAYER_NOTE]
       };
     default:
       return FULL_PAGE;
@@ -3122,8 +4094,10 @@ function realStreamBody(opts) {
     cards = false,
     valueSource = "e.detail.value",
     afterValue = [],
+    afterTurn = [],
     mock: mock2 = false,
-    filesExpr
+    filesExpr,
+    fetchSignal
   } = opts;
   const asConst = strictRoles ? " as const" : "";
   const historyType = strictRoles ? ": ChatMessage[]" : "";
@@ -3156,6 +4130,11 @@ function realStreamBody(opts) {
     `${indent}  method: 'POST',`,
     `${indent}  headers: { 'Content-Type': 'application/json' },`,
     `${indent}  body: JSON.stringify(${bodyPayload(threadExpr)}),`,
+    ...fetchSignal ? [
+      `${indent}  // The turn's own AbortSignal (from sessions.begin above): switching`,
+      `${indent}  // threads or deleting this one can cancel the request itself.`,
+      `${indent}  signal: ${fetchSignal},`
+    ] : [],
     `${indent}});`,
     `${indent}// The finished turn: text, reasoning, tool calls, stop reason, usage. An`,
     `${indent}// error FRAME inside a 200 stream lands on turn.error, and whatever`,
@@ -3180,17 +4159,29 @@ function realStreamBody(opts) {
       `${pad}  if (turn.error) console.error('Model error:', turn.error.message);`
     ],
     `${pad}} catch (err) {`,
+    ...fetchSignal && !mock2 ? [
+      `${pad}  // A DELIBERATE abort (the thread was deleted, or a new turn began on it)`,
+      `${pad}  // is not a failure and has no one left to report it to.`,
+      `${pad}  if (${fetchSignal}.aborted) return;`
+    ] : [],
     `${pad}  // Without this a bad key is a permanently blank assistant bubble plus an`,
-    `${pad}  // unhandled rejection. abort() settles the message and flips any tool`,
-    `${pad}  // panel still waiting on a result to output-error, so nothing spins`,
-    `${pad}  // forever; text that already streamed stays put.`,
-    `${pad}  stream.abort(err instanceof Error ? err.message : 'Request failed');`,
-    `${pad}  console.error(err);  // swap in your own error surface (a toast, a banner)`,
+    `${pad}  // unhandled rejection. abort(reason) settles the message AND puts the`,
+    `${pad}  // reason where the reader can see it: onto any tool panel still waiting`,
+    `${pad}  // on a result (output-error, so nothing spins forever), or — on a`,
+    `${pad}  // text-only turn, which has no panel to carry it — as a new text part in`,
+    `${pad}  // the thread. Text that already streamed stays put.`,
+    `${pad}  // The reason is SHOWN TO THE USER. err.message is the honest default;`,
+    `${pad}  // swap in a sentence a visitor can read once you know your failure modes.`,
+    `${pad}  // The && is load-bearing: an Error is free to carry an empty message, and`,
+    `${pad}  // an empty reason is nothing to show — back to the blank bubble.`,
+    `${pad}  stream.abort(err instanceof Error && err.message ? err.message : 'Request failed');`,
+    `${pad}  console.error(err);  // the console is for you; the thread is for them`,
     `${pad}} finally {`,
     `${pad}  // done() SETTLES the message: every sink call after it is dropped, which`,
     `${pad}  // is why the whole loop runs above it and not after.`,
     `${pad}  stream.done();`,
     `${pad}  ${setLoading("false")}`,
+    ...afterTurn.map((l) => `${pad}  ${l}`),
     `${pad}}`
   ].join("\n");
 }
@@ -3276,12 +4267,14 @@ function assertCardToolFormat(integration) {
   return provider;
 }
 function wireImportLines(opts) {
-  const { pad = "", typed, toolLoop = false, setMessagesType = false, cards = false, cardTools: emitsCardTools = false, mock: mock2 = false, attachments = false } = opts;
+  const { pad = "", typed, toolLoop = false, setMessagesType = false, cards = false, cardTools: emitsCardTools = false, mock: mock2 = false, attachments = false, workspaceBlock = false } = opts;
   const stateNames = [
+    ...workspaceBlock ? ["bindThreadMessages"] : [],
     "createAssistantStream",
     // The mock's canned reply comes from the kit, not from a copy pasted into
     // this file. One implementation, shared with create-kai and the starters.
     ...mock2 ? ["createMockResponder"] : [],
+    ...workspaceBlock ? ["createSaveScheduler", "createThreadSessions", "parseStoredThread"] : [],
     ...attachments ? ["type AttachmentData"] : [],
     ...typed ? ["type ChatMessage"] : [],
     ...typed && setMessagesType ? ["type SetMessages"] : []
@@ -3409,11 +4402,197 @@ const CARD_PROP_COMMENT = [
 function jsxComment(lines, pad) {
   return lines.map((l) => `${pad}{/* ${l.replace(/^\/\/ ?/, "")} */}`);
 }
+function indentEmitted(lines, by) {
+  return lines.flatMap((l) => l.split("\n")).map((l) => l === "" ? l : `${by}${l}`);
+}
 const MESSAGE_EMBEDDED_TAGS = /* @__PURE__ */ new Set(["kai-tool", "kai-reasoning"]);
-const WORKSPACE_STRUCTURAL_TAGS = /* @__PURE__ */ new Set(["kai-resizable", "kai-artifact"]);
-function isWorkspace(components) {
+const ARTIFACT_SPLIT_TAGS = /* @__PURE__ */ new Set(["kai-resizable", "kai-artifact"]);
+function isArtifactSplit(components) {
   return components.includes("kai-resizable") && components.includes("kai-artifact");
 }
+const BLOCK_TAGS = /* @__PURE__ */ new Set(["kai-workspace", "kai-conversations"]);
+function isWorkspaceBlock(components) {
+  return components.includes("kai-workspace") && components.includes("kai-conversations");
+}
+function blockThreadStoreLines(pad = "") {
+  return [
+    `${pad}// ── The workspace block's thread store — YOUR code, from here down ─────────`,
+    `${pad}//`,
+    `${pad}// The record shape is yours (title policy, timestamps, whatever you add);`,
+    `${pad}// the kit's helpers only require { id, messages } (ThreadLike).`,
+    `${pad}interface Thread {`,
+    `${pad}  id: string;`,
+    `${pad}  title: string;`,
+    `${pad}  updatedAt: string;`,
+    `${pad}  messages: ChatMessage[];`,
+    `${pad}}`,
+    ``,
+    `${pad}const THREADS_KEY = 'kai-workspace/threads/v1';`,
+    ``,
+    `${pad}// PERSISTENCE IS YOURS. localStorage here is a starting policy, not kit`,
+    `${pad}// behavior: the backend, the quota, what is retained and for how long are`,
+    `${pad}// application decisions. Swap these two functions for your API and nothing`,
+    `${pad}// else in the block changes.`,
+    `${pad}function loadThreads(): Thread[] {`,
+    `${pad}  let raw: string | null = null;`,
+    `${pad}  // Private-mode Safari throws on ACCESS: no storage is a working app with`,
+    `${pad}  // no history, not a crash on first paint.`,
+    `${pad}  try { raw = localStorage.getItem(THREADS_KEY); } catch { return []; }`,
+    `${pad}  if (!raw) return [];`,
+    `${pad}  try {`,
+    `${pad}    const stored: unknown = JSON.parse(raw);`,
+    `${pad}    if (!Array.isArray(stored)) return [];`,
+    `${pad}    return stored.flatMap((record): Thread[] => {`,
+    `${pad}      if (typeof record !== 'object' || record === null) return [];`,
+    `${pad}      const r = record as { id?: unknown; title?: unknown; updatedAt?: unknown; messages?: unknown };`,
+    `${pad}      if (typeof r.id !== 'string' || r.id === '') return [];`,
+    `${pad}      // The kit validates the MESSAGES (the shape it owns — the MessagePart`,
+    `${pad}      // variant list is derived, not hand-typed) and reports the drops;`,
+    `${pad}      // deciding what a drop means is this line, and it is yours.`,
+    `${pad}      const { messages, dropped } = parseStoredThread(r.messages);`,
+    `${pad}      if (dropped.length > 0) console.warn('[threads] dropped unreadable stored entries', dropped);`,
+    `${pad}      return [{`,
+    `${pad}        id: r.id,`,
+    `${pad}        title: typeof r.title === 'string' ? r.title : 'New conversation',`,
+    `${pad}        updatedAt: typeof r.updatedAt === 'string' ? r.updatedAt : new Date().toISOString(),`,
+    `${pad}        messages,`,
+    `${pad}      }];`,
+    `${pad}    });`,
+    `${pad}  } catch {`,
+    `${pad}    // Unparseable history is ignored, loudly enough to notice in dev.`,
+    `${pad}    console.warn('[threads] stored history could not be parsed and was ignored');`,
+    `${pad}    return [];`,
+    `${pad}  }`,
+    `${pad}}`,
+    ``,
+    `${pad}function saveThreads(threads: Thread[]): void {`,
+    `${pad}  // QuotaExceededError is the realistic failure. Warn-and-continue is a`,
+    `${pad}  // POLICY (yours): the alternative — throwing out of a save mid-stream —`,
+    `${pad}  // would take the thread down with it.`,
+    `${pad}  try { localStorage.setItem(THREADS_KEY, JSON.stringify(threads)); }`,
+    `${pad}  catch (err) { console.warn('[threads] history could not be saved', err); }`,
+    `${pad}}`,
+    ``,
+    `${pad}// First line of the first user turn, clipped — the fallback titling policy.`,
+    `${pad}// Titles are what the rail's built-in search matches, so this is also the`,
+    `${pad}// search index; swap in your own (a summariser, a user rename).`,
+    `${pad}function deriveTitle(text: string): string {`,
+    `${pad}  const firstLine = text.trim().split('\\n', 1)[0] ?? '';`,
+    `${pad}  if (firstLine === '') return 'New conversation';`,
+    `${pad}  return firstLine.length > 48 ? firstLine.slice(0, 47) + '…' : firstLine;`,
+    `${pad}}`
+  ];
+}
+const BLOCK_RAIL_NOTE = [
+  `The rail renders the ROWS it is handed (batteries mode) — a view of your`,
+  `records, no message bodies. To own the row markup instead, slot your own`,
+  `<kai-conversation-item> loop as light-DOM children (item mode): data rows`,
+  `stop rendering while any item child is present, and selection still arrives`,
+  `as kai-conversation-select.`
+];
+const BLOCK_RAIL_NOTE_SOLID = [
+  `The rail renders the ROWS it is handed (batteries mode) — a view of your`,
+  `records, no message bodies. To own the row markup instead, pass your own`,
+  `SlottedConversationItem loop via the \`items\` prop (item mode): data rows`,
+  `stop rendering while items are present, and selection still arrives through`,
+  `onSelect.`
+];
+const BLOCK_TARGET_ID_NOTE = [
+  `The thread that was open when the user hit send — not whichever is open`,
+  `when the tokens land. Everything below binds to this id, which is what`,
+  `makes switching away mid-reply safe.`
+];
+const BLOCK_BIND_NOTE = [
+  `bindThreadMessages routes every stream delta to THIS thread, with the`,
+  `reactivity two-halves (new array + new object) handled by the helper.`,
+  `\`touch\` is your policy hook — here it stamps updatedAt on every delta.`
+];
+const BLOCK_SESSIONS_NOTE = [
+  `One in-flight turn per thread: begin() aborts a prior turn on the same`,
+  `thread and hands back its AbortController. Deleting a thread mid-stream is`,
+  `sessions.abort(id) — the aborted turn's late deltas are dropped by the`,
+  `bound sink instead of resurrecting the record.`
+];
+function blockLiveThread(readExpr) {
+  return {
+    open: ({ pad, userMessage }) => [
+      `${pad}// The STORE is the thread: the id-bound sink writes each delta back into`,
+      `${pad}// the record, so every round below re-encodes the live, current value.`,
+      `${pad}setMessages(() => [...${readExpr}, ${userMessage}]);`
+    ],
+    live: readExpr,
+    setter: "setMessages"
+  };
+}
+function slotPlacementFor(tag) {
+  for (const r of surfaceRecipes) {
+    for (const c of r.composition ?? []) {
+      if (c.child === tag) return { parent: c.parent, slot: c.slot };
+    }
+  }
+  return null;
+}
+const ALWAYS_EMITTED_TAG = "kai-chat";
+function slottedInChat(components) {
+  return components.flatMap((tag) => {
+    const placement = slotPlacementFor(tag);
+    if (!placement || placement.parent !== ALWAYS_EMITTED_TAG) return [];
+    return [{ tag, slot: placement.slot }];
+  });
+}
+function railSiblingNote(tag, placement) {
+  const w2 = conversationsWiring();
+  const handler = `on${toPascalCase(w2.event)}`;
+  return [
+    `      {/* NOT WIRED, and NOT SLOTTED — both deliberate, both fixable here.`,
+    `          COMPOSITION: the kit composes this as <${tag} slot="${placement.slot}"> INSIDE`,
+    `          <${placement.parent}>, which renders it into a fixed-width ::part(${placement.slot}) column.`,
+    `          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`,
+    `          reads event.detail.id and calls setMessages with that thread. */}`
+  ];
+}
+function htmlComment(lines, pad) {
+  return lines.map(
+    (l, i) => `${pad}${i === 0 ? "<!-- " : "     "}${l}${i === lines.length - 1 ? " -->" : ""}`
+  );
+}
+function slottedChildMarkup(components, pad, opts) {
+  const w2 = 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
+    // (`chat-thread.tsx`), exposed as a part and nothing more: it does not listen
+    // for the rail's collapse, and it has no responsive behaviour, so a rail that
+    // collapses inside it leaves the column exactly as wide as it was.
+    ...htmlComment(
+      [
+        `SLOTTED, not a sibling: <kai-chat> renders this into its own`,
+        `::part(${s.slot}) aside — a fixed-width column, and that is the whole of`,
+        `what the shell does with it. Collapsing the rail does NOT narrow the`,
+        `column: use the <kai-workspace> layout shell (start aside: startCollapsed /`,
+        `collapseBelow / drawer-below) or your own layout if it has to collapse or resize.${opts.wired ? " src/main.ts drives the rail." : ""}`
+      ],
+      pad
+    ),
+    ...opts.wired ? [] : htmlComment(notWiredNote(s.tag, w2.property, w2.event), pad),
+    `${pad}<${s.tag}${opts.ids ? ` id="${s.tag.replace(/^kai-/, "")}"` : ""} slot="${s.slot}" style="display:block;height:100%"></${s.tag}>`
+  ]);
+}
+function notWiredNote(tag, property, event) {
+  return [
+    `NOT WIRED: <${tag}> needs el.${property} (a JS property — arrays are never`,
+    `attributes) and a ${event} listener that sets kai-chat.messages from your own`,
+    `thread store. The html target emits that wiring in full; ask the`,
+    `component_reference MCP tool for the workspace-chat recipe to see the shape.`
+  ];
+}
+function conversationsWiring() {
+  const edge = surfaceRecipes.flatMap((r) => r.wiring).find((w2) => w2.from === "kai-conversations" && w2.to === "kai-chat" && w2.property === "messages");
+  return { property: "conversations", event: edge?.event ?? "kai-conversation-select" };
+}
 const ATTACHMENT_TAGS = /* @__PURE__ */ new Set(["kai-file-upload", "kai-attachments"]);
 function hasAttachments(components) {
   return components.includes("kai-file-upload") && components.includes("kai-attachments");
@@ -3512,9 +4691,20 @@ function sampleSeedComment(isMock, pad, decl) {
   ];
 }
 function componentTags(components, chatFill) {
+  const block = isWorkspaceBlock(components);
+  const slotted = slottedInChat(components);
+  const slottedTags = new Set(slotted.map((s) => s.tag));
+  const chatSlotted = block ? slotted.filter((s) => !BLOCK_TAGS.has(s.tag)) : slotted;
   const companionTags = components.filter(
-    (t) => t !== "kai-chat" && !MESSAGE_EMBEDDED_TAGS.has(t) && !WORKSPACE_STRUCTURAL_TAGS.has(t) && !(hasAttachments(components) && ATTACHMENT_TAGS.has(t))
+    (t) => t !== "kai-chat" && !MESSAGE_EMBEDDED_TAGS.has(t) && !ARTIFACT_SPLIT_TAGS.has(t) && !(block && BLOCK_TAGS.has(t)) && !slottedTags.has(t) && !(hasAttachments(components) && ATTACHMENT_TAGS.has(t))
   );
+  const chatBlock = (pad) => chatSlotted.length === 0 ? [`${pad}<kai-chat id="chat" suggestion-mode="submit" style="${chatFill}"></kai-chat>`] : [
+    `${pad}<kai-chat id="chat" suggestion-mode="submit" style="${chatFill}">`,
+    // wired: `htmlModule` below emits the property, the two listeners and
+    // the thread map. This is the one target that does.
+    ...slottedChildMarkup(components, `${pad}  `, { wired: true, ids: true }),
+    `${pad}</kai-chat>`
+  ];
   const hasEmbedded = components.some((t) => MESSAGE_EMBEDDED_TAGS.has(t));
   const hasStandaloneCompanions = companionTags.length > 0;
   const lines = [];
@@ -3529,13 +4719,13 @@ function componentTags(components, chatFill) {
       `  </div>`
     );
   }
-  if (isWorkspace(components)) {
+  if (isArtifactSplit(components)) {
     lines.push(
       `  <!-- SCAF-14: workspace split — chat pane left, artifact preview right. -->`,
       `  <!-- kai-resizable needs kai-resizable-item children to render panels. -->`,
       `  <kai-resizable orientation="horizontal" style="display:block;width:100%;height:100%">`,
       `    <kai-resizable-item size="40%" min="240px">`,
-      `      <kai-chat id="chat" suggestion-mode="submit" style="${chatFill}"></kai-chat>`,
+      ...chatBlock("      "),
       `    </kai-resizable-item>`,
       `    <kai-resizable-item min="280px">`,
       `      <!-- Replace src with your artifact URL or set .files for multi-file preview. -->`,
@@ -3544,7 +4734,7 @@ function componentTags(components, chatFill) {
       `  </kai-resizable>`
     );
   } else {
-    lines.push(`  <kai-chat id="chat" suggestion-mode="submit" style="${chatFill}"></kai-chat>`);
+    lines.push(...chatBlock("  "));
   }
   if (hasEmbedded) {
     lines.push(
@@ -3566,12 +4756,35 @@ function componentTags(components, chatFill) {
   if (hasStandaloneCompanions) {
     lines.push(`  <!-- wire data props — see the component_reference MCP tool -->`);
   }
+  if (block) {
+    return [
+      `  <!-- ── The workspace BLOCK: the shell + the rail + your thread records ── -->`,
+      ...htmlComment(
+        [
+          `<kai-workspace> is the chat-agnostic layout shell: header/start/main/`,
+          `end/footer slots, aside resize + collapse, and a mobile drawer below`,
+          `the drawer-below width. It knows nothing about chat.`
+        ],
+        "  "
+      ),
+      `  <kai-workspace drawer-below="720" style="display:block;width:100%;height:100%">`,
+      ...htmlComment([...BLOCK_RAIL_NOTE, `src/main.ts drives the rail.`], "    "),
+      `    <kai-conversations id="conversations" slot="start" style="display:block;height:100%"></kai-conversations>`,
+      `    <!-- Unnamed children project into the shell's MAIN region. -->`,
+      `    <div style="display:flex;flex-direction:column;height:100%;min-height:0">`,
+      ...lines.map((l) => l === "" ? l : `    ${l}`),
+      `    </div>`,
+      `  </kai-workspace>`
+    ].join("\n");
+  }
   return lines.join("\n");
 }
 function htmlModule(ctx, components) {
   const hasEmbedded = components.some((t) => MESSAGE_EMBEDDED_TAGS.has(t));
   const hasSources = components.includes("kai-sources");
   const attachments = hasAttachments(components);
+  const block = isWorkspaceBlock(components);
+  const conversations = !block && slottedInChat(components).some((s) => s.tag === "kai-conversations");
   const attachmentModuleLines = attachments ? [
     ...ATTACHMENT_WIRE_NOTE,
     `//`,
@@ -3616,6 +4829,152 @@ function htmlModule(ctx, components) {
     `  sourcesEl.sources = sampleSources;`,
     ``
   ] : [];
+  const conversationsSetupLines = conversations ? [
+    `  const conversationsEl = document.getElementById('conversations') as KaiConversationsElement;`,
+    `  // Same upgrade rule as <kai-chat>: 'conversations' is an array, so it is a`,
+    `  // PROPERTY, and a property set before the element upgrades is dropped on upgrade.`,
+    `  await customElements.whenDefined('kai-conversations');`,
+    `  // The row shape, DERIVED from the property it is assigned to — it cannot`,
+    `  // drift out of step with the element the way a hand-written copy would.`,
+    `  type Conversation = KaiConversationsElement['conversations'][number];`,
+    `  // Replace this list with your own. Your store owns titles, grouping and order;`,
+    `  // the rail renders what it is given, in the order it is given.`,
+    `  const now = new Date().toISOString();`,
+    `  let conversationRows: Conversation[] = [`,
+    `    { id: 'c1', title: 'New chat', scope: { type: 'document' }, messageCount: 0, lastMessageAt: now, updatedAt: now },`,
+    `  ];`,
+    `  let activeId = conversationRows[0].id;`,
+    `  // The threads you have open, keyed by conversation id. It starts EMPTY on`,
+    `  // purpose: seeding it would put words in the user's mouth. Load a thread`,
+    `  // from your backend in the select handler below and this fills itself.`,
+    `  const threads: Record<string, KaiChatElement['messages']> = {};`,
+    `  // A NEW array per write — the array reference is what notifies.`,
+    `  const showConversations = () => {`,
+    `    conversationsEl.conversations = [...conversationRows];`,
+    `    conversationsEl.activeId = activeId;`,
+    `  };`,
+    `  showConversations();`,
+    ``,
+    `  // The row's title, derived the way every chat app derives it: the first`,
+    `  // thing the user said, on one line. Swap in your own — a summariser, or`,
+    `  // whatever the user renamed the thread to — this is the fallback, not a`,
+    `  // policy. Returns undefined for an empty thread so the row keeps the`,
+    `  // placeholder it was created with rather than losing its label.`,
+    `  const TITLE_MAX = 48;`,
+    `  const titleFrom = (messages: KaiChatElement['messages']): string | undefined => {`,
+    `    const first = messages.find((message) => message.role === 'user');`,
+    `    // flatMap, not filter: a message can open with file parts, and this`,
+    `    // narrows the part union without needing a type predicate.`,
+    `    const text = (first?.parts ?? [])`,
+    `      .flatMap((part) => (part.type === 'text' ? [part.text] : []))`,
+    `      .join(' ')`,
+    `      .replace(/\\s+/g, ' ')`,
+    `      .trim();`,
+    `    if (!text) return undefined;`,
+    `    return text.length > TITLE_MAX ? \`\${text.slice(0, TITLE_MAX).trimEnd()}…\` : text;`,
+    `  };`,
+    ``,
+    `  // The row and the thread are two views of one conversation, and only the`,
+    `  // HOST keeps them in step: <kai-conversations> renders what it is handed and`,
+    `  // reports what was clicked, nothing more. Without this the rail reads`,
+    `  // "New chat / 0 messages / just now" forever, whatever the user does.`,
+    `  const syncActiveRow = () => {`,
+    `    const messages = chat.messages ?? [];`,
+    `    const at = new Date().toISOString();`,
+    `    // BOTH HALVES OF THE CONTRACT, and the rail is silently stale without`,
+    `    // either. A NEW ARRAY is what NOTIFIES — handing the same array back is a`,
+    `    // no-op even when a row inside it changed. A NEW OBJECT for the row that`,
+    `    // changed is what makes it VISIBLE, because the rail renders rows through`,
+    `    // a reference-keyed list and never re-renders a row whose identity held.`,
+    `    // So: map to a fresh row. Never \`row.messageCount = …\` — that mutation`,
+    `    // updates the data and leaves the screen showing the old numbers.`,
+    `    conversationRows = conversationRows.map((row) =>`,
+    `      row.id === activeId`,
+    `        ? {`,
+    `            ...row,`,
+    `            title: titleFrom(messages) ?? row.title,`,
+    `            messageCount: messages.length,`,
+    `            lastMessageAt: at,`,
+    `            updatedAt: at,`,
+    `          }`,
+    `        : row,`,
+    `    );`,
+    `    showConversations();`,
+    `  };`,
+    ``,
+    `  conversationsEl.addEventListener('kai-conversation-select', (event: Event) => {`,
+    `    const { id } = (event as CustomEvent<{ id: string }>).detail;`,
+    `    // Keep what is on screen before switching away from it.`,
+    `    threads[activeId] = chat.messages ?? [];`,
+    `    activeId = id;`,
+    `    // ...and load the one picked. Fetch it here if your store is remote.`,
+    `    chat.messages = [...(threads[id] ?? [])];`,
+    `    showConversations();`,
+    `  });`,
+    `  conversationsEl.addEventListener('kai-new-chat', () => {`,
+    `    // The event carries no detail by design: it IS the whole signal.`,
+    `    threads[activeId] = chat.messages ?? [];`,
+    `    const at = new Date().toISOString();`,
+    `    activeId = \`c\${conversationRows.length + 1}\`;`,
+    `    conversationRows = [`,
+    `      { id: activeId, title: 'New chat', scope: { type: 'document' }, messageCount: 0, lastMessageAt: at, updatedAt: at },`,
+    `      ...conversationRows,`,
+    `    ];`,
+    `    chat.messages = [];`,
+    `    showConversations();`,
+    `  });`,
+    ``
+  ] : [];
+  const blockSetupLines = block ? [
+    `  // ── The block's state: your records + the kit's session/persistence helpers ─`,
+    `  const conversationsEl = document.getElementById('conversations') as KaiConversationsElement;`,
+    `  // Same upgrade rule as <kai-chat>: 'conversations' is an array, so it is a`,
+    `  // PROPERTY, and a property set before the element upgrades is dropped on upgrade.`,
+    `  await customElements.whenDefined('kai-conversations');`,
+    ``,
+    `  let threads: Thread[] = loadThreads();`,
+    `  // null means a DRAFT: "New chat" was pressed and nothing is stored yet. A`,
+    `  // record is created on its first turn, so the rail never fills with empties.`,
+    `  let activeId: string | null = threads[0]?.id ?? null;`,
+    ...BLOCK_SESSIONS_NOTE.map((l) => `  // ${l}`),
+    `  const sessions = createThreadSessions(() => showWorkspace());`,
+    `  // The save scheduler: the debounce/flush MECHANICS are the kit's; the delay,`,
+    `  // the save target and what a failed save means are YOURS (see saveThreads).`,
+    `  const saver = createSaveScheduler(saveThreads, { delayMs: 250 });`,
+    `  // Flush the pending write when the tab closes mid-debounce (or mid-stream).`,
+    `  window.addEventListener('beforeunload', () => saver.flush());`,
+    `  // Every write goes through this: schedule the save and re-project the views.`,
+    `  const setThreads = (updater: (prev: Thread[]) => Thread[]): void => {`,
+    `    threads = updater(threads);`,
+    `    saver.schedule(threads);`,
+    `    showWorkspace();`,
+    `  };`,
+    ``,
+    `  // Project the records onto the elements. NEW arrays per write — the array`,
+    `  // reference is what notifies (reactivity-two-halves; the changed objects`,
+    `  // inside come from the helpers' folds).`,
+    `  function showWorkspace(): void {`,
+    `    // The rail's row shape is a VIEW of your record — titles and counts, no`,
+    `    // message bodies. The rail renders the array in the order it is given.`,
+    `    conversationsEl.conversations = threads.map((t) => ({ id: t.id, title: t.title, messageCount: t.messages.length, updatedAt: t.updatedAt }));`,
+    `    conversationsEl.activeId = activeId ?? undefined;`,
+    `    chat.messages = [...(threads.find((t) => t.id === activeId)?.messages ?? [])];`,
+    `    chat.loading = activeId !== null && sessions.isStreaming(activeId);`,
+    `  }`,
+    `  showWorkspace();`,
+    ``,
+    `  conversationsEl.addEventListener('kai-conversation-select', (event: Event) => {`,
+    `    activeId = (event as CustomEvent<{ id: string }>).detail.id;`,
+    `    showWorkspace();`,
+    `  });`,
+    `  conversationsEl.addEventListener('kai-new-chat', () => {`,
+    `    // The event carries no detail by design: it IS the whole signal. A DRAFT,`,
+    `    // not a record — see activeId above.`,
+    `    activeId = null;`,
+    `    showWorkspace();`,
+    `  });`,
+    ``
+  ] : [];
   const modelLines = ctx.defaultModel ? [
     `// SCAF-8: change this model id to another id THIS PROVIDER accepts.`,
     `const model = '${ctx.defaultModel}';`,
@@ -3633,9 +4992,13 @@ function htmlModule(ctx, components) {
   const elementTypes = [
     "KaiChatElement",
     ...hasSources ? ["KaiSourcesElement"] : [],
-    ...attachments ? ["KaiAttachmentsElement"] : []
+    ...attachments ? ["KaiAttachmentsElement"] : [],
+    // Same rule again: only when the rail is really on this surface. It types the
+    // property assignments AND supplies the row type, so it is used twice over.
+    // The block drives the same element from its own thread store.
+    ...conversations || block ? ["KaiConversationsElement"] : []
   ].join(", ");
-  const annotatesChatMessage = !ctx.emitToolLoop;
+  const annotatesChatMessage = !ctx.emitToolLoop || block;
   const head = [
     `// src/main.ts — the page's logic, in a module YOUR build type-checks.`,
     `//`,
@@ -3654,13 +5017,15 @@ function htmlModule(ctx, components) {
       cards: ctx.emitCards,
       cardTools: ctx.cardProvider !== null,
       mock: ctx.isMock,
-      attachments
+      attachments,
+      workspaceBlock: block
     }),
     `import '@kitn.ai/ui/theme.tokens.css';  // compiled token defaults; use theme.css only for Tailwind-source apps`,
     ``,
     ...ctx.isMock ? [...mockResponderInit(), ``] : [],
     ...modelLines,
     ...attachmentModuleLines,
+    ...block ? [...blockThreadStoreLines(""), ``] : [],
     ...cardsLines,
     ...toolsLines,
     ...runnerLines,
@@ -3677,7 +5042,9 @@ function htmlModule(ctx, components) {
     ...cardPropLines,
     ...seedLines,
     ...sourcesSetupLines,
-    ...attachmentSetupLines
+    ...attachmentSetupLines,
+    ...conversationsSetupLines,
+    ...blockSetupLines
   ];
   const listenerOpen = [
     `  chat.addEventListener('kai-submit', async (event: Event) => {`,
@@ -3690,33 +5057,62 @@ function htmlModule(ctx, components) {
     `// A <script type="module"> is deferred, so the DOM is already parsed here.`,
     `void init();`
   ];
+  const blockPrelude = block ? [
+    ...BLOCK_TARGET_ID_NOTE.map((l) => `// ${l}`),
+    `const targetId = activeId ?? crypto.randomUUID();`,
+    `// The record is born on its first turn — with YOUR title policy.`,
+    `setThreads((prev) => prev.some((t) => t.id === targetId)`,
+    `  ? prev`,
+    `  : [{ id: targetId, title: deriveTitle(value), updatedAt: new Date().toISOString(), messages: [] }, ...prev]);`,
+    `activeId = targetId;`,
+    ...BLOCK_BIND_NOTE.map((l) => `// ${l}`),
+    `const setMessages = bindThreadMessages<Thread>(setThreads, targetId, {`,
+    `  touch: (t) => ({ ...t, updatedAt: new Date().toISOString() }),`,
+    `});`,
+    `const controller = sessions.begin(targetId);`,
+    `showWorkspace();`
+  ] : [];
   return [
     ...head,
     `  // messages is a JS PROPERTY (objects can't be HTML attributes)`,
     ...listenerOpen,
     realStreamBody({
       pad: "    ",
-      read: "chat.messages",
-      commitSet: (expr) => `chat.messages = ${expr};`,
-      setterAdapter: "(fn) => { chat.messages = fn(chat.messages); }",
-      setLoading: (v2) => `chat.loading = ${v2};`,
+      read: block ? `(threads.find((t) => t.id === targetId)?.messages ?? [])` : "chat.messages",
+      commitSet: block ? (expr) => `setMessages(() => ${expr});` : (expr) => `chat.messages = ${expr};`,
+      setterAdapter: block ? "setMessages" : "(fn) => { chat.messages = fn(chat.messages); }",
+      setLoading: block ? (v2) => v2 === "true" ? `// loading for THIS thread now derives from the sessions map (showWorkspace).` : `sessions.end(targetId, controller); showWorkspace();` : (v2) => `chat.loading = ${v2};`,
       bodyPayload: realBodyPayload({ defaultModel: ctx.defaultModel, tools: ctx.emitTools }),
       strictRoles: true,
       toolLoop: ctx.emitToolLoop,
       cards: ctx.emitCards,
-      thread: liveThreadBinding(
+      thread: block ? blockLiveThread(`(threads.find((t) => t.id === targetId)?.messages ?? [])`) : liveThreadBinding(
         "chat.messages",
         "(fn) => { chat.messages = fn(chat.messages); }",
         "chat.messages ?? []"
       ),
       mock: ctx.isMock,
+      ...block ? { fetchSignal: "controller.signal", afterValue: blockPrelude } : {},
+      // ONE call site, in the `finally`, and deliberately not also on submit. The
+      // finally sees the WHOLE turn — the user's message and the assistant's — so
+      // one call cannot leave the row disagreeing with the thread, and it runs on
+      // the error path too, where the user's message is on the thread regardless.
+      // The cost is that the title appears when the reply settles rather than the
+      // instant the user hits send; call it right after `chat.messages = history`
+      // as well if you want it sooner.
+      afterTurn: conversations ? [`syncActiveRow();  // keep the rail's row in step with the thread`] : [],
       ...attachments ? {
         filesExpr: "files",
-        afterValue: attachmentTurnLines({
-          stagedExpr: "staged",
-          clear: ["staged = [];", "showStaged();"],
-          fromSubmitEvent: true
-        })
+        // The attachment capture must read the staging list before anything
+        // clears it, so it precedes the block's prelude.
+        afterValue: [
+          ...attachmentTurnLines({
+            stagedExpr: "staged",
+            clear: ["staged = [];", "showStaged();"],
+            fromSubmitEvent: true
+          }),
+          ...blockPrelude
+        ]
       } : {}
     }),
     ...footer
@@ -3755,14 +5151,17 @@ function toPascalCase(tag) {
 function renderJsx(components, ctx, framework) {
   const { p, emptyHint, suggestions, isMock, defaultModel, emitTools, emitToolLoop } = ctx;
   const hasEmbedded = components.some((t) => MESSAGE_EMBEDDED_TAGS.has(t));
-  const workspace = isWorkspace(components);
-  const renderableTags = components.filter((t) => !MESSAGE_EMBEDDED_TAGS.has(t));
+  const workspace = isArtifactSplit(components);
+  const block = isWorkspaceBlock(components);
+  const renderableTags = [
+    .../* @__PURE__ */ new Set([ALWAYS_EMITTED_TAG, ...components.filter((t) => !MESSAGE_EMBEDDED_TAGS.has(t))])
+  ];
   const importTags = workspace ? [.../* @__PURE__ */ new Set([...renderableTags.filter((t) => t !== "kai-resizable"), "kai-resizable", "kai-resizable-item"])] : renderableTags;
   const wrapperNames = importTags.map(toPascalCase);
   const importList = wrapperNames.join(", ");
   const attachments = hasAttachments(components);
   const standaloneCompanionTags = components.filter(
-    (t) => t !== "kai-chat" && !MESSAGE_EMBEDDED_TAGS.has(t) && !WORKSPACE_STRUCTURAL_TAGS.has(t) && !(attachments && ATTACHMENT_TAGS.has(t))
+    (t) => t !== "kai-chat" && !MESSAGE_EMBEDDED_TAGS.has(t) && !ARTIFACT_SPLIT_TAGS.has(t) && !(block && BLOCK_TAGS.has(t)) && !(attachments && ATTACHMENT_TAGS.has(t))
   );
   const companionJsxLines = [];
   if (hasEmbedded) {
@@ -3777,6 +5176,8 @@ function renderJsx(components, ctx, framework) {
         `      {/* Replace sampleSources with your real data. */}`,
         `      <Sources sources={sampleSources} />`
       );
+    } else if (slotPlacementFor(t)) {
+      companionJsxLines.push(...railSiblingNote(t, slotPlacementFor(t)), `      <${toPascalCase(t)} />`);
     } else {
       companionJsxLines.push(`      {/* wire data props — see the component_reference MCP tool */}`);
       companionJsxLines.push(`      <${toPascalCase(t)} />`);
@@ -3819,13 +5220,54 @@ function renderJsx(components, ctx, framework) {
   } : {};
   const submitParamType = attachments ? "CustomEvent<{ value: string; attachments: AttachmentData[] }>" : "CustomEvent<{ value: string }>";
   const mockInit = isMock ? mockResponderInit() : [];
-  const sampleMessagesInit = [
+  const sampleMessagesInit = block ? [
+    `  // ── The block's state: your records + the kit's session/persistence helpers ─`,
+    `  const [threads, setThreads] = useState<Thread[]>(loadThreads);`,
+    `  // null means a DRAFT: "New chat" was pressed and nothing is stored yet. A`,
+    `  // record is created on its first turn, so the rail never fills with empties.`,
+    `  const [activeId, setActiveId] = useState<string | null>(threads[0]?.id ?? null);`,
+    `  // One id per in-flight reply — a stream keeps running when you switch away,`,
+    `  // so this cannot be a single boolean.`,
+    `  const [streamingIds, setStreamingIds] = useState<string[]>([]);`,
+    ...BLOCK_SESSIONS_NOTE.map((l) => `  // ${l}`),
+    `  const [sessions] = useState(() => createThreadSessions(setStreamingIds));`,
+    `  // The save scheduler: the debounce/flush MECHANICS are the kit's; the delay,`,
+    `  // the save target and what a failed save means are YOURS (see saveThreads).`,
+    `  const [saver] = useState(() => createSaveScheduler(saveThreads, { delayMs: 250 }));`,
+    `  useEffect(() => { saver.schedule(threads); }, [saver, threads]);`,
+    `  useEffect(() => {`,
+    `    // Flush the pending write when the tab closes mid-debounce (or mid-stream).`,
+    `    const flush = () => saver.flush();`,
+    `    window.addEventListener('beforeunload', flush);`,
+    `    return () => window.removeEventListener('beforeunload', flush);`,
+    `  }, [saver]);`,
+    ``,
+    `  const active = threads.find((t) => t.id === activeId) ?? null;`,
+    `  const messages = active?.messages ?? NO_MESSAGES;`,
+    `  const loading = activeId !== null && streamingIds.includes(activeId);`,
+    `  // The rail's row shape is a VIEW of your record — titles and counts, no`,
+    `  // message bodies. Newest-first is your ordering; the rail renders the array`,
+    `  // in the order it is given.`,
+    `  const rows = threads.map((t) => ({ id: t.id, title: t.title, messageCount: t.messages.length, updatedAt: t.updatedAt }));`
+  ].join("\n") : [
     ...hasEmbedded ? sampleSeedComment(isMock, "  ", (literal) => [
       `const sampleMessages: ChatMessage[] = [${literal}];`,
       `const [messages, setMessages] = useState<ChatMessage[]>(sampleMessages);`
     ]) : [],
     `  const [messages, setMessages] = useState<ChatMessage[]>([]);`
   ].join("\n");
+  const blockModuleInit = block ? [
+    // One joined entry so the JSX branches' blank-line filter cannot squash
+    // the store's own paragraph breaks.
+    [
+      `/** A stable reference for the empty thread. \`messages\` is diffed by`,
+      ` *  reference, so a fresh \`[]\` every render would re-notify for nothing. */`,
+      `const NO_MESSAGES: ChatMessage[] = [];`,
+      ``,
+      ...blockThreadStoreLines("")
+    ].join("\n")
+  ] : [];
+  const loadingInit = block ? [] : [`  const [loading, setLoading] = useState(false);`];
   const sampleSourcesInit = standaloneCompanionTags.includes("kai-sources") ? [
     `  // Replace sampleSources with your real source data.`,
     `  const sampleSources = [`,
@@ -3840,21 +5282,109 @@ function renderJsx(components, ctx, framework) {
   const cardsInit = ctx.emitCards ? cardRegistryLines("") : [];
   const cardProps = (pad) => ctx.emitCards ? [`${pad}cardTypes={cards.tags}`, `${pad}cardSchemas={cards.validationSchemas}`] : [];
   const cardPropsNote = (pad) => ctx.emitCards ? jsxComment(CARD_PROP_COMMENT, pad) : [];
+  const blockPrelude = block ? [
+    ...BLOCK_TARGET_ID_NOTE.map((l) => `// ${l}`),
+    `const targetId = activeId ?? crypto.randomUUID();`,
+    `// The record is born on its first turn — with YOUR title policy.`,
+    `setThreads((prev) => prev.some((t) => t.id === targetId)`,
+    `  ? prev`,
+    `  : [{ id: targetId, title: deriveTitle(value), updatedAt: new Date().toISOString(), messages: [] }, ...prev]);`,
+    `setActiveId(targetId);`,
+    ...BLOCK_BIND_NOTE.map((l) => `// ${l}`),
+    `const setMessages = bindThreadMessages<Thread>(setThreads, targetId, {`,
+    `  touch: (t) => ({ ...t, updatedAt: new Date().toISOString() }),`,
+    `});`,
+    `const controller = sessions.begin(targetId);`
+  ] : [];
+  const blockReactThread = {
+    open: ({ pad, userMessage }) => [
+      `${pad}// THE TURN OWNS THE THREAD (same rule as the single-thread scaffold): the`,
+      `${pad}// loop below re-encodes it every round, and React state cannot be read`,
+      `${pad}// back mid-turn. setMessages (the id-bound sink) just projects it.`,
+      `${pad}let thread: ChatMessage[] = [...(threads.find((t) => t.id === targetId)?.messages ?? []), ${userMessage}];`,
+      `${pad}const set: SetMessages = (fn) => { thread = fn(thread); setMessages(() => thread); };`,
+      `${pad}setMessages(() => thread);`
+    ],
+    live: "thread",
+    setter: "set"
+  };
   const onSubmitBody = realStreamBody({
     pad: "    ",
-    read: "messages",
-    commitSet: (expr) => `setMessages(${expr});`,
-    // useState's setter IS a SetMessages: both are (updater) => void.
+    read: block ? `(threads.find((t) => t.id === targetId)?.messages ?? [])` : "messages",
+    commitSet: block ? (expr) => `setMessages(() => ${expr});` : (expr) => `setMessages(${expr});`,
+    // useState's setter IS a SetMessages: both are (updater) => void — and in
+    // block mode the id-bound sink from bindThreadMessages is one too.
     setterAdapter: "setMessages",
-    setLoading: (v2) => `setLoading(${v2});`,
+    setLoading: block ? (v2) => v2 === "true" ? `// loading for THIS thread now derives from the sessions map (streamingIds).` : `sessions.end(targetId, controller);` : (v2) => `setLoading(${v2});`,
     bodyPayload: realBodyPayload({ defaultModel, tools: emitTools }),
     strictRoles: true,
     toolLoop: emitToolLoop,
     cards: ctx.emitCards,
-    thread: REACT_THREAD,
+    thread: block ? blockReactThread : REACT_THREAD,
     mock: isMock,
-    ...attachmentSubmitOpts
+    ...block ? { fetchSignal: "controller.signal" } : {},
+    ...attachmentSubmitOpts,
+    ...block ? {
+      afterValue: [
+        ...attachmentSubmitOpts.afterValue ?? [],
+        ...blockPrelude
+      ]
+    } : {}
   });
+  const chatJsx = (pad) => [
+    ...cardPropsNote(pad),
+    `${pad}<Chat`,
+    `${pad}  messages={messages}`,
+    `${pad}  loading={loading}`,
+    `${pad}  suggestions={suggestions}`,
+    `${pad}  suggestionMode="submit"`,
+    ...cardProps(`${pad}  `),
+    `${pad}  onSubmit={onSubmit}`,
+    `${pad}  style={{ ${jsxStyle(p.chatFill)} }}`,
+    `${pad}/>`
+  ];
+  const splitJsx = [
+    `      {/* SCAF-14: workspace split — chat pane left, artifact preview right. */}`,
+    `      {/* Resizable needs ResizableItem children to render panels. */}`,
+    `      <Resizable orientation="horizontal" style={{ display: 'block', width: '100%', height: '100%' }}>`,
+    `        <ResizableItem size="40%" min="240px">`,
+    ...chatJsx("          "),
+    `        </ResizableItem>`,
+    `        <ResizableItem min="280px">`,
+    `          {/* Replace src + files with your real artifact data (files is required: array/object props are never optional attributes on a kai-* element). */}`,
+    `          <Artifact src="https://example.com" files={[{ path: 'index.html', url: 'https://example.com' }]} style={{ width: '100%', height: '100%' }} />`,
+    `        </ResizableItem>`,
+    `      </Resizable>`
+  ];
+  const mainJsx = [
+    ...attachmentJsx ? [attachmentJsx] : [],
+    ...workspace ? [...splitJsx, companions] : [...chatJsx("      "), companions]
+  ];
+  const surfaceJsx = block ? [
+    `      {/* ── The workspace BLOCK: the shell + the rail + your thread records ── */}`,
+    `      {/* <Workspace> is the chat-agnostic layout shell (header/start/main/end/`,
+    `          footer slots, aside resize + collapse, a mobile drawer below`,
+    `          drawerBelow px). It knows nothing about chat. */}`,
+    `      <Workspace drawerBelow={720} style={{ display: 'block', width: '100%', height: '100%' }}>`,
+    ...jsxComment(BLOCK_RAIL_NOTE, "        "),
+    `        {/* The React wrappers forward no slot prop, so a plain div carries the`,
+    `            slot attribute into the shell's start aside. */}`,
+    `        <div slot="start" style={{ height: '100%' }}>`,
+    `          {/* New chat = a DRAFT (activeId null): the record appears on the first turn. */}`,
+    `          <Conversations`,
+    `            conversations={rows}`,
+    `            activeId={activeId ?? undefined}`,
+    `            onConversationSelect={(e) => setActiveId(e.detail.id)}`,
+    `            onNewChat={() => setActiveId(null)}`,
+    `            style={{ display: 'block', height: '100%' }}`,
+    `          />`,
+    `        </div>`,
+    `        {/* Unnamed children project into the shell's MAIN region. */}`,
+    `        <div style={{ display: 'flex', flexDirection: 'column', height: '100%', minHeight: 0 }}>`,
+    ...indentEmitted(mainJsx, "    "),
+    `        </div>`,
+    `      </Workspace>`
+  ] : mainJsx;
   const useClientDirective = framework === "next" ? [`'use client';`, ``] : [];
   if (framework === "next") {
     const dynamicImports = wrapperNames.map(
@@ -3864,7 +5394,7 @@ function renderJsx(components, ctx, framework) {
     return [
       // 'use client' must be the very first line for Next.js App Router.
       ...useClientDirective,
-      `import { useState } from 'react';`,
+      `import { ${block ? "useEffect, useState" : "useState"} } from 'react';`,
       `import dynamic from 'next/dynamic';`,
       // The adapter is pure parsing + pure state; both entries are SSR-import-safe,
       // so they stay static imports even though the ELEMENTS have to be dynamic.
@@ -3875,7 +5405,8 @@ function renderJsx(components, ctx, framework) {
         cards: ctx.emitCards,
         cardTools: ctx.cardProvider !== null,
         mock: isMock,
-        attachments
+        attachments,
+        workspaceBlock: block
       }),
       `import '@kitn.ai/ui/theme.tokens.css';  // compiled token defaults; use theme.css only for Tailwind-source apps`,
       `// <kai-*> are client-only custom elements (the server has no customElements`,
@@ -3889,10 +5420,11 @@ function renderJsx(components, ctx, framework) {
       ...mockInit,
       ``,
       ...attachmentModuleInit,
+      ...blockModuleInit,
       ...cardsInit,
       `export default function App() {`,
       sampleMessagesInit,
-      `  const [loading, setLoading] = useState(false);`,
+      ...loadingInit,
       `  const suggestions = ${jsArray(suggestions)};`,
       ...attachmentStateInit ? [attachmentStateInit] : [],
       ...sampleSourcesInit ? [sampleSourcesInit] : [],
@@ -3906,46 +5438,7 @@ function renderJsx(components, ctx, framework) {
       ``,
       `  return (`,
       `    <div style={{ ${jsxStyle(p.style)} }}>`,
-      ...attachmentJsx ? [attachmentJsx] : [],
-      ...workspace ? [
-        `      {/* SCAF-14: workspace split — chat pane left, artifact preview right. */}`,
-        `      {/* Resizable needs ResizableItem children to render panels. */}`,
-        `      <Resizable orientation="horizontal" style={{ display: 'block', width: '100%', height: '100%' }}>`,
-        `        <ResizableItem size="40%" min="240px">`,
-        ...cardPropsNote("          "),
-        `          <Chat`,
-        `            messages={messages}`,
-        `            loading={loading}`,
-        `            suggestions={suggestions}`,
-        `            suggestionMode="submit"`,
-        ...cardProps("            "),
-        `            onSubmit={onSubmit}`,
-        `            style={{ ${jsxStyle(p.chatFill)} }}`,
-        `          />`,
-        `        </ResizableItem>`,
-        `        <ResizableItem min="280px">`,
-        `          {/* Replace src + files with your real artifact data (files is required: array/object props are never optional attributes on a kai-* element). */}`,
-        `          <Artifact src="https://example.com" files={[{ path: 'index.html', url: 'https://example.com' }]} style={{ width: '100%', height: '100%' }} />`,
-        `        </ResizableItem>`,
-        `      </Resizable>`,
-        // Standalone companions are siblings of the SPLIT, not of the chat:
-        // the split owns chat + artifact, and a sources panel or a voice input
-        // belongs beside it. Dropping them here is what the workspace branch
-        // used to do — see WORKSPACE_STRUCTURAL_TAGS.
-        companions
-      ] : [
-        ...cardPropsNote("      "),
-        `      <Chat`,
-        `        messages={messages}`,
-        `        loading={loading}`,
-        `        suggestions={suggestions}`,
-        `        suggestionMode="submit"`,
-        ...cardProps("        "),
-        `        onSubmit={onSubmit}`,
-        `        style={{ ${jsxStyle(p.chatFill)} }}`,
-        `      />`,
-        companions
-      ],
+      ...surfaceJsx,
       `    </div>`,
       `  );`,
       `}`
@@ -3958,7 +5451,7 @@ function renderJsx(components, ctx, framework) {
     // (1) REQUIRED: registers <kai-*> — the react wrappers do NOT auto-register.
     // Must come BEFORE importing the wrappers, or <kai-chat> renders empty.
     `import '@kitn.ai/ui/elements';  // registers <kai-*> — required, must come first`,
-    `import { useState } from 'react';`,
+    `import { ${block ? "useEffect, useState" : "useState"} } from 'react';`,
     `import { ${importList} } from '@kitn.ai/ui/react';`,
     ...wireImportLines({
       typed: true,
@@ -3967,7 +5460,8 @@ function renderJsx(components, ctx, framework) {
       cards: ctx.emitCards,
       cardTools: ctx.cardProvider !== null,
       mock: isMock,
-      attachments
+      attachments,
+      workspaceBlock: block
     }),
     `import '@kitn.ai/ui/theme.tokens.css';  // compiled token defaults; use theme.css only for Tailwind-source apps`,
     ``,
@@ -3977,10 +5471,11 @@ function renderJsx(components, ctx, framework) {
     ...mockInit,
     ``,
     ...attachmentModuleInit,
+    ...blockModuleInit,
     ...cardsInit,
     `export default function App() {`,
     sampleMessagesInit,
-    `  const [loading, setLoading] = useState(false);`,
+    ...loadingInit,
     `  const suggestions = ${jsArray(suggestions)};`,
     ...attachmentStateInit ? [attachmentStateInit] : [],
     ...sampleSourcesInit ? [sampleSourcesInit] : [],
@@ -3994,43 +5489,7 @@ function renderJsx(components, ctx, framework) {
     ``,
     `  return (`,
     `    <div style={{ ${jsxStyle(p.style)} }}>`,
-    ...attachmentJsx ? [attachmentJsx] : [],
-    ...workspace ? [
-      `      {/* SCAF-14: workspace split — chat pane left, artifact preview right. */}`,
-      `      {/* Resizable needs ResizableItem children to render panels. */}`,
-      `      <Resizable orientation="horizontal" style={{ display: 'block', width: '100%', height: '100%' }}>`,
-      `        <ResizableItem size="40%" min="240px">`,
-      ...cardPropsNote("          "),
-      `          <Chat`,
-      `            messages={messages}`,
-      `            loading={loading}`,
-      `            suggestions={suggestions}`,
-      `            suggestionMode="submit"`,
-      ...cardProps("            "),
-      `            onSubmit={onSubmit}`,
-      `            style={{ ${jsxStyle(p.chatFill)} }}`,
-      `          />`,
-      `        </ResizableItem>`,
-      `        <ResizableItem min="280px">`,
-      `          {/* Replace src + files with your real artifact data (files is required: array/object props are never optional attributes on a kai-* element). */}`,
-      `          <Artifact src="https://example.com" files={[{ path: 'index.html', url: 'https://example.com' }]} style={{ width: '100%', height: '100%' }} />`,
-      `        </ResizableItem>`,
-      `      </Resizable>`,
-      // Siblings of the SPLIT — see the same line in the other JSX branch.
-      companions
-    ] : [
-      ...cardPropsNote("      "),
-      `      <Chat`,
-      `        messages={messages}`,
-      `        loading={loading}`,
-      `        suggestions={suggestions}`,
-      `        suggestionMode="submit"`,
-      ...cardProps("        "),
-      `        onSubmit={onSubmit}`,
-      `        style={{ ${jsxStyle(p.chatFill)} }}`,
-      `      />`,
-      companions
-    ],
+    ...surfaceJsx,
     `    </div>`,
     `  );`,
     `}`
@@ -4038,10 +5497,13 @@ function renderJsx(components, ctx, framework) {
 }
 function renderVue(components, ctx) {
   const { p, emptyHint, suggestions, isMock, defaultModel, emitTools, emitToolLoop } = ctx;
-  const workspace = isWorkspace(components);
+  const workspace = isArtifactSplit(components);
+  const block = isWorkspaceBlock(components);
   const attachments = hasAttachments(components);
+  const slottedTags = new Set(slottedInChat(components).map((s) => s.tag));
+  const vueSlotted = (pad) => block ? [] : slottedChildMarkup(components, pad, { wired: false, ids: false });
   const standaloneCompanionTags = components.filter(
-    (t) => t !== "kai-chat" && !MESSAGE_EMBEDDED_TAGS.has(t) && !WORKSPACE_STRUCTURAL_TAGS.has(t) && !(attachments && ATTACHMENT_TAGS.has(t))
+    (t) => t !== "kai-chat" && !MESSAGE_EMBEDDED_TAGS.has(t) && !ARTIFACT_SPLIT_TAGS.has(t) && !(block && BLOCK_TAGS.has(t)) && !slottedTags.has(t) && !(attachments && ATTACHMENT_TAGS.has(t))
   );
   const hasEmbedded = components.some((t) => MESSAGE_EMBEDDED_TAGS.has(t));
   const companionLines = [];
@@ -4096,19 +5558,41 @@ function renderVue(components, ctx) {
       fromSubmitEvent: true
     })
   } : {};
+  const blockRead = `(threads.value.find((t) => t.id === targetId)?.messages ?? [])`;
+  const blockPrelude = block ? [
+    ...BLOCK_TARGET_ID_NOTE.map((l) => `// ${l}`),
+    `const targetId = activeId.value ?? crypto.randomUUID();`,
+    `// The record is born on its first turn — with YOUR title policy.`,
+    `setThreads((prev) => prev.some((t) => t.id === targetId)`,
+    `  ? prev`,
+    `  : [{ id: targetId, title: deriveTitle(value), updatedAt: new Date().toISOString(), messages: [] }, ...prev]);`,
+    `activeId.value = targetId;`,
+    ...BLOCK_BIND_NOTE.map((l) => `// ${l}`),
+    `const setMessages = bindThreadMessages<Thread>(setThreads, targetId, {`,
+    `  touch: (t) => ({ ...t, updatedAt: new Date().toISOString() }),`,
+    `});`,
+    `const controller = sessions.begin(targetId);`
+  ] : [];
   const onSubmitBody = realStreamBody({
     pad: "    ",
-    read: "messages.value",
-    commitSet: (expr) => `messages.value = ${expr};`,
-    setterAdapter: "(fn) => { messages.value = fn(messages.value); }",
-    setLoading: (v2) => `loading.value = ${v2};`,
+    read: block ? blockRead : "messages.value",
+    commitSet: block ? (expr) => `setMessages(() => ${expr});` : (expr) => `messages.value = ${expr};`,
+    setterAdapter: block ? "setMessages" : "(fn) => { messages.value = fn(messages.value); }",
+    setLoading: block ? (v2) => v2 === "true" ? `// loading for THIS thread now derives from the sessions map (streamingIds).` : `sessions.end(targetId, controller);` : (v2) => `loading.value = ${v2};`,
     bodyPayload: realBodyPayload({ defaultModel, tools: emitTools }),
     strictRoles: true,
     toolLoop: emitToolLoop,
     cards: ctx.emitCards,
-    thread: liveThreadBinding("messages.value", "(fn) => { messages.value = fn(messages.value); }"),
+    thread: block ? blockLiveThread(blockRead) : liveThreadBinding("messages.value", "(fn) => { messages.value = fn(messages.value); }"),
     mock: isMock,
-    ...attachmentSubmitOpts
+    ...block ? { fetchSignal: "controller.signal" } : {},
+    ...attachmentSubmitOpts,
+    ...block ? {
+      afterValue: [
+        ...attachmentSubmitOpts.afterValue ?? [],
+        ...blockPrelude
+      ]
+    } : {}
   });
   const mockInit = isMock ? mockResponderInit() : [];
   const modelInit = defaultModel ? [
@@ -4119,7 +5603,39 @@ function renderVue(components, ctx) {
   const cardPropAssign = ctx.emitCards ? [`cardTypes: cards.tags`, `cardSchemas: cards.validationSchemas`] : [];
   const toolsLines = emitTools ? toolSchemaLines("", ctx.cardProvider) : [];
   const runnerLines = emitToolLoop ? toolRunnerLines("") : [];
-  const sampleSeed = [
+  const sampleSeed = block ? [
+    `// ── The block's state: your records + the kit's session/persistence helpers ──`,
+    `const threads = ref<Thread[]>(loadThreads());`,
+    `// null means a DRAFT: "New chat" was pressed and nothing is stored yet. A`,
+    `// record is created on its first turn, so the rail never fills with empties.`,
+    `const activeId = ref<string | null>(threads.value[0]?.id ?? null);`,
+    `// One id per in-flight reply — a stream keeps running when you switch away.`,
+    `const streamingIds = ref<string[]>([]);`,
+    ...BLOCK_SESSIONS_NOTE.map((l) => `// ${l}`),
+    `const sessions = createThreadSessions((ids) => { streamingIds.value = ids; });`,
+    `// The save scheduler: the debounce/flush MECHANICS are the kit's; the delay,`,
+    `// the save target and what a failed save means are YOURS (see saveThreads).`,
+    `const saver = createSaveScheduler(saveThreads, { delayMs: 250 });`,
+    `watch(threads, () => saver.schedule(threads.value));`,
+    `// Every write goes through this — a NEW array per write is what notifies.`,
+    `const setThreads = (updater: (prev: Thread[]) => Thread[]): void => {`,
+    `  threads.value = updater(threads.value);`,
+    `};`,
+    `const active = computed(() => threads.value.find((t) => t.id === activeId.value) ?? null);`,
+    `const messages = computed(() => active.value?.messages ?? []);`,
+    `const loading = computed(() => { const id = activeId.value; return id !== null && streamingIds.value.includes(id); });`,
+    `// The rail's row shape is a VIEW of your record — titles and counts, no`,
+    `// message bodies. The rail renders the array in the order it is given.`,
+    `const rows = computed(() => threads.value.map((t) => ({ id: t.id, title: t.title, messageCount: t.messages.length, updatedAt: t.updatedAt })));`,
+    ``,
+    `function onSelect(event: Event) {`,
+    `  activeId.value = (event as CustomEvent<{ id: string }>).detail.id;`,
+    `}`,
+    `function onNewChat() {`,
+    `  // A DRAFT, not a record: it becomes a thread on its first turn.`,
+    `  activeId.value = null;`,
+    `}`
+  ] : [
     ...hasEmbedded ? sampleSeedComment(isMock, "", (literal) => [
       `const messages = ref<ChatMessage[]>([${literal}]);`
     ]) : [],
@@ -4136,7 +5652,7 @@ function renderVue(components, ctx) {
     `  if (el) el.sources = sampleSources;`,
     `});`
   ] : [];
-  const vueImports = `import { ref, onMounted } from 'vue';`;
+  const vueImports = block ? `import { computed, onMounted, ref, watch } from 'vue';` : `import { ref, onMounted } from 'vue';`;
   const workspaceTemplate = workspace ? [
     `    <!-- SCAF-14: workspace split — chat pane left, artifact preview right. -->`,
     `    <!-- kai-resizable needs kai-resizable-item children to render panels. -->`,
@@ -4149,7 +5665,9 @@ function renderVue(components, ctx) {
     `          suggestion-mode="submit"`,
     `          style="${p.chatFill}"`,
     `          @kai-submit="onSubmit"`,
-    `        ></kai-chat>`,
+    `        >`,
+    ...vueSlotted("          "),
+    `        </kai-chat>`,
     `      </kai-resizable-item>`,
     `      <kai-resizable-item min="280px">`,
     `        <!-- Replace src with your artifact URL or set .files for multi-file preview. -->`,
@@ -4166,7 +5684,9 @@ function renderVue(components, ctx) {
     `      suggestion-mode="submit"`,
     `      style="${p.chatFill}"`,
     `      @kai-submit="onSubmit"`,
-    `    ></kai-chat>`,
+    `    >`,
+    ...vueSlotted("      "),
+    `    </kai-chat>`,
     companions
   ];
   return [
@@ -4184,16 +5704,18 @@ function renderVue(components, ctx) {
       cards: ctx.emitCards,
       cardTools: ctx.cardProvider !== null,
       mock: isMock,
-      attachments
+      attachments,
+      workspaceBlock: block
     }),
     `import '@kitn.ai/ui/theme.tokens.css';  // compiled token defaults; use theme.css only for Tailwind-source apps`,
     vueImports,
     ``,
     ...mockInit,
     ``,
+    ...block ? [blockThreadStoreLines("").join("\n"), ``] : [],
     ...cardsInit,
     ...sampleSeed,
-    `const loading = ref(false);`,
+    ...block ? [] : [`const loading = ref(false);`],
     `const suggestions = ${jsArray(suggestions)};`,
     ...modelInit,
     ...toolsLines,
@@ -4209,6 +5731,14 @@ function renderVue(components, ctx) {
     ...ctx.emitCards ? CARD_PROP_COMMENT.map((l) => `  ${l}`) : [],
     `  const el = document.querySelector('kai-chat');`,
     `  if (el) Object.assign(el, { messages: messages.value, loading: loading.value, suggestions${cardPropAssign.length ? `, ${cardPropAssign.join(", ")}` : ""} });`,
+    ...block ? [
+      `  // The rail's array props follow the same upgrade rule.`,
+      `  await customElements.whenDefined('kai-conversations');`,
+      `  const rail = document.querySelector('kai-conversations');`,
+      `  if (rail) Object.assign(rail, { conversations: rows.value, activeId: activeId.value ?? undefined });`,
+      `  // Flush the pending write when the tab closes mid-debounce (or mid-stream).`,
+      `  window.addEventListener('beforeunload', saver.flush);`
+    ] : [],
     `});`,
     ``,
     `async function onSubmit(e: ${attachments ? "CustomEvent<{ value: string; attachments: AttachmentData[] }>" : "CustomEvent<{ value: string }>"}) {`,
@@ -4218,18 +5748,49 @@ function renderVue(components, ctx) {
     ``,
     `<template>`,
     `  <div style="${p.style}">`,
-    ...attachmentTemplate ? [attachmentTemplate] : [],
-    ...workspaceTemplate,
+    ...block ? [
+      `    <!-- ── The workspace BLOCK: the shell + the rail + your thread records ── -->`,
+      ...htmlComment(
+        [
+          `<kai-workspace> is the chat-agnostic layout shell: header/start/main/`,
+          `end/footer slots, aside resize + collapse, and a mobile drawer below`,
+          `the drawer-below width. It knows nothing about chat.`
+        ],
+        "    "
+      ),
+      `    <kai-workspace drawer-below="720" style="display:block;width:100%;height:100%">`,
+      ...htmlComment(BLOCK_RAIL_NOTE, "      "),
+      `      <!-- New chat = a DRAFT (activeId null): the record appears on the first turn. -->`,
+      `      <kai-conversations`,
+      `        slot="start"`,
+      `        :conversations.prop="rows"`,
+      `        :activeId.prop="activeId ?? undefined"`,
+      `        style="display:block;height:100%"`,
+      `        @kai-conversation-select="onSelect"`,
+      `        @kai-new-chat="onNewChat"`,
+      `      />`,
+      `      <!-- Unnamed children project into the shell's MAIN region. -->`,
+      `      <div style="display:flex;flex-direction:column;height:100%;min-height:0">`,
+      ...indentEmitted(
+        [...attachmentTemplate ? [attachmentTemplate] : [], ...workspaceTemplate],
+        "    "
+      ),
+      `      </div>`,
+      `    </kai-workspace>`
+    ] : [...attachmentTemplate ? [attachmentTemplate] : [], ...workspaceTemplate],
     `  </div>`,
     `</template>`
   ].filter((l) => l !== "").join("\n");
 }
 function renderSvelte(components, ctx) {
   const { p, emptyHint, suggestions, isMock, defaultModel, emitTools, emitToolLoop } = ctx;
-  const workspace = isWorkspace(components);
+  const workspace = isArtifactSplit(components);
+  const block = isWorkspaceBlock(components);
   const attachments = hasAttachments(components);
+  const slottedTags = new Set(slottedInChat(components).map((s) => s.tag));
+  const svelteSlotted = (pad) => block ? [] : slottedChildMarkup(components, pad, { wired: false, ids: false });
   const standaloneCompanionTags = components.filter(
-    (t) => t !== "kai-chat" && !MESSAGE_EMBEDDED_TAGS.has(t) && !WORKSPACE_STRUCTURAL_TAGS.has(t) && !(attachments && ATTACHMENT_TAGS.has(t))
+    (t) => t !== "kai-chat" && !MESSAGE_EMBEDDED_TAGS.has(t) && !ARTIFACT_SPLIT_TAGS.has(t) && !(block && BLOCK_TAGS.has(t)) && !slottedTags.has(t) && !(attachments && ATTACHMENT_TAGS.has(t))
   );
   const hasEmbedded = components.some((t) => MESSAGE_EMBEDDED_TAGS.has(t));
   const hasSourcesCompanion = standaloneCompanionTags.includes("kai-sources");
@@ -4257,19 +5818,41 @@ function renderSvelte(components, ctx) {
       fromSubmitEvent: true
     })
   } : {};
+  const blockRead = `(threads.find((t) => t.id === targetId)?.messages ?? [])`;
+  const blockPrelude = block ? [
+    ...BLOCK_TARGET_ID_NOTE.map((l) => `// ${l}`),
+    `const targetId = activeId ?? crypto.randomUUID();`,
+    `// The record is born on its first turn — with YOUR title policy.`,
+    `setThreads((prev) => prev.some((t) => t.id === targetId)`,
+    `  ? prev`,
+    `  : [{ id: targetId, title: deriveTitle(value), updatedAt: new Date().toISOString(), messages: [] }, ...prev]);`,
+    `activeId = targetId;`,
+    ...BLOCK_BIND_NOTE.map((l) => `// ${l}`),
+    `const setMessages = bindThreadMessages<Thread>(setThreads, targetId, {`,
+    `  touch: (t) => ({ ...t, updatedAt: new Date().toISOString() }),`,
+    `});`,
+    `const controller = sessions.begin(targetId);`
+  ] : [];
   const onSubmitBody = realStreamBody({
     pad: "    ",
-    read: "messages",
-    commitSet: (expr) => `messages = ${expr};`,
-    setterAdapter: "(fn) => { messages = fn(messages); }",
-    setLoading: (v2) => `loading = ${v2};`,
+    read: block ? blockRead : "messages",
+    commitSet: block ? (expr) => `setMessages(() => ${expr});` : (expr) => `messages = ${expr};`,
+    setterAdapter: block ? "setMessages" : "(fn) => { messages = fn(messages); }",
+    setLoading: block ? (v2) => v2 === "true" ? `// loading for THIS thread now derives from the sessions map (streamingIds).` : `sessions.end(targetId, controller);` : (v2) => `loading = ${v2};`,
     bodyPayload: realBodyPayload({ defaultModel, tools: emitTools }),
     strictRoles: true,
     toolLoop: emitToolLoop,
     cards: ctx.emitCards,
-    thread: liveThreadBinding("messages", "(fn) => { messages = fn(messages); }"),
+    thread: block ? blockLiveThread(blockRead) : liveThreadBinding("messages", "(fn) => { messages = fn(messages); }"),
     mock: isMock,
-    ...attachmentSubmitOpts
+    ...block ? { fetchSignal: "controller.signal" } : {},
+    ...attachmentSubmitOpts,
+    ...block ? {
+      afterValue: [
+        ...attachmentSubmitOpts.afterValue ?? [],
+        ...blockPrelude
+      ]
+    } : {}
   });
   const mockInit = isMock ? mockResponderInit("  ") : [];
   const modelInit = defaultModel ? [
@@ -4280,7 +5863,46 @@ function renderSvelte(components, ctx) {
   const cardPropEffect = ctx.emitCards ? ` chatEl.cardTypes = cards.tags; chatEl.cardSchemas = cards.validationSchemas;` : "";
   const toolsLines = emitTools ? toolSchemaLines("  ", ctx.cardProvider) : [];
   const runnerLines = emitToolLoop ? toolRunnerLines("  ") : [];
-  const sampleMessagesInit = [
+  const sampleMessagesInit = block ? [
+    `  // ── The block's state: your records + the kit's session/persistence helpers ─`,
+    `  // $state.raw for the same reason messages was: the kit's contract is a NEW`,
+    `  // array reference per write, which is exactly what raw state tracks.`,
+    `  let threads = $state.raw<Thread[]>(loadThreads());`,
+    `  // null means a DRAFT: "New chat" was pressed and nothing is stored yet. A`,
+    `  // record is created on its first turn, so the rail never fills with empties.`,
+    `  let activeId = $state<string | null>(threads[0]?.id ?? null);`,
+    `  // One id per in-flight reply — a stream keeps running when you switch away.`,
+    `  let streamingIds = $state.raw<string[]>([]);`,
+    ...BLOCK_SESSIONS_NOTE.map((l) => `  // ${l}`),
+    `  const sessions = createThreadSessions((ids) => { streamingIds = ids; });`,
+    `  // The save scheduler: the debounce/flush MECHANICS are the kit's; the delay,`,
+    `  // the save target and what a failed save means are YOURS (see saveThreads).`,
+    `  const saver = createSaveScheduler(saveThreads, { delayMs: 250 });`,
+    `  $effect(() => { saver.schedule(threads); });`,
+    `  // Every write goes through this — a NEW array per write is what notifies.`,
+    `  const setThreads = (updater: (prev: Thread[]) => Thread[]): void => {`,
+    `    threads = updater(threads);`,
+    `  };`,
+    `  const active = $derived(threads.find((t) => t.id === activeId) ?? null);`,
+    `  const messages = $derived(active?.messages ?? []);`,
+    `  const loading = $derived.by(() => { const id = activeId; return id !== null && streamingIds.includes(id); });`,
+    `  // The rail's row shape is a VIEW of your record — titles and counts, no`,
+    `  // message bodies. The rail renders the array in the order it is given.`,
+    `  const rows = $derived(threads.map((t) => ({ id: t.id, title: t.title, messageCount: t.messages.length, updatedAt: t.updatedAt })));`,
+    `  // \`bind:this\` writes to this binding, so under runes it must be $state.`,
+    `  let railEl = $state<KaiConversationsElement | undefined>(undefined);`,
+    `  $effect(() => {`,
+    `    if (railEl && defined) { railEl.conversations = rows; railEl.activeId = activeId ?? undefined; }`,
+    `  });`,
+    ``,
+    `  function onSelect(e: CustomEvent<{ id: string }>) {`,
+    `    activeId = e.detail.id;`,
+    `  }`,
+    `  function onNewChat() {`,
+    `    // A DRAFT, not a record: it becomes a thread on its first turn.`,
+    `    activeId = null;`,
+    `  }`
+  ] : [
     ...hasEmbedded ? sampleSeedComment(isMock, "  ", (literal) => [
       `let messages = $state.raw<ChatMessage[]>([${literal}]);`
     ]) : [],
@@ -4327,7 +5949,9 @@ function renderSvelte(components, ctx) {
     `  <!-- kai-resizable needs kai-resizable-item children to render panels. -->`,
     `  <kai-resizable orientation="horizontal" style="display:block;width:100%;height:100%">`,
     `    <kai-resizable-item size="40%" min="240px">`,
-    `      <kai-chat bind:this={chatEl} suggestion-mode="submit" style="${p.chatFill}" onkai-submit={onSubmit}></kai-chat>`,
+    `      <kai-chat bind:this={chatEl} suggestion-mode="submit" style="${p.chatFill}" onkai-submit={onSubmit}>`,
+    ...svelteSlotted("        "),
+    `      </kai-chat>`,
     `    </kai-resizable-item>`,
     `    <kai-resizable-item min="280px">`,
     `      <!-- Replace src with your artifact URL or set .files for multi-file preview. -->`,
@@ -4337,7 +5961,9 @@ function renderSvelte(components, ctx) {
     // Siblings of the SPLIT — see the same line in renderJsx.
     companionLines
   ] : [
-    `  <kai-chat bind:this={chatEl} suggestion-mode="submit" style="${p.chatFill}" onkai-submit={onSubmit}></kai-chat>`,
+    `  <kai-chat bind:this={chatEl} suggestion-mode="submit" style="${p.chatFill}" onkai-submit={onSubmit}>`,
+    ...svelteSlotted("    "),
+    `  </kai-chat>`,
     companionLines
   ];
   return [
@@ -4354,6 +5980,7 @@ function renderSvelte(components, ctx) {
     // on every archetype without kai-sources.
     `  import type { ${[
       "KaiChatElement",
+      ...block ? ["KaiConversationsElement"] : [],
       ...hasSourcesCompanion ? ["KaiSourcesElement"] : [],
       ...attachments ? ["KaiAttachmentsElement"] : []
     ].join(", ")} } from '@kitn.ai/ui/elements';`,
@@ -4364,21 +5991,36 @@ function renderSvelte(components, ctx) {
       cards: ctx.emitCards,
       cardTools: ctx.cardProvider !== null,
       mock: isMock,
-      attachments
+      attachments,
+      workspaceBlock: block
     }),
     `  import '@kitn.ai/ui/theme.tokens.css';  // compiled token defaults; use theme.css only for Tailwind-source apps`,
     `  import { onMount } from 'svelte';`,
     ...mockInit,
+    ...block ? [blockThreadStoreLines("  ").join("\n"), ``] : [],
     `  // \`bind:this\` writes to this binding, so under runes it must be $state.`,
     `  let chatEl = $state<KaiChatElement | undefined>(undefined);`,
     `  // SCAF-15: kai-* register via an async dynamic import (SSR-safety). Gate the`,
     `  // property $effect on the upgrade so the first application isn't dropped`,
     `  // (props set on a not-yet-upgraded element are lost on upgrade).`,
     `  let defined = $state(false);`,
-    `  onMount(async () => { await customElements.whenDefined('kai-chat'); defined = true; });`,
+    ...block ? [
+      `  onMount(() => {`,
+      `    void Promise.all([`,
+      `      customElements.whenDefined('kai-chat'),`,
+      `      customElements.whenDefined('kai-conversations'),`,
+      `    ]).then(() => { defined = true; });`,
+      `    // Flush the pending write when the tab closes mid-debounce (or mid-stream).`,
+      `    const flush = () => saver.flush();`,
+      `    window.addEventListener('beforeunload', flush);`,
+      `    return () => window.removeEventListener('beforeunload', flush);`,
+      `  });`
+    ] : [
+      `  onMount(async () => { await customElements.whenDefined('kai-chat'); defined = true; });`
+    ],
     ...sourcesEl,
     ...sampleMessagesInit,
-    `  let loading = $state(false);`,
+    ...block ? [] : [`  let loading = $state(false);`],
     `  const suggestions: string[] = ${jsArray(suggestions)};`,
     ...modelInit,
     ...cardsInit,
@@ -4398,22 +6040,49 @@ function renderSvelte(components, ctx) {
     `<\/script>`,
     ``,
     `<div style="${p.style}">`,
-    ...attachmentMarkup,
-    ...workspaceMarkup,
+    ...block ? [
+      `  <!-- ── The workspace BLOCK: the shell + the rail + your thread records ── -->`,
+      ...htmlComment(
+        [
+          `<kai-workspace> is the chat-agnostic layout shell: header/start/main/`,
+          `end/footer slots, aside resize + collapse, and a mobile drawer below`,
+          `the drawer-below width. It knows nothing about chat.`
+        ],
+        "  "
+      ),
+      `  <kai-workspace drawer-below="720" style="display:block;width:100%;height:100%">`,
+      ...htmlComment(BLOCK_RAIL_NOTE, "    "),
+      `    <!-- New chat = a DRAFT (activeId null): the record appears on the first turn. -->`,
+      `    <kai-conversations`,
+      `      bind:this={railEl}`,
+      `      slot="start"`,
+      `      style="display:block;height:100%"`,
+      `      onkai-conversation-select={onSelect}`,
+      `      onkai-new-chat={onNewChat}`,
+      `    ></kai-conversations>`,
+      `    <!-- Unnamed children project into the shell's MAIN region. -->`,
+      `    <div style="display:flex;flex-direction:column;height:100%;min-height:0">`,
+      ...indentEmitted([...attachmentMarkup, ...workspaceMarkup], "    "),
+      `    </div>`,
+      `  </kai-workspace>`
+    ] : [...attachmentMarkup, ...workspaceMarkup],
     `</div>`
   ].filter((l, i, arr) => !(l === "" && arr[i - 1] === "" && i === arr.length - 1)).join("\n");
 }
 function renderTanstackStart(components, ctx) {
   const { p, emptyHint, suggestions, isMock, defaultModel, emitTools, emitToolLoop } = ctx;
   const hasEmbedded = components.some((t) => MESSAGE_EMBEDDED_TAGS.has(t));
-  const workspace = isWorkspace(components);
-  const renderableTags = components.filter((t) => !MESSAGE_EMBEDDED_TAGS.has(t));
+  const workspace = isArtifactSplit(components);
+  const block = isWorkspaceBlock(components);
+  const renderableTags = [
+    .../* @__PURE__ */ new Set([ALWAYS_EMITTED_TAG, ...components.filter((t) => !MESSAGE_EMBEDDED_TAGS.has(t))])
+  ];
   const importTags = workspace ? [.../* @__PURE__ */ new Set([...renderableTags.filter((t) => t !== "kai-resizable"), "kai-resizable", "kai-resizable-item"])] : renderableTags;
   const wrapperNames = importTags.map(toPascalCase);
   const importList = wrapperNames.join(", ");
   const attachments = hasAttachments(components);
   const standaloneCompanionTags = components.filter(
-    (t) => t !== "kai-chat" && !MESSAGE_EMBEDDED_TAGS.has(t) && !WORKSPACE_STRUCTURAL_TAGS.has(t) && !(attachments && ATTACHMENT_TAGS.has(t))
+    (t) => t !== "kai-chat" && !MESSAGE_EMBEDDED_TAGS.has(t) && !ARTIFACT_SPLIT_TAGS.has(t) && !(block && BLOCK_TAGS.has(t)) && !(attachments && ATTACHMENT_TAGS.has(t))
   );
   const companionJsxLines = [];
   if (hasEmbedded) {
@@ -4428,6 +6097,8 @@ function renderTanstackStart(components, ctx) {
         `      {/* Replace sampleSources with your real data. */}`,
         `      <Sources sources={sampleSources} />`
       );
+    } else if (slotPlacementFor(t)) {
+      companionJsxLines.push(...railSiblingNote(t, slotPlacementFor(t)), `      <${toPascalCase(t)} />`);
     } else {
       companionJsxLines.push(`      {/* wire data props — see the component_reference MCP tool */}`);
       companionJsxLines.push(`      <${toPascalCase(t)} />`);
@@ -4470,13 +6141,52 @@ function renderTanstackStart(components, ctx) {
   } : {};
   const submitParamType = attachments ? "CustomEvent<{ value: string; attachments: AttachmentData[] }>" : "CustomEvent<{ value: string }>";
   const mockInit = isMock ? mockResponderInit() : [];
-  const sampleMessagesInit = [
+  const sampleMessagesInit = block ? [
+    `  // ── The block's state: your records + the kit's session/persistence helpers ─`,
+    `  const [threads, setThreads] = useState<Thread[]>(loadThreads);`,
+    `  // null means a DRAFT: "New chat" was pressed and nothing is stored yet. A`,
+    `  // record is created on its first turn, so the rail never fills with empties.`,
+    `  const [activeId, setActiveId] = useState<string | null>(threads[0]?.id ?? null);`,
+    `  // One id per in-flight reply — a stream keeps running when you switch away,`,
+    `  // so this cannot be a single boolean.`,
+    `  const [streamingIds, setStreamingIds] = useState<string[]>([]);`,
+    ...BLOCK_SESSIONS_NOTE.map((l) => `  // ${l}`),
+    `  const [sessions] = useState(() => createThreadSessions(setStreamingIds));`,
+    `  // The save scheduler: the debounce/flush MECHANICS are the kit's; the delay,`,
+    `  // the save target and what a failed save means are YOURS (see saveThreads).`,
+    `  const [saver] = useState(() => createSaveScheduler(saveThreads, { delayMs: 250 }));`,
+    `  useEffect(() => { saver.schedule(threads); }, [saver, threads]);`,
+    `  useEffect(() => {`,
+    `    // Flush the pending write when the tab closes mid-debounce (or mid-stream).`,
+    `    const flush = () => saver.flush();`,
+    `    window.addEventListener('beforeunload', flush);`,
+    `    return () => window.removeEventListener('beforeunload', flush);`,
+    `  }, [saver]);`,
+    ``,
+    `  const active = threads.find((t) => t.id === activeId) ?? null;`,
+    `  const messages = active?.messages ?? NO_MESSAGES;`,
+    `  const loading = activeId !== null && streamingIds.includes(activeId);`,
+    `  // The rail's row shape is a VIEW of your record — titles and counts, no`,
+    `  // message bodies. Newest-first is your ordering; the rail renders the array`,
+    `  // in the order it is given.`,
+    `  const rows = threads.map((t) => ({ id: t.id, title: t.title, messageCount: t.messages.length, updatedAt: t.updatedAt }));`
+  ].join("\n") : [
     ...hasEmbedded ? sampleSeedComment(isMock, "  ", (literal) => [
       `const sampleMessages: ChatMessage[] = [${literal}];`,
       `const [messages, setMessages] = useState<ChatMessage[]>(sampleMessages);`
     ]) : [],
     `  const [messages, setMessages] = useState<ChatMessage[]>([]);`
   ].join("\n");
+  const blockModuleInit = block ? [
+    [
+      `/** A stable reference for the empty thread. \`messages\` is diffed by`,
+      ` *  reference, so a fresh \`[]\` every render would re-notify for nothing. */`,
+      `const NO_MESSAGES: ChatMessage[] = [];`,
+      ``,
+      ...blockThreadStoreLines("")
+    ].join("\n")
+  ] : [];
+  const loadingInit = block ? [] : [`  const [loading, setLoading] = useState(false);`];
   const sampleSourcesInit = standaloneCompanionTags.includes("kai-sources") ? [
     `  // Replace sampleSources with your real source data.`,
     `  const sampleSources = [`,
@@ -4491,20 +6201,54 @@ function renderTanstackStart(components, ctx) {
   const cardsInit = ctx.emitCards ? cardRegistryLines("") : [];
   const cardProps = (pad) => ctx.emitCards ? [`${pad}cardTypes={cards.tags}`, `${pad}cardSchemas={cards.validationSchemas}`] : [];
   const cardPropsNote = (pad) => ctx.emitCards ? jsxComment(CARD_PROP_COMMENT, pad) : [];
+  const blockPrelude = block ? [
+    ...BLOCK_TARGET_ID_NOTE.map((l) => `// ${l}`),
+    `const targetId = activeId ?? crypto.randomUUID();`,
+    `// The record is born on its first turn — with YOUR title policy.`,
+    `setThreads((prev) => prev.some((t) => t.id === targetId)`,
+    `  ? prev`,
+    `  : [{ id: targetId, title: deriveTitle(value), updatedAt: new Date().toISOString(), messages: [] }, ...prev]);`,
+    `setActiveId(targetId);`,
+    ...BLOCK_BIND_NOTE.map((l) => `// ${l}`),
+    `const setMessages = bindThreadMessages<Thread>(setThreads, targetId, {`,
+    `  touch: (t) => ({ ...t, updatedAt: new Date().toISOString() }),`,
+    `});`,
+    `const controller = sessions.begin(targetId);`
+  ] : [];
+  const blockReactThread = {
+    open: ({ pad, userMessage }) => [
+      `${pad}// THE TURN OWNS THE THREAD (same rule as the single-thread scaffold): the`,
+      `${pad}// loop below re-encodes it every round, and React state cannot be read`,
+      `${pad}// back mid-turn. setMessages (the id-bound sink) just projects it.`,
+      `${pad}let thread: ChatMessage[] = [...(threads.find((t) => t.id === targetId)?.messages ?? []), ${userMessage}];`,
+      `${pad}const set: SetMessages = (fn) => { thread = fn(thread); setMessages(() => thread); };`,
+      `${pad}setMessages(() => thread);`
+    ],
+    live: "thread",
+    setter: "set"
+  };
   const onSubmitBody = realStreamBody({
     pad: "    ",
-    read: "messages",
-    commitSet: (expr) => `setMessages(${expr});`,
-    // useState's setter IS a SetMessages: both are (updater) => void.
+    read: block ? `(threads.find((t) => t.id === targetId)?.messages ?? [])` : "messages",
+    commitSet: block ? (expr) => `setMessages(() => ${expr});` : (expr) => `setMessages(${expr});`,
+    // useState's setter IS a SetMessages: both are (updater) => void — and in
+    // block mode the id-bound sink from bindThreadMessages is one too.
     setterAdapter: "setMessages",
-    setLoading: (v2) => `setLoading(${v2});`,
+    setLoading: block ? (v2) => v2 === "true" ? `// loading for THIS thread now derives from the sessions map (streamingIds).` : `sessions.end(targetId, controller);` : (v2) => `setLoading(${v2});`,
     bodyPayload: realBodyPayload({ defaultModel, tools: emitTools }),
     strictRoles: true,
     toolLoop: emitToolLoop,
     cards: ctx.emitCards,
-    thread: REACT_THREAD,
+    thread: block ? blockReactThread : REACT_THREAD,
     mock: isMock,
-    ...attachmentSubmitOpts
+    ...block ? { fetchSignal: "controller.signal" } : {},
+    ...attachmentSubmitOpts,
+    ...block ? {
+      afterValue: [
+        ...attachmentSubmitOpts.afterValue ?? [],
+        ...blockPrelude
+      ]
+    } : {}
   });
   const filePathNote = [
     `// TanStack Start route file — save as: src/routes/chat.tsx`,
@@ -4520,11 +6264,65 @@ function renderTanstackStart(components, ctx) {
     `// server function: src/routes/api/chat.ts with server.handlers.POST — block (2).`,
     ``
   ];
+  const chatJsx = (pad) => [
+    ...cardPropsNote(pad),
+    `${pad}<Chat`,
+    `${pad}  messages={messages}`,
+    `${pad}  loading={loading}`,
+    `${pad}  suggestions={suggestions}`,
+    `${pad}  suggestionMode="submit"`,
+    ...cardProps(`${pad}  `),
+    `${pad}  onSubmit={onSubmit}`,
+    `${pad}  style={{ ${jsxStyle(p.chatFill)} }}`,
+    `${pad}/>`
+  ];
+  const splitJsx = [
+    `      {/* SCAF-14: workspace split — chat pane left, artifact preview right. */}`,
+    `      {/* Resizable needs ResizableItem children to render panels. */}`,
+    `      <Resizable orientation="horizontal" style={{ display: 'block', width: '100%', height: '100%' }}>`,
+    `        <ResizableItem size="40%" min="240px">`,
+    ...chatJsx("          "),
+    `        </ResizableItem>`,
+    `        <ResizableItem min="280px">`,
+    `          {/* Replace src + files with your real artifact data (files is required: array/object props are never optional attributes on a kai-* element). */}`,
+    `          <Artifact src="https://example.com" files={[{ path: 'index.html', url: 'https://example.com' }]} style={{ width: '100%', height: '100%' }} />`,
+    `        </ResizableItem>`,
+    `      </Resizable>`
+  ];
+  const mainJsx = [
+    ...attachmentJsx ? [attachmentJsx] : [],
+    ...workspace ? [...splitJsx, companions] : [...chatJsx("      "), companions]
+  ];
+  const surfaceJsx = block ? [
+    `      {/* ── The workspace BLOCK: the shell + the rail + your thread records ── */}`,
+    `      {/* <Workspace> is the chat-agnostic layout shell (header/start/main/end/`,
+    `          footer slots, aside resize + collapse, a mobile drawer below`,
+    `          drawerBelow px). It knows nothing about chat. */}`,
+    `      <Workspace drawerBelow={720} style={{ display: 'block', width: '100%', height: '100%' }}>`,
+    ...jsxComment(BLOCK_RAIL_NOTE, "        "),
+    `        {/* The React wrappers forward no slot prop, so a plain div carries the`,
+    `            slot attribute into the shell's start aside. */}`,
+    `        <div slot="start" style={{ height: '100%' }}>`,
+    `          {/* New chat = a DRAFT (activeId null): the record appears on the first turn. */}`,
+    `          <Conversations`,
+    `            conversations={rows}`,
+    `            activeId={activeId ?? undefined}`,
+    `            onConversationSelect={(e) => setActiveId(e.detail.id)}`,
+    `            onNewChat={() => setActiveId(null)}`,
+    `            style={{ display: 'block', height: '100%' }}`,
+    `          />`,
+    `        </div>`,
+    `        {/* Unnamed children project into the shell's MAIN region. */}`,
+    `        <div style={{ display: 'flex', flexDirection: 'column', height: '100%', minHeight: 0 }}>`,
+    ...indentEmitted(mainJsx, "    "),
+    `        </div>`,
+    `      </Workspace>`
+  ] : mainJsx;
   return [
     ...filePathNote,
     // TanStack Start uses @tanstack/react-router's createFileRoute
     `import { createFileRoute } from '@tanstack/react-router'`,
-    `import { useState } from 'react'`,
+    `import { ${block ? "useEffect, useState" : "useState"} } from 'react'`,
     // Elements registration: the library is SSR-import-safe; top-level import is safe here
     `import '@kitn.ai/ui/elements';  // registers <kai-*> — required, must come first`,
     `import { ${importList} } from '@kitn.ai/ui/react'`,
@@ -4535,7 +6333,8 @@ function renderTanstackStart(components, ctx) {
       cards: ctx.emitCards,
       cardTools: ctx.cardProvider !== null,
       mock: isMock,
-      attachments
+      attachments,
+      workspaceBlock: block
     }),
     `import '@kitn.ai/ui/theme.tokens.css'  // compiled token defaults`,
     ``,
@@ -4544,6 +6343,7 @@ function renderTanstackStart(components, ctx) {
     ...mockInit,
     ``,
     ...attachmentModuleInit,
+    ...blockModuleInit,
     ...cardsInit,
     `// ssr: false keeps the Solid-based web component client-only.`,
     `// Server HTML for /chat omits <kai-chat> → no hydration mismatch.`,
@@ -4554,7 +6354,7 @@ function renderTanstackStart(components, ctx) {
     ``,
     `function ChatPage() {`,
     sampleMessagesInit,
-    `  const [loading, setLoading] = useState(false);`,
+    ...loadingInit,
     `  const suggestions = ${jsArray(suggestions)};`,
     ...attachmentStateInit ? [attachmentStateInit] : [],
     ...sampleSourcesInit ? [sampleSourcesInit] : [],
@@ -4568,43 +6368,7 @@ function renderTanstackStart(components, ctx) {
     ``,
     `  return (`,
     `    <main style={{ ${jsxStyle(p.style)} }}>`,
-    ...attachmentJsx ? [attachmentJsx] : [],
-    ...workspace ? [
-      `      {/* SCAF-14: workspace split — chat pane left, artifact preview right. */}`,
-      `      {/* Resizable needs ResizableItem children to render panels. */}`,
-      `      <Resizable orientation="horizontal" style={{ display: 'block', width: '100%', height: '100%' }}>`,
-      `        <ResizableItem size="40%" min="240px">`,
-      ...cardPropsNote("          "),
-      `          <Chat`,
-      `            messages={messages}`,
-      `            loading={loading}`,
-      `            suggestions={suggestions}`,
-      `            suggestionMode="submit"`,
-      ...cardProps("            "),
-      `            onSubmit={onSubmit}`,
-      `            style={{ ${jsxStyle(p.chatFill)} }}`,
-      `          />`,
-      `        </ResizableItem>`,
-      `        <ResizableItem min="280px">`,
-      `          {/* Replace src + files with your real artifact data (files is required: array/object props are never optional attributes on a kai-* element). */}`,
-      `          <Artifact src="https://example.com" files={[{ path: 'index.html', url: 'https://example.com' }]} style={{ width: '100%', height: '100%' }} />`,
-      `        </ResizableItem>`,
-      `      </Resizable>`,
-      // Siblings of the SPLIT — see the same line in the other JSX branch.
-      companions
-    ] : [
-      ...cardPropsNote("      "),
-      `      <Chat`,
-      `        messages={messages}`,
-      `        loading={loading}`,
-      `        suggestions={suggestions}`,
-      `        suggestionMode="submit"`,
-      ...cardProps("        "),
-      `        onSubmit={onSubmit}`,
-      `        style={{ ${jsxStyle(p.chatFill)} }}`,
-      `      />`,
-      companions
-    ],
+    ...surfaceJsx,
     `    </main>`,
     `  );`,
     `}`
@@ -4612,10 +6376,12 @@ function renderTanstackStart(components, ctx) {
 }
 function renderAngular(components, ctx) {
   const { p, emptyHint, suggestions, isMock, defaultModel, emitTools, emitToolLoop } = ctx;
-  const workspace = isWorkspace(components);
+  const workspace = isArtifactSplit(components);
+  const block = isWorkspaceBlock(components);
   const attachments = hasAttachments(components);
+  const slottedTags = new Set(slottedInChat(components).map((s) => s.tag));
   const standaloneCompanionTags = components.filter(
-    (t) => t !== "kai-chat" && !MESSAGE_EMBEDDED_TAGS.has(t) && !WORKSPACE_STRUCTURAL_TAGS.has(t) && !(attachments && ATTACHMENT_TAGS.has(t))
+    (t) => t !== "kai-chat" && !MESSAGE_EMBEDDED_TAGS.has(t) && !ARTIFACT_SPLIT_TAGS.has(t) && !(block && BLOCK_TAGS.has(t)) && !slottedTags.has(t) && !(attachments && ATTACHMENT_TAGS.has(t))
   );
   const hasEmbedded = components.some((t) => MESSAGE_EMBEDDED_TAGS.has(t));
   const hasSourcesCompanion = standaloneCompanionTags.includes("kai-sources");
@@ -4679,19 +6445,41 @@ function renderAngular(components, ctx) {
   const read = "this.messages()";
   const commit = (value) => `this.messages.set(${value});`;
   const setter = "(fn) => this.messages.set(fn(this.messages()))";
+  const blockRead = `(this.threads().find((t) => t.id === targetId)?.messages ?? [])`;
+  const blockPrelude = block ? [
+    ...BLOCK_TARGET_ID_NOTE.map((l) => `// ${l}`),
+    `const targetId = this.activeId() ?? crypto.randomUUID();`,
+    `// The record is born on its first turn — with YOUR title policy.`,
+    `this.setThreads((prev) => prev.some((t) => t.id === targetId)`,
+    `  ? prev`,
+    `  : [{ id: targetId, title: deriveTitle(value), updatedAt: new Date().toISOString(), messages: [] }, ...prev]);`,
+    `this.activeId.set(targetId);`,
+    ...BLOCK_BIND_NOTE.map((l) => `// ${l}`),
+    `const setMessages = bindThreadMessages<Thread>(this.setThreads, targetId, {`,
+    `  touch: (t) => ({ ...t, updatedAt: new Date().toISOString() }),`,
+    `});`,
+    `const controller = this.sessions.begin(targetId);`
+  ] : [];
   const onSubmitBody = realStreamBody({
     pad: "    ",
-    read,
-    commitSet: (expr) => commit(expr),
-    setterAdapter: setter,
-    setLoading: (v2) => `this.loading.set(${v2});`,
+    read: block ? blockRead : read,
+    commitSet: block ? (expr) => `setMessages(() => ${expr});` : (expr) => commit(expr),
+    setterAdapter: block ? "setMessages" : setter,
+    setLoading: block ? (v2) => v2 === "true" ? `// loading for THIS thread now derives from the sessions map (streamingIds).` : `this.sessions.end(targetId, controller);` : (v2) => `this.loading.set(${v2});`,
     bodyPayload: realBodyPayload({ defaultModel, tools: emitTools }),
     strictRoles: true,
     toolLoop: emitToolLoop,
     cards: ctx.emitCards,
-    thread: accessorThreadBinding(read, commit, setter),
+    thread: block ? blockLiveThread(blockRead) : accessorThreadBinding(read, commit, setter),
     mock: isMock,
-    ...attachmentSubmitOpts
+    ...block ? { fetchSignal: "controller.signal" } : {},
+    ...attachmentSubmitOpts,
+    ...block ? {
+      afterValue: [
+        ...attachmentSubmitOpts.afterValue ?? [],
+        ...blockPrelude
+      ]
+    } : {}
   });
   const modelInit = defaultModel ? [
     `// SCAF-8: change this model id to another id THIS PROVIDER accepts.`,
@@ -4706,7 +6494,31 @@ function renderAngular(components, ctx) {
     `        cardTypes: cards.tags,`,
     `        cardSchemas: cards.validationSchemas,`
   ] : [];
-  const sampleSeed = [
+  const sampleSeed = block ? [
+    `  // ── The block's state: your records + the kit's session/persistence helpers ─`,
+    `  readonly threads = signal<Thread[]>(loadThreads());`,
+    `  // null means a DRAFT: "New chat" was pressed and nothing is stored yet. A`,
+    `  // record is created on its first turn, so the rail never fills with empties.`,
+    `  readonly activeId = signal<string | null>(this.threads()[0]?.id ?? null);`,
+    `  // One id per in-flight reply — a stream keeps running when you switch away.`,
+    `  readonly streamingIds = signal<string[]>([]);`,
+    ...BLOCK_SESSIONS_NOTE.map((l) => `  // ${l}`),
+    `  private readonly sessions = createThreadSessions((ids) => this.streamingIds.set(ids));`,
+    `  // The save scheduler: the debounce/flush MECHANICS are the kit's; the delay,`,
+    `  // the save target and what a failed save means are YOURS (see saveThreads).`,
+    `  private readonly saver = createSaveScheduler(saveThreads, { delayMs: 250 });`,
+    `  // Every write goes through this — a NEW array per write is what notifies.`,
+    `  private readonly setThreads = (updater: (prev: Thread[]) => Thread[]): void =>`,
+    `    this.threads.update(updater);`,
+    `  readonly active = computed(() => this.threads().find((t) => t.id === this.activeId()) ?? null);`,
+    `  readonly messages = computed(() => this.active()?.messages ?? []);`,
+    `  readonly loading = computed(() => { const id = this.activeId(); return id !== null && this.streamingIds().includes(id); });`,
+    `  // The rail's row shape is a VIEW of your record — titles and counts, no`,
+    `  // message bodies. The rail renders the array in the order it is given.`,
+    `  readonly rows = computed(() => this.threads().map((t) => ({ id: t.id, title: t.title, messageCount: t.messages.length, updatedAt: t.updatedAt })));`,
+    `  // The template cannot spell \`undefined\` portably, so the ?? lives here.`,
+    `  readonly activeIdOrUndefined = computed(() => this.activeId() ?? undefined);`
+  ] : [
     ...hasEmbedded ? sampleSeedComment(isMock, "  ", (literal) => [
       `readonly messages = signal<ChatMessage[]>([${literal}]);`
     ]) : [],
@@ -4721,17 +6533,20 @@ function renderAngular(components, ctx) {
     `  private readonly sourcesEl = viewChild.required<ElementRef<KaiSourcesElement>>('sources');`
   ] : [];
   const sourcesReapply = hasSourcesCompanion ? [`      Object.assign(this.sourcesEl().nativeElement, { sources: this.sampleSources });`] : [];
-  const chatTag = (pad) => [
-    `<kai-chat`,
-    `  #chat`,
-    `  [messages]="messages()"`,
-    `  [loading]="loading()"`,
-    `  [suggestions]="suggestions"`,
-    `  suggestion-mode="submit"`,
-    `  style="${p.chatFill}"`,
-    `  (kai-submit)="onSubmit($event)"`,
-    `></kai-chat>`
-  ].map((l) => `${pad}${l}`);
+  const chatTag = (pad) => {
+    const slotted = block ? [] : slottedChildMarkup(components, "  ", { wired: false, ids: false });
+    return [
+      `<kai-chat`,
+      `  #chat`,
+      `  [messages]="messages()"`,
+      `  [loading]="loading()"`,
+      `  [suggestions]="suggestions"`,
+      `  suggestion-mode="submit"`,
+      `  style="${p.chatFill}"`,
+      `  (kai-submit)="onSubmit($event)"`,
+      ...slotted.length === 0 ? [`></kai-chat>`] : [`>`, ...slotted, `</kai-chat>`]
+    ].map((l) => `${pad}${l}`);
+  };
   const templateBody = workspace ? [
     `      <!-- SCAF-14: workspace split — chat pane left, artifact preview right. -->`,
     `      <!-- kai-resizable needs kai-resizable-item children to render panels. -->`,
@@ -4747,7 +6562,39 @@ function renderAngular(components, ctx) {
     // Siblings of the SPLIT — see the same line in renderJsx.
     ...companionLines
   ] : [...chatTag("      "), ...companionLines];
-  const elementTypes = hasSourcesCompanion ? "KaiChatElement, KaiSourcesElement" : "KaiChatElement";
+  const elementTypes = [
+    "KaiChatElement",
+    ...block ? ["KaiConversationsElement"] : [],
+    ...hasSourcesCompanion ? ["KaiSourcesElement"] : []
+  ].join(", ");
+  const surfaceTemplate = block ? [
+    `      <!-- ── The workspace BLOCK: the shell + the rail + your thread records ── -->`,
+    ...htmlComment(
+      [
+        `<kai-workspace> is the chat-agnostic layout shell: header/start/main/`,
+        `end/footer slots, aside resize + collapse, and a mobile drawer below`,
+        `the drawer-below width. It knows nothing about chat.`
+      ],
+      "      "
+    ),
+    `      <kai-workspace drawer-below="720" style="display:block;width:100%;height:100%">`,
+    ...htmlComment(BLOCK_RAIL_NOTE, "        "),
+    `        <!-- New chat = a DRAFT (activeId null): the record appears on the first turn. -->`,
+    `        <kai-conversations`,
+    `          #rail`,
+    `          slot="start"`,
+    `          [conversations]="rows()"`,
+    `          [activeId]="activeIdOrUndefined()"`,
+    `          style="display:block;height:100%"`,
+    `          (kai-conversation-select)="onSelect($event)"`,
+    `          (kai-new-chat)="onNewChat()"`,
+    `        ></kai-conversations>`,
+    `        <!-- Unnamed children project into the shell's MAIN region. -->`,
+    `        <div style="display:flex;flex-direction:column;height:100%;min-height:0">`,
+    ...indentEmitted([...attachmentTemplate, ...templateBody], "    "),
+    `        </div>`,
+    `      </kai-workspace>`
+  ] : [...attachmentTemplate, ...templateBody];
   return [
     `// Angular standalone component — save as: src/app/chat.component.ts`,
     `// Render it: put <app-chat /> in your root template and add ChatComponent to`,
@@ -4759,7 +6606,7 @@ function renderAngular(components, ctx) {
     `//   "styles": ["node_modules/@kitn.ai/ui/dist/theme.tokens.css", "src/styles.css"]`,
     `// (@kitn.ai/ui/theme.tokens.css is the compiled token file; theme.css is`,
     `// Tailwind source and is only for apps that compile Tailwind themselves.)`,
-    `import { CUSTOM_ELEMENTS_SCHEMA, Component, ElementRef, afterNextRender, signal, viewChild } from '@angular/core';`,
+    `import { CUSTOM_ELEMENTS_SCHEMA, Component, ElementRef, afterNextRender, ${block ? "computed, effect, " : ""}signal, viewChild } from '@angular/core';`,
     `import '@kitn.ai/ui/elements';  // registers <kai-*> — required, must come first`,
     `import type { ${elementTypes} } from '@kitn.ai/ui/elements';`,
     ...wireImportLines({
@@ -4768,7 +6615,8 @@ function renderAngular(components, ctx) {
       cards: ctx.emitCards,
       cardTools: ctx.cardProvider !== null,
       mock: isMock,
-      attachments
+      attachments,
+      workspaceBlock: block
     }),
     ``,
     `// ${ctx.label} — ${p.note}. empty-state hint: ${emptyHint}`,
@@ -4777,6 +6625,7 @@ function renderAngular(components, ctx) {
     ``,
     ...modelInit,
     ...attachmentModuleInit,
+    ...block ? [...blockThreadStoreLines(""), ``] : [],
     ...cardsInit,
     ...toolsLines,
     ...runnerLines,
@@ -4788,8 +6637,7 @@ function renderAngular(components, ctx) {
     `  schemas: [CUSTOM_ELEMENTS_SCHEMA],`,
     `  template: \``,
     `    <div style="${p.style}">`,
-    ...attachmentTemplate,
-    ...templateBody,
+    ...surfaceTemplate,
     `    </div>`,
     `  \`,`,
     `})`,
@@ -4797,12 +6645,17 @@ function renderAngular(components, ctx) {
     `  // Every write assigns a NEW array. That reference change is what re-renders`,
     `  // <kai-chat> — mutating the array in place does nothing.`,
     ...sampleSeed,
-    `  readonly loading = signal(false);`,
+    ...block ? [] : [`  readonly loading = signal(false);`],
     `  readonly suggestions = ${jsArray(suggestions)};`,
     ...sourcesField,
     `  private readonly chatEl = viewChild.required<ElementRef<KaiChatElement>>('chat');`,
+    ...block ? [`  private readonly railEl = viewChild.required<ElementRef<KaiConversationsElement>>('rail');`] : [],
     ``,
     `  constructor() {`,
+    ...block ? [
+      `    // The save scheduler rides an effect: every threads() write schedules a save.`,
+      `    effect(() => this.saver.schedule(this.threads()));`
+    ] : [],
     `    // SCAF-15: kai-* register via an async dynamic import (SSR-safety), so the`,
     `    // element may not be upgraded when Angular first applies the bindings above —`,
     `    // and a property set on a not-yet-upgraded element is dropped on upgrade.`,
@@ -4817,10 +6670,30 @@ function renderAngular(components, ctx) {
     `        suggestions: this.suggestions,`,
     ...cardPropAssign,
     `      });`,
+    ...block ? [
+      `      // The rail's array props follow the same upgrade rule.`,
+      `      await customElements.whenDefined('kai-conversations');`,
+      `      Object.assign(this.railEl().nativeElement, {`,
+      `        conversations: this.rows(),`,
+      `        activeId: this.activeIdOrUndefined(),`,
+      `      });`,
+      `      // Flush the pending write when the tab closes mid-debounce (or mid-stream).`,
+      `      window.addEventListener('beforeunload', () => this.saver.flush());`
+    ] : [],
     ...sourcesReapply,
     `    });`,
     `  }`,
     ``,
+    ...block ? [
+      `  onSelect(event: Event) {`,
+      `    this.activeId.set((event as CustomEvent<{ id: string }>).detail.id);`,
+      `  }`,
+      `  onNewChat() {`,
+      `    // A DRAFT, not a record: it becomes a thread on its first turn.`,
+      `    this.activeId.set(null);`,
+      `  }`,
+      ``
+    ] : [],
     ...attachmentFields,
     ``,
     `  // \`Event\`, not \`CustomEvent\`: under strictTemplates Angular types \`$event\` on`,
@@ -4835,13 +6708,17 @@ function renderAngular(components, ctx) {
 }
 function renderSolid(components, ctx) {
   const { p, emptyHint, suggestions, isMock, defaultModel, emitTools, emitToolLoop } = ctx;
-  const workspace = isWorkspace(components);
+  const workspace = isArtifactSplit(components);
+  const block = isWorkspaceBlock(components);
   const attachments = hasAttachments(components);
   const standaloneCompanionTags = components.filter(
-    (t) => t !== "kai-chat" && !MESSAGE_EMBEDDED_TAGS.has(t) && !WORKSPACE_STRUCTURAL_TAGS.has(t) && !(attachments && ATTACHMENT_TAGS.has(t))
+    (t) => t !== "kai-chat" && !MESSAGE_EMBEDDED_TAGS.has(t) && !ARTIFACT_SPLIT_TAGS.has(t) && !(block && BLOCK_TAGS.has(t)) && !(attachments && ATTACHMENT_TAGS.has(t))
   );
   const hasSources = standaloneCompanionTags.includes("kai-sources");
   const hasVoice = standaloneCompanionTags.includes("kai-voice-input");
+  const unrenderedCompanions = standaloneCompanionTags.filter(
+    (t) => t !== "kai-sources" && t !== "kai-voice-input"
+  );
   const componentImports = [
     "Attachment",
     "AttachmentInfo",
@@ -4869,6 +6746,9 @@ function renderSolid(components, ctx) {
     "SourceTrigger",
     "Tool",
     ...workspace ? ["Artifact", "ResizableHandle", "ResizablePanel", "ResizablePanelGroup"] : [],
+    // The BLOCK's structural pair: the Solid shell + the Solid rail (this target
+    // renders components, not <kai-*> tags — same rule as everything above).
+    ...block ? ["ConversationList", "WorkspaceShell"] : [],
     ...hasVoice ? ["VoiceInput"] : [],
     // `Attachments`/`Attachment`/`AttachmentPreview`/`AttachmentInfo` are already
     // unconditional above — `renderPart` draws `file` PARTS with them whatever the
@@ -4880,17 +6760,32 @@ function renderSolid(components, ctx) {
   const read = "messages()";
   const commit = (value) => `setMessages(${value});`;
   const setter = "(fn) => setMessages((prev) => fn(prev))";
+  const blockRead = `(threads().find((t) => t.id === targetId)?.messages ?? [])`;
+  const blockPrelude = block ? [
+    ...BLOCK_TARGET_ID_NOTE.map((l) => `// ${l}`),
+    `const targetId = activeId() ?? crypto.randomUUID();`,
+    `// The record is born on its first turn — with YOUR title policy.`,
+    `setThreads((prev) => prev.some((t) => t.id === targetId)`,
+    `  ? prev`,
+    `  : [{ id: targetId, title: deriveTitle(value), updatedAt: new Date().toISOString(), messages: [] }, ...prev]);`,
+    `setActiveId(targetId);`,
+    ...BLOCK_BIND_NOTE.map((l) => `// ${l}`),
+    `const setMessages = bindThreadMessages<Thread>((fn) => { setThreads((prev) => fn(prev)); }, targetId, {`,
+    `  touch: (t) => ({ ...t, updatedAt: new Date().toISOString() }),`,
+    `});`,
+    `const controller = sessions.begin(targetId);`
+  ] : [];
   const onSubmitBody = realStreamBody({
     pad: "    ",
-    read,
-    commitSet: (expr) => commit(expr),
-    setterAdapter: setter,
-    setLoading: (v2) => `setLoading(${v2});`,
+    read: block ? blockRead : read,
+    commitSet: block ? (expr) => `setMessages(() => ${expr});` : (expr) => commit(expr),
+    setterAdapter: block ? "setMessages" : setter,
+    setLoading: block ? (v2) => v2 === "true" ? `// loading for THIS thread now derives from the sessions map (streamingIds).` : `sessions.end(targetId, controller);` : (v2) => `setLoading(${v2});`,
     bodyPayload: realBodyPayload({ defaultModel, tools: emitTools }),
     strictRoles: true,
     toolLoop: emitToolLoop,
     cards: ctx.emitCards,
-    thread: accessorThreadBinding(read, commit, setter),
+    thread: block ? blockLiveThread(blockRead) : accessorThreadBinding(read, commit, setter),
     valueSource: "input()",
     // The staged files are captured BEFORE either list is cleared. `setInput('')`
     // stays last so the order reads the way it executes.
@@ -4900,9 +6795,11 @@ function renderSolid(components, ctx) {
         clear: ["setStaged([]);"],
         fromSubmitEvent: false
       }) : [],
+      ...blockPrelude,
       `setInput('');`
     ],
     ...attachments ? { filesExpr: "files" } : {},
+    ...block ? { fetchSignal: "controller.signal" } : {},
     mock: isMock
   });
   const modelInit = defaultModel ? [
@@ -5082,6 +6979,21 @@ function renderSolid(components, ctx) {
   return [
     `// SolidJS + Vite — save as: src/App.tsx`,
     `//`,
+    // What this target DROPS, said out loud. It renders Solid components for the
+    // companions it knows (sources, voice input) and nothing at all for the rest,
+    // so a `components` list naming one of those used to produce a file with no
+    // trace of it — a silent drop, and the quiet half of the same defect the
+    // conversation rail had. Naming them is not a fix; it is the honest record
+    // until this target grows a branch for them.
+    ...unrenderedCompanions.length > 0 ? [
+      `// NOT WIRED, and not rendered: ${unrenderedCompanions.join(", ")}.`,
+      `// You asked for ${unrenderedCompanions.length === 1 ? "it" : "them"} and this target has no branch for`,
+      `// ${unrenderedCompanions.length === 1 ? "it" : "them"} — see the note below on why this file renders Solid`,
+      `// components rather than <kai-*> elements. Compose the Solid component`,
+      `// yourself (ask the component_reference MCP tool for what it exports), or`,
+      `// scaffold the html target, which drives the custom elements directly.`,
+      `//`
+    ] : [],
     `// This target does NOT use the <kai-*> custom elements, and that is deliberate:`,
     `// the kit is AUTHORED in SolidJS, so a Solid app renders the real components`,
     `// with real props and real fine-grained reactivity. Going through the`,
@@ -5098,7 +7010,7 @@ function renderSolid(components, ctx) {
     `// The @source line is NOT optional: without it Tailwind scans only src/, strips`,
     `// every kit utility class as unused, and the whole UI renders unstyled.`,
     `// (theme.css here, not theme.tokens.css: this app compiles Tailwind itself.)`,
-    `import { For, Index, Match, Show, Switch, createMemo, createSignal } from 'solid-js';`,
+    `import { For, Index, Match, Show, Switch, ${block ? "createEffect, " : ""}createMemo, createSignal${block ? ", onCleanup" : ""} } from 'solid-js';`,
     // '@kitn.ai/ui/solid', NOT the root '@kitn.ai/ui', and the difference is
     // invisible to every compiler on this repo's critical path: src/solid.ts is
     // `export * from './index'`, so ./solid is a strict SUPERSET of the root and
@@ -5123,13 +7035,15 @@ function renderSolid(components, ctx) {
       toolLoop: emitToolLoop,
       cards: ctx.emitCards,
       cardTools: ctx.cardProvider !== null,
-      mock: isMock
+      mock: isMock,
+      workspaceBlock: block
     }),
     ``,
     `// ${ctx.label} — ${p.note}. empty-state hint: ${emptyHint}`,
     ...(p.altNote ?? []).map((l) => `// ${l}`),
     ``,
     ...isMock ? [...mockResponderInit(), ``] : [],
+    ...block ? [...blockThreadStoreLines(""), ``] : [],
     ...cardsInit,
     `// Narrow a part to ONE variant, or false. One read, one cast — and the JSX`,
     `// below re-runs it on every delta, which is what keeps a growing text or`,
@@ -5303,8 +7217,34 @@ function renderSolid(components, ctx) {
     `  // streaming message as a NEW OBJECT on every delta: a new reference IS the`,
     `  // re-render signal. Which is exactly why the thread below is keyed by message`,
     `  // id rather than by the message objects — see messageKeys.`,
-    `  const [messages, setMessages] = createSignal<ChatMessage[]>([]);`,
-    `  const [loading, setLoading] = createSignal(false);`,
+    ...block ? [
+      `  // ── The block's state: your records + the kit's session/persistence helpers ─`,
+      `  const [threads, setThreads] = createSignal<Thread[]>(loadThreads());`,
+      `  // null means a DRAFT: "New chat" was pressed and nothing is stored yet. A`,
+      `  // record is created on its first turn, so the rail never fills with empties.`,
+      `  const [activeId, setActiveId] = createSignal<string | null>(threads()[0]?.id ?? null);`,
+      `  // One id per in-flight reply — a stream keeps running when you switch away.`,
+      `  const [streamingIds, setStreamingIds] = createSignal<string[]>([]);`,
+      ...BLOCK_SESSIONS_NOTE.map((l) => `  // ${l}`),
+      `  const sessions = createThreadSessions((ids) => setStreamingIds(ids));`,
+      `  // The save scheduler: the debounce/flush MECHANICS are the kit's; the delay,`,
+      `  // the save target and what a failed save means are YOURS (see saveThreads).`,
+      `  const saver = createSaveScheduler(saveThreads, { delayMs: 250 });`,
+      `  createEffect(() => saver.schedule(threads()));`,
+      `  // Flush the pending write when the tab closes mid-debounce (or mid-stream).`,
+      `  const flushOnUnload = () => saver.flush();`,
+      `  window.addEventListener('beforeunload', flushOnUnload);`,
+      `  onCleanup(() => window.removeEventListener('beforeunload', flushOnUnload));`,
+      `  const active = createMemo(() => threads().find((t) => t.id === activeId()) ?? null);`,
+      `  const messages = createMemo(() => active()?.messages ?? []);`,
+      `  const loading = createMemo(() => { const id = activeId(); return id !== null && streamingIds().includes(id); });`,
+      `  // The rail's row shape is a VIEW of your record — titles and counts, no`,
+      `  // message bodies. The rail renders the array in the order it is given.`,
+      `  const rows = createMemo(() => threads().map((t) => ({ id: t.id, title: t.title, messageCount: t.messages.length, updatedAt: t.updatedAt })));`
+    ] : [
+      `  const [messages, setMessages] = createSignal<ChatMessage[]>([]);`,
+      `  const [loading, setLoading] = createSignal(false);`
+    ],
     `  // PromptInput is CONTROLLED here, so this signal — not a kai-submit event — is`,
     `  // where the submitted text comes from.`,
     `  const [input, setInput] = createSignal('');`,
@@ -5332,7 +7272,31 @@ function renderSolid(components, ctx) {
     `    // component below it. Mount it once, at the top.`,
     `    <ChatConfig>`,
     `      <div style={{ ${solidStyle(p.style)} }}>`,
-    ...tree,
+    ...block ? [
+      `        {/* ── The workspace BLOCK: the shell + the rail + your thread records ── */}`,
+      `        {/* WorkspaceShell is the chat-agnostic layout shell (header/start/main/`,
+      `            end/footer regions, aside resize + collapse, a mobile drawer below`,
+      `            drawerBelow px). It knows nothing about chat. */}`,
+      `        <WorkspaceShell`,
+      `          drawerBelow={720}`,
+      `          class="h-full w-full"`,
+      `          start={`,
+      // A JS line comment, not a {/* */} pair: inside an attribute's
+      // expression container the braces form is a parse error.
+      ...BLOCK_RAIL_NOTE_SOLID.map((l) => `            // ${l}`),
+      `            <ConversationList`,
+      `              groups={[]}`,
+      `              conversations={rows()}`,
+      `              activeId={activeId() ?? undefined}`,
+      `              onSelect={(id) => setActiveId(id)}`,
+      `              onNewChat={() => setActiveId(null)}`,
+      `              class="h-full"`,
+      `            />`,
+      `          }`,
+      `        >`,
+      ...indentEmitted(tree, "  "),
+      `        </WorkspaceShell>`
+    ] : tree,
     `      </div>`,
     `    </ChatConfig>`,
     `  );`,
@@ -5480,17 +7444,38 @@ function viteMiddlewareAdapter(plugin) {
       `    name: 'chat-api',`,
       `    configureServer(server) {`,
       `      server.middlewares.use('/api/chat', async (req, res) => {`,
+      `        // The METHOD has to survive the bridge, like the status does below.`,
+      `        // Hard-coding 'POST' here meant a bare GET /api/chat arrived at`,
+      `        // readChatRequest as an empty POST and came back 400 "not valid JSON":`,
+      `        // the 405 guard was emitted, compiled, and unreachable on this host.`,
+      `        const method = req.method ?? 'POST';`,
+      `        // undici THROWS on \`new Request(url, { method: 'GET', body })\`, so only`,
+      `        // read a body from the methods that can carry one.`,
+      `        const hasBody = method !== 'GET' && method !== 'HEAD';`,
       `        let body = '';`,
-      `        req.setEncoding('utf8');`,
-      `        for await (const chunk of req) body += chunk;`,
+      `        if (hasBody) {`,
+      `          req.setEncoding('utf8');`,
+      `          for await (const chunk of req) body += chunk;`,
+      `        }`,
       ``,
-      `        const response = await chatHandler(`,
-      `          new Request('http://localhost/api/chat', {`,
-      `            method: 'POST',`,
-      `            headers: { 'Content-Type': 'application/json' },`,
-      `            body,`,
-      `          }),`,
-      `        );`,
+      `        let response: Response;`,
+      `        try {`,
+      `          response = await chatHandler(`,
+      `            new Request('http://localhost/api/chat', {`,
+      `              method,`,
+      `              headers: { 'Content-Type': 'application/json' },`,
+      `              body: hasBody ? body : undefined,`,
+      `            }),`,
+      `          );`,
+      `        } catch (error) {`,
+      `          // An unhandled rejection in an async connect middleware EXITS Node 22 —`,
+      `          // this catch is the guard findings F-10 exists for. The browser gets`,
+      `          // eight generic words, so the TERMINAL has to get the real thing:`,
+      `          // swallowing it here would make a dev server strictly less`,
+      `          // diagnosable than the crash it replaced.`,
+      `          console.error('[chat-api] chatHandler failed:', error);`,
+      `          response = Response.json({ error: 'Chat handler failed.' }, { status: 500 });`,
+      `        }`,
       ``,
       `        // The STATUS has to survive the bridge: a 401 from the provider that`,
       `        // arrives at the browser as a 200 is a blank bubble and no error.`,
@@ -5807,7 +7792,13 @@ function cannotHostWarning(integration, route, framework) {
     // and reaches localhost, so the page can call it. That advice was emitted
     // identically for every integration because nothing read the flag that
     // distinguishes them.
-    ...integration.keyExposure === "frontend-safe" ? [
+    ...integration.id === "mock" ? [
+      // For mock the honest first option is to do nothing: the block is
+      // already labelled OPTIONAL, and "call it directly" would be advice
+      // about an upstream that does not exist.
+      `#   • or ignore it: the front end above already streams the mock locally, so`,
+      `#     nothing in this scaffold needs the route to run.`
+    ] : integration.keyExposure === "frontend-safe" ? [
       `#   • or drop the route entirely: this integration needs no server hop — see the`,
       `#     run note — so the page may call it directly (CORS applies).`
     ] : [],
@@ -5816,7 +7807,8 @@ function cannotHostWarning(integration, route, framework) {
       `#   • it is a separate SERVICE either way: run it (uvicorn main:app) and proxy`,
       `#     /api/chat to it, or point the fetch at http://localhost:8000/api/chat.`
     ] : [`#   • or run it where it belongs: framework: "${route.framework}".`],
-    `#   • or use integration: "mock" for a zero-config local stream (no backend, no key).`
+    // Not emitted for mock itself: "use mock" is where the reader already is.
+    ...integration.id === "mock" ? [] : [`#   • or use integration: "mock" for a zero-config local stream (no backend, no key).`]
   ];
   return [
     `#`,
@@ -5922,7 +7914,7 @@ function compose(components, integration, placement, framework, suggestions, aud
     audience
   });
   const isMock = integration.id === "mock";
-  const route = isMock ? void 0 : chooseRoute(integration, framework);
+  const route = chooseRoute(integration, framework);
   const header = [
     `# AI/UI scaffold — ${preset ? preset.title : surfaceLabel(components)} × ${integration.title}`,
     `combo: ${preset ? preset.id : components.join("+")} × ${integration.id} × ${placement} × ${framework}`,
@@ -5936,11 +7928,17 @@ function compose(components, integration, placement, framework, suggestions, aud
   const block2Parts = [`=== (2) BACKEND ROUTE ===`, ``];
   if (isMock) {
     block2Parts.push(
-      `# No backend or API key needed — replies stream locally for preview (see the`,
-      `# front-end onSubmit above). Swap \`integration\` for a real provider (openrouter,`,
-      `# ollama, vercel-ai-sdk, …) when ready, and this block becomes its route handler.`
+      `# OPTIONAL — the front end above streams its reply locally, so this scaffold`,
+      `# RUNS with no backend and no key. The route below is the mock's server half:`,
+      `# the same createMockResponder() frames served over HTTP, so you can stand up`,
+      `# the real /api/chat seam before any provider exists. To use it, swap the`,
+      `# onSubmit's \`const res = mockResponse(value);\` for a request to /api/chat and`,
+      `# hand its response body to the same reader. Going live later then means`,
+      `# editing THIS file only — replace the responder with a provider call, or`,
+      `# re-scaffold with a real integration and this block becomes its route.`
     );
-  } else if (route) {
+  }
+  if (route) {
     if (!route.exact) {
       block2Parts.push(
         `# Note: ${integration.title} has no route for "${framework}". Emitting its native`,
@@ -6142,8 +8140,8 @@ function rejectUseCase(id) {
     // so the rejection that teaches the id list is the right place to say so.
     `These are PRESETS over the real axis, which is \`components\`. To compose a surface no`,
     `preset names, pass the list directly, e.g. components: ["kai-chat", "kai-tool",`,
-    `"kai-reasoning", "kai-artifact", "kai-resizable"] for a workspace that also renders its`,
-    `tool calls. Pick a preset id or pass \`components\`, then call scaffold again.`
+    `"kai-reasoning", "kai-artifact", "kai-resizable"] for an artifact split that also renders`,
+    `its tool calls. Pick a preset id or pass \`components\`, then call scaffold again.`
   ].join("\n");
 }
 const scaffold = {
@@ -6207,60 +8205,99 @@ 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";
+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]);
+  return names;
+}
+const DECLARED_TOKENS = declaredKaiTokens(themeCss);
+function colorToken(suffix) {
+  const name = `--kai-color-${suffix}`;
+  if (!DECLARED_TOKENS.has(name)) {
+    throw new Error(
+      `[kai mcp: theme] theme.css declares no \`${name}\`. The tool brands that token, so emitting it would hand the caller CSS that themes nothing. Either the token was renamed in packages/ui/theme.css (update the BRAND_TOKENS suffix in src/agent-tooling/mcp/tools/theme.ts to match) or it was removed (drop the entry). Known --kai-color-* names: ${[...DECLARED_TOKENS].filter((n) => n.startsWith("--kai-color-")).sort().join(", ")}`
+    );
+  }
+  return name;
+}
+const BRAND_TOKENS = [
+  { key: "primary", suffix: "primary", purpose: "primary brand color" },
+  {
+    key: "primaryFg",
+    suffix: "primary-foreground",
+    purpose: "AA-contrast foreground on primary (auto-selected black/white)"
+  },
+  { key: "ring", suffix: "ring", purpose: "keyboard focus ring" },
+  { key: "accent", suffix: "accent", purpose: "tinted accent surface" },
+  { key: "accentFg", suffix: "accent-foreground", purpose: "text on accent surface" }
+];
+let memo;
+function emittedTokens() {
+  if (!memo) {
+    const tokens = BRAND_TOKENS.map((t) => ({
+      key: t.key,
+      name: colorToken(t.suffix),
+      purpose: t.purpose
+    }));
+    memo = { tokens, valueColumn: Math.max(...tokens.map((t) => t.name.length + 1)) + 2 };
+  }
+  return memo;
+}
 function parseHex(hex) {
   const s = hex.trim().replace(/^#/, "");
   if (s.length === 3) {
     const r = parseInt(s[0] + s[0], 16);
-    const g2 = parseInt(s[1] + s[1], 16);
+    const g = parseInt(s[1] + s[1], 16);
     const b = parseInt(s[2] + s[2], 16);
-    if (isNaN(r) || isNaN(g2) || isNaN(b)) return null;
-    return { r, g: g2, b };
+    if (isNaN(r) || isNaN(g) || isNaN(b)) return null;
+    return { r, g, b };
   }
   if (s.length === 6) {
     const r = parseInt(s.slice(0, 2), 16);
-    const g2 = parseInt(s.slice(2, 4), 16);
+    const g = parseInt(s.slice(2, 4), 16);
     const b = parseInt(s.slice(4, 6), 16);
-    if (isNaN(r) || isNaN(g2) || isNaN(b)) return null;
-    return { r, g: g2, b };
+    if (isNaN(r) || isNaN(g) || isNaN(b)) return null;
+    return { r, g, b };
   }
   return null;
 }
-function toHex(r, g2, b) {
-  return "#" + [r, g2, b].map((v2) => Math.max(0, Math.min(255, Math.round(v2))).toString(16).padStart(2, "0")).join("");
+function toHex(r, g, b) {
+  return "#" + [r, g, b].map((v2) => Math.max(0, Math.min(255, Math.round(v2))).toString(16).padStart(2, "0")).join("");
 }
-function relativeLuminance(r, g2, b) {
+function relativeLuminance(r, g, b) {
   const lin = (c) => {
     const s = c / 255;
     return s <= 0.04045 ? s / 12.92 : Math.pow((s + 0.055) / 1.055, 2.4);
   };
-  return 0.2126 * lin(r) + 0.7152 * lin(g2) + 0.0722 * lin(b);
+  return 0.2126 * lin(r) + 0.7152 * lin(g) + 0.0722 * lin(b);
 }
-function foreground(r, g2, b) {
-  const lum = relativeLuminance(r, g2, b);
+function foreground(r, g, b) {
+  const lum = relativeLuminance(r, g, b);
   const contrastWhite = 1.05 / (lum + 0.05);
   const contrastBlack = (lum + 0.05) / 0.05;
   return contrastWhite >= contrastBlack ? "#ffffff" : "#000000";
 }
-function lighten(r, g2, b, ratio) {
+function lighten(r, g, b, ratio) {
   return toHex(
     r + (255 - r) * ratio,
-    g2 + (255 - g2) * ratio,
+    g + (255 - g) * ratio,
     b + (255 - b) * ratio
   );
 }
-function darken(r, g2, b, ratio) {
-  return toHex(r * (1 - ratio), g2 * (1 - ratio), b * (1 - ratio));
+function darken(r, g, b, ratio) {
+  return toHex(r * (1 - ratio), g * (1 - ratio), b * (1 - ratio));
 }
-function accentSurface(r, g2, b) {
-  return lighten(r, g2, b, 0.88);
+function accentSurface(r, g, b) {
+  return lighten(r, g, b, 0.88);
 }
-function darkModeBrand(r, g2, b) {
-  const lum = relativeLuminance(r, g2, b);
-  if (lum > 0.25) return toHex(r, g2, b);
-  return lighten(r, g2, b, 0.35);
+function darkModeBrand(r, g, b) {
+  const lum = relativeLuminance(r, g, b);
+  if (lum > 0.25) return toHex(r, g, b);
+  return lighten(r, g, b, 0.35);
 }
-function darkAccentSurface(r, g2, b) {
-  return darken(r, g2, b, 0.75);
+function darkAccentSurface(r, g, b) {
+  return darken(r, g, b, 0.75);
 }
 const KEYWORD_COLORS = {
   blue: "#3b82f6",
@@ -6328,10 +8365,10 @@ function resolveBrand(brand, description) {
     note: `No brand color or description provided — defaulted to **${DEFAULT_BRAND}** (indigo, the kit's own brand). Pass \`brand: '#rrggbb'\` to use your color.`
   };
 }
-function buildTokenSet(r, g2, b) {
-  const primary = toHex(r, g2, b);
-  const primaryFg = foreground(r, g2, b);
-  const accent = accentSurface(r, g2, b);
+function buildTokenSet(r, g, b) {
+  const primary = toHex(r, g, b);
+  const primaryFg = foreground(r, g, b);
+  const accent = accentSurface(r, g, b);
   const accentFgColor = foreground(
     ...[accent].map((h) => parseHex(h)).flatMap((c) => [c.r, c.g, c.b])
   );
@@ -6343,12 +8380,12 @@ function buildTokenSet(r, g2, b) {
     accentFg: accentFgColor
   };
 }
-function buildDarkTokenSet(r, g2, b) {
-  const darkBrand = darkModeBrand(r, g2, b);
+function buildDarkTokenSet(r, g, b) {
+  const darkBrand = darkModeBrand(r, g, b);
   const parsed = parseHex(darkBrand);
   const primary = darkBrand;
   const primaryFg = foreground(parsed.r, parsed.g, parsed.b);
-  const accent = darkAccentSurface(r, g2, b);
+  const accent = darkAccentSurface(r, g, b);
   const accentFgParsed = parseHex(accent);
   return {
     primary,
@@ -6358,14 +8395,12 @@ function buildDarkTokenSet(r, g2, b) {
     accentFg: foreground(accentFgParsed.r, accentFgParsed.g, accentFgParsed.b)
   };
 }
-function cssBlock(selector, tokens) {
+function cssBlock(selector, values, emitted) {
   return [
     `${selector} {`,
-    `  --kai-color-primary:             ${tokens.primary};`,
-    `  --kai-color-primary-foreground:  ${tokens.primaryFg};`,
-    `  --kai-color-ring:                ${tokens.ring};`,
-    `  --kai-color-accent:              ${tokens.accent};`,
-    `  --kai-color-accent-foreground:   ${tokens.accentFg};`,
+    ...emitted.tokens.map(
+      (t) => `  ${`${t.name}:`.padEnd(emitted.valueColumn)}${values[t.key]};`
+    ),
     `}`
   ].join("\n");
 }
@@ -6387,21 +8422,24 @@ const theme = {
       description,
       mode = "light"
     } = args;
-    const { hex, r, g: g2, b, note } = resolveBrand(brand, description);
-    const lightTokens = buildTokenSet(r, g2, b);
-    const darkTokens = buildDarkTokenSet(r, g2, b);
+    const emitted = emittedTokens();
+    const { hex, r, g, b, note } = resolveBrand(brand, description);
+    const lightTokens = buildTokenSet(r, g, b);
+    const darkTokens = buildDarkTokenSet(r, g, b);
     const blocks = [];
     if (mode === "light" || mode === "both") {
-      blocks.push(cssBlock(":root", lightTokens));
+      blocks.push(cssBlock(":root", lightTokens, emitted));
     }
     if (mode === "dark" || mode === "both") {
-      blocks.push(cssBlock(".dark", darkTokens));
+      blocks.push(cssBlock(".dark", darkTokens, emitted));
     }
     const cssOutput = blocks.join("\n\n");
     const noteLabel = note.startsWith("Could not parse") ? "Note" : "Assumption";
     const noteSection = note ? `
 > **${noteLabel}:** ${note}
 ` : "";
+    const tokenList = emitted.tokens.map((t) => `- \`${t.name}\` — ${t.purpose}`).join("\n");
+    const firstToken = emitted.tokens[0].name;
     const text2 = `## AI/UI theme override — \`${hex}\`
 ${noteSection}
 Paste this block into your **global stylesheet** (before the \`@import\` of \`@kitn.ai/ui\` or after — order doesn't matter since \`--kai-*\` tokens are resolved at runtime via \`var()\` fallbacks). For \`mode:'dark'\` overrides, the \`.dark\` class must be on a parent element (e.g. \`<html class="dark">\`) for them to take effect.
@@ -6412,14 +8450,10 @@ ${cssOutput}
 
 ### How it works
 
-The \`--kai-color-*\` tokens pierce the Shadow DOM via CSS custom-property inheritance. Every \`kai-*\` element reads them through a \`var(--kai-color-primary, <default>)\` fallback chain defined in \`theme.css\`. Setting them on \`:root\` (or a wrapper element) is enough to rebrand everything globally.
+The \`--kai-color-*\` tokens pierce the Shadow DOM via CSS custom-property inheritance. Every \`kai-*\` element reads them through a \`var(${firstToken}, <default>)\` fallback chain defined in \`theme.css\`. Setting them on \`:root\` (or a wrapper element) is enough to rebrand everything globally.
 
-**Tokens emitted** (verified names from \`theme.css\`):
-- \`--kai-color-primary\` — primary brand color
-- \`--kai-color-primary-foreground\` — AA-contrast foreground on primary (auto-selected black/white)
-- \`--kai-color-ring\` — keyboard focus ring
-- \`--kai-color-accent\` — tinted accent surface
-- \`--kai-color-accent-foreground\` — text on accent surface
+**Tokens emitted** (names read from \`theme.css\`):
+${tokenList}
 
 ### Apply to a subtree only
 
@@ -6620,12 +8654,96 @@ const debug = {
     };
   }
 };
+function editDistance(a, b) {
+  const prev = new Array(b.length + 1);
+  for (let j2 = 0; j2 <= b.length; j2++) prev[j2] = j2;
+  for (let i = 1; i <= a.length; i++) {
+    let diag = prev[0];
+    prev[0] = i;
+    for (let j2 = 1; j2 <= b.length; j2++) {
+      const tmp = prev[j2];
+      prev[j2] = Math.min(
+        prev[j2] + 1,
+        prev[j2 - 1] + 1,
+        diag + (a[i - 1] === b[j2 - 1] ? 0 : 1)
+      );
+      diag = tmp;
+    }
+  }
+  return prev[b.length];
+}
+function typeWord(prop) {
+  if (!prop) return "value";
+  if (Array.isArray(prop.enum)) return prop.enum.map((v2) => JSON.stringify(v2)).join(" | ");
+  if (prop.type === "array") {
+    const items = prop.items;
+    return `array of ${typeof items?.type === "string" ? items.type : "values"}`;
+  }
+  return typeof prop.type === "string" ? prop.type : "value";
+}
+function suggestKey(unknownKey, value, shape, supplied) {
+  const keys = Object.keys(shape);
+  let best;
+  let bestDistance = 3;
+  for (const key of keys) {
+    const d = editDistance(unknownKey.toLowerCase(), key.toLowerCase());
+    if (d < bestDistance) {
+      bestDistance = d;
+      best = key;
+    }
+  }
+  if (best !== void 0) return best;
+  const byValue = keys.filter(
+    (key) => !supplied.includes(key) && z$1.safeParse(shape[key], value).success
+  );
+  return byValue.length === 1 ? byValue[0] : void 0;
+}
+function validateToolArgs(toolName, schema, args) {
+  const shape = schema.shape;
+  const keys = Object.keys(shape);
+  const supplied = Object.keys(args);
+  const problems = [];
+  for (const key of supplied) {
+    if (keys.includes(key)) continue;
+    const suggestion = suggestKey(key, args[key], shape, supplied);
+    problems.push(
+      `unknown argument ${JSON.stringify(key)}` + (suggestion ? ` — did you mean ${JSON.stringify(suggestion)}?` : "")
+    );
+  }
+  for (const key of keys) {
+    if (!(key in args) && !z$1.safeParse(shape[key], void 0).success) {
+      problems.push(`missing required argument ${JSON.stringify(key)}`);
+    }
+  }
+  if (problems.length === 0) return void 0;
+  const json = z$1.toJSONSchema(schema);
+  const required = new Set(json.required ?? []);
+  const argLines = keys.map((key) => {
+    const kind = required.has(key) ? "required" : "optional";
+    return `  ${key} (${kind}) — ${typeWord(json.properties?.[key])}`;
+  });
+  return `${toolName}: ${problems.join("; ")}.
+
+Nothing was returned for this call — answering anyway could look like a reply to the question you meant to ask.
+
+Expected arguments for ${toolName}:
+${argLines.join("\n")}`;
+}
 const tools = [reference, scaffold, theme, debug];
+const PACKAGE_NAME = "@kitn.ai/ui";
+function packageIdentity() {
+  const specifier = `${PACKAGE_NAME}/package.json`;
+  const require2 = createRequire(import.meta.url);
+  const pkg = require2(specifier);
+  if (pkg.name !== PACKAGE_NAME || typeof pkg.version !== "string") {
+    throw new Error(
+      `[${PACKAGE_NAME}] Refusing to report a serverInfo that is not this package's: ${specifier} resolved to ${require2.resolve(specifier)}, whose name is ${JSON.stringify(pkg.name)} and version ${JSON.stringify(pkg.version)}.`
+    );
+  }
+  return { name: pkg.name, version: pkg.version };
+}
 function createServer() {
-  const server = new Server(
-    { name: "@kitn.ai/ui", version: "0.15.0" },
-    { capabilities: { tools: {} } }
-  );
+  const server = new Server(packageIdentity(), { capabilities: { tools: {} } });
   const byName = new Map(tools.map((t) => [t.name, t]));
   server.setRequestHandler(ListToolsRequestSchema, async () => ({
     tools: tools.map((t) => ({
@@ -6645,7 +8763,12 @@ function createServer() {
         content: [{ type: "text", text: `Unknown tool: ${request.params.name}` }]
       };
     }
-    return tool.handler(request.params.arguments ?? {});
+    const args = request.params.arguments ?? {};
+    const problem = validateToolArgs(tool.name, tool.inputSchema, args);
+    if (problem) {
+      return { isError: true, content: [{ type: "text", text: problem }] };
+    }
+    return tool.handler(args);
   });
   server.__listToolsForTest = () => tools.map((t) => t.name);
   return server;