@kitn.ai/ui 0.20.1 → 0.22.0

package/src/elements/element-meta.json

@@ -4,12 +4,22 @@
     "className": "KaiAgentCardElement",
     "displayName": "AgentCard",
     "props": [
+      {
+        "name": "theme",
+        "type": "\"light\" | \"dark\" | \"auto\"",
+        "optional": true,
+        "scalar": true,
+        "description": "Color mode (`auto` follows prefers-color-scheme).",
+        "default": "'auto'",
+        "universal": true,
+        "displayType": "\"light\" | \"dark\" | \"auto\""
+      },
       {
         "name": "name",
         "type": "undefined | string",
         "optional": true,
         "scalar": true,
-        "description": "The agent's name — the primary label. Attribute: `name`.",
+        "description": "The agent's name, the primary label. Attribute: `name`.",
         "displayType": "undefined | string"
       },
       {
@@ -25,7 +35,7 @@
         "type": "undefined | false | true",
         "optional": true,
         "scalar": true,
-        "description": "Raise a prominent \"Needs you\" pill plus a glowing amber edge — the attention-routing signal that pulls focus to this agent. Attribute: `needs-attention`.",
+        "description": "Raise a prominent \"Needs you\" pill plus a glowing amber edge. This is the attention-routing signal that pulls focus to this agent. Attribute: `needs-attention`.",
         "displayType": "undefined | false | true"
       },
       {
@@ -33,7 +43,10 @@
         "type": "undefined | { tone: \"working\" | \"idle\" | \"done\" | \"error\" | \"blocked\"; label?: undefined | string; pulse?: undefined | false | true }",
         "optional": true,
         "scalar": false,
-        "description": "Run status — a JS PROPERTY (object), not an attribute. Shape: `{ tone, label?, pulse? }`, where `tone` is one of `working` | `idle` | `done` | `error` | `blocked` (maps to the kit's tool hues), `label` is an optional short string beside the dot, and `pulse` animates the dot. Set it with `el.status = { tone: 'working', label: 'Working', pulse: true }`.",
+        "description": "Run status. A JS PROPERTY (object), not an attribute. Shape: `{ tone, label?, pulse? }`, where `tone` is one of `working` | `idle` | `done` | `error` | `blocked` (maps to the kit's tool hues), `label` is an optional short string beside the dot, and `pulse` animates the dot. Set it with `el.status = { tone: 'working', label: 'Working', pulse: true }`.",
+        "typeName": "AgentStatus",
+        "typeShape": "{ tone: \"working\" | \"idle\" | \"done\" | \"error\" | \"blocked\"; label?: undefined | string; pulse?: undefined | false | true }",
+        "typeImport": "AgentStatus",
         "displayType": "undefined | { tone: \"working\" | \"idle\" | \"done\" | \"error\" | \"blocked\"; label?: undefined | string; pulse?: undefined | false | true }"
       }
     ],
@@ -41,7 +54,7 @@
       {
         "name": "kai-activate",
         "detail": null,
-        "description": "The card was activated — clicked, or Enter / Space while focused. Promote this agent back to focus.",
+        "description": "The card was activated by a click, or by Enter / Space while focused. Promote this agent back to focus.",
         "displayDetail": null
       },
       {
@@ -78,6 +91,16 @@
     "className": "KaiArtifactElement",
     "displayName": "Artifact",
     "props": [
+      {
+        "name": "theme",
+        "type": "\"light\" | \"dark\" | \"auto\"",
+        "optional": true,
+        "scalar": true,
+        "description": "Color mode (`auto` follows prefers-color-scheme).",
+        "default": "'auto'",
+        "universal": true,
+        "displayType": "\"light\" | \"dark\" | \"auto\""
+      },
       {
         "name": "src",
         "type": "undefined | string",
@@ -88,15 +111,15 @@
       },
       {
         "name": "files",
-        "type": "{ path: string; url?: undefined | string; code?: undefined | string; language?: undefined | string; type?: undefined | \"html\" | \"pdf\" | \"image\" | \"other\"; additions?: undefined | number; deletions?: undefined | number; status?: undefined | \"added\" | \"modified\" | \"deleted\" | \"renamed\" | \"untracked\" }[]",
-        "optional": false,
+        "type": "undefined | { path: string; url?: undefined | string; code?: undefined | string; language?: undefined | string; type?: undefined | \"html\" | \"pdf\" | \"image\" | \"other\"; additions?: undefined | number; deletions?: undefined | number; status?: undefined | \"added\" | \"modified\" | \"deleted\" | \"renamed\" | \"untracked\" }[]",
+        "optional": true,
         "scalar": false,
-        "description": "Files for the Code tab tree + each file's preview `url`. Set as a JS property (array).",
-        "typeName": "FileTreeFile[]",
+        "description": "Files for the Code tab tree + each file's preview `url`. Omit for a preview-only artifact (the Code tab then has nothing to show; pair it with `no-tabs` to hide the toggle). Set as a JS property (array).",
+        "typeName": "ArtifactCardFile[]",
         "typeShape": "{ path: string; url?: undefined | string; code?: undefined | string; language?: undefined | string; type?: undefined | \"html\" | \"pdf\" | \"image\" | \"other\"; additions?: undefined | number; deletions?: undefined | number; status?: undefined | \"added\" | \"modified\" | \"deleted\" | \"renamed\" | \"untracked\" }[]",
         "default": "[]",
-        "typeImport": "FileTreeFile",
-        "displayType": "{ path: string; url?: undefined | string; code?: undefined | string; language?: undefined | string; type?: undefined | \"html\" | \"pdf\" | \"image\" | \"other\"; additions?: undefined | number; deletions?: undefined | number; status?: undefined | \"added\" | \"modified\" | \"deleted\" | \"renamed\" | \"untracked\" }[]"
+        "typeImport": "ArtifactCardFile",
+        "displayType": "undefined | { path: string; url?: undefined | string; code?: undefined | string; language?: undefined | string; type?: undefined | \"html\" | \"pdf\" | \"image\" | \"other\"; additions?: undefined | number; deletions?: undefined | number; status?: undefined | \"added\" | \"modified\" | \"deleted\" | \"renamed\" | \"untracked\" }[]"
       },
       {
         "name": "tab",
@@ -119,7 +142,7 @@
         "type": "undefined | string",
         "optional": true,
         "scalar": true,
-        "description": "Selected file path — syncs the tree highlight, Code source, and preview.",
+        "description": "Selected file path. Syncs the tree highlight, Code source, and preview.",
         "displayType": "undefined | string"
       },
       {
@@ -251,6 +274,12 @@
         "description": "Artifact's own maximize button toggled (consumer-observable; non-bubbling).",
         "displayDetail": "{ maximized: false | true }"
       },
+      {
+        "name": "kai-maximize-intent",
+        "detail": "{ requested: false | true }",
+        "description": "The maximize PROTOCOL intent, raised as a raw bubbling + composed CustomEvent (not through `dispatch`) so an enclosing `<kai-resizable>` can catch it and maximize the containing panel. Declared here so it is typed and reaches the generated API. Listen for it to drive maximize from your own chrome, or re-emit it to trigger one.",
+        "displayDetail": "{ requested: false | true }"
+      },
       {
         "name": "kai-navigate",
         "detail": "{ url: string }",
@@ -293,7 +322,7 @@
         "name": "navigate",
         "params": "url: string",
         "returns": "void",
-        "description": "Push + load a url in the preview — the path-field submit path (fires kai-navigate)."
+        "description": "Push + load a url in the preview, the path-field submit path (fires kai-navigate)."
       },
       {
         "name": "selectFile",
@@ -305,13 +334,13 @@
         "name": "openExternal",
         "params": "",
         "returns": "void",
-        "description": "Open the current url in a new browser tab (no-op when there's no concrete url). Named openExternal, NOT openInTab — that's a prop (toolbar button visibility)."
+        "description": "Open the current url in a new browser tab (no-op when there's no concrete url). Named openExternal, NOT openInTab, which is a prop (toolbar button visibility)."
       },
       {
         "name": "maximize",
         "params": "",
         "returns": "void",
-        "description": "Enter the maximized view-state (fires kai-maximize-change{maximized:true}). Named maximize, NOT maximized — that's a prop."
+        "description": "Enter the maximized view-state (fires kai-maximize-change{maximized:true}). Named maximize, NOT maximized, which is a prop."
       },
       {
         "name": "restore",
@@ -334,17 +363,27 @@
     "className": "KaiAttachmentsElement",
     "displayName": "Attachments",
     "props": [
+      {
+        "name": "theme",
+        "type": "\"light\" | \"dark\" | \"auto\"",
+        "optional": true,
+        "scalar": true,
+        "description": "Color mode (`auto` follows prefers-color-scheme).",
+        "default": "'auto'",
+        "universal": true,
+        "displayType": "\"light\" | \"dark\" | \"auto\""
+      },
       {
         "name": "items",
-        "type": "{ id: string; type: \"file\" | \"source-document\"; filename?: undefined | string; mediaType?: undefined | string; url?: undefined | string; title?: undefined | string }[]",
-        "optional": false,
+        "type": "undefined | { id: string; type: \"file\" | \"source-document\"; filename?: undefined | string; mediaType?: undefined | string; url?: undefined | string; title?: undefined | string }[]",
+        "optional": true,
         "scalar": false,
-        "description": "The attachments to render. Set as a JS property (array).",
+        "description": "The attachments to render. Omit (or pass an empty array) for the empty state, which shows `emptyText` if set and nothing otherwise. Set as a JS property (array).",
         "typeName": "AttachmentData[]",
         "typeShape": "{ id: string; type: \"file\" | \"source-document\"; filename?: undefined | string; mediaType?: undefined | string; url?: undefined | string; title?: undefined | string }[]",
         "default": "[]",
         "typeImport": "AttachmentData",
-        "displayType": "AttachmentData[]"
+        "displayType": "AttachmentData[] | undefined"
       },
       {
         "name": "variant",
@@ -451,7 +490,7 @@
     "parts": [
       {
         "name": "preview",
-        "doc": "The image shown in an attachment’s hover-card preview. Bounded by default (max ~320×256, aspect preserved) so a large image never blows up the card — raise or lower the cap from outside.",
+        "doc": "The image shown in an attachment’s hover-card preview. Bounded by default (max ~320×256, aspect preserved) so a large image never blows up the card. Raise or lower the cap from outside.",
         "recipe": "kai-attachments::part(preview) { max-width: 32rem; max-height: 24rem }"
       }
     ]
@@ -461,6 +500,16 @@
     "className": "KaiAudioVisualizerElement",
     "displayName": "AudioVisualizer",
     "props": [
+      {
+        "name": "theme",
+        "type": "\"light\" | \"dark\" | \"auto\"",
+        "optional": true,
+        "scalar": true,
+        "description": "Color mode (`auto` follows prefers-color-scheme).",
+        "default": "'auto'",
+        "universal": true,
+        "displayType": "\"light\" | \"dark\" | \"auto\""
+      },
       {
         "name": "variant",
         "type": "undefined | string",
@@ -582,6 +631,9 @@
         "optional": true,
         "scalar": false,
         "description": "Custom fragment shader for `variant=\"custom\"`. JS property only.",
+        "typeName": "ShaderSpec",
+        "typeShape": "{ fragment: string; uniforms?: undefined | Record<string, { type: \"1f\" | \"1i\" | \"1fv\" | \"2f\" | \"3f\" | \"3fv\" | \"4f\" | \"4fv\" | \"Matrix2fv\" | \"Matrix3fv\" | \"Matrix4fv\"; value: number | number[] }> }",
+        "typeImport": "ShaderSpec",
         "displayType": "undefined | { fragment: string; uniforms?: undefined | Record<string, { type: \"1f\" | \"1i\" | \"1fv\" | \"2f\" | \"3f\" | \"3fv\" | \"4f\" | \"4fv\" | \"Matrix2fv\" | \"Matrix3fv\" | \"Matrix4fv\"; value: number | number[] }> }"
       },
       {
@@ -631,6 +683,16 @@
     "className": "KaiAvatarElement",
     "displayName": "Avatar",
     "props": [
+      {
+        "name": "theme",
+        "type": "\"light\" | \"dark\" | \"auto\"",
+        "optional": true,
+        "scalar": true,
+        "description": "Color mode (`auto` follows prefers-color-scheme).",
+        "default": "'auto'",
+        "universal": true,
+        "displayType": "\"light\" | \"dark\" | \"auto\""
+      },
       {
         "name": "src",
         "type": "undefined | string",
@@ -652,7 +714,7 @@
         "type": "undefined | string",
         "optional": true,
         "scalar": true,
-        "description": "Short text shown when there's no image — usually initials (e.g. \"JD\", \"AI\").",
+        "description": "Short text shown when there's no image, usually initials (e.g. \"JD\", \"AI\").",
         "default": "''",
         "displayType": "undefined | string"
       },
@@ -682,6 +744,16 @@
     "className": "KaiBadgeElement",
     "displayName": "Badge",
     "props": [
+      {
+        "name": "theme",
+        "type": "\"light\" | \"dark\" | \"auto\"",
+        "optional": true,
+        "scalar": true,
+        "description": "Color mode (`auto` follows prefers-color-scheme).",
+        "default": "'auto'",
+        "universal": true,
+        "displayType": "\"light\" | \"dark\" | \"auto\""
+      },
       {
         "name": "variant",
         "type": "undefined | \"default\" | \"count\" | \"citation\"",
@@ -702,6 +774,13 @@
       }
     ],
     "tokens": [],
+    "slots": [
+      {
+        "name": "",
+        "mode": "inject",
+        "doc": "The badge's label: text, or a small inline icon plus text."
+      }
+    ],
     "parts": [
       {
         "name": "badge",
@@ -715,12 +794,22 @@
     "className": "KaiButtonElement",
     "displayName": "Button",
     "props": [
+      {
+        "name": "theme",
+        "type": "\"light\" | \"dark\" | \"auto\"",
+        "optional": true,
+        "scalar": true,
+        "description": "Color mode (`auto` follows prefers-color-scheme).",
+        "default": "'auto'",
+        "universal": true,
+        "displayType": "\"light\" | \"dark\" | \"auto\""
+      },
       {
         "name": "variant",
         "type": "undefined | \"default\" | \"subtle\" | \"ghost\" | \"outline\" | \"destructive\"",
         "optional": true,
         "scalar": true,
-        "description": "Visual style. `default` (filled), `subtle` (muted text, hover tint — the toolbar icon look), `ghost` (transparent, hover fill), `outline`, or `destructive`. Defaults to `default`.",
+        "description": "Visual style. `default` (filled), `subtle` (muted text, hover tint, the toolbar icon look), `ghost` (transparent, hover fill), `outline`, or `destructive`. Defaults to `default`.",
         "default": "'default'",
         "displayType": "undefined | \"default\" | \"subtle\" | \"ghost\" | \"outline\" | \"destructive\""
       },
@@ -754,7 +843,7 @@
         "type": "undefined | string",
         "optional": true,
         "scalar": true,
-        "description": "Accessible name. REQUIRED for icon-only buttons (no visible text); ignored when you slot visible text, which already names the button.",
+        "description": "Accessible name. REQUIRED for icon-only buttons (no visible text); ignored when you slot visible text, which already names the button. An `aria-label` on top of visible text REPLACES that name rather than adding to it, so a button reading \"Save\" that answers to \"Submit\" is unusable by speech input (WCAG 2.5.3, Label in Name). The visible text wins. An `icon` / `icon-sm` size hides the slot, which makes the button icon-only whatever you slotted, so `label` is what names it there.",
         "displayType": "undefined | string"
       },
       {
@@ -771,7 +860,7 @@
         "type": "undefined | false | true",
         "optional": true,
         "scalar": true,
-        "description": "Stretch the button to the full width of its container (a block button) — e.g. a card CTA or a stacked action. Attribute: `full`.",
+        "description": "Stretch the button to the full width of its container (a block button), e.g. a card CTA or a stacked action. Attribute: `full`.",
         "default": "false",
         "displayType": "undefined | false | true"
       },
@@ -819,7 +908,7 @@
         "name": "click",
         "params": "",
         "returns": "void",
-        "description": "Programmatically activate the button — runs the same path as a user click and fires kai-click. Forwarding to the inner button means `disabled` is respected automatically."
+        "description": "Programmatically activate the button. Runs the same path as a user click and fires kai-click. Forwarding to the inner button means `disabled` is respected automatically."
       }
     ],
     "composedFrom": [
@@ -831,6 +920,11 @@
     ],
     "tokens": [],
     "slots": [
+      {
+        "name": "",
+        "mode": "inject",
+        "doc": "The button's label. Omit it for an icon-only button (pair with `aria-label`)."
+      },
       {
         "name": "icon",
         "mode": "replace",
@@ -850,6 +944,16 @@
     "className": "KaiCardElement",
     "displayName": "Card",
     "props": [
+      {
+        "name": "theme",
+        "type": "\"light\" | \"dark\" | \"auto\"",
+        "optional": true,
+        "scalar": true,
+        "description": "Color mode (`auto` follows prefers-color-scheme).",
+        "default": "'auto'",
+        "universal": true,
+        "displayType": "\"light\" | \"dark\" | \"auto\""
+      },
       {
         "name": "appearance",
         "type": "undefined | \"outlined\" | \"filled\" | \"plain\" | \"accent\"",
@@ -864,7 +968,7 @@
         "type": "undefined | \"vertical\" | \"horizontal\" | \"responsive\"",
         "optional": true,
         "scalar": true,
-        "description": "`vertical` (default, media on top) | `horizontal` (media at the start) | `responsive` (horizontal when the card's container is wide enough, else vertical — a container query on the card's own width). Attribute: `orientation`.",
+        "description": "`vertical` (default, media on top) | `horizontal` (media at the start) | `responsive` (horizontal when the card's container is wide enough, else vertical, via a container query on the card's own width). Attribute: `orientation`.",
         "default": "'vertical'",
         "displayType": "undefined | \"vertical\" | \"horizontal\" | \"responsive\""
       },
@@ -953,6 +1057,11 @@
     ],
     "tokens": [],
     "slots": [
+      {
+        "name": "",
+        "mode": "inject",
+        "doc": "The card body, below the header/media regions."
+      },
       {
         "name": "media",
         "mode": "inject",
@@ -1017,12 +1126,25 @@
     "className": "KaiCardsElement",
     "displayName": "Cards",
     "props": [
+      {
+        "name": "theme",
+        "type": "\"light\" | \"dark\" | \"auto\"",
+        "optional": true,
+        "scalar": true,
+        "description": "Color mode (`auto` follows prefers-color-scheme).",
+        "default": "'auto'",
+        "universal": true,
+        "displayType": "\"light\" | \"dark\" | \"auto\""
+      },
       {
         "name": "cards",
         "type": "undefined | { type: string; id: string; data: unknown; title?: undefined | string; resolution?: undefined | { kind: \"action\"; action: string; payload?: unknown; at?: undefined | string } | { kind: \"submit\"; data: unknown; at?: undefined | string } | { kind: \"dismissed\"; at?: undefined | string } | { kind: \"expired\"; reason?: undefined | string; at?: undefined | string } }[]",
         "optional": true,
         "scalar": false,
         "description": "The stream of card envelopes to render. Set as a JS PROPERTY: `el.cards = [...]`.",
+        "typeName": "CardEnvelope[]",
+        "typeShape": "{ type: string; id: string; data: unknown; title?: undefined | string; resolution?: undefined | { kind: \"action\"; action: string; payload?: unknown; at?: undefined | string } | { kind: \"submit\"; data: unknown; at?: undefined | string } | { kind: \"dismissed\"; at?: undefined | string } | { kind: \"expired\"; reason?: undefined | string; at?: undefined | string } }[]",
+        "typeImport": "CardEnvelope",
         "displayType": "undefined | { type: string; id: string; data: unknown; title?: undefined | string; resolution?: undefined | { kind: \"action\"; action: string; payload?: unknown; at?: undefined | string } | { kind: \"submit\"; data: unknown; at?: undefined | string } | { kind: \"dismissed\"; at?: undefined | string } | { kind: \"expired\"; reason?: undefined | string; at?: undefined | string } }[]"
       },
       {
@@ -1033,20 +1155,40 @@
         "description": "Optional type→tag overrides/additions (merged over the built-ins). Property: `el.types`. Typed as a plain string map (not the `CardTagMap` alias) so the generated React wrapper inlines it instead of emitting an unresolved named type.",
         "displayType": "undefined | Record<string, string>"
       },
+      {
+        "name": "schemas",
+        "type": "undefined | Record<string, object>",
+        "optional": true,
+        "scalar": false,
+        "description": "JSON Schemas for the card types this app renders, keyed by envelope type. The companion of `types`, which says what DRAWS a card while this says what a VALID one looks like. An OBJECT, so it is a JS property only: `el.schemas = { 'pricing-table': pricingSchema }`, never an attribute. `createCardRegistry(...).validationSchemas` is exactly this shape. Without it the kit validates its own seven built-ins and leaves your own card type, the one your app actually cares about, as the only unchecked thing on screen. A schema here WINS over a built-in of the same name, matching `mergeCardTags`, where your entry is spread over ours. Typed `Record<string, object>` rather than `Record<string, JsonSchema>` deliberately: an imported `.json` schema widens `\"type\"` to `string`, and an authored one carries `$schema`/`title`/`description`/`additionalProperties`, so the tighter type would reject both of the normal ways to supply one. See `CardSchemaMap` in components/card-renderer.tsx.",
+        "displayType": "undefined | Record<string, object>"
+      },
       {
         "name": "policy",
         "type": "undefined | { onSubmit?: undefined | (cardId: string, data: unknown) => void; onAction?: undefined | (cardId: string, action: string, payload?: unknown) => void; onSendPrompt?: undefined | (text: string, opts: { mode: \"compose\" | \"send\"; context?: unknown; }) => void; onOpen?: undefined | (url: string, target: \"tab\" | \"artifact\") => void; onState?: undefined | (cardId: string, patch: unknown) => void; onDismiss?: undefined | (cardId: string) => void; onReopen?: undefined | (cardId: string) => void; onError?: undefined | (cardId: string, message: string) => void; maxSendPromptMode?: undefined | \"compose\" | \"send\" }",
         "optional": true,
         "scalar": false,
         "description": "Optional CardPolicy handling child events. Property: `el.policy`.",
+        "typeName": "CardPolicy",
+        "typeShape": "{ onSubmit?: undefined | (cardId: string, data: unknown) => void; onAction?: undefined | (cardId: string, action: string, payload?: unknown) => void; onSendPrompt?: undefined | (text: string, opts: { mode: \"compose\" | \"send\"; context?: unknown; }) => void; onOpen?: undefined | (url: string, target: \"tab\" | \"artifact\") => void; onState?: undefined | (cardId: string, patch: unknown) => void; onDismiss?: undefined | (cardId: string) => void; onReopen?: undefined | (cardId: string) => void; onError?: undefined | (cardId: string, message: string) => void; maxSendPromptMode?: undefined | \"compose\" | \"send\" }",
+        "typeImport": "CardPolicy",
         "displayType": "undefined | { onSubmit?: undefined | (cardId: string, data: unknown) => void; onAction?: undefined | (cardId: string, action: string, payload?: unknown) => void; onSendPrompt?: undefined | (text: string, opts: { mode: \"compose\" | \"send\"; context?: unknown; }) => void; onOpen?: undefined | (url: string, target: \"tab\" | \"artifact\") => void; onState?: undefined | (cardId: string, patch: unknown) => void; onDismiss?: undefined | (cardId: string) => void; onReopen?: undefined | (cardId: string) => void; onError?: undefined | (cardId: string, message: string) => void; maxSendPromptMode?: undefined | \"compose\" | \"send\" }"
+      },
+      {
+        "name": "validateCards",
+        "type": "undefined | false | true",
+        "optional": true,
+        "scalar": true,
+        "description": "Validate each envelope's `data` against the schema for its type before rendering it, using a built-in's own schema or yours from `schemas`. Default `true`; set `validate-cards=\"false\"` (or `el.validateCards = false`) to opt out. A hard failure (wrong type, a missing required field) renders a diagnostic naming the field instead of the card; a soft failure (bounds) renders the card unchanged. Both emit a contract `error` event. On in production too: a model emitting a bad shape is a production failure mode, so stripping the check there would hide it from exactly the person who needs to see it.",
+        "default": "true",
+        "displayType": "undefined | false | true"
       }
     ],
     "events": [
       {
         "name": "kai-card-resolved",
         "detail": "{ cardId: string; resolution: { kind: \"action\"; action: string; payload?: unknown; at?: undefined | string } | { kind: \"submit\"; data: unknown; at?: undefined | string } | { kind: \"dismissed\"; at?: undefined | string } | { kind: \"expired\"; reason?: undefined | string; at?: undefined | string } }",
-        "description": "A child card transitioned to a resolved/deferred state (an action was chosen, a form/tasks submission landed, or it was dismissed) — re-emitted off the host as a non-bubbling convenience event so a consumer can observe resolution centrally without diffing the cards array. `detail` = `{ cardId, resolution }`. (A `reopen` un-resolves a card and has no `CardResolution`, so it does NOT fire this — observe reopen via the underlying bubbling `kai-card` event.)",
+        "description": "A child card transitioned to a resolved/deferred state (an action was chosen, a form/tasks submission landed, or it was dismissed). Re-emitted off the host as a non-bubbling convenience event so a consumer can observe resolution centrally without diffing the cards array. `detail` = `{ cardId, resolution }`. (A `reopen` un-resolves a card and has no `CardResolution`, so it does NOT fire this; observe reopen via the underlying bubbling `kai-card` event.)",
         "displayDetail": "{ cardId: string; resolution: { kind: \"action\"; action: string; payload?: unknown; at?: undefined | string } | { kind: \"submit\"; data: unknown; at?: undefined | string } | { kind: \"dismissed\"; at?: undefined | string } | { kind: \"expired\"; reason?: undefined | string; at?: undefined | string } }"
       }
     ],
@@ -1055,13 +1197,13 @@
         "name": "resolve",
         "params": "cardId: string, resolution: CardResolution",
         "returns": "void",
-        "description": "Programmatically resolve a child card by id: set that envelope's `resolution` so the child re-renders into its read-only/resolved view — the imperative twin of the consumer mutating the cards array. No-op for an unknown id."
+        "description": "Programmatically resolve a child card by id: set that envelope's `resolution` so the child re-renders into its read-only/resolved view. The imperative twin of the consumer mutating the cards array. No-op for an unknown id."
       },
       {
         "name": "dismiss",
         "params": "cardId: string",
         "returns": "void",
-        "description": "Collapse a card to its re-openable stub from the host side — convenience for `resolve(cardId, { kind: 'dismissed' })`."
+        "description": "Collapse a card to its re-openable stub from the host side. Convenience for `resolve(cardId, { kind: 'dismissed' })`."
       },
       {
         "name": "getCard",
@@ -1084,23 +1226,34 @@
     "className": "KaiChainOfThoughtElement",
     "displayName": "ChainOfThought",
     "props": [
+      {
+        "name": "theme",
+        "type": "\"light\" | \"dark\" | \"auto\"",
+        "optional": true,
+        "scalar": true,
+        "description": "Color mode (`auto` follows prefers-color-scheme).",
+        "default": "'auto'",
+        "universal": true,
+        "displayType": "\"light\" | \"dark\" | \"auto\""
+      },
       {
         "name": "steps",
-        "type": "{ label: string; content?: undefined | string; id?: undefined | string }[]",
-        "optional": false,
+        "type": "undefined | { label: string; content?: undefined | string; id?: undefined | string }[]",
+        "optional": true,
         "scalar": false,
-        "description": "The reasoning steps. Set as a JS property. Compound sub-parts collapse to this one data model (Route 1). Each `{ label, content?, id? }`.",
+        "description": "The reasoning steps. Set as a JS property. Compound sub-parts collapse to this one data model (Route 1). Each `{ label, content?, id? }`. Omit to supply the steps as `<kai-step>` light-DOM children instead; when both are present the property's steps come first.",
         "typeName": "ChainOfThoughtStepData[]",
         "typeShape": "{ label: string; content?: undefined | string; id?: undefined | string }[]",
         "default": "[]",
-        "displayType": "{ label: string; content?: undefined | string; id?: undefined | string }[]"
+        "typeImport": "ChainOfThoughtStepData",
+        "displayType": "undefined | { label: string; content?: undefined | string; id?: undefined | string }[]"
       },
       {
         "name": "type",
         "type": "undefined | \"single\" | \"multiple\"",
         "optional": true,
         "scalar": true,
-        "description": "Open mode: `'multiple'` (default — any number of steps open at once) or `'single'` (at most one open; opening a step closes the others).",
+        "description": "Open mode: `'multiple'` (default, any number of steps open at once) or `'single'` (at most one open; opening a step closes the others).",
         "displayType": "undefined | \"single\" | \"multiple\""
       },
       {
@@ -1116,7 +1269,7 @@
         "type": "undefined | string | string[]",
         "optional": true,
         "scalar": false,
-        "description": "Uncontrolled INITIAL open step key(s) — seeds which steps render expanded. Ignored once `value` is provided. Set as a JS property.",
+        "description": "Uncontrolled INITIAL open step key(s), seeding which steps render expanded. Ignored once `value` is provided. Set as a JS property.",
         "displayType": "undefined | string | string[]"
       }
     ],
@@ -1124,7 +1277,7 @@
       {
         "name": "kai-value-change",
         "detail": "{ value: string | string[] }",
-        "description": "The open set changed — by user click OR an expand()/collapse()/toggle() call. `value` is a string in `single` mode, a string[] in `multiple` mode. (Maps Radix Accordion's onValueChange.)",
+        "description": "The open set changed, by user click OR an expand()/collapse()/toggle() call. `value` is a string in `single` mode, a string[] in `multiple` mode. (Maps Radix Accordion's onValueChange.)",
         "displayDetail": "{ value: string | string[] }"
       }
     ],
@@ -1133,13 +1286,13 @@
         "name": "expand",
         "params": "index?: number",
         "returns": "void",
-        "description": "Open one step's detail by index, or — with no arg — ALL steps. In `single` mode opening one step closes the others (expand-all keeps the last)."
+        "description": "Open one step's detail by index, or ALL steps when called with no arg. In `single` mode opening one step closes the others (expand-all keeps the last)."
       },
       {
         "name": "collapse",
         "params": "index?: number",
         "returns": "void",
-        "description": "Close one step's detail by index, or — with no arg — ALL steps."
+        "description": "Close one step's detail by index, or ALL steps when called with no arg."
       },
       {
         "name": "toggle",
@@ -1155,7 +1308,18 @@
         "storyId": "solid-advanced-elements-chainofthoughtaccordion--docs"
       }
     ],
-    "tokens": []
+    "tokens": [],
+    "declarativeChildren": [
+      {
+        "tag": "kai-step",
+        "attributes": [
+          "label",
+          "step-id"
+        ],
+        "text": true,
+        "description": "Parse a single light-DOM `<kai-step>` element into a `Step` descriptor. Attribute mapping: - `label` → Step.label (the always-visible heading) - `step-id` → Step.id (optional stable open-set key) - textContent → Step.content (optional expandable detail)"
+      }
+    ]
   },
   {
     "tag": "kai-chat",
@@ -1163,16 +1327,23 @@
     "displayName": "Chat",
     "props": [
       {
-        "name": "messages",
-        "type": "{ id: string; role: \"user\" | \"assistant\"; content: string; reasoning?: undefined | { text: string; label?: undefined | string }; tools?: undefined | { type: string; state: \"input-streaming\" | \"input-available\" | \"output-available\" | \"output-error\"; input?: undefined | Record<string, unknown>; output?: undefined | Record<string, unknown>; toolCallId?: undefined | string; errorText?: undefined | string }[]; attachments?: undefined | { id: string; type: \"file\" | \"source-document\"; filename?: undefined | string; mediaType?: undefined | string; url?: undefined | string; title?: undefined | string }[]; actions?: undefined | (\"copy\" | \"like\" | \"dislike\" | \"regenerate\" | \"edit\" | { id: string; label: string; icon?: undefined | string; tooltip?: undefined | string })[]; avatar?: undefined | { src?: undefined | string; fallback?: undefined | string; alt?: undefined | string }; feedback?: undefined | \"like\" | \"dislike\" }[]",
-        "optional": false,
-        "scalar": false,
-        "description": "The full message thread to render, newest last. Each entry carries its role, content, and optional reasoning/tools/attachments/actions. Set as a JS property (`el.messages = [...]`).",
-        "typeName": "ChatMessage[]",
-        "typeShape": "{ id: string; role: \"user\" | \"assistant\"; content: string; reasoning?: undefined | { text: string; label?: undefined | string }; tools?: undefined | { type: string; state: \"input-streaming\" | \"input-available\" | \"output-available\" | \"output-error\"; input?: undefined | Record<string, unknown>; output?: undefined | Record<string, unknown>; toolCallId?: undefined | string; errorText?: undefined | string }[]; attachments?: undefined | { id: string; type: \"file\" | \"source-document\"; filename?: undefined | string; mediaType?: undefined | string; url?: undefined | string; title?: undefined | string }[]; actions?: undefined | (\"copy\" | \"like\" | \"dislike\" | \"regenerate\" | \"edit\" | { id: string; label: string; icon?: undefined | string; tooltip?: undefined | string })[]; avatar?: undefined | { src?: undefined | string; fallback?: undefined | string; alt?: undefined | string }; feedback?: undefined | \"like\" | \"dislike\" }[]",
-        "default": "[]",
-        "typeImport": "ChatMessage",
-        "displayType": "{ id: string; role: \"user\" | \"assistant\"; content: string; reasoning?: undefined | { text: string; label?: undefined | string }; tools?: undefined | { type: string; state: \"input-streaming\" | \"input-available\" | \"output-available\" | \"output-error\"; input?: undefined | Record<string, unknown>; output?: undefined | Record<string, unknown>; toolCallId?: undefined | string; errorText?: undefined | string }[]; attachments?: undefined | { id: string; type: \"file\" | \"source-document\"; filename?: undefined | string; mediaType?: undefined | string; url?: undefined | string; title?: undefined | string }[]; actions?: undefined | (\"copy\" | \"like\" | \"dislike\" | \"regenerate\" | \"edit\" | { id: string; label: string; icon?: undefined | string; tooltip?: undefined | string })[]; avatar?: undefined | { src?: undefined | string; fallback?: undefined | string; alt?: undefined | string }; feedback?: undefined | \"like\" | \"dislike\" }[]"
+        "name": "theme",
+        "type": "\"light\" | \"dark\" | \"auto\"",
+        "optional": true,
+        "scalar": true,
+        "description": "Color mode (`auto` follows prefers-color-scheme).",
+        "default": "'auto'",
+        "universal": true,
+        "displayType": "\"light\" | \"dark\" | \"auto\""
+      },
+      {
+        "name": "search",
+        "type": "undefined | false | true",
+        "optional": true,
+        "scalar": true,
+        "description": "Show a Search (Globe) button in the input toolbar; fires a `search` event.",
+        "default": "false",
+        "displayType": "undefined | false | true"
       },
       {
         "name": "value",
@@ -1228,12 +1399,12 @@
       },
       {
         "name": "proseSize",
-        "type": "undefined | \"sm\" | \"lg\" | \"xs\" | \"base\"",
+        "type": "undefined | \"xs\" | \"sm\" | \"base\" | \"lg\"",
         "optional": true,
         "scalar": true,
         "description": "Body/prose font scale for rendered markdown (`'xs' | 'sm' | 'base' | 'lg'`). Defaults to `'sm'`.",
         "default": "'sm'",
-        "displayType": "undefined | \"sm\" | \"lg\" | \"xs\" | \"base\""
+        "displayType": "undefined | \"xs\" | \"sm\" | \"base\" | \"lg\""
       },
       {
         "name": "codeTheme",
@@ -1267,6 +1438,9 @@
         "optional": true,
         "scalar": false,
         "description": "Optional model list. When set (>1 model) a ModelSwitcher is shown in the header and a `kai-model-change` event fires on selection.",
+        "typeName": "ModelOption[]",
+        "typeShape": "{ id: string; name: string; provider?: undefined | string; description?: undefined | string; group?: undefined | string }[]",
+        "typeImport": "ModelOption",
         "displayType": "undefined | { id: string; name: string; provider?: undefined | string; description?: undefined | string; group?: undefined | string }[]"
       },
       {
@@ -1283,6 +1457,9 @@
         "optional": true,
         "scalar": false,
         "description": "Optional context-window token usage. When set, a Context token meter is shown in the header.",
+        "typeName": "ChatThreadContextUsage",
+        "typeShape": "{ usedTokens: number; maxTokens: number; inputTokens?: undefined | number; outputTokens?: undefined | number; estimatedCost?: undefined | number }",
+        "typeImport": "ChatThreadContextUsage",
         "displayType": "ContextData | undefined"
       },
       {
@@ -1299,7 +1476,7 @@
         "type": "undefined | false | true",
         "optional": true,
         "scalar": true,
-        "description": "Whether the host has `slot=\"header-start\"` content (left of the title) — set by the `<kai-chat>` facade so a custom control forces the header open.",
+        "description": "Whether the host has `slot=\"header-start\"` content (left of the title). Set by the `<kai-chat>` facade so a custom control forces the header open.",
         "displayType": "undefined | false | true"
       },
       {
@@ -1315,7 +1492,7 @@
         "type": "undefined | false | true",
         "optional": true,
         "scalar": true,
-        "description": "REPLACE — full custom header in place of the built-in title/model/context bar.",
+        "description": "REPLACE: full custom header in place of the built-in title/model/context bar.",
         "displayType": "undefined | false | true"
       },
       {
@@ -1323,7 +1500,7 @@
         "type": "undefined | false | true",
         "optional": true,
         "scalar": true,
-        "description": "INJECT — left sidebar column (e.g. a conversation list / your own nav).",
+        "description": "INJECT: left sidebar column (e.g. a conversation list / your own nav).",
         "displayType": "undefined | false | true"
       },
       {
@@ -1331,7 +1508,7 @@
         "type": "undefined | false | true",
         "optional": true,
         "scalar": true,
-        "description": "REPLACE — custom zero-state rendered in the message area while the thread is empty (replaces the empty message list only; the composer and its suggestions still render).",
+        "description": "REPLACE: custom zero-state rendered in the message area while the thread is empty (replaces the empty message list only; the composer and its suggestions still render).",
         "displayType": "undefined | false | true"
       },
       {
@@ -1339,7 +1516,7 @@
         "type": "undefined | false | true",
         "optional": true,
         "scalar": true,
-        "description": "REPLACE — full custom composer in place of the built-in prompt input. The projected content wires its own submit (the data-flow boundary).",
+        "description": "REPLACE: full custom composer in place of the built-in prompt input. The projected content wires its own submit (the data-flow boundary).",
         "displayType": "undefined | false | true"
       },
       {
@@ -1347,7 +1524,7 @@
         "type": "undefined | false | true",
         "optional": true,
         "scalar": true,
-        "description": "INJECT — accessory row just above the composer (e.g. extra actions).",
+        "description": "INJECT: accessory row just above the composer (e.g. extra actions).",
         "displayType": "undefined | false | true"
       },
       {
@@ -1355,16 +1532,7 @@
         "type": "undefined | false | true",
         "optional": true,
         "scalar": true,
-        "description": "INJECT — footer row below the composer (disclaimers, token meter, …).",
-        "displayType": "undefined | false | true"
-      },
-      {
-        "name": "search",
-        "type": "undefined | false | true",
-        "optional": true,
-        "scalar": true,
-        "description": "Show a Search (Globe) button in the input toolbar; fires a `search` event.",
-        "default": "false",
+        "description": "INJECT: footer row below the composer (disclaimers, token meter, …).",
         "displayType": "undefined | false | true"
       },
       {
@@ -1381,7 +1549,10 @@
         "type": "undefined | { char: string; kind: string; items?: undefined | { id: string; label: string; icon?: undefined | string; description?: undefined | string; group?: undefined | string; kind?: undefined | string; promptText?: undefined | string; data?: undefined | Record<string, unknown> }[] }[]",
         "optional": true,
         "scalar": false,
-        "description": "Rich entity triggers — each `{ char, kind, items }` opens a caret-anchored menu that inserts an atomic pill (`/` skills, `@` agents/plugins). Set as a JS property; forwarded to the input.",
+        "description": "Rich entity triggers. Each `{ char, kind, items }` opens a caret-anchored menu that inserts an atomic pill (`/` skills, `@` agents/plugins). Set as a JS property; forwarded to the input.",
+        "typeName": "TriggerDef[]",
+        "typeShape": "{ char: string; kind: string; items?: undefined | { id: string; label: string; icon?: undefined | string; description?: undefined | string; group?: undefined | string; kind?: undefined | string; promptText?: undefined | string; data?: undefined | Record<string, unknown> }[] }[]",
+        "typeImport": "TriggerDef",
         "displayType": "undefined | { char: string; kind: string; items?: undefined | { id: string; label: string; icon?: undefined | string; description?: undefined | string; group?: undefined | string; kind?: undefined | string; promptText?: undefined | string; data?: undefined | Record<string, unknown> }[] }[]"
       },
       {
@@ -1400,6 +1571,42 @@
         "description": "Whether each message's action bar is always visible (`'always'`, default) or only revealed on hover of that message row (`'hover'`).",
         "default": "'always'",
         "displayType": "undefined | \"always\" | \"hover\""
+      },
+      {
+        "name": "accept",
+        "type": "undefined | string",
+        "optional": true,
+        "scalar": true,
+        "description": "Which attachment media types the user may stage, in HTML `accept` syntax: `<kai-chat accept=\"image/*,application/pdf\">`. A plain string, so unlike `messages` it DOES work as an attribute. Omitted means no filter. MEDIA TYPES ONLY -- exact (`image/png`) or subtype wildcard (`text/*`). HTML allows a file extension here and this does not: `accept=\".py\"` THROWS with the entry named, rather than silently resolving to a picker that accepts nothing. It can only NARROW what the kit can already encode: `accept=\"image/*\"` resolves to the four image formats both APIs take, not to every image type the OS offers. Pass the SAME string to `toOpenAIMessages(msgs, { accept })` and the picker and the wire cannot disagree -- both resolve it through `resolveMediaPolicy` against one declaration. That declaration is readable as `encodableMediaTypes()` from `@kitn.ai/ui/wire`, if you would rather build your own picker than use this prop.",
+        "displayType": "undefined | string"
+      },
+      {
+        "name": "messages",
+        "type": "undefined | { id: string; role: \"user\" | \"assistant\"; parts: ({ type: \"text\"; text: string; raw?: undefined | { source: string; payload: unknown } } | { type: \"reasoning\"; text: string; label?: undefined | string; index?: undefined | number; streamId?: undefined | string; signature?: undefined | string; raw?: undefined | { source: string; payload: unknown } } | { type: \"tool\"; tool: { type: string; kind?: undefined | \"command\" | \"file-change\" | \"search\" | \"fetch\" | \"mcp\" | \"image\" | \"generic\"; state: \"input-streaming\" | \"input-available\" | \"output-available\" | \"output-error\"; input?: undefined | Record<string, unknown>; rawInput?: undefined | string; output?: undefined | Record<string, unknown>; toolCallId?: undefined | string; errorText?: undefined | string; raw?: undefined | { source: string; payload: unknown } }; raw?: undefined | { source: string; payload: unknown } } | { type: \"card\"; envelope: { type: string; id: string; data: unknown; title?: undefined | string; resolution?: undefined | { kind: \"action\"; action: string; payload?: unknown; at?: undefined | string } | { kind: \"submit\"; data: unknown; at?: undefined | string } | { kind: \"dismissed\"; at?: undefined | string } | { kind: \"expired\"; reason?: undefined | string; at?: undefined | string } }; raw?: undefined | { source: string; payload: unknown } } | { type: \"source\"; source: { id?: undefined | string; url?: undefined | string; title?: undefined | string; snippet?: undefined | string; index?: undefined | number }; raw?: undefined | { source: string; payload: unknown } } | { type: \"file\"; attachment: { id: string; type: \"file\" | \"source-document\"; filename?: undefined | string; mediaType?: undefined | string; url?: undefined | string; title?: undefined | string }; raw?: undefined | { source: string; payload: unknown } })[]; actions?: undefined | (\"copy\" | \"like\" | \"dislike\" | \"regenerate\" | \"edit\" | { id: string; label: string; icon?: undefined | string; tooltip?: undefined | string })[]; avatar?: undefined | { src?: undefined | string; fallback?: undefined | string; alt?: undefined | string }; feedback?: undefined | \"like\" | \"dislike\" }[]",
+        "optional": true,
+        "scalar": false,
+        "description": "The full message thread to render, newest last. Each entry carries its role, ordered `parts`, and optional actions/avatar/feedback. Set as a JS property (`el.messages = [...]`); a NEW array reference per streaming chunk re-renders (mutating in place does not). Omit for an empty thread. Re-declared here (rather than inherited from `ChatThreadProps`) because the ELEMENT registers a `[]` default and renders the empty state without it, while the SolidJS `<ChatThread>` component still requires it. The facade hands it a validated array either way. Matches `<kai-thread>`.",
+        "typeName": "ChatMessage[]",
+        "typeShape": "{ id: string; role: \"user\" | \"assistant\"; parts: ({ type: \"text\"; text: string; raw?: undefined | { source: string; payload: unknown } } | { type: \"reasoning\"; text: string; label?: undefined | string; index?: undefined | number; streamId?: undefined | string; signature?: undefined | string; raw?: undefined | { source: string; payload: unknown } } | { type: \"tool\"; tool: { type: string; kind?: undefined | \"command\" | \"file-change\" | \"search\" | \"fetch\" | \"mcp\" | \"image\" | \"generic\"; state: \"input-streaming\" | \"input-available\" | \"output-available\" | \"output-error\"; input?: undefined | Record<string, unknown>; rawInput?: undefined | string; output?: undefined | Record<string, unknown>; toolCallId?: undefined | string; errorText?: undefined | string; raw?: undefined | { source: string; payload: unknown } }; raw?: undefined | { source: string; payload: unknown } } | { type: \"card\"; envelope: { type: string; id: string; data: unknown; title?: undefined | string; resolution?: undefined | { kind: \"action\"; action: string; payload?: unknown; at?: undefined | string } | { kind: \"submit\"; data: unknown; at?: undefined | string } | { kind: \"dismissed\"; at?: undefined | string } | { kind: \"expired\"; reason?: undefined | string; at?: undefined | string } }; raw?: undefined | { source: string; payload: unknown } } | { type: \"source\"; source: { id?: undefined | string; url?: undefined | string; title?: undefined | string; snippet?: undefined | string; index?: undefined | number }; raw?: undefined | { source: string; payload: unknown } } | { type: \"file\"; attachment: { id: string; type: \"file\" | \"source-document\"; filename?: undefined | string; mediaType?: undefined | string; url?: undefined | string; title?: undefined | string }; raw?: undefined | { source: string; payload: unknown } })[]; actions?: undefined | (\"copy\" | \"like\" | \"dislike\" | \"regenerate\" | \"edit\" | { id: string; label: string; icon?: undefined | string; tooltip?: undefined | string })[]; avatar?: undefined | { src?: undefined | string; fallback?: undefined | string; alt?: undefined | string }; feedback?: undefined | \"like\" | \"dislike\" }[]",
+        "default": "[]",
+        "typeImport": "ChatMessage",
+        "displayType": "undefined | { id: string; role: \"user\" | \"assistant\"; parts: ({ type: \"text\"; text: string; raw?: undefined | { source: string; payload: unknown } } | { type: \"reasoning\"; text: string; label?: undefined | string; index?: undefined | number; streamId?: undefined | string; signature?: undefined | string; raw?: undefined | { source: string; payload: unknown } } | { type: \"tool\"; tool: { type: string; kind?: undefined | \"command\" | \"file-change\" | \"search\" | \"fetch\" | \"mcp\" | \"image\" | \"generic\"; state: \"input-streaming\" | \"input-available\" | \"output-available\" | \"output-error\"; input?: undefined | Record<string, unknown>; rawInput?: undefined | string; output?: undefined | Record<string, unknown>; toolCallId?: undefined | string; errorText?: undefined | string; raw?: undefined | { source: string; payload: unknown } }; raw?: undefined | { source: string; payload: unknown } } | { type: \"card\"; envelope: { type: string; id: string; data: unknown; title?: undefined | string; resolution?: undefined | { kind: \"action\"; action: string; payload?: unknown; at?: undefined | string } | { kind: \"submit\"; data: unknown; at?: undefined | string } | { kind: \"dismissed\"; at?: undefined | string } | { kind: \"expired\"; reason?: undefined | string; at?: undefined | string } }; raw?: undefined | { source: string; payload: unknown } } | { type: \"source\"; source: { id?: undefined | string; url?: undefined | string; title?: undefined | string; snippet?: undefined | string; index?: undefined | number }; raw?: undefined | { source: string; payload: unknown } } | { type: \"file\"; attachment: { id: string; type: \"file\" | \"source-document\"; filename?: undefined | string; mediaType?: undefined | string; url?: undefined | string; title?: undefined | string }; raw?: undefined | { source: string; payload: unknown } })[]; actions?: undefined | (\"copy\" | \"like\" | \"dislike\" | \"regenerate\" | \"edit\" | { id: string; label: string; icon?: undefined | string; tooltip?: undefined | string })[]; avatar?: undefined | { src?: undefined | string; fallback?: undefined | string; alt?: undefined | string }; feedback?: undefined | \"like\" | \"dislike\" }[]"
+      },
+      {
+        "name": "cardTypes",
+        "type": "undefined | Record<string, string>",
+        "optional": true,
+        "scalar": false,
+        "description": "Optional card type -> custom-element tag overrides/additions for `card` parts (merged over the built-ins). Property: `el.cardTypes`. Typed as a plain string map (not the `CardTagMap` alias) so the generated React wrapper inlines it instead of emitting an unresolved named type.",
+        "displayType": "undefined | Record<string, string>"
+      },
+      {
+        "name": "cardSchemas",
+        "type": "undefined | Record<string, object>",
+        "optional": true,
+        "scalar": false,
+        "description": "JSON Schemas for the card types this app renders, keyed by envelope type. The companion of `cardTypes`, which says what DRAWS a card while this says what a VALID one looks like. An OBJECT, so it is a JS property only: `el.cardSchemas = { 'pricing-table': pricingSchema }`, never an attribute. `createCardRegistry(...).validationSchemas` is exactly this shape. Without it the kit validates its own seven built-ins and leaves your own card type, the one your app actually cares about, as the only unchecked thing on screen. A schema here WINS over a built-in of the same name. Typed `Record<string, object>` rather than `Record<string, JsonSchema>` deliberately: an imported `.json` schema widens `\"type\"` to `string`, and an authored one carries `$schema`/`title`/`description`/`additionalProperties`, so the tighter type would reject both of the normal ways to supply one.",
+        "displayType": "undefined | Record<string, object>"
       }
     ],
     "events": [
@@ -1409,6 +1616,12 @@
         "description": "The staged attachments changed (file added or removed). Carries the full current list so a consumer can react in real time.",
         "displayDetail": "{ attachments: { id: string; type: \"file\" | \"source-document\"; filename?: undefined | string; mediaType?: undefined | string; url?: undefined | string; title?: undefined | string }[] }"
       },
+      {
+        "name": "kai-attachments-rejected",
+        "detail": "{ rejected: { filename: string; mediaType: string; reason: \"filtered\" | \"unsupported\" }[] }",
+        "description": "One or more picked files were refused because `accept` excluded them. The element renders NO message of its own: it reports the facts (name, media type, whether the kit could have sent it) and what the user should see is the application's call. Only ever fires when `accept` is set.",
+        "displayDetail": "{ rejected: { filename: string; mediaType: string; reason: \"filtered\" | \"unsupported\" }[] }"
+      },
       {
         "name": "kai-message-action",
         "detail": "{ messageId: string; action: string; state?: undefined | \"on\" | \"off\" }",
@@ -1457,31 +1670,31 @@
         "name": "focus",
         "params": "options?: FocusOptions",
         "returns": "void",
-        "description": ""
+        "description": "Focus the composer, meaning the contenteditable (or textarea) inside the shadow root. A native `focus()` on the host lands on the host itself and never reaches it, so this is the only way to focus the input programmatically."
       },
       {
         "name": "blur",
         "params": "",
         "returns": "void",
-        "description": ""
+        "description": "Blur whatever currently holds focus inside the shadow root. The companion to `focus()`, for the same reason: a native `blur()` on the host misses the real focus target."
       },
       {
         "name": "clear",
         "params": "",
         "returns": "void",
-        "description": ""
+        "description": "Empty the COMPOSER: drops the draft text and every staged attachment, then fires `kai-value-change` with `''`. It does NOT touch the thread. `messages` is the consumer's own state, so clearing history stays the consumer's call."
       },
       {
         "name": "send",
         "params": "",
         "returns": "void",
-        "description": ""
+        "description": "Submit whatever the composer currently holds, on the same path as Enter or the send button: fires `kai-submit` with that value plus the staged attachments, then drops the attachments. It takes no argument, so to send text the user never typed, set `el.value` first. There is no empty-check, so an empty composer still fires. The draft is cleared afterwards only when `value` is uncontrolled; a controlled host owns its value and clears it itself. Named `send`, not `submit`, to match the shared vocabulary."
       },
       {
         "name": "scrollToBottom",
         "params": "behavior?: ScrollBehavior",
         "returns": "void",
-        "description": ""
+        "description": "Scroll the message viewport to the newest message. Defaults to `'smooth'`; pass `'instant'` to jump without animating."
       }
     ],
     "composedFrom": [
@@ -1518,7 +1731,7 @@
       {
         "name": "empty",
         "mode": "replace",
-        "doc": "Custom zero-state rendered in the message area while the thread is empty. Replaces the empty message list only — the composer and any suggestions still render."
+        "doc": "Custom zero-state rendered in the message area while the thread is empty. Replaces the empty message list only; the composer and any suggestions still render."
       },
       {
         "name": "composer",
@@ -1562,6 +1775,16 @@
     "className": "KaiCheckpointElement",
     "displayName": "Checkpoint",
     "props": [
+      {
+        "name": "theme",
+        "type": "\"light\" | \"dark\" | \"auto\"",
+        "optional": true,
+        "scalar": true,
+        "description": "Color mode (`auto` follows prefers-color-scheme).",
+        "default": "'auto'",
+        "universal": true,
+        "displayType": "\"light\" | \"dark\" | \"auto\""
+      },
       {
         "name": "label",
         "type": "undefined | string",
@@ -1580,12 +1803,12 @@
       },
       {
         "name": "variant",
-        "type": "undefined | \"default\" | \"ghost\" | \"outline\"",
+        "type": "undefined | \"ghost\" | \"default\" | \"outline\"",
         "optional": true,
         "scalar": true,
         "description": "Visual button style.",
         "default": "'ghost'",
-        "displayType": "undefined | \"default\" | \"ghost\" | \"outline\""
+        "displayType": "undefined | \"ghost\" | \"default\" | \"outline\""
       },
       {
         "name": "size",
@@ -1630,13 +1853,26 @@
     "className": "KaiChoiceElement",
     "displayName": "Choice",
     "props": [
+      {
+        "name": "theme",
+        "type": "\"light\" | \"dark\" | \"auto\"",
+        "optional": true,
+        "scalar": true,
+        "description": "Color mode (`auto` follows prefers-color-scheme).",
+        "default": "'auto'",
+        "universal": true,
+        "displayType": "\"light\" | \"dark\" | \"auto\""
+      },
       {
         "name": "data",
-        "type": "undefined | Record<string, unknown>",
+        "type": "undefined | { prompt?: undefined | string; options: { id: string; label: string; description?: undefined | string; media?: undefined | { image?: undefined | string; imageAlt?: undefined | string; icon?: undefined | string }; meta?: undefined | string; recommended?: undefined | false | true; disabled?: undefined | false | true; payload?: unknown }[]; allowOther?: undefined | false | true | { label?: undefined | string; placeholder?: undefined | string }; submitLabel?: undefined | string; dismissible?: undefined | false | true }",
         "optional": true,
         "scalar": false,
         "description": "The choice definition (the CardEnvelope.data). Set as a JS PROPERTY: `el.data = { prompt, options:[…], allowOther?, submitLabel? }`. Import `ChoiceCardData` from `@kitn.ai/ui` for the full shape.",
-        "displayType": "undefined | Record<string, unknown>"
+        "typeName": "ChoiceCardData",
+        "typeShape": "{ prompt?: undefined | string; options: { id: string; label: string; description?: undefined | string; media?: undefined | { image?: undefined | string; imageAlt?: undefined | string; icon?: undefined | string }; meta?: undefined | string; recommended?: undefined | false | true; disabled?: undefined | false | true; payload?: unknown }[]; allowOther?: undefined | false | true | { label?: undefined | string; placeholder?: undefined | string }; submitLabel?: undefined | string; dismissible?: undefined | false | true }",
+        "typeImport": "ChoiceCardData",
+        "displayType": "undefined | { prompt?: undefined | string; options: { id: string; label: string; description?: undefined | string; media?: undefined | { image?: undefined | string; imageAlt?: undefined | string; icon?: undefined | string }; meta?: undefined | string; recommended?: undefined | false | true; disabled?: undefined | false | true; payload?: unknown }[]; allowOther?: undefined | false | true | { label?: undefined | string; placeholder?: undefined | string }; submitLabel?: undefined | string; dismissible?: undefined | false | true }"
       },
       {
         "name": "cardId",
@@ -1667,7 +1903,7 @@
         "type": "undefined | string",
         "optional": true,
         "scalar": true,
-        "description": "Controlled selection — the selected option id. When set, the consumer owns the current pick (RadioGroup `value`). Attribute: `value`.",
+        "description": "Controlled selection: the selected option id. When set, the consumer owns the current pick (RadioGroup `value`). Attribute: `value`.",
         "displayType": "undefined | string"
       },
       {
@@ -1706,25 +1942,25 @@
         "name": "select",
         "params": "optionId: string",
         "returns": "void",
-        "description": "Select an option by id locally — no emit, fires kai-value-change (same as a row click). Lets a consumer pre-highlight or drive selection externally."
+        "description": "Select an option by id locally: no emit, fires kai-value-change (same as a row click). Lets a consumer pre-highlight or drive selection externally."
       },
       {
         "name": "send",
         "params": "",
         "returns": "void",
-        "description": "Submit the current selection — emits the `action` verb on kai-card and resolves the card (single-shot). Named `send`, not `submit`, per the shared vocabulary."
+        "description": "Submit the current selection: emits the `action` verb on kai-card and resolves the card (single-shot). Named `send`, not `submit`, per the shared vocabulary."
       },
       {
         "name": "dismiss",
         "params": "",
         "returns": "void",
-        "description": "Trigger the dismiss path — emits `dismiss` on kai-card and optimistically collapses the card to its re-openable stub."
+        "description": "Trigger the dismiss path: emits `dismiss` on kai-card and optimistically collapses the card to its re-openable stub."
       },
       {
         "name": "reopen",
         "params": "",
         "returns": "void",
-        "description": "Re-open a dismissed card from its stub — emits `reopen` on kai-card."
+        "description": "Re-open a dismissed card from its stub: emits `reopen` on kai-card."
       }
     ],
     "composedFrom": [
@@ -1741,6 +1977,16 @@
     "className": "KaiCoachmarkElement",
     "displayName": "Coachmark",
     "props": [
+      {
+        "name": "theme",
+        "type": "\"light\" | \"dark\" | \"auto\"",
+        "optional": true,
+        "scalar": true,
+        "description": "Color mode (`auto` follows prefers-color-scheme).",
+        "default": "'auto'",
+        "universal": true,
+        "displayType": "\"light\" | \"dark\" | \"auto\""
+      },
       {
         "name": "open",
         "type": "undefined | false | true",
@@ -1783,11 +2029,11 @@
       },
       {
         "name": "tone",
-        "type": "undefined | \"error\" | \"primary\" | \"info\" | \"success\" | \"warning\"",
+        "type": "undefined | \"primary\" | \"info\" | \"success\" | \"warning\" | \"error\"",
         "optional": true,
         "scalar": true,
-        "description": "Color tone: `primary` (default, theme accent), `info` (blue), `success` (green), `warning` (amber), or `error` (red) — reusing the kit's tool hues.",
-        "displayType": "undefined | \"error\" | \"primary\" | \"info\" | \"success\" | \"warning\""
+        "description": "Color tone: `primary` (default, theme accent), `info` (blue), `success` (green), `warning` (amber), or `error` (red), reusing the kit's tool hues.",
+        "displayType": "undefined | \"primary\" | \"info\" | \"success\" | \"warning\" | \"error\""
       },
       {
         "name": "arrow",
@@ -1842,6 +2088,11 @@
     ],
     "tokens": [],
     "slots": [
+      {
+        "name": "",
+        "mode": "inject",
+        "doc": "The ANCHOR the coachmark points at: the element it attaches to and positions against. The bubble body is the `content` slot."
+      },
       {
         "name": "content",
         "mode": "replace",
@@ -1881,6 +2132,16 @@
     "className": "KaiCodeBlockElement",
     "displayName": "CodeBlock",
     "props": [
+      {
+        "name": "theme",
+        "type": "\"light\" | \"dark\" | \"auto\"",
+        "optional": true,
+        "scalar": true,
+        "description": "Color mode (`auto` follows prefers-color-scheme).",
+        "default": "'auto'",
+        "universal": true,
+        "displayType": "\"light\" | \"dark\" | \"auto\""
+      },
       {
         "name": "code",
         "type": "string",
@@ -1918,12 +2179,12 @@
       },
       {
         "name": "proseSize",
-        "type": "undefined | \"sm\" | \"lg\" | \"xs\" | \"base\"",
+        "type": "undefined | \"xs\" | \"sm\" | \"base\" | \"lg\"",
         "optional": true,
         "scalar": true,
         "description": "Code text sizing.",
         "default": "'sm'",
-        "displayType": "undefined | \"sm\" | \"lg\" | \"xs\" | \"base\""
+        "displayType": "undefined | \"xs\" | \"sm\" | \"base\" | \"lg\""
       }
     ],
     "events": [],
@@ -1949,12 +2210,25 @@
     "className": "KaiCommandElement",
     "displayName": "Command",
     "props": [
+      {
+        "name": "theme",
+        "type": "\"light\" | \"dark\" | \"auto\"",
+        "optional": true,
+        "scalar": true,
+        "description": "Color mode (`auto` follows prefers-color-scheme).",
+        "default": "'auto'",
+        "universal": true,
+        "displayType": "\"light\" | \"dark\" | \"auto\""
+      },
       {
         "name": "items",
         "type": "undefined | { id: string; label: string; icon?: undefined | string; description?: undefined | string; shortcut?: undefined | string; group?: undefined | string }[]",
         "optional": true,
         "scalar": false,
-        "description": "Flat list of items. Set as a JS property — not an HTML attribute.",
+        "description": "Flat list of items. Set as a JS property, not an HTML attribute.",
+        "typeName": "KaiCommandItem[]",
+        "typeShape": "{ id: string; label: string; icon?: undefined | string; description?: undefined | string; shortcut?: undefined | string; group?: undefined | string }[]",
+        "typeImport": "KaiCommandItem",
         "displayType": "undefined | { id: string; label: string; icon?: undefined | string; description?: undefined | string; shortcut?: undefined | string; group?: undefined | string }[]"
       },
       {
@@ -1977,9 +2251,9 @@
     "events": [
       {
         "name": "kai-active-change",
-        "detail": "{ id: undefined | string }",
-        "description": "Fired when the highlighted/active item changes — via Arrow keys or when filtering re-clamps the active row. `id` is the newly active item's id, or `undefined` when no item is active (e.g. the filtered list is empty). Lets a host preview the active item without committing a selection.",
-        "displayDetail": "{ id: undefined | string }"
+        "detail": "{ id: string | undefined }",
+        "description": "Fired when the highlighted/active item changes, via Arrow keys or when filtering re-clamps the active row. `id` is the newly active item's id, or `undefined` when no item is active (e.g. the filtered list is empty). Lets a host preview the active item without committing a selection.",
+        "displayDetail": "{ id: string | undefined }"
       },
       {
         "name": "kai-query-change",
@@ -2011,7 +2285,7 @@
         "name": "clear",
         "params": "",
         "returns": "void",
-        "description": "Reset the search query to empty — re-showing all items — and fire `kai-query-change` with `''`. Mirrors the Escape-key behavior."
+        "description": "Reset the search query to empty, re-showing all items, and fire `kai-query-change` with `''`. Mirrors the Escape-key behavior."
       }
     ],
     "composedFrom": [
@@ -2035,6 +2309,16 @@
     "className": "KaiCompareElement",
     "displayName": "Compare",
     "props": [
+      {
+        "name": "theme",
+        "type": "\"light\" | \"dark\" | \"auto\"",
+        "optional": true,
+        "scalar": true,
+        "description": "Color mode (`auto` follows prefers-color-scheme).",
+        "default": "'auto'",
+        "universal": true,
+        "displayType": "\"light\" | \"dark\" | \"auto\""
+      },
       {
         "name": "data",
         "type": "undefined | Record<string, unknown>",
@@ -2064,17 +2348,17 @@
         "type": "undefined | \"auto\" | \"columns\" | \"tabs\"",
         "optional": true,
         "scalar": true,
-        "description": "Layout: `'auto'` (default — columns when wide, tabs when narrow, by CONTAINER width) | `'columns'` (side-by-side) | `'tabs'` (pills to switch). Attribute: `layout`.",
+        "description": "Layout: `'auto'` (default, columns when wide, tabs when narrow, by CONTAINER width) | `'columns'` (side-by-side) | `'tabs'` (pills to switch). Attribute: `layout`.",
         "default": "'auto'",
         "displayType": "undefined | \"auto\" | \"columns\" | \"tabs\""
       },
       {
         "name": "proseSize",
-        "type": "undefined | \"sm\" | \"lg\" | \"xs\" | \"base\"",
+        "type": "undefined | \"xs\" | \"sm\" | \"base\" | \"lg\"",
         "optional": true,
         "scalar": true,
         "description": "Prose/text size for the rendered candidates. Attribute: `prose-size`.",
-        "displayType": "undefined | \"sm\" | \"lg\" | \"xs\" | \"base\""
+        "displayType": "undefined | \"xs\" | \"sm\" | \"base\" | \"lg\""
       },
       {
         "name": "codeTheme",
@@ -2118,7 +2402,7 @@
         "name": "select",
         "params": "candidateId: string",
         "returns": "void",
-        "description": "Programmatically commit a pick by candidate id — same path as the \"Pick this\" button: fires kai-compare-select and optimistically collapses (single-shot; inert while streaming or already resolved). `select` does NOT collide with the `selection` prop (distinct identifier)."
+        "description": "Programmatically commit a pick by candidate id, on the same path as the \"Pick this\" button: fires kai-compare-select and optimistically collapses (single-shot; inert while streaming or already resolved). `select` does NOT collide with the `selection` prop (distinct identifier)."
       },
       {
         "name": "focus",
@@ -2141,12 +2425,22 @@
     "className": "KaiComposerElement",
     "displayName": "Composer",
     "props": [
+      {
+        "name": "theme",
+        "type": "\"light\" | \"dark\" | \"auto\"",
+        "optional": true,
+        "scalar": true,
+        "description": "Color mode (`auto` follows prefers-color-scheme).",
+        "default": "'auto'",
+        "universal": true,
+        "displayType": "\"light\" | \"dark\" | \"auto\""
+      },
       {
         "name": "value",
         "type": "undefined | string | ({ type: \"text\"; text: string } | { type: \"entity\"; entity: { kind: string; id: string; label: string; icon?: undefined | string; promptText?: undefined | string; data?: undefined | Record<string, unknown> } })[]",
         "optional": true,
         "scalar": false,
-        "description": "Controlled value — string or a full ComposerDoc (set as JS property).",
+        "description": "Controlled value: a string or a full ComposerDoc (set as JS property).",
         "displayType": "undefined | string | ({ type: \"text\"; text: string } | { type: \"entity\"; entity: { kind: string; id: string; label: string; icon?: undefined | string; promptText?: undefined | string; data?: undefined | Record<string, unknown> } })[]"
       },
       {
@@ -2177,12 +2471,12 @@
       },
       {
         "name": "maxHeight",
-        "type": "undefined | string | number",
+        "type": "undefined | number | string",
         "optional": true,
         "scalar": true,
         "description": "Maximum height in px before the content scrolls. Default 240.",
         "default": "240",
-        "displayType": "undefined | string | number"
+        "displayType": "undefined | number | string"
       },
       {
         "name": "submitOnEnter",
@@ -2198,7 +2492,10 @@
         "type": "undefined | { char: string; kind: string; items?: undefined | { id: string; label: string; icon?: undefined | string; description?: undefined | string; group?: undefined | string; kind?: undefined | string; promptText?: undefined | string; data?: undefined | Record<string, unknown> }[] }[]",
         "optional": true,
         "scalar": false,
-        "description": "Trigger definitions — set as a JS property.",
+        "description": "Trigger definitions. Set as a JS property.",
+        "typeName": "TriggerDef[]",
+        "typeShape": "{ char: string; kind: string; items?: undefined | { id: string; label: string; icon?: undefined | string; description?: undefined | string; group?: undefined | string; kind?: undefined | string; promptText?: undefined | string; data?: undefined | Record<string, unknown> }[] }[]",
+        "typeImport": "TriggerDef",
         "displayType": "undefined | { char: string; kind: string; items?: undefined | { id: string; label: string; icon?: undefined | string; description?: undefined | string; group?: undefined | string; kind?: undefined | string; promptText?: undefined | string; data?: undefined | Record<string, unknown> }[] }[]"
       },
       {
@@ -2206,7 +2503,7 @@
         "type": "undefined | (string | { pattern: string; flags?: undefined | string; class?: undefined | string })[]",
         "optional": true,
         "scalar": false,
-        "description": "Keyword highlight rules — set as a JS property.",
+        "description": "Keyword highlight rules. Set as a JS property.",
         "displayType": "undefined | (string | { pattern: string; flags?: undefined | string; class?: undefined | string })[]"
       },
       {
@@ -2240,7 +2537,7 @@
       {
         "name": "kai-focus",
         "detail": "{ originalEvent: FocusEvent }",
-        "description": "The composer gained focus. `focus`/`blur` are NOT composed natively, so they don't escape the shadow root — these re-expose them on the host. (For `keydown`/`paste`/`focusin`/`focusout`, listen NATIVELY on `<kai-composer>`: they're composed and already cross the shadow boundary.)",
+        "description": "The composer gained focus. `focus`/`blur` are NOT composed natively, so they don't escape the shadow root; these re-expose them on the host. (For `keydown`/`paste`/`focusin`/`focusout`, listen NATIVELY on `<kai-composer>`: they're composed and already cross the shadow boundary.)",
         "displayDetail": "{ originalEvent: FocusEvent }"
       },
       {
@@ -2273,7 +2570,7 @@
         "name": "focus",
         "params": "options?: FocusOptions",
         "returns": "void",
-        "description": "Focus the editable element. `focus`/`blur` are NOT composed natively, so a host-level focus() can't reach the editable inside the shadow root — this is the only way to focus the composer programmatically."
+        "description": "Focus the editable element. `focus`/`blur` are NOT composed natively, so a host-level focus() can't reach the editable inside the shadow root. This is the only way to focus the composer programmatically."
       },
       {
         "name": "blur",
@@ -2291,7 +2588,7 @@
         "name": "send",
         "params": "",
         "returns": "void",
-        "description": "Submit the current content programmatically — same path as Enter (fires kai-submit). Named `send`, not `submit`, to match the shared vocabulary and avoid any submit collision."
+        "description": "Submit the current content programmatically, on the same path as Enter (fires kai-submit). Named `send`, not `submit`, to match the shared vocabulary and avoid any submit collision."
       },
       {
         "name": "insertEntity",
@@ -2314,13 +2611,26 @@
     "className": "KaiConfirmElement",
     "displayName": "Confirm",
     "props": [
+      {
+        "name": "theme",
+        "type": "\"light\" | \"dark\" | \"auto\"",
+        "optional": true,
+        "scalar": true,
+        "description": "Color mode (`auto` follows prefers-color-scheme).",
+        "default": "'auto'",
+        "universal": true,
+        "displayType": "\"light\" | \"dark\" | \"auto\""
+      },
       {
         "name": "data",
-        "type": "undefined | Record<string, unknown>",
+        "type": "undefined | { heading?: undefined | string; body?: undefined | string; tone?: undefined | \"default\" | \"warning\" | \"danger\"; actions: { id: string; label: string; style?: undefined | \"primary\" | \"default\" | \"destructive\"; payload?: unknown; default?: undefined | false | true }[]; dismissible?: undefined | false | true }",
         "optional": true,
         "scalar": false,
         "description": "The confirm definition (the CardEnvelope.data). Set as a JS PROPERTY: `el.data = { body, tone, actions:[…] }`. Import `ConfirmCardData` from `@kitn.ai/ui` for the full shape.",
-        "displayType": "undefined | Record<string, unknown>"
+        "typeName": "ConfirmCardData",
+        "typeShape": "{ heading?: undefined | string; body?: undefined | string; tone?: undefined | \"default\" | \"warning\" | \"danger\"; actions: { id: string; label: string; style?: undefined | \"primary\" | \"default\" | \"destructive\"; payload?: unknown; default?: undefined | false | true }[]; dismissible?: undefined | false | true }",
+        "typeImport": "ConfirmCardData",
+        "displayType": "undefined | { heading?: undefined | string; body?: undefined | string; tone?: undefined | \"default\" | \"warning\" | \"danger\"; actions: { id: string; label: string; style?: undefined | \"primary\" | \"default\" | \"destructive\"; payload?: unknown; default?: undefined | false | true }[]; dismissible?: undefined | false | true }"
       },
       {
         "name": "cardId",
@@ -2343,7 +2653,7 @@
         "type": "undefined | false | true",
         "optional": true,
         "scalar": true,
-        "description": "Focus the default action on mount (off by default — no focus-stealing). Attribute: `autofocus`.",
+        "description": "Focus the default action on mount (off by default, so nothing steals focus). Attribute: `autofocus`.",
         "default": "false",
         "displayType": "undefined | false | true"
       },
@@ -2362,25 +2672,25 @@
         "name": "focus",
         "params": "options?: FocusOptions",
         "returns": "void",
-        "description": "Focus the default action button (or the first action if none is default) — the same target `autofocus` focuses on mount, but on demand."
+        "description": "Focus the default action button (or the first action if none is default). The same target `autofocus` focuses on mount, but on demand."
       },
       {
         "name": "confirm",
         "params": "actionId?: string",
         "returns": "void",
-        "description": "Activate an action by id — emits the `action` verb on kai-card and resolves the card (single-shot). With no id, invokes the default action."
+        "description": "Activate an action by id: emits the `action` verb on kai-card and resolves the card (single-shot). With no id, invokes the default action."
       },
       {
         "name": "dismiss",
         "params": "",
         "returns": "void",
-        "description": "Trigger the dismiss path — emits `dismiss` on kai-card and optimistically collapses the card to its re-openable stub."
+        "description": "Trigger the dismiss path: emits `dismiss` on kai-card and optimistically collapses the card to its re-openable stub."
       },
       {
         "name": "reopen",
         "params": "",
         "returns": "void",
-        "description": "Re-open a dismissed card from its stub — emits `reopen` on kai-card."
+        "description": "Re-open a dismissed card from its stub: emits `reopen` on kai-card."
       }
     ],
     "composedFrom": [
@@ -2397,12 +2707,25 @@
     "className": "KaiContextElement",
     "displayName": "Context",
     "props": [
+      {
+        "name": "theme",
+        "type": "\"light\" | \"dark\" | \"auto\"",
+        "optional": true,
+        "scalar": true,
+        "description": "Color mode (`auto` follows prefers-color-scheme).",
+        "default": "'auto'",
+        "universal": true,
+        "displayType": "\"light\" | \"dark\" | \"auto\""
+      },
       {
         "name": "context",
         "type": "undefined | { usedTokens: number; maxTokens: number; inputTokens?: undefined | number; outputTokens?: undefined | number; reasoningTokens?: undefined | number; cacheTokens?: undefined | number; estimatedCost?: undefined | number }",
         "optional": true,
         "scalar": false,
         "description": "Token-usage data. Set as a JS property.",
+        "typeName": "KaiContextUsage",
+        "typeShape": "{ usedTokens: number; maxTokens: number; inputTokens?: undefined | number; outputTokens?: undefined | number; reasoningTokens?: undefined | number; cacheTokens?: undefined | number; estimatedCost?: undefined | number }",
+        "typeImport": "KaiContextUsage",
         "displayType": "ContextData | undefined"
       },
       {
@@ -2481,48 +2804,60 @@
         "name": "ContextCacheUsage",
         "group": "Components",
         "storyId": "solid-advanced-elements-contextcacheusage--docs"
-      },
+      }
+    ],
+    "tokens": [],
+    "parts": [
       {
-        "name": "DEFAULT_WARN_THRESHOLD",
-        "group": "Components",
-        "storyId": "solid-advanced-elements-defaultwarnthreshold--docs"
+        "name": "track",
+        "doc": "The usage meter track inside the hover-card breakdown. Carries `role=\"progressbar\"` and is in the DOM only while the card is open. Restyle its height, radius, or background from outside.",
+        "recipe": "kai-context::part(track) { height: 0.5rem }"
       },
       {
-        "name": "DEFAULT_DANGER_THRESHOLD",
-        "group": "Components",
-        "storyId": "solid-advanced-elements-defaultdangerthreshold--docs"
+        "name": "fill",
+        "doc": "The used-tokens portion of that meter. Its width follows `usedTokens / maxTokens`; its default color is the severity hue picked by `warnThreshold` / `dangerThreshold`, so recoloring it from outside replaces that signal.",
+        "recipe": "kai-context::part(fill) { background: var(--color-tool-blue) }"
       }
-    ],
-    "tokens": []
+    ]
   },
   {
     "tag": "kai-conversations",
     "className": "KaiConversationsElement",
     "displayName": "Conversations",
     "props": [
+      {
+        "name": "theme",
+        "type": "\"light\" | \"dark\" | \"auto\"",
+        "optional": true,
+        "scalar": true,
+        "description": "Color mode (`auto` follows prefers-color-scheme).",
+        "default": "'auto'",
+        "universal": true,
+        "displayType": "\"light\" | \"dark\" | \"auto\""
+      },
       {
         "name": "groups",
-        "type": "{ id: string; userId?: undefined | string; teamId?: undefined | string; name: string; sortOrder: number; createdAt: string }[]",
-        "optional": false,
+        "type": "undefined | { id: string; userId?: undefined | string; teamId?: undefined | string; name: string; sortOrder: number; createdAt: string }[]",
+        "optional": true,
         "scalar": false,
-        "description": "Pre-bucketed conversation groups (e.g. \"Today\", \"Yesterday\"), each with its own conversations. Use this when you want to control the grouping/headers yourself; otherwise pass a flat `conversations` array. Set as a JS property.",
+        "description": "The list's section headers (`{ id, name, sortOrder, createdAt }`), rendered in array order. A group carries no conversations of its own; it is matched against `conversations` by id, so the two props are complementary rather than alternatives. Omit for an ungrouped list. Set as a JS property.",
         "typeName": "ConversationGroup[]",
         "typeShape": "{ id: string; userId?: undefined | string; teamId?: undefined | string; name: string; sortOrder: number; createdAt: string }[]",
         "default": "[]",
         "typeImport": "ConversationGroup",
-        "displayType": "ConversationGroup[]"
+        "displayType": "undefined | { id: string; userId?: undefined | string; teamId?: undefined | string; name: string; sortOrder: number; createdAt: string }[]"
       },
       {
         "name": "conversations",
-        "type": "{ id: string; title: string; groupId?: undefined | string; scope: { type: \"document\" | \"collection\"; documentId?: undefined | string; filters?: undefined | { tags?: undefined | string[]; authors?: undefined | string[]; contentType?: undefined | \"transcript\" | \"markdown\"; dateRange?: undefined | { from: string; to: string } } }; messageCount: number; lastMessageAt: string; updatedAt: string; trailing?: undefined | string }[]",
-        "optional": false,
+        "type": "undefined | { id: string; title: string; groupId?: undefined | string; scope: { type: \"document\" | \"collection\"; documentId?: undefined | string; filters?: undefined | { tags?: undefined | string[]; authors?: undefined | string[]; contentType?: undefined | \"transcript\" | \"markdown\"; dateRange?: undefined | { from: string; to: string } } }; messageCount: number; lastMessageAt: string; updatedAt: string; trailing?: undefined | string }[]",
+        "optional": true,
         "scalar": false,
-        "description": "A flat list of conversation summaries; the component buckets them by recency for you. Ignored when `groups` is provided. Set as a JS property.",
+        "description": "Every conversation the list renders, flat. Each one is filed under the group whose `id` equals its `groupId`; one with no `groupId`, or with a `groupId` matching no entry in `groups`, falls into a trailing \"Ungrouped\" section, so nothing you pass in is ever dropped. There is no recency bucketing. Set as a JS property. Omit to supply them as `<kai-conversation>` light-DOM children instead, or for the empty state.",
         "typeName": "ConversationSummary[]",
         "typeShape": "{ id: string; title: string; groupId?: undefined | string; scope: { type: \"document\" | \"collection\"; documentId?: undefined | string; filters?: undefined | { tags?: undefined | string[]; authors?: undefined | string[]; contentType?: undefined | \"transcript\" | \"markdown\"; dateRange?: undefined | { from: string; to: string } } }; messageCount: number; lastMessageAt: string; updatedAt: string; trailing?: undefined | string }[]",
         "default": "[]",
         "typeImport": "ConversationSummary",
-        "displayType": "{ id: string; title: string; groupId?: undefined | string; scope: { type: \"document\" | \"collection\"; documentId?: undefined | string; filters?: undefined | { tags?: undefined | string[]; authors?: undefined | string[]; contentType?: undefined | \"transcript\" | \"markdown\"; dateRange?: undefined | { from: string; to: string } } }; messageCount: number; lastMessageAt: string; updatedAt: string; trailing?: undefined | string }[]"
+        "displayType": "undefined | { id: string; title: string; groupId?: undefined | string; scope: { type: \"document\" | \"collection\"; documentId?: undefined | string; filters?: undefined | { tags?: undefined | string[]; authors?: undefined | string[]; contentType?: undefined | \"transcript\" | \"markdown\"; dateRange?: undefined | { from: string; to: string } } }; messageCount: number; lastMessageAt: string; updatedAt: string; trailing?: undefined | string }[]"
       },
       {
         "name": "activeId",
@@ -2598,7 +2933,7 @@
         "name": "select",
         "params": "id: string",
         "returns": "void",
-        "description": "Programmatically select a conversation by id — mirror of the kai-conversation-select event (a convenience over driving `activeId`)."
+        "description": "Programmatically select a conversation by id. The mirror of the kai-conversation-select event (a convenience over driving `activeId`)."
       },
       {
         "name": "collapse",
@@ -2635,6 +2970,17 @@
       "--color-sidebar",
       "--color-scrollbar-thumb"
     ],
+    "declarativeChildren": [
+      {
+        "tag": "kai-conversation",
+        "attributes": [
+          "group-id",
+          "id"
+        ],
+        "text": true,
+        "description": "Parse a single light-DOM `<kai-conversation>` element into a `ConversationSummary`. Attribute mapping: - `id` → ConversationSummary.id - `group-id` → ConversationSummary.groupId (optional) - textContent → ConversationSummary.title Required fields not expressible as HTML attributes (`scope`, `messageCount`, `lastMessageAt`, `updatedAt`) receive safe defaults so the rendered list item is fully functional with just `id` + title text."
+      }
+    ],
     "slots": [
       {
         "name": "header",
@@ -2649,7 +2995,7 @@
       {
         "name": "footer",
         "mode": "inject",
-        "doc": "A row below the list — account, settings, or usage."
+        "doc": "A row below the list: account, settings, or usage."
       }
     ],
     "parts": [
@@ -2665,6 +3011,16 @@
     "className": "KaiDialogElement",
     "displayName": "Dialog",
     "props": [
+      {
+        "name": "theme",
+        "type": "\"light\" | \"dark\" | \"auto\"",
+        "optional": true,
+        "scalar": true,
+        "description": "Color mode (`auto` follows prefers-color-scheme).",
+        "default": "'auto'",
+        "universal": true,
+        "displayType": "\"light\" | \"dark\" | \"auto\""
+      },
       {
         "name": "open",
         "type": "undefined | false | true",
@@ -2725,6 +3081,11 @@
     ],
     "tokens": [],
     "slots": [
+      {
+        "name": "",
+        "mode": "inject",
+        "doc": "The dialog body, between the `header` and `footer` slots."
+      },
       {
         "name": "header",
         "mode": "inject",
@@ -2769,12 +3130,22 @@
     "className": "KaiEditableLabelElement",
     "displayName": "EditableLabel",
     "props": [
+      {
+        "name": "theme",
+        "type": "\"light\" | \"dark\" | \"auto\"",
+        "optional": true,
+        "scalar": true,
+        "description": "Color mode (`auto` follows prefers-color-scheme).",
+        "default": "'auto'",
+        "universal": true,
+        "displayType": "\"light\" | \"dark\" | \"auto\""
+      },
       {
         "name": "value",
         "type": "undefined | string",
         "optional": true,
         "scalar": true,
-        "description": "The label text — settable and reflected to the `value` attribute. Read `el.value` for live state.",
+        "description": "The label text. Settable and reflected to the `value` attribute. Read `el.value` for live state.",
         "displayType": "undefined | string"
       },
       {
@@ -2823,7 +3194,19 @@
         "name": "edit",
         "params": "",
         "returns": "void",
-        "description": ""
+        "description": "Switch the label into its editing field, which autofocuses and selects the current text. Same entry point as a user double-click, and a no-op while `disabled`. Commit with `commit()` or by blurring, abandon with `cancel()` or Escape."
+      },
+      {
+        "name": "commit",
+        "params": "",
+        "returns": "void",
+        "description": "Close the field and keep what was typed, exactly as blurring it does. `kai-rename` fires only when the text actually changed, so committing an untouched field is silent. A no-op while the field is closed."
+      },
+      {
+        "name": "cancel",
+        "params": "",
+        "returns": "void",
+        "description": "Abandon the edit, exactly as Escape does: the original text is restored, the field closes and `kai-cancel` fires. `kai-rename` never fires, even if the field was edited. Also works when `editing` was set programmatically and the field has not rendered yet."
       }
     ],
     "composedFrom": [
@@ -2852,6 +3235,16 @@
     "className": "KaiEmbedElement",
     "displayName": "Embed",
     "props": [
+      {
+        "name": "theme",
+        "type": "\"light\" | \"dark\" | \"auto\"",
+        "optional": true,
+        "scalar": true,
+        "description": "Color mode (`auto` follows prefers-color-scheme).",
+        "default": "'auto'",
+        "universal": true,
+        "displayType": "\"light\" | \"dark\" | \"auto\""
+      },
       {
         "name": "cardId",
         "type": "undefined | string",
@@ -2866,6 +3259,9 @@
         "optional": true,
         "scalar": false,
         "description": "The embed payload (provider + id/url + options). Set as a JS **property** (object).",
+        "typeName": "EmbedCardData",
+        "typeShape": "{ provider: \"youtube\" | \"vimeo\" | \"generic\"; id?: undefined | string; url?: undefined | string; title?: undefined | string; poster?: undefined | string; start?: undefined | number; aspectRatio?: undefined | \"16:9\" | \"4:3\" | \"1:1\" | \"9:16\" }",
+        "typeImport": "EmbedCardData",
         "displayType": "undefined | { provider: \"youtube\" | \"vimeo\" | \"generic\"; id?: undefined | string; url?: undefined | string; title?: undefined | string; poster?: undefined | string; start?: undefined | number; aspectRatio?: undefined | \"16:9\" | \"4:3\" | \"1:1\" | \"9:16\" }"
       }
     ],
@@ -2885,6 +3281,16 @@
     "className": "KaiEmptyElement",
     "displayName": "Empty",
     "props": [
+      {
+        "name": "theme",
+        "type": "\"light\" | \"dark\" | \"auto\"",
+        "optional": true,
+        "scalar": true,
+        "description": "Color mode (`auto` follows prefers-color-scheme).",
+        "default": "'auto'",
+        "universal": true,
+        "displayType": "\"light\" | \"dark\" | \"auto\""
+      },
       {
         "name": "emptyTitle",
         "type": "undefined | string",
@@ -2938,19 +3344,41 @@
         "storyId": "solid-advanced-elements-emptycontent--docs"
       }
     ],
-    "tokens": []
-  },
-  {
+    "tokens": [],
+    "slots": [
+      {
+        "name": "",
+        "mode": "inject",
+        "doc": "The empty-state body below the title/description, usually the call to action."
+      },
+      {
+        "name": "media",
+        "mode": "replace",
+        "doc": "The leading illustration or icon above the title (any inline SVG or <img>). Replaces the built-in media box."
+      }
+    ]
+  },
+  {
     "tag": "kai-feedback-bar",
     "className": "KaiFeedbackBarElement",
     "displayName": "FeedbackBar",
     "props": [
+      {
+        "name": "theme",
+        "type": "\"light\" | \"dark\" | \"auto\"",
+        "optional": true,
+        "scalar": true,
+        "description": "Color mode (`auto` follows prefers-color-scheme).",
+        "default": "'auto'",
+        "universal": true,
+        "displayType": "\"light\" | \"dark\" | \"auto\""
+      },
       {
         "name": "barTitle",
         "type": "undefined | string",
         "optional": true,
         "scalar": true,
-        "description": "The banner label (e.g. \"Was this helpful?\"). Attribute: `bar-title` (`title` is avoided — it's a global HTML attribute).",
+        "description": "The banner label (e.g. \"Was this helpful?\"). Attribute: `bar-title` (`title` is avoided because it is a global HTML attribute).",
         "default": "'Was this helpful?'",
         "displayType": "undefined | string"
       },
@@ -3038,16 +3466,26 @@
     "className": "KaiFileTreeElement",
     "displayName": "FileTree",
     "props": [
+      {
+        "name": "theme",
+        "type": "\"light\" | \"dark\" | \"auto\"",
+        "optional": true,
+        "scalar": true,
+        "description": "Color mode (`auto` follows prefers-color-scheme).",
+        "default": "'auto'",
+        "universal": true,
+        "displayType": "\"light\" | \"dark\" | \"auto\""
+      },
       {
         "name": "files",
         "type": "{ path: string; url?: undefined | string; code?: undefined | string; language?: undefined | string; type?: undefined | \"html\" | \"pdf\" | \"image\" | \"other\"; additions?: undefined | number; deletions?: undefined | number; status?: undefined | \"added\" | \"modified\" | \"deleted\" | \"renamed\" | \"untracked\" }[]",
         "optional": false,
         "scalar": false,
         "description": "The files to render. Set as a JS property (array of `{ path, url?, code?, language?, type?, additions?, deletions?, status? }`).",
-        "typeName": "FileTreeFile[]",
+        "typeName": "ArtifactCardFile[]",
         "typeShape": "{ path: string; url?: undefined | string; code?: undefined | string; language?: undefined | string; type?: undefined | \"html\" | \"pdf\" | \"image\" | \"other\"; additions?: undefined | number; deletions?: undefined | number; status?: undefined | \"added\" | \"modified\" | \"deleted\" | \"renamed\" | \"untracked\" }[]",
         "default": "[]",
-        "typeImport": "FileTreeFile",
+        "typeImport": "ArtifactCardFile",
         "displayType": "{ path: string; url?: undefined | string; code?: undefined | string; language?: undefined | string; type?: undefined | \"html\" | \"pdf\" | \"image\" | \"other\"; additions?: undefined | number; deletions?: undefined | number; status?: undefined | \"added\" | \"modified\" | \"deleted\" | \"renamed\" | \"untracked\" }[]"
       },
       {
@@ -3055,7 +3493,7 @@
         "type": "undefined | string",
         "optional": true,
         "scalar": true,
-        "description": "Selected file path — highlighted in the tree.",
+        "description": "Selected file path, highlighted in the tree.",
         "displayType": "undefined | string"
       },
       {
@@ -3121,6 +3559,16 @@
     "className": "KaiFileUploadElement",
     "displayName": "FileUpload",
     "props": [
+      {
+        "name": "theme",
+        "type": "\"light\" | \"dark\" | \"auto\"",
+        "optional": true,
+        "scalar": true,
+        "description": "Color mode (`auto` follows prefers-color-scheme).",
+        "default": "'auto'",
+        "universal": true,
+        "displayType": "\"light\" | \"dark\" | \"auto\""
+      },
       {
         "name": "multiple",
         "type": "undefined | false | true",
@@ -3143,7 +3591,7 @@
         "type": "undefined | false | true",
         "optional": true,
         "scalar": true,
-        "description": "Disable the dropzone — no clicking, no drag-and-drop.",
+        "description": "Disable the dropzone: no clicking, no drag-and-drop.",
         "default": "false",
         "displayType": "undefined | false | true"
       },
@@ -3178,20 +3626,40 @@
         "storyId": "solid-advanced-elements-fileuploadtrigger--docs"
       }
     ],
-    "tokens": []
+    "tokens": [],
+    "slots": [
+      {
+        "name": "",
+        "mode": "inject",
+        "doc": "Custom dropzone content, replacing the default label (the `label` prop is the fallback)."
+      }
+    ]
   },
   {
     "tag": "kai-form",
     "className": "KaiFormElement",
     "displayName": "Form",
     "props": [
+      {
+        "name": "theme",
+        "type": "\"light\" | \"dark\" | \"auto\"",
+        "optional": true,
+        "scalar": true,
+        "description": "Color mode (`auto` follows prefers-color-scheme).",
+        "default": "'auto'",
+        "universal": true,
+        "displayType": "\"light\" | \"dark\" | \"auto\""
+      },
       {
         "name": "data",
-        "type": "undefined | Record<string, unknown>",
+        "type": "undefined | { type: \"object\"; title?: undefined | string; description?: undefined | string; required?: undefined | string[]; properties: Record<string, { type: \"string\" | \"number\" | \"integer\" | \"boolean\" | \"array\" | \"object\"; title?: undefined | string; description?: undefined | string; default?: unknown; enum?: undefined | unknown[]; format?: undefined | \"email\" | \"uri\" | \"url\" | \"date\" | \"date-time\" | \"time\"; minimum?: undefined | number; maximum?: undefined | number; minLength?: undefined | number; maxLength?: undefined | number; pattern?: undefined | string; minItems?: undefined | number; maxItems?: undefined | number; items?: undefined | Record<string, unknown> | { enum: unknown[] }; properties?: undefined | Record<string, Record<string, unknown>>; required?: undefined | string[]; readOnly?: undefined | false | true; \"x-kai-widget\"?: undefined | \"textarea\" | \"slider\" | \"rating\" | \"radio\" | \"select\" | \"checkbox\" | \"password\" | \"switch\"; \"x-kai-placeholder\"?: undefined | string; \"x-kai-step\"?: undefined | number }>; \"x-kai-order\"?: undefined | string[]; \"x-kai-inlineMax\"?: undefined | number; \"x-kai-submitLabel\"?: undefined | string; \"x-kai-dismissible\"?: undefined | false | true; \"x-kai-actions\"?: undefined | { id: string; label: string; variant?: undefined | \"default\" | \"ghost\" | \"outline\" }[] }",
         "optional": true,
         "scalar": false,
-        "description": "The form definition — a JSON Schema (`type:'object'`) + `x-kai-*` UI hints (the CardEnvelope.data). Set as a JS PROPERTY: `el.data = { type:'object', properties:{…} }`. Import the `FormDefinition` type from `@kitn.ai/ui` for the full shape (it is self-referential, so the element types it loosely).",
-        "displayType": "undefined | Record<string, unknown>"
+        "description": "The form definition: a JSON Schema (`type:'object'`) + `x-kai-*` UI hints (the CardEnvelope.data). Set as a JS PROPERTY: `el.data = { type:'object', properties:{…} }`. Import the `FormDefinition` type from `@kitn.ai/ui` for the full shape. It IS self-referential (`FormField.properties` is another `FormField` map), and the generated `element-types.d.ts` inlines every named type, so the shipped declaration bottoms out in a `Record<string, unknown>` placeholder one level down rather than carrying the recursion. That is why `FormDefinition` is a `type` alias: an interface gets no implicit index signature, so it would not be assignable to that placeholder.",
+        "typeName": "FormDefinition",
+        "typeShape": "{ type: \"object\"; title?: undefined | string; description?: undefined | string; required?: undefined | string[]; properties: Record<string, { type: \"string\" | \"number\" | \"integer\" | \"boolean\" | \"array\" | \"object\"; title?: undefined | string; description?: undefined | string; default?: unknown; enum?: undefined | unknown[]; format?: undefined | \"email\" | \"uri\" | \"url\" | \"date\" | \"date-time\" | \"time\"; minimum?: undefined | number; maximum?: undefined | number; minLength?: undefined | number; maxLength?: undefined | number; pattern?: undefined | string; minItems?: undefined | number; maxItems?: undefined | number; items?: undefined | Record<string, unknown> | { enum: unknown[] }; properties?: undefined | Record<string, Record<string, unknown>>; required?: undefined | string[]; readOnly?: undefined | false | true; \"x-kai-widget\"?: undefined | \"textarea\" | \"slider\" | \"rating\" | \"radio\" | \"select\" | \"checkbox\" | \"password\" | \"switch\"; \"x-kai-placeholder\"?: undefined | string; \"x-kai-step\"?: undefined | number }>; \"x-kai-order\"?: undefined | string[]; \"x-kai-inlineMax\"?: undefined | number; \"x-kai-submitLabel\"?: undefined | string; \"x-kai-dismissible\"?: undefined | false | true; \"x-kai-actions\"?: undefined | { id: string; label: string; variant?: undefined | \"default\" | \"ghost\" | \"outline\" }[] }",
+        "typeImport": "FormDefinition",
+        "displayType": "undefined | { type: \"object\"; title?: undefined | string; description?: undefined | string; required?: undefined | string[]; properties: Record<string, { type: \"string\" | \"number\" | \"integer\" | \"boolean\" | \"array\" | \"object\"; title?: undefined | string; description?: undefined | string; default?: unknown; enum?: undefined | unknown[]; format?: undefined | \"email\" | \"uri\" | \"url\" | \"date\" | \"date-time\" | \"time\"; minimum?: undefined | number; maximum?: undefined | number; minLength?: undefined | number; maxLength?: undefined | number; pattern?: undefined | string; minItems?: undefined | number; maxItems?: undefined | number; items?: undefined | Record<string, unknown> | { enum: unknown[] }; properties?: undefined | Record<string, Record<string, unknown>>; required?: undefined | string[]; readOnly?: undefined | false | true; \"x-kai-widget\"?: undefined | \"textarea\" | \"slider\" | \"rating\" | \"radio\" | \"select\" | \"checkbox\" | \"password\" | \"switch\"; \"x-kai-placeholder\"?: undefined | string; \"x-kai-step\"?: undefined | number }>; \"x-kai-order\"?: undefined | string[]; \"x-kai-inlineMax\"?: undefined | number; \"x-kai-submitLabel\"?: undefined | string; \"x-kai-dismissible\"?: undefined | false | true; \"x-kai-actions\"?: undefined | { id: string; label: string; variant?: undefined | \"default\" | \"ghost\" | \"outline\" }[] }"
       },
       {
         "name": "cardId",
@@ -3247,7 +3715,7 @@
       {
         "name": "kai-values-change",
         "detail": "{ values: Record<string, unknown>; valid: false | true }",
-        "description": "The form's values changed on input — current coerced values + validity.",
+        "description": "The form's values changed on input. Carries the current coerced values + validity.",
         "displayDetail": "{ values: Record<string, unknown>; valid: false | true }"
       }
     ],
@@ -3262,7 +3730,7 @@
         "name": "send",
         "params": "",
         "returns": "void",
-        "description": "Validate + submit programmatically — focus the first invalid field on failure, else emit the `submit` CardEvent and resolve. Named `send`, not `submit`."
+        "description": "Validate + submit programmatically: focus the first invalid field on failure, else emit the `submit` CardEvent and resolve. Named `send`, not `submit`."
       },
       {
         "name": "validate",
@@ -3303,6 +3771,16 @@
     "className": "KaiHoverCardElement",
     "displayName": "HoverCard",
     "props": [
+      {
+        "name": "theme",
+        "type": "\"light\" | \"dark\" | \"auto\"",
+        "optional": true,
+        "scalar": true,
+        "description": "Color mode (`auto` follows prefers-color-scheme).",
+        "default": "'auto'",
+        "universal": true,
+        "displayType": "\"light\" | \"dark\" | \"auto\""
+      },
       {
         "name": "openDelay",
         "type": "undefined | number",
@@ -3399,6 +3877,11 @@
     ],
     "tokens": [],
     "slots": [
+      {
+        "name": "",
+        "mode": "inject",
+        "doc": "The TRIGGER the card hovers off. The card body is the `card` slot."
+      },
       {
         "name": "card",
         "mode": "inject",
@@ -3411,6 +3894,16 @@
     "className": "KaiIconElement",
     "displayName": "Icon",
     "props": [
+      {
+        "name": "theme",
+        "type": "\"light\" | \"dark\" | \"auto\"",
+        "optional": true,
+        "scalar": true,
+        "description": "Color mode (`auto` follows prefers-color-scheme).",
+        "default": "'auto'",
+        "universal": true,
+        "displayType": "\"light\" | \"dark\" | \"auto\""
+      },
       {
         "name": "name",
         "type": "undefined | string",
@@ -3447,6 +3940,16 @@
     "className": "KaiImageElement",
     "displayName": "Image",
     "props": [
+      {
+        "name": "theme",
+        "type": "\"light\" | \"dark\" | \"auto\"",
+        "optional": true,
+        "scalar": true,
+        "description": "Color mode (`auto` follows prefers-color-scheme).",
+        "default": "'auto'",
+        "universal": true,
+        "displayType": "\"light\" | \"dark\" | \"auto\""
+      },
       {
         "name": "base64",
         "type": "undefined | string",
@@ -3497,6 +4000,16 @@
     "className": "KaiInputElement",
     "displayName": "Input",
     "props": [
+      {
+        "name": "theme",
+        "type": "\"light\" | \"dark\" | \"auto\"",
+        "optional": true,
+        "scalar": true,
+        "description": "Color mode (`auto` follows prefers-color-scheme).",
+        "default": "'auto'",
+        "universal": true,
+        "displayType": "\"light\" | \"dark\" | \"auto\""
+      },
       {
         "name": "type",
         "type": "undefined | string",
@@ -3511,7 +4024,7 @@
         "type": "undefined | string",
         "optional": true,
         "scalar": true,
-        "description": "Controlled value — settable and reflected to the `value` attribute. `el.value = 'hi'` drives it (no event); typing updates it and fires `kai-input`. Read `el.value` for live state.",
+        "description": "Controlled value. Settable and reflected to the `value` attribute. `el.value = 'hi'` drives it (no event); typing updates it and fires `kai-input`. Read `el.value` for live state.",
         "displayType": "undefined | string"
       },
       {
@@ -3694,22 +4207,32 @@
     "className": "KaiKbdElement",
     "displayName": "Kbd",
     "props": [
+      {
+        "name": "theme",
+        "type": "\"light\" | \"dark\" | \"auto\"",
+        "optional": true,
+        "scalar": true,
+        "description": "Color mode (`auto` follows prefers-color-scheme).",
+        "default": "'auto'",
+        "universal": true,
+        "displayType": "\"light\" | \"dark\" | \"auto\""
+      },
       {
         "name": "keys",
         "type": "undefined | string",
         "optional": true,
         "scalar": true,
-        "description": "Shortcut spec — tokens joined by `+` (e.g. `Mod+Shift+K`). Omit it to show default-slot content instead. Display only; the element does not bind keys.",
+        "description": "Shortcut spec: tokens joined by `+` (e.g. `Mod+Shift+K`). Omit it to show default-slot content instead. Display only; the element does not bind keys.",
         "displayType": "undefined | string"
       },
       {
         "name": "platform",
-        "type": "undefined | \"other\" | \"auto\" | \"mac\"",
+        "type": "undefined | \"auto\" | \"mac\" | \"other\"",
         "optional": true,
         "scalar": true,
         "description": "`mac` uses ⌘/⌥, `other` uses Ctrl. `auto` (default) sniffs the OS.",
         "default": "'auto'",
-        "displayType": "undefined | \"other\" | \"auto\" | \"mac\""
+        "displayType": "undefined | \"auto\" | \"mac\" | \"other\""
       },
       {
         "name": "size",
@@ -3731,6 +4254,13 @@
       }
     ],
     "tokens": [],
+    "slots": [
+      {
+        "name": "",
+        "mode": "inject",
+        "doc": "Literal key text, when you are not using the `keys` prop to render key caps."
+      }
+    ],
     "parts": [
       {
         "name": "key",
@@ -3749,6 +4279,16 @@
     "className": "KaiLinkPreviewElement",
     "displayName": "LinkPreview",
     "props": [
+      {
+        "name": "theme",
+        "type": "\"light\" | \"dark\" | \"auto\"",
+        "optional": true,
+        "scalar": true,
+        "description": "Color mode (`auto` follows prefers-color-scheme).",
+        "default": "'auto'",
+        "universal": true,
+        "displayType": "\"light\" | \"dark\" | \"auto\""
+      },
       {
         "name": "cardId",
         "type": "undefined | string",
@@ -3763,6 +4303,9 @@
         "optional": true,
         "scalar": false,
         "description": "The link payload (OG metadata). Set as a JS **property** (object).",
+        "typeName": "LinkPreviewData",
+        "typeShape": "{ url: string; title?: undefined | string; description?: undefined | string; image?: undefined | string; imageAlt?: undefined | string; favicon?: undefined | string; domain?: undefined | string; siteName?: undefined | string }",
+        "typeImport": "LinkPreviewData",
         "displayType": "undefined | { url: string; title?: undefined | string; description?: undefined | string; image?: undefined | string; imageAlt?: undefined | string; favicon?: undefined | string; domain?: undefined | string; siteName?: undefined | string }"
       }
     ],
@@ -3782,6 +4325,16 @@
     "className": "KaiLoaderElement",
     "displayName": "Loader",
     "props": [
+      {
+        "name": "theme",
+        "type": "\"light\" | \"dark\" | \"auto\"",
+        "optional": true,
+        "scalar": true,
+        "description": "Color mode (`auto` follows prefers-color-scheme).",
+        "default": "'auto'",
+        "universal": true,
+        "displayType": "\"light\" | \"dark\" | \"auto\""
+      },
       {
         "name": "variant",
         "type": "undefined | \"circular\" | \"classic\" | \"pulse\" | \"pulse-dot\" | \"dots\" | \"typing\" | \"wave\" | \"bars\" | \"terminal\" | \"text-blink\" | \"text-shimmer\" | \"loading-dots\"",
@@ -3825,6 +4378,16 @@
     "className": "KaiMarkdownElement",
     "displayName": "Markdown",
     "props": [
+      {
+        "name": "theme",
+        "type": "\"light\" | \"dark\" | \"auto\"",
+        "optional": true,
+        "scalar": true,
+        "description": "Color mode (`auto` follows prefers-color-scheme).",
+        "default": "'auto'",
+        "universal": true,
+        "displayType": "\"light\" | \"dark\" | \"auto\""
+      },
       {
         "name": "content",
         "type": "string",
@@ -3836,12 +4399,12 @@
       },
       {
         "name": "proseSize",
-        "type": "undefined | \"sm\" | \"lg\" | \"xs\" | \"base\"",
+        "type": "undefined | \"xs\" | \"sm\" | \"base\" | \"lg\"",
         "optional": true,
         "scalar": true,
         "description": "Text/markdown sizing.",
         "default": "'sm'",
-        "displayType": "undefined | \"sm\" | \"lg\" | \"xs\" | \"base\""
+        "displayType": "undefined | \"xs\" | \"sm\" | \"base\" | \"lg\""
       },
       {
         "name": "codeTheme",
@@ -3878,12 +4441,25 @@
     "className": "KaiMenuElement",
     "displayName": "Menu",
     "props": [
+      {
+        "name": "theme",
+        "type": "\"light\" | \"dark\" | \"auto\"",
+        "optional": true,
+        "scalar": true,
+        "description": "Color mode (`auto` follows prefers-color-scheme).",
+        "default": "'auto'",
+        "universal": true,
+        "displayType": "\"light\" | \"dark\" | \"auto\""
+      },
       {
         "name": "items",
         "type": "undefined | { id?: undefined | string; label?: undefined | string; icon?: undefined | string; shortcut?: undefined | string; checked?: undefined | false | true; radioGroup?: undefined | string; disabled?: undefined | false | true; separator?: undefined | false | true; heading?: undefined | false | true; items?: undefined | Record<string, unknown>[] }[]",
         "optional": true,
         "scalar": false,
-        "description": "Tree of menu items. Set as a JS property — not an HTML attribute.",
+        "description": "Tree of menu items. Set as a JS property, not an HTML attribute.",
+        "typeName": "KaiMenuItem[]",
+        "typeShape": "{ id?: undefined | string; label?: undefined | string; icon?: undefined | string; shortcut?: undefined | string; checked?: undefined | false | true; radioGroup?: undefined | string; disabled?: undefined | false | true; separator?: undefined | false | true; heading?: undefined | false | true; items?: undefined | { id?: undefined | string; label?: undefined | string; icon?: undefined | string; shortcut?: undefined | string; checked?: undefined | false | true; radioGroup?: undefined | string; disabled?: undefined | false | true; separator?: undefined | false | true; heading?: undefined | false | true; items?: undefined | Record<string, unknown>[] }[] }[]",
+        "typeImport": "KaiMenuItem",
         "displayType": "undefined | { id?: undefined | string; label?: undefined | string; icon?: undefined | string; shortcut?: undefined | string; checked?: undefined | false | true; radioGroup?: undefined | string; disabled?: undefined | false | true; separator?: undefined | false | true; heading?: undefined | false | true; items?: undefined | Record<string, unknown>[] }[]"
       },
       {
@@ -3899,7 +4475,7 @@
         "type": "undefined | string",
         "optional": true,
         "scalar": true,
-        "description": "Built-in trigger: leading icon (a named icon like `\"plus\"`, an image URL/data-URI, or text). Use this instead of slotting `slot=\"trigger\"` for the common case — a slotted trigger overrides it.",
+        "description": "Built-in trigger: leading icon (a named icon like `\"plus\"`, an image URL/data-URI, or text). Use this instead of slotting `slot=\"trigger\"` for the common case; a slotted trigger overrides it.",
         "displayType": "undefined | string"
       },
       {
@@ -3907,7 +4483,7 @@
         "type": "undefined | string",
         "optional": true,
         "scalar": true,
-        "description": "Built-in trigger: a text label (e.g. `\"High\"`).",
+        "description": "Built-in trigger: a text label (e.g. `\"High\"`). This is the trigger's VISIBLE text, so it is also its accessible name, and `label` does not override it: an accessible name that does not contain the visible text is unreachable by speech input, which is what WCAG 2.5.3 (Label in Name) exists for. A slotted `slot=\"trigger\"` replaces this built-in trigger entirely and is named differently; see `label`.",
         "displayType": "undefined | string"
       },
       {
@@ -3923,7 +4499,7 @@
         "type": "undefined | string",
         "optional": true,
         "scalar": true,
-        "description": "Accessible name for an icon-only trigger (no visible label).",
+        "description": "Accessible name for a trigger with no visible label. Ignored when `triggerLabel` is set, which is already the visible name. It DOES name a slotted `slot=\"trigger\"`, and that is a difference in what the two slots MEAN, not a limitation. `<kai-button>`'s slot IS the button's label, so text slotted there is the name and `label` steps aside. This slot is VISUAL content, a `+` or an `<svg>`, with the name supplied separately: decoration beside a name, never a second name competing with one. So `label` names the trigger here by design. Slotting a real WORD rather than a glyph makes that word a visible label, and an accessible name has to contain the visible text. Then either drop `label` or make it contain the word you slotted.",
         "displayType": "undefined | string"
       },
       {
@@ -3947,7 +4523,7 @@
         "type": "undefined | false | true",
         "optional": true,
         "scalar": true,
-        "description": "Disable the trigger — click/keyboard and `show()` no longer open the menu.",
+        "description": "Disable the trigger: click/keyboard and `show()` no longer open the menu.",
         "displayType": "undefined | false | true"
       }
     ],
@@ -3961,7 +4537,7 @@
       {
         "name": "kai-select",
         "detail": "{ id: string; checked?: undefined | false | true; radioGroup?: undefined | string }",
-        "description": "Fired when the user selects a leaf item. - Plain items: `{ id }`. - Checkbox items: `{ id, checked }` where `checked` is the NEW state. - Radio items: `{ id, radioGroup }` — the consumer marks `id` as the selected one in `radioGroup` and clears the others.",
+        "description": "Fired when the user selects a leaf item. - Plain items: `{ id }`. - Checkbox items: `{ id, checked }` where `checked` is the NEW state. - Radio items: `{ id, radioGroup }`, where the consumer marks `id` as the selected one in `radioGroup` and clears the others.",
         "displayDetail": "{ id: string; checked?: undefined | false | true; radioGroup?: undefined | string }"
       }
     ],
@@ -4068,31 +4644,36 @@
     "className": "KaiMessageElement",
     "displayName": "Message",
     "props": [
+      {
+        "name": "theme",
+        "type": "\"light\" | \"dark\" | \"auto\"",
+        "optional": true,
+        "scalar": true,
+        "description": "Color mode (`auto` follows prefers-color-scheme).",
+        "default": "'auto'",
+        "universal": true,
+        "displayType": "\"light\" | \"dark\" | \"auto\""
+      },
       {
         "name": "message",
-        "type": "undefined | { id: string; role: \"user\" | \"assistant\"; content: string; reasoning?: undefined | { text: string; label?: undefined | string }; tools?: undefined | { type: string; state: \"input-streaming\" | \"input-available\" | \"output-available\" | \"output-error\"; input?: undefined | Record<string, unknown>; output?: undefined | Record<string, unknown>; toolCallId?: undefined | string; errorText?: undefined | string }[]; attachments?: undefined | { id: string; type: \"file\" | \"source-document\"; filename?: undefined | string; mediaType?: undefined | string; url?: undefined | string; title?: undefined | string }[]; actions?: undefined | (\"copy\" | \"like\" | \"dislike\" | \"regenerate\" | \"edit\" | { id: string; label: string; icon?: undefined | string; tooltip?: undefined | string })[]; avatar?: undefined | { src?: undefined | string; fallback?: undefined | string; alt?: undefined | string }; feedback?: undefined | \"like\" | \"dislike\" }",
+        "type": "undefined | { id: string; role: \"user\" | \"assistant\"; parts: ({ type: \"text\"; text: string; raw?: undefined | { source: string; payload: unknown } } | { type: \"reasoning\"; text: string; label?: undefined | string; index?: undefined | number; streamId?: undefined | string; signature?: undefined | string; raw?: undefined | { source: string; payload: unknown } } | { type: \"tool\"; tool: { type: string; kind?: undefined | \"command\" | \"file-change\" | \"search\" | \"fetch\" | \"mcp\" | \"image\" | \"generic\"; state: \"input-streaming\" | \"input-available\" | \"output-available\" | \"output-error\"; input?: undefined | Record<string, unknown>; rawInput?: undefined | string; output?: undefined | Record<string, unknown>; toolCallId?: undefined | string; errorText?: undefined | string; raw?: undefined | { source: string; payload: unknown } }; raw?: undefined | { source: string; payload: unknown } } | { type: \"card\"; envelope: { type: string; id: string; data: unknown; title?: undefined | string; resolution?: undefined | { kind: \"action\"; action: string; payload?: unknown; at?: undefined | string } | { kind: \"submit\"; data: unknown; at?: undefined | string } | { kind: \"dismissed\"; at?: undefined | string } | { kind: \"expired\"; reason?: undefined | string; at?: undefined | string } }; raw?: undefined | { source: string; payload: unknown } } | { type: \"source\"; source: { id?: undefined | string; url?: undefined | string; title?: undefined | string; snippet?: undefined | string; index?: undefined | number }; raw?: undefined | { source: string; payload: unknown } } | { type: \"file\"; attachment: { id: string; type: \"file\" | \"source-document\"; filename?: undefined | string; mediaType?: undefined | string; url?: undefined | string; title?: undefined | string }; raw?: undefined | { source: string; payload: unknown } })[]; actions?: undefined | (\"copy\" | \"like\" | \"dislike\" | \"regenerate\" | \"edit\" | { id: string; label: string; icon?: undefined | string; tooltip?: undefined | string })[]; avatar?: undefined | { src?: undefined | string; fallback?: undefined | string; alt?: undefined | string }; feedback?: undefined | \"like\" | \"dislike\" }",
         "optional": true,
         "scalar": false,
         "description": "The full message object. Set as a JS property.",
-        "displayType": "undefined | { id: string; role: \"user\" | \"assistant\"; content: string; reasoning?: undefined | { text: string; label?: undefined | string }; tools?: undefined | { type: string; state: \"input-streaming\" | \"input-available\" | \"output-available\" | \"output-error\"; input?: undefined | Record<string, unknown>; output?: undefined | Record<string, unknown>; toolCallId?: undefined | string; errorText?: undefined | string }[]; attachments?: undefined | { id: string; type: \"file\" | \"source-document\"; filename?: undefined | string; mediaType?: undefined | string; url?: undefined | string; title?: undefined | string }[]; actions?: undefined | (\"copy\" | \"like\" | \"dislike\" | \"regenerate\" | \"edit\" | { id: string; label: string; icon?: undefined | string; tooltip?: undefined | string })[]; avatar?: undefined | { src?: undefined | string; fallback?: undefined | string; alt?: undefined | string }; feedback?: undefined | \"like\" | \"dislike\" }"
+        "typeName": "ChatMessage",
+        "typeShape": "{ id: string; role: \"user\" | \"assistant\"; parts: ({ type: \"text\"; text: string; raw?: undefined | { source: string; payload: unknown } } | { type: \"reasoning\"; text: string; label?: undefined | string; index?: undefined | number; streamId?: undefined | string; signature?: undefined | string; raw?: undefined | { source: string; payload: unknown } } | { type: \"tool\"; tool: { type: string; kind?: undefined | \"command\" | \"file-change\" | \"search\" | \"fetch\" | \"mcp\" | \"image\" | \"generic\"; state: \"input-streaming\" | \"input-available\" | \"output-available\" | \"output-error\"; input?: undefined | Record<string, unknown>; rawInput?: undefined | string; output?: undefined | Record<string, unknown>; toolCallId?: undefined | string; errorText?: undefined | string; raw?: undefined | { source: string; payload: unknown } }; raw?: undefined | { source: string; payload: unknown } } | { type: \"card\"; envelope: { type: string; id: string; data: unknown; title?: undefined | string; resolution?: undefined | { kind: \"action\"; action: string; payload?: unknown; at?: undefined | string } | { kind: \"submit\"; data: unknown; at?: undefined | string } | { kind: \"dismissed\"; at?: undefined | string } | { kind: \"expired\"; reason?: undefined | string; at?: undefined | string } }; raw?: undefined | { source: string; payload: unknown } } | { type: \"source\"; source: { id?: undefined | string; url?: undefined | string; title?: undefined | string; snippet?: undefined | string; index?: undefined | number }; raw?: undefined | { source: string; payload: unknown } } | { type: \"file\"; attachment: { id: string; type: \"file\" | \"source-document\"; filename?: undefined | string; mediaType?: undefined | string; url?: undefined | string; title?: undefined | string }; raw?: undefined | { source: string; payload: unknown } })[]; actions?: undefined | (\"copy\" | \"like\" | \"dislike\" | \"regenerate\" | \"edit\" | { id: string; label: string; icon?: undefined | string; tooltip?: undefined | string })[]; avatar?: undefined | { src?: undefined | string; fallback?: undefined | string; alt?: undefined | string }; feedback?: undefined | \"like\" | \"dislike\" }",
+        "typeImport": "ChatMessage",
+        "displayType": "undefined | { id: string; role: \"user\" | \"assistant\"; parts: ({ type: \"text\"; text: string; raw?: undefined | { source: string; payload: unknown } } | { type: \"reasoning\"; text: string; label?: undefined | string; index?: undefined | number; streamId?: undefined | string; signature?: undefined | string; raw?: undefined | { source: string; payload: unknown } } | { type: \"tool\"; tool: { type: string; kind?: undefined | \"command\" | \"file-change\" | \"search\" | \"fetch\" | \"mcp\" | \"image\" | \"generic\"; state: \"input-streaming\" | \"input-available\" | \"output-available\" | \"output-error\"; input?: undefined | Record<string, unknown>; rawInput?: undefined | string; output?: undefined | Record<string, unknown>; toolCallId?: undefined | string; errorText?: undefined | string; raw?: undefined | { source: string; payload: unknown } }; raw?: undefined | { source: string; payload: unknown } } | { type: \"card\"; envelope: { type: string; id: string; data: unknown; title?: undefined | string; resolution?: undefined | { kind: \"action\"; action: string; payload?: unknown; at?: undefined | string } | { kind: \"submit\"; data: unknown; at?: undefined | string } | { kind: \"dismissed\"; at?: undefined | string } | { kind: \"expired\"; reason?: undefined | string; at?: undefined | string } }; raw?: undefined | { source: string; payload: unknown } } | { type: \"source\"; source: { id?: undefined | string; url?: undefined | string; title?: undefined | string; snippet?: undefined | string; index?: undefined | number }; raw?: undefined | { source: string; payload: unknown } } | { type: \"file\"; attachment: { id: string; type: \"file\" | \"source-document\"; filename?: undefined | string; mediaType?: undefined | string; url?: undefined | string; title?: undefined | string }; raw?: undefined | { source: string; payload: unknown } })[]; actions?: undefined | (\"copy\" | \"like\" | \"dislike\" | \"regenerate\" | \"edit\" | { id: string; label: string; icon?: undefined | string; tooltip?: undefined | string })[]; avatar?: undefined | { src?: undefined | string; fallback?: undefined | string; alt?: undefined | string }; feedback?: undefined | \"like\" | \"dislike\" }"
       },
       {
         "name": "role",
         "type": "undefined | \"user\" | \"assistant\"",
         "optional": true,
         "scalar": true,
-        "description": "Convenience for simple cases when not passing a `message` object.",
+        "description": "Who is speaking: `'user'` or `'assistant'`. Convenience for simple cases when not passing a `message` object. This is the SEMANTIC role of the message, not an ARIA role. The name collides with the global ARIA `role` attribute, which is why the facade lifts it off the host (see `liftRoleOffHost`). Neither speaker is a valid ARIA role, so a `role=\"user\"` left on `<kai-message>` is a CRITICAL axe `aria-roles` violation. The accessible role lives on the row inside the shadow root instead: `role=\"article\"` plus an `aria-label` naming the speaker, matching the SolidJS `<Message>` component.",
         "default": "'assistant'",
         "displayType": "undefined | \"user\" | \"assistant\""
       },
-      {
-        "name": "content",
-        "type": "undefined | string",
-        "optional": true,
-        "scalar": true,
-        "description": "Convenience content (used when `message` is not set).",
-        "displayType": "undefined | string"
-      },
       {
         "name": "markdown",
         "type": "undefined | false | true",
@@ -4103,12 +4684,12 @@
       },
       {
         "name": "proseSize",
-        "type": "undefined | \"sm\" | \"lg\" | \"xs\" | \"base\"",
+        "type": "undefined | \"xs\" | \"sm\" | \"base\" | \"lg\"",
         "optional": true,
         "scalar": true,
         "description": "Text/markdown sizing for the message body.",
         "default": "'sm'",
-        "displayType": "undefined | \"sm\" | \"lg\" | \"xs\" | \"base\""
+        "displayType": "undefined | \"xs\" | \"sm\" | \"base\" | \"lg\""
       },
       {
         "name": "codeTheme",
@@ -4160,6 +4741,22 @@
         "scalar": true,
         "description": "Avatar rail mode. `'none'` omits the avatar rail entirely so the body spans the full row (predictable layout when you never show avatars). Any other value keeps the default behaviour: the built-in avatar when one resolves, or your `slot=\"avatar\"` content when projected (which REPLACES the built-in).",
         "displayType": "undefined | string"
+      },
+      {
+        "name": "cardTypes",
+        "type": "undefined | Record<string, string>",
+        "optional": true,
+        "scalar": false,
+        "description": "Optional card type -> custom-element tag overrides/additions for `card` parts (merged over the built-ins). Property: `el.cardTypes`. Typed as a plain string map (not the `CardTagMap` alias) so the generated React wrapper inlines it instead of emitting an unresolved named type.",
+        "displayType": "undefined | Record<string, string>"
+      },
+      {
+        "name": "cardSchemas",
+        "type": "undefined | Record<string, object>",
+        "optional": true,
+        "scalar": false,
+        "description": "JSON Schemas for the card types this app renders, keyed by envelope type. The companion of `cardTypes`, which says what DRAWS a card while this says what a VALID one looks like. An OBJECT, so it is a JS property only: `el.cardSchemas = { 'pricing-table': pricingSchema }`, never an attribute. `createCardRegistry(...).validationSchemas` is exactly this shape. Without it the kit validates its own seven built-ins and leaves your own card type, the one your app actually cares about, as the only unchecked thing on screen. A schema here WINS over a built-in of the same name. Typed `Record<string, object>` rather than `Record<string, JsonSchema>` deliberately: an imported `.json` schema widens `\"type\"` to `string`, and an authored one carries `$schema`/`title`/`description`/`additionalProperties`, so the tighter type would reject both of the normal ways to supply one.",
+        "displayType": "undefined | Record<string, object>"
       }
     ],
     "events": [
@@ -4196,16 +4793,29 @@
       }
     ],
     "tokens": [],
+    "declarativeChildren": [
+      {
+        "tag": "kai-action",
+        "attributes": [
+          "action",
+          "icon",
+          "id",
+          "label",
+          "tooltip"
+        ],
+        "text": true
+      }
+    ],
     "slots": [
       {
         "name": "before-body",
         "mode": "inject",
-        "doc": "A per-message header at the TOP of the body, above reasoning/tools/content — a model-name label, a role + timestamp line."
+        "doc": "A per-message header at the TOP of the body, above reasoning/tools/content: a model-name label, a role + timestamp line."
       },
       {
         "name": "after-body",
         "mode": "inject",
-        "doc": "A row at the BOTTOM of the body, below the action bar — a citation/sources row, a token-cost/latency line."
+        "doc": "A row at the BOTTOM of the body, below the action bar: a citation/sources row, a token-cost/latency line."
       },
       {
         "name": "avatar",
@@ -4235,6 +4845,11 @@
         "doc": "The action-bar row (copy / like / regenerate …). Restyle its spacing or hide it entirely from outside.",
         "recipe": "kai-message::part(actions) { gap: 0.25rem }"
       },
+      {
+        "name": "citations",
+        "doc": "The citation row rendered from the message’s `source` parts: a wrapped row of chips below the bubble, never inside it. Restyle its spacing or hide it entirely from outside.",
+        "recipe": "kai-message::part(citations) { gap: 0.5rem }"
+      },
       {
         "name": "avatar",
         "doc": "Replaces the built-in avatar rail with your own node. Use `avatar=\"none\"` to omit the rail and let the body span the full row."
@@ -4246,17 +4861,27 @@
     "className": "KaiModelSwitcherElement",
     "displayName": "ModelSwitcher",
     "props": [
+      {
+        "name": "theme",
+        "type": "\"light\" | \"dark\" | \"auto\"",
+        "optional": true,
+        "scalar": true,
+        "description": "Color mode (`auto` follows prefers-color-scheme).",
+        "default": "'auto'",
+        "universal": true,
+        "displayType": "\"light\" | \"dark\" | \"auto\""
+      },
       {
         "name": "models",
-        "type": "{ id: string; name: string; provider?: undefined | string; description?: undefined | string; group?: undefined | string }[]",
-        "optional": false,
+        "type": "undefined | { id: string; name: string; provider?: undefined | string; description?: undefined | string; group?: undefined | string }[]",
+        "optional": true,
         "scalar": false,
-        "description": "The selectable models. Set as a JS property (array).",
+        "description": "The selectable models. Set as a JS property (array). Omit to supply them as `<kai-model>` light-DOM children instead; when both are present the property's models come first.",
         "typeName": "ModelOption[]",
         "typeShape": "{ id: string; name: string; provider?: undefined | string; description?: undefined | string; group?: undefined | string }[]",
         "default": "[]",
         "typeImport": "ModelOption",
-        "displayType": "{ id: string; name: string; provider?: undefined | string; description?: undefined | string; group?: undefined | string }[]"
+        "displayType": "undefined | { id: string; name: string; provider?: undefined | string; description?: undefined | string; group?: undefined | string }[]"
       },
       {
         "name": "currentModel",
@@ -4287,7 +4912,7 @@
         "type": "undefined | false | true",
         "optional": true,
         "scalar": true,
-        "description": "Disable the trigger — click/keyboard and `show()` no longer open the dropdown.",
+        "description": "Disable the trigger: click/keyboard and `show()` no longer open the dropdown.",
         "displayType": "undefined | false | true"
       }
     ],
@@ -4332,20 +4957,46 @@
         "storyId": "solid-advanced-elements-modelswitcher--docs"
       }
     ],
-    "tokens": []
+    "tokens": [],
+    "declarativeChildren": [
+      {
+        "tag": "kai-model",
+        "attributes": [
+          "description",
+          "group",
+          "id",
+          "provider"
+        ],
+        "text": true,
+        "description": "Parse a single light-DOM `<kai-model>` element into a `ModelOption` descriptor. Attribute mapping: - `id` → ModelOption.id - textContent → ModelOption.name - `provider` → ModelOption.provider (optional) - `description` → ModelOption.description (optional subtitle) - `group` → ModelOption.group (optional collapsible section)"
+      }
+    ]
   },
   {
     "tag": "kai-nav",
     "className": "KaiNavElement",
     "displayName": "Nav",
     "props": [
+      {
+        "name": "theme",
+        "type": "\"light\" | \"dark\" | \"auto\"",
+        "optional": true,
+        "scalar": true,
+        "description": "Color mode (`auto` follows prefers-color-scheme).",
+        "default": "'auto'",
+        "universal": true,
+        "displayType": "\"light\" | \"dark\" | \"auto\""
+      },
       {
         "name": "items",
-        "type": "undefined | { id: string; label?: undefined | string; icon?: undefined | string; badge?: undefined | string; trailing?: undefined | string; disabled?: undefined | false | true; children?: undefined | Record<string, unknown>[]; status?: undefined | { tone: \"error\" | \"primary\" | \"info\" | \"success\" | \"warning\" | \"neutral\"; label?: undefined | string; pulse?: undefined | false | true }; meta?: undefined | string; action?: undefined | { icon: string; label: string }; closable?: undefined | false | true }[]",
+        "type": "undefined | { id: string; label?: undefined | string; icon?: undefined | string; badge?: undefined | string; trailing?: undefined | string; disabled?: undefined | false | true; children?: undefined | Record<string, unknown>[]; status?: undefined | { tone: \"primary\" | \"info\" | \"success\" | \"warning\" | \"error\" | \"neutral\"; label?: undefined | string; pulse?: undefined | false | true }; meta?: undefined | string; action?: undefined | { icon: string; label: string }; closable?: undefined | false | true }[]",
         "optional": true,
         "scalar": false,
         "description": "The nav items. Set as a JS property (array, not an attribute). Each item may carry `children` (a collapsible group), a `status` dot, and trailing `meta` text.",
-        "displayType": "undefined | { id: string; label?: undefined | string; icon?: undefined | string; badge?: undefined | string; trailing?: undefined | string; disabled?: undefined | false | true; children?: undefined | Record<string, unknown>[]; status?: undefined | { tone: \"error\" | \"primary\" | \"info\" | \"success\" | \"warning\" | \"neutral\"; label?: undefined | string; pulse?: undefined | false | true }; meta?: undefined | string; action?: undefined | { icon: string; label: string }; closable?: undefined | false | true }[]"
+        "typeName": "KaiNavItem[]",
+        "typeShape": "{ id: string; label?: undefined | string; icon?: undefined | string; badge?: undefined | string; trailing?: undefined | string; disabled?: undefined | false | true; children?: undefined | { id: string; label?: undefined | string; icon?: undefined | string; badge?: undefined | string; trailing?: undefined | string; disabled?: undefined | false | true; children?: undefined | Record<string, unknown>[]; status?: undefined | { tone: \"primary\" | \"info\" | \"success\" | \"warning\" | \"error\" | \"neutral\"; label?: undefined | string; pulse?: undefined | false | true }; meta?: undefined | string; action?: undefined | { icon: string; label: string }; closable?: undefined | false | true }[]; status?: undefined | { tone: \"primary\" | \"info\" | \"success\" | \"warning\" | \"error\" | \"neutral\"; label?: undefined | string; pulse?: undefined | false | true }; meta?: undefined | string; action?: undefined | { icon: string; label: string }; closable?: undefined | false | true }[]",
+        "typeImport": "KaiNavItem",
+        "displayType": "undefined | { id: string; label?: undefined | string; icon?: undefined | string; badge?: undefined | string; trailing?: undefined | string; disabled?: undefined | false | true; children?: undefined | Record<string, unknown>[]; status?: undefined | { tone: \"primary\" | \"info\" | \"success\" | \"warning\" | \"error\" | \"neutral\"; label?: undefined | string; pulse?: undefined | false | true }; meta?: undefined | string; action?: undefined | { icon: string; label: string }; closable?: undefined | false | true }[]"
       },
       {
         "name": "value",
@@ -4451,14 +5102,24 @@
     "className": "KaiNoticeElement",
     "displayName": "Notice",
     "props": [
+      {
+        "name": "theme",
+        "type": "\"light\" | \"dark\" | \"auto\"",
+        "optional": true,
+        "scalar": true,
+        "description": "Color mode (`auto` follows prefers-color-scheme).",
+        "default": "'auto'",
+        "universal": true,
+        "displayType": "\"light\" | \"dark\" | \"auto\""
+      },
       {
         "name": "severity",
-        "type": "undefined | \"error\" | \"info\" | \"success\" | \"warning\" | \"neutral\"",
+        "type": "undefined | \"neutral\" | \"info\" | \"warning\" | \"error\" | \"success\"",
         "optional": true,
         "scalar": true,
         "description": "`neutral` (default) · `info` · `warning` · `error` · `success`. Drives the leading icon's color and the a11y role (`alert` for errors, else `status`).",
         "default": "'neutral'",
-        "displayType": "undefined | \"error\" | \"info\" | \"success\" | \"warning\" | \"neutral\""
+        "displayType": "undefined | \"neutral\" | \"info\" | \"warning\" | \"error\" | \"success\""
       },
       {
         "name": "icon",
@@ -4496,15 +5157,20 @@
     ],
     "tokens": [],
     "slots": [
+      {
+        "name": "",
+        "mode": "inject",
+        "doc": "The notice message. `icon` and `action` are the named seams around it."
+      },
       {
         "name": "action",
         "mode": "inject",
-        "doc": "A trailing action beside the message — a link or button."
+        "doc": "A trailing action beside the message: a link or button."
       },
       {
         "name": "icon",
         "mode": "replace",
-        "doc": "A custom leading icon (any inline SVG, inherits `currentColor`). Overrides the severity default and the `icon` prop — the same escape hatch as `kai-button`."
+        "doc": "A custom leading icon (any inline SVG, inherits `currentColor`). Overrides the severity default and the `icon` prop, the same escape hatch as `kai-button`."
       }
     ]
   },
@@ -4513,6 +5179,16 @@
     "className": "KaiPaneElement",
     "displayName": "Pane",
     "props": [
+      {
+        "name": "theme",
+        "type": "\"light\" | \"dark\" | \"auto\"",
+        "optional": true,
+        "scalar": true,
+        "description": "Color mode (`auto` follows prefers-color-scheme).",
+        "default": "'auto'",
+        "universal": true,
+        "displayType": "\"light\" | \"dark\" | \"auto\""
+      },
       {
         "name": "headline",
         "type": "undefined | string",
@@ -4572,6 +5248,9 @@
         "optional": true,
         "scalar": false,
         "description": "A tone-colored status dot (+ optional label) in the header. An object `{ tone, label?, pulse? }` set as a JS PROPERTY (not an attribute).",
+        "typeName": "PaneStatus",
+        "typeShape": "{ tone: \"working\" | \"idle\" | \"done\" | \"error\" | \"blocked\"; label?: undefined | string; pulse?: undefined | false | true }",
+        "typeImport": "PaneStatus",
         "displayType": "undefined | { tone: \"working\" | \"idle\" | \"done\" | \"error\" | \"blocked\"; label?: undefined | string; pulse?: undefined | false | true }"
       }
     ],
@@ -4591,7 +5270,7 @@
       {
         "name": "kai-maximize",
         "detail": "{ maximized: false | true }",
-        "description": "The maximize/restore control was clicked. `detail.maximized` is the intended NEXT state — drive the `maximized` prop yourself from it.",
+        "description": "The maximize/restore control was clicked. `detail.maximized` is the intended NEXT state. Drive the `maximized` prop yourself from it.",
         "displayDetail": "{ maximized: false | true }"
       },
       {
@@ -4611,6 +5290,11 @@
     ],
     "tokens": [],
     "slots": [
+      {
+        "name": "",
+        "mode": "inject",
+        "doc": "The pane body, below the header row."
+      },
       {
         "name": "leading",
         "mode": "inject",
@@ -4655,12 +5339,25 @@
     "className": "KaiPaneGroupElement",
     "displayName": "PaneGroup",
     "props": [
+      {
+        "name": "theme",
+        "type": "\"light\" | \"dark\" | \"auto\"",
+        "optional": true,
+        "scalar": true,
+        "description": "Color mode (`auto` follows prefers-color-scheme).",
+        "default": "'auto'",
+        "universal": true,
+        "displayType": "\"light\" | \"dark\" | \"auto\""
+      },
       {
         "name": "tabs",
         "type": "undefined | { id: string; name: string; status?: undefined | { tone: \"working\" | \"idle\" | \"done\" | \"error\" | \"blocked\"; label?: undefined | string; pulse?: undefined | false | true }; needsAttention?: undefined | false | true; number?: undefined | number }[]",
         "optional": true,
         "scalar": false,
         "description": "The tabs to render. An array of `{ id, name, status?, needsAttention?, number? }` set as a JS PROPERTY (not an HTML attribute).",
+        "typeName": "PaneTab[]",
+        "typeShape": "{ id: string; name: string; status?: undefined | { tone: \"working\" | \"idle\" | \"done\" | \"error\" | \"blocked\"; label?: undefined | string; pulse?: undefined | false | true }; needsAttention?: undefined | false | true; number?: undefined | number }[]",
+        "typeImport": "PaneTab",
         "displayType": "undefined | { id: string; name: string; status?: undefined | { tone: \"working\" | \"idle\" | \"done\" | \"error\" | \"blocked\"; label?: undefined | string; pulse?: undefined | false | true }; needsAttention?: undefined | false | true; number?: undefined | number }[]"
       },
       {
@@ -4723,6 +5420,13 @@
       }
     ],
     "tokens": [],
+    "slots": [
+      {
+        "name": "",
+        "mode": "inject",
+        "doc": "Content shown for every tab. Use it INSTEAD of the per-tab `slot=\"<tab id>\"` seams when you swap the content yourself."
+      }
+    ],
     "parts": [
       {
         "name": "tabs",
@@ -4756,14 +5460,24 @@
     "className": "KaiPopoverElement",
     "displayName": "Popover",
     "props": [
+      {
+        "name": "theme",
+        "type": "\"light\" | \"dark\" | \"auto\"",
+        "optional": true,
+        "scalar": true,
+        "description": "Color mode (`auto` follows prefers-color-scheme).",
+        "default": "'auto'",
+        "universal": true,
+        "displayType": "\"light\" | \"dark\" | \"auto\""
+      },
       {
         "name": "placement",
-        "type": "undefined | \"top\" | \"right\" | \"bottom\" | \"left\" | \"top-start\" | \"top-end\" | \"right-start\" | \"right-end\" | \"bottom-start\" | \"bottom-end\" | \"left-start\" | \"left-end\"",
+        "type": "undefined | \"top\" | \"right\" | \"bottom\" | \"left\" | \"bottom-end\" | \"bottom-start\" | \"left-end\" | \"left-start\" | \"right-end\" | \"right-start\" | \"top-end\" | \"top-start\"",
         "optional": true,
         "scalar": true,
         "description": "Floating placement relative to the trigger (floating-ui placement).",
         "default": "'bottom-start'",
-        "displayType": "undefined | \"top\" | \"right\" | \"bottom\" | \"left\" | \"top-start\" | \"top-end\" | \"right-start\" | \"right-end\" | \"bottom-start\" | \"bottom-end\" | \"left-start\" | \"left-end\""
+        "displayType": "undefined | \"top\" | \"right\" | \"bottom\" | \"left\" | \"bottom-end\" | \"bottom-start\" | \"left-end\" | \"left-start\" | \"right-end\" | \"right-start\" | \"top-end\" | \"top-start\""
       },
       {
         "name": "gutter",
@@ -4834,13 +5548,35 @@
         "storyId": "solid-advanced-primitives-popover--docs"
       }
     ],
-    "tokens": []
+    "tokens": [],
+    "slots": [
+      {
+        "name": "",
+        "mode": "inject",
+        "doc": "The popover panel body. The control that opens it is the `trigger` slot."
+      },
+      {
+        "name": "trigger",
+        "mode": "replace",
+        "doc": "The control that opens the popover (a button, an avatar, …). The panel anchors to it."
+      }
+    ]
   },
   {
     "tag": "kai-progress-bar",
     "className": "KaiProgressBarElement",
     "displayName": "ProgressBar",
     "props": [
+      {
+        "name": "theme",
+        "type": "\"light\" | \"dark\" | \"auto\"",
+        "optional": true,
+        "scalar": true,
+        "description": "Color mode (`auto` follows prefers-color-scheme).",
+        "default": "'auto'",
+        "universal": true,
+        "displayType": "\"light\" | \"dark\" | \"auto\""
+      },
       {
         "name": "value",
         "type": "undefined | number",
@@ -4903,23 +5639,33 @@
     "className": "KaiPromptDockElement",
     "displayName": "PromptDock",
     "props": [
+      {
+        "name": "theme",
+        "type": "\"light\" | \"dark\" | \"auto\"",
+        "optional": true,
+        "scalar": true,
+        "description": "Color mode (`auto` follows prefers-color-scheme).",
+        "default": "'auto'",
+        "universal": true,
+        "displayType": "\"light\" | \"dark\" | \"auto\""
+      },
       {
         "name": "frame",
-        "type": "undefined | \"none\" | \"inset\" | \"edge\"",
+        "type": "undefined | \"inset\" | \"edge\" | \"none\"",
         "optional": true,
         "scalar": true,
-        "description": "How the tray frames the input — the SPATIAL inset axis: `inset` (default, the classic recessed frame on every side) | `edge` (top/bottom inset only; the input sits flush left/right so the lips span the full width) | `none` (no inset; the lips attach directly as a plain stack). Attribute: `frame`.",
+        "description": "How the tray frames the input, the SPATIAL inset axis: `inset` (default, the classic recessed frame on every side) | `edge` (top/bottom inset only; the input sits flush left/right so the lips span the full width) | `none` (no inset; the lips attach directly as a plain stack). Attribute: `frame`.",
         "default": "'inset'",
-        "displayType": "undefined | \"none\" | \"inset\" | \"edge\""
+        "displayType": "undefined | \"inset\" | \"edge\" | \"none\""
       },
       {
         "name": "appearance",
-        "type": "undefined | \"outlined\" | \"filled\" | \"plain\" | \"soft\"",
+        "type": "undefined | \"soft\" | \"outlined\" | \"filled\" | \"plain\"",
         "optional": true,
         "scalar": true,
-        "description": "How the tray surface looks — the VISUAL axis, orthogonal to `frame`: `soft` (default, sunken surface + border + radius) | `outlined` (transparent + border + radius) | `filled` (sunken, no border, + radius) | `plain` (bare). Attribute: `appearance`.",
+        "description": "How the tray surface looks, the VISUAL axis orthogonal to `frame`: `soft` (default, sunken surface + border + radius) | `outlined` (transparent + border + radius) | `filled` (sunken, no border, + radius) | `plain` (bare). Attribute: `appearance`.",
         "default": "'soft'",
-        "displayType": "undefined | \"outlined\" | \"filled\" | \"plain\" | \"soft\""
+        "displayType": "undefined | \"soft\" | \"outlined\" | \"filled\" | \"plain\""
       }
     ],
     "events": [],
@@ -4933,6 +5679,11 @@
     ],
     "tokens": [],
     "slots": [
+      {
+        "name": "",
+        "mode": "inject",
+        "doc": "The input the dock wraps, typically a `<kai-prompt-input>`. The `top`/`bottom` slots are the lips around it."
+      },
       {
         "name": "top",
         "mode": "inject",
@@ -4967,6 +5718,16 @@
     "className": "KaiPromptInputElement",
     "displayName": "PromptInput",
     "props": [
+      {
+        "name": "theme",
+        "type": "\"light\" | \"dark\" | \"auto\"",
+        "optional": true,
+        "scalar": true,
+        "description": "Color mode (`auto` follows prefers-color-scheme).",
+        "default": "'auto'",
+        "universal": true,
+        "displayType": "\"light\" | \"dark\" | \"auto\""
+      },
       {
         "name": "value",
         "type": "undefined | string | ({ type: \"text\"; text: string } | { type: \"entity\"; entity: { kind: string; id: string; label: string; icon?: undefined | string; promptText?: undefined | string; data?: undefined | Record<string, unknown> } })[]",
@@ -5051,7 +5812,7 @@
         "type": "undefined | \"always\" | \"auto\"",
         "optional": true,
         "scalar": true,
-        "description": "Send-button visibility. `'always'` (default) always shows it; `'auto'` shows it only when there's text/attachments (an empty composer hides it — Enter still submits). To hide it entirely (Enter-only), it's pure CSS: `::part(send){display:none}` — no prop needed. Restyle via `::part(send)`. The Stop button (`stoppable` + `loading`) is unaffected.",
+        "description": "Send-button visibility. `'always'` (default) always shows it; `'auto'` shows it only when there's text/attachments (an empty composer hides it, though Enter still submits). To hide it entirely (Enter-only), it's pure CSS: `::part(send){display:none}`, no prop needed. Restyle via `::part(send)`. The Stop button (`stoppable` + `loading`) is unaffected.",
         "default": "'always'",
         "displayType": "undefined | \"always\" | \"auto\""
       },
@@ -5070,6 +5831,9 @@
         "optional": true,
         "scalar": false,
         "description": "Attachments to seed the input with (so a consumer can pre-populate staged files without an upload). Set as a JS property; the element then manages its own attachment state from there (add via the paperclip, remove per chip).",
+        "typeName": "AttachmentData[]",
+        "typeShape": "{ id: string; type: \"file\" | \"source-document\"; filename?: undefined | string; mediaType?: undefined | string; url?: undefined | string; title?: undefined | string }[]",
+        "typeImport": "AttachmentData",
         "displayType": "AttachmentData[] | undefined"
       },
       {
@@ -5077,7 +5841,10 @@
         "type": "undefined | { char: string; kind: string; items?: undefined | { id: string; label: string; icon?: undefined | string; description?: undefined | string; group?: undefined | string; kind?: undefined | string; promptText?: undefined | string; data?: undefined | Record<string, unknown> }[] }[]",
         "optional": true,
         "scalar": false,
-        "description": "Rich entity triggers — each `{ char, kind, items }` opens a caret-anchored menu that inserts an atomic pill. Convention: `/` → skills, `@` → agents (plugins are the grouping/provenance of those items). Set as a JS property.",
+        "description": "Rich entity triggers. Each `{ char, kind, items }` opens a caret-anchored menu that inserts an atomic pill. Convention: `/` → skills, `@` → agents (plugins are the grouping/provenance of those items). Set as a JS property.",
+        "typeName": "TriggerDef[]",
+        "typeShape": "{ char: string; kind: string; items?: undefined | { id: string; label: string; icon?: undefined | string; description?: undefined | string; group?: undefined | string; kind?: undefined | string; promptText?: undefined | string; data?: undefined | Record<string, unknown> }[] }[]",
+        "typeImport": "TriggerDef",
         "displayType": "undefined | { char: string; kind: string; items?: undefined | { id: string; label: string; icon?: undefined | string; description?: undefined | string; group?: undefined | string; kind?: undefined | string; promptText?: undefined | string; data?: undefined | Record<string, unknown> }[] }[]"
       },
       {
@@ -5093,7 +5860,7 @@
       {
         "name": "kai-attachments-change",
         "detail": "{ attachments: { id: string; type: \"file\" | \"source-document\"; filename?: undefined | string; mediaType?: undefined | string; url?: undefined | string; title?: undefined | string }[] }",
-        "description": "The staged attachments changed — a file was added (via the paperclip) or removed (per-chip ×). Carries the full current list so a consumer can react in real time (validate, show upload progress, toggle the send button).",
+        "description": "The staged attachments changed: a file was added (via the paperclip) or removed (per-chip ×). Carries the full current list so a consumer can react in real time (validate, show upload progress, toggle the send button).",
         "displayDetail": "{ attachments: { id: string; type: \"file\" | \"source-document\"; filename?: undefined | string; mediaType?: undefined | string; url?: undefined | string; title?: undefined | string }[] }"
       },
       {
@@ -5162,21 +5929,90 @@
         "name": "send",
         "params": "",
         "returns": "void",
-        "description": "Send the current value programmatically — same path as Enter / the send button (fires kai-submit, then clears staged attachments). Named `send`, not `submit`, to avoid colliding with the `submit` prop."
+        "description": "Send the current value programmatically, on the same path as Enter / the send button (fires kai-submit, then clears staged attachments). Named `send`, not `submit`, to avoid colliding with the `submit` prop."
+      }
+    ],
+    "composedFrom": [
+      {
+        "name": "PromptInput",
+        "group": "Components",
+        "storyId": "solid-advanced-elements-promptinput--docs"
+      },
+      {
+        "name": "PromptInputTextarea",
+        "group": "Components",
+        "storyId": "solid-advanced-elements-promptinputtextarea--docs"
+      },
+      {
+        "name": "PromptInputActions",
+        "group": "Components",
+        "storyId": "solid-advanced-elements-promptinputactions--docs"
+      },
+      {
+        "name": "PromptSuggestion",
+        "group": "Components",
+        "storyId": "solid-advanced-elements-promptsuggestion--docs"
+      },
+      {
+        "name": "Button",
+        "group": "UI",
+        "storyId": "solid-advanced-primitives-button--docs"
+      },
+      {
+        "name": "Tooltip",
+        "group": "UI",
+        "storyId": "solid-advanced-primitives-tooltip--docs"
+      },
+      {
+        "name": "Attachments",
+        "group": "Components",
+        "storyId": "solid-advanced-elements-attachments--docs"
+      },
+      {
+        "name": "Attachment",
+        "group": "Components",
+        "storyId": "solid-advanced-elements-attachment--docs"
+      },
+      {
+        "name": "AttachmentPreview",
+        "group": "Components",
+        "storyId": "solid-advanced-elements-attachmentpreview--docs"
+      },
+      {
+        "name": "AttachmentInfo",
+        "group": "Components",
+        "storyId": "solid-advanced-elements-attachmentinfo--docs"
+      },
+      {
+        "name": "AttachmentRemove",
+        "group": "Components",
+        "storyId": "solid-advanced-elements-attachmentremove--docs"
       }
     ],
-    "composedFrom": [],
     "tokens": [],
+    "declarativeChildren": [
+      {
+        "tag": "kai-action",
+        "attributes": [
+          "action",
+          "icon",
+          "id",
+          "label",
+          "tooltip"
+        ],
+        "text": true
+      }
+    ],
     "slots": [
       {
         "name": "input-top",
         "mode": "inject",
-        "doc": "Inside the card, above the textarea (e.g. an inline status strip). For content above/below the whole card, use your own layout — that is light DOM you control."
+        "doc": "Inside the card, above the textarea (e.g. an inline status strip). For content above/below the whole card, use your own layout; that is light DOM you control."
       },
       {
         "name": "toolbar-start",
         "mode": "inject",
-        "doc": "Leading controls in the input toolbar — where a + menu goes."
+        "doc": "Leading controls in the input toolbar, where a + menu goes."
       },
       {
         "name": "toolbar-end",
@@ -5187,7 +6023,7 @@
     "parts": [
       {
         "name": "send",
-        "doc": "The send button. Restyle from outside, or hide it entirely (Enter-only) — hiding is pure CSS, which is why there is no `submit=\"never\"`.",
+        "doc": "The send button. Restyle from outside, or hide it entirely (Enter-only). Hiding is pure CSS, which is why there is no `submit=\"never\"`.",
         "recipe": "kai-prompt-input::part(send) { display: none } /* Enter-only; or restyle: background, border-radius, … */"
       }
     ]
@@ -5197,6 +6033,16 @@
     "className": "KaiReasoningElement",
     "displayName": "Reasoning",
     "props": [
+      {
+        "name": "theme",
+        "type": "\"light\" | \"dark\" | \"auto\"",
+        "optional": true,
+        "scalar": true,
+        "description": "Color mode (`auto` follows prefers-color-scheme).",
+        "default": "'auto'",
+        "universal": true,
+        "displayType": "\"light\" | \"dark\" | \"auto\""
+      },
       {
         "name": "text",
         "type": "string",
@@ -5254,7 +6100,7 @@
         "type": "undefined | false | true",
         "optional": true,
         "scalar": true,
-        "description": "Gate the disclosure trigger — programmatic `show()/hide()/toggle()` still work, but the trigger click no longer toggles.",
+        "description": "Gate the disclosure trigger: programmatic `show()/hide()/toggle()` still work, but the trigger click no longer toggles.",
         "displayType": "undefined | false | true"
       }
     ],
@@ -5310,6 +6156,16 @@
     "className": "KaiRemoteElement",
     "displayName": "Remote",
     "props": [
+      {
+        "name": "theme",
+        "type": "\"light\" | \"dark\" | \"auto\"",
+        "optional": true,
+        "scalar": true,
+        "description": "Color mode (`auto` follows prefers-color-scheme).",
+        "default": "'auto'",
+        "universal": true,
+        "displayType": "\"light\" | \"dark\" | \"auto\""
+      },
       {
         "name": "src",
         "type": "undefined | string",
@@ -5353,32 +6209,42 @@
     "className": "KaiResizableElement",
     "displayName": "Resizable",
     "props": [
+      {
+        "name": "theme",
+        "type": "\"light\" | \"dark\" | \"auto\"",
+        "optional": true,
+        "scalar": true,
+        "description": "Color mode (`auto` follows prefers-color-scheme).",
+        "default": "'auto'",
+        "universal": true,
+        "displayType": "\"light\" | \"dark\" | \"auto\""
+      },
       {
         "name": "orientation",
-        "type": "undefined | \"vertical\" | \"horizontal\"",
+        "type": "undefined | \"horizontal\" | \"vertical\"",
         "optional": true,
         "scalar": true,
         "description": "Layout axis: `horizontal` (row, default) or `vertical` (column).",
         "default": "'horizontal'",
-        "displayType": "undefined | \"vertical\" | \"horizontal\""
+        "displayType": "undefined | \"horizontal\" | \"vertical\""
       },
       {
         "name": "maximizedIndex",
-        "type": "undefined | null | number",
+        "type": "undefined | number | null",
         "optional": true,
         "scalar": false,
         "description": "Which item index is maximized (null = none). Declarative source of truth.",
         "default": "null",
-        "displayType": "undefined | null | number"
+        "displayType": "undefined | number | null"
       },
       {
         "name": "handle",
-        "type": "undefined | \"none\" | \"line\" | \"grip\"",
+        "type": "undefined | \"line\" | \"grip\" | \"none\"",
         "optional": true,
         "scalar": true,
-        "description": "Divider affordance drawn inside each draggable handle's 8px grab zone: - `line` (default) — a 1px hairline, transparent at rest, tinting on hover/drag. - `grip` — a dotted grip handle. - `none` — no visible divider, just the invisible hit-area. The full grab zone and keyboard/ARIA behavior are identical for all three.",
+        "description": "Divider affordance drawn inside each draggable handle's 8px grab zone: - `line` (default): a 1px hairline, transparent at rest, tinting on hover/drag. - `grip`: a dotted grip handle. - `none`: no visible divider, just the invisible hit-area. The full grab zone and keyboard/ARIA behavior are identical for all three.",
         "default": "'line'",
-        "displayType": "undefined | \"none\" | \"line\" | \"grip\""
+        "displayType": "undefined | \"line\" | \"grip\" | \"none\""
       }
     ],
     "events": [
@@ -5390,12 +6256,31 @@
       },
       {
         "name": "kai-maximize-change",
-        "detail": "{ maximized: false | true; index: null | number }",
+        "detail": "{ maximized: false | true; index: number | null }",
         "description": "Observe layout maximize state.",
-        "displayDetail": "{ maximized: false | true; index: null | number }"
+        "displayDetail": "{ maximized: false | true; index: number | null }"
+      },
+      {
+        "name": "kai-maximize-state",
+        "detail": "{ maximized: false | true }",
+        "description": "Authoritative maximize state, dispatched as a raw composed CustomEvent (not through `dispatch`) onto the affected `<kai-resizable-item>` and, on restore, onto the group host. A nested element (e.g. `<kai-artifact>`) listens for it to reconcile its own toggle.",
+        "displayDetail": "{ maximized: false | true }"
+      }
+    ],
+    "methods": [
+      {
+        "name": "maximize",
+        "params": "index: number",
+        "returns": "void",
+        "description": "Imperatively maximize the item at `index` (thin wrapper over `maximizedIndex`)."
+      },
+      {
+        "name": "restore",
+        "params": "",
+        "returns": "void",
+        "description": "Imperatively restore from the maximized layout."
       }
     ],
-    "methods": [],
     "composedFrom": [
       {
         "name": "ResizableHandle",
@@ -5403,13 +6288,30 @@
         "storyId": "solid-advanced-primitives-resizablehandle--docs"
       }
     ],
-    "tokens": []
+    "tokens": [],
+    "slots": [
+      {
+        "name": "",
+        "mode": "inject",
+        "doc": "The `<kai-resizable-item>` panels, in order. Dividers are inserted between them."
+      }
+    ]
   },
   {
     "tag": "kai-resizable-item",
     "className": "KaiResizableItemElement",
     "displayName": "ResizableItem",
     "props": [
+      {
+        "name": "theme",
+        "type": "\"light\" | \"dark\" | \"auto\"",
+        "optional": true,
+        "scalar": true,
+        "description": "Color mode (`auto` follows prefers-color-scheme).",
+        "default": "'auto'",
+        "universal": true,
+        "displayType": "\"light\" | \"dark\" | \"auto\""
+      },
       {
         "name": "size",
         "type": "undefined | string",
@@ -5457,7 +6359,7 @@
         "type": "undefined | false | true",
         "optional": true,
         "scalar": true,
-        "description": "Collapse this panel — same layout effect as `hidden` (divider dropped, the rest reflow), but it WORKS as a bare boolean from framework JSX. A plain `<kai-resizable-item collapsed>` in React/Solid/Vue/Svelte collapses the panel at the first render; `hidden` does not, because a JSX boolean sets neither the `hidden` attribute nor the IDL property on a custom element, so the parent never sees it. The facade reflects `collapsed` to a `collapsed` attribute the parent reads. Prefer this over `hidden` for declarative collapse.",
+        "description": "Collapse this panel. Same layout effect as `hidden` (divider dropped, the rest reflow), but it WORKS as a bare boolean from framework JSX. A plain `<kai-resizable-item collapsed>` in React/Solid/Vue/Svelte collapses the panel at the first render; `hidden` does not, because a JSX boolean sets neither the `hidden` attribute nor the IDL property on a custom element, so the parent never sees it. The facade reflects `collapsed` to a `collapsed` attribute the parent reads. Prefer this over `hidden` for declarative collapse.",
         "default": "false",
         "displayType": "undefined | false | true"
       }
@@ -5474,6 +6376,12 @@
         "detail": "unknown",
         "description": "",
         "displayDetail": "unknown"
+      },
+      {
+        "name": "kai-maximize-state",
+        "detail": "unknown",
+        "description": "",
+        "displayDetail": "unknown"
       }
     ],
     "methods": [],
@@ -5484,19 +6392,36 @@
         "storyId": "solid-advanced-primitives-resizablehandle--docs"
       }
     ],
-    "tokens": []
+    "tokens": [],
+    "slots": [
+      {
+        "name": "",
+        "mode": "inject",
+        "doc": "This panel's content."
+      }
+    ]
   },
   {
     "tag": "kai-response-stream",
     "className": "KaiResponseStreamElement",
     "displayName": "ResponseStream",
     "props": [
+      {
+        "name": "theme",
+        "type": "\"light\" | \"dark\" | \"auto\"",
+        "optional": true,
+        "scalar": true,
+        "description": "Color mode (`auto` follows prefers-color-scheme).",
+        "default": "'auto'",
+        "universal": true,
+        "displayType": "\"light\" | \"dark\" | \"auto\""
+      },
       {
         "name": "text",
         "type": "undefined | string | AsyncIterable<string>",
         "optional": true,
         "scalar": false,
-        "description": "Text to stream. A string, or an `AsyncIterable<string>` (set as a JS property — async iterables can't be HTML attributes).",
+        "description": "Text to stream. A string, or an `AsyncIterable<string>` (set as a JS property, since async iterables can't be HTML attributes).",
         "default": "''",
         "displayType": "undefined | string | AsyncIterable<string>"
       },
@@ -5550,23 +6475,33 @@
     "className": "KaiScopePickerElement",
     "displayName": "ScopePicker",
     "props": [
+      {
+        "name": "theme",
+        "type": "\"light\" | \"dark\" | \"auto\"",
+        "optional": true,
+        "scalar": true,
+        "description": "Color mode (`auto` follows prefers-color-scheme).",
+        "default": "'auto'",
+        "universal": true,
+        "displayType": "\"light\" | \"dark\" | \"auto\""
+      },
       {
         "name": "availableAuthors",
-        "type": "string[]",
-        "optional": false,
+        "type": "undefined | string[]",
+        "optional": true,
         "scalar": false,
-        "description": "Authors to offer as scope filters. Set as a JS property.",
+        "description": "Authors to offer as scope filters. Omit to drop the Authors section (for a tag-only picker). Set as a JS property.",
         "default": "[]",
-        "displayType": "string[]"
+        "displayType": "undefined | string[]"
       },
       {
         "name": "availableTags",
-        "type": "string[]",
-        "optional": false,
+        "type": "undefined | string[]",
+        "optional": true,
         "scalar": false,
-        "description": "Tags to offer as scope filters. Set as a JS property.",
+        "description": "Tags to offer as scope filters. Omit to drop the Tags section (for an author-only picker). Set as a JS property.",
         "default": "[]",
-        "displayType": "string[]"
+        "displayType": "undefined | string[]"
       },
       {
         "name": "currentLabel",
@@ -5598,7 +6533,7 @@
         "type": "undefined | false | true",
         "optional": true,
         "scalar": true,
-        "description": "Disable the trigger — click/keyboard and `show()` no longer open the dropdown.",
+        "description": "Disable the trigger: click/keyboard and `show()` no longer open the dropdown.",
         "displayType": "undefined | false | true"
       }
     ],
@@ -5611,9 +6546,9 @@
       },
       {
         "name": "kai-scope-change",
-        "detail": "{ filters: undefined | { tags?: undefined | string[]; authors?: undefined | string[]; contentType?: undefined | \"transcript\" | \"markdown\"; dateRange?: undefined | { from: string; to: string } } }",
+        "detail": "{ filters: { tags?: undefined | string[]; authors?: undefined | string[]; contentType?: undefined | \"transcript\" | \"markdown\"; dateRange?: undefined | { from: string; to: string } } | undefined }",
         "description": "A scope was chosen (`undefined` filters = \"All Content\").",
-        "displayDetail": "{ filters: SearchFilters | undefined }"
+        "displayDetail": "{ filters: { tags?: undefined | string[]; authors?: undefined | string[]; contentType?: undefined | \"transcript\" | \"markdown\"; dateRange?: undefined | { from: string; to: string } } | undefined }"
       }
     ],
     "methods": [
@@ -5650,6 +6585,16 @@
     "className": "KaiScreenElement",
     "displayName": "Screen",
     "props": [
+      {
+        "name": "theme",
+        "type": "\"light\" | \"dark\" | \"auto\"",
+        "optional": true,
+        "scalar": true,
+        "description": "Color mode (`auto` follows prefers-color-scheme).",
+        "default": "'auto'",
+        "universal": true,
+        "displayType": "\"light\" | \"dark\" | \"auto\""
+      },
       {
         "name": "open",
         "type": "undefined | false | true",
@@ -5740,6 +6685,11 @@
     ],
     "tokens": [],
     "slots": [
+      {
+        "name": "",
+        "mode": "inject",
+        "doc": "The screen body, below the title bar."
+      },
       {
         "name": "title",
         "mode": "replace",
@@ -5779,6 +6729,16 @@
     "className": "KaiScrollAreaElement",
     "displayName": "ScrollArea",
     "props": [
+      {
+        "name": "theme",
+        "type": "\"light\" | \"dark\" | \"auto\"",
+        "optional": true,
+        "scalar": true,
+        "description": "Color mode (`auto` follows prefers-color-scheme).",
+        "default": "'auto'",
+        "universal": true,
+        "displayType": "\"light\" | \"dark\" | \"auto\""
+      },
       {
         "name": "orientation",
         "type": "undefined | \"vertical\" | \"horizontal\" | \"both\"",
@@ -5799,6 +6759,13 @@
       }
     ],
     "tokens": [],
+    "slots": [
+      {
+        "name": "",
+        "mode": "inject",
+        "doc": "The scrollable content."
+      }
+    ],
     "parts": [
       {
         "name": "viewport",
@@ -5812,6 +6779,16 @@
     "className": "KaiScrollButtonElement",
     "displayName": "ScrollButton",
     "props": [
+      {
+        "name": "theme",
+        "type": "\"light\" | \"dark\" | \"auto\"",
+        "optional": true,
+        "scalar": true,
+        "description": "Color mode (`auto` follows prefers-color-scheme).",
+        "default": "'auto'",
+        "universal": true,
+        "displayType": "\"light\" | \"dark\" | \"auto\""
+      },
       {
         "name": "for",
         "type": "undefined | string",
@@ -5822,12 +6799,12 @@
       },
       {
         "name": "variant",
-        "type": "undefined | \"default\" | \"ghost\" | \"outline\"",
+        "type": "undefined | \"outline\" | \"ghost\" | \"default\"",
         "optional": true,
         "scalar": true,
         "description": "Button visual variant: `'outline' | 'ghost' | 'default'`. Defaults to `'outline'`.",
         "default": "'outline'",
-        "displayType": "undefined | \"default\" | \"ghost\" | \"outline\""
+        "displayType": "undefined | \"outline\" | \"ghost\" | \"default\""
       },
       {
         "name": "size",
@@ -5843,7 +6820,7 @@
       {
         "name": "kai-scroll",
         "detail": null,
-        "description": "Emitted when the user clicks the button and `scrollToBottom()` is called. Carries no detail — consumers use it to know a manual scroll occurred.",
+        "description": "Emitted when the user clicks the button and `scrollToBottom()` is called. Carries no detail; consumers use it to know a manual scroll occurred.",
         "displayDetail": null
       }
     ],
@@ -5862,12 +6839,22 @@
     "className": "KaiSearchElement",
     "displayName": "Search",
     "props": [
+      {
+        "name": "theme",
+        "type": "\"light\" | \"dark\" | \"auto\"",
+        "optional": true,
+        "scalar": true,
+        "description": "Color mode (`auto` follows prefers-color-scheme).",
+        "default": "'auto'",
+        "universal": true,
+        "displayType": "\"light\" | \"dark\" | \"auto\""
+      },
       {
         "name": "value",
         "type": "undefined | string",
         "optional": true,
         "scalar": true,
-        "description": "Controlled query — settable and reflected to the `value` attribute. Read `el.value` for live state.",
+        "description": "Controlled query. Settable and reflected to the `value` attribute. Read `el.value` for live state.",
         "displayType": "undefined | string"
       },
       {
@@ -5940,7 +6927,13 @@
         "name": "focus",
         "params": "",
         "returns": "void",
-        "description": ""
+        "description": "Focus the search input inside the shadow root. A native `focus()` on the host lands on the host itself and never reaches it."
+      },
+      {
+        "name": "clear",
+        "params": "",
+        "returns": "void",
+        "description": "Empty the field and fire `kai-search` with an empty value immediately, cancelling any debounced search still in flight, then return focus to the input. Same path as the trailing clear button."
       }
     ],
     "composedFrom": [
@@ -5984,15 +6977,26 @@
     "className": "KaiSegmentedElement",
     "displayName": "Segmented",
     "props": [
+      {
+        "name": "theme",
+        "type": "\"light\" | \"dark\" | \"auto\"",
+        "optional": true,
+        "scalar": true,
+        "description": "Color mode (`auto` follows prefers-color-scheme).",
+        "default": "'auto'",
+        "universal": true,
+        "displayType": "\"light\" | \"dark\" | \"auto\""
+      },
       {
         "name": "options",
         "type": "{ value: string; label: string; icon?: undefined | string }[]",
         "optional": false,
         "scalar": false,
         "description": "The selectable segments, left to right. Set as a JS property (array).",
-        "typeName": "Option[]",
+        "typeName": "KaiSegmentedOption[]",
         "typeShape": "{ value: string; label: string; icon?: undefined | string }[]",
         "default": "[]",
+        "typeImport": "KaiSegmentedOption",
         "displayType": "{ value: string; label: string; icon?: undefined | string }[]"
       },
       {
@@ -6000,7 +7004,7 @@
         "type": "undefined | string",
         "optional": true,
         "scalar": true,
-        "description": "Controlled selected `value` — settable and reflected to the `value` attribute. `el.value = 'preview'` drives it; choosing a segment updates it and fires `kai-change`. Read `el.value` for live state.",
+        "description": "Controlled selected `value`. Settable and reflected to the `value` attribute. `el.value = 'preview'` drives it; choosing a segment updates it and fires `kai-change`. Read `el.value` for live state.",
         "displayType": "undefined | string"
       },
       {
@@ -6048,14 +7052,24 @@
     "className": "KaiSeparatorElement",
     "displayName": "Separator",
     "props": [
+      {
+        "name": "theme",
+        "type": "\"light\" | \"dark\" | \"auto\"",
+        "optional": true,
+        "scalar": true,
+        "description": "Color mode (`auto` follows prefers-color-scheme).",
+        "default": "'auto'",
+        "universal": true,
+        "displayType": "\"light\" | \"dark\" | \"auto\""
+      },
       {
         "name": "orientation",
-        "type": "undefined | \"vertical\" | \"horizontal\"",
+        "type": "undefined | \"horizontal\" | \"vertical\"",
         "optional": true,
         "scalar": true,
-        "description": "`horizontal` (default, block + full-width) or `vertical` (a rule inside a flex/grid row — it stretches to the row height).",
+        "description": "`horizontal` (default, block + full-width) or `vertical` (a rule inside a flex/grid row, stretching to the row height).",
         "default": "'horizontal'",
-        "displayType": "undefined | \"vertical\" | \"horizontal\""
+        "displayType": "undefined | \"horizontal\" | \"vertical\""
       }
     ],
     "events": [],
@@ -6081,6 +7095,16 @@
     "className": "KaiSettingItemElement",
     "displayName": "SettingItem",
     "props": [
+      {
+        "name": "theme",
+        "type": "\"light\" | \"dark\" | \"auto\"",
+        "optional": true,
+        "scalar": true,
+        "description": "Color mode (`auto` follows prefers-color-scheme).",
+        "default": "'auto'",
+        "universal": true,
+        "displayType": "\"light\" | \"dark\" | \"auto\""
+      },
       {
         "name": "label",
         "type": "undefined | string",
@@ -6134,6 +7158,16 @@
     "className": "KaiSettingsGroupElement",
     "displayName": "SettingsGroup",
     "props": [
+      {
+        "name": "theme",
+        "type": "\"light\" | \"dark\" | \"auto\"",
+        "optional": true,
+        "scalar": true,
+        "description": "Color mode (`auto` follows prefers-color-scheme).",
+        "default": "'auto'",
+        "universal": true,
+        "displayType": "\"light\" | \"dark\" | \"auto\""
+      },
       {
         "name": "heading",
         "type": "undefined | string",
@@ -6162,6 +7196,13 @@
       }
     ],
     "tokens": [],
+    "slots": [
+      {
+        "name": "",
+        "mode": "inject",
+        "doc": "The `<kai-setting-item>` rows in this group."
+      }
+    ],
     "parts": [
       {
         "name": "header",
@@ -6180,6 +7221,16 @@
     "className": "KaiSkeletonElement",
     "displayName": "Skeleton",
     "props": [
+      {
+        "name": "theme",
+        "type": "\"light\" | \"dark\" | \"auto\"",
+        "optional": true,
+        "scalar": true,
+        "description": "Color mode (`auto` follows prefers-color-scheme).",
+        "default": "'auto'",
+        "universal": true,
+        "displayType": "\"light\" | \"dark\" | \"auto\""
+      },
       {
         "name": "variant",
         "type": "undefined | \"text\" | \"rect\" | \"circle\"",
@@ -6237,16 +7288,27 @@
     "className": "KaiSkillsElement",
     "displayName": "Skills",
     "props": [
+      {
+        "name": "theme",
+        "type": "\"light\" | \"dark\" | \"auto\"",
+        "optional": true,
+        "scalar": true,
+        "description": "Color mode (`auto` follows prefers-color-scheme).",
+        "default": "'auto'",
+        "universal": true,
+        "displayType": "\"light\" | \"dark\" | \"auto\""
+      },
       {
         "name": "skills",
-        "type": "{ id: string; name: string }[]",
-        "optional": false,
+        "type": "undefined | { id: string; name: string }[]",
+        "optional": true,
         "scalar": false,
-        "description": "The active skills to badge. Set as a JS property.",
+        "description": "The active skills to badge. Set as a JS property. Omit to supply them as `<kai-skill>` light-DOM children instead; when both are present the property's skills come first. Nothing renders when there are none.",
         "typeName": "Skill[]",
         "typeShape": "{ id: string; name: string }[]",
         "default": "[]",
-        "displayType": "{ id: string; name: string }[]"
+        "typeImport": "Skill",
+        "displayType": "undefined | { id: string; name: string }[]"
       }
     ],
     "events": [],
@@ -6258,13 +7320,33 @@
         "storyId": "solid-advanced-elements-messageskills--docs"
       }
     ],
-    "tokens": []
+    "tokens": [],
+    "declarativeChildren": [
+      {
+        "tag": "kai-skill",
+        "attributes": [
+          "id"
+        ],
+        "text": true,
+        "description": "Parse a single light-DOM `<kai-skill>` element into a `Skill` descriptor. Attribute / content mapping: - `id` → Skill.id (falls back to `name` when absent) - `textContent` → Skill.name (the human-readable badge label) Example: `<kai-skill id=\"web-search\">Web Search</kai-skill>`"
+      }
+    ]
   },
   {
     "tag": "kai-source",
     "className": "KaiSourceElement",
     "displayName": "Source",
     "props": [
+      {
+        "name": "theme",
+        "type": "\"light\" | \"dark\" | \"auto\"",
+        "optional": true,
+        "scalar": true,
+        "description": "Color mode (`auto` follows prefers-color-scheme).",
+        "default": "'auto'",
+        "universal": true,
+        "displayType": "\"light\" | \"dark\" | \"auto\""
+      },
       {
         "name": "href",
         "type": "undefined | string",
@@ -6287,7 +7369,7 @@
         "type": "undefined | string",
         "optional": true,
         "scalar": true,
-        "description": "Hover-card headline. Attribute: `headline` (`title` is avoided — it's a global HTML attribute that reflects in a CE constructor and breaks it).",
+        "description": "Hover-card headline. Attribute: `headline` (`title` is avoided because it is a global HTML attribute that reflects in a CE constructor and breaks it).",
         "default": "''",
         "displayType": "undefined | string"
       },
@@ -6341,16 +7423,27 @@
     "className": "KaiSourcesElement",
     "displayName": "Sources",
     "props": [
+      {
+        "name": "theme",
+        "type": "\"light\" | \"dark\" | \"auto\"",
+        "optional": true,
+        "scalar": true,
+        "description": "Color mode (`auto` follows prefers-color-scheme).",
+        "default": "'auto'",
+        "universal": true,
+        "displayType": "\"light\" | \"dark\" | \"auto\""
+      },
       {
         "name": "sources",
-        "type": "{ href: string; title?: undefined | string; description?: undefined | string; label?: undefined | string; showFavicon?: undefined | false | true }[]",
-        "optional": false,
+        "type": "undefined | { href: string; title?: undefined | string; description?: undefined | string; label?: undefined | string; showFavicon?: undefined | false | true }[]",
+        "optional": true,
         "scalar": false,
-        "description": "The sources to render. Set as a JS property.",
-        "typeName": "SourceItem[]",
+        "description": "The sources to render. Set as a JS property. Omit to supply them as `<kai-source>` light-DOM children instead; when both are present the property's sources come first.",
+        "typeName": "KaiSourceItem[]",
         "typeShape": "{ href: string; title?: undefined | string; description?: undefined | string; label?: undefined | string; showFavicon?: undefined | false | true }[]",
         "default": "[]",
-        "displayType": "SourceItem[]"
+        "typeImport": "KaiSourceItem",
+        "displayType": "undefined | { href: string; title?: undefined | string; description?: undefined | string; label?: undefined | string; showFavicon?: undefined | false | true }[]"
       },
       {
         "name": "showFavicon",
@@ -6366,7 +7459,7 @@
         "type": "undefined | false | true",
         "optional": true,
         "scalar": true,
-        "description": "When true, each citation chip is labelled with its 1-based index in the merged (prop + declarative-children) list (`[1]`, `[2]`, …) instead of the per-item `label` or domain fallback. HTML attribute: `numbered` (boolean — bare attribute or `numbered=\"true\"`). JS property: `el.numbered = true`.",
+        "description": "When true, each citation chip is labelled with its 1-based index in the merged (prop + declarative-children) list (`[1]`, `[2]`, …) instead of the per-item `label` or domain fallback. HTML attribute: `numbered` (boolean: a bare attribute or `numbered=\"true\"`). JS property: `el.numbered = true`.",
         "default": "false",
         "displayType": "undefined | false | true"
       }
@@ -6395,13 +7488,37 @@
         "storyId": "solid-advanced-elements-sourcelist--docs"
       }
     ],
-    "tokens": []
+    "tokens": [],
+    "declarativeChildren": [
+      {
+        "tag": "kai-source",
+        "attributes": [
+          "description",
+          "headline",
+          "href",
+          "label",
+          "show-favicon"
+        ],
+        "text": false,
+        "description": "Parse a single light-DOM `<kai-source>` element into a `KaiSourceItem` descriptor. Attribute mapping: - `href` → KaiSourceItem.href - `label` → KaiSourceItem.label - `headline` → KaiSourceItem.title (matches kai-source's prop name; \"title\" is a reserved HTMLElement attribute so kai-source uses \"headline\") - `description` → KaiSourceItem.description - `show-favicon`→ KaiSourceItem.showFavicon (bare boolean attribute)"
+      }
+    ]
   },
   {
     "tag": "kai-status",
     "className": "KaiStatusElement",
     "displayName": "Status",
     "props": [
+      {
+        "name": "theme",
+        "type": "\"light\" | \"dark\" | \"auto\"",
+        "optional": true,
+        "scalar": true,
+        "description": "Color mode (`auto` follows prefers-color-scheme).",
+        "default": "'auto'",
+        "universal": true,
+        "displayType": "\"light\" | \"dark\" | \"auto\""
+      },
       {
         "name": "status",
         "type": "undefined | \"new\" | \"online\" | \"busy\" | \"away\" | \"offline\"",
@@ -6461,23 +7578,33 @@
     "className": "KaiSuggestionsElement",
     "displayName": "Suggestions",
     "props": [
+      {
+        "name": "theme",
+        "type": "\"light\" | \"dark\" | \"auto\"",
+        "optional": true,
+        "scalar": true,
+        "description": "Color mode (`auto` follows prefers-color-scheme).",
+        "default": "'auto'",
+        "universal": true,
+        "displayType": "\"light\" | \"dark\" | \"auto\""
+      },
       {
         "name": "suggestions",
-        "type": "(string | { label: string; value?: undefined | string; icon?: undefined | string })[]",
-        "optional": false,
+        "type": "undefined | (string | { label: string; value?: undefined | string; icon?: undefined | string })[]",
+        "optional": true,
         "scalar": false,
-        "description": "The suggestions. Strings, or `{ label, value }` when the displayed text and the emitted value differ. Set as a JS property.",
+        "description": "The suggestions. Strings, or `{ label, value }` when the displayed text and the emitted value differ. Set as a JS property. Omit to supply them as `<kai-suggestion>` light-DOM children instead; when both are present the property's suggestions come first.",
         "default": "[]",
-        "displayType": "(string | { label: string; value?: undefined | string; icon?: undefined | string })[]"
+        "displayType": "undefined | (string | { label: string; value?: undefined | string; icon?: undefined | string })[]"
       },
       {
         "name": "variant",
-        "type": "undefined | \"default\" | \"ghost\" | \"outline\"",
+        "type": "undefined | \"outline\" | \"ghost\" | \"default\"",
         "optional": true,
         "scalar": true,
         "description": "Chip style: `'outline'` (default), `'ghost'`, or `'default'` (filled).",
         "default": "'outline'",
-        "displayType": "undefined | \"default\" | \"ghost\" | \"outline\""
+        "displayType": "undefined | \"outline\" | \"ghost\" | \"default\""
       },
       {
         "name": "size",
@@ -6490,12 +7617,12 @@
       },
       {
         "name": "layout",
-        "type": "undefined | \"list\" | \"chips\"",
+        "type": "undefined | \"chips\" | \"list\"",
         "optional": true,
         "scalar": true,
-        "description": "Layout: `'chips'` (default) renders a wrapping row of rounded pills; `'list'` renders a vertical, full-width \"Ideas for you\" list — each row is left-aligned with a leading `icon`, a label, and a hover background.",
+        "description": "Layout: `'chips'` (default) renders a wrapping row of rounded pills; `'list'` renders a vertical, full-width \"Ideas for you\" list where each row is left-aligned with a leading `icon`, a label, and a hover background.",
         "default": "'chips'",
-        "displayType": "undefined | \"list\" | \"chips\""
+        "displayType": "undefined | \"chips\" | \"list\""
       },
       {
         "name": "block",
@@ -6531,19 +7658,40 @@
         "storyId": "solid-advanced-elements-promptsuggestion--docs"
       }
     ],
-    "tokens": []
+    "tokens": [],
+    "declarativeChildren": [
+      {
+        "tag": "kai-suggestion",
+        "attributes": [
+          "icon",
+          "value"
+        ],
+        "text": true,
+        "description": "Parse a single `<kai-suggestion>` node into an `Item` descriptor."
+      }
+    ]
   },
   {
     "tag": "kai-switch",
     "className": "KaiSwitchElement",
     "displayName": "Switch",
     "props": [
+      {
+        "name": "theme",
+        "type": "\"light\" | \"dark\" | \"auto\"",
+        "optional": true,
+        "scalar": true,
+        "description": "Color mode (`auto` follows prefers-color-scheme).",
+        "default": "'auto'",
+        "universal": true,
+        "displayType": "\"light\" | \"dark\" | \"auto\""
+      },
       {
         "name": "checked",
         "type": "undefined | false | true",
         "optional": true,
         "scalar": true,
-        "description": "Controlled checked state — settable and reflected to the `checked` attribute. `el.checked = true` (or `<kai-switch checked>`) drives it; the toggle UI updates it and fires `kai-change`. Read `el.checked` for live state.",
+        "description": "Controlled checked state. Settable and reflected to the `checked` attribute. `el.checked = true` (or `<kai-switch checked>`) drives it; the toggle UI updates it and fires `kai-change`. Read `el.checked` for live state.",
         "displayType": "undefined | false | true"
       },
       {
@@ -6623,12 +7771,25 @@
     "className": "KaiTabsElement",
     "displayName": "Tabs",
     "props": [
+      {
+        "name": "theme",
+        "type": "\"light\" | \"dark\" | \"auto\"",
+        "optional": true,
+        "scalar": true,
+        "description": "Color mode (`auto` follows prefers-color-scheme).",
+        "default": "'auto'",
+        "universal": true,
+        "displayType": "\"light\" | \"dark\" | \"auto\""
+      },
       {
         "name": "items",
         "type": "undefined | { id: string; label?: undefined | string; icon?: undefined | string; disabled?: undefined | false | true }[]",
         "optional": true,
         "scalar": false,
         "description": "Tabs to render. Set as a JS property, not an HTML attribute.",
+        "typeName": "KaiTabItem[]",
+        "typeShape": "{ id: string; label?: undefined | string; icon?: undefined | string; disabled?: undefined | false | true }[]",
+        "typeImport": "KaiTabItem",
         "displayType": "undefined | { id: string; label?: undefined | string; icon?: undefined | string; disabled?: undefined | false | true }[]"
       },
       {
@@ -6721,13 +7882,26 @@
     "className": "KaiTasksElement",
     "displayName": "Tasks",
     "props": [
+      {
+        "name": "theme",
+        "type": "\"light\" | \"dark\" | \"auto\"",
+        "optional": true,
+        "scalar": true,
+        "description": "Color mode (`auto` follows prefers-color-scheme).",
+        "default": "'auto'",
+        "universal": true,
+        "displayType": "\"light\" | \"dark\" | \"auto\""
+      },
       {
         "name": "data",
-        "type": "undefined | Record<string, unknown>",
+        "type": "undefined | { mode?: undefined | \"select\" | \"progress\"; heading?: undefined | string; tasks: { id: string; label: string; description?: undefined | string; checked?: undefined | false | true; disabled?: undefined | false | true }[]; selectAll?: undefined | false | true; confirmLabel?: undefined | string; allowEmpty?: undefined | false | true; min?: undefined | number; max?: undefined | number; dismissible?: undefined | false | true }",
         "optional": true,
         "scalar": false,
         "description": "The tasks definition (the CardEnvelope.data). Set as a JS PROPERTY: `el.data = { tasks:[…], selectAll, confirmLabel, … }`. Import `TasksCardData` from `@kitn.ai/ui` for the full shape.",
-        "displayType": "undefined | Record<string, unknown>"
+        "typeName": "TasksCardData",
+        "typeShape": "{ mode?: undefined | \"select\" | \"progress\"; heading?: undefined | string; tasks: { id: string; label: string; description?: undefined | string; checked?: undefined | false | true; disabled?: undefined | false | true }[]; selectAll?: undefined | false | true; confirmLabel?: undefined | string; allowEmpty?: undefined | false | true; min?: undefined | number; max?: undefined | number; dismissible?: undefined | false | true }",
+        "typeImport": "TasksCardData",
+        "displayType": "undefined | { mode?: undefined | \"select\" | \"progress\"; heading?: undefined | string; tasks: { id: string; label: string; description?: undefined | string; checked?: undefined | false | true; disabled?: undefined | false | true }[]; selectAll?: undefined | false | true; confirmLabel?: undefined | string; allowEmpty?: undefined | false | true; min?: undefined | number; max?: undefined | number; dismissible?: undefined | false | true }"
       },
       {
         "name": "cardId",
@@ -6792,7 +7966,7 @@
       {
         "name": "kai-value-change",
         "detail": "{ value: string[] }",
-        "description": "The selection changed on a toggle — the selected ids in input order.",
+        "description": "The selection changed on a toggle. Carries the selected ids in input order.",
         "displayDetail": "{ value: string[] }"
       }
     ],
@@ -6813,7 +7987,7 @@
         "name": "send",
         "params": "",
         "returns": "void",
-        "description": "Confirm the current selection — emits the `submit` CardEvent + resolves (only when the min/max gate passes). Named `send`, not `submit`."
+        "description": "Confirm the current selection: emits the `submit` CardEvent + resolves (only when the min/max gate passes). Named `send`, not `submit`."
       },
       {
         "name": "focus",
@@ -6848,6 +8022,16 @@
     "className": "KaiTextShimmerElement",
     "displayName": "TextShimmer",
     "props": [
+      {
+        "name": "theme",
+        "type": "\"light\" | \"dark\" | \"auto\"",
+        "optional": true,
+        "scalar": true,
+        "description": "Color mode (`auto` follows prefers-color-scheme).",
+        "default": "'auto'",
+        "universal": true,
+        "displayType": "\"light\" | \"dark\" | \"auto\""
+      },
       {
         "name": "text",
         "type": "undefined | string",
@@ -6901,6 +8085,16 @@
     "className": "KaiThinkingBarElement",
     "displayName": "ThinkingBar",
     "props": [
+      {
+        "name": "theme",
+        "type": "\"light\" | \"dark\" | \"auto\"",
+        "optional": true,
+        "scalar": true,
+        "description": "Color mode (`auto` follows prefers-color-scheme).",
+        "default": "'auto'",
+        "universal": true,
+        "displayType": "\"light\" | \"dark\" | \"auto\""
+      },
       {
         "name": "text",
         "type": "undefined | string",
@@ -6952,31 +8146,44 @@
     "className": "KaiThreadElement",
     "displayName": "Thread",
     "props": [
+      {
+        "name": "theme",
+        "type": "\"light\" | \"dark\" | \"auto\"",
+        "optional": true,
+        "scalar": true,
+        "description": "Color mode (`auto` follows prefers-color-scheme).",
+        "default": "'auto'",
+        "universal": true,
+        "displayType": "\"light\" | \"dark\" | \"auto\""
+      },
       {
         "name": "messages",
-        "type": "undefined | { id: string; role: \"user\" | \"assistant\"; content: string; reasoning?: undefined | { text: string; label?: undefined | string }; tools?: undefined | { type: string; state: \"input-streaming\" | \"input-available\" | \"output-available\" | \"output-error\"; input?: undefined | Record<string, unknown>; output?: undefined | Record<string, unknown>; toolCallId?: undefined | string; errorText?: undefined | string }[]; attachments?: undefined | { id: string; type: \"file\" | \"source-document\"; filename?: undefined | string; mediaType?: undefined | string; url?: undefined | string; title?: undefined | string }[]; actions?: undefined | (\"copy\" | \"like\" | \"dislike\" | \"regenerate\" | \"edit\" | { id: string; label: string; icon?: undefined | string; tooltip?: undefined | string })[]; avatar?: undefined | { src?: undefined | string; fallback?: undefined | string; alt?: undefined | string }; feedback?: undefined | \"like\" | \"dislike\" }[]",
+        "type": "undefined | { id: string; role: \"user\" | \"assistant\"; parts: ({ type: \"text\"; text: string; raw?: undefined | { source: string; payload: unknown } } | { type: \"reasoning\"; text: string; label?: undefined | string; index?: undefined | number; streamId?: undefined | string; signature?: undefined | string; raw?: undefined | { source: string; payload: unknown } } | { type: \"tool\"; tool: { type: string; kind?: undefined | \"command\" | \"file-change\" | \"search\" | \"fetch\" | \"mcp\" | \"image\" | \"generic\"; state: \"input-streaming\" | \"input-available\" | \"output-available\" | \"output-error\"; input?: undefined | Record<string, unknown>; rawInput?: undefined | string; output?: undefined | Record<string, unknown>; toolCallId?: undefined | string; errorText?: undefined | string; raw?: undefined | { source: string; payload: unknown } }; raw?: undefined | { source: string; payload: unknown } } | { type: \"card\"; envelope: { type: string; id: string; data: unknown; title?: undefined | string; resolution?: undefined | { kind: \"action\"; action: string; payload?: unknown; at?: undefined | string } | { kind: \"submit\"; data: unknown; at?: undefined | string } | { kind: \"dismissed\"; at?: undefined | string } | { kind: \"expired\"; reason?: undefined | string; at?: undefined | string } }; raw?: undefined | { source: string; payload: unknown } } | { type: \"source\"; source: { id?: undefined | string; url?: undefined | string; title?: undefined | string; snippet?: undefined | string; index?: undefined | number }; raw?: undefined | { source: string; payload: unknown } } | { type: \"file\"; attachment: { id: string; type: \"file\" | \"source-document\"; filename?: undefined | string; mediaType?: undefined | string; url?: undefined | string; title?: undefined | string }; raw?: undefined | { source: string; payload: unknown } })[]; actions?: undefined | (\"copy\" | \"like\" | \"dislike\" | \"regenerate\" | \"edit\" | { id: string; label: string; icon?: undefined | string; tooltip?: undefined | string })[]; avatar?: undefined | { src?: undefined | string; fallback?: undefined | string; alt?: undefined | string }; feedback?: undefined | \"like\" | \"dislike\" }[]",
         "optional": true,
         "scalar": false,
-        "description": "The full message thread to render, newest last. Each entry carries its role, content, and optional reasoning/tools/attachments/actions/avatar. Set as a JS property (`el.messages = [...]`); a NEW array reference per streaming chunk re-renders (mutating in place does not).",
-        "displayType": "undefined | { id: string; role: \"user\" | \"assistant\"; content: string; reasoning?: undefined | { text: string; label?: undefined | string }; tools?: undefined | { type: string; state: \"input-streaming\" | \"input-available\" | \"output-available\" | \"output-error\"; input?: undefined | Record<string, unknown>; output?: undefined | Record<string, unknown>; toolCallId?: undefined | string; errorText?: undefined | string }[]; attachments?: undefined | { id: string; type: \"file\" | \"source-document\"; filename?: undefined | string; mediaType?: undefined | string; url?: undefined | string; title?: undefined | string }[]; actions?: undefined | (\"copy\" | \"like\" | \"dislike\" | \"regenerate\" | \"edit\" | { id: string; label: string; icon?: undefined | string; tooltip?: undefined | string })[]; avatar?: undefined | { src?: undefined | string; fallback?: undefined | string; alt?: undefined | string }; feedback?: undefined | \"like\" | \"dislike\" }[]"
+        "description": "The full message thread to render, newest last. Each entry carries its role, ordered `parts`, and optional actions/avatar/feedback. Set as a JS property (`el.messages = [...]`); a NEW array reference per streaming chunk re-renders (mutating in place does not).",
+        "typeName": "ChatMessage[]",
+        "typeShape": "{ id: string; role: \"user\" | \"assistant\"; parts: ({ type: \"text\"; text: string; raw?: undefined | { source: string; payload: unknown } } | { type: \"reasoning\"; text: string; label?: undefined | string; index?: undefined | number; streamId?: undefined | string; signature?: undefined | string; raw?: undefined | { source: string; payload: unknown } } | { type: \"tool\"; tool: { type: string; kind?: undefined | \"command\" | \"file-change\" | \"search\" | \"fetch\" | \"mcp\" | \"image\" | \"generic\"; state: \"input-streaming\" | \"input-available\" | \"output-available\" | \"output-error\"; input?: undefined | Record<string, unknown>; rawInput?: undefined | string; output?: undefined | Record<string, unknown>; toolCallId?: undefined | string; errorText?: undefined | string; raw?: undefined | { source: string; payload: unknown } }; raw?: undefined | { source: string; payload: unknown } } | { type: \"card\"; envelope: { type: string; id: string; data: unknown; title?: undefined | string; resolution?: undefined | { kind: \"action\"; action: string; payload?: unknown; at?: undefined | string } | { kind: \"submit\"; data: unknown; at?: undefined | string } | { kind: \"dismissed\"; at?: undefined | string } | { kind: \"expired\"; reason?: undefined | string; at?: undefined | string } }; raw?: undefined | { source: string; payload: unknown } } | { type: \"source\"; source: { id?: undefined | string; url?: undefined | string; title?: undefined | string; snippet?: undefined | string; index?: undefined | number }; raw?: undefined | { source: string; payload: unknown } } | { type: \"file\"; attachment: { id: string; type: \"file\" | \"source-document\"; filename?: undefined | string; mediaType?: undefined | string; url?: undefined | string; title?: undefined | string }; raw?: undefined | { source: string; payload: unknown } })[]; actions?: undefined | (\"copy\" | \"like\" | \"dislike\" | \"regenerate\" | \"edit\" | { id: string; label: string; icon?: undefined | string; tooltip?: undefined | string })[]; avatar?: undefined | { src?: undefined | string; fallback?: undefined | string; alt?: undefined | string }; feedback?: undefined | \"like\" | \"dislike\" }[]",
+        "typeImport": "ChatMessage",
+        "displayType": "undefined | { id: string; role: \"user\" | \"assistant\"; parts: ({ type: \"text\"; text: string; raw?: undefined | { source: string; payload: unknown } } | { type: \"reasoning\"; text: string; label?: undefined | string; index?: undefined | number; streamId?: undefined | string; signature?: undefined | string; raw?: undefined | { source: string; payload: unknown } } | { type: \"tool\"; tool: { type: string; kind?: undefined | \"command\" | \"file-change\" | \"search\" | \"fetch\" | \"mcp\" | \"image\" | \"generic\"; state: \"input-streaming\" | \"input-available\" | \"output-available\" | \"output-error\"; input?: undefined | Record<string, unknown>; rawInput?: undefined | string; output?: undefined | Record<string, unknown>; toolCallId?: undefined | string; errorText?: undefined | string; raw?: undefined | { source: string; payload: unknown } }; raw?: undefined | { source: string; payload: unknown } } | { type: \"card\"; envelope: { type: string; id: string; data: unknown; title?: undefined | string; resolution?: undefined | { kind: \"action\"; action: string; payload?: unknown; at?: undefined | string } | { kind: \"submit\"; data: unknown; at?: undefined | string } | { kind: \"dismissed\"; at?: undefined | string } | { kind: \"expired\"; reason?: undefined | string; at?: undefined | string } }; raw?: undefined | { source: string; payload: unknown } } | { type: \"source\"; source: { id?: undefined | string; url?: undefined | string; title?: undefined | string; snippet?: undefined | string; index?: undefined | number }; raw?: undefined | { source: string; payload: unknown } } | { type: \"file\"; attachment: { id: string; type: \"file\" | \"source-document\"; filename?: undefined | string; mediaType?: undefined | string; url?: undefined | string; title?: undefined | string }; raw?: undefined | { source: string; payload: unknown } })[]; actions?: undefined | (\"copy\" | \"like\" | \"dislike\" | \"regenerate\" | \"edit\" | { id: string; label: string; icon?: undefined | string; tooltip?: undefined | string })[]; avatar?: undefined | { src?: undefined | string; fallback?: undefined | string; alt?: undefined | string }; feedback?: undefined | \"like\" | \"dislike\" }[]"
       },
       {
         "name": "loading",
         "type": "undefined | false | true",
         "optional": true,
         "scalar": true,
-        "description": "Show a typing indicator on the pending assistant turn — set while awaiting the assistant's reply.",
+        "description": "Show a typing indicator on the pending assistant turn. Set it while awaiting the assistant's reply.",
         "default": "false",
         "displayType": "undefined | false | true"
       },
       {
         "name": "proseSize",
-        "type": "undefined | \"sm\" | \"lg\" | \"xs\" | \"base\"",
+        "type": "undefined | \"xs\" | \"sm\" | \"base\" | \"lg\"",
         "optional": true,
         "scalar": true,
         "description": "Body/prose font scale for rendered markdown (`'xs' | 'sm' | 'base' | 'lg'`). Defaults to `'sm'`.",
         "default": "'sm'",
-        "displayType": "undefined | \"sm\" | \"lg\" | \"xs\" | \"base\""
+        "displayType": "undefined | \"xs\" | \"sm\" | \"base\" | \"lg\""
       },
       {
         "name": "codeTheme",
@@ -7021,6 +8228,22 @@
         "scalar": true,
         "description": "Extra classes applied to the thread's inner root.",
         "displayType": "undefined | string"
+      },
+      {
+        "name": "cardTypes",
+        "type": "undefined | Record<string, string>",
+        "optional": true,
+        "scalar": false,
+        "description": "Optional card type -> custom-element tag overrides/additions for `card` parts (merged over the built-ins). Property: `el.cardTypes`. Typed as a plain string map (not the `CardTagMap` alias) so the generated React wrapper inlines it instead of emitting an unresolved named type.",
+        "displayType": "undefined | Record<string, string>"
+      },
+      {
+        "name": "cardSchemas",
+        "type": "undefined | Record<string, object>",
+        "optional": true,
+        "scalar": false,
+        "description": "JSON Schemas for the card types this app renders, keyed by envelope type. The companion of `cardTypes`, which says what DRAWS a card while this says what a VALID one looks like. An OBJECT, so it is a JS property only: `el.cardSchemas = { 'pricing-table': pricingSchema }`, never an attribute. `createCardRegistry(...).validationSchemas` is exactly this shape. Without it the kit validates its own seven built-ins and leaves your own card type, the one your app actually cares about, as the only unchecked thing on screen. A schema here WINS over a built-in of the same name. Typed `Record<string, object>` rather than `Record<string, JsonSchema>` deliberately: an imported `.json` schema widens `\"type\"` to `string`, and an authored one carries `$schema`/`title`/`description`/`additionalProperties`, so the tighter type would reject both of the normal ways to supply one.",
+        "displayType": "undefined | Record<string, object>"
       }
     ],
     "events": [
@@ -7060,17 +8283,27 @@
     "className": "KaiToastRegionElement",
     "displayName": "ToastRegion",
     "props": [
+      {
+        "name": "theme",
+        "type": "\"light\" | \"dark\" | \"auto\"",
+        "optional": true,
+        "scalar": true,
+        "description": "Color mode (`auto` follows prefers-color-scheme).",
+        "default": "'auto'",
+        "universal": true,
+        "displayType": "\"light\" | \"dark\" | \"auto\""
+      },
       {
         "name": "toasts",
-        "type": "{ id: string; message: string; variant?: undefined | \"error\" | \"info\" | \"success\" | \"warning\" | \"neutral\"; appearance?: undefined | \"pill\" | \"card\"; inverse?: undefined | false | true; description?: undefined | string; action?: undefined | { label: string; onAction: () => void | false }; duration?: undefined | number; dismissible?: undefined | false | true; target?: undefined | HTMLElement }[]",
-        "optional": false,
+        "type": "undefined | { id: string; message: string; variant?: undefined | \"neutral\" | \"success\" | \"warning\" | \"error\" | \"info\"; appearance?: undefined | \"pill\" | \"card\"; inverse?: undefined | false | true; description?: undefined | string; action?: undefined | { label: string; onAction: () => void | false }; duration?: undefined | number; dismissible?: undefined | false | true; target?: undefined | HTMLElement }[]",
+        "optional": true,
         "scalar": false,
-        "description": "The toasts to render. Newest is shown on top. Set as a JS property (array); pass a new array reference to update.",
+        "description": "The toasts to render. Newest is shown on top. Set as a JS property (array); pass a new array reference to update. Omit for an empty region, which is the normal resting state and how the imperative `toast()` API starts.",
         "typeName": "ToastItem[]",
-        "typeShape": "{ id: string; message: string; variant?: undefined | \"error\" | \"info\" | \"success\" | \"warning\" | \"neutral\"; appearance?: undefined | \"pill\" | \"card\"; inverse?: undefined | false | true; description?: undefined | string; action?: undefined | { label: string; onAction: () => void | false }; duration?: undefined | number; dismissible?: undefined | false | true; target?: undefined | HTMLElement }[]",
+        "typeShape": "{ id: string; message: string; variant?: undefined | \"neutral\" | \"success\" | \"warning\" | \"error\" | \"info\"; appearance?: undefined | \"pill\" | \"card\"; inverse?: undefined | false | true; description?: undefined | string; action?: undefined | { label: string; onAction: () => void | false }; duration?: undefined | number; dismissible?: undefined | false | true; target?: undefined | HTMLElement }[]",
         "default": "[]",
         "typeImport": "ToastItem",
-        "displayType": "{ id: string; message: string; variant?: undefined | \"error\" | \"info\" | \"success\" | \"warning\" | \"neutral\"; appearance?: undefined | \"pill\" | \"card\"; inverse?: undefined | false | true; description?: undefined | string; action?: undefined | { label: string; onAction: () => void | false }; duration?: undefined | number; dismissible?: undefined | false | true; target?: undefined | HTMLElement }[]"
+        "displayType": "undefined | { id: string; message: string; variant?: undefined | \"neutral\" | \"success\" | \"warning\" | \"error\" | \"info\"; appearance?: undefined | \"pill\" | \"card\"; inverse?: undefined | false | true; description?: undefined | string; action?: undefined | { label: string; onAction: () => void | false }; duration?: undefined | number; dismissible?: undefined | false | true; target?: undefined | HTMLElement }[]"
       },
       {
         "name": "position",
@@ -7135,9 +8368,9 @@
       },
       {
         "name": "kai-dismiss",
-        "detail": "{ id: string; reason: \"action\" | \"timeout\" | \"close\" }",
+        "detail": "{ id: string; reason: \"timeout\" | \"close\" | \"action\" }",
         "description": "A toast left the stack. `reason` is `'timeout' | 'close' | 'action'`.",
-        "displayDetail": "{ id: string; reason: \"action\" | \"timeout\" | \"close\" }"
+        "displayDetail": "{ id: string; reason: \"timeout\" | \"close\" | \"action\" }"
       }
     ],
     "methods": [],
@@ -7155,13 +8388,26 @@
     "className": "KaiToolElement",
     "displayName": "Tool",
     "props": [
+      {
+        "name": "theme",
+        "type": "\"light\" | \"dark\" | \"auto\"",
+        "optional": true,
+        "scalar": true,
+        "description": "Color mode (`auto` follows prefers-color-scheme).",
+        "default": "'auto'",
+        "universal": true,
+        "displayType": "\"light\" | \"dark\" | \"auto\""
+      },
       {
         "name": "tool",
-        "type": "undefined | { type: string; state: \"input-streaming\" | \"input-available\" | \"output-available\" | \"output-error\"; input?: undefined | Record<string, unknown>; output?: undefined | Record<string, unknown>; toolCallId?: undefined | string; errorText?: undefined | string }",
+        "type": "undefined | { type: string; kind?: undefined | \"command\" | \"file-change\" | \"search\" | \"fetch\" | \"mcp\" | \"image\" | \"generic\"; state: \"input-streaming\" | \"input-available\" | \"output-available\" | \"output-error\"; input?: undefined | Record<string, unknown>; rawInput?: undefined | string; output?: undefined | Record<string, unknown>; toolCallId?: undefined | string; errorText?: undefined | string; raw?: undefined | { source: string; payload: unknown } }",
         "optional": true,
         "scalar": false,
         "description": "The tool-call to display. Set as a JS property.",
-        "displayType": "ToolPart | undefined"
+        "typeName": "ToolPart",
+        "typeShape": "{ type: string; kind?: undefined | \"command\" | \"file-change\" | \"search\" | \"fetch\" | \"mcp\" | \"image\" | \"generic\"; state: \"input-streaming\" | \"input-available\" | \"output-available\" | \"output-error\"; input?: undefined | Record<string, unknown>; rawInput?: undefined | string; output?: undefined | Record<string, unknown>; toolCallId?: undefined | string; errorText?: undefined | string; raw?: undefined | { source: string; payload: unknown } }",
+        "typeImport": "ToolPart",
+        "displayType": "undefined | { type: string; kind?: undefined | \"command\" | \"file-change\" | \"search\" | \"fetch\" | \"mcp\" | \"image\" | \"generic\"; state: \"input-streaming\" | \"input-available\" | \"output-available\" | \"output-error\"; input?: undefined | Record<string, unknown>; rawInput?: undefined | string; output?: undefined | Record<string, unknown>; toolCallId?: undefined | string; errorText?: undefined | string; raw?: undefined | { source: string; payload: unknown } }"
       },
       {
         "name": "open",
@@ -7184,7 +8430,7 @@
         "type": "undefined | false | true",
         "optional": true,
         "scalar": true,
-        "description": "Gate the disclosure trigger — programmatic `show()/hide()/toggle()` still work, but the trigger click no longer toggles.",
+        "description": "Gate the disclosure trigger: programmatic `show()/hide()/toggle()` still work, but the trigger click no longer toggles.",
         "displayType": "undefined | false | true"
       }
     ],
@@ -7235,6 +8481,16 @@
     "className": "KaiTooltipElement",
     "displayName": "Tooltip",
     "props": [
+      {
+        "name": "theme",
+        "type": "\"light\" | \"dark\" | \"auto\"",
+        "optional": true,
+        "scalar": true,
+        "description": "Color mode (`auto` follows prefers-color-scheme).",
+        "default": "'auto'",
+        "universal": true,
+        "displayType": "\"light\" | \"dark\" | \"auto\""
+      },
       {
         "name": "content",
         "type": "undefined | string",
@@ -7328,19 +8584,36 @@
         "storyId": "solid-advanced-primitives-tooltip--docs"
       }
     ],
-    "tokens": []
+    "tokens": [],
+    "slots": [
+      {
+        "name": "",
+        "mode": "inject",
+        "doc": "The TRIGGER the tooltip describes. The tip text is the `text` prop."
+      }
+    ]
   },
   {
     "tag": "kai-voice-input",
     "className": "KaiVoiceInputElement",
     "displayName": "VoiceInput",
     "props": [
+      {
+        "name": "theme",
+        "type": "\"light\" | \"dark\" | \"auto\"",
+        "optional": true,
+        "scalar": true,
+        "description": "Color mode (`auto` follows prefers-color-scheme).",
+        "default": "'auto'",
+        "universal": true,
+        "displayType": "\"light\" | \"dark\" | \"auto\""
+      },
       {
         "name": "transcribe",
         "type": "undefined | (audio: Blob) => Promise<string>",
         "optional": true,
         "scalar": false,
-        "description": "Transcriber the host supplies — records audio, returns the text. This is a **function-valued property** (`el.transcribe = async blob => '...'`) because a value-returning callback can't be modelled as a fire-and-forget event.",
+        "description": "Transcriber the host supplies: records audio, returns the text. This is a **function-valued property** (`el.transcribe = async blob => '...'`) because a value-returning callback can't be modelled as a fire-and-forget event.",
         "displayType": "undefined | (audio: Blob) => Promise<string>"
       },
       {
@@ -7374,13 +8647,13 @@
       {
         "name": "kai-audio-captured",
         "detail": "{ blob: Blob }",
-        "description": "Raw audio captured (before transcription) — for hosts that prefer to handle transcription themselves instead of via the `transcribe` property. Also the unsupported-fallback signal: no `transcribe`, no SpeechRecognition, so only the blob is produced (no text).",
+        "description": "Raw audio captured (before transcription), for hosts that prefer to handle transcription themselves instead of via the `transcribe` property. Also the unsupported-fallback signal: no `transcribe`, no SpeechRecognition, so only the blob is produced (no text).",
         "displayDetail": "{ blob: Blob }"
       },
       {
         "name": "kai-recording-change",
         "detail": "{ recording: false | true }",
-        "description": "Recording started or stopped — lets the host drive its own UI (waveform, push-to-talk indicator) in sync with the mic. Fires on real transitions only (manual click and programmatic start()/stop()), never on mount.",
+        "description": "Recording started or stopped. Lets the host drive its own UI (waveform, push-to-talk indicator) in sync with the mic. Fires on real transitions only (manual click and programmatic start()/stop()), never on mount.",
         "displayDetail": "{ recording: false | true }"
       },
       {
@@ -7392,7 +8665,7 @@
       {
         "name": "kai-transcription",
         "detail": "{ text: string }",
-        "description": "Final transcript — the `transcribe` property resolved, OR native `SpeechRecognition` produced final text (no `transcribe` set).",
+        "description": "Final transcript: the `transcribe` property resolved, OR native `SpeechRecognition` produced final text (no `transcribe` set).",
         "displayDetail": "{ text: string }"
       }
     ],
@@ -7424,6 +8697,16 @@
     "className": "KaiVoiceOutputElement",
     "displayName": "VoiceOutput",
     "props": [
+      {
+        "name": "theme",
+        "type": "\"light\" | \"dark\" | \"auto\"",
+        "optional": true,
+        "scalar": true,
+        "description": "Color mode (`auto` follows prefers-color-scheme).",
+        "default": "'auto'",
+        "universal": true,
+        "displayType": "\"light\" | \"dark\" | \"auto\""
+      },
       {
         "name": "text",
         "type": "undefined | string",
@@ -7447,7 +8730,7 @@
         "type": "undefined | (text: string) => Promise<Blob>",
         "optional": true,
         "scalar": false,
-        "description": "TTS model seam the host supplies — given text, returns an audio `Blob` to play. This is a **function-valued property** (`el.synthesize = async text => blob`); when set, the native `speechSynthesis` path is bypassed. Mirrors `<kai-voice-input>`'s `transcribe`. A value-returning callback can't be modelled as a fire-and-forget event, hence a property.",
+        "description": "TTS model seam the host supplies: given text, returns an audio `Blob` to play. This is a **function-valued property** (`el.synthesize = async text => blob`); when set, the native `speechSynthesis` path is bypassed. Mirrors `<kai-voice-input>`'s `transcribe`. A value-returning callback can't be modelled as a fire-and-forget event, hence a property.",
         "displayType": "undefined | (text: string) => Promise<Blob>"
       },
       {
@@ -7464,13 +8747,13 @@
       {
         "name": "kai-speaking-change",
         "detail": "{ speaking: false | true }",
-        "description": "Playback started or stopped — drive your own UI in sync. Fires on real transitions only (manual click and programmatic speak()/stop()), never on mount.",
+        "description": "Playback started or stopped. Drive your own UI in sync. Fires on real transitions only (manual click and programmatic speak()/stop()), never on mount.",
         "displayDetail": "{ speaking: false | true }"
       },
       {
         "name": "kai-synthesized",
         "detail": "{ blob: Blob }",
-        "description": "The model path (`synthesize`) resolved audio — the raw `Blob` before playback.",
+        "description": "The model path (`synthesize`) resolved audio: the raw `Blob` before playback.",
         "displayDetail": "{ blob: Blob }"
       }
     ],
@@ -7521,29 +8804,39 @@
     "className": "KaiWorkspaceElement",
     "displayName": "Workspace",
     "props": [
+      {
+        "name": "theme",
+        "type": "\"light\" | \"dark\" | \"auto\"",
+        "optional": true,
+        "scalar": true,
+        "description": "Color mode (`auto` follows prefers-color-scheme).",
+        "default": "'auto'",
+        "universal": true,
+        "displayType": "\"light\" | \"dark\" | \"auto\""
+      },
       {
         "name": "groups",
-        "type": "{ id: string; userId?: undefined | string; teamId?: undefined | string; name: string; sortOrder: number; createdAt: string }[]",
-        "optional": false,
+        "type": "undefined | { id: string; userId?: undefined | string; teamId?: undefined | string; name: string; sortOrder: number; createdAt: string }[]",
+        "optional": true,
         "scalar": false,
-        "description": "Pre-bucketed conversation groups for the sidebar. Set as a JS property.",
+        "description": "The sidebar's section headers, rendered in array order. A group carries no conversations of its own; it is matched against `conversations` by id, so the two props are complementary rather than alternatives. Omit for an ungrouped sidebar. Set as a JS property.",
         "typeName": "ConversationGroup[]",
         "typeShape": "{ id: string; userId?: undefined | string; teamId?: undefined | string; name: string; sortOrder: number; createdAt: string }[]",
         "default": "[]",
         "typeImport": "ConversationGroup",
-        "displayType": "ConversationGroup[]"
+        "displayType": "undefined | { id: string; userId?: undefined | string; teamId?: undefined | string; name: string; sortOrder: number; createdAt: string }[]"
       },
       {
         "name": "conversations",
-        "type": "{ id: string; title: string; groupId?: undefined | string; scope: { type: \"document\" | \"collection\"; documentId?: undefined | string; filters?: undefined | { tags?: undefined | string[]; authors?: undefined | string[]; contentType?: undefined | \"transcript\" | \"markdown\"; dateRange?: undefined | { from: string; to: string } } }; messageCount: number; lastMessageAt: string; updatedAt: string; trailing?: undefined | string }[]",
-        "optional": false,
+        "type": "undefined | { id: string; title: string; groupId?: undefined | string; scope: { type: \"document\" | \"collection\"; documentId?: undefined | string; filters?: undefined | { tags?: undefined | string[]; authors?: undefined | string[]; contentType?: undefined | \"transcript\" | \"markdown\"; dateRange?: undefined | { from: string; to: string } } }; messageCount: number; lastMessageAt: string; updatedAt: string; trailing?: undefined | string }[]",
+        "optional": true,
         "scalar": false,
-        "description": "Flat conversation list (auto-bucketed if `groups` is empty). Set as a JS property.",
+        "description": "Every conversation in the sidebar, flat. Each one is filed under the group whose `id` equals its `groupId`; one with no `groupId`, or with a `groupId` matching no entry in `groups`, falls into a trailing ungrouped section (headerless when `compact`), so nothing you pass in is ever dropped. There is no recency bucketing. Set as a JS property. Omit for an empty sidebar, or when `no-conversations` replaces the built-in list with your own `sidebar-header` content.",
         "typeName": "ConversationSummary[]",
         "typeShape": "{ id: string; title: string; groupId?: undefined | string; scope: { type: \"document\" | \"collection\"; documentId?: undefined | string; filters?: undefined | { tags?: undefined | string[]; authors?: undefined | string[]; contentType?: undefined | \"transcript\" | \"markdown\"; dateRange?: undefined | { from: string; to: string } } }; messageCount: number; lastMessageAt: string; updatedAt: string; trailing?: undefined | string }[]",
         "default": "[]",
         "typeImport": "ConversationSummary",
-        "displayType": "{ id: string; title: string; groupId?: undefined | string; scope: { type: \"document\" | \"collection\"; documentId?: undefined | string; filters?: undefined | { tags?: undefined | string[]; authors?: undefined | string[]; contentType?: undefined | \"transcript\" | \"markdown\"; dateRange?: undefined | { from: string; to: string } } }; messageCount: number; lastMessageAt: string; updatedAt: string; trailing?: undefined | string }[]"
+        "displayType": "undefined | { id: string; title: string; groupId?: undefined | string; scope: { type: \"document\" | \"collection\"; documentId?: undefined | string; filters?: undefined | { tags?: undefined | string[]; authors?: undefined | string[]; contentType?: undefined | \"transcript\" | \"markdown\"; dateRange?: undefined | { from: string; to: string } } }; messageCount: number; lastMessageAt: string; updatedAt: string; trailing?: undefined | string }[]"
       },
       {
         "name": "activeId",
@@ -7555,15 +8848,15 @@
       },
       {
         "name": "messages",
-        "type": "{ id: string; role: \"user\" | \"assistant\"; content: string; reasoning?: undefined | { text: string; label?: undefined | string }; tools?: undefined | { type: string; state: \"input-streaming\" | \"input-available\" | \"output-available\" | \"output-error\"; input?: undefined | Record<string, unknown>; output?: undefined | Record<string, unknown>; toolCallId?: undefined | string; errorText?: undefined | string }[]; attachments?: undefined | { id: string; type: \"file\" | \"source-document\"; filename?: undefined | string; mediaType?: undefined | string; url?: undefined | string; title?: undefined | string }[]; actions?: undefined | (\"copy\" | \"like\" | \"dislike\" | \"regenerate\" | \"edit\" | { id: string; label: string; icon?: undefined | string; tooltip?: undefined | string })[]; avatar?: undefined | { src?: undefined | string; fallback?: undefined | string; alt?: undefined | string }; feedback?: undefined | \"like\" | \"dislike\" }[]",
-        "optional": false,
+        "type": "undefined | { id: string; role: \"user\" | \"assistant\"; parts: ({ type: \"text\"; text: string; raw?: undefined | { source: string; payload: unknown } } | { type: \"reasoning\"; text: string; label?: undefined | string; index?: undefined | number; streamId?: undefined | string; signature?: undefined | string; raw?: undefined | { source: string; payload: unknown } } | { type: \"tool\"; tool: { type: string; kind?: undefined | \"command\" | \"file-change\" | \"search\" | \"fetch\" | \"mcp\" | \"image\" | \"generic\"; state: \"input-streaming\" | \"input-available\" | \"output-available\" | \"output-error\"; input?: undefined | Record<string, unknown>; rawInput?: undefined | string; output?: undefined | Record<string, unknown>; toolCallId?: undefined | string; errorText?: undefined | string; raw?: undefined | { source: string; payload: unknown } }; raw?: undefined | { source: string; payload: unknown } } | { type: \"card\"; envelope: { type: string; id: string; data: unknown; title?: undefined | string; resolution?: undefined | { kind: \"action\"; action: string; payload?: unknown; at?: undefined | string } | { kind: \"submit\"; data: unknown; at?: undefined | string } | { kind: \"dismissed\"; at?: undefined | string } | { kind: \"expired\"; reason?: undefined | string; at?: undefined | string } }; raw?: undefined | { source: string; payload: unknown } } | { type: \"source\"; source: { id?: undefined | string; url?: undefined | string; title?: undefined | string; snippet?: undefined | string; index?: undefined | number }; raw?: undefined | { source: string; payload: unknown } } | { type: \"file\"; attachment: { id: string; type: \"file\" | \"source-document\"; filename?: undefined | string; mediaType?: undefined | string; url?: undefined | string; title?: undefined | string }; raw?: undefined | { source: string; payload: unknown } })[]; actions?: undefined | (\"copy\" | \"like\" | \"dislike\" | \"regenerate\" | \"edit\" | { id: string; label: string; icon?: undefined | string; tooltip?: undefined | string })[]; avatar?: undefined | { src?: undefined | string; fallback?: undefined | string; alt?: undefined | string }; feedback?: undefined | \"like\" | \"dislike\" }[]",
+        "optional": true,
         "scalar": false,
-        "description": "The active conversation's message thread, newest last. Set as a JS property.",
+        "description": "The active conversation's message thread, newest last. Set as a JS property (`el.messages = [...]`); a NEW array reference per streaming chunk re-renders (mutating in place does not). Omit for an empty thread.",
         "typeName": "ChatMessage[]",
-        "typeShape": "{ id: string; role: \"user\" | \"assistant\"; content: string; reasoning?: undefined | { text: string; label?: undefined | string }; tools?: undefined | { type: string; state: \"input-streaming\" | \"input-available\" | \"output-available\" | \"output-error\"; input?: undefined | Record<string, unknown>; output?: undefined | Record<string, unknown>; toolCallId?: undefined | string; errorText?: undefined | string }[]; attachments?: undefined | { id: string; type: \"file\" | \"source-document\"; filename?: undefined | string; mediaType?: undefined | string; url?: undefined | string; title?: undefined | string }[]; actions?: undefined | (\"copy\" | \"like\" | \"dislike\" | \"regenerate\" | \"edit\" | { id: string; label: string; icon?: undefined | string; tooltip?: undefined | string })[]; avatar?: undefined | { src?: undefined | string; fallback?: undefined | string; alt?: undefined | string }; feedback?: undefined | \"like\" | \"dislike\" }[]",
+        "typeShape": "{ id: string; role: \"user\" | \"assistant\"; parts: ({ type: \"text\"; text: string; raw?: undefined | { source: string; payload: unknown } } | { type: \"reasoning\"; text: string; label?: undefined | string; index?: undefined | number; streamId?: undefined | string; signature?: undefined | string; raw?: undefined | { source: string; payload: unknown } } | { type: \"tool\"; tool: { type: string; kind?: undefined | \"command\" | \"file-change\" | \"search\" | \"fetch\" | \"mcp\" | \"image\" | \"generic\"; state: \"input-streaming\" | \"input-available\" | \"output-available\" | \"output-error\"; input?: undefined | Record<string, unknown>; rawInput?: undefined | string; output?: undefined | Record<string, unknown>; toolCallId?: undefined | string; errorText?: undefined | string; raw?: undefined | { source: string; payload: unknown } }; raw?: undefined | { source: string; payload: unknown } } | { type: \"card\"; envelope: { type: string; id: string; data: unknown; title?: undefined | string; resolution?: undefined | { kind: \"action\"; action: string; payload?: unknown; at?: undefined | string } | { kind: \"submit\"; data: unknown; at?: undefined | string } | { kind: \"dismissed\"; at?: undefined | string } | { kind: \"expired\"; reason?: undefined | string; at?: undefined | string } }; raw?: undefined | { source: string; payload: unknown } } | { type: \"source\"; source: { id?: undefined | string; url?: undefined | string; title?: undefined | string; snippet?: undefined | string; index?: undefined | number }; raw?: undefined | { source: string; payload: unknown } } | { type: \"file\"; attachment: { id: string; type: \"file\" | \"source-document\"; filename?: undefined | string; mediaType?: undefined | string; url?: undefined | string; title?: undefined | string }; raw?: undefined | { source: string; payload: unknown } })[]; actions?: undefined | (\"copy\" | \"like\" | \"dislike\" | \"regenerate\" | \"edit\" | { id: string; label: string; icon?: undefined | string; tooltip?: undefined | string })[]; avatar?: undefined | { src?: undefined | string; fallback?: undefined | string; alt?: undefined | string }; feedback?: undefined | \"like\" | \"dislike\" }[]",
         "default": "[]",
         "typeImport": "ChatMessage",
-        "displayType": "{ id: string; role: \"user\" | \"assistant\"; content: string; reasoning?: undefined | { text: string; label?: undefined | string }; tools?: undefined | { type: string; state: \"input-streaming\" | \"input-available\" | \"output-available\" | \"output-error\"; input?: undefined | Record<string, unknown>; output?: undefined | Record<string, unknown>; toolCallId?: undefined | string; errorText?: undefined | string }[]; attachments?: undefined | { id: string; type: \"file\" | \"source-document\"; filename?: undefined | string; mediaType?: undefined | string; url?: undefined | string; title?: undefined | string }[]; actions?: undefined | (\"copy\" | \"like\" | \"dislike\" | \"regenerate\" | \"edit\" | { id: string; label: string; icon?: undefined | string; tooltip?: undefined | string })[]; avatar?: undefined | { src?: undefined | string; fallback?: undefined | string; alt?: undefined | string }; feedback?: undefined | \"like\" | \"dislike\" }[]"
+        "displayType": "undefined | { id: string; role: \"user\" | \"assistant\"; parts: ({ type: \"text\"; text: string; raw?: undefined | { source: string; payload: unknown } } | { type: \"reasoning\"; text: string; label?: undefined | string; index?: undefined | number; streamId?: undefined | string; signature?: undefined | string; raw?: undefined | { source: string; payload: unknown } } | { type: \"tool\"; tool: { type: string; kind?: undefined | \"command\" | \"file-change\" | \"search\" | \"fetch\" | \"mcp\" | \"image\" | \"generic\"; state: \"input-streaming\" | \"input-available\" | \"output-available\" | \"output-error\"; input?: undefined | Record<string, unknown>; rawInput?: undefined | string; output?: undefined | Record<string, unknown>; toolCallId?: undefined | string; errorText?: undefined | string; raw?: undefined | { source: string; payload: unknown } }; raw?: undefined | { source: string; payload: unknown } } | { type: \"card\"; envelope: { type: string; id: string; data: unknown; title?: undefined | string; resolution?: undefined | { kind: \"action\"; action: string; payload?: unknown; at?: undefined | string } | { kind: \"submit\"; data: unknown; at?: undefined | string } | { kind: \"dismissed\"; at?: undefined | string } | { kind: \"expired\"; reason?: undefined | string; at?: undefined | string } }; raw?: undefined | { source: string; payload: unknown } } | { type: \"source\"; source: { id?: undefined | string; url?: undefined | string; title?: undefined | string; snippet?: undefined | string; index?: undefined | number }; raw?: undefined | { source: string; payload: unknown } } | { type: \"file\"; attachment: { id: string; type: \"file\" | \"source-document\"; filename?: undefined | string; mediaType?: undefined | string; url?: undefined | string; title?: undefined | string }; raw?: undefined | { source: string; payload: unknown } })[]; actions?: undefined | (\"copy\" | \"like\" | \"dislike\" | \"regenerate\" | \"edit\" | { id: string; label: string; icon?: undefined | string; tooltip?: undefined | string })[]; avatar?: undefined | { src?: undefined | string; fallback?: undefined | string; alt?: undefined | string }; feedback?: undefined | \"like\" | \"dislike\" }[]"
       },
       {
         "name": "value",
@@ -7610,12 +8903,12 @@
       },
       {
         "name": "proseSize",
-        "type": "undefined | \"sm\" | \"lg\" | \"xs\" | \"base\"",
+        "type": "undefined | \"xs\" | \"sm\" | \"base\" | \"lg\"",
         "optional": true,
         "scalar": true,
         "description": "",
         "default": "'sm'",
-        "displayType": "undefined | \"sm\" | \"lg\" | \"xs\" | \"base\""
+        "displayType": "undefined | \"xs\" | \"sm\" | \"base\" | \"lg\""
       },
       {
         "name": "codeTheme",
@@ -7649,6 +8942,9 @@
         "optional": true,
         "scalar": false,
         "description": "",
+        "typeName": "ModelOption[]",
+        "typeShape": "{ id: string; name: string; provider?: undefined | string; description?: undefined | string; group?: undefined | string }[]",
+        "typeImport": "ModelOption",
         "displayType": "undefined | { id: string; name: string; provider?: undefined | string; description?: undefined | string; group?: undefined | string }[]"
       },
       {
@@ -7665,6 +8961,9 @@
         "optional": true,
         "scalar": false,
         "description": "",
+        "typeName": "ChatThreadContextUsage",
+        "typeShape": "{ usedTokens: number; maxTokens: number; inputTokens?: undefined | number; outputTokens?: undefined | number; estimatedCost?: undefined | number }",
+        "typeImport": "ChatThreadContextUsage",
         "displayType": "ContextData | undefined"
       },
       {
@@ -7700,6 +8999,9 @@
         "optional": true,
         "scalar": false,
         "description": "Rich entity triggers (`/` skills, `@` agents/plugins) forwarded to the input.",
+        "typeName": "TriggerDef[]",
+        "typeShape": "{ char: string; kind: string; items?: undefined | { id: string; label: string; icon?: undefined | string; description?: undefined | string; group?: undefined | string; kind?: undefined | string; promptText?: undefined | string; data?: undefined | Record<string, unknown> }[] }[]",
+        "typeImport": "TriggerDef",
         "displayType": "undefined | { char: string; kind: string; items?: undefined | { id: string; label: string; icon?: undefined | string; description?: undefined | string; group?: undefined | string; kind?: undefined | string; promptText?: undefined | string; data?: undefined | Record<string, unknown> }[] }[]"
       },
       {
@@ -7776,6 +9078,22 @@
         "scalar": true,
         "description": "Suppress the built-in ConversationList so the `sidebar-header` slot owns the whole rail flex region (for apps that supply their own rail nav). Default false. Attribute: `no-conversations`.",
         "displayType": "undefined | false | true"
+      },
+      {
+        "name": "cardTypes",
+        "type": "undefined | Record<string, string>",
+        "optional": true,
+        "scalar": false,
+        "description": "Optional card type -> custom-element tag overrides/additions for `card` parts (merged over the built-ins). Property: `el.cardTypes`. Typed as a plain string map (not the `CardTagMap` alias) so the generated React wrapper inlines it instead of emitting an unresolved named type.",
+        "displayType": "undefined | Record<string, string>"
+      },
+      {
+        "name": "cardSchemas",
+        "type": "undefined | Record<string, object>",
+        "optional": true,
+        "scalar": false,
+        "description": "JSON Schemas for the card types this app renders, keyed by envelope type. The companion of `cardTypes`, which says what DRAWS a card while this says what a VALID one looks like. An OBJECT, so it is a JS property only: `el.cardSchemas = { 'pricing-table': pricingSchema }`, never an attribute. `createCardRegistry(...).validationSchemas` is exactly this shape. Without it the kit validates its own seven built-ins and leaves your own card type, the one your app actually cares about, as the only unchecked thing on screen. A schema here WINS over a built-in of the same name. Typed `Record<string, object>` rather than `Record<string, JsonSchema>` deliberately: an imported `.json` schema widens `\"type\"` to `string`, and an authored one carries `$schema`/`title`/`description`/`additionalProperties`, so the tighter type would reject both of the normal ways to supply one.",
+        "displayType": "undefined | Record<string, object>"
       }
     ],
     "events": [