@kitn.ai/ui 0.26.0 → 0.28.0

package/dist/custom-elements.json

@@ -618,7 +618,7 @@
               "type": {
                 "text": "undefined | { id: string; type: \"file\" | \"source-document\"; filename?: undefined | string; mediaType?: undefined | string; url?: undefined | string; title?: undefined | string }[]"
               },
-              "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).",
+              "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). Each item's `url` must be a `data:` URI or an https URL, never `URL.createObjectURL`: a `blob:` URL previews here but the wire encoders (`toOpenAIMessages`/`toAnthropicMessages`) refuse it.",
               "privacy": "public"
             },
             {
@@ -1761,7 +1761,7 @@
               "kind": "field",
               "name": "policy",
               "type": {
-                "text": "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\" }"
+                "text": "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\" }"
               },
               "description": "Optional CardPolicy handling child events. Property: `el.policy`.",
               "privacy": "public"
@@ -2095,6 +2095,24 @@
               "description": "Enable Shiki syntax highlighting in code blocks. Turn off to render plain `<pre>` blocks (lighter, no highlighter load). Default true.",
               "privacy": "public"
             },
+            {
+              "kind": "field",
+              "name": "reasoning",
+              "type": {
+                "text": "undefined | \"full\" | \"compact\" | \"off\""
+              },
+              "description": "How `reasoning` parts render across the thread. `'full'` (default) is the current collapsible-disclosure behavior; `'compact'` shows only a shimmer loader while a reasoning part streams and nothing once it settles (no expandable detail); `'off'` renders reasoning parts not at all. Forwarded to every `MessageBody` as `reasoningMode`.",
+              "privacy": "public"
+            },
+            {
+              "kind": "field",
+              "name": "reasoningOpen",
+              "type": {
+                "text": "undefined | false | true"
+              },
+              "description": "Seeds the reasoning disclosure open AND keeps it tracking the stream (open while streaming, closes when it settles): the pre-Task-19f `full` behavior. Default false/absent: the panel starts closed (just the \"Thinking\" shimmer chip) and only opens on click, the current default (owner ruling, 2026-08-26). Meaningless when `reasoning` is `'compact'` or `'off'`. Forwarded to every `MessageBody` as `reasoningDefaultOpen`.",
+              "privacy": "public"
+            },
             {
               "kind": "field",
               "name": "chatTitle",
@@ -2212,6 +2230,15 @@
               "description": "INJECT: footer row below the composer (disclaimers, token meter, …).",
               "privacy": "public"
             },
+            {
+              "kind": "field",
+              "name": "attach",
+              "type": {
+                "text": "undefined | false | true"
+              },
+              "description": "When `false`, hides the built-in paperclip attach button. Defaults to `true` (undeclared keeps today's behavior: attach visible), matching `DefaultPromptInput`'s own default: only an explicit `false` hides it.",
+              "privacy": "public"
+            },
             {
               "kind": "field",
               "name": "webSearch",
@@ -2293,6 +2320,33 @@
               "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.",
               "privacy": "public"
             },
+            {
+              "kind": "field",
+              "name": "conversations",
+              "type": {
+                "text": "undefined | false | true"
+              },
+              "description": "Turns on the prior-conversations list (a list-toggle button in the header, plus a second list view sharing the panel, C-1). Attribute- settable like every other boolean flag on this element: `<kai-chat conversations>`. Requires `store`. A row select, \"new conversation,\" or the visitor's mount-time auto-restore all deliver their messages the same way: listen for `kai-conversation-load` and set `el.messages` from `event.detail.messages` (a fresh array): this element does not update `messages` for you. Set with no `store`, the underlying `ChatThread` decides loudly (one console.error) and stays visually off; this facade always supplies its own internal load handler (the `kai-conversation-load` dispatch below), so the second ChatThread guard, missing `onConversationLoad`, never trips here, even for a consumer who never listens for the event. Default false.",
+              "privacy": "public"
+            },
+            {
+              "kind": "field",
+              "name": "store",
+              "type": {
+                "text": "undefined | { list: () => Promise<{ id: string; title: string; groupId?: undefined | string; scope?: undefined | { 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?: undefined | string; updatedAt: string; trailing?: undefined | string; lastReadAt?: undefined | string }[]>; load: (id: string) => Promise<{ 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\" }[]>; save: (id: string, messages: { 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\" }[]) => Promise<void>; markRead?: undefined | ((id: string) => Promise<void>) }"
+              },
+              "description": "The adapter this thread persists conversations through: an object of three functions (`list`/`load`/`save`; `ConversationStore`, exported from `@kitn.ai/ui`'s `primitives/conversation-store`). A JS PROPERTY ONLY: `el.store = myAdapter`. It can never be an attribute, since a function-bearing object has no HTML string form, the same reasoning that keeps `messages`/`cardSchemas` property-only (the kai- contract: array/object props are JS properties, never attributes). Two built-ins ship: `localStorageStore(name, userId?)` and `fetchStore(url, userId?)`.",
+              "privacy": "public"
+            },
+            {
+              "kind": "field",
+              "name": "home",
+              "type": {
+                "text": "undefined | { greeting?: undefined | { title?: undefined | string; subtitle?: undefined | string }; recentConversation?: undefined | false | true; newConversation?: undefined | { label?: undefined | string }; links?: undefined | { label: string; href?: undefined | string; description?: undefined | string; icon?: undefined | string }[] }"
+              },
+              "description": "Turns on the widget home screen (Intercom-pattern): the panel boots into a `home` view, with a greeting, most-recent-conversation card, a \"new conversation\" CTA, and host-defined links, plus a Home/Messages tab bar for switching back to the thread. An OBJECT, so it is a JS property only: `el.home = { greeting: { title: 'Hey' }, links: [...] }`, never an attribute (the kai- contract: array/object props are JS properties). A `links` entry with no `href` fires `kai-home-link` with that entry when tapped, rather than navigating; one WITH `href` opens it directly (only when the URL passes the kit's own scheme allowlist). Omit for the no-home widget (chat view only, unchanged).",
+              "privacy": "public"
+            },
             {
               "kind": "method",
               "name": "focus",
@@ -2424,6 +2478,22 @@
               },
               "description": "Enable Shiki syntax highlighting in code blocks. Turn off to render plain `<pre>` blocks (lighter, no highlighter load). Default true."
             },
+            {
+              "name": "reasoning",
+              "fieldName": "reasoning",
+              "type": {
+                "text": "undefined | \"full\" | \"compact\" | \"off\""
+              },
+              "description": "How `reasoning` parts render across the thread. `'full'` (default) is the current collapsible-disclosure behavior; `'compact'` shows only a shimmer loader while a reasoning part streams and nothing once it settles (no expandable detail); `'off'` renders reasoning parts not at all. Forwarded to every `MessageBody` as `reasoningMode`."
+            },
+            {
+              "name": "reasoning-open",
+              "fieldName": "reasoningOpen",
+              "type": {
+                "text": "undefined | false | true"
+              },
+              "description": "Seeds the reasoning disclosure open AND keeps it tracking the stream (open while streaming, closes when it settles): the pre-Task-19f `full` behavior. Default false/absent: the panel starts closed (just the \"Thinking\" shimmer chip) and only opens on click, the current default (owner ruling, 2026-08-26). Meaningless when `reasoning` is `'compact'` or `'off'`. Forwarded to every `MessageBody` as `reasoningDefaultOpen`."
+            },
             {
               "name": "chat-title",
               "fieldName": "chatTitle",
@@ -2512,6 +2582,14 @@
               },
               "description": "INJECT: footer row below the composer (disclaimers, token meter, …)."
             },
+            {
+              "name": "attach",
+              "fieldName": "attach",
+              "type": {
+                "text": "undefined | false | true"
+              },
+              "description": "When `false`, hides the built-in paperclip attach button. Defaults to `true` (undeclared keeps today's behavior: attach visible), matching `DefaultPromptInput`'s own default: only an explicit `false` hides it."
+            },
             {
               "name": "web-search",
               "fieldName": "webSearch",
@@ -2543,6 +2621,14 @@
                 "text": "undefined | string"
               },
               "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."
+            },
+            {
+              "name": "conversations",
+              "fieldName": "conversations",
+              "type": {
+                "text": "undefined | false | true"
+              },
+              "description": "Turns on the prior-conversations list (a list-toggle button in the header, plus a second list view sharing the panel, C-1). Attribute- settable like every other boolean flag on this element: `<kai-chat conversations>`. Requires `store`. A row select, \"new conversation,\" or the visitor's mount-time auto-restore all deliver their messages the same way: listen for `kai-conversation-load` and set `el.messages` from `event.detail.messages` (a fresh array): this element does not update `messages` for you. Set with no `store`, the underlying `ChatThread` decides loudly (one console.error) and stays visually off; this facade always supplies its own internal load handler (the `kai-conversation-load` dispatch below), so the second ChatThread guard, missing `onConversationLoad`, never trips here, even for a consumer who never listens for the event. Default false."
             }
           ],
           "events": [
@@ -2560,6 +2646,20 @@
               },
               "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."
             },
+            {
+              "name": "kai-conversation-load",
+              "type": {
+                "text": "CustomEvent<{ id: string | undefined; messages: { 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\" }[] }>"
+              },
+              "description": "A conversation's history loaded: a row tap in the list, \"new conversation,\" or the visitor's own mount-time auto-restore of their most recent thread (only fires when `conversations` is on and a `store` is set). `detail.id` is that conversation's id, `undefined` for the \"new conversation\" case (no id exists until the first message mints one, C-6). Set `el.messages = event.detail.messages` (already a fresh array) to actually render it, since this element does not do that for you; `messages` stays your own state like everywhere else on this element."
+            },
+            {
+              "name": "kai-home-link",
+              "type": {
+                "text": "CustomEvent<{ entry: { label: string; href?: undefined | string; description?: undefined | string; icon?: undefined | string } }>"
+              },
+              "description": "A `home.links` entry with no `href` was activated (tapped/clicked/Enter). Meaningful only when `home` is set."
+            },
             {
               "name": "kai-message-action",
               "type": {
@@ -2668,8 +2768,8 @@
         {
           "kind": "class",
           "customElement": true,
-          "tagName": "kai-checkpoint",
-          "name": "KaiCheckpointElement",
+          "tagName": "kai-checkbox",
+          "name": "KaiCheckboxElement",
           "description": "",
           "members": [
             {
@@ -2683,38 +2783,101 @@
             },
             {
               "kind": "field",
-              "name": "label",
+              "name": "checked",
               "type": {
-                "text": "undefined | string"
+                "text": "undefined | false | true"
               },
-              "description": "Optional text beside the icon.",
+              "description": "Controlled checked state. Settable and reflected to the `checked` attribute. `el.checked = true` (or `<kai-checkbox checked>`) drives it; ticking the box updates it and fires `kai-change`. Read `el.checked` for live state.",
               "privacy": "public"
             },
             {
               "kind": "field",
-              "name": "tooltip",
+              "name": "defaultChecked",
+              "type": {
+                "text": "undefined | false | true"
+              },
+              "description": "Initial checked state on mount (uncontrolled seed). Bare attribute (`<kai-checkbox default-checked>`) turns it on.",
+              "privacy": "public"
+            },
+            {
+              "kind": "field",
+              "name": "indeterminate",
+              "type": {
+                "text": "undefined | false | true"
+              },
+              "description": "The mixed state, for a parent box whose children are partly ticked. Visual plus an accessibility hint: the box still reports `checked === false`.",
+              "privacy": "public"
+            },
+            {
+              "kind": "field",
+              "name": "disabled",
+              "type": {
+                "text": "undefined | false | true"
+              },
+              "description": "Disable interaction.",
+              "privacy": "public"
+            },
+            {
+              "kind": "field",
+              "name": "required",
+              "type": {
+                "text": "undefined | false | true"
+              },
+              "description": "Set the native `required` attribute, and nothing more. Whether an unticked box is an error is the application's rule, not the kit's.",
+              "privacy": "public"
+            },
+            {
+              "kind": "field",
+              "name": "label",
               "type": {
                 "text": "undefined | string"
               },
-              "description": "Tooltip on hover.",
+              "description": "Accessible label. The visible text beside the box is the consumer's to render.",
               "privacy": "public"
             },
             {
               "kind": "field",
-              "name": "variant",
+              "name": "name",
               "type": {
-                "text": "undefined | \"ghost\" | \"default\" | \"outline\""
+                "text": "undefined | string"
               },
-              "description": "Visual button style.",
+              "description": "Form-control name (paired with `value`).",
               "privacy": "public"
             },
             {
               "kind": "field",
-              "name": "size",
+              "name": "value",
               "type": {
-                "text": "undefined | \"sm\" | \"md\" | \"lg\" | \"icon\" | \"icon-sm\""
+                "text": "undefined | string"
               },
-              "description": "Button size (use an `icon*` size for an icon-only checkpoint).",
+              "description": "Submitted value when checked (paired with `name`). Defaults to `'on'`.",
+              "privacy": "public"
+            },
+            {
+              "kind": "method",
+              "name": "toggle",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              },
+              "description": "Flip the box and fire `kai-change` (no-op while disabled).",
+              "privacy": "public"
+            },
+            {
+              "kind": "method",
+              "name": "focus",
+              "parameters": [
+                {
+                  "name": "options?: FocusOptions"
+                }
+              ],
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              },
+              "description": "Focus the inner input (the host element can't reach it).",
               "privacy": "public"
             }
           ],
@@ -2728,45 +2891,77 @@
               "description": "Color mode (`auto` follows prefers-color-scheme)."
             },
             {
-              "name": "label",
-              "fieldName": "label",
+              "name": "checked",
+              "fieldName": "checked",
               "type": {
-                "text": "undefined | string"
+                "text": "undefined | false | true"
               },
-              "description": "Optional text beside the icon."
+              "description": "Controlled checked state. Settable and reflected to the `checked` attribute. `el.checked = true` (or `<kai-checkbox checked>`) drives it; ticking the box updates it and fires `kai-change`. Read `el.checked` for live state."
             },
             {
-              "name": "tooltip",
-              "fieldName": "tooltip",
+              "name": "default-checked",
+              "fieldName": "defaultChecked",
+              "type": {
+                "text": "undefined | false | true"
+              },
+              "description": "Initial checked state on mount (uncontrolled seed). Bare attribute (`<kai-checkbox default-checked>`) turns it on."
+            },
+            {
+              "name": "indeterminate",
+              "fieldName": "indeterminate",
+              "type": {
+                "text": "undefined | false | true"
+              },
+              "description": "The mixed state, for a parent box whose children are partly ticked. Visual plus an accessibility hint: the box still reports `checked === false`."
+            },
+            {
+              "name": "disabled",
+              "fieldName": "disabled",
+              "type": {
+                "text": "undefined | false | true"
+              },
+              "description": "Disable interaction."
+            },
+            {
+              "name": "required",
+              "fieldName": "required",
+              "type": {
+                "text": "undefined | false | true"
+              },
+              "description": "Set the native `required` attribute, and nothing more. Whether an unticked box is an error is the application's rule, not the kit's."
+            },
+            {
+              "name": "label",
+              "fieldName": "label",
               "type": {
                 "text": "undefined | string"
               },
-              "description": "Tooltip on hover."
+              "description": "Accessible label. The visible text beside the box is the consumer's to render."
             },
             {
-              "name": "variant",
-              "fieldName": "variant",
+              "name": "name",
+              "fieldName": "name",
               "type": {
-                "text": "undefined | \"ghost\" | \"default\" | \"outline\""
+                "text": "undefined | string"
               },
-              "description": "Visual button style."
+              "description": "Form-control name (paired with `value`)."
             },
             {
-              "name": "size",
-              "fieldName": "size",
+              "name": "value",
+              "fieldName": "value",
               "type": {
-                "text": "undefined | \"sm\" | \"md\" | \"lg\" | \"icon\" | \"icon-sm\""
+                "text": "undefined | string"
               },
-              "description": "Button size (use an `icon*` size for an icon-only checkpoint)."
+              "description": "Submitted value when checked (paired with `name`). Defaults to `'on'`."
             }
           ],
           "events": [
             {
-              "name": "kai-select",
+              "name": "kai-change",
               "type": {
-                "text": "CustomEvent"
+                "text": "CustomEvent<{ checked: false | true }>"
               },
-              "description": "The checkpoint was clicked."
+              "description": "The box was ticked or unticked."
             }
           ],
           "cssProperties": []
@@ -2774,8 +2969,8 @@
         {
           "kind": "class",
           "customElement": true,
-          "tagName": "kai-choice",
-          "name": "KaiChoiceElement",
+          "tagName": "kai-checkbox-group",
+          "name": "KaiCheckboxGroupElement",
           "description": "",
           "members": [
             {
@@ -2789,65 +2984,47 @@
             },
             {
               "kind": "field",
-              "name": "data",
+              "name": "options",
               "type": {
-                "text": "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 }"
+                "text": "{ value: string; label: string; description?: undefined | string; disabled?: undefined | false | true }[]"
               },
-              "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.",
+              "description": "The choices, top to bottom. Set as a JS PROPERTY (array), never an attribute. Rendered in full: the kit never truncates, re-orders or de-duplicates them.",
               "privacy": "public"
             },
             {
               "kind": "field",
-              "name": "cardId",
+              "name": "value",
               "type": {
                 "text": "undefined | string"
               },
-              "description": "Stable card id correlating every emitted CardEvent. Attribute: `card-id`.",
+              "description": "The FIRST selected value. Settable and reflected to the `value` attribute, so `:host([value])` and `el.value` see live state, and a seed can be written in markup. Writing it makes that the whole selection; to read or drive the rest, use `el.values`.",
               "privacy": "public"
             },
             {
               "kind": "field",
-              "name": "heading",
+              "name": "name",
               "type": {
                 "text": "undefined | string"
               },
-              "description": "Heading rendered in the card chrome (= CardEnvelope.title). Attribute: `heading`.",
-              "privacy": "public"
-            },
-            {
-              "kind": "field",
-              "name": "resolution",
-              "type": {
-                "text": "undefined | Record<string, unknown>"
-              },
-              "description": "Set when the user resolved this card; renders the read-only view. Property: `el.resolution = { kind:'action', action:'…' }`.",
+              "description": "The shared form-control name every box carries, so `FormData.getAll(name)` reads the whole selection back under one key. NO DEFAULT, unlike `<kai-radio-group>`. A radio set needs a shared `name` for the browser to make it exclusive and arrow-navigable, so one is generated when none is given; checkboxes are independent controls and behave correctly with no name at all. Generating one here would submit the selection under a random key, which is worse than submitting nothing. The element is NOT form-associated (no `ElementInternals`, no `setFormValue()`), the same known gap `<kai-input>` records: the boxes live in a shadow root, so a surrounding `<form>` collects nothing from them whether or not `name` is set. Read `el.values`. The name still lands on every inner input, so it is right the day form association arrives.",
               "privacy": "public"
             },
             {
               "kind": "field",
-              "name": "value",
+              "name": "disabled",
               "type": {
-                "text": "undefined | string"
+                "text": "undefined | false | true"
               },
-              "description": "Controlled selection: the selected option id. When set, the consumer owns the current pick (RadioGroup `value`). Attribute: `value`.",
+              "description": "Disable every row. Individual rows carry their own `disabled`.",
               "privacy": "public"
             },
             {
               "kind": "field",
-              "name": "defaultValue",
+              "name": "label",
               "type": {
                 "text": "undefined | string"
               },
-              "description": "Option id to pre-select on mount (uncontrolled seed). Attribute: `default-value`.",
-              "privacy": "public"
-            },
-            {
-              "kind": "field",
-              "name": "disabled",
-              "type": {
-                "text": "undefined | false | true"
-              },
-              "description": "Disable the whole radiogroup + Submit (e.g. while the agent is busy). Attribute: `disabled`.",
+              "description": "Accessible name for the group.",
               "privacy": "public"
             },
             {
@@ -2863,12 +3040,267 @@
                   "text": "void"
                 }
               },
-              "description": "Focus the radiogroup roving tab stop (or the Other input when selected).",
+              "description": "Focus the group's first box. Not \"the first ticked one\", which is `<kai-radio-group>`'s rule: a radio group is ONE tab stop that lands on the selection, while every checkbox here is its own tab stop, so the entry point is simply the top of the list.",
               "privacy": "public"
-            },
+            }
+          ],
+          "attributes": [
             {
-              "kind": "method",
-              "name": "select",
+              "name": "theme",
+              "fieldName": "theme",
+              "type": {
+                "text": "\"light\" | \"dark\" | \"auto\""
+              },
+              "description": "Color mode (`auto` follows prefers-color-scheme)."
+            },
+            {
+              "name": "value",
+              "fieldName": "value",
+              "type": {
+                "text": "undefined | string"
+              },
+              "description": "The FIRST selected value. Settable and reflected to the `value` attribute, so `:host([value])` and `el.value` see live state, and a seed can be written in markup. Writing it makes that the whole selection; to read or drive the rest, use `el.values`."
+            },
+            {
+              "name": "name",
+              "fieldName": "name",
+              "type": {
+                "text": "undefined | string"
+              },
+              "description": "The shared form-control name every box carries, so `FormData.getAll(name)` reads the whole selection back under one key. NO DEFAULT, unlike `<kai-radio-group>`. A radio set needs a shared `name` for the browser to make it exclusive and arrow-navigable, so one is generated when none is given; checkboxes are independent controls and behave correctly with no name at all. Generating one here would submit the selection under a random key, which is worse than submitting nothing. The element is NOT form-associated (no `ElementInternals`, no `setFormValue()`), the same known gap `<kai-input>` records: the boxes live in a shadow root, so a surrounding `<form>` collects nothing from them whether or not `name` is set. Read `el.values`. The name still lands on every inner input, so it is right the day form association arrives."
+            },
+            {
+              "name": "disabled",
+              "fieldName": "disabled",
+              "type": {
+                "text": "undefined | false | true"
+              },
+              "description": "Disable every row. Individual rows carry their own `disabled`."
+            },
+            {
+              "name": "label",
+              "fieldName": "label",
+              "type": {
+                "text": "undefined | string"
+              },
+              "description": "Accessible name for the group."
+            }
+          ],
+          "events": [
+            {
+              "name": "kai-change",
+              "type": {
+                "text": "CustomEvent<{ value: string; values: string[] }>"
+              },
+              "description": "A row was ticked or unticked. `values` is the whole selection after the change, which is what a multi-select control needs; `value` is the first of them (empty when nothing is selected). Both are always present, so neither shape silently loses the other. This is `<kai-select>`'s detail, deliberately."
+            }
+          ],
+          "cssProperties": []
+        },
+        {
+          "kind": "class",
+          "customElement": true,
+          "tagName": "kai-checkpoint",
+          "name": "KaiCheckpointElement",
+          "description": "",
+          "members": [
+            {
+              "kind": "field",
+              "name": "theme",
+              "type": {
+                "text": "\"light\" | \"dark\" | \"auto\""
+              },
+              "description": "Color mode (`auto` follows prefers-color-scheme).",
+              "privacy": "public"
+            },
+            {
+              "kind": "field",
+              "name": "label",
+              "type": {
+                "text": "undefined | string"
+              },
+              "description": "Optional text beside the icon.",
+              "privacy": "public"
+            },
+            {
+              "kind": "field",
+              "name": "tooltip",
+              "type": {
+                "text": "undefined | string"
+              },
+              "description": "Tooltip on hover.",
+              "privacy": "public"
+            },
+            {
+              "kind": "field",
+              "name": "variant",
+              "type": {
+                "text": "undefined | \"ghost\" | \"default\" | \"outline\""
+              },
+              "description": "Visual button style.",
+              "privacy": "public"
+            },
+            {
+              "kind": "field",
+              "name": "size",
+              "type": {
+                "text": "undefined | \"sm\" | \"md\" | \"lg\" | \"icon\" | \"icon-sm\""
+              },
+              "description": "Button size (use an `icon*` size for an icon-only checkpoint).",
+              "privacy": "public"
+            }
+          ],
+          "attributes": [
+            {
+              "name": "theme",
+              "fieldName": "theme",
+              "type": {
+                "text": "\"light\" | \"dark\" | \"auto\""
+              },
+              "description": "Color mode (`auto` follows prefers-color-scheme)."
+            },
+            {
+              "name": "label",
+              "fieldName": "label",
+              "type": {
+                "text": "undefined | string"
+              },
+              "description": "Optional text beside the icon."
+            },
+            {
+              "name": "tooltip",
+              "fieldName": "tooltip",
+              "type": {
+                "text": "undefined | string"
+              },
+              "description": "Tooltip on hover."
+            },
+            {
+              "name": "variant",
+              "fieldName": "variant",
+              "type": {
+                "text": "undefined | \"ghost\" | \"default\" | \"outline\""
+              },
+              "description": "Visual button style."
+            },
+            {
+              "name": "size",
+              "fieldName": "size",
+              "type": {
+                "text": "undefined | \"sm\" | \"md\" | \"lg\" | \"icon\" | \"icon-sm\""
+              },
+              "description": "Button size (use an `icon*` size for an icon-only checkpoint)."
+            }
+          ],
+          "events": [
+            {
+              "name": "kai-select",
+              "type": {
+                "text": "CustomEvent"
+              },
+              "description": "The checkpoint was clicked."
+            }
+          ],
+          "cssProperties": []
+        },
+        {
+          "kind": "class",
+          "customElement": true,
+          "tagName": "kai-choice",
+          "name": "KaiChoiceElement",
+          "description": "",
+          "members": [
+            {
+              "kind": "field",
+              "name": "theme",
+              "type": {
+                "text": "\"light\" | \"dark\" | \"auto\""
+              },
+              "description": "Color mode (`auto` follows prefers-color-scheme).",
+              "privacy": "public"
+            },
+            {
+              "kind": "field",
+              "name": "data",
+              "type": {
+                "text": "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 }"
+              },
+              "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.",
+              "privacy": "public"
+            },
+            {
+              "kind": "field",
+              "name": "cardId",
+              "type": {
+                "text": "undefined | string"
+              },
+              "description": "Stable card id correlating every emitted CardEvent. Attribute: `card-id`.",
+              "privacy": "public"
+            },
+            {
+              "kind": "field",
+              "name": "heading",
+              "type": {
+                "text": "undefined | string"
+              },
+              "description": "Heading rendered in the card chrome (= CardEnvelope.title). Attribute: `heading`.",
+              "privacy": "public"
+            },
+            {
+              "kind": "field",
+              "name": "resolution",
+              "type": {
+                "text": "undefined | Record<string, unknown>"
+              },
+              "description": "Set when the user resolved this card; renders the read-only view. Property: `el.resolution = { kind:'action', action:'…' }`.",
+              "privacy": "public"
+            },
+            {
+              "kind": "field",
+              "name": "value",
+              "type": {
+                "text": "undefined | string"
+              },
+              "description": "Controlled selection: the selected option id. When set, the consumer owns the current pick (RadioGroup `value`). Attribute: `value`.",
+              "privacy": "public"
+            },
+            {
+              "kind": "field",
+              "name": "defaultValue",
+              "type": {
+                "text": "undefined | string"
+              },
+              "description": "Option id to pre-select on mount (uncontrolled seed). Attribute: `default-value`.",
+              "privacy": "public"
+            },
+            {
+              "kind": "field",
+              "name": "disabled",
+              "type": {
+                "text": "undefined | false | true"
+              },
+              "description": "Disable the whole radiogroup + Submit (e.g. while the agent is busy). Attribute: `disabled`.",
+              "privacy": "public"
+            },
+            {
+              "kind": "method",
+              "name": "focus",
+              "parameters": [
+                {
+                  "name": "options?: FocusOptions"
+                }
+              ],
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              },
+              "description": "Focus the radiogroup roving tab stop (or the Other input when selected).",
+              "privacy": "public"
+            },
+            {
+              "kind": "method",
+              "name": "select",
               "parameters": [
                 {
                   "name": "optionId: string"
@@ -3928,7 +4360,7 @@
               "type": {
                 "text": "CustomEvent<{ doc: ({ type: \"text\"; text: string } | { type: \"entity\"; entity: { kind: string; id: string; label: string; icon?: undefined | string; promptText?: undefined | string; data?: undefined | Record<string, unknown> } })[]; text: string; entities: { kind: string; id: string; label: string; icon?: undefined | string; promptText?: undefined | string; data?: undefined | Record<string, unknown> }[] }>"
               },
-              "description": "The user submitted the composer (Enter or programmatic submit)."
+              "description": "The user submitted the composer (Enter or programmatic submit). Note the detail carries no `attachments`; `<kai-composer>` is the bare editing surface: no send button, toolbar, or attachments. For a drop-in composer row with all three, reach for `<kai-prompt-input>`, which is built on this."
             },
             {
               "name": "kai-trigger",
@@ -4222,7 +4654,7 @@
               "type": {
                 "text": "undefined | string"
               },
-              "description": "The row's identity, handed to the container's selection contract. In the element this is the `conversation-id` attribute (host `id` is the fallback).",
+              "description": "The row's identity: the `conversation-id` attribute (host `id` is the fallback). Inside `<kai-conversations>` it is handed to the container's selection contract (`kai-conversation-select`); standalone it is the `id` in this element's own `kai-select` detail.",
               "privacy": "public"
             },
             {
@@ -4231,7 +4663,7 @@
               "type": {
                 "text": "undefined | false | true"
               },
-              "description": "Selected state. Reflected as `aria-current` on the row body and a `data-active` styling hook on the row; the container drives it from its `activeId`.",
+              "description": "Selected state. Reflected as `aria-current` on the row body and a `data-active` styling hook on the row; inside a container the container drives it from its `activeId`, standalone you set it yourself.",
               "privacy": "public"
             },
             {
@@ -4259,7 +4691,7 @@
               "type": {
                 "text": "undefined | string"
               },
-              "description": "The row's identity, handed to the container's selection contract. In the element this is the `conversation-id` attribute (host `id` is the fallback)."
+              "description": "The row's identity: the `conversation-id` attribute (host `id` is the fallback). Inside `<kai-conversations>` it is handed to the container's selection contract (`kai-conversation-select`); standalone it is the `id` in this element's own `kai-select` detail."
             },
             {
               "name": "active",
@@ -4267,7 +4699,7 @@
               "type": {
                 "text": "undefined | false | true"
               },
-              "description": "Selected state. Reflected as `aria-current` on the row body and a `data-active` styling hook on the row; the container drives it from its `activeId`."
+              "description": "Selected state. Reflected as `aria-current` on the row body and a `data-active` styling hook on the row; inside a container the container drives it from its `activeId`, standalone you set it yourself."
             },
             {
               "name": "compact",
@@ -4278,13 +4710,21 @@
               "description": "Dense single-line row padding."
             }
           ],
-          "events": [],
-          "cssProperties": [],
-          "slots": [
+          "events": [
             {
-              "name": "",
-              "description": "The row title. `leading`, `meta` and `menu` are the named regions around it."
-            },
+              "name": "kai-select",
+              "type": {
+                "text": "CustomEvent<{ id: string }>"
+              },
+              "description": "STANDALONE activation only: the row was activated (click, Enter or Space on its body) while the item is NOT a direct child of `<kai-conversations>`. `id` is the row's identity: the `conversation-id` attribute, else the host `id`. Inside a container this never fires: activation surfaces once, as `kai-conversation-select` on the container."
+            }
+          ],
+          "cssProperties": [],
+          "slots": [
+            {
+              "name": "",
+              "description": "The row title. `leading`, `meta` and `menu` are the named regions around it."
+            },
             {
               "name": "leading",
               "description": "Leading region before the title (an icon or avatar)."
@@ -4357,7 +4797,7 @@
               "kind": "field",
               "name": "conversations",
               "type": {
-                "text": "undefined | { id: string; title: string; groupId?: undefined | string; scope?: undefined | { 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?: undefined | string; updatedAt: string; trailing?: undefined | string }[]"
+                "text": "undefined | { id: string; title: string; groupId?: undefined | string; scope?: undefined | { 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?: undefined | string; updatedAt: string; trailing?: undefined | string; lastReadAt?: undefined | string }[]"
               },
               "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. A search query that matches nothing shows a visible \"No conversations match your search\" state, distinct from the zero-conversations empty state. Slotted `<kai-conversation-item>` children switch the list into item mode instead: your own rows win and this array is not rendered.",
               "privacy": "public"
@@ -4574,7 +5014,7 @@
                 }
               ],
               "textContent": 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 Fields not expressible as HTML attributes are NOT fabricated (F-10): the optional `scope` and `lastMessageAt` stay absent, and the required `messageCount`/`updatedAt` get honest defaults — zero messages, and an empty `updatedAt` from which no trailing relative time is derived (the epoch it used to fabricate rendered a bogus \"many days ago\" on every declarative row)."
+              "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 Fields not expressible as HTML attributes are NOT fabricated: the optional `scope` and `lastMessageAt` stay absent, and the required `messageCount`/`updatedAt` get honest defaults — zero messages, and an empty `updatedAt` from which no trailing relative time is derived (the epoch it used to fabricate rendered a bogus \"many days ago\" on every declarative row)."
             }
           ],
           "slots": [
@@ -4873,6 +5313,15 @@
               "description": "Disable the launcher; `show()` and `toggle()` are gated on it.",
               "privacy": "public"
             },
+            {
+              "kind": "field",
+              "name": "hideClose",
+              "type": {
+                "text": "undefined | false | true"
+              },
+              "description": "Suppress the dock's own built-in mobile close X. Set this when your slotted panel content supplies its own close affordance (e.g. a `<kai-chat slot=\"header-end\">` close button), otherwise the two stack. TRADEOFF: the mobile panel reserves a padding band above its content so the built-in X never paints over slotted content; that band stays reserved unless you set this true, so only set it once your own control is actually in place. Attribute: `hide-close`.",
+              "privacy": "public"
+            },
             {
               "kind": "field",
               "name": "focusOnOpen",
@@ -5005,6 +5454,14 @@
               },
               "description": "Disable the launcher; `show()` and `toggle()` are gated on it."
             },
+            {
+              "name": "hide-close",
+              "fieldName": "hideClose",
+              "type": {
+                "text": "undefined | false | true"
+              },
+              "description": "Suppress the dock's own built-in mobile close X. Set this when your slotted panel content supplies its own close affordance (e.g. a `<kai-chat slot=\"header-end\">` close button), otherwise the two stack. TRADEOFF: the mobile panel reserves a padding band above its content so the built-in X never paints over slotted content; that band stays reserved unless you set this true, so only set it once your own control is actually in place. Attribute: `hide-close`."
+            },
             {
               "name": "focus-on-open",
               "fieldName": "focusOnOpen",
@@ -5971,7 +6428,7 @@
               "kind": "field",
               "name": "data",
               "type": {
-                "text": "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\" }[] }"
+                "text": "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-format\"?: undefined | \"tel\" | \"ssn\" | \"credit-card\" | \"custom\"; \"x-kai-mask\"?: undefined | string; \"x-kai-mask-guide\"?: undefined | string }>; \"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\" }[] }"
               },
               "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.",
               "privacy": "public"
@@ -6522,7 +6979,7 @@
               "type": {
                 "text": "undefined | string"
               },
-              "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, and always the CANONICAL one when a mask is active: digits for `tel` / `ssn` / `credit-card`, the formatted text for `custom`. Settable and reflected to the `value` attribute. `el.value = '5551234567'` drives it (no event) and is re-fitted to the mask on the way in, so the field shows `555-123-4567`. Read `el.value` for live state; the formatted text rides along on every `kai-input` / `kai-change` detail as `formattedValue`.",
               "privacy": "public"
             },
             {
@@ -6633,6 +7090,51 @@
               "description": "Virtual-keyboard hint forwarded to the inner input (e.g. `numeric`, `email`).",
               "privacy": "public"
             },
+            {
+              "kind": "field",
+              "name": "format",
+              "type": {
+                "text": "undefined | string"
+              },
+              "description": "Mask pattern: `#` a digit, `@` a letter or digit, `*` an obscurable letter or digit, and every other character a positional literal (`@@@-####` → `CHG-4821`). The literal `default` is the opt-in sentinel: it resolves to the default format of `semantic` (`tel` → `###-###-####`). A bare `semantic` never starts masking on its own, so an opt-in token is what turns tier 2 on.",
+              "privacy": "public"
+            },
+            {
+              "kind": "field",
+              "name": "guide",
+              "type": {
+                "text": "undefined | string"
+              },
+              "description": "Placeholder guide shown at unfilled positions, aligned position for position with `format`: `mm/dd/yyyy` against `##/##/####`. Spaces are a valid guide character, so a guide of blanks and separators is how a phone field shows its shape without showing letters. Without a guide the field shows only up to the last typed character. A guide is a visual aid, never an accessible name: keep the `hint` text as well.",
+              "privacy": "public"
+            },
+            {
+              "kind": "field",
+              "name": "semantic",
+              "type": {
+                "text": "undefined | \"credit-card\" | \"custom\" | \"ssn\" | \"tel\""
+              },
+              "description": "Semantic field type: `tel` · `ssn` · `credit-card` · `custom`. On its own it sets `inputmode` / `autocomplete` / `spellcheck` / `autocorrect` / `autocapitalize` and decides the canonical value; it never starts masking by itself.",
+              "privacy": "public"
+            },
+            {
+              "kind": "field",
+              "name": "caseMode",
+              "type": {
+                "text": "undefined | \"preserve\" | \"upper\" | \"lower\""
+              },
+              "description": "Case folding applied to typed and pasted text: `preserve` (default) · `upper` · `lower`. Attribute: `case-mode`.",
+              "privacy": "public"
+            },
+            {
+              "kind": "field",
+              "name": "copyPolicy",
+              "type": {
+                "text": "undefined | \"formatted\" | \"canonical\" | \"obscured\" | \"blocked\""
+              },
+              "description": "What a copy or cut of a masked field puts on the clipboard: `canonical` (default) · `formatted` · `obscured` · `blocked`. Attribute: `copy-policy`.",
+              "privacy": "public"
+            },
             {
               "kind": "method",
               "name": "focus",
@@ -6660,6 +7162,28 @@
               "description": "Select the inner input's text.",
               "privacy": "public"
             },
+            {
+              "kind": "method",
+              "name": "getRawValue",
+              "return": {
+                "type": {
+                  "text": "string"
+                }
+              },
+              "description": "The canonical value: digits for `tel` / `ssn` / `credit-card`, the formatted text for `custom`, and the field text when no mask is on. Identical to reading `el.value`, under the name backends use for the submitted form of a masked field. The mask engine has a third, narrower notion of raw (the fill characters with no literals at all) and that one is internal: it is not what any backend wants and it is not exposed here.",
+              "privacy": "public"
+            },
+            {
+              "kind": "method",
+              "name": "getFormattedValue",
+              "return": {
+                "type": {
+                  "text": "string"
+                }
+              },
+              "description": "The text on screen, literals and guide included. The counterpart to `formattedValue` on the `kai-input` / `kai-change` details, for a consumer that needs it outside an event.",
+              "privacy": "public"
+            },
             {
               "kind": "method",
               "name": "clear",
@@ -6668,7 +7192,7 @@
                   "text": "void"
                 }
               },
-              "description": "Empty the value and fire `kai-change` with `''`.",
+              "description": "Empty the value and fire `kai-change` with `''`. On a masked field this resets the mask itself, not just the text on screen, so the next character starts over.",
               "privacy": "public"
             }
           ],
@@ -6695,7 +7219,7 @@
               "type": {
                 "text": "undefined | string"
               },
-              "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, and always the CANONICAL one when a mask is active: digits for `tel` / `ssn` / `credit-card`, the formatted text for `custom`. Settable and reflected to the `value` attribute. `el.value = '5551234567'` drives it (no event) and is re-fitted to the mask on the way in, so the field shows `555-123-4567`. Read `el.value` for live state; the formatted text rides along on every `kai-input` / `kai-change` detail as `formattedValue`."
             },
             {
               "name": "placeholder",
@@ -6792,22 +7316,69 @@
                 "text": "undefined | string"
               },
               "description": "Virtual-keyboard hint forwarded to the inner input (e.g. `numeric`, `email`)."
+            },
+            {
+              "name": "format",
+              "fieldName": "format",
+              "type": {
+                "text": "undefined | string"
+              },
+              "description": "Mask pattern: `#` a digit, `@` a letter or digit, `*` an obscurable letter or digit, and every other character a positional literal (`@@@-####` → `CHG-4821`). The literal `default` is the opt-in sentinel: it resolves to the default format of `semantic` (`tel` → `###-###-####`). A bare `semantic` never starts masking on its own, so an opt-in token is what turns tier 2 on."
+            },
+            {
+              "name": "guide",
+              "fieldName": "guide",
+              "type": {
+                "text": "undefined | string"
+              },
+              "description": "Placeholder guide shown at unfilled positions, aligned position for position with `format`: `mm/dd/yyyy` against `##/##/####`. Spaces are a valid guide character, so a guide of blanks and separators is how a phone field shows its shape without showing letters. Without a guide the field shows only up to the last typed character. A guide is a visual aid, never an accessible name: keep the `hint` text as well."
+            },
+            {
+              "name": "semantic",
+              "fieldName": "semantic",
+              "type": {
+                "text": "undefined | \"credit-card\" | \"custom\" | \"ssn\" | \"tel\""
+              },
+              "description": "Semantic field type: `tel` · `ssn` · `credit-card` · `custom`. On its own it sets `inputmode` / `autocomplete` / `spellcheck` / `autocorrect` / `autocapitalize` and decides the canonical value; it never starts masking by itself."
+            },
+            {
+              "name": "case-mode",
+              "fieldName": "caseMode",
+              "type": {
+                "text": "undefined | \"preserve\" | \"upper\" | \"lower\""
+              },
+              "description": "Case folding applied to typed and pasted text: `preserve` (default) · `upper` · `lower`. Attribute: `case-mode`."
+            },
+            {
+              "name": "copy-policy",
+              "fieldName": "copyPolicy",
+              "type": {
+                "text": "undefined | \"formatted\" | \"canonical\" | \"obscured\" | \"blocked\""
+              },
+              "description": "What a copy or cut of a masked field puts on the clipboard: `canonical` (default) · `formatted` · `obscured` · `blocked`. Attribute: `copy-policy`."
             }
           ],
           "events": [
             {
               "name": "kai-change",
               "type": {
-                "text": "CustomEvent<{ value: string }>"
+                "text": "CustomEvent<{ value: string; formattedValue: string }>"
               },
-              "description": "The value was committed (blur)."
+              "description": "The value was committed (blur). Same detail shape as `kai-input`."
             },
             {
               "name": "kai-input",
               "type": {
-                "text": "CustomEvent<{ value: string }>"
+                "text": "CustomEvent<{ value: string; formattedValue: string }>"
               },
-              "description": "The value changed per keystroke."
+              "description": "The value changed per keystroke. `value` is the canonical value (what a backend wants); `formattedValue` is the text on screen. With no mask the two are equal."
+            },
+            {
+              "name": "kai-input-rejected",
+              "type": {
+                "text": "CustomEvent<{ reason: \"full\" | \"wrong-class\" | \"over-capacity\" | \"format-change-clipped\"; data: string }>"
+              },
+              "description": "A mask refused, or partly refused, some content. The reasons are `full` (no free position left), `wrong-class` (a letter into a digit position), `over-capacity` (a paste longer than the mask holds; what fits was kept), and `format-change-clipped` (the `format` changed under a value that no longer fits). `data` is the content that was refused. The first three are USER-INPUT errors, and are the ones worth announcing in a polite live region. `format-change-clipped` is not one: it follows the app changing its own configuration, so it reports and nothing more. None of the four touches validity, so `invalid` and `error` stay the consumer decision."
             }
           ],
           "cssProperties": [],
@@ -8384,6 +8955,113 @@
             }
           ]
         },
+        {
+          "kind": "class",
+          "customElement": true,
+          "tagName": "kai-pane-grid",
+          "name": "KaiPaneGridElement",
+          "description": "",
+          "members": [
+            {
+              "kind": "field",
+              "name": "theme",
+              "type": {
+                "text": "\"light\" | \"dark\" | \"auto\""
+              },
+              "description": "Color mode (`auto` follows prefers-color-scheme).",
+              "privacy": "public"
+            },
+            {
+              "kind": "field",
+              "name": "minPaneWidth",
+              "type": {
+                "text": "undefined | number"
+              },
+              "description": "Minimum width of every pane, in px, before columns drop / the grid scrolls. Defaults to `280`. Attribute: `min-pane-width`.",
+              "privacy": "public"
+            },
+            {
+              "kind": "field",
+              "name": "minPaneHeight",
+              "type": {
+                "text": "undefined | number"
+              },
+              "description": "Minimum height of every pane, in px, before the grid scrolls vertically. Defaults to `200`. Attribute: `min-pane-height`.",
+              "privacy": "public"
+            },
+            {
+              "kind": "field",
+              "name": "maxColumns",
+              "type": {
+                "text": "undefined | number"
+              },
+              "description": "Column cap when the container is wide (default `3`). Attribute: `max-columns`.",
+              "privacy": "public"
+            },
+            {
+              "kind": "field",
+              "name": "gap",
+              "type": {
+                "text": "undefined | string"
+              },
+              "description": "Gap between panes, any CSS length. Defaults to the kit gap (`var(--kai-pane-grid-gap, 0.5rem)`). Attribute: `gap`.",
+              "privacy": "public"
+            },
+            {
+              "kind": "field",
+              "name": "maximizedIndex",
+              "type": {
+                "text": "undefined | number | null"
+              },
+              "description": "When set to a valid child index, render ONLY that pane full-bleed: a simple maximize hook the consumer drives (pair it with `<kai-pane>`'s `kai-maximize` event). Clear it (or point out of range) for the full tiled grid. Attribute: `maximized-index`.",
+              "privacy": "public"
+            }
+          ],
+          "attributes": [
+            {
+              "name": "theme",
+              "fieldName": "theme",
+              "type": {
+                "text": "\"light\" | \"dark\" | \"auto\""
+              },
+              "description": "Color mode (`auto` follows prefers-color-scheme)."
+            },
+            {
+              "name": "min-pane-width",
+              "fieldName": "minPaneWidth",
+              "type": {
+                "text": "undefined | number"
+              },
+              "description": "Minimum width of every pane, in px, before columns drop / the grid scrolls. Defaults to `280`. Attribute: `min-pane-width`."
+            },
+            {
+              "name": "min-pane-height",
+              "fieldName": "minPaneHeight",
+              "type": {
+                "text": "undefined | number"
+              },
+              "description": "Minimum height of every pane, in px, before the grid scrolls vertically. Defaults to `200`. Attribute: `min-pane-height`."
+            },
+            {
+              "name": "max-columns",
+              "fieldName": "maxColumns",
+              "type": {
+                "text": "undefined | number"
+              },
+              "description": "Column cap when the container is wide (default `3`). Attribute: `max-columns`."
+            },
+            {
+              "name": "gap",
+              "fieldName": "gap",
+              "type": {
+                "text": "undefined | string"
+              },
+              "description": "Gap between panes, any CSS length. Defaults to the kit gap (`var(--kai-pane-grid-gap, 0.5rem)`). Attribute: `gap`."
+            }
+          ],
+          "events": [],
+          "cssProperties": []
+        },
         {
           "kind": "class",
           "customElement": true,
@@ -9029,7 +9707,7 @@
               "type": {
                 "text": "undefined | { id: string; type: \"file\" | \"source-document\"; filename?: undefined | string; mediaType?: undefined | string; url?: undefined | string; title?: undefined | string }[]"
               },
-              "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).",
+              "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). Each item's `url` must be a `data:` URI or an https URL, never `URL.createObjectURL`: a `blob:` URL previews perfectly and is meaningless outside this tab, so `toOpenAIMessages`/`toAnthropicMessages` refuse it. (The built-in paperclip already stages files as `data:` URIs.)",
               "privacy": "public"
             },
             {
@@ -9202,7 +9880,7 @@
               "type": {
                 "text": "CustomEvent<{ value: string; doc: ({ type: \"text\"; text: string } | { type: \"entity\"; entity: { kind: string; id: string; label: string; icon?: undefined | string; promptText?: undefined | string; data?: undefined | Record<string, unknown> } })[]; entities: { kind: string; id: string; label: string; icon?: undefined | string; promptText?: undefined | string; data?: undefined | Record<string, unknown> }[]; attachments: { id: string; type: \"file\" | \"source-document\"; filename?: undefined | string; mediaType?: undefined | string; url?: undefined | string; title?: undefined | string }[] }>"
               },
-              "description": "The user submitted the prompt (Enter or send button). `value` is the flattened text (back-compat); `doc` is the structured document and `entities` the inserted pills (skills/agents) for downstream expansion."
+              "description": "The user submitted the prompt (Enter or send button). `value` is the flattened text (back-compat); `doc` is the structured document and `entities` the inserted pills (skills/agents) for downstream expansion. `<kai-prompt-input>` is the batteries-included composer row (send button, toolbar, attachment staging) built on `<kai-composer>`, the bare editor."
             },
             {
               "name": "kai-suggestion-click",
@@ -9290,8 +9968,8 @@
         {
           "kind": "class",
           "customElement": true,
-          "tagName": "kai-reasoning",
-          "name": "KaiReasoningElement",
+          "tagName": "kai-radio-group",
+          "name": "KaiRadioGroupElement",
           "description": "",
           "members": [
             {
@@ -9305,98 +9983,63 @@
             },
             {
               "kind": "field",
-              "name": "text",
+              "name": "options",
               "type": {
-                "text": "string"
+                "text": "{ value: string; label: string; description?: undefined | string; disabled?: undefined | false | true }[]"
               },
-              "description": "The reasoning text to display.",
+              "description": "The choices, top to bottom. Set as a JS PROPERTY (array), never an attribute.",
               "privacy": "public"
             },
             {
               "kind": "field",
-              "name": "label",
+              "name": "value",
               "type": {
                 "text": "undefined | string"
               },
-              "description": "Trigger label.",
-              "privacy": "public"
-            },
-            {
-              "kind": "field",
-              "name": "open",
-              "type": {
-                "text": "undefined | false | true"
-              },
-              "description": "Drive/observe open state (Shoelace-style: settable + reflected to the `open` attribute; the element still self-manages on trigger click + while streaming). Set `el.open = true`; listen for `kai-open-change`.",
-              "privacy": "public"
-            },
-            {
-              "kind": "field",
-              "name": "defaultOpen",
-              "type": {
-                "text": "undefined | false | true"
-              },
-              "description": "Initial open state on mount (uncontrolled seed).",
+              "description": "Controlled selected `value`. Settable and reflected to the `value` attribute. `el.value = 'degraded'` drives it; choosing a row updates it and fires `kai-change`. Read `el.value` for live state.",
               "privacy": "public"
             },
             {
               "kind": "field",
-              "name": "streaming",
+              "name": "name",
               "type": {
-                "text": "undefined | false | true"
+                "text": "undefined | string"
               },
-              "description": "While true, auto-expands (and re-collapses when it flips false).",
+              "description": "Shared form-control name for every radio in the group. Defaults to a generated id, so the group is exclusive and keyboard-navigable even when nothing is submitted.",
               "privacy": "public"
             },
             {
               "kind": "field",
-              "name": "markdown",
+              "name": "disabled",
               "type": {
                 "text": "undefined | false | true"
               },
-              "description": "Render `text` as markdown.",
+              "description": "Disable every row. Individual rows carry their own `disabled`.",
               "privacy": "public"
             },
             {
               "kind": "field",
-              "name": "disabled",
+              "name": "label",
               "type": {
-                "text": "undefined | false | true"
-              },
-              "description": "Gate the disclosure trigger: programmatic `show()/hide()/toggle()` still work, but the trigger click no longer toggles.",
-              "privacy": "public"
-            },
-            {
-              "kind": "method",
-              "name": "show",
-              "return": {
-                "type": {
-                  "text": "void"
-                }
+                "text": "undefined | string"
               },
-              "description": "Open it programmatically (no-op while disabled).",
+              "description": "Accessible name for the group.",
               "privacy": "public"
             },
             {
               "kind": "method",
-              "name": "hide",
-              "return": {
-                "type": {
-                  "text": "void"
+              "name": "focus",
+              "parameters": [
+                {
+                  "name": "options?: FocusOptions"
                 }
-              },
-              "description": "Close it programmatically.",
-              "privacy": "public"
-            },
-            {
-              "kind": "method",
-              "name": "toggle",
+              ],
               "return": {
                 "type": {
                   "text": "void"
                 }
               },
-              "description": "Flip the open state (closes while disabled).",
+              "description": "Focus the group's tab stop. That is the selected radio, or the first row when nothing is selected yet.",
               "privacy": "public"
             }
           ],
@@ -9410,8 +10053,174 @@
               "description": "Color mode (`auto` follows prefers-color-scheme)."
             },
             {
-              "name": "text",
-              "fieldName": "text",
+              "name": "value",
+              "fieldName": "value",
+              "type": {
+                "text": "undefined | string"
+              },
+              "description": "Controlled selected `value`. Settable and reflected to the `value` attribute. `el.value = 'degraded'` drives it; choosing a row updates it and fires `kai-change`. Read `el.value` for live state."
+            },
+            {
+              "name": "name",
+              "fieldName": "name",
+              "type": {
+                "text": "undefined | string"
+              },
+              "description": "Shared form-control name for every radio in the group. Defaults to a generated id, so the group is exclusive and keyboard-navigable even when nothing is submitted."
+            },
+            {
+              "name": "disabled",
+              "fieldName": "disabled",
+              "type": {
+                "text": "undefined | false | true"
+              },
+              "description": "Disable every row. Individual rows carry their own `disabled`."
+            },
+            {
+              "name": "label",
+              "fieldName": "label",
+              "type": {
+                "text": "undefined | string"
+              },
+              "description": "Accessible name for the group."
+            }
+          ],
+          "events": [
+            {
+              "name": "kai-change",
+              "type": {
+                "text": "CustomEvent<{ value: string }>"
+              },
+              "description": "A row was chosen."
+            }
+          ],
+          "cssProperties": []
+        },
+        {
+          "kind": "class",
+          "customElement": true,
+          "tagName": "kai-reasoning",
+          "name": "KaiReasoningElement",
+          "description": "",
+          "members": [
+            {
+              "kind": "field",
+              "name": "theme",
+              "type": {
+                "text": "\"light\" | \"dark\" | \"auto\""
+              },
+              "description": "Color mode (`auto` follows prefers-color-scheme).",
+              "privacy": "public"
+            },
+            {
+              "kind": "field",
+              "name": "text",
+              "type": {
+                "text": "string"
+              },
+              "description": "The reasoning text to display.",
+              "privacy": "public"
+            },
+            {
+              "kind": "field",
+              "name": "label",
+              "type": {
+                "text": "undefined | string"
+              },
+              "description": "Trigger label.",
+              "privacy": "public"
+            },
+            {
+              "kind": "field",
+              "name": "open",
+              "type": {
+                "text": "undefined | false | true"
+              },
+              "description": "Drive/observe open state (Shoelace-style: settable + reflected to the `open` attribute; the element still self-manages on trigger click + while streaming). Set `el.open = true`; listen for `kai-open-change`.",
+              "privacy": "public"
+            },
+            {
+              "kind": "field",
+              "name": "defaultOpen",
+              "type": {
+                "text": "undefined | false | true"
+              },
+              "description": "Initial open state on mount (uncontrolled seed).",
+              "privacy": "public"
+            },
+            {
+              "kind": "field",
+              "name": "streaming",
+              "type": {
+                "text": "undefined | false | true"
+              },
+              "description": "While true, auto-expands (and re-collapses when it flips false).",
+              "privacy": "public"
+            },
+            {
+              "kind": "field",
+              "name": "markdown",
+              "type": {
+                "text": "undefined | false | true"
+              },
+              "description": "Render `text` as markdown.",
+              "privacy": "public"
+            },
+            {
+              "kind": "field",
+              "name": "disabled",
+              "type": {
+                "text": "undefined | false | true"
+              },
+              "description": "Gate the disclosure trigger: programmatic `show()/hide()/toggle()` still work, but the trigger click no longer toggles.",
+              "privacy": "public"
+            },
+            {
+              "kind": "method",
+              "name": "show",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              },
+              "description": "Open it programmatically (no-op while disabled).",
+              "privacy": "public"
+            },
+            {
+              "kind": "method",
+              "name": "hide",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              },
+              "description": "Close it programmatically.",
+              "privacy": "public"
+            },
+            {
+              "kind": "method",
+              "name": "toggle",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              },
+              "description": "Flip the open state (closes while disabled).",
+              "privacy": "public"
+            }
+          ],
+          "attributes": [
+            {
+              "name": "theme",
+              "fieldName": "theme",
+              "type": {
+                "text": "\"light\" | \"dark\" | \"auto\""
+              },
+              "description": "Color mode (`auto` follows prefers-color-scheme)."
+            },
+            {
+              "name": "text",
+              "fieldName": "text",
               "type": {
                 "text": "string"
               },
@@ -10425,6 +11234,24 @@
               },
               "description": "Button size token. Defaults to `'icon'` (square).",
               "privacy": "public"
+            },
+            {
+              "kind": "field",
+              "name": "label",
+              "type": {
+                "text": "undefined | string"
+              },
+              "description": "The button's accessible name. It is announced whether or not the label is visible, so the text is always localisable. Defaults to `'Scroll to bottom'`.",
+              "privacy": "public"
+            },
+            {
+              "kind": "field",
+              "name": "showLabel",
+              "type": {
+                "text": "undefined | false | true"
+              },
+              "description": "Also render `label` visibly beside the icon. Defaults to `false`, which is the icon-only button. When the text is visible it IS the accessible name, so nothing gets announced twice.",
+              "privacy": "public"
             }
           ],
           "attributes": [
@@ -10459,6 +11286,22 @@
                 "text": "undefined | \"sm\" | \"md\" | \"lg\" | \"icon\" | \"icon-sm\""
               },
               "description": "Button size token. Defaults to `'icon'` (square)."
+            },
+            {
+              "name": "label",
+              "fieldName": "label",
+              "type": {
+                "text": "undefined | string"
+              },
+              "description": "The button's accessible name. It is announced whether or not the label is visible, so the text is always localisable. Defaults to `'Scroll to bottom'`."
+            },
+            {
+              "name": "show-label",
+              "fieldName": "showLabel",
+              "type": {
+                "text": "undefined | false | true"
+              },
+              "description": "Also render `label` visibly beside the icon. Defaults to `false`, which is the icon-only button. When the text is visible it IS the accessible name, so nothing gets announced twice."
             }
           ],
           "events": [
@@ -10761,8 +11604,8 @@
         {
           "kind": "class",
           "customElement": true,
-          "tagName": "kai-separator",
-          "name": "KaiSeparatorElement",
+          "tagName": "kai-select",
+          "name": "KaiSelectElement",
           "description": "",
           "members": [
             {
@@ -10776,81 +11619,280 @@
             },
             {
               "kind": "field",
-              "name": "orientation",
+              "name": "options",
               "type": {
-                "text": "undefined | \"horizontal\" | \"vertical\""
+                "text": "{ value: string; label?: undefined | string; disabled?: undefined | false | true }[]"
               },
-              "description": "`horizontal` (default, block + full-width) or `vertical` (a rule inside a flex/grid row, stretching to the row height).",
+              "description": "The choices, in display order. Set as a JS PROPERTY (array), never an attribute. Rendered in full: the kit never truncates, re-orders or de-duplicates them.",
               "privacy": "public"
-            }
-          ],
-          "attributes": [
+            },
             {
-              "name": "theme",
-              "fieldName": "theme",
+              "kind": "field",
+              "name": "value",
               "type": {
-                "text": "\"light\" | \"dark\" | \"auto\""
+                "text": "undefined | string"
               },
-              "description": "Color mode (`auto` follows prefers-color-scheme)."
+              "description": "Controlled selected value. Settable and reflected to the `value` attribute. `el.value = 'high'` drives it; choosing an option updates it and fires `kai-change`. Read `el.value` for live state; for a `multiple` select read `el.values` instead.",
+              "privacy": "public"
             },
             {
-              "name": "orientation",
-              "fieldName": "orientation",
+              "kind": "field",
+              "name": "placeholder",
               "type": {
-                "text": "undefined | \"horizontal\" | \"vertical\""
+                "text": "undefined | string"
               },
-              "description": "`horizontal` (default, block + full-width) or `vertical` (a rule inside a flex/grid row, stretching to the row height)."
-            }
-          ],
-          "events": [],
-          "cssProperties": [],
-          "cssParts": [
-            {
-              "name": "separator",
-              "description": "The divider line. Restyle its color, thickness, or inset from outside.",
-              "recipe": "kai-separator::part(separator) { background: var(--color-border) }"
-            }
-          ]
-        },
-        {
-          "kind": "class",
-          "customElement": true,
-          "tagName": "kai-setting-item",
-          "name": "KaiSettingItemElement",
-          "description": "",
-          "members": [
+              "description": "Text for a leading, disabled, empty option: the \"nothing chosen yet\" row. Omitted means no such row at all; there is no default wording, because inventing one would put words in your UI.",
+              "privacy": "public"
+            },
             {
               "kind": "field",
-              "name": "theme",
+              "name": "multiple",
               "type": {
-                "text": "\"light\" | \"dark\" | \"auto\""
+                "text": "undefined | false | true"
               },
-              "description": "Color mode (`auto` follows prefers-color-scheme).",
+              "description": "Allow more than one selection. Turns the control into the platform's list box, so the kit's chevron is not drawn.",
               "privacy": "public"
             },
             {
               "kind": "field",
-              "name": "label",
+              "name": "invalid",
               "type": {
-                "text": "undefined | string"
+                "text": "undefined | false | true"
               },
-              "description": "Row label (primary text). Attribute: `label`.",
+              "description": "Force the invalid (destructive-border) state.",
               "privacy": "public"
             },
             {
               "kind": "field",
-              "name": "description",
+              "name": "disabled",
               "type": {
-                "text": "undefined | string"
+                "text": "undefined | false | true"
               },
-              "description": "Optional secondary description under the label. Attribute: `description`.",
+              "description": "Disable interaction.",
               "privacy": "public"
-            }
-          ],
-          "attributes": [
+            },
             {
-              "name": "theme",
-              "fieldName": "theme",
+              "kind": "field",
+              "name": "required",
+              "type": {
+                "text": "undefined | false | true"
+              },
+              "description": "Set the native `required` attribute, and nothing more. Whether an empty select is an error is the application's rule, not the kit's.",
+              "privacy": "public"
+            },
+            {
+              "kind": "field",
+              "name": "label",
+              "type": {
+                "text": "undefined | string"
+              },
+              "description": "Accessible label for the control.",
+              "privacy": "public"
+            },
+            {
+              "kind": "field",
+              "name": "name",
+              "type": {
+                "text": "undefined | string"
+              },
+              "description": "Form-control name, for a native form submit.",
+              "privacy": "public"
+            },
+            {
+              "kind": "method",
+              "name": "focus",
+              "parameters": [
+                {
+                  "name": "options?: FocusOptions"
+                }
+              ],
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              },
+              "description": "Focus the inner select (the host element can't reach it).",
+              "privacy": "public"
+            }
+          ],
+          "attributes": [
+            {
+              "name": "theme",
+              "fieldName": "theme",
+              "type": {
+                "text": "\"light\" | \"dark\" | \"auto\""
+              },
+              "description": "Color mode (`auto` follows prefers-color-scheme)."
+            },
+            {
+              "name": "value",
+              "fieldName": "value",
+              "type": {
+                "text": "undefined | string"
+              },
+              "description": "Controlled selected value. Settable and reflected to the `value` attribute. `el.value = 'high'` drives it; choosing an option updates it and fires `kai-change`. Read `el.value` for live state; for a `multiple` select read `el.values` instead."
+            },
+            {
+              "name": "placeholder",
+              "fieldName": "placeholder",
+              "type": {
+                "text": "undefined | string"
+              },
+              "description": "Text for a leading, disabled, empty option: the \"nothing chosen yet\" row. Omitted means no such row at all; there is no default wording, because inventing one would put words in your UI."
+            },
+            {
+              "name": "multiple",
+              "fieldName": "multiple",
+              "type": {
+                "text": "undefined | false | true"
+              },
+              "description": "Allow more than one selection. Turns the control into the platform's list box, so the kit's chevron is not drawn."
+            },
+            {
+              "name": "invalid",
+              "fieldName": "invalid",
+              "type": {
+                "text": "undefined | false | true"
+              },
+              "description": "Force the invalid (destructive-border) state."
+            },
+            {
+              "name": "disabled",
+              "fieldName": "disabled",
+              "type": {
+                "text": "undefined | false | true"
+              },
+              "description": "Disable interaction."
+            },
+            {
+              "name": "required",
+              "fieldName": "required",
+              "type": {
+                "text": "undefined | false | true"
+              },
+              "description": "Set the native `required` attribute, and nothing more. Whether an empty select is an error is the application's rule, not the kit's."
+            },
+            {
+              "name": "label",
+              "fieldName": "label",
+              "type": {
+                "text": "undefined | string"
+              },
+              "description": "Accessible label for the control."
+            },
+            {
+              "name": "name",
+              "fieldName": "name",
+              "type": {
+                "text": "undefined | string"
+              },
+              "description": "Form-control name, for a native form submit."
+            }
+          ],
+          "events": [
+            {
+              "name": "kai-change",
+              "type": {
+                "text": "CustomEvent<{ value: string; values: string[] }>"
+              },
+              "description": "A choice was made. `value` is the first selected option (empty when nothing is selected); `values` is every selected option, which is what a `multiple` select needs. Both are always present, so neither shape silently loses the other."
+            }
+          ],
+          "cssProperties": []
+        },
+        {
+          "kind": "class",
+          "customElement": true,
+          "tagName": "kai-separator",
+          "name": "KaiSeparatorElement",
+          "description": "",
+          "members": [
+            {
+              "kind": "field",
+              "name": "theme",
+              "type": {
+                "text": "\"light\" | \"dark\" | \"auto\""
+              },
+              "description": "Color mode (`auto` follows prefers-color-scheme).",
+              "privacy": "public"
+            },
+            {
+              "kind": "field",
+              "name": "orientation",
+              "type": {
+                "text": "undefined | \"horizontal\" | \"vertical\""
+              },
+              "description": "`horizontal` (default, block + full-width) or `vertical` (a rule inside a flex/grid row, stretching to the row height).",
+              "privacy": "public"
+            }
+          ],
+          "attributes": [
+            {
+              "name": "theme",
+              "fieldName": "theme",
+              "type": {
+                "text": "\"light\" | \"dark\" | \"auto\""
+              },
+              "description": "Color mode (`auto` follows prefers-color-scheme)."
+            },
+            {
+              "name": "orientation",
+              "fieldName": "orientation",
+              "type": {
+                "text": "undefined | \"horizontal\" | \"vertical\""
+              },
+              "description": "`horizontal` (default, block + full-width) or `vertical` (a rule inside a flex/grid row, stretching to the row height)."
+            }
+          ],
+          "events": [],
+          "cssProperties": [],
+          "cssParts": [
+            {
+              "name": "separator",
+              "description": "The divider line. Restyle its color, thickness, or inset from outside.",
+              "recipe": "kai-separator::part(separator) { background: var(--color-border) }"
+            }
+          ]
+        },
+        {
+          "kind": "class",
+          "customElement": true,
+          "tagName": "kai-setting-item",
+          "name": "KaiSettingItemElement",
+          "description": "",
+          "members": [
+            {
+              "kind": "field",
+              "name": "theme",
+              "type": {
+                "text": "\"light\" | \"dark\" | \"auto\""
+              },
+              "description": "Color mode (`auto` follows prefers-color-scheme).",
+              "privacy": "public"
+            },
+            {
+              "kind": "field",
+              "name": "label",
+              "type": {
+                "text": "undefined | string"
+              },
+              "description": "Row label (primary text). Attribute: `label`.",
+              "privacy": "public"
+            },
+            {
+              "kind": "field",
+              "name": "description",
+              "type": {
+                "text": "undefined | string"
+              },
+              "description": "Optional secondary description under the label. Attribute: `description`.",
+              "privacy": "public"
+            }
+          ],
+          "attributes": [
+            {
+              "name": "theme",
+              "fieldName": "theme",
               "type": {
                 "text": "\"light\" | \"dark\" | \"auto\""
               },
@@ -11131,6 +12173,195 @@
             }
           ]
         },
+        {
+          "kind": "class",
+          "customElement": true,
+          "tagName": "kai-slider",
+          "name": "KaiSliderElement",
+          "description": "",
+          "members": [
+            {
+              "kind": "field",
+              "name": "theme",
+              "type": {
+                "text": "\"light\" | \"dark\" | \"auto\""
+              },
+              "description": "Color mode (`auto` follows prefers-color-scheme).",
+              "privacy": "public"
+            },
+            {
+              "kind": "field",
+              "name": "min",
+              "type": {
+                "text": "undefined | number"
+              },
+              "description": "Lowest selectable value. Required: a range with no bounds is a guess, and the guess belongs to whoever knows what the number means.",
+              "privacy": "public"
+            },
+            {
+              "kind": "field",
+              "name": "max",
+              "type": {
+                "text": "undefined | number"
+              },
+              "description": "Highest selectable value. Required, for the same reason as `min`.",
+              "privacy": "public"
+            },
+            {
+              "kind": "field",
+              "name": "step",
+              "type": {
+                "text": "undefined | number | \"any\""
+              },
+              "description": "Granularity. Omitted means the native default of 1; `any` means continuous.",
+              "privacy": "public"
+            },
+            {
+              "kind": "field",
+              "name": "value",
+              "type": {
+                "text": "undefined | number"
+              },
+              "description": "Controlled value. Settable and reflected to the `value` attribute. `el.value = 40` drives it; dragging updates it and fires `kai-input` per step, `kai-change` on release. Read `el.value` for live state.",
+              "privacy": "public"
+            },
+            {
+              "kind": "field",
+              "name": "disabled",
+              "type": {
+                "text": "undefined | false | true"
+              },
+              "description": "Disable interaction.",
+              "privacy": "public"
+            },
+            {
+              "kind": "field",
+              "name": "label",
+              "type": {
+                "text": "undefined | string"
+              },
+              "description": "Accessible label for the slider.",
+              "privacy": "public"
+            },
+            {
+              "kind": "field",
+              "name": "name",
+              "type": {
+                "text": "undefined | string"
+              },
+              "description": "Form-control name, for a native form submit.",
+              "privacy": "public"
+            },
+            {
+              "kind": "field",
+              "name": "valueLabel",
+              "type": {
+                "text": "undefined | false | true | ((value: number) => string)"
+              },
+              "description": "Show the current value beside the track. Off by default. Two ways in, because one of them is not a scalar. As a bare ATTRIBUTE (`<kai-slider value-label>`) it renders the raw number. As a JS PROPERTY it also accepts a formatter function (`el.valueLabel = (v) => v + '%'`), for a slider that is not counting bare numbers. A function cannot survive an attribute, so that half is property-only. The readout is hidden from assistive tech: the slider already reports the same number, and an exposed copy would be announced twice.",
+              "privacy": "public"
+            },
+            {
+              "kind": "method",
+              "name": "focus",
+              "parameters": [
+                {
+                  "name": "options?: FocusOptions"
+                }
+              ],
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              },
+              "description": "Focus the inner range input (the host element can't reach it).",
+              "privacy": "public"
+            }
+          ],
+          "attributes": [
+            {
+              "name": "theme",
+              "fieldName": "theme",
+              "type": {
+                "text": "\"light\" | \"dark\" | \"auto\""
+              },
+              "description": "Color mode (`auto` follows prefers-color-scheme)."
+            },
+            {
+              "name": "min",
+              "fieldName": "min",
+              "type": {
+                "text": "undefined | number"
+              },
+              "description": "Lowest selectable value. Required: a range with no bounds is a guess, and the guess belongs to whoever knows what the number means."
+            },
+            {
+              "name": "max",
+              "fieldName": "max",
+              "type": {
+                "text": "undefined | number"
+              },
+              "description": "Highest selectable value. Required, for the same reason as `min`."
+            },
+            {
+              "name": "step",
+              "fieldName": "step",
+              "type": {
+                "text": "undefined | number | \"any\""
+              },
+              "description": "Granularity. Omitted means the native default of 1; `any` means continuous."
+            },
+            {
+              "name": "value",
+              "fieldName": "value",
+              "type": {
+                "text": "undefined | number"
+              },
+              "description": "Controlled value. Settable and reflected to the `value` attribute. `el.value = 40` drives it; dragging updates it and fires `kai-input` per step, `kai-change` on release. Read `el.value` for live state."
+            },
+            {
+              "name": "disabled",
+              "fieldName": "disabled",
+              "type": {
+                "text": "undefined | false | true"
+              },
+              "description": "Disable interaction."
+            },
+            {
+              "name": "label",
+              "fieldName": "label",
+              "type": {
+                "text": "undefined | string"
+              },
+              "description": "Accessible label for the slider."
+            },
+            {
+              "name": "name",
+              "fieldName": "name",
+              "type": {
+                "text": "undefined | string"
+              },
+              "description": "Form-control name, for a native form submit."
+            }
+          ],
+          "events": [
+            {
+              "name": "kai-change",
+              "type": {
+                "text": "CustomEvent<{ value: number }>"
+              },
+              "description": "The value was committed: pointer released, or a key press finished."
+            },
+            {
+              "name": "kai-input",
+              "type": {
+                "text": "CustomEvent<{ value: number }>"
+              },
+              "description": "The thumb moved. Fires per step during a drag or a key press."
+            }
+          ],
+          "cssProperties": []
+        },
         {
           "kind": "class",
           "customElement": true,
@@ -12571,7 +13802,7 @@
               "type": {
                 "text": "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 }[]"
               },
-              "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.",
+              "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. Note the handover: the first `toast()` call ADOPTS a region you placed in markup (no second region mounts) and binds the imperative store to this property, replacing any array you set. Drive a region as data OR via `toast()`, not both at once.",
               "privacy": "public"
             },
             {
@@ -13057,7 +14288,7 @@
               "kind": "field",
               "name": "transcribe",
               "type": {
-                "text": "undefined | (audio: Blob) => Promise<string>"
+                "text": "undefined | ((audio: Blob) => Promise<string>)"
               },
               "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.",
               "privacy": "public"
@@ -13223,7 +14454,7 @@
               "kind": "field",
               "name": "synthesize",
               "type": {
-                "text": "undefined | (text: string) => Promise<Blob>"
+                "text": "undefined | ((text: string) => Promise<Blob>)"
               },
               "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.",
               "privacy": "public"