@kitn.ai/ui 0.20.0 → 0.21.0

package/src/elements/element-types.d.ts

@@ -1,14 +1,44 @@
 // AUTO-GENERATED by scripts/gen-element-api.mjs — do not edit by hand.
 // Typed custom-element interfaces + HTMLElementTagNameMap augmentation, so
 // `document.querySelector('kai-message')` is typed and gets prop autocomplete.
-
-
-// Re-exports for `import { … } from '@kitn.ai/ui/elements'`.
-export type { ChatMessage, ChatMessageAction } from './chat-types';
+// Also augments React's JSX.IntrinsicElements (see below) so a raw <kai-chat>
+// written directly in TSX type-checks.
+
+
+// Local bindings for the two names the DECLARATIONS below reference
+// (`configureCodeHighlighting(options: CodeHighlightingOptions)`, `classifyTool(): ToolKind`).
+// `export type { X } from '…'` re-exports X without binding it in this file's scope,
+// so without these imports both signatures are TS2304 — invisible under
+// `skipLibCheck: true`, which is exactly why this file is now compiled with it off
+// (tests/elements/element-types-lib-check.test.ts).
+import type { CodeHighlightingOptions } from '../primitives/highlighter';
+import type { ToolKind } from '../components/tool-classify';
+
+// Re-exports for `import { … } from '@kitn.ai/ui/elements'`. Mirrors the names the
+// shipped dist/elements.d.ts inlines, so both copies expose the same surface.
+export type {
+  AvatarData,
+  ChatMessage,
+  ChatMessageAction,
+  CustomAction,
+  FeedbackVote,
+  MessagePart,
+  MessageSource,
+  RawOrigin,
+} from './chat-types';
+export type { ToolPart } from '../components/tool-types';
+export type { ToolKind } from '../components/tool-classify';
+export type { AttachmentData } from '../components/attachment-types';
+export type { CardEnvelope, CardResolution } from '../primitives/card-contract';
 export type { CodeHighlightingOptions } from '../primitives/highlighter';
 export declare function configureCodeHighlighting(options: CodeHighlightingOptions): void;
 export declare function isCodeHighlightingEnabled(): boolean;
 
+/** Classify a tool call by its provider-chosen NAME. Total, deterministic and
+ *  side-effect free; ALWAYS terminates in `'generic'`. Named by ToolPart.kind's
+ *  doc comment, so it must stay reachable from this entry. */
+export declare function classifyTool(name: string): ToolKind;
+
 /** Resolves once the kai-* elements are registered (browser); inert on the server. */
 export declare const elementsReady: Promise<unknown>;
 
@@ -95,29 +125,29 @@ export declare function configureToasts(config: ToastConfig): void;
 
 export interface KaiAgentCardElement extends HTMLElement {
   /** Color mode (`auto` follows prefers-color-scheme). */
-  theme?: 'light' | 'dark' | 'auto';
-  /** The agent's name — the primary label. Attribute: `name`. */
+  theme?: "light" | "dark" | "auto";
+  /** The agent's name, the primary label. Attribute: `name`. */
   name?: string;
   /** Selected / focused state: highlighted border + surface. Attribute: `active`. */
   active?: boolean;
-  /** Raise a prominent "Needs you" pill plus a glowing amber edge — the attention-routing signal that pulls focus to this agent. Attribute: `needs-attention`. */
+  /** Raise a prominent "Needs you" pill plus a glowing amber edge. This is the attention-routing signal that pulls focus to this agent. Attribute: `needs-attention`. */
   needsAttention?: boolean;
-  /** Run status — a JS PROPERTY (object), not an attribute. Shape: `{ tone, label?, pulse? }`, where `tone` is one of `working` | `idle` | `done` | `error` | `blocked` (maps to the kit's tool hues), `label` is an optional short string beside the dot, and `pulse` animates the dot. Set it with `el.status = { tone: 'working', label: 'Working', pulse: true }`. */
+  /** Run status. A JS PROPERTY (object), not an attribute. Shape: `{ tone, label?, pulse? }`, where `tone` is one of `working` | `idle` | `done` | `error` | `blocked` (maps to the kit's tool hues), `label` is an optional short string beside the dot, and `pulse` animates the dot. Set it with `el.status = { tone: 'working', label: 'Working', pulse: true }`. */
   status?: { tone: "working" | "idle" | "done" | "error" | "blocked"; label?: string; pulse?: boolean };
 }
 
 export interface KaiArtifactElement extends HTMLElement {
   /** Color mode (`auto` follows prefers-color-scheme). */
-  theme?: 'light' | 'dark' | 'auto';
+  theme?: "light" | "dark" | "auto";
   /** URL the preview iframe frames. Consumer-controlled. */
   src?: string;
-  /** Files for the Code tab tree + each file's preview `url`. Set as a JS property (array). */
-  files: { path: string; url?: undefined | string; code?: undefined | string; language?: undefined | string; type?: undefined | "html" | "pdf" | "image" | "other"; additions?: undefined | number; deletions?: undefined | number; status?: undefined | "added" | "modified" | "deleted" | "renamed" | "untracked" }[];
+  /** Files for the Code tab tree + each file's preview `url`. Omit for a preview-only artifact (the Code tab then has nothing to show; pair it with `no-tabs` to hide the toggle). Set as a JS property (array). */
+  files: { path: string; url?: string; code?: string; language?: string; type?: "html" | "pdf" | "image" | "other"; additions?: number; deletions?: number; status?: "added" | "modified" | "deleted" | "renamed" | "untracked" }[];
   /** Controlled active tab: `preview` or `code`. When set, the artifact follows it (re-asserted on change). Leave unset for an uncontrolled tab (see `defaultTab`). */
   tab?: "preview" | "code";
   /** Uncontrolled INITIAL tab (used only when `tab` is unset). Default `preview`. Seeds the starting tab; the user can then switch freely without the consumer re-asserting a controlled `tab`. */
   defaultTab?: "preview" | "code";
-  /** Selected file path — syncs the tree highlight, Code source, and preview. */
+  /** Selected file path. Syncs the tree highlight, Code source, and preview. */
   activeFile?: string;
   /** iframe `sandbox` override. Secure default `allow-scripts allow-forms` (NOT `allow-same-origin`). */
   sandbox?: string;
@@ -145,13 +175,31 @@ export interface KaiArtifactElement extends HTMLElement {
   readonlyPath?: boolean;
   /** Friendly address shown in the path field instead of the real current url (read-only, non-navigable). Use when the framed url is not consumer-facing (e.g. a `data:` blob) so a clean address shows instead of leaking it. Scalar string: set as the `display-url` attribute or the `displayUrl` property. */
   displayUrl?: string;
+  /** Go back in the artifact's own history stack (no-op when there's no prior entry). */
+  back(): void;
+  /** Go forward in the history stack (no-op when there's no forward entry). */
+  forward(): void;
+  /** Force-reload the current preview url (also re-renders an inline PDF). */
+  reload(): void;
+  /** Navigate to the `src` home url (no-op when there's no `src`). */
+  home(): void;
+  /** Push + load a url in the preview, the path-field submit path (fires kai-navigate). */
+  navigate(url: string): void;
+  /** Select a file by path: highlights the tree, shows its source, navigates the preview (fires kai-file-select + kai-navigate). Named selectFile to avoid the `activeFile` prop. */
+  selectFile(path: string): void;
+  /** Open the current url in a new browser tab (no-op when there's no concrete url). Named openExternal, NOT openInTab, which is a prop (toolbar button visibility). */
+  openExternal(): void;
+  /** Enter the maximized view-state (fires kai-maximize-change{maximized:true}). Named maximize, NOT maximized, which is a prop. */
+  maximize(): void;
+  /** Exit the maximized view-state (fires kai-maximize-change{maximized:false}). */
+  restore(): void;
 }
 
 export interface KaiAttachmentsElement extends HTMLElement {
   /** Color mode (`auto` follows prefers-color-scheme). */
-  theme?: 'light' | 'dark' | 'auto';
-  /** The attachments to render. Set as a JS property (array). */
-  items: { id: string; type: "file" | "source-document"; filename?: undefined | string; mediaType?: undefined | string; url?: undefined | string; title?: undefined | string }[];
+  theme?: "light" | "dark" | "auto";
+  /** 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). */
+  items: { id: string; type: "file" | "source-document"; filename?: string; mediaType?: string; url?: string; title?: string }[];
   /** Layout: `grid` = visual tiles, `inline` = icon + label chips, `list` = rows. */
   variant?: "grid" | "inline" | "list";
   /** Wrap each item in a hover card that previews its details. */
@@ -166,7 +214,7 @@ export interface KaiAttachmentsElement extends HTMLElement {
 
 export interface KaiAudioVisualizerElement extends HTMLElement {
   /** Color mode (`auto` follows prefers-color-scheme). */
-  theme?: 'light' | 'dark' | 'auto';
+  theme?: "light" | "dark" | "auto";
   /** Look to render: `bar` (default), `grid`, `radial`, `wave`, `aurora`, `custom`. `aura` is accepted as a LiveKit-markup alias for `aurora`. Attribute: `variant`. */
   variant?: string;
   /** `idle` (default), `connecting`, `listening`, `thinking`, `speaking`, `disconnected` (connection down: the dead, flat look). LiveKit's room-lifecycle state names are accepted as aliases. Attribute: `state`. */
@@ -203,12 +251,12 @@ export interface KaiAudioVisualizerElement extends HTMLElement {
 
 export interface KaiAvatarElement extends HTMLElement {
   /** Color mode (`auto` follows prefers-color-scheme). */
-  theme?: 'light' | 'dark' | 'auto';
+  theme?: "light" | "dark" | "auto";
   /** Image URL/data-URI. When absent, the `fallback` initials show instead. */
   src?: string;
   /** Alt text for the image. Defaults to `fallback`. */
   alt?: string;
-  /** Short text shown when there's no image — usually initials (e.g. "JD", "AI"). */
+  /** Short text shown when there's no image, usually initials (e.g. "JD", "AI"). */
   fallback?: string;
   /** Size token: `sm` | `md` (default) | `lg`. */
   size?: "sm" | "md" | "lg";
@@ -216,15 +264,15 @@ export interface KaiAvatarElement extends HTMLElement {
 
 export interface KaiBadgeElement extends HTMLElement {
   /** Color mode (`auto` follows prefers-color-scheme). */
-  theme?: 'light' | 'dark' | 'auto';
+  theme?: "light" | "dark" | "auto";
   /** `default` (muted pill) · `count` (compact number badge) · `citation` (filled primary, for inline citation markers). Defaults to `default`. */
   variant?: "default" | "count" | "citation";
 }
 
 export interface KaiButtonElement extends HTMLElement {
   /** Color mode (`auto` follows prefers-color-scheme). */
-  theme?: 'light' | 'dark' | 'auto';
-  /** Visual style. `default` (filled), `subtle` (muted text, hover tint — the toolbar icon look), `ghost` (transparent, hover fill), `outline`, or `destructive`. Defaults to `default`. */
+  theme?: "light" | "dark" | "auto";
+  /** Visual style. `default` (filled), `subtle` (muted text, hover tint, the toolbar icon look), `ghost` (transparent, hover fill), `outline`, or `destructive`. Defaults to `default`. */
   variant?: "default" | "subtle" | "ghost" | "outline" | "destructive";
   /** Size token. `icon` / `icon-sm` are square (for icon-only buttons); `sm` / `md` / `lg` size text buttons. Defaults to `md`. */
   size?: "sm" | "md" | "lg" | "icon" | "icon-sm";
@@ -236,20 +284,26 @@ export interface KaiButtonElement extends HTMLElement {
   label?: string;
   /** Disable the button (non-interactive, dimmed). */
   disabled?: boolean;
-  /** Stretch the button to the full width of its container (a block button) — e.g. a card CTA or a stacked action. Attribute: `full`. */
+  /** Stretch the button to the full width of its container (a block button), e.g. a card CTA or a stacked action. Attribute: `full`. */
   full?: boolean;
   /** Justify the button's content: `start`, `center` (default), or `end`. Combine with `full` for a full-width, left-aligned button. */
   align?: "start" | "center" | "end";
   /** Native button `type`. Defaults to `button` (so it never submits a form). */
   type?: "button" | "submit" | "reset";
+  /** Focus the inner `<button>` (host.focus() would focus the wrapper). */
+  focus(options?: FocusOptions): void;
+  /** Blur the inner `<button>`. */
+  blur(): void;
+  /** Programmatically activate the button. Runs the same path as a user click and fires kai-click. Forwarding to the inner button means `disabled` is respected automatically. */
+  click(): void;
 }
 
 export interface KaiCardElement extends HTMLElement {
   /** Color mode (`auto` follows prefers-color-scheme). */
-  theme?: 'light' | 'dark' | 'auto';
+  theme?: "light" | "dark" | "auto";
   /** Surface treatment: `outlined` (default) | `filled` | `plain` | `accent`. Attribute: `appearance`. */
   appearance?: "outlined" | "filled" | "plain" | "accent";
-  /** `vertical` (default, media on top) | `horizontal` (media at the start) | `responsive` (horizontal when the card's container is wide enough, else vertical — a container query on the card's own width). Attribute: `orientation`. */
+  /** `vertical` (default, media on top) | `horizontal` (media at the start) | `responsive` (horizontal when the card's container is wide enough, else vertical, via a container query on the card's own width). Attribute: `orientation`. */
   orientation?: "vertical" | "horizontal" | "responsive";
   /** The card width below which a `responsive` card collapses to vertical and the footer actions stack. A CSS length; default `28rem`. Attribute: `collapse`. */
   collapse?: string;
@@ -269,33 +323,49 @@ export interface KaiCardElement extends HTMLElement {
 
 export interface KaiCardsElement extends HTMLElement {
   /** Color mode (`auto` follows prefers-color-scheme). */
-  theme?: 'light' | 'dark' | 'auto';
+  theme?: "light" | "dark" | "auto";
   /** The stream of card envelopes to render. Set as a JS PROPERTY: `el.cards = [...]`. */
   cards?: { type: string; id: string; data: unknown; title?: string; resolution?: { kind: "action"; action: string; payload?: unknown; at?: string } | { kind: "submit"; data: unknown; at?: string } | { kind: "dismissed"; at?: string } | { kind: "expired"; reason?: string; at?: string } }[];
   /** Optional type→tag overrides/additions (merged over the built-ins). Property: `el.types`. Typed as a plain string map (not the `CardTagMap` alias) so the generated React wrapper inlines it instead of emitting an unresolved named type. */
   types?: Record<string, string>;
+  /** JSON Schemas for the card types this app renders, keyed by envelope type. The companion of `types`, which says what DRAWS a card while this says what a VALID one looks like. An OBJECT, so it is a JS property only: `el.schemas = { 'pricing-table': pricingSchema }`, never an attribute. `createCardRegistry(...).validationSchemas` is exactly this shape. Without it the kit validates its own seven built-ins and leaves your own card type, the one your app actually cares about, as the only unchecked thing on screen. A schema here WINS over a built-in of the same name, matching `mergeCardTags`, where your entry is spread over ours. Typed `Record<string, object>` rather than `Record<string, JsonSchema>` deliberately: an imported `.json` schema widens `"type"` to `string`, and an authored one carries `$schema`/`title`/`description`/`additionalProperties`, so the tighter type would reject both of the normal ways to supply one. See `CardSchemaMap` in components/card-renderer.tsx. */
+  schemas?: Record<string, object>;
   /** Optional CardPolicy handling child events. Property: `el.policy`. */
   policy?: { onSubmit?: (cardId: string, data: unknown) => void; onAction?: (cardId: string, action: string, payload?: unknown) => void; onSendPrompt?: (text: string, opts: { mode: "compose" | "send"; context?: unknown; }) => void; onOpen?: (url: string, target: "tab" | "artifact") => void; onState?: (cardId: string, patch: unknown) => void; onDismiss?: (cardId: string) => void; onReopen?: (cardId: string) => void; onError?: (cardId: string, message: string) => void; maxSendPromptMode?: "compose" | "send" };
+  /** Validate each envelope's `data` against the schema for its type before rendering it, using a built-in's own schema or yours from `schemas`. Default `true`; set `validate-cards="false"` (or `el.validateCards = false`) to opt out. A hard failure (wrong type, a missing required field) renders a diagnostic naming the field instead of the card; a soft failure (bounds) renders the card unchanged. Both emit a contract `error` event. On in production too: a model emitting a bad shape is a production failure mode, so stripping the check there would hide it from exactly the person who needs to see it. */
+  validateCards?: boolean;
+  /** Programmatically resolve a child card by id: set that envelope's `resolution` so the child re-renders into its read-only/resolved view. The imperative twin of the consumer mutating the cards array. No-op for an unknown id. */
+  resolve(cardId: string, resolution: { kind: "action"; action: string; payload?: unknown; at?: undefined | string } | { kind: "submit"; data: unknown; at?: undefined | string } | { kind: "dismissed"; at?: undefined | string } | { kind: "expired"; reason?: undefined | string; at?: undefined | string }): void;
+  /** Collapse a card to its re-openable stub from the host side. Convenience for `resolve(cardId, { kind: 'dismissed' })`. */
+  dismiss(cardId: string): void;
+  /** Return the live child element node for a card id (or null) so consumers can call that card's own methods (focus/expand/…) without a shadow-DOM query. */
+  getCard(cardId: string): HTMLElement | null;
 }
 
 export interface KaiChainOfThoughtElement extends HTMLElement {
   /** Color mode (`auto` follows prefers-color-scheme). */
-  theme?: 'light' | 'dark' | 'auto';
-  /** The reasoning steps. Set as a JS property. Compound sub-parts collapse to this one data model (Route 1). Each `{ label, content?, id? }`. */
-  steps: { label: string; content?: undefined | string; id?: undefined | string }[];
-  /** Open mode: `'multiple'` (default — any number of steps open at once) or `'single'` (at most one open; opening a step closes the others). */
+  theme?: "light" | "dark" | "auto";
+  /** The reasoning steps. Set as a JS property. Compound sub-parts collapse to this one data model (Route 1). Each `{ label, content?, id? }`. Omit to supply the steps as `<kai-step>` light-DOM children instead; when both are present the property's steps come first. */
+  steps: { label: string; content?: string; id?: string }[];
+  /** Open mode: `'multiple'` (default, any number of steps open at once) or `'single'` (at most one open; opening a step closes the others). */
   type?: "single" | "multiple";
   /** Controlled open step key(s). When set, it WINS over user interaction (the consumer owns the open set). String in `single` mode, string[] in `multiple` mode. Set as a JS property. */
   value?: string | string[];
-  /** Uncontrolled INITIAL open step key(s) — seeds which steps render expanded. Ignored once `value` is provided. Set as a JS property. */
+  /** Uncontrolled INITIAL open step key(s), seeding which steps render expanded. Ignored once `value` is provided. Set as a JS property. */
   defaultValue?: string | string[];
+  /** Open one step's detail by index, or ALL steps when called with no arg. In `single` mode opening one step closes the others (expand-all keeps the last). */
+  expand(index?: number): void;
+  /** Close one step's detail by index, or ALL steps when called with no arg. */
+  collapse(index?: number): void;
+  /** Flip one step's open state by index. */
+  toggle(index?: number): void;
 }
 
 export interface KaiChatElement extends HTMLElement {
   /** Color mode (`auto` follows prefers-color-scheme). */
-  theme?: 'light' | 'dark' | 'auto';
-  /** The full message thread to render, newest last. Each entry carries its role, content, and optional reasoning/tools/attachments/actions. Set as a JS property (`el.messages = [...]`). */
-  messages: { id: string; role: "user" | "assistant"; content: string; reasoning?: undefined | { text: string; label?: undefined | string }; tools?: undefined | { type: string; state: "input-streaming" | "input-available" | "output-available" | "output-error"; input?: undefined | Record<string, unknown>; output?: undefined | Record<string, unknown>; toolCallId?: undefined | string; errorText?: undefined | string }[]; attachments?: undefined | { id: string; type: "file" | "source-document"; filename?: undefined | string; mediaType?: undefined | string; url?: undefined | string; title?: undefined | string }[]; actions?: undefined | ("copy" | "like" | "dislike" | "regenerate" | "edit" | { id: string; label: string; icon?: undefined | string; tooltip?: undefined | string })[]; avatar?: undefined | { src?: undefined | string; fallback?: undefined | string; alt?: undefined | string }; feedback?: undefined | "like" | "dislike" }[];
+  theme?: "light" | "dark" | "auto";
+  /** Show a Search (Globe) button in the input toolbar; fires a `search` event. */
+  search?: boolean;
   /** Value of the input. A **string** is controlled (the host owns the text and updates it on `kai-value-change`). A **ComposerDoc** is a one-time seed that pre-populates pills; the user then edits freely. Leave unset for uncontrolled. */
   value?: string | ({ type: "text"; text: string } | { type: "entity"; entity: { kind: string; id: string; label: string; icon?: string; promptText?: string; data?: Record<string, unknown> } })[];
   /** Placeholder text shown in the empty input. */
@@ -309,7 +379,7 @@ export interface KaiChatElement extends HTMLElement {
   /** Keep suggestions visible after the conversation starts. By default suggestions are conversation starters and hide once `messages` is non-empty; set this to keep them always shown. Default false. */
   persistSuggestions?: boolean;
   /** Body/prose font scale for rendered markdown (`'xs' | 'sm' | 'base' | 'lg'`). Defaults to `'sm'`. */
-  proseSize?: "sm" | "lg" | "xs" | "base";
+  proseSize?: "xs" | "sm" | "base" | "lg";
   /** Shiki theme name for syntax-highlighted code blocks (e.g. `'github-dark-dimmed'`). */
   codeTheme?: string;
   /** Enable Shiki syntax highlighting in code blocks. Turn off to render plain `<pre>` blocks (lighter, no highlighter load). Default true. */
@@ -324,69 +394,93 @@ export interface KaiChatElement extends HTMLElement {
   context?: { usedTokens: number; maxTokens: number; inputTokens?: number; outputTokens?: number; estimatedCost?: number };
   /** Show the scroll-to-bottom button inside the scroll area. Default true. */
   scrollButton?: boolean;
-  /** Whether the host has `slot="header-start"` content (left of the title) — set by the `<kai-chat>` facade so a custom control forces the header open. */
+  /** Whether the host has `slot="header-start"` content (left of the title). Set by the `<kai-chat>` facade so a custom control forces the header open. */
   headerStart?: boolean;
   /** Whether the host has `slot="header-end"` content (right of the controls). */
   headerEnd?: boolean;
-  /** REPLACE — full custom header in place of the built-in title/model/context bar. */
+  /** REPLACE: full custom header in place of the built-in title/model/context bar. */
   headerFull?: boolean;
-  /** INJECT — left sidebar column (e.g. a conversation list / your own nav). */
+  /** INJECT: left sidebar column (e.g. a conversation list / your own nav). */
   sidebar?: boolean;
-  /** REPLACE — custom zero-state rendered in the message area while the thread is empty (replaces the empty message list only; the composer and its suggestions still render). */
+  /** REPLACE: custom zero-state rendered in the message area while the thread is empty (replaces the empty message list only; the composer and its suggestions still render). */
   empty?: boolean;
-  /** REPLACE — full custom composer in place of the built-in prompt input. The projected content wires its own submit (the data-flow boundary). */
+  /** REPLACE: full custom composer in place of the built-in prompt input. The projected content wires its own submit (the data-flow boundary). */
   composer?: boolean;
-  /** INJECT — accessory row just above the composer (e.g. extra actions). */
+  /** INJECT: accessory row just above the composer (e.g. extra actions). */
   composerActions?: boolean;
-  /** INJECT — footer row below the composer (disclaimers, token meter, …). */
+  /** INJECT: footer row below the composer (disclaimers, token meter, …). */
   footer?: boolean;
-  /** Show a Search (Globe) button in the input toolbar; fires a `search` event. */
-  search?: boolean;
   /** Show a Voice (Mic) button in the input toolbar; fires a `voice` event. */
   voice?: boolean;
-  /** Rich entity triggers — each `{ char, kind, items }` opens a caret-anchored menu that inserts an atomic pill (`/` skills, `@` agents/plugins). Set as a JS property; forwarded to the input. */
+  /** Rich entity triggers. Each `{ char, kind, items }` opens a caret-anchored menu that inserts an atomic pill (`/` skills, `@` agents/plugins). Set as a JS property; forwarded to the input. */
   triggers?: { char: string; kind: string; items?: { id: string; label: string; icon?: string; description?: string; group?: string; kind?: string; promptText?: string; data?: Record<string, unknown> }[] }[];
   /** Default icon per entity kind (kind → image src) for pills/menu items. */
   kindIcons?: Record<string, string>;
   /** Whether each message's action bar is always visible (`'always'`, default) or only revealed on hover of that message row (`'hover'`). */
   actionsReveal?: "always" | "hover";
+  /** The full message thread to render, newest last. Each entry carries its role, ordered `parts`, and optional actions/avatar/feedback. Set as a JS property (`el.messages = [...]`); a NEW array reference per streaming chunk re-renders (mutating in place does not). Omit for an empty thread. Re-declared here (rather than inherited from `ChatThreadProps`) because the ELEMENT registers a `[]` default and renders the empty state without it, while the SolidJS `<ChatThread>` component still requires it. The facade hands it a validated array either way. Matches `<kai-thread>`. */
+  messages: { id: string; role: "user" | "assistant"; parts: ({ type: "text"; text: string; raw?: { source: string; payload: unknown } } | { type: "reasoning"; text: string; label?: string; index?: number; streamId?: string; signature?: string; raw?: { source: string; payload: unknown } } | { type: "tool"; tool: { type: string; kind?: "command" | "file-change" | "search" | "fetch" | "mcp" | "image" | "generic"; state: "input-streaming" | "input-available" | "output-available" | "output-error"; input?: Record<string, unknown>; rawInput?: string; output?: Record<string, unknown>; toolCallId?: string; errorText?: string; raw?: { source: string; payload: unknown } }; raw?: { source: string; payload: unknown } } | { type: "card"; envelope: { type: string; id: string; data: unknown; title?: string; resolution?: { kind: "action"; action: string; payload?: unknown; at?: string } | { kind: "submit"; data: unknown; at?: string } | { kind: "dismissed"; at?: string } | { kind: "expired"; reason?: string; at?: string } }; raw?: { source: string; payload: unknown } } | { type: "source"; source: { id?: string; url?: string; title?: string; snippet?: string; index?: number }; raw?: { source: string; payload: unknown } } | { type: "file"; attachment: { id: string; type: "file" | "source-document"; filename?: string; mediaType?: string; url?: string; title?: string }; raw?: { source: string; payload: unknown } })[]; actions?: ("copy" | "like" | "dislike" | "regenerate" | "edit" | { id: string; label: string; icon?: string; tooltip?: string })[]; avatar?: { src?: string; fallback?: string; alt?: string }; feedback?: "like" | "dislike" }[];
+  /** Optional card type -> custom-element tag overrides/additions for `card` parts (merged over the built-ins). Property: `el.cardTypes`. Typed as a plain string map (not the `CardTagMap` alias) so the generated React wrapper inlines it instead of emitting an unresolved named type. */
+  cardTypes?: Record<string, string>;
+  /** 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. */
+  cardSchemas?: Record<string, object>;
+  /** Focus the composer, meaning the contenteditable (or textarea) inside the shadow root. A native `focus()` on the host lands on the host itself and never reaches it, so this is the only way to focus the input programmatically. */
+  focus(options?: FocusOptions): void;
+  /** Blur whatever currently holds focus inside the shadow root. The companion to `focus()`, for the same reason: a native `blur()` on the host misses the real focus target. */
+  blur(): void;
+  /** Empty the COMPOSER: drops the draft text and every staged attachment, then fires `kai-value-change` with `''`. It does NOT touch the thread. `messages` is the consumer's own state, so clearing history stays the consumer's call. */
+  clear(): void;
+  /** Submit whatever the composer currently holds, on the same path as Enter or the send button: fires `kai-submit` with that value plus the staged attachments, then drops the attachments. It takes no argument, so to send text the user never typed, set `el.value` first. There is no empty-check, so an empty composer still fires. The draft is cleared afterwards only when `value` is uncontrolled; a controlled host owns its value and clears it itself. Named `send`, not `submit`, to match the shared vocabulary. */
+  send(): void;
+  /** Scroll the message viewport to the newest message. Defaults to `'smooth'`; pass `'instant'` to jump without animating. */
+  scrollToBottom(behavior?: "auto" | "instant" | "smooth"): void;
 }
 
 export interface KaiCheckpointElement extends HTMLElement {
   /** Color mode (`auto` follows prefers-color-scheme). */
-  theme?: 'light' | 'dark' | 'auto';
+  theme?: "light" | "dark" | "auto";
   /** Optional text beside the icon. */
   label?: string;
   /** Tooltip on hover. */
   tooltip?: string;
   /** Visual button style. */
-  variant?: "default" | "ghost" | "outline";
+  variant?: "ghost" | "default" | "outline";
   /** Button size (use an `icon*` size for an icon-only checkpoint). */
   size?: "sm" | "md" | "lg" | "icon" | "icon-sm";
 }
 
 export interface KaiChoiceElement extends HTMLElement {
   /** Color mode (`auto` follows prefers-color-scheme). */
-  theme?: 'light' | 'dark' | 'auto';
+  theme?: "light" | "dark" | "auto";
   /** 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. */
-  data?: Record<string, unknown>;
+  data?: { prompt?: string; options: { id: string; label: string; description?: string; media?: { image?: string; imageAlt?: string; icon?: string }; meta?: string; recommended?: boolean; disabled?: boolean; payload?: unknown }[]; allowOther?: boolean | { label?: string; placeholder?: string }; submitLabel?: string; dismissible?: boolean };
   /** Stable card id correlating every emitted CardEvent. Attribute: `card-id`. */
   cardId?: string;
   /** Heading rendered in the card chrome (= CardEnvelope.title). Attribute: `heading`. */
   heading?: string;
   /** Set when the user resolved this card; renders the read-only view. Property: `el.resolution = { kind:'action', action:'…' }`. */
   resolution?: Record<string, unknown>;
-  /** Controlled selection — the selected option id. When set, the consumer owns the current pick (RadioGroup `value`). Attribute: `value`. */
+  /** Controlled selection: the selected option id. When set, the consumer owns the current pick (RadioGroup `value`). Attribute: `value`. */
   value?: string;
   /** Option id to pre-select on mount (uncontrolled seed). Attribute: `default-value`. */
   defaultValue?: string;
   /** Disable the whole radiogroup + Submit (e.g. while the agent is busy). Attribute: `disabled`. */
   disabled?: boolean;
+  /** Focus the radiogroup roving tab stop (or the Other input when selected). */
+  focus(options?: FocusOptions): void;
+  /** Select an option by id locally: no emit, fires kai-value-change (same as a row click). Lets a consumer pre-highlight or drive selection externally. */
+  select(optionId: string): void;
+  /** Submit the current selection: emits the `action` verb on kai-card and resolves the card (single-shot). Named `send`, not `submit`, per the shared vocabulary. */
+  send(): void;
+  /** Trigger the dismiss path: emits `dismiss` on kai-card and optimistically collapses the card to its re-openable stub. */
+  dismiss(): void;
+  /** Re-open a dismissed card from its stub: emits `reopen` on kai-card. */
+  reopen(): void;
 }
 
 export interface KaiCoachmarkElement extends HTMLElement {
   /** Color mode (`auto` follows prefers-color-scheme). */
-  theme?: 'light' | 'dark' | 'auto';
+  theme?: "light" | "dark" | "auto";
   /** Drive/observe open state (Shoelace-style: settable + reflected to the `open` attribute; the element still self-manages). Set `el.open = true`, or `<kai-coachmark open>`; listen for `kai-open-change`. */
   open?: boolean;
   /** Initial open state on mount (uncontrolled seed). */
@@ -397,15 +491,21 @@ export interface KaiCoachmarkElement extends HTMLElement {
   badge?: string;
   /** Floating placement relative to the anchor (default `bottom`). */
   placement?: string;
-  /** Color tone: `primary` (default, theme accent), `info` (blue), `success` (green), `warning` (amber), or `error` (red) — reusing the kit's tool hues. */
-  tone?: "error" | "primary" | "info" | "success" | "warning";
+  /** Color tone: `primary` (default, theme accent), `info` (blue), `success` (green), `warning` (amber), or `error` (red), reusing the kit's tool hues. */
+  tone?: "primary" | "info" | "success" | "warning" | "error";
   /** Render the arrow that points at the anchor (default `true`). Set `arrow="false"` for a plain bubble with no pointer. */
   arrow?: boolean;
+  /** Open it programmatically (no-op while disabled). */
+  show(): void;
+  /** Close it programmatically. */
+  hide(): void;
+  /** Flip the open state (closes while disabled). */
+  toggle(): void;
 }
 
 export interface KaiCodeBlockElement extends HTMLElement {
   /** Color mode (`auto` follows prefers-color-scheme). */
-  theme?: 'light' | 'dark' | 'auto';
+  theme?: "light" | "dark" | "auto";
   /** The source code to render. */
   code: string;
   /** Language grammar (e.g. `js`, `python`). Defaults to `tsx`. */
@@ -415,43 +515,53 @@ export interface KaiCodeBlockElement extends HTMLElement {
   /** Disable syntax highlighting (renders plain text, no Shiki). */
   codeHighlight?: boolean;
   /** Code text sizing. */
-  proseSize?: "sm" | "lg" | "xs" | "base";
+  proseSize?: "xs" | "sm" | "base" | "lg";
 }
 
 export interface KaiCommandElement extends HTMLElement {
   /** Color mode (`auto` follows prefers-color-scheme). */
-  theme?: 'light' | 'dark' | 'auto';
-  /** Flat list of items. Set as a JS property — not an HTML attribute. */
+  theme?: "light" | "dark" | "auto";
+  /** Flat list of items. Set as a JS property, not an HTML attribute. */
   items?: { id: string; label: string; icon?: string; description?: string; shortcut?: string; group?: string }[];
   /** Placeholder text for the search input. */
   placeholder?: string;
   /** Label shown when no items match the current query. */
   emptyLabel?: string;
+  /** Focus the search combobox input inside the shadow root so the palette is type-ready on demand (Shadow-DOM autofocus is unreliable, so hosts call this after opening the palette). */
+  focus(options?: FocusOptions): void;
+  /** Blur the focused search input. */
+  blur(): void;
+  /** Reset the search query to empty, re-showing all items, and fire `kai-query-change` with `''`. Mirrors the Escape-key behavior. */
+  clear(): void;
 }
 
 export interface KaiCompareElement extends HTMLElement {
   /** Color mode (`auto` follows prefers-color-scheme). */
-  theme?: 'light' | 'dark' | 'auto';
+  theme?: "light" | "dark" | "auto";
   /** The compare definition (prompt + the two candidates). Set as a JS PROPERTY: `el.data = { prompt, candidates: [A, B], collapse? }`. Import `ResponseCompareData` from `@kitn.ai/ui` for the full shape. */
   data?: Record<string, unknown>;
   /** Stable id correlating every emitted event. Attribute: `compare-id`. */
   compareId?: string;
   /** Re-hydrate / control the user's pick. Set as a JS PROPERTY: `el.selection = { chosenId, rejectedIds }`. Renders the collapsed winner. */
   selection?: Record<string, unknown>;
-  /** Layout: `'auto'` (default — columns when wide, tabs when narrow, by CONTAINER width) | `'columns'` (side-by-side) | `'tabs'` (pills to switch). Attribute: `layout`. */
+  /** Layout: `'auto'` (default, columns when wide, tabs when narrow, by CONTAINER width) | `'columns'` (side-by-side) | `'tabs'` (pills to switch). Attribute: `layout`. */
   layout?: "auto" | "columns" | "tabs";
   /** Prose/text size for the rendered candidates. Attribute: `prose-size`. */
-  proseSize?: "sm" | "lg" | "xs" | "base";
+  proseSize?: "xs" | "sm" | "base" | "lg";
   /** Shiki theme for code blocks in the candidates. Attribute: `code-theme`. */
   codeTheme?: string;
   /** Whether code blocks are syntax-highlighted. Attribute: `code-highlight`. */
   codeHighlight?: boolean;
+  /** Programmatically commit a pick by candidate id, on the same path as the "Pick this" button: fires kai-compare-select and optimistically collapses (single-shot; inert while streaming or already resolved). `select` does NOT collide with the `selection` prop (distinct identifier). */
+  select(candidateId: string): void;
+  /** Focus the current roving tab stop (the focused candidate's "Pick this" radio) so a consumer can move keyboard focus into the radiogroup. */
+  focus(options?: FocusOptions): void;
 }
 
 export interface KaiComposerElement extends HTMLElement {
   /** Color mode (`auto` follows prefers-color-scheme). */
-  theme?: 'light' | 'dark' | 'auto';
-  /** Controlled value — string or a full ComposerDoc (set as JS property). */
+  theme?: "light" | "dark" | "auto";
+  /** Controlled value: a string or a full ComposerDoc (set as JS property). */
   value?: string | ({ type: "text"; text: string } | { type: "entity"; entity: { kind: string; id: string; label: string; icon?: string; promptText?: string; data?: Record<string, unknown> } })[];
   /** Placeholder text shown when the composer is empty. */
   placeholder?: string;
@@ -460,35 +570,53 @@ export interface KaiComposerElement extends HTMLElement {
   /** Show a loading/streaming state and block submit. */
   loading?: boolean;
   /** Maximum height in px before the content scrolls. Default 240. */
-  maxHeight?: string | number;
+  maxHeight?: number | string;
   /** Whether pressing Enter (without Shift) submits. Default true. */
   submitOnEnter?: boolean;
-  /** Trigger definitions — set as a JS property. */
+  /** Trigger definitions. Set as a JS property. */
   triggers?: { char: string; kind: string; items?: { id: string; label: string; icon?: string; description?: string; group?: string; kind?: string; promptText?: string; data?: Record<string, unknown> }[] }[];
-  /** Keyword highlight rules — set as a JS property. */
+  /** Keyword highlight rules. Set as a JS property. */
   highlights?: (string | { pattern: string; flags?: string; class?: string })[];
   /** Default icon per entity kind (kind → image URL/data-URI) for items without their own `icon`. Overrides the built-in agent/plugin glyphs. JS property. */
   kindIcons?: Record<string, string>;
+  /** Focus the editable element. `focus`/`blur` are NOT composed natively, so a host-level focus() can't reach the editable inside the shadow root. This is the only way to focus the composer programmatically. */
+  focus(options?: FocusOptions): void;
+  /** Blur the editable element. */
+  blur(): void;
+  /** Empty the composer to a blank doc (resets the internal value + history baseline; fires kai-value-change). */
+  clear(): void;
+  /** Submit the current content programmatically, on the same path as Enter (fires kai-submit). Named `send`, not `submit`, to match the shared vocabulary and avoid any submit collision. */
+  send(): void;
+  /** Insert an atomic entity pill (skill/agent/plugin) at the caret without typing a trigger (fires kai-entity-add). */
+  insertEntity(entity: { kind: string; id: string; label: string; icon?: undefined | string; promptText?: undefined | string; data?: undefined | Record<string, unknown> }): void;
 }
 
 export interface KaiConfirmElement extends HTMLElement {
   /** Color mode (`auto` follows prefers-color-scheme). */
-  theme?: 'light' | 'dark' | 'auto';
+  theme?: "light" | "dark" | "auto";
   /** The confirm definition (the CardEnvelope.data). Set as a JS PROPERTY: `el.data = { body, tone, actions:[…] }`. Import `ConfirmCardData` from `@kitn.ai/ui` for the full shape. */
-  data?: Record<string, unknown>;
+  data?: { heading?: string; body?: string; tone?: "default" | "warning" | "danger"; actions: { id: string; label: string; style?: "primary" | "default" | "destructive"; payload?: unknown; default?: boolean }[]; dismissible?: boolean };
   /** Stable card id correlating every emitted CardEvent. Attribute: `card-id`. */
   cardId?: string;
   /** Heading rendered in the card chrome (= CardEnvelope.title). Attribute: `heading`. */
   heading?: string;
-  /** Focus the default action on mount (off by default — no focus-stealing). Attribute: `autofocus`. */
-  autofocus?: boolean;
+  /** Focus the default action on mount (off by default, so nothing steals focus). Attribute: `autofocus`. Re-declares the DOM member `HTMLElement.autofocus`, so it is NOT optional here: an interface extending HTMLElement may only narrow it, and the element always carries a value for it. */
+  autofocus: boolean;
   /** Set when the user resolved this card; renders the read-only view. Property: `el.resolution = { kind:'action', action:'…' }`. */
   resolution?: Record<string, unknown>;
+  /** Focus the default action button (or the first action if none is default). The same target `autofocus` focuses on mount, but on demand. */
+  focus(options?: FocusOptions): void;
+  /** Activate an action by id: emits the `action` verb on kai-card and resolves the card (single-shot). With no id, invokes the default action. */
+  confirm(actionId?: string): void;
+  /** Trigger the dismiss path: emits `dismiss` on kai-card and optimistically collapses the card to its re-openable stub. */
+  dismiss(): void;
+  /** Re-open a dismissed card from its stub: emits `reopen` on kai-card. */
+  reopen(): void;
 }
 
 export interface KaiContextElement extends HTMLElement {
   /** Color mode (`auto` follows prefers-color-scheme). */
-  theme?: 'light' | 'dark' | 'auto';
+  theme?: "light" | "dark" | "auto";
   /** Token-usage data. Set as a JS property. */
   context?: { usedTokens: number; maxTokens: number; inputTokens?: number; outputTokens?: number; reasoningTokens?: number; cacheTokens?: number; estimatedCost?: number };
   /** Fraction (0–1) above which the meter turns yellow. Defaults to `0.7` (70%). */
@@ -499,32 +627,52 @@ export interface KaiContextElement extends HTMLElement {
 
 export interface KaiConversationsElement extends HTMLElement {
   /** Color mode (`auto` follows prefers-color-scheme). */
-  theme?: 'light' | 'dark' | 'auto';
-  /** Pre-bucketed conversation groups (e.g. "Today", "Yesterday"), each with its own conversations. Use this when you want to control the grouping/headers yourself; otherwise pass a flat `conversations` array. Set as a JS property. */
-  groups: { id: string; userId?: undefined | string; teamId?: undefined | string; name: string; sortOrder: number; createdAt: string }[];
-  /** A flat list of conversation summaries; the component buckets them by recency for you. Ignored when `groups` is provided. Set as a JS property. */
-  conversations: { id: string; title: string; groupId?: undefined | string; scope: { type: "document" | "collection"; documentId?: undefined | string; filters?: undefined | { tags?: undefined | string[]; authors?: undefined | string[]; contentType?: undefined | "transcript" | "markdown"; dateRange?: undefined | { from: string; to: string } } }; messageCount: number; lastMessageAt: string; updatedAt: string; trailing?: undefined | string }[];
+  theme?: "light" | "dark" | "auto";
+  /** The list's section headers (`{ id, name, sortOrder, createdAt }`), rendered in array order. A group carries no conversations of its own; it is matched against `conversations` by id, so the two props are complementary rather than alternatives. Omit for an ungrouped list. Set as a JS property. */
+  groups: { id: string; userId?: string; teamId?: string; name: string; sortOrder: number; createdAt: string }[];
+  /** 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. */
+  conversations: { id: string; title: string; groupId?: string; scope: { type: "document" | "collection"; documentId?: string; filters?: { tags?: string[]; authors?: string[]; contentType?: "transcript" | "markdown"; dateRange?: { from: string; to: string } } }; messageCount: number; lastMessageAt: string; updatedAt: string; trailing?: string }[];
   /** The id of the currently-open conversation, highlighted in the list. */
   activeId?: string;
   /** Controlled collapsed state. Set as a JS property (`el.collapsed = true`) to drive the rail from your app, updating it in response to `kai-collapse-toggle`. Omit for uncontrolled (the element manages it). Collapsed shrinks the rail to a floating reopen button. */
   collapsed?: boolean;
   /** Initial collapsed state when uncontrolled (default false). Use the `default-collapsed` attribute to start collapsed in plain HTML. */
   defaultCollapsed?: boolean;
+  /** Focus the built-in search input inside the shadow root. */
+  focus(options?: FocusOptions): void;
+  /** Clear the internal search query (resets the list filter) and fire kai-search with an empty string. */
+  clear(): void;
+  /** Programmatically select a conversation by id. The mirror of the kai-conversation-select event (a convenience over driving `activeId`). */
+  select(id: string): void;
+  /** Collapse the rail to its floating reopen button (fires `kai-collapse-toggle`). */
+  collapse(): void;
+  /** Expand the rail back to the full list (fires `kai-collapse-toggle`). */
+  expand(): void;
+  /** Toggle the rail collapsed/expanded (fires `kai-collapse-toggle`). */
+  toggle(): void;
 }
 
 export interface KaiDialogElement extends HTMLElement {
   /** Color mode (`auto` follows prefers-color-scheme). */
-  theme?: 'light' | 'dark' | 'auto';
+  theme?: "light" | "dark" | "auto";
   /** Drive/observe open state (Shoelace-style: settable + reflected to the `open` attribute; the element still self-manages on Escape/backdrop). Set `el.open = true`, or `<kai-dialog open>`; listen for `kai-open-change`. */
   open?: boolean;
   /** Initial open state on mount (uncontrolled seed). */
   defaultOpen?: boolean;
+  /** Open it programmatically (no-op while disabled). */
+  show(): void;
+  /** Close it programmatically. */
+  hide(): void;
+  /** Flip the open state (closes while disabled). */
+  toggle(): void;
+  /** Move focus to the dialog panel (no-op while closed). */
+  focus(options?: FocusOptions): void;
 }
 
 export interface KaiEditableLabelElement extends HTMLElement {
   /** Color mode (`auto` follows prefers-color-scheme). */
-  theme?: 'light' | 'dark' | 'auto';
-  /** The label text — settable and reflected to the `value` attribute. Read `el.value` for live state. */
+  theme?: "light" | "dark" | "auto";
+  /** The label text. Settable and reflected to the `value` attribute. Read `el.value` for live state. */
   value?: string;
   /** Controlled edit state. `el.editing = true` opens the field; reflected to the `editing` attribute. */
   editing?: boolean;
@@ -532,11 +680,17 @@ export interface KaiEditableLabelElement extends HTMLElement {
   placeholder?: string;
   /** Disable entering edit mode. */
   disabled?: boolean;
+  /** Switch the label into its editing field, which autofocuses and selects the current text. Same entry point as a user double-click, and a no-op while `disabled`. Commit with `commit()` or by blurring, abandon with `cancel()` or Escape. */
+  edit(): void;
+  /** Close the field and keep what was typed, exactly as blurring it does. `kai-rename` fires only when the text actually changed, so committing an untouched field is silent. A no-op while the field is closed. */
+  commit(): void;
+  /** Abandon the edit, exactly as Escape does: the original text is restored, the field closes and `kai-cancel` fires. `kai-rename` never fires, even if the field was edited. Also works when `editing` was set programmatically and the field has not rendered yet. */
+  cancel(): void;
 }
 
 export interface KaiEmbedElement extends HTMLElement {
   /** Color mode (`auto` follows prefers-color-scheme). */
-  theme?: 'light' | 'dark' | 'auto';
+  theme?: "light" | "dark" | "auto";
   /** Stable card id correlating every emitted event. Set as an attribute or property. */
   cardId?: string;
   /** The embed payload (provider + id/url + options). Set as a JS **property** (object). */
@@ -545,7 +699,7 @@ export interface KaiEmbedElement extends HTMLElement {
 
 export interface KaiEmptyElement extends HTMLElement {
   /** Color mode (`auto` follows prefers-color-scheme). */
-  theme?: 'light' | 'dark' | 'auto';
+  theme?: "light" | "dark" | "auto";
   /** Title text. Attribute: `empty-title` (`title` is a global HTML attribute). */
   emptyTitle?: string;
   /** Description text. */
@@ -554,8 +708,8 @@ export interface KaiEmptyElement extends HTMLElement {
 
 export interface KaiFeedbackBarElement extends HTMLElement {
   /** Color mode (`auto` follows prefers-color-scheme). */
-  theme?: 'light' | 'dark' | 'auto';
-  /** The banner label (e.g. "Was this helpful?"). Attribute: `bar-title` (`title` is avoided — it's a global HTML attribute). */
+  theme?: "light" | "dark" | "auto";
+  /** The banner label (e.g. "Was this helpful?"). Attribute: `bar-title` (`title` is avoided because it is a global HTML attribute). */
   barTitle?: string;
   /** When set, a not-helpful vote opens an optional detail form before the thank-you confirmation. Attribute: `collect-detail`. */
   collectDetail?: boolean;
@@ -573,10 +727,10 @@ export interface KaiFeedbackBarElement extends HTMLElement {
 
 export interface KaiFileTreeElement extends HTMLElement {
   /** Color mode (`auto` follows prefers-color-scheme). */
-  theme?: 'light' | 'dark' | 'auto';
+  theme?: "light" | "dark" | "auto";
   /** The files to render. Set as a JS property (array of `{ path, url?, code?, language?, type?, additions?, deletions?, status? }`). */
   files: { path: string; url?: undefined | string; code?: undefined | string; language?: undefined | string; type?: undefined | "html" | "pdf" | "image" | "other"; additions?: undefined | number; deletions?: undefined | number; status?: undefined | "added" | "modified" | "deleted" | "renamed" | "untracked" }[];
-  /** Selected file path — highlighted in the tree. */
+  /** Selected file path, highlighted in the tree. */
   activeFile?: string;
   /** Folder paths expanded initially. Omit to start with all folders open. */
   defaultExpanded?: string[];
@@ -586,12 +740,12 @@ export interface KaiFileTreeElement extends HTMLElement {
 
 export interface KaiFileUploadElement extends HTMLElement {
   /** Color mode (`auto` follows prefers-color-scheme). */
-  theme?: 'light' | 'dark' | 'auto';
+  theme?: "light" | "dark" | "auto";
   /** Allow selecting multiple files (default true). */
   multiple?: boolean;
   /** `accept` attribute for the file picker (e.g. `image/*`). */
   accept?: string;
-  /** Disable the dropzone — no clicking, no drag-and-drop. */
+  /** Disable the dropzone: no clicking, no drag-and-drop. */
   disabled?: boolean;
   /** Default dropzone label (overridable via the default slot). */
   label?: string;
@@ -599,9 +753,9 @@ export interface KaiFileUploadElement extends HTMLElement {
 
 export interface KaiFormElement extends HTMLElement {
   /** Color mode (`auto` follows prefers-color-scheme). */
-  theme?: 'light' | 'dark' | 'auto';
-  /** The form definition — a JSON Schema (`type:'object'`) + `x-kai-*` UI hints (the CardEnvelope.data). Set as a JS PROPERTY: `el.data = { type:'object', properties:{…} }`. Import the `FormDefinition` type from `@kitn.ai/ui` for the full shape (it is self-referential, so the element types it loosely). */
-  data?: Record<string, unknown>;
+  theme?: "light" | "dark" | "auto";
+  /** 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. */
+  data?: { type: "object"; title?: string; description?: string; required?: string[]; properties: Record<string, { type: "string" | "number" | "integer" | "boolean" | "array" | "object"; title?: string; description?: string; default?: unknown; enum?: unknown[]; format?: "email" | "uri" | "url" | "date" | "date-time" | "time"; minimum?: number; maximum?: number; minLength?: number; maxLength?: number; pattern?: string; minItems?: number; maxItems?: number; items?: Record<string, unknown> | { enum: unknown[] }; properties?: Record<string, Record<string, unknown>>; required?: string[]; readOnly?: boolean; "x-kai-widget"?: "textarea" | "slider" | "rating" | "radio" | "select" | "checkbox" | "password" | "switch"; "x-kai-placeholder"?: string; "x-kai-step"?: number }>; "x-kai-order"?: string[]; "x-kai-inlineMax"?: number; "x-kai-submitLabel"?: string; "x-kai-dismissible"?: boolean; "x-kai-actions"?: { id: string; label: string; variant?: "default" | "ghost" | "outline" }[] };
   /** Stable card id correlating every emitted CardEvent. Attribute: `card-id`. */
   cardId?: string;
   /** Heading rendered in the card chrome (= CardEnvelope.title). Attribute: `heading`. */
@@ -614,11 +768,23 @@ export interface KaiFormElement extends HTMLElement {
   defaultValues?: Record<string, unknown>;
   /** Disable all fields + submit. Attribute: `disabled`. */
   disabled?: boolean;
+  /** Focus the first control, or the first INVALID control after a failed validation. */
+  focus(options?: FocusOptions): void;
+  /** Validate + submit programmatically: focus the first invalid field on failure, else emit the `submit` CardEvent and resolve. Named `send`, not `submit`. */
+  send(): void;
+  /** Run client-side validation now and return `{ valid, errors? }` WITHOUT submitting. */
+  validate(): void;
+  /** Re-seed the form from each field's `default` and clear errors. */
+  reset(): void;
+  /** Trigger the dismiss path (emit `dismiss` + collapse to the re-openable stub). */
+  dismiss(): void;
+  /** Re-open a dismissed card from its stub (emit `reopen`). */
+  reopen(): void;
 }
 
 export interface KaiHoverCardElement extends HTMLElement {
   /** Color mode (`auto` follows prefers-color-scheme). */
-  theme?: 'light' | 'dark' | 'auto';
+  theme?: "light" | "dark" | "auto";
   /** Delay (ms) before the card opens on hover. Defaults to 0 (focus opens it immediately too). */
   openDelay?: number;
   /** Delay (ms) before it closes after the pointer leaves. Defaults to 300. */
@@ -631,11 +797,17 @@ export interface KaiHoverCardElement extends HTMLElement {
   defaultOpen?: boolean;
   /** Suppress the hover behavior entirely without unmounting. */
   disabled?: boolean;
+  /** Open it programmatically (no-op while disabled). */
+  show(): void;
+  /** Close it programmatically. */
+  hide(): void;
+  /** Flip the open state (closes while disabled). */
+  toggle(): void;
 }
 
 export interface KaiIconElement extends HTMLElement {
   /** Color mode (`auto` follows prefers-color-scheme). */
-  theme?: 'light' | 'dark' | 'auto';
+  theme?: "light" | "dark" | "auto";
   /** A curated icon name (e.g. `"mic"`, `"globe"`), an image URL/data-URI, or plain text. */
   name?: string;
   /** Size token: `sm` | `md` (default) | `lg`. */
@@ -644,7 +816,7 @@ export interface KaiIconElement extends HTMLElement {
 
 export interface KaiImageElement extends HTMLElement {
   /** Color mode (`auto` follows prefers-color-scheme). */
-  theme?: 'light' | 'dark' | 'auto';
+  theme?: "light" | "dark" | "auto";
   /** Base64-encoded image data (pair with `media-type`). */
   base64?: string;
   /** Raw image bytes (set as a JS property). */
@@ -657,10 +829,10 @@ export interface KaiImageElement extends HTMLElement {
 
 export interface KaiInputElement extends HTMLElement {
   /** Color mode (`auto` follows prefers-color-scheme). */
-  theme?: 'light' | 'dark' | 'auto';
+  theme?: "light" | "dark" | "auto";
   /** Native input type: `text` (default) · `email` · `url` · `search` · `tel` · `password` · `number`. Single-line only. */
   type?: string;
-  /** 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. */
+  /** 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. */
   value?: string;
   /** Placeholder shown when empty. */
   placeholder?: string;
@@ -686,22 +858,28 @@ export interface KaiInputElement extends HTMLElement {
   autocomplete?: string;
   /** Virtual-keyboard hint forwarded to the inner input (e.g. `numeric`, `email`). */
   inputmode?: string;
+  /** Focus the inner input (the host can't reach into the shadow root). */
+  focus(options?: FocusOptions): void;
+  /** Select the inner input's text. */
+  select(): void;
+  /** Empty the value and fire `kai-change` with `''`. */
+  clear(): void;
 }
 
 export interface KaiKbdElement extends HTMLElement {
   /** Color mode (`auto` follows prefers-color-scheme). */
-  theme?: 'light' | 'dark' | 'auto';
-  /** Shortcut spec — tokens joined by `+` (e.g. `Mod+Shift+K`). Omit it to show default-slot content instead. Display only; the element does not bind keys. */
+  theme?: "light" | "dark" | "auto";
+  /** Shortcut spec: tokens joined by `+` (e.g. `Mod+Shift+K`). Omit it to show default-slot content instead. Display only; the element does not bind keys. */
   keys?: string;
   /** `mac` uses ⌘/⌥, `other` uses Ctrl. `auto` (default) sniffs the OS. */
-  platform?: "other" | "auto" | "mac";
+  platform?: "auto" | "mac" | "other";
   /** Cap size: `sm` or `md`. Defaults to `md`. */
   size?: "sm" | "md";
 }
 
 export interface KaiLinkPreviewElement extends HTMLElement {
   /** Color mode (`auto` follows prefers-color-scheme). */
-  theme?: 'light' | 'dark' | 'auto';
+  theme?: "light" | "dark" | "auto";
   /** Stable card id correlating every emitted event. Set as an attribute or property. */
   cardId?: string;
   /** The link payload (OG metadata). Set as a JS **property** (object). */
@@ -710,7 +888,7 @@ export interface KaiLinkPreviewElement extends HTMLElement {
 
 export interface KaiLoaderElement extends HTMLElement {
   /** Color mode (`auto` follows prefers-color-scheme). */
-  theme?: 'light' | 'dark' | 'auto';
+  theme?: "light" | "dark" | "auto";
   /** The animation style: `'circular' | 'classic' | 'pulse' | 'pulse-dot' | 'dots' | 'typing' | 'wave' | 'bars' | 'terminal' | 'text-blink' | 'text-shimmer' | 'loading-dots'`. Defaults to `'circular'`. */
   variant?: "circular" | "classic" | "pulse" | "pulse-dot" | "dots" | "typing" | "wave" | "bars" | "terminal" | "text-blink" | "text-shimmer" | "loading-dots";
   /** Loader size: `'sm' | 'md' | 'lg'`. Defaults to `'md'`. */
@@ -721,11 +899,11 @@ export interface KaiLoaderElement extends HTMLElement {
 
 export interface KaiMarkdownElement extends HTMLElement {
   /** Color mode (`auto` follows prefers-color-scheme). */
-  theme?: 'light' | 'dark' | 'auto';
+  theme?: "light" | "dark" | "auto";
   /** The markdown source to render. */
   content: string;
   /** Text/markdown sizing. */
-  proseSize?: "sm" | "lg" | "xs" | "base";
+  proseSize?: "xs" | "sm" | "base" | "lg";
   /** Shiki theme for fenced code blocks. */
   codeTheme?: string;
   /** Disable syntax highlighting (no Shiki loads). */
@@ -734,12 +912,12 @@ export interface KaiMarkdownElement extends HTMLElement {
 
 export interface KaiMenuElement extends HTMLElement {
   /** Color mode (`auto` follows prefers-color-scheme). */
-  theme?: 'light' | 'dark' | 'auto';
-  /** Tree of menu items. Set as a JS property — not an HTML attribute. */
+  theme?: "light" | "dark" | "auto";
+  /** Tree of menu items. Set as a JS property, not an HTML attribute. */
   items?: { id?: string; label?: string; icon?: string; shortcut?: string; checked?: boolean; radioGroup?: string; disabled?: boolean; separator?: boolean; heading?: boolean; items?: Record<string, unknown>[] }[];
   /** Optional placement hint (unused by the underlying Dropdown which always positions bottom-start, kept for future extension). */
   placement?: string;
-  /** Built-in trigger: leading icon (a named icon like `"plus"`, an image URL/data-URI, or text). Use this instead of slotting `slot="trigger"` for the common case — a slotted trigger overrides it. */
+  /** Built-in trigger: leading icon (a named icon like `"plus"`, an image URL/data-URI, or text). Use this instead of slotting `slot="trigger"` for the common case; a slotted trigger overrides it. */
   triggerIcon?: string;
   /** Built-in trigger: a text label (e.g. `"High"`). */
   triggerLabel?: string;
@@ -751,23 +929,27 @@ export interface KaiMenuElement extends HTMLElement {
   open?: boolean;
   /** Initial open state on mount (uncontrolled seed). */
   defaultOpen?: boolean;
-  /** Disable the trigger — click/keyboard and `show()` no longer open the menu. */
+  /** Disable the trigger: click/keyboard and `show()` no longer open the menu. */
   disabled?: boolean;
+  /** Open it programmatically (no-op while disabled). */
+  show(): void;
+  /** Close it programmatically. */
+  hide(): void;
+  /** Flip the open state (closes while disabled). */
+  toggle(): void;
 }
 
 export interface KaiMessageElement extends HTMLElement {
   /** Color mode (`auto` follows prefers-color-scheme). */
-  theme?: 'light' | 'dark' | 'auto';
+  theme?: "light" | "dark" | "auto";
   /** The full message object. Set as a JS property. */
-  message?: { id: string; role: "user" | "assistant"; content: string; reasoning?: { text: string; label?: string }; tools?: { type: string; state: "input-streaming" | "input-available" | "output-available" | "output-error"; input?: Record<string, unknown>; output?: Record<string, unknown>; toolCallId?: string; errorText?: string }[]; attachments?: { id: string; type: "file" | "source-document"; filename?: string; mediaType?: string; url?: string; title?: string }[]; actions?: ("copy" | "like" | "dislike" | "regenerate" | "edit" | { id: string; label: string; icon?: string; tooltip?: string })[]; avatar?: { src?: string; fallback?: string; alt?: string }; feedback?: "like" | "dislike" };
-  /** Convenience for simple cases when not passing a `message` object. */
-  role?: "user" | "assistant";
-  /** Convenience content (used when `message` is not set). */
-  content?: string;
+  message?: { id: string; role: "user" | "assistant"; parts: ({ type: "text"; text: string; raw?: { source: string; payload: unknown } } | { type: "reasoning"; text: string; label?: string; index?: number; streamId?: string; signature?: string; raw?: { source: string; payload: unknown } } | { type: "tool"; tool: { type: string; kind?: "command" | "file-change" | "search" | "fetch" | "mcp" | "image" | "generic"; state: "input-streaming" | "input-available" | "output-available" | "output-error"; input?: Record<string, unknown>; rawInput?: string; output?: Record<string, unknown>; toolCallId?: string; errorText?: string; raw?: { source: string; payload: unknown } }; raw?: { source: string; payload: unknown } } | { type: "card"; envelope: { type: string; id: string; data: unknown; title?: string; resolution?: { kind: "action"; action: string; payload?: unknown; at?: string } | { kind: "submit"; data: unknown; at?: string } | { kind: "dismissed"; at?: string } | { kind: "expired"; reason?: string; at?: string } }; raw?: { source: string; payload: unknown } } | { type: "source"; source: { id?: string; url?: string; title?: string; snippet?: string; index?: number }; raw?: { source: string; payload: unknown } } | { type: "file"; attachment: { id: string; type: "file" | "source-document"; filename?: string; mediaType?: string; url?: string; title?: string }; raw?: { source: string; payload: unknown } })[]; actions?: ("copy" | "like" | "dislike" | "regenerate" | "edit" | { id: string; label: string; icon?: string; tooltip?: string })[]; avatar?: { src?: string; fallback?: string; alt?: string }; feedback?: "like" | "dislike" };
+  /** Who is speaking: `'user'` or `'assistant'`. Convenience for simple cases when not passing a `message` object. This is the SEMANTIC role of the message, not an ARIA role. The name collides with the global ARIA `role` attribute, which is why the facade lifts it off the host (see `liftRoleOffHost`). Neither speaker is a valid ARIA role, so a `role="user"` left on `<kai-message>` is a CRITICAL axe `aria-roles` violation. The accessible role lives on the row inside the shadow root instead: `role="article"` plus an `aria-label` naming the speaker, matching the SolidJS `<Message>` component. Re-declares the DOM member `HTMLElement.role`, so it is NOT optional here: an interface extending HTMLElement may only narrow it, and the element always carries a value for it. */
+  role: "user" | "assistant";
   /** Force markdown on/off. Defaults to on for assistant, off for user. */
   markdown?: boolean;
   /** Text/markdown sizing for the message body. */
-  proseSize?: "sm" | "lg" | "xs" | "base";
+  proseSize?: "xs" | "sm" | "base" | "lg";
   /** Shiki theme name used for fenced code blocks in the content. */
   codeTheme?: string;
   /** Disable syntax highlighting for code blocks (no Shiki loads). */
@@ -780,41 +962,55 @@ export interface KaiMessageElement extends HTMLElement {
   avatarFallback?: string;
   /** Avatar rail mode. `'none'` omits the avatar rail entirely so the body spans the full row (predictable layout when you never show avatars). Any other value keeps the default behaviour: the built-in avatar when one resolves, or your `slot="avatar"` content when projected (which REPLACES the built-in). */
   avatar?: string;
+  /** Optional card type -> custom-element tag overrides/additions for `card` parts (merged over the built-ins). Property: `el.cardTypes`. Typed as a plain string map (not the `CardTagMap` alias) so the generated React wrapper inlines it instead of emitting an unresolved named type. */
+  cardTypes?: Record<string, string>;
+  /** 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. */
+  cardSchemas?: Record<string, object>;
+  /** Copy the message content to the clipboard and show the copied check. */
+  copy(): void;
 }
 
 export interface KaiModelSwitcherElement extends HTMLElement {
   /** Color mode (`auto` follows prefers-color-scheme). */
-  theme?: 'light' | 'dark' | 'auto';
-  /** The selectable models. Set as a JS property (array). */
-  models: { id: string; name: string; provider?: undefined | string; description?: undefined | string; group?: undefined | string }[];
+  theme?: "light" | "dark" | "auto";
+  /** The selectable models. Set as a JS property (array). Omit to supply them as `<kai-model>` light-DOM children instead; when both are present the property's models come first. */
+  models: { id: string; name: string; provider?: string; description?: string; group?: string }[];
   /** The currently-selected model id. Defaults to the first model. */
   currentModel?: string;
   /** Drive/observe the dropdown's open state (Shoelace-style: settable + reflected to the `open` attribute, the dropdown still self-manages on click/keyboard). Set `el.open = true`, or `<kai-model-switcher open>`; listen for `kai-open-change`. */
   open?: boolean;
   /** Initial open state on mount (uncontrolled seed). */
   defaultOpen?: boolean;
-  /** Disable the trigger — click/keyboard and `show()` no longer open the dropdown. */
+  /** Disable the trigger: click/keyboard and `show()` no longer open the dropdown. */
   disabled?: boolean;
+  /** Open it programmatically (no-op while disabled). */
+  show(): void;
+  /** Close it programmatically. */
+  hide(): void;
+  /** Flip the open state (closes while disabled). */
+  toggle(): void;
 }
 
 export interface KaiNavElement extends HTMLElement {
   /** Color mode (`auto` follows prefers-color-scheme). */
-  theme?: 'light' | 'dark' | 'auto';
+  theme?: "light" | "dark" | "auto";
   /** The nav items. Set as a JS property (array, not an attribute). Each item may carry `children` (a collapsible group), a `status` dot, and trailing `meta` text. */
-  items?: { id: string; label?: string; icon?: string; badge?: string; trailing?: string; disabled?: boolean; children?: Record<string, unknown>[]; status?: { tone: "error" | "primary" | "info" | "success" | "warning" | "neutral"; label?: string; pulse?: boolean }; meta?: string; action?: { icon: string; label: string }; closable?: boolean }[];
+  items?: { id: string; label?: string; icon?: string; badge?: string; trailing?: string; disabled?: boolean; children?: Record<string, unknown>[]; status?: { tone: "primary" | "info" | "success" | "warning" | "error" | "neutral"; label?: string; pulse?: boolean }; meta?: string; action?: { icon: string; label: string }; closable?: boolean }[];
   /** Active item id (controlled). */
   value?: string;
   /** Initial active id when uncontrolled. */
   defaultValue?: string;
   /** Ids of group items collapsed on first render (groups default to expanded). Set as a JS property (array). */
   defaultCollapsed?: string[];
+  /** Activate an item by id (fires kai-nav-select). */
+  select(id: string): void;
 }
 
 export interface KaiNoticeElement extends HTMLElement {
   /** Color mode (`auto` follows prefers-color-scheme). */
-  theme?: 'light' | 'dark' | 'auto';
+  theme?: "light" | "dark" | "auto";
   /** `neutral` (default) · `info` · `warning` · `error` · `success`. Drives the leading icon's color and the a11y role (`alert` for errors, else `status`). */
-  severity?: "error" | "info" | "success" | "warning" | "neutral";
+  severity?: "neutral" | "info" | "warning" | "error" | "success";
   /** Leading icon: omit for the severity default, `"none"` to hide it, or a named icon to override. */
   icon?: string;
   /** Show a dismiss (×) that hides the notice and emits `kai-dismiss`. */
@@ -823,7 +1019,7 @@ export interface KaiNoticeElement extends HTMLElement {
 
 export interface KaiPaneElement extends HTMLElement {
   /** Color mode (`auto` follows prefers-color-scheme). */
-  theme?: 'light' | 'dark' | 'auto';
+  theme?: "light" | "dark" | "auto";
   /** The pane title (the agent / window name). Named `headline` because `title` collides with the global `HTMLElement.title` attribute (it throws at registration). Attribute: `headline`. */
   headline?: string;
   /** A role / label shown under the title (e.g. "Reviewer", "claude-sonnet"). Attribute: `subtitle`. */
@@ -842,20 +1038,24 @@ export interface KaiPaneElement extends HTMLElement {
 
 export interface KaiPaneGroupElement extends HTMLElement {
   /** Color mode (`auto` follows prefers-color-scheme). */
-  theme?: 'light' | 'dark' | 'auto';
+  theme?: "light" | "dark" | "auto";
   /** The tabs to render. An array of `{ id, name, status?, needsAttention?, number? }` set as a JS PROPERTY (not an HTML attribute). */
   tabs?: { id: string; name: string; status?: { tone: "working" | "idle" | "done" | "error" | "blocked"; label?: string; pulse?: boolean }; needsAttention?: boolean; number?: number }[];
   /** The active tab id (controlled, and reflected to the `active` ATTRIBUTE so `::part`/`[active]` selectors and the per-tab named slot follow it). Set it as the `active` attribute or drive it from `kai-tab-change`; omit for uncontrolled (the first tab). */
   active?: string;
   /** Highlight the frame as the ACTIVE group in a multi-group layout. Attribute: `focused`. */
   focused?: boolean;
+  /** Select a tab by id (fires `kai-tab-change`). Ignores unknown ids. */
+  select(id: string): void;
+  /** Focus the active tab in the strip. */
+  focus(): void;
 }
 
 export interface KaiPopoverElement extends HTMLElement {
   /** Color mode (`auto` follows prefers-color-scheme). */
-  theme?: 'light' | 'dark' | 'auto';
+  theme?: "light" | "dark" | "auto";
   /** Floating placement relative to the trigger (floating-ui placement). */
-  placement?: "top" | "right" | "bottom" | "left" | "top-start" | "top-end" | "right-start" | "right-end" | "bottom-start" | "bottom-end" | "left-start" | "left-end";
+  placement?: "top" | "right" | "bottom" | "left" | "bottom-end" | "bottom-start" | "left-end" | "left-start" | "right-end" | "right-start" | "top-end" | "top-start";
   /** Gap in px between the trigger and the panel. */
   gutter?: number;
   /** Drive/observe open state (Shoelace-style: settable + reflected to the `open` attribute, the element still self-manages on click). Set `el.open = true`, or `<kai-popover open>`; listen for `kai-open-change`. */
@@ -864,11 +1064,17 @@ export interface KaiPopoverElement extends HTMLElement {
   defaultOpen?: boolean;
   /** Turn the popover off while keeping the trigger mounted (clicks and `show()` no longer open it). */
   disabled?: boolean;
+  /** Open it programmatically (no-op while disabled). */
+  show(): void;
+  /** Close it programmatically. */
+  hide(): void;
+  /** Flip the open state (closes while disabled). */
+  toggle(): void;
 }
 
 export interface KaiProgressBarElement extends HTMLElement {
   /** Color mode (`auto` follows prefers-color-scheme). */
-  theme?: 'light' | 'dark' | 'auto';
+  theme?: "light" | "dark" | "auto";
   /** Current progress value (0..max). Attribute: `value`. */
   value?: number;
   /** The value `value` runs to (default 100). Attribute: `max`. */
@@ -881,16 +1087,16 @@ export interface KaiProgressBarElement extends HTMLElement {
 
 export interface KaiPromptDockElement extends HTMLElement {
   /** Color mode (`auto` follows prefers-color-scheme). */
-  theme?: 'light' | 'dark' | 'auto';
-  /** How the tray frames the input — the SPATIAL inset axis: `inset` (default, the classic recessed frame on every side) | `edge` (top/bottom inset only; the input sits flush left/right so the lips span the full width) | `none` (no inset; the lips attach directly as a plain stack). Attribute: `frame`. */
-  frame?: "none" | "inset" | "edge";
-  /** How the tray surface looks — the VISUAL axis, orthogonal to `frame`: `soft` (default, sunken surface + border + radius) | `outlined` (transparent + border + radius) | `filled` (sunken, no border, + radius) | `plain` (bare). Attribute: `appearance`. */
-  appearance?: "outlined" | "filled" | "plain" | "soft";
+  theme?: "light" | "dark" | "auto";
+  /** How the tray frames the input, the SPATIAL inset axis: `inset` (default, the classic recessed frame on every side) | `edge` (top/bottom inset only; the input sits flush left/right so the lips span the full width) | `none` (no inset; the lips attach directly as a plain stack). Attribute: `frame`. */
+  frame?: "inset" | "edge" | "none";
+  /** How the tray surface looks, the VISUAL axis orthogonal to `frame`: `soft` (default, sunken surface + border + radius) | `outlined` (transparent + border + radius) | `filled` (sunken, no border, + radius) | `plain` (bare). Attribute: `appearance`. */
+  appearance?: "soft" | "outlined" | "filled" | "plain";
 }
 
 export interface KaiPromptInputElement extends HTMLElement {
   /** Color mode (`auto` follows prefers-color-scheme). */
-  theme?: 'light' | 'dark' | 'auto';
+  theme?: "light" | "dark" | "auto";
   /** Value of the input, as a JS property. A **string** is the controlled text mirror (the host owns it and updates on `kai-value-change`). A **ComposerDoc** (array of text/entity segments) is a one-time **seed** that pre-populates pills (skills/agents/plugins); the user then edits freely. Leave unset for uncontrolled behavior. `kai-submit`/`kai-value-change` always emit `value` as the flattened string (back-compat) plus the structured `doc` + `entities`. */
   value?: string | ({ type: "text"; text: string } | { type: "entity"; entity: { kind: string; id: string; label: string; icon?: string; promptText?: string; data?: Record<string, unknown> } })[];
   /** Placeholder text shown in the empty input. */
@@ -909,21 +1115,29 @@ export interface KaiPromptInputElement extends HTMLElement {
   voice?: boolean;
   /** When set and `loading` is true, the send button is replaced by a Stop button (square icon, "Stop" aria-label). Clicking it fires `kai-stop`. */
   stoppable?: boolean;
-  /** Send-button visibility. `'always'` (default) always shows it; `'auto'` shows it only when there's text/attachments (an empty composer hides it — Enter still submits). To hide it entirely (Enter-only), it's pure CSS: `::part(send){display:none}` — no prop needed. Restyle via `::part(send)`. The Stop button (`stoppable` + `loading`) is unaffected. */
+  /** Send-button visibility. `'always'` (default) always shows it; `'auto'` shows it only when there's text/attachments (an empty composer hides it, though Enter still submits). To hide it entirely (Enter-only), it's pure CSS: `::part(send){display:none}`, no prop needed. Restyle via `::part(send)`. The Stop button (`stoppable` + `loading`) is unaffected. */
   submit?: "always" | "auto";
   /** When `false`, hides the built-in paperclip attach button even though the element otherwise supports attachments. Use this when a `+` menu in `toolbar-start` already exposes "Add files", to avoid a duplicate control. Defaults to `true`. */
   attach?: boolean;
   /** 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). */
   attachments?: { id: string; type: "file" | "source-document"; filename?: string; mediaType?: string; url?: string; title?: string }[];
-  /** Rich entity triggers — each `{ char, kind, items }` opens a caret-anchored menu that inserts an atomic pill. Convention: `/` → skills, `@` → agents (plugins are the grouping/provenance of those items). Set as a JS property. */
+  /** Rich entity triggers. Each `{ char, kind, items }` opens a caret-anchored menu that inserts an atomic pill. Convention: `/` → skills, `@` → agents (plugins are the grouping/provenance of those items). Set as a JS property. */
   triggers?: { char: string; kind: string; items?: { id: string; label: string; icon?: string; description?: string; group?: string; kind?: string; promptText?: string; data?: Record<string, unknown> }[] }[];
   /** Default icon per entity kind (kind → image URL/data-URI) for pills/menu items without their own `icon`. Overrides the built-in agent/plugin glyphs. JS property. */
   kindIcons?: Record<string, string>;
+  /** Focus the text editor inside the shadow root (not the hidden file input). */
+  focus(options?: FocusOptions): void;
+  /** Blur the focused input control. */
+  blur(): void;
+  /** Clear the text and any staged attachments (fires kai-value-change / kai-attachments-change so a controlled consumer can react). */
+  clear(): void;
+  /** Send the current value programmatically, on the same path as Enter / the send button (fires kai-submit, then clears staged attachments). Named `send`, not `submit`, to avoid colliding with the `submit` prop. */
+  send(): void;
 }
 
 export interface KaiReasoningElement extends HTMLElement {
   /** Color mode (`auto` follows prefers-color-scheme). */
-  theme?: 'light' | 'dark' | 'auto';
+  theme?: "light" | "dark" | "auto";
   /** The reasoning text to display. */
   text: string;
   /** Trigger label. */
@@ -936,13 +1150,19 @@ export interface KaiReasoningElement extends HTMLElement {
   streaming?: boolean;
   /** Render `text` as markdown. */
   markdown?: boolean;
-  /** Gate the disclosure trigger — programmatic `show()/hide()/toggle()` still work, but the trigger click no longer toggles. */
+  /** Gate the disclosure trigger: programmatic `show()/hide()/toggle()` still work, but the trigger click no longer toggles. */
   disabled?: boolean;
+  /** Open it programmatically (no-op while disabled). */
+  show(): void;
+  /** Close it programmatically. */
+  hide(): void;
+  /** Flip the open state (closes while disabled). */
+  toggle(): void;
 }
 
 export interface KaiRemoteElement extends HTMLElement {
   /** Color mode (`auto` follows prefers-color-scheme). */
-  theme?: 'light' | 'dark' | 'auto';
+  theme?: "light" | "dark" | "auto";
   /** The remote card URL. Attribute: `src`. */
   src?: string;
   /** Exact provider origin (https: or http://localhost for dev). Attribute: `provider-origin`. */
@@ -955,18 +1175,22 @@ export interface KaiRemoteElement extends HTMLElement {
 
 export interface KaiResizableElement extends HTMLElement {
   /** Color mode (`auto` follows prefers-color-scheme). */
-  theme?: 'light' | 'dark' | 'auto';
+  theme?: "light" | "dark" | "auto";
   /** Layout axis: `horizontal` (row, default) or `vertical` (column). */
-  orientation?: "vertical" | "horizontal";
+  orientation?: "horizontal" | "vertical";
   /** Which item index is maximized (null = none). Declarative source of truth. */
-  maximizedIndex?: null | number;
-  /** Divider affordance drawn inside each draggable handle's 8px grab zone: - `line` (default) — a 1px hairline, transparent at rest, tinting on hover/drag. - `grip` — a dotted grip handle. - `none` — no visible divider, just the invisible hit-area. The full grab zone and keyboard/ARIA behavior are identical for all three. */
-  handle?: "none" | "line" | "grip";
+  maximizedIndex: number | null;
+  /** Divider affordance drawn inside each draggable handle's 8px grab zone: - `line` (default): a 1px hairline, transparent at rest, tinting on hover/drag. - `grip`: a dotted grip handle. - `none`: no visible divider, just the invisible hit-area. The full grab zone and keyboard/ARIA behavior are identical for all three. */
+  handle?: "line" | "grip" | "none";
+  /** Imperatively maximize the item at `index` (thin wrapper over `maximizedIndex`). */
+  maximize(index: number): void;
+  /** Imperatively restore from the maximized layout. */
+  restore(): void;
 }
 
 export interface KaiResizableItemElement extends HTMLElement {
   /** Color mode (`auto` follows prefers-color-scheme). */
-  theme?: 'light' | 'dark' | 'auto';
+  theme?: "light" | "dark" | "auto";
   /** Initial main-axis size: `"280px"` (fixed) or `"25%"`/`25` (percent). Omitted → flexible. */
   size?: string;
   /** Minimum size during resize (px or %). */
@@ -975,17 +1199,17 @@ export interface KaiResizableItemElement extends HTMLElement {
   max?: string;
   /** Fix this panel's size; adjacent dividers become non-draggable. */
   locked?: boolean;
-  /** Hide this panel; its divider is dropped and the rest reflow. */
-  hidden?: boolean;
-  /** Collapse this panel — same layout effect as `hidden` (divider dropped, the rest reflow), but it WORKS as a bare boolean from framework JSX. A plain `<kai-resizable-item collapsed>` in React/Solid/Vue/Svelte collapses the panel at the first render; `hidden` does not, because a JSX boolean sets neither the `hidden` attribute nor the IDL property on a custom element, so the parent never sees it. The facade reflects `collapsed` to a `collapsed` attribute the parent reads. Prefer this over `hidden` for declarative collapse. */
+  /** Hide this panel; its divider is dropped and the rest reflow. Re-declares the DOM member `HTMLElement.hidden`, so it is NOT optional here: an interface extending HTMLElement may only narrow it, and the element always carries a value for it. */
+  hidden: boolean;
+  /** Collapse this panel. Same layout effect as `hidden` (divider dropped, the rest reflow), but it WORKS as a bare boolean from framework JSX. A plain `<kai-resizable-item collapsed>` in React/Solid/Vue/Svelte collapses the panel at the first render; `hidden` does not, because a JSX boolean sets neither the `hidden` attribute nor the IDL property on a custom element, so the parent never sees it. The facade reflects `collapsed` to a `collapsed` attribute the parent reads. Prefer this over `hidden` for declarative collapse. */
   collapsed?: boolean;
 }
 
 export interface KaiResponseStreamElement extends HTMLElement {
   /** Color mode (`auto` follows prefers-color-scheme). */
-  theme?: 'light' | 'dark' | 'auto';
-  /** Text to stream. A string, or an `AsyncIterable<string>` (set as a JS property — async iterables can't be HTML attributes). */
-  text?: string | AsyncIterable<string>;
+  theme?: "light" | "dark" | "auto";
+  /** Text to stream. A string, or an `AsyncIterable<string>` (set as a JS property, since async iterables can't be HTML attributes). */
+  text: string | AsyncIterable<string>;
   /** Reveal animation. */
   mode?: "typewriter" | "fade";
   /** Characters/segments per tick. */
@@ -996,10 +1220,10 @@ export interface KaiResponseStreamElement extends HTMLElement {
 
 export interface KaiScopePickerElement extends HTMLElement {
   /** Color mode (`auto` follows prefers-color-scheme). */
-  theme?: 'light' | 'dark' | 'auto';
-  /** Authors to offer as scope filters. Set as a JS property. */
+  theme?: "light" | "dark" | "auto";
+  /** Authors to offer as scope filters. Omit to drop the Authors section (for a tag-only picker). Set as a JS property. */
   availableAuthors: string[];
-  /** Tags to offer as scope filters. Set as a JS property. */
+  /** Tags to offer as scope filters. Omit to drop the Tags section (for an author-only picker). Set as a JS property. */
   availableTags: string[];
   /** The label shown on the trigger for the active scope. */
   currentLabel?: string;
@@ -1007,13 +1231,19 @@ export interface KaiScopePickerElement extends HTMLElement {
   open?: boolean;
   /** Initial open state on mount (uncontrolled seed). */
   defaultOpen?: boolean;
-  /** Disable the trigger — click/keyboard and `show()` no longer open the dropdown. */
+  /** Disable the trigger: click/keyboard and `show()` no longer open the dropdown. */
   disabled?: boolean;
+  /** Open it programmatically (no-op while disabled). */
+  show(): void;
+  /** Close it programmatically. */
+  hide(): void;
+  /** Flip the open state (closes while disabled). */
+  toggle(): void;
 }
 
 export interface KaiScreenElement extends HTMLElement {
   /** Color mode (`auto` follows prefers-color-scheme). */
-  theme?: 'light' | 'dark' | 'auto';
+  theme?: "light" | "dark" | "auto";
   /** Drive/observe open state (Shoelace-style: settable + reflected to the `open` attribute; the element still self-manages). Set `el.open = true`, or `<kai-screen open>`; listen for `kai-open-change`. */
   open?: boolean;
   /** Initial open state on mount (uncontrolled seed). */
@@ -1024,30 +1254,38 @@ export interface KaiScreenElement extends HTMLElement {
   back?: boolean;
   /** Opt out of marking sibling elements inert/aria-hidden while open (for unusual layouts). */
   noInert?: boolean;
+  /** Open it programmatically (no-op while disabled). */
+  show(): void;
+  /** Close it programmatically. */
+  hide(): void;
+  /** Flip the open state (closes while disabled). */
+  toggle(): void;
+  /** Move focus to the screen surface (no-op while closed). */
+  focus(options?: FocusOptions): void;
 }
 
 export interface KaiScrollAreaElement extends HTMLElement {
   /** Color mode (`auto` follows prefers-color-scheme). */
-  theme?: 'light' | 'dark' | 'auto';
+  theme?: "light" | "dark" | "auto";
   /** Which axis scrolls. `vertical` (default) · `horizontal` · `both`. The cross axis is clamped so content can't overflow it. */
   orientation?: "vertical" | "horizontal" | "both";
 }
 
 export interface KaiScrollButtonElement extends HTMLElement {
   /** Color mode (`auto` follows prefers-color-scheme). */
-  theme?: 'light' | 'dark' | 'auto';
+  theme?: "light" | "dark" | "auto";
   /** CSS id of the scroll container to control. When omitted the element walks up the DOM (outside its own shadow root) to find the nearest scrollable ancestor. Mirrors the `for` convention of `<label for="...">`. */
   for?: string;
   /** Button visual variant: `'outline' | 'ghost' | 'default'`. Defaults to `'outline'`. */
-  variant?: "default" | "ghost" | "outline";
+  variant?: "outline" | "ghost" | "default";
   /** Button size token. Defaults to `'icon'` (square). */
   size?: "sm" | "md" | "lg" | "icon" | "icon-sm";
 }
 
 export interface KaiSearchElement extends HTMLElement {
   /** Color mode (`auto` follows prefers-color-scheme). */
-  theme?: 'light' | 'dark' | 'auto';
-  /** Controlled query — settable and reflected to the `value` attribute. Read `el.value` for live state. */
+  theme?: "light" | "dark" | "auto";
+  /** Controlled query. Settable and reflected to the `value` attribute. Read `el.value` for live state. */
   value?: string;
   /** Placeholder. Defaults to `Search…`. */
   placeholder?: string;
@@ -1059,14 +1297,18 @@ export interface KaiSearchElement extends HTMLElement {
   loading?: boolean;
   /** Optional shortcut hint shown (as a `kai-kbd`) while the field is empty, e.g. `Mod+K`. Display only; it does not bind the key. */
   shortcut?: string;
+  /** Focus the search input inside the shadow root. A native `focus()` on the host lands on the host itself and never reaches it. */
+  focus(): void;
+  /** Empty the field and fire `kai-search` with an empty value immediately, cancelling any debounced search still in flight, then return focus to the input. Same path as the trailing clear button. */
+  clear(): void;
 }
 
 export interface KaiSegmentedElement extends HTMLElement {
   /** Color mode (`auto` follows prefers-color-scheme). */
-  theme?: 'light' | 'dark' | 'auto';
+  theme?: "light" | "dark" | "auto";
   /** The selectable segments, left to right. Set as a JS property (array). */
   options: { value: string; label: string; icon?: undefined | string }[];
-  /** Controlled selected `value` — settable and reflected to the `value` attribute. `el.value = 'preview'` drives it; choosing a segment updates it and fires `kai-change`. Read `el.value` for live state. */
+  /** Controlled selected `value`. Settable and reflected to the `value` attribute. `el.value = 'preview'` drives it; choosing a segment updates it and fires `kai-change`. Read `el.value` for live state. */
   value?: string;
   /** Control density: `sm` or `md`. Defaults to `md`. */
   size?: "sm" | "md";
@@ -1074,14 +1316,14 @@ export interface KaiSegmentedElement extends HTMLElement {
 
 export interface KaiSeparatorElement extends HTMLElement {
   /** Color mode (`auto` follows prefers-color-scheme). */
-  theme?: 'light' | 'dark' | 'auto';
-  /** `horizontal` (default, block + full-width) or `vertical` (a rule inside a flex/grid row — it stretches to the row height). */
-  orientation?: "vertical" | "horizontal";
+  theme?: "light" | "dark" | "auto";
+  /** `horizontal` (default, block + full-width) or `vertical` (a rule inside a flex/grid row, stretching to the row height). */
+  orientation?: "horizontal" | "vertical";
 }
 
 export interface KaiSettingItemElement extends HTMLElement {
   /** Color mode (`auto` follows prefers-color-scheme). */
-  theme?: 'light' | 'dark' | 'auto';
+  theme?: "light" | "dark" | "auto";
   /** Row label (primary text). Attribute: `label`. */
   label?: string;
   /** Optional secondary description under the label. Attribute: `description`. */
@@ -1090,7 +1332,7 @@ export interface KaiSettingItemElement extends HTMLElement {
 
 export interface KaiSettingsGroupElement extends HTMLElement {
   /** Color mode (`auto` follows prefers-color-scheme). */
-  theme?: 'light' | 'dark' | 'auto';
+  theme?: "light" | "dark" | "auto";
   /** Small section heading shown above the card. Attribute: `heading`. */
   heading?: string;
   /** Optional muted description under the heading. Attribute: `description`. */
@@ -1099,7 +1341,7 @@ export interface KaiSettingsGroupElement extends HTMLElement {
 
 export interface KaiSkeletonElement extends HTMLElement {
   /** Color mode (`auto` follows prefers-color-scheme). */
-  theme?: 'light' | 'dark' | 'auto';
+  theme?: "light" | "dark" | "auto";
   /** `text` (one or more lines), `rect` (a block), or `circle` (round). Defaults to `text`. */
   variant?: "text" | "rect" | "circle";
   /** CSS width (e.g. `'12rem'`, `'60%'`). Defaults to full width (responsive); for `circle` it is the diameter. */
@@ -1112,19 +1354,19 @@ export interface KaiSkeletonElement extends HTMLElement {
 
 export interface KaiSkillsElement extends HTMLElement {
   /** Color mode (`auto` follows prefers-color-scheme). */
-  theme?: 'light' | 'dark' | 'auto';
-  /** The active skills to badge. Set as a JS property. */
+  theme?: "light" | "dark" | "auto";
+  /** The active skills to badge. Set as a JS property. Omit to supply them as `<kai-skill>` light-DOM children instead; when both are present the property's skills come first. Nothing renders when there are none. */
   skills: { id: string; name: string }[];
 }
 
 export interface KaiSourceElement extends HTMLElement {
   /** Color mode (`auto` follows prefers-color-scheme). */
-  theme?: 'light' | 'dark' | 'auto';
+  theme?: "light" | "dark" | "auto";
   /** The URL this citation links to (the domain also seeds the default label/favicon). */
   href?: string;
   /** Trigger label (defaults to the domain). */
   label?: string;
-  /** Hover-card headline. Attribute: `headline` (`title` is avoided — it's a global HTML attribute that reflects in a CE constructor and breaks it). */
+  /** Hover-card headline. Attribute: `headline` (`title` is avoided because it is a global HTML attribute that reflects in a CE constructor and breaks it). */
   headline?: string;
   /** Hover-card body text describing the source. */
   description?: string;
@@ -1134,18 +1376,18 @@ export interface KaiSourceElement extends HTMLElement {
 
 export interface KaiSourcesElement extends HTMLElement {
   /** Color mode (`auto` follows prefers-color-scheme). */
-  theme?: 'light' | 'dark' | 'auto';
-  /** The sources to render. Set as a JS property. */
-  sources: { href: string; title?: undefined | string; description?: undefined | string; label?: undefined | string; showFavicon?: undefined | boolean }[];
+  theme?: "light" | "dark" | "auto";
+  /** The sources to render. Set as a JS property. Omit to supply them as `<kai-source>` light-DOM children instead; when both are present the property's sources come first. */
+  sources: { href: string; title?: string; description?: string; label?: string; showFavicon?: boolean }[];
   /** Show favicons on all items (per-item `showFavicon` overrides). */
   showFavicon?: boolean;
-  /** When true, each citation chip is labelled with its 1-based index in the merged (prop + declarative-children) list (`[1]`, `[2]`, …) instead of the per-item `label` or domain fallback. HTML attribute: `numbered` (boolean — bare attribute or `numbered="true"`). JS property: `el.numbered = true`. */
+  /** When true, each citation chip is labelled with its 1-based index in the merged (prop + declarative-children) list (`[1]`, `[2]`, …) instead of the per-item `label` or domain fallback. HTML attribute: `numbered` (boolean: a bare attribute or `numbered="true"`). JS property: `el.numbered = true`. */
   numbered?: boolean;
 }
 
 export interface KaiStatusElement extends HTMLElement {
   /** Color mode (`auto` follows prefers-color-scheme). */
-  theme?: 'light' | 'dark' | 'auto';
+  theme?: "light" | "dark" | "auto";
   /** Presence/notification state → color. `new` (default) maps to the blue hue. */
   status?: "new" | "online" | "busy" | "away" | "offline";
   /** Animated ping ring (off by default; respects prefers-reduced-motion). */
@@ -1158,15 +1400,15 @@ export interface KaiStatusElement extends HTMLElement {
 
 export interface KaiSuggestionsElement extends HTMLElement {
   /** Color mode (`auto` follows prefers-color-scheme). */
-  theme?: 'light' | 'dark' | 'auto';
-  /** The suggestions. Strings, or `{ label, value }` when the displayed text and the emitted value differ. Set as a JS property. */
-  suggestions: (string | { label: string; value?: undefined | string; icon?: undefined | string })[];
+  theme?: "light" | "dark" | "auto";
+  /** The suggestions. Strings, or `{ label, value }` when the displayed text and the emitted value differ. Set as a JS property. Omit to supply them as `<kai-suggestion>` light-DOM children instead; when both are present the property's suggestions come first. */
+  suggestions: (string | { label: string; value?: string; icon?: string })[];
   /** Chip style: `'outline'` (default), `'ghost'`, or `'default'` (filled). */
-  variant?: "default" | "ghost" | "outline";
+  variant?: "outline" | "ghost" | "default";
   /** Row height for `layout="list"`: `'md'` (default) or `'lg'` for taller rows. Chips are unaffected. */
   size?: "md" | "lg";
-  /** Layout: `'chips'` (default) renders a wrapping row of rounded pills; `'list'` renders a vertical, full-width "Ideas for you" list — each row is left-aligned with a leading `icon`, a label, and a hover background. */
-  layout?: "list" | "chips";
+  /** Layout: `'chips'` (default) renders a wrapping row of rounded pills; `'list'` renders a vertical, full-width "Ideas for you" list where each row is left-aligned with a leading `icon`, a label, and a hover background. */
+  layout?: "chips" | "list";
   /** Full-width left-aligned rows instead of pills. */
   block?: boolean;
   /** Substring to highlight within each suggestion. */
@@ -1175,8 +1417,8 @@ export interface KaiSuggestionsElement extends HTMLElement {
 
 export interface KaiSwitchElement extends HTMLElement {
   /** Color mode (`auto` follows prefers-color-scheme). */
-  theme?: 'light' | 'dark' | 'auto';
-  /** Controlled checked state — settable and reflected to the `checked` attribute. `el.checked = true` (or `<kai-switch checked>`) drives it; the toggle UI updates it and fires `kai-change`. Read `el.checked` for live state. */
+  theme?: "light" | "dark" | "auto";
+  /** Controlled checked state. Settable and reflected to the `checked` attribute. `el.checked = true` (or `<kai-switch checked>`) drives it; the toggle UI updates it and fires `kai-change`. Read `el.checked` for live state. */
   checked?: boolean;
   /** Initial checked state on mount (uncontrolled seed). Bare attribute (`<kai-switch default-checked>`) turns it on. */
   defaultChecked?: boolean;
@@ -1188,11 +1430,15 @@ export interface KaiSwitchElement extends HTMLElement {
   name?: string;
   /** Submitted value when checked (paired with `name`). Defaults to `'on'`. */
   value?: string;
+  /** Flip the switch and fire `kai-change` (no-op while disabled). */
+  toggle(): void;
+  /** Focus the inner `role="switch"` button (the host element can't reach it). */
+  focus(options?: FocusOptions): void;
 }
 
 export interface KaiTabsElement extends HTMLElement {
   /** Color mode (`auto` follows prefers-color-scheme). */
-  theme?: 'light' | 'dark' | 'auto';
+  theme?: "light" | "dark" | "auto";
   /** Tabs to render. Set as a JS property, not an HTML attribute. */
   items?: { id: string; label?: string; icon?: string; disabled?: boolean }[];
   /** Controlled selected id. Set as a JS property (or the `value` attribute); drive it from your app in response to `kai-tab-change`. Omit for uncontrolled. */
@@ -1205,13 +1451,17 @@ export interface KaiTabsElement extends HTMLElement {
   block?: boolean;
   /** Disable the whole strip. */
   disabled?: boolean;
+  /** Select a tab by id (fires `kai-tab-change`). Ignores unknown/disabled ids. */
+  select(id: string): void;
+  /** Focus the active tab (or the first focusable tab). */
+  focus(): void;
 }
 
 export interface KaiTasksElement extends HTMLElement {
   /** Color mode (`auto` follows prefers-color-scheme). */
-  theme?: 'light' | 'dark' | 'auto';
+  theme?: "light" | "dark" | "auto";
   /** The tasks definition (the CardEnvelope.data). Set as a JS PROPERTY: `el.data = { tasks:[…], selectAll, confirmLabel, … }`. Import `TasksCardData` from `@kitn.ai/ui` for the full shape. */
-  data?: Record<string, unknown>;
+  data?: { mode?: "select" | "progress"; heading?: string; tasks: { id: string; label: string; description?: string; checked?: boolean; disabled?: boolean }[]; selectAll?: boolean; confirmLabel?: string; allowEmpty?: boolean; min?: number; max?: number; dismissible?: boolean };
   /** Stable card id correlating every emitted CardEvent. Attribute: `card-id`. */
   cardId?: string;
   /** Heading rendered in the card chrome (= CardEnvelope.title). Attribute: `heading`. */
@@ -1226,11 +1476,23 @@ export interface KaiTasksElement extends HTMLElement {
   disabled?: boolean;
   /** Display-only: rows can't be toggled and show the default cursor (no pointer, hover, or focus affordances). Keeps the look as-is. Attribute: `readonly`. */
   readonly?: boolean;
+  /** Set the checked task ids (local-only, no emit), respecting disabled/max. With no arg, select all toggleable rows. */
+  select(taskIds?: string[]): void;
+  /** Toggle one task by id, honoring the max gate (no `checked` = flip). */
+  toggle(taskId: string, checked?: boolean): void;
+  /** Confirm the current selection: emits the `submit` CardEvent + resolves (only when the min/max gate passes). Named `send`, not `submit`. */
+  send(): void;
+  /** Focus the task group (select-all checkbox if shown, else the first row). */
+  focus(options?: FocusOptions): void;
+  /** Trigger the dismiss path (emit `dismiss` + collapse to the re-openable stub). */
+  dismiss(): void;
+  /** Re-open a dismissed card from its stub (emit `reopen`). */
+  reopen(): void;
 }
 
 export interface KaiTextShimmerElement extends HTMLElement {
   /** Color mode (`auto` follows prefers-color-scheme). */
-  theme?: 'light' | 'dark' | 'auto';
+  theme?: "light" | "dark" | "auto";
   /** The text to shimmer. */
   text?: string;
   /** Element tag to render as (default `span`). */
@@ -1243,7 +1505,7 @@ export interface KaiTextShimmerElement extends HTMLElement {
 
 export interface KaiThinkingBarElement extends HTMLElement {
   /** Color mode (`auto` follows prefers-color-scheme). */
-  theme?: 'light' | 'dark' | 'auto';
+  theme?: "light" | "dark" | "auto";
   /** The shimmering label, e.g. "Thinking…". */
   text?: string;
   /** When true, show a "stop" affordance that fires a `stop` event. */
@@ -1254,13 +1516,13 @@ export interface KaiThinkingBarElement extends HTMLElement {
 
 export interface KaiThreadElement extends HTMLElement {
   /** Color mode (`auto` follows prefers-color-scheme). */
-  theme?: 'light' | 'dark' | 'auto';
-  /** The full message thread to render, newest last. Each entry carries its role, content, and optional reasoning/tools/attachments/actions/avatar. Set as a JS property (`el.messages = [...]`); a NEW array reference per streaming chunk re-renders (mutating in place does not). */
-  messages?: { id: string; role: "user" | "assistant"; content: string; reasoning?: { text: string; label?: string }; tools?: { type: string; state: "input-streaming" | "input-available" | "output-available" | "output-error"; input?: Record<string, unknown>; output?: Record<string, unknown>; toolCallId?: string; errorText?: string }[]; attachments?: { id: string; type: "file" | "source-document"; filename?: string; mediaType?: string; url?: string; title?: string }[]; actions?: ("copy" | "like" | "dislike" | "regenerate" | "edit" | { id: string; label: string; icon?: string; tooltip?: string })[]; avatar?: { src?: string; fallback?: string; alt?: string }; feedback?: "like" | "dislike" }[];
-  /** Show a typing indicator on the pending assistant turn — set while awaiting the assistant's reply. */
+  theme?: "light" | "dark" | "auto";
+  /** The full message thread to render, newest last. Each entry carries its role, ordered `parts`, and optional actions/avatar/feedback. Set as a JS property (`el.messages = [...]`); a NEW array reference per streaming chunk re-renders (mutating in place does not). */
+  messages?: { id: string; role: "user" | "assistant"; parts: ({ type: "text"; text: string; raw?: { source: string; payload: unknown } } | { type: "reasoning"; text: string; label?: string; index?: number; streamId?: string; signature?: string; raw?: { source: string; payload: unknown } } | { type: "tool"; tool: { type: string; kind?: "command" | "file-change" | "search" | "fetch" | "mcp" | "image" | "generic"; state: "input-streaming" | "input-available" | "output-available" | "output-error"; input?: Record<string, unknown>; rawInput?: string; output?: Record<string, unknown>; toolCallId?: string; errorText?: string; raw?: { source: string; payload: unknown } }; raw?: { source: string; payload: unknown } } | { type: "card"; envelope: { type: string; id: string; data: unknown; title?: string; resolution?: { kind: "action"; action: string; payload?: unknown; at?: string } | { kind: "submit"; data: unknown; at?: string } | { kind: "dismissed"; at?: string } | { kind: "expired"; reason?: string; at?: string } }; raw?: { source: string; payload: unknown } } | { type: "source"; source: { id?: string; url?: string; title?: string; snippet?: string; index?: number }; raw?: { source: string; payload: unknown } } | { type: "file"; attachment: { id: string; type: "file" | "source-document"; filename?: string; mediaType?: string; url?: string; title?: string }; raw?: { source: string; payload: unknown } })[]; actions?: ("copy" | "like" | "dislike" | "regenerate" | "edit" | { id: string; label: string; icon?: string; tooltip?: string })[]; avatar?: { src?: string; fallback?: string; alt?: string }; feedback?: "like" | "dislike" }[];
+  /** Show a typing indicator on the pending assistant turn. Set it while awaiting the assistant's reply. */
   loading?: boolean;
   /** Body/prose font scale for rendered markdown (`'xs' | 'sm' | 'base' | 'lg'`). Defaults to `'sm'`. */
-  proseSize?: "sm" | "lg" | "xs" | "base";
+  proseSize?: "xs" | "sm" | "base" | "lg";
   /** Shiki theme name for syntax-highlighted code blocks (e.g. `'github-dark-dimmed'`). */
   codeTheme?: string;
   /** Enable Shiki syntax highlighting in code blocks. Turn off to render plain `<pre>` blocks (lighter, no highlighter load). Default true. */
@@ -1271,13 +1533,19 @@ export interface KaiThreadElement extends HTMLElement {
   scrollButton?: boolean;
   /** Extra classes applied to the thread's inner root. */
   class?: string;
+  /** Optional card type -> custom-element tag overrides/additions for `card` parts (merged over the built-ins). Property: `el.cardTypes`. Typed as a plain string map (not the `CardTagMap` alias) so the generated React wrapper inlines it instead of emitting an unresolved named type. */
+  cardTypes?: Record<string, string>;
+  /** 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. */
+  cardSchemas?: Record<string, object>;
+  /** Scroll the message list to the bottom (default `'smooth'`). */
+  scrollToBottom(behavior?: "auto" | "instant" | "smooth"): void;
 }
 
 export interface KaiToastRegionElement extends HTMLElement {
   /** Color mode (`auto` follows prefers-color-scheme). */
-  theme?: 'light' | 'dark' | 'auto';
-  /** The toasts to render. Newest is shown on top. Set as a JS property (array); pass a new array reference to update. */
-  toasts: { id: string; message: string; variant?: undefined | "error" | "info" | "success" | "warning" | "neutral"; appearance?: undefined | "pill" | "card"; inverse?: undefined | boolean; description?: undefined | string; action?: undefined | { label: string; onAction: () => void | false }; duration?: undefined | number; dismissible?: undefined | boolean; target?: undefined | HTMLElement }[];
+  theme?: "light" | "dark" | "auto";
+  /** 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. */
+  toasts: { id: string; message: string; variant?: "neutral" | "success" | "warning" | "error" | "info"; appearance?: "pill" | "card"; inverse?: boolean; description?: string; action?: { label: string; onAction: () => void | false }; duration?: number; dismissible?: boolean; target?: HTMLElement }[];
   /** Stack anchor: `'top-center'` (default), `'top-right'`, `'bottom-center'`, … */
   position?: "top-center" | "top-right" | "top-left" | "bottom-center" | "bottom-right" | "bottom-left";
   /** Max simultaneously-visible toasts; the rest queue. Defaults to `3`. */
@@ -1294,20 +1562,26 @@ export interface KaiToastRegionElement extends HTMLElement {
 
 export interface KaiToolElement extends HTMLElement {
   /** Color mode (`auto` follows prefers-color-scheme). */
-  theme?: 'light' | 'dark' | 'auto';
+  theme?: "light" | "dark" | "auto";
   /** The tool-call to display. Set as a JS property. */
-  tool?: { type: string; state: "input-streaming" | "input-available" | "output-available" | "output-error"; input?: Record<string, unknown>; output?: Record<string, unknown>; toolCallId?: string; errorText?: string };
+  tool?: { type: string; kind?: "command" | "file-change" | "search" | "fetch" | "mcp" | "image" | "generic"; state: "input-streaming" | "input-available" | "output-available" | "output-error"; input?: Record<string, unknown>; rawInput?: string; output?: Record<string, unknown>; toolCallId?: string; errorText?: string; raw?: { source: string; payload: unknown } };
   /** Drive/observe open state (Shoelace-style: settable + reflected to the `open` attribute; the element still self-manages on trigger click). Set `el.open = true`, or `<kai-tool open>`; listen for `kai-open-change`. */
   open?: boolean;
   /** Initial open state on mount (uncontrolled seed). */
   defaultOpen?: boolean;
-  /** Gate the disclosure trigger — programmatic `show()/hide()/toggle()` still work, but the trigger click no longer toggles. */
+  /** Gate the disclosure trigger: programmatic `show()/hide()/toggle()` still work, but the trigger click no longer toggles. */
   disabled?: boolean;
+  /** Open it programmatically (no-op while disabled). */
+  show(): void;
+  /** Close it programmatically. */
+  hide(): void;
+  /** Flip the open state (closes while disabled). */
+  toggle(): void;
 }
 
 export interface KaiTooltipElement extends HTMLElement {
   /** Color mode (`auto` follows prefers-color-scheme). */
-  theme?: 'light' | 'dark' | 'auto';
+  theme?: "light" | "dark" | "auto";
   /** The hint text shown on hover/focus of the slotted trigger. */
   content?: string;
   /** Delay (ms) before the tooltip appears on hover. Defaults to 600. Focus shows it immediately regardless. */
@@ -1322,12 +1596,18 @@ export interface KaiTooltipElement extends HTMLElement {
   defaultOpen?: boolean;
   /** Turn the tooltip off while keeping the trigger mounted (hover/focus and `show()` no longer open it). */
   disabled?: boolean;
+  /** Open it programmatically (no-op while disabled). */
+  show(): void;
+  /** Close it programmatically. */
+  hide(): void;
+  /** Flip the open state (closes while disabled). */
+  toggle(): void;
 }
 
 export interface KaiVoiceInputElement extends HTMLElement {
   /** Color mode (`auto` follows prefers-color-scheme). */
-  theme?: 'light' | 'dark' | 'auto';
-  /** 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. */
+  theme?: "light" | "dark" | "auto";
+  /** 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. */
   transcribe?: (audio: Blob) => Promise<string>;
   /** Disable the mic button (non-interactive). */
   disabled?: boolean;
@@ -1335,38 +1615,50 @@ export interface KaiVoiceInputElement extends HTMLElement {
   recognitionLang?: string;
   /** Emit live partial transcripts (`kai-transcript-interim`) during native recognition. Attribute: `interim`. No-op on the transcribe/fallback paths. */
   interim?: boolean;
+  /** Begin recording programmatically (e.g. push-to-talk bound to a global key). Runs the same getUserMedia path as clicking the mic; no-ops if already recording. */
+  start(): void;
+  /** Stop the in-progress recording, producing the blob (→ kai-audio-captured) and running transcription. Pairs with start() for push-to-talk. */
+  stop(): void;
 }
 
 export interface KaiVoiceOutputElement extends HTMLElement {
   /** Color mode (`auto` follows prefers-color-scheme). */
-  theme?: 'light' | 'dark' | 'auto';
+  theme?: "light" | "dark" | "auto";
   /** The utterance to read aloud. */
   text?: string;
   /** Speak automatically when `text` is set/changed. */
   autoplay?: boolean;
-  /** 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. */
+  /** 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. */
   synthesize?: (text: string) => Promise<Blob>;
   /** Disable the button (non-interactive). */
   disabled?: boolean;
+  /** Speak the current `text` (native, or via `synthesize` if set). */
+  speak(): void;
+  /** Pause playback (resumable). */
+  pause(): void;
+  /** Resume paused playback. */
+  resume(): void;
+  /** Stop playback and reset. */
+  stop(): void;
 }
 
 export interface KaiWorkspaceElement extends HTMLElement {
   /** Color mode (`auto` follows prefers-color-scheme). */
-  theme?: 'light' | 'dark' | 'auto';
-  /** Pre-bucketed conversation groups for the sidebar. Set as a JS property. */
-  groups: { id: string; userId?: undefined | string; teamId?: undefined | string; name: string; sortOrder: number; createdAt: string }[];
-  /** Flat conversation list (auto-bucketed if `groups` is empty). Set as a JS property. */
-  conversations: { id: string; title: string; groupId?: undefined | string; scope: { type: "document" | "collection"; documentId?: undefined | string; filters?: undefined | { tags?: undefined | string[]; authors?: undefined | string[]; contentType?: undefined | "transcript" | "markdown"; dateRange?: undefined | { from: string; to: string } } }; messageCount: number; lastMessageAt: string; updatedAt: string; trailing?: undefined | string }[];
+  theme?: "light" | "dark" | "auto";
+  /** The sidebar's section headers, rendered in array order. A group carries no conversations of its own; it is matched against `conversations` by id, so the two props are complementary rather than alternatives. Omit for an ungrouped sidebar. Set as a JS property. */
+  groups: { id: string; userId?: string; teamId?: string; name: string; sortOrder: number; createdAt: string }[];
+  /** Every conversation in the sidebar, flat. Each one is filed under the group whose `id` equals its `groupId`; one with no `groupId`, or with a `groupId` matching no entry in `groups`, falls into a trailing ungrouped section (headerless when `compact`), so nothing you pass in is ever dropped. There is no recency bucketing. Set as a JS property. Omit for an empty sidebar, or when `no-conversations` replaces the built-in list with your own `sidebar-header` content. */
+  conversations: { id: string; title: string; groupId?: string; scope: { type: "document" | "collection"; documentId?: string; filters?: { tags?: string[]; authors?: string[]; contentType?: "transcript" | "markdown"; dateRange?: { from: string; to: string } } }; messageCount: number; lastMessageAt: string; updatedAt: string; trailing?: string }[];
   /** Id of the open conversation, highlighted in the sidebar. */
   activeId?: string;
-  /** The active conversation's message thread, newest last. Set as a JS property. */
-  messages: { id: string; role: "user" | "assistant"; content: string; reasoning?: undefined | { text: string; label?: undefined | string }; tools?: undefined | { type: string; state: "input-streaming" | "input-available" | "output-available" | "output-error"; input?: undefined | Record<string, unknown>; output?: undefined | Record<string, unknown>; toolCallId?: undefined | string; errorText?: undefined | string }[]; attachments?: undefined | { id: string; type: "file" | "source-document"; filename?: undefined | string; mediaType?: undefined | string; url?: undefined | string; title?: undefined | string }[]; actions?: undefined | ("copy" | "like" | "dislike" | "regenerate" | "edit" | { id: string; label: string; icon?: undefined | string; tooltip?: undefined | string })[]; avatar?: undefined | { src?: undefined | string; fallback?: undefined | string; alt?: undefined | string }; feedback?: undefined | "like" | "dislike" }[];
+  /** The active conversation's message thread, newest last. Set as a JS property (`el.messages = [...]`); a NEW array reference per streaming chunk re-renders (mutating in place does not). Omit for an empty thread. */
+  messages: { id: string; role: "user" | "assistant"; parts: ({ type: "text"; text: string; raw?: { source: string; payload: unknown } } | { type: "reasoning"; text: string; label?: string; index?: number; streamId?: string; signature?: string; raw?: { source: string; payload: unknown } } | { type: "tool"; tool: { type: string; kind?: "command" | "file-change" | "search" | "fetch" | "mcp" | "image" | "generic"; state: "input-streaming" | "input-available" | "output-available" | "output-error"; input?: Record<string, unknown>; rawInput?: string; output?: Record<string, unknown>; toolCallId?: string; errorText?: string; raw?: { source: string; payload: unknown } }; raw?: { source: string; payload: unknown } } | { type: "card"; envelope: { type: string; id: string; data: unknown; title?: string; resolution?: { kind: "action"; action: string; payload?: unknown; at?: string } | { kind: "submit"; data: unknown; at?: string } | { kind: "dismissed"; at?: string } | { kind: "expired"; reason?: string; at?: string } }; raw?: { source: string; payload: unknown } } | { type: "source"; source: { id?: string; url?: string; title?: string; snippet?: string; index?: number }; raw?: { source: string; payload: unknown } } | { type: "file"; attachment: { id: string; type: "file" | "source-document"; filename?: string; mediaType?: string; url?: string; title?: string }; raw?: { source: string; payload: unknown } })[]; actions?: ("copy" | "like" | "dislike" | "regenerate" | "edit" | { id: string; label: string; icon?: string; tooltip?: string })[]; avatar?: { src?: string; fallback?: string; alt?: string }; feedback?: "like" | "dislike" }[];
   value?: string;
   placeholder?: string;
   loading?: boolean;
   suggestions?: string[];
   suggestionMode?: "submit" | "fill";
-  proseSize?: "sm" | "lg" | "xs" | "base";
+  proseSize?: "xs" | "sm" | "base" | "lg";
   codeTheme?: string;
   codeHighlight?: boolean;
   chatTitle?: string;
@@ -1396,6 +1688,24 @@ export interface KaiWorkspaceElement extends HTMLElement {
   compact?: boolean;
   /** Suppress the built-in ConversationList so the `sidebar-header` slot owns the whole rail flex region (for apps that supply their own rail nav). Default false. Attribute: `no-conversations`. */
   noConversations?: boolean;
+  /** Optional card type -> custom-element tag overrides/additions for `card` parts (merged over the built-ins). Property: `el.cardTypes`. Typed as a plain string map (not the `CardTagMap` alias) so the generated React wrapper inlines it instead of emitting an unresolved named type. */
+  cardTypes?: Record<string, string>;
+  /** 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. */
+  cardSchemas?: Record<string, object>;
+  /** Collapse/expand the conversation sidebar and fire `kai-sidebar-toggle`. */
+  toggleSidebar(): void;
+  /** Force the conversation sidebar collapsed (fires `kai-sidebar-toggle`). */
+  collapseSidebar(): void;
+  /** Force the conversation sidebar expanded (fires `kai-sidebar-toggle`). */
+  expandSidebar(): void;
+  /** Focus the thread's composer. */
+  focus(options?: FocusOptions): void;
+  /** Clear the thread draft + staged attachments. */
+  clear(): void;
+  /** Submit the current thread draft programmatically (fires `kai-submit`). */
+  send(): void;
+  /** Scroll the thread to the newest message. */
+  scrollToBottom(behavior?: "auto" | "instant" | "smooth"): void;
 }
 
 declare global {
@@ -1482,3 +1792,2118 @@ declare global {
     'kai-workspace': KaiWorkspaceElement;
   }
 }
+
+interface KaiElementJsxProps {
+  id?: string;
+  class?: string;
+  className?: string;
+  style?: Record<string, string | number> | string;
+  slot?: string;
+  part?: string;
+  children?: unknown;
+  ref?: unknown;
+  [attr: string]: unknown;
+}
+
+declare module 'react' {
+  namespace JSX {
+    interface IntrinsicElements {
+      'kai-agent-card': KaiElementJsxProps;
+      'kai-artifact': KaiElementJsxProps;
+      'kai-attachments': KaiElementJsxProps;
+      'kai-audio-visualizer': KaiElementJsxProps;
+      'kai-avatar': KaiElementJsxProps;
+      'kai-badge': KaiElementJsxProps;
+      'kai-button': KaiElementJsxProps;
+      'kai-card': KaiElementJsxProps;
+      'kai-cards': KaiElementJsxProps;
+      'kai-chain-of-thought': KaiElementJsxProps;
+      'kai-chat': KaiElementJsxProps;
+      'kai-checkpoint': KaiElementJsxProps;
+      'kai-choice': KaiElementJsxProps;
+      'kai-coachmark': KaiElementJsxProps;
+      'kai-code-block': KaiElementJsxProps;
+      'kai-command': KaiElementJsxProps;
+      'kai-compare': KaiElementJsxProps;
+      'kai-composer': KaiElementJsxProps;
+      'kai-confirm': KaiElementJsxProps;
+      'kai-context': KaiElementJsxProps;
+      'kai-conversations': KaiElementJsxProps;
+      'kai-dialog': KaiElementJsxProps;
+      'kai-editable-label': KaiElementJsxProps;
+      'kai-embed': KaiElementJsxProps;
+      'kai-empty': KaiElementJsxProps;
+      'kai-feedback-bar': KaiElementJsxProps;
+      'kai-file-tree': KaiElementJsxProps;
+      'kai-file-upload': KaiElementJsxProps;
+      'kai-form': KaiElementJsxProps;
+      'kai-hover-card': KaiElementJsxProps;
+      'kai-icon': KaiElementJsxProps;
+      'kai-image': KaiElementJsxProps;
+      'kai-input': KaiElementJsxProps;
+      'kai-kbd': KaiElementJsxProps;
+      'kai-link-preview': KaiElementJsxProps;
+      'kai-loader': KaiElementJsxProps;
+      'kai-markdown': KaiElementJsxProps;
+      'kai-menu': KaiElementJsxProps;
+      'kai-message': KaiElementJsxProps;
+      'kai-model-switcher': KaiElementJsxProps;
+      'kai-nav': KaiElementJsxProps;
+      'kai-notice': KaiElementJsxProps;
+      'kai-pane': KaiElementJsxProps;
+      'kai-pane-group': KaiElementJsxProps;
+      'kai-popover': KaiElementJsxProps;
+      'kai-progress-bar': KaiElementJsxProps;
+      'kai-prompt-dock': KaiElementJsxProps;
+      'kai-prompt-input': KaiElementJsxProps;
+      'kai-reasoning': KaiElementJsxProps;
+      'kai-remote': KaiElementJsxProps;
+      'kai-resizable': KaiElementJsxProps;
+      'kai-resizable-item': KaiElementJsxProps;
+      'kai-response-stream': KaiElementJsxProps;
+      'kai-scope-picker': KaiElementJsxProps;
+      'kai-screen': KaiElementJsxProps;
+      'kai-scroll-area': KaiElementJsxProps;
+      'kai-scroll-button': KaiElementJsxProps;
+      'kai-search': KaiElementJsxProps;
+      'kai-segmented': KaiElementJsxProps;
+      'kai-separator': KaiElementJsxProps;
+      'kai-setting-item': KaiElementJsxProps;
+      'kai-settings-group': KaiElementJsxProps;
+      'kai-skeleton': KaiElementJsxProps;
+      'kai-skills': KaiElementJsxProps;
+      'kai-source': KaiElementJsxProps;
+      'kai-sources': KaiElementJsxProps;
+      'kai-status': KaiElementJsxProps;
+      'kai-suggestions': KaiElementJsxProps;
+      'kai-switch': KaiElementJsxProps;
+      'kai-tabs': KaiElementJsxProps;
+      'kai-tasks': KaiElementJsxProps;
+      'kai-text-shimmer': KaiElementJsxProps;
+      'kai-thinking-bar': KaiElementJsxProps;
+      'kai-thread': KaiElementJsxProps;
+      'kai-toast-region': KaiElementJsxProps;
+      'kai-tool': KaiElementJsxProps;
+      'kai-tooltip': KaiElementJsxProps;
+      'kai-voice-input': KaiElementJsxProps;
+      'kai-voice-output': KaiElementJsxProps;
+      'kai-workspace': KaiElementJsxProps;
+    }
+  }
+}
+
+export interface KaiAgentCardElementProps {
+  /** Color mode (`auto` follows prefers-color-scheme). */
+  theme?: "light" | "dark" | "auto";
+  /** The agent's name, the primary label. Attribute: `name`. */
+  name?: string;
+  /** Selected / focused state: highlighted border + surface. Attribute: `active`. */
+  active?: boolean;
+  /** Raise a prominent "Needs you" pill plus a glowing amber edge. This is the attention-routing signal that pulls focus to this agent. Attribute: `needs-attention`. */
+  needsAttention?: boolean;
+  /** Run status. A JS PROPERTY (object), not an attribute. Shape: `{ tone, label?, pulse? }`, where `tone` is one of `working` | `idle` | `done` | `error` | `blocked` (maps to the kit's tool hues), `label` is an optional short string beside the dot, and `pulse` animates the dot. Set it with `el.status = { tone: 'working', label: 'Working', pulse: true }`. */
+  status?: { tone: "working" | "idle" | "done" | "error" | "blocked"; label?: string; pulse?: boolean };
+}
+
+export interface KaiArtifactElementProps {
+  /** Color mode (`auto` follows prefers-color-scheme). */
+  theme?: "light" | "dark" | "auto";
+  /** URL the preview iframe frames. Consumer-controlled. */
+  src?: string;
+  /** Files for the Code tab tree + each file's preview `url`. Omit for a preview-only artifact (the Code tab then has nothing to show; pair it with `no-tabs` to hide the toggle). Set as a JS property (array). */
+  files?: { path: string; url?: string; code?: string; language?: string; type?: "html" | "pdf" | "image" | "other"; additions?: number; deletions?: number; status?: "added" | "modified" | "deleted" | "renamed" | "untracked" }[];
+  /** Controlled active tab: `preview` or `code`. When set, the artifact follows it (re-asserted on change). Leave unset for an uncontrolled tab (see `defaultTab`). */
+  tab?: "preview" | "code";
+  /** Uncontrolled INITIAL tab (used only when `tab` is unset). Default `preview`. Seeds the starting tab; the user can then switch freely without the consumer re-asserting a controlled `tab`. */
+  defaultTab?: "preview" | "code";
+  /** Selected file path. Syncs the tree highlight, Code source, and preview. */
+  activeFile?: string;
+  /** iframe `sandbox` override. Secure default `allow-scripts allow-forms` (NOT `allow-same-origin`). */
+  sandbox?: string;
+  /** Accessible title for the preview iframe. */
+  iframeTitle?: string;
+  /** Reflects the artifact's own maximized view-state (usually driven by the protocol). */
+  maximized?: boolean;
+  /** Show the expand-to-fill button (OPT-IN). */
+  expandable?: boolean;
+  /** Show the open-in-new-tab button (OPT-IN). */
+  openInTab?: boolean;
+  /** Hide back/forward. */
+  noNav?: boolean;
+  /** Hide reload. */
+  noReload?: boolean;
+  /** Hide home. */
+  noHome?: boolean;
+  /** Hide the address field. */
+  noPathField?: boolean;
+  /** Hide the Preview|Code toggle. */
+  noTabs?: boolean;
+  /** Standalone chrome: rounded corners + border (else square, borderless in-panel). */
+  standalone?: boolean;
+  /** Show the address but make it read-only (visible, nav-tracking, non-editable). */
+  readonlyPath?: boolean;
+  /** Friendly address shown in the path field instead of the real current url (read-only, non-navigable). Use when the framed url is not consumer-facing (e.g. a `data:` blob) so a clean address shows instead of leaking it. Scalar string: set as the `display-url` attribute or the `displayUrl` property. */
+  displayUrl?: string;
+}
+
+export interface KaiAttachmentsElementProps {
+  /** Color mode (`auto` follows prefers-color-scheme). */
+  theme?: "light" | "dark" | "auto";
+  /** 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). */
+  items?: { id: string; type: "file" | "source-document"; filename?: string; mediaType?: string; url?: string; title?: string }[];
+  /** Layout: `grid` = visual tiles, `inline` = icon + label chips, `list` = rows. */
+  variant?: "grid" | "inline" | "list";
+  /** Wrap each item in a hover card that previews its details. */
+  hoverCard?: boolean;
+  /** Show a remove button per item; clicking it fires a `kai-remove` event. */
+  removable?: boolean;
+  /** Also show the media type beneath the filename (non-grid variants). */
+  showMediaType?: boolean;
+  /** Text shown when `items` is empty. */
+  emptyText?: string;
+}
+
+export interface KaiAudioVisualizerElementProps {
+  /** Color mode (`auto` follows prefers-color-scheme). */
+  theme?: "light" | "dark" | "auto";
+  /** Look to render: `bar` (default), `grid`, `radial`, `wave`, `aurora`, `custom`. `aura` is accepted as a LiveKit-markup alias for `aurora`. Attribute: `variant`. */
+  variant?: string;
+  /** `idle` (default), `connecting`, `listening`, `thinking`, `speaking`, `disconnected` (connection down: the dead, flat look). LiveKit's room-lifecycle state names are accepted as aliases. Attribute: `state`. */
+  state?: string;
+  /** `icon` | `sm` | `md` (default) | `lg` | `xl`. Attribute: `size`. */
+  size?: string;
+  /** Bars to draw. Bar and radial only. Attribute: `bar-count`. */
+  barCount?: number;
+  /** Grid only: rows and columns of the (always square) grid. Attribute: `count`. */
+  count?: number;
+  /** Radial only: ring distance from center, in px. Attribute: `radius`. */
+  radius?: number;
+  /** Grid only: ring distance for the connecting animation, in cells. Attribute: `spread`. */
+  spread?: number;
+  /** Grid only: ms between scripted frames. Attribute: `interval`. */
+  interval?: number;
+  /** CSS color for the geometry, overriding the inherited `currentColor`. Attribute: `color`. */
+  color?: string;
+  /** Shader variants only: pattern density, 0..1. Attribute: `complexity`. */
+  complexity?: number;
+  /** Setting this makes the element an announced image (`role="img"`) instead of decorative (`aria-hidden`). Attribute: `label`. */
+  label?: string;
+  /** Live microphone or WebRTC audio to analyze. JS property only. */
+  stream?: MediaStream;
+  /** An `<audio>` or `<video>` element to tap for its audio. JS property only. */
+  audioElement?: HTMLMediaElement;
+  /** Pre-computed levels, 0..1. Set this and no AudioContext is ever built, which is what keeps headless/SSR rendering and browser-speech-synthesis playback (which exposes no audio node) free of Web Audio entirely. JS property only. A new array reference is required for each update; mutating the existing array in place will not re-render. */
+  bands?: number[];
+  /** Custom fragment shader for `variant="custom"`. JS property only. */
+  shader?: { fragment: string; uniforms?: Record<string, { type: "1f" | "1i" | "1fv" | "2f" | "3f" | "3fv" | "4f" | "4fv" | "Matrix2fv" | "Matrix3fv" | "Matrix4fv"; value: number | number[] }> };
+  /** Shader variants only: keep animating while scrolled off screen. Off by default, which stops drawing and releases the WebGL context until the element comes back (browsers ration contexts to roughly 16 a page). Does not override `prefers-reduced-motion`. Attribute: `animate-when-not-visible`. */
+  animateWhenNotVisible?: boolean;
+}
+
+export interface KaiAvatarElementProps {
+  /** Color mode (`auto` follows prefers-color-scheme). */
+  theme?: "light" | "dark" | "auto";
+  /** Image URL/data-URI. When absent, the `fallback` initials show instead. */
+  src?: string;
+  /** Alt text for the image. Defaults to `fallback`. */
+  alt?: string;
+  /** Short text shown when there's no image, usually initials (e.g. "JD", "AI"). */
+  fallback?: string;
+  /** Size token: `sm` | `md` (default) | `lg`. */
+  size?: "sm" | "md" | "lg";
+}
+
+export interface KaiBadgeElementProps {
+  /** Color mode (`auto` follows prefers-color-scheme). */
+  theme?: "light" | "dark" | "auto";
+  /** `default` (muted pill) · `count` (compact number badge) · `citation` (filled primary, for inline citation markers). Defaults to `default`. */
+  variant?: "default" | "count" | "citation";
+}
+
+export interface KaiButtonElementProps {
+  /** Color mode (`auto` follows prefers-color-scheme). */
+  theme?: "light" | "dark" | "auto";
+  /** Visual style. `default` (filled), `subtle` (muted text, hover tint, the toolbar icon look), `ghost` (transparent, hover fill), `outline`, or `destructive`. Defaults to `default`. */
+  variant?: "default" | "subtle" | "ghost" | "outline" | "destructive";
+  /** Size token. `icon` / `icon-sm` are square (for icon-only buttons); `sm` / `md` / `lg` size text buttons. Defaults to `md`. */
+  size?: "sm" | "md" | "lg" | "icon" | "icon-sm";
+  /** Leading icon: a named icon (e.g. `"mic"`, `"plus"`), an image URL/data-URI, or plain text. Renders before any slotted label. */
+  icon?: string;
+  /** Trailing icon, after the label (e.g. `"chevron-down"` for a menu affordance). */
+  iconTrailing?: string;
+  /** Accessible name. REQUIRED for icon-only buttons (no visible text); ignored when you slot visible text, which already names the button. */
+  label?: string;
+  /** Disable the button (non-interactive, dimmed). */
+  disabled?: boolean;
+  /** Stretch the button to the full width of its container (a block button), e.g. a card CTA or a stacked action. Attribute: `full`. */
+  full?: boolean;
+  /** Justify the button's content: `start`, `center` (default), or `end`. Combine with `full` for a full-width, left-aligned button. */
+  align?: "start" | "center" | "end";
+  /** Native button `type`. Defaults to `button` (so it never submits a form). */
+  type?: "button" | "submit" | "reset";
+}
+
+export interface KaiCardElementProps {
+  /** Color mode (`auto` follows prefers-color-scheme). */
+  theme?: "light" | "dark" | "auto";
+  /** Surface treatment: `outlined` (default) | `filled` | `plain` | `accent`. Attribute: `appearance`. */
+  appearance?: "outlined" | "filled" | "plain" | "accent";
+  /** `vertical` (default, media on top) | `horizontal` (media at the start) | `responsive` (horizontal when the card's container is wide enough, else vertical, via a container query on the card's own width). Attribute: `orientation`. */
+  orientation?: "vertical" | "horizontal" | "responsive";
+  /** The card width below which a `responsive` card collapses to vertical and the footer actions stack. A CSS length; default `28rem`. Attribute: `collapse`. */
+  collapse?: string;
+  /** Tighter spacing for dense lists. Attribute: `dense`. */
+  dense?: boolean;
+  /** Show a close (×) that hides the card and emits `kai-dismiss`. Attribute: `dismissible`. Off by default. */
+  dismissible?: boolean;
+  /** Render the whole card as a link. Attribute: `href`. Wins over `clickable`. */
+  href?: string;
+  /** `target` for the `href` anchor. Attribute: `target`. */
+  target?: string;
+  /** `rel` for the `href` anchor. Attribute: `rel`. */
+  rel?: string;
+  /** Make the whole card a button (`role="button"`, Enter/Space, hover affordance) that emits `kai-card-click`. Attribute: `clickable`. Ignored when `href` is set. */
+  clickable?: boolean;
+}
+
+export interface KaiCardsElementProps {
+  /** Color mode (`auto` follows prefers-color-scheme). */
+  theme?: "light" | "dark" | "auto";
+  /** The stream of card envelopes to render. Set as a JS PROPERTY: `el.cards = [...]`. */
+  cards?: { type: string; id: string; data: unknown; title?: string; resolution?: { kind: "action"; action: string; payload?: unknown; at?: string } | { kind: "submit"; data: unknown; at?: string } | { kind: "dismissed"; at?: string } | { kind: "expired"; reason?: string; at?: string } }[];
+  /** Optional type→tag overrides/additions (merged over the built-ins). Property: `el.types`. Typed as a plain string map (not the `CardTagMap` alias) so the generated React wrapper inlines it instead of emitting an unresolved named type. */
+  types?: Record<string, string>;
+  /** JSON Schemas for the card types this app renders, keyed by envelope type. The companion of `types`, which says what DRAWS a card while this says what a VALID one looks like. An OBJECT, so it is a JS property only: `el.schemas = { 'pricing-table': pricingSchema }`, never an attribute. `createCardRegistry(...).validationSchemas` is exactly this shape. Without it the kit validates its own seven built-ins and leaves your own card type, the one your app actually cares about, as the only unchecked thing on screen. A schema here WINS over a built-in of the same name, matching `mergeCardTags`, where your entry is spread over ours. Typed `Record<string, object>` rather than `Record<string, JsonSchema>` deliberately: an imported `.json` schema widens `"type"` to `string`, and an authored one carries `$schema`/`title`/`description`/`additionalProperties`, so the tighter type would reject both of the normal ways to supply one. See `CardSchemaMap` in components/card-renderer.tsx. */
+  schemas?: Record<string, object>;
+  /** Optional CardPolicy handling child events. Property: `el.policy`. */
+  policy?: { onSubmit?: (cardId: string, data: unknown) => void; onAction?: (cardId: string, action: string, payload?: unknown) => void; onSendPrompt?: (text: string, opts: { mode: "compose" | "send"; context?: unknown; }) => void; onOpen?: (url: string, target: "tab" | "artifact") => void; onState?: (cardId: string, patch: unknown) => void; onDismiss?: (cardId: string) => void; onReopen?: (cardId: string) => void; onError?: (cardId: string, message: string) => void; maxSendPromptMode?: "compose" | "send" };
+  /** Validate each envelope's `data` against the schema for its type before rendering it, using a built-in's own schema or yours from `schemas`. Default `true`; set `validate-cards="false"` (or `el.validateCards = false`) to opt out. A hard failure (wrong type, a missing required field) renders a diagnostic naming the field instead of the card; a soft failure (bounds) renders the card unchanged. Both emit a contract `error` event. On in production too: a model emitting a bad shape is a production failure mode, so stripping the check there would hide it from exactly the person who needs to see it. */
+  validateCards?: boolean;
+}
+
+export interface KaiChainOfThoughtElementProps {
+  /** Color mode (`auto` follows prefers-color-scheme). */
+  theme?: "light" | "dark" | "auto";
+  /** The reasoning steps. Set as a JS property. Compound sub-parts collapse to this one data model (Route 1). Each `{ label, content?, id? }`. Omit to supply the steps as `<kai-step>` light-DOM children instead; when both are present the property's steps come first. */
+  steps?: { label: string; content?: string; id?: string }[];
+  /** Open mode: `'multiple'` (default, any number of steps open at once) or `'single'` (at most one open; opening a step closes the others). */
+  type?: "single" | "multiple";
+  /** Controlled open step key(s). When set, it WINS over user interaction (the consumer owns the open set). String in `single` mode, string[] in `multiple` mode. Set as a JS property. */
+  value?: string | string[];
+  /** Uncontrolled INITIAL open step key(s), seeding which steps render expanded. Ignored once `value` is provided. Set as a JS property. */
+  defaultValue?: string | string[];
+}
+
+export interface KaiChatElementProps {
+  /** Color mode (`auto` follows prefers-color-scheme). */
+  theme?: "light" | "dark" | "auto";
+  /** Show a Search (Globe) button in the input toolbar; fires a `search` event. */
+  search?: boolean;
+  /** Value of the input. A **string** is controlled (the host owns the text and updates it on `kai-value-change`). A **ComposerDoc** is a one-time seed that pre-populates pills; the user then edits freely. Leave unset for uncontrolled. */
+  value?: string | ({ type: "text"; text: string } | { type: "entity"; entity: { kind: string; id: string; label: string; icon?: string; promptText?: string; data?: Record<string, unknown> } })[];
+  /** Placeholder text shown in the empty input. */
+  placeholder?: string;
+  /** When true, shows the loading/streaming state and disables submit (use while awaiting the assistant's reply). */
+  loading?: boolean;
+  /** Starter prompts shown above the input when the thread is empty. Clicking one follows `suggestionMode`. Set as a JS property. */
+  suggestions?: string[];
+  /** What clicking a suggestion does: `'submit'` (default) sends it immediately as if typed and submitted; `'fill'` just places it in the input. */
+  suggestionMode?: "submit" | "fill";
+  /** Keep suggestions visible after the conversation starts. By default suggestions are conversation starters and hide once `messages` is non-empty; set this to keep them always shown. Default false. */
+  persistSuggestions?: boolean;
+  /** Body/prose font scale for rendered markdown (`'xs' | 'sm' | 'base' | 'lg'`). Defaults to `'sm'`. */
+  proseSize?: "xs" | "sm" | "base" | "lg";
+  /** Shiki theme name for syntax-highlighted code blocks (e.g. `'github-dark-dimmed'`). */
+  codeTheme?: string;
+  /** Enable Shiki syntax highlighting in code blocks. Turn off to render plain `<pre>` blocks (lighter, no highlighter load). Default true. */
+  codeHighlight?: boolean;
+  /** Optional header title shown on the left of the header. */
+  chatTitle?: string;
+  /** Optional model list. When set (>1 model) a ModelSwitcher is shown in the header and a `kai-model-change` event fires on selection. */
+  models?: { id: string; name: string; provider?: string; description?: string; group?: string }[];
+  /** The currently selected model id (pairs with `models`). */
+  currentModel?: string;
+  /** Optional context-window token usage. When set, a Context token meter is shown in the header. */
+  context?: { usedTokens: number; maxTokens: number; inputTokens?: number; outputTokens?: number; estimatedCost?: number };
+  /** Show the scroll-to-bottom button inside the scroll area. Default true. */
+  scrollButton?: boolean;
+  /** Whether the host has `slot="header-start"` content (left of the title). Set by the `<kai-chat>` facade so a custom control forces the header open. */
+  headerStart?: boolean;
+  /** Whether the host has `slot="header-end"` content (right of the controls). */
+  headerEnd?: boolean;
+  /** REPLACE: full custom header in place of the built-in title/model/context bar. */
+  headerFull?: boolean;
+  /** INJECT: left sidebar column (e.g. a conversation list / your own nav). */
+  sidebar?: boolean;
+  /** REPLACE: custom zero-state rendered in the message area while the thread is empty (replaces the empty message list only; the composer and its suggestions still render). */
+  empty?: boolean;
+  /** REPLACE: full custom composer in place of the built-in prompt input. The projected content wires its own submit (the data-flow boundary). */
+  composer?: boolean;
+  /** INJECT: accessory row just above the composer (e.g. extra actions). */
+  composerActions?: boolean;
+  /** INJECT: footer row below the composer (disclaimers, token meter, …). */
+  footer?: boolean;
+  /** Show a Voice (Mic) button in the input toolbar; fires a `voice` event. */
+  voice?: boolean;
+  /** Rich entity triggers. Each `{ char, kind, items }` opens a caret-anchored menu that inserts an atomic pill (`/` skills, `@` agents/plugins). Set as a JS property; forwarded to the input. */
+  triggers?: { char: string; kind: string; items?: { id: string; label: string; icon?: string; description?: string; group?: string; kind?: string; promptText?: string; data?: Record<string, unknown> }[] }[];
+  /** Default icon per entity kind (kind → image src) for pills/menu items. */
+  kindIcons?: Record<string, string>;
+  /** Whether each message's action bar is always visible (`'always'`, default) or only revealed on hover of that message row (`'hover'`). */
+  actionsReveal?: "always" | "hover";
+  /** The full message thread to render, newest last. Each entry carries its role, ordered `parts`, and optional actions/avatar/feedback. Set as a JS property (`el.messages = [...]`); a NEW array reference per streaming chunk re-renders (mutating in place does not). Omit for an empty thread. Re-declared here (rather than inherited from `ChatThreadProps`) because the ELEMENT registers a `[]` default and renders the empty state without it, while the SolidJS `<ChatThread>` component still requires it. The facade hands it a validated array either way. Matches `<kai-thread>`. */
+  messages?: { id: string; role: "user" | "assistant"; parts: ({ type: "text"; text: string; raw?: { source: string; payload: unknown } } | { type: "reasoning"; text: string; label?: string; index?: number; streamId?: string; signature?: string; raw?: { source: string; payload: unknown } } | { type: "tool"; tool: { type: string; kind?: "command" | "file-change" | "search" | "fetch" | "mcp" | "image" | "generic"; state: "input-streaming" | "input-available" | "output-available" | "output-error"; input?: Record<string, unknown>; rawInput?: string; output?: Record<string, unknown>; toolCallId?: string; errorText?: string; raw?: { source: string; payload: unknown } }; raw?: { source: string; payload: unknown } } | { type: "card"; envelope: { type: string; id: string; data: unknown; title?: string; resolution?: { kind: "action"; action: string; payload?: unknown; at?: string } | { kind: "submit"; data: unknown; at?: string } | { kind: "dismissed"; at?: string } | { kind: "expired"; reason?: string; at?: string } }; raw?: { source: string; payload: unknown } } | { type: "source"; source: { id?: string; url?: string; title?: string; snippet?: string; index?: number }; raw?: { source: string; payload: unknown } } | { type: "file"; attachment: { id: string; type: "file" | "source-document"; filename?: string; mediaType?: string; url?: string; title?: string }; raw?: { source: string; payload: unknown } })[]; actions?: ("copy" | "like" | "dislike" | "regenerate" | "edit" | { id: string; label: string; icon?: string; tooltip?: string })[]; avatar?: { src?: string; fallback?: string; alt?: string }; feedback?: "like" | "dislike" }[];
+  /** Optional card type -> custom-element tag overrides/additions for `card` parts (merged over the built-ins). Property: `el.cardTypes`. Typed as a plain string map (not the `CardTagMap` alias) so the generated React wrapper inlines it instead of emitting an unresolved named type. */
+  cardTypes?: Record<string, string>;
+  /** 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. */
+  cardSchemas?: Record<string, object>;
+}
+
+export interface KaiCheckpointElementProps {
+  /** Color mode (`auto` follows prefers-color-scheme). */
+  theme?: "light" | "dark" | "auto";
+  /** Optional text beside the icon. */
+  label?: string;
+  /** Tooltip on hover. */
+  tooltip?: string;
+  /** Visual button style. */
+  variant?: "ghost" | "default" | "outline";
+  /** Button size (use an `icon*` size for an icon-only checkpoint). */
+  size?: "sm" | "md" | "lg" | "icon" | "icon-sm";
+}
+
+export interface KaiChoiceElementProps {
+  /** Color mode (`auto` follows prefers-color-scheme). */
+  theme?: "light" | "dark" | "auto";
+  /** 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. */
+  data?: { prompt?: string; options: { id: string; label: string; description?: string; media?: { image?: string; imageAlt?: string; icon?: string }; meta?: string; recommended?: boolean; disabled?: boolean; payload?: unknown }[]; allowOther?: boolean | { label?: string; placeholder?: string }; submitLabel?: string; dismissible?: boolean };
+  /** Stable card id correlating every emitted CardEvent. Attribute: `card-id`. */
+  cardId?: string;
+  /** Heading rendered in the card chrome (= CardEnvelope.title). Attribute: `heading`. */
+  heading?: string;
+  /** Set when the user resolved this card; renders the read-only view. Property: `el.resolution = { kind:'action', action:'…' }`. */
+  resolution?: Record<string, unknown>;
+  /** Controlled selection: the selected option id. When set, the consumer owns the current pick (RadioGroup `value`). Attribute: `value`. */
+  value?: string;
+  /** Option id to pre-select on mount (uncontrolled seed). Attribute: `default-value`. */
+  defaultValue?: string;
+  /** Disable the whole radiogroup + Submit (e.g. while the agent is busy). Attribute: `disabled`. */
+  disabled?: boolean;
+}
+
+export interface KaiCoachmarkElementProps {
+  /** Color mode (`auto` follows prefers-color-scheme). */
+  theme?: "light" | "dark" | "auto";
+  /** Drive/observe open state (Shoelace-style: settable + reflected to the `open` attribute; the element still self-manages). Set `el.open = true`, or `<kai-coachmark open>`; listen for `kai-open-change`. */
+  open?: boolean;
+  /** Initial open state on mount (uncontrolled seed). */
+  defaultOpen?: boolean;
+  /** The bold title. Named `headline` because `title` collides with the global `HTMLElement.title` attribute (it throws at registration). */
+  headline?: string;
+  /** A small badge pill beside the headline (e.g. "New"). */
+  badge?: string;
+  /** Floating placement relative to the anchor (default `bottom`). */
+  placement?: string;
+  /** Color tone: `primary` (default, theme accent), `info` (blue), `success` (green), `warning` (amber), or `error` (red), reusing the kit's tool hues. */
+  tone?: "primary" | "info" | "success" | "warning" | "error";
+  /** Render the arrow that points at the anchor (default `true`). Set `arrow="false"` for a plain bubble with no pointer. */
+  arrow?: boolean;
+}
+
+export interface KaiCodeBlockElementProps {
+  /** Color mode (`auto` follows prefers-color-scheme). */
+  theme?: "light" | "dark" | "auto";
+  /** The source code to render. */
+  code: string;
+  /** Language grammar (e.g. `js`, `python`). Defaults to `tsx`. */
+  language?: string;
+  /** Shiki theme name. */
+  codeTheme?: string;
+  /** Disable syntax highlighting (renders plain text, no Shiki). */
+  codeHighlight?: boolean;
+  /** Code text sizing. */
+  proseSize?: "xs" | "sm" | "base" | "lg";
+}
+
+export interface KaiCommandElementProps {
+  /** Color mode (`auto` follows prefers-color-scheme). */
+  theme?: "light" | "dark" | "auto";
+  /** Flat list of items. Set as a JS property, not an HTML attribute. */
+  items?: { id: string; label: string; icon?: string; description?: string; shortcut?: string; group?: string }[];
+  /** Placeholder text for the search input. */
+  placeholder?: string;
+  /** Label shown when no items match the current query. */
+  emptyLabel?: string;
+}
+
+export interface KaiCompareElementProps {
+  /** Color mode (`auto` follows prefers-color-scheme). */
+  theme?: "light" | "dark" | "auto";
+  /** The compare definition (prompt + the two candidates). Set as a JS PROPERTY: `el.data = { prompt, candidates: [A, B], collapse? }`. Import `ResponseCompareData` from `@kitn.ai/ui` for the full shape. */
+  data?: Record<string, unknown>;
+  /** Stable id correlating every emitted event. Attribute: `compare-id`. */
+  compareId?: string;
+  /** Re-hydrate / control the user's pick. Set as a JS PROPERTY: `el.selection = { chosenId, rejectedIds }`. Renders the collapsed winner. */
+  selection?: Record<string, unknown>;
+  /** Layout: `'auto'` (default, columns when wide, tabs when narrow, by CONTAINER width) | `'columns'` (side-by-side) | `'tabs'` (pills to switch). Attribute: `layout`. */
+  layout?: "auto" | "columns" | "tabs";
+  /** Prose/text size for the rendered candidates. Attribute: `prose-size`. */
+  proseSize?: "xs" | "sm" | "base" | "lg";
+  /** Shiki theme for code blocks in the candidates. Attribute: `code-theme`. */
+  codeTheme?: string;
+  /** Whether code blocks are syntax-highlighted. Attribute: `code-highlight`. */
+  codeHighlight?: boolean;
+}
+
+export interface KaiComposerElementProps {
+  /** Color mode (`auto` follows prefers-color-scheme). */
+  theme?: "light" | "dark" | "auto";
+  /** Controlled value: a string or a full ComposerDoc (set as JS property). */
+  value?: string | ({ type: "text"; text: string } | { type: "entity"; entity: { kind: string; id: string; label: string; icon?: string; promptText?: string; data?: Record<string, unknown> } })[];
+  /** Placeholder text shown when the composer is empty. */
+  placeholder?: string;
+  /** Disable the composer entirely (non-interactive). */
+  disabled?: boolean;
+  /** Show a loading/streaming state and block submit. */
+  loading?: boolean;
+  /** Maximum height in px before the content scrolls. Default 240. */
+  maxHeight?: number | string;
+  /** Whether pressing Enter (without Shift) submits. Default true. */
+  submitOnEnter?: boolean;
+  /** Trigger definitions. Set as a JS property. */
+  triggers?: { char: string; kind: string; items?: { id: string; label: string; icon?: string; description?: string; group?: string; kind?: string; promptText?: string; data?: Record<string, unknown> }[] }[];
+  /** Keyword highlight rules. Set as a JS property. */
+  highlights?: (string | { pattern: string; flags?: string; class?: string })[];
+  /** Default icon per entity kind (kind → image URL/data-URI) for items without their own `icon`. Overrides the built-in agent/plugin glyphs. JS property. */
+  kindIcons?: Record<string, string>;
+}
+
+export interface KaiConfirmElementProps {
+  /** Color mode (`auto` follows prefers-color-scheme). */
+  theme?: "light" | "dark" | "auto";
+  /** The confirm definition (the CardEnvelope.data). Set as a JS PROPERTY: `el.data = { body, tone, actions:[…] }`. Import `ConfirmCardData` from `@kitn.ai/ui` for the full shape. */
+  data?: { heading?: string; body?: string; tone?: "default" | "warning" | "danger"; actions: { id: string; label: string; style?: "primary" | "default" | "destructive"; payload?: unknown; default?: boolean }[]; dismissible?: boolean };
+  /** Stable card id correlating every emitted CardEvent. Attribute: `card-id`. */
+  cardId?: string;
+  /** Heading rendered in the card chrome (= CardEnvelope.title). Attribute: `heading`. */
+  heading?: string;
+  /** Focus the default action on mount (off by default, so nothing steals focus). Attribute: `autofocus`. */
+  autofocus?: boolean;
+  /** Set when the user resolved this card; renders the read-only view. Property: `el.resolution = { kind:'action', action:'…' }`. */
+  resolution?: Record<string, unknown>;
+}
+
+export interface KaiContextElementProps {
+  /** Color mode (`auto` follows prefers-color-scheme). */
+  theme?: "light" | "dark" | "auto";
+  /** Token-usage data. Set as a JS property. */
+  context?: { usedTokens: number; maxTokens: number; inputTokens?: number; outputTokens?: number; reasoningTokens?: number; cacheTokens?: number; estimatedCost?: number };
+  /** Fraction (0–1) above which the meter turns yellow. Defaults to `0.7` (70%). */
+  warnThreshold?: number;
+  /** Fraction (0–1) above which the meter turns red. Defaults to `0.9` (90%). */
+  dangerThreshold?: number;
+}
+
+export interface KaiConversationsElementProps {
+  /** Color mode (`auto` follows prefers-color-scheme). */
+  theme?: "light" | "dark" | "auto";
+  /** The list's section headers (`{ id, name, sortOrder, createdAt }`), rendered in array order. A group carries no conversations of its own; it is matched against `conversations` by id, so the two props are complementary rather than alternatives. Omit for an ungrouped list. Set as a JS property. */
+  groups?: { id: string; userId?: string; teamId?: string; name: string; sortOrder: number; createdAt: string }[];
+  /** 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. */
+  conversations?: { id: string; title: string; groupId?: string; scope: { type: "document" | "collection"; documentId?: string; filters?: { tags?: string[]; authors?: string[]; contentType?: "transcript" | "markdown"; dateRange?: { from: string; to: string } } }; messageCount: number; lastMessageAt: string; updatedAt: string; trailing?: string }[];
+  /** The id of the currently-open conversation, highlighted in the list. */
+  activeId?: string;
+  /** Controlled collapsed state. Set as a JS property (`el.collapsed = true`) to drive the rail from your app, updating it in response to `kai-collapse-toggle`. Omit for uncontrolled (the element manages it). Collapsed shrinks the rail to a floating reopen button. */
+  collapsed?: boolean;
+  /** Initial collapsed state when uncontrolled (default false). Use the `default-collapsed` attribute to start collapsed in plain HTML. */
+  defaultCollapsed?: boolean;
+}
+
+export interface KaiDialogElementProps {
+  /** Color mode (`auto` follows prefers-color-scheme). */
+  theme?: "light" | "dark" | "auto";
+  /** Drive/observe open state (Shoelace-style: settable + reflected to the `open` attribute; the element still self-manages on Escape/backdrop). Set `el.open = true`, or `<kai-dialog open>`; listen for `kai-open-change`. */
+  open?: boolean;
+  /** Initial open state on mount (uncontrolled seed). */
+  defaultOpen?: boolean;
+}
+
+export interface KaiEditableLabelElementProps {
+  /** Color mode (`auto` follows prefers-color-scheme). */
+  theme?: "light" | "dark" | "auto";
+  /** The label text. Settable and reflected to the `value` attribute. Read `el.value` for live state. */
+  value?: string;
+  /** Controlled edit state. `el.editing = true` opens the field; reflected to the `editing` attribute. */
+  editing?: boolean;
+  /** Placeholder shown while editing / when the value is empty. */
+  placeholder?: string;
+  /** Disable entering edit mode. */
+  disabled?: boolean;
+}
+
+export interface KaiEmbedElementProps {
+  /** Color mode (`auto` follows prefers-color-scheme). */
+  theme?: "light" | "dark" | "auto";
+  /** Stable card id correlating every emitted event. Set as an attribute or property. */
+  cardId?: string;
+  /** The embed payload (provider + id/url + options). Set as a JS **property** (object). */
+  data?: { provider: "youtube" | "vimeo" | "generic"; id?: string; url?: string; title?: string; poster?: string; start?: number; aspectRatio?: "16:9" | "4:3" | "1:1" | "9:16" };
+}
+
+export interface KaiEmptyElementProps {
+  /** Color mode (`auto` follows prefers-color-scheme). */
+  theme?: "light" | "dark" | "auto";
+  /** Title text. Attribute: `empty-title` (`title` is a global HTML attribute). */
+  emptyTitle?: string;
+  /** Description text. */
+  description?: string;
+}
+
+export interface KaiFeedbackBarElementProps {
+  /** Color mode (`auto` follows prefers-color-scheme). */
+  theme?: "light" | "dark" | "auto";
+  /** The banner label (e.g. "Was this helpful?"). Attribute: `bar-title` (`title` is avoided because it is a global HTML attribute). */
+  barTitle?: string;
+  /** When set, a not-helpful vote opens an optional detail form before the thank-you confirmation. Attribute: `collect-detail`. */
+  collectDetail?: boolean;
+  /** Optional category chips for the detail form. Set as a JS property (array). */
+  categories?: string[];
+  /** Heading for the detail form. Attribute: `detail-title`. */
+  detailTitle?: string;
+  /** Placeholder for the detail comment box. Attribute: `detail-placeholder`. */
+  detailPlaceholder?: string;
+  /** Submit button label in the detail form. Attribute: `submit-label`. */
+  submitLabel?: string;
+  /** Confirmation copy shown after a vote/submit. Attribute: `thanks-message`. */
+  thanksMessage?: string;
+}
+
+export interface KaiFileTreeElementProps {
+  /** Color mode (`auto` follows prefers-color-scheme). */
+  theme?: "light" | "dark" | "auto";
+  /** The files to render. Set as a JS property (array of `{ path, url?, code?, language?, type?, additions?, deletions?, status? }`). */
+  files: { path: string; url?: undefined | string; code?: undefined | string; language?: undefined | string; type?: undefined | "html" | "pdf" | "image" | "other"; additions?: undefined | number; deletions?: undefined | number; status?: undefined | "added" | "modified" | "deleted" | "renamed" | "untracked" }[];
+  /** Selected file path, highlighted in the tree. */
+  activeFile?: string;
+  /** Folder paths expanded initially. Omit to start with all folders open. */
+  defaultExpanded?: string[];
+  /** Show a changed-files summary header (file count + summed `+/-` + Collapse-all). Attribute: `summary`. Off by default. */
+  summary?: boolean;
+}
+
+export interface KaiFileUploadElementProps {
+  /** Color mode (`auto` follows prefers-color-scheme). */
+  theme?: "light" | "dark" | "auto";
+  /** Allow selecting multiple files (default true). */
+  multiple?: boolean;
+  /** `accept` attribute for the file picker (e.g. `image/*`). */
+  accept?: string;
+  /** Disable the dropzone: no clicking, no drag-and-drop. */
+  disabled?: boolean;
+  /** Default dropzone label (overridable via the default slot). */
+  label?: string;
+}
+
+export interface KaiFormElementProps {
+  /** Color mode (`auto` follows prefers-color-scheme). */
+  theme?: "light" | "dark" | "auto";
+  /** 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. */
+  data?: { type: "object"; title?: string; description?: string; required?: string[]; properties: Record<string, { type: "string" | "number" | "integer" | "boolean" | "array" | "object"; title?: string; description?: string; default?: unknown; enum?: unknown[]; format?: "email" | "uri" | "url" | "date" | "date-time" | "time"; minimum?: number; maximum?: number; minLength?: number; maxLength?: number; pattern?: string; minItems?: number; maxItems?: number; items?: Record<string, unknown> | { enum: unknown[] }; properties?: Record<string, Record<string, unknown>>; required?: string[]; readOnly?: boolean; "x-kai-widget"?: "textarea" | "slider" | "rating" | "radio" | "select" | "checkbox" | "password" | "switch"; "x-kai-placeholder"?: string; "x-kai-step"?: number }>; "x-kai-order"?: string[]; "x-kai-inlineMax"?: number; "x-kai-submitLabel"?: string; "x-kai-dismissible"?: boolean; "x-kai-actions"?: { id: string; label: string; variant?: "default" | "ghost" | "outline" }[] };
+  /** Stable card id correlating every emitted CardEvent. Attribute: `card-id`. */
+  cardId?: string;
+  /** Heading rendered in the card chrome (= CardEnvelope.title). Attribute: `heading`. */
+  heading?: string;
+  /** Set when the user resolved this card; renders the read-only view. Property: `el.resolution = { kind:'submit', data:{…} }`. */
+  resolution?: Record<string, unknown>;
+  /** Controlled field values (JS property). When set, it wins over local edits. */
+  values?: Record<string, unknown>;
+  /** Initial values overlaying the schema defaults (uncontrolled seed; JS property). */
+  defaultValues?: Record<string, unknown>;
+  /** Disable all fields + submit. Attribute: `disabled`. */
+  disabled?: boolean;
+}
+
+export interface KaiHoverCardElementProps {
+  /** Color mode (`auto` follows prefers-color-scheme). */
+  theme?: "light" | "dark" | "auto";
+  /** Delay (ms) before the card opens on hover. Defaults to 0 (focus opens it immediately too). */
+  openDelay?: number;
+  /** Delay (ms) before it closes after the pointer leaves. Defaults to 300. */
+  closeDelay?: number;
+  /** Preferred placement: `'top' | 'bottom' | 'left' | 'right'` (+ optional `-start`/`-end`). Defaults to `'bottom'`; flips to stay in view. */
+  placement?: string;
+  /** Drive/observe open state (Shoelace-style: settable + reflected to the `open` attribute, the element still self-manages on hover). Set `el.open = true`, or `<kai-hover-card open>`; listen for `kai-open-change`. */
+  open?: boolean;
+  /** Initial open state on mount (uncontrolled seed). */
+  defaultOpen?: boolean;
+  /** Suppress the hover behavior entirely without unmounting. */
+  disabled?: boolean;
+}
+
+export interface KaiIconElementProps {
+  /** Color mode (`auto` follows prefers-color-scheme). */
+  theme?: "light" | "dark" | "auto";
+  /** A curated icon name (e.g. `"mic"`, `"globe"`), an image URL/data-URI, or plain text. */
+  name?: string;
+  /** Size token: `sm` | `md` (default) | `lg`. */
+  size?: "sm" | "md" | "lg";
+}
+
+export interface KaiImageElementProps {
+  /** Color mode (`auto` follows prefers-color-scheme). */
+  theme?: "light" | "dark" | "auto";
+  /** Base64-encoded image data (pair with `media-type`). */
+  base64?: string;
+  /** Raw image bytes (set as a JS property). */
+  bytes?: Uint8Array;
+  /** Alt text. */
+  alt?: string;
+  /** MIME type (default `image/png`). */
+  mediaType?: string;
+}
+
+export interface KaiInputElementProps {
+  /** Color mode (`auto` follows prefers-color-scheme). */
+  theme?: "light" | "dark" | "auto";
+  /** Native input type: `text` (default) · `email` · `url` · `search` · `tel` · `password` · `number`. Single-line only. */
+  type?: string;
+  /** 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. */
+  value?: string;
+  /** Placeholder shown when empty. */
+  placeholder?: string;
+  /** Field label, linked to the input. */
+  label?: string;
+  /** Helper text below the control. */
+  hint?: string;
+  /** Error text; flips the field invalid (`aria-invalid` + destructive border). */
+  error?: string;
+  /** Control density: `sm` or `md`. Defaults to `md`. */
+  size?: "sm" | "md";
+  /** Disable interaction. */
+  disabled?: boolean;
+  /** Make the input read-only. */
+  readonly?: boolean;
+  /** Mark the input required. */
+  required?: boolean;
+  /** Force the invalid state without an `error` string. */
+  invalid?: boolean;
+  /** Form-control name. */
+  name?: string;
+  /** Autofill hint forwarded to the inner input (e.g. `email`, `current-password`). */
+  autocomplete?: string;
+  /** Virtual-keyboard hint forwarded to the inner input (e.g. `numeric`, `email`). */
+  inputmode?: string;
+}
+
+export interface KaiKbdElementProps {
+  /** Color mode (`auto` follows prefers-color-scheme). */
+  theme?: "light" | "dark" | "auto";
+  /** Shortcut spec: tokens joined by `+` (e.g. `Mod+Shift+K`). Omit it to show default-slot content instead. Display only; the element does not bind keys. */
+  keys?: string;
+  /** `mac` uses ⌘/⌥, `other` uses Ctrl. `auto` (default) sniffs the OS. */
+  platform?: "auto" | "mac" | "other";
+  /** Cap size: `sm` or `md`. Defaults to `md`. */
+  size?: "sm" | "md";
+}
+
+export interface KaiLinkPreviewElementProps {
+  /** Color mode (`auto` follows prefers-color-scheme). */
+  theme?: "light" | "dark" | "auto";
+  /** Stable card id correlating every emitted event. Set as an attribute or property. */
+  cardId?: string;
+  /** The link payload (OG metadata). Set as a JS **property** (object). */
+  data?: { url: string; title?: string; description?: string; image?: string; imageAlt?: string; favicon?: string; domain?: string; siteName?: string };
+}
+
+export interface KaiLoaderElementProps {
+  /** Color mode (`auto` follows prefers-color-scheme). */
+  theme?: "light" | "dark" | "auto";
+  /** The animation style: `'circular' | 'classic' | 'pulse' | 'pulse-dot' | 'dots' | 'typing' | 'wave' | 'bars' | 'terminal' | 'text-blink' | 'text-shimmer' | 'loading-dots'`. Defaults to `'circular'`. */
+  variant?: "circular" | "classic" | "pulse" | "pulse-dot" | "dots" | "typing" | "wave" | "bars" | "terminal" | "text-blink" | "text-shimmer" | "loading-dots";
+  /** Loader size: `'sm' | 'md' | 'lg'`. Defaults to `'md'`. */
+  size?: "sm" | "md" | "lg";
+  /** Label for the text-based variants. */
+  text?: string;
+}
+
+export interface KaiMarkdownElementProps {
+  /** Color mode (`auto` follows prefers-color-scheme). */
+  theme?: "light" | "dark" | "auto";
+  /** The markdown source to render. */
+  content: string;
+  /** Text/markdown sizing. */
+  proseSize?: "xs" | "sm" | "base" | "lg";
+  /** Shiki theme for fenced code blocks. */
+  codeTheme?: string;
+  /** Disable syntax highlighting (no Shiki loads). */
+  codeHighlight?: boolean;
+}
+
+export interface KaiMenuElementProps {
+  /** Color mode (`auto` follows prefers-color-scheme). */
+  theme?: "light" | "dark" | "auto";
+  /** Tree of menu items. Set as a JS property, not an HTML attribute. */
+  items?: { id?: string; label?: string; icon?: string; shortcut?: string; checked?: boolean; radioGroup?: string; disabled?: boolean; separator?: boolean; heading?: boolean; items?: Record<string, unknown>[] }[];
+  /** Optional placement hint (unused by the underlying Dropdown which always positions bottom-start, kept for future extension). */
+  placement?: string;
+  /** Built-in trigger: leading icon (a named icon like `"plus"`, an image URL/data-URI, or text). Use this instead of slotting `slot="trigger"` for the common case; a slotted trigger overrides it. */
+  triggerIcon?: string;
+  /** Built-in trigger: a text label (e.g. `"High"`). */
+  triggerLabel?: string;
+  /** Built-in trigger: a trailing icon (e.g. `"chevron-down"` for a select look). */
+  triggerIconTrailing?: string;
+  /** Accessible name for an icon-only trigger (no visible label). */
+  label?: string;
+  /** Drive/observe open state (Shoelace-style: settable + reflected to the `open` attribute, the menu still self-manages on click/keyboard). Set `el.open = true`, or `<kai-menu open>`; listen for `kai-open-change`. */
+  open?: boolean;
+  /** Initial open state on mount (uncontrolled seed). */
+  defaultOpen?: boolean;
+  /** Disable the trigger: click/keyboard and `show()` no longer open the menu. */
+  disabled?: boolean;
+}
+
+export interface KaiMessageElementProps {
+  /** Color mode (`auto` follows prefers-color-scheme). */
+  theme?: "light" | "dark" | "auto";
+  /** The full message object. Set as a JS property. */
+  message?: { id: string; role: "user" | "assistant"; parts: ({ type: "text"; text: string; raw?: { source: string; payload: unknown } } | { type: "reasoning"; text: string; label?: string; index?: number; streamId?: string; signature?: string; raw?: { source: string; payload: unknown } } | { type: "tool"; tool: { type: string; kind?: "command" | "file-change" | "search" | "fetch" | "mcp" | "image" | "generic"; state: "input-streaming" | "input-available" | "output-available" | "output-error"; input?: Record<string, unknown>; rawInput?: string; output?: Record<string, unknown>; toolCallId?: string; errorText?: string; raw?: { source: string; payload: unknown } }; raw?: { source: string; payload: unknown } } | { type: "card"; envelope: { type: string; id: string; data: unknown; title?: string; resolution?: { kind: "action"; action: string; payload?: unknown; at?: string } | { kind: "submit"; data: unknown; at?: string } | { kind: "dismissed"; at?: string } | { kind: "expired"; reason?: string; at?: string } }; raw?: { source: string; payload: unknown } } | { type: "source"; source: { id?: string; url?: string; title?: string; snippet?: string; index?: number }; raw?: { source: string; payload: unknown } } | { type: "file"; attachment: { id: string; type: "file" | "source-document"; filename?: string; mediaType?: string; url?: string; title?: string }; raw?: { source: string; payload: unknown } })[]; actions?: ("copy" | "like" | "dislike" | "regenerate" | "edit" | { id: string; label: string; icon?: string; tooltip?: string })[]; avatar?: { src?: string; fallback?: string; alt?: string }; feedback?: "like" | "dislike" };
+  /** Who is speaking: `'user'` or `'assistant'`. Convenience for simple cases when not passing a `message` object. This is the SEMANTIC role of the message, not an ARIA role. The name collides with the global ARIA `role` attribute, which is why the facade lifts it off the host (see `liftRoleOffHost`). Neither speaker is a valid ARIA role, so a `role="user"` left on `<kai-message>` is a CRITICAL axe `aria-roles` violation. The accessible role lives on the row inside the shadow root instead: `role="article"` plus an `aria-label` naming the speaker, matching the SolidJS `<Message>` component. */
+  role?: "user" | "assistant";
+  /** Force markdown on/off. Defaults to on for assistant, off for user. */
+  markdown?: boolean;
+  /** Text/markdown sizing for the message body. */
+  proseSize?: "xs" | "sm" | "base" | "lg";
+  /** Shiki theme name used for fenced code blocks in the content. */
+  codeTheme?: string;
+  /** Disable syntax highlighting for code blocks (no Shiki loads). */
+  codeHighlight?: boolean;
+  /** Whether the action bar is always visible (`'always'`, default) or only revealed on hover of the message row (`'hover'`). */
+  actionsReveal?: "always" | "hover";
+  /** Convenience avatar image URL (used when `message.avatar` is not set). */
+  avatarSrc?: string;
+  /** Convenience avatar fallback text (used when `message.avatar` is not set). */
+  avatarFallback?: string;
+  /** Avatar rail mode. `'none'` omits the avatar rail entirely so the body spans the full row (predictable layout when you never show avatars). Any other value keeps the default behaviour: the built-in avatar when one resolves, or your `slot="avatar"` content when projected (which REPLACES the built-in). */
+  avatar?: string;
+  /** Optional card type -> custom-element tag overrides/additions for `card` parts (merged over the built-ins). Property: `el.cardTypes`. Typed as a plain string map (not the `CardTagMap` alias) so the generated React wrapper inlines it instead of emitting an unresolved named type. */
+  cardTypes?: Record<string, string>;
+  /** 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. */
+  cardSchemas?: Record<string, object>;
+}
+
+export interface KaiModelSwitcherElementProps {
+  /** Color mode (`auto` follows prefers-color-scheme). */
+  theme?: "light" | "dark" | "auto";
+  /** The selectable models. Set as a JS property (array). Omit to supply them as `<kai-model>` light-DOM children instead; when both are present the property's models come first. */
+  models?: { id: string; name: string; provider?: string; description?: string; group?: string }[];
+  /** The currently-selected model id. Defaults to the first model. */
+  currentModel?: string;
+  /** Drive/observe the dropdown's open state (Shoelace-style: settable + reflected to the `open` attribute, the dropdown still self-manages on click/keyboard). Set `el.open = true`, or `<kai-model-switcher open>`; listen for `kai-open-change`. */
+  open?: boolean;
+  /** Initial open state on mount (uncontrolled seed). */
+  defaultOpen?: boolean;
+  /** Disable the trigger: click/keyboard and `show()` no longer open the dropdown. */
+  disabled?: boolean;
+}
+
+export interface KaiNavElementProps {
+  /** Color mode (`auto` follows prefers-color-scheme). */
+  theme?: "light" | "dark" | "auto";
+  /** The nav items. Set as a JS property (array, not an attribute). Each item may carry `children` (a collapsible group), a `status` dot, and trailing `meta` text. */
+  items?: { id: string; label?: string; icon?: string; badge?: string; trailing?: string; disabled?: boolean; children?: Record<string, unknown>[]; status?: { tone: "primary" | "info" | "success" | "warning" | "error" | "neutral"; label?: string; pulse?: boolean }; meta?: string; action?: { icon: string; label: string }; closable?: boolean }[];
+  /** Active item id (controlled). */
+  value?: string;
+  /** Initial active id when uncontrolled. */
+  defaultValue?: string;
+  /** Ids of group items collapsed on first render (groups default to expanded). Set as a JS property (array). */
+  defaultCollapsed?: string[];
+}
+
+export interface KaiNoticeElementProps {
+  /** Color mode (`auto` follows prefers-color-scheme). */
+  theme?: "light" | "dark" | "auto";
+  /** `neutral` (default) · `info` · `warning` · `error` · `success`. Drives the leading icon's color and the a11y role (`alert` for errors, else `status`). */
+  severity?: "neutral" | "info" | "warning" | "error" | "success";
+  /** Leading icon: omit for the severity default, `"none"` to hide it, or a named icon to override. */
+  icon?: string;
+  /** Show a dismiss (×) that hides the notice and emits `kai-dismiss`. */
+  dismissible?: boolean;
+}
+
+export interface KaiPaneElementProps {
+  /** Color mode (`auto` follows prefers-color-scheme). */
+  theme?: "light" | "dark" | "auto";
+  /** The pane title (the agent / window name). Named `headline` because `title` collides with the global `HTMLElement.title` attribute (it throws at registration). Attribute: `headline`. */
+  headline?: string;
+  /** A role / label shown under the title (e.g. "Reviewer", "claude-sonnet"). Attribute: `subtitle`. */
+  subtitle?: string;
+  /** Show the restore glyph instead of maximize, and signal the maximized view-state. Drive it yourself in response to `kai-maximize`. Attribute: `maximized`. */
+  maximized?: boolean;
+  /** Highlight the frame with a ring/border to mark the ACTIVE pane. Attribute: `focused`. */
+  focused?: boolean;
+  /** Show a split-pane window control that fires `kai-split`. Off by default. Attribute: `show-split`. */
+  showSplit?: boolean;
+  /** Show a dock-to-side window control that fires `kai-dock`. Off by default. Attribute: `show-dock`. */
+  showDock?: boolean;
+  /** A tone-colored status dot (+ optional label) in the header. An object `{ tone, label?, pulse? }` set as a JS PROPERTY (not an attribute). */
+  status?: { tone: "working" | "idle" | "done" | "error" | "blocked"; label?: string; pulse?: boolean };
+}
+
+export interface KaiPaneGroupElementProps {
+  /** Color mode (`auto` follows prefers-color-scheme). */
+  theme?: "light" | "dark" | "auto";
+  /** The tabs to render. An array of `{ id, name, status?, needsAttention?, number? }` set as a JS PROPERTY (not an HTML attribute). */
+  tabs?: { id: string; name: string; status?: { tone: "working" | "idle" | "done" | "error" | "blocked"; label?: string; pulse?: boolean }; needsAttention?: boolean; number?: number }[];
+  /** The active tab id (controlled, and reflected to the `active` ATTRIBUTE so `::part`/`[active]` selectors and the per-tab named slot follow it). Set it as the `active` attribute or drive it from `kai-tab-change`; omit for uncontrolled (the first tab). */
+  active?: string;
+  /** Highlight the frame as the ACTIVE group in a multi-group layout. Attribute: `focused`. */
+  focused?: boolean;
+}
+
+export interface KaiPopoverElementProps {
+  /** Color mode (`auto` follows prefers-color-scheme). */
+  theme?: "light" | "dark" | "auto";
+  /** Floating placement relative to the trigger (floating-ui placement). */
+  placement?: "top" | "right" | "bottom" | "left" | "bottom-end" | "bottom-start" | "left-end" | "left-start" | "right-end" | "right-start" | "top-end" | "top-start";
+  /** Gap in px between the trigger and the panel. */
+  gutter?: number;
+  /** Drive/observe open state (Shoelace-style: settable + reflected to the `open` attribute, the element still self-manages on click). Set `el.open = true`, or `<kai-popover open>`; listen for `kai-open-change`. */
+  open?: boolean;
+  /** Initial open state on mount (uncontrolled seed). */
+  defaultOpen?: boolean;
+  /** Turn the popover off while keeping the trigger mounted (clicks and `show()` no longer open it). */
+  disabled?: boolean;
+}
+
+export interface KaiProgressBarElementProps {
+  /** Color mode (`auto` follows prefers-color-scheme). */
+  theme?: "light" | "dark" | "auto";
+  /** Current progress value (0..max). Attribute: `value`. */
+  value?: number;
+  /** The value `value` runs to (default 100). Attribute: `max`. */
+  max?: number;
+  /** Optional caption above the track. Attribute: `label`. */
+  label?: string;
+  /** Fill color: `primary` (default), `success`, `warning`, `error`, `info`. Attribute: `tone`. */
+  tone?: string;
+}
+
+export interface KaiPromptDockElementProps {
+  /** Color mode (`auto` follows prefers-color-scheme). */
+  theme?: "light" | "dark" | "auto";
+  /** How the tray frames the input, the SPATIAL inset axis: `inset` (default, the classic recessed frame on every side) | `edge` (top/bottom inset only; the input sits flush left/right so the lips span the full width) | `none` (no inset; the lips attach directly as a plain stack). Attribute: `frame`. */
+  frame?: "inset" | "edge" | "none";
+  /** How the tray surface looks, the VISUAL axis orthogonal to `frame`: `soft` (default, sunken surface + border + radius) | `outlined` (transparent + border + radius) | `filled` (sunken, no border, + radius) | `plain` (bare). Attribute: `appearance`. */
+  appearance?: "soft" | "outlined" | "filled" | "plain";
+}
+
+export interface KaiPromptInputElementProps {
+  /** Color mode (`auto` follows prefers-color-scheme). */
+  theme?: "light" | "dark" | "auto";
+  /** Value of the input, as a JS property. A **string** is the controlled text mirror (the host owns it and updates on `kai-value-change`). A **ComposerDoc** (array of text/entity segments) is a one-time **seed** that pre-populates pills (skills/agents/plugins); the user then edits freely. Leave unset for uncontrolled behavior. `kai-submit`/`kai-value-change` always emit `value` as the flattened string (back-compat) plus the structured `doc` + `entities`. */
+  value?: string | ({ type: "text"; text: string } | { type: "entity"; entity: { kind: string; id: string; label: string; icon?: string; promptText?: string; data?: Record<string, unknown> } })[];
+  /** Placeholder text shown in the empty input. */
+  placeholder?: string;
+  /** Disable the input and submit button entirely (non-interactive). */
+  disabled?: boolean;
+  /** Show the loading/streaming state and block submit (use while awaiting a reply). */
+  loading?: boolean;
+  /** Starter prompts shown above the input. Clicking one follows `suggestionMode`. Set as a JS property. */
+  suggestions?: string[];
+  /** What clicking a suggestion does: `'submit'` (default) sends it immediately as if typed and submitted; `'fill'` just places it in the input. */
+  suggestionMode?: "submit" | "fill";
+  /** Show a Search (Globe) button in the left toolbar; clicking it fires a `search` event. */
+  search?: boolean;
+  /** Show a Voice (Mic) button in the left toolbar; clicking it fires a `voice` event. */
+  voice?: boolean;
+  /** When set and `loading` is true, the send button is replaced by a Stop button (square icon, "Stop" aria-label). Clicking it fires `kai-stop`. */
+  stoppable?: boolean;
+  /** Send-button visibility. `'always'` (default) always shows it; `'auto'` shows it only when there's text/attachments (an empty composer hides it, though Enter still submits). To hide it entirely (Enter-only), it's pure CSS: `::part(send){display:none}`, no prop needed. Restyle via `::part(send)`. The Stop button (`stoppable` + `loading`) is unaffected. */
+  submit?: "always" | "auto";
+  /** When `false`, hides the built-in paperclip attach button even though the element otherwise supports attachments. Use this when a `+` menu in `toolbar-start` already exposes "Add files", to avoid a duplicate control. Defaults to `true`. */
+  attach?: boolean;
+  /** 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). */
+  attachments?: { id: string; type: "file" | "source-document"; filename?: string; mediaType?: string; url?: string; title?: string }[];
+  /** Rich entity triggers. Each `{ char, kind, items }` opens a caret-anchored menu that inserts an atomic pill. Convention: `/` → skills, `@` → agents (plugins are the grouping/provenance of those items). Set as a JS property. */
+  triggers?: { char: string; kind: string; items?: { id: string; label: string; icon?: string; description?: string; group?: string; kind?: string; promptText?: string; data?: Record<string, unknown> }[] }[];
+  /** Default icon per entity kind (kind → image URL/data-URI) for pills/menu items without their own `icon`. Overrides the built-in agent/plugin glyphs. JS property. */
+  kindIcons?: Record<string, string>;
+}
+
+export interface KaiReasoningElementProps {
+  /** Color mode (`auto` follows prefers-color-scheme). */
+  theme?: "light" | "dark" | "auto";
+  /** The reasoning text to display. */
+  text: string;
+  /** Trigger label. */
+  label?: string;
+  /** 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`. */
+  open?: boolean;
+  /** Initial open state on mount (uncontrolled seed). */
+  defaultOpen?: boolean;
+  /** While true, auto-expands (and re-collapses when it flips false). */
+  streaming?: boolean;
+  /** Render `text` as markdown. */
+  markdown?: boolean;
+  /** Gate the disclosure trigger: programmatic `show()/hide()/toggle()` still work, but the trigger click no longer toggles. */
+  disabled?: boolean;
+}
+
+export interface KaiRemoteElementProps {
+  /** Color mode (`auto` follows prefers-color-scheme). */
+  theme?: "light" | "dark" | "auto";
+  /** The remote card URL. Attribute: `src`. */
+  src?: string;
+  /** Exact provider origin (https: or http://localhost for dev). Attribute: `provider-origin`. */
+  providerOrigin?: string;
+  /** The card envelope to render. JS property only. */
+  envelope?: Record<string, unknown>;
+  /** Optional routing policy. JS property only. */
+  policy?: Record<string, unknown>;
+}
+
+export interface KaiResizableElementProps {
+  /** Color mode (`auto` follows prefers-color-scheme). */
+  theme?: "light" | "dark" | "auto";
+  /** Layout axis: `horizontal` (row, default) or `vertical` (column). */
+  orientation?: "horizontal" | "vertical";
+  /** Which item index is maximized (null = none). Declarative source of truth. */
+  maximizedIndex?: number | null;
+  /** Divider affordance drawn inside each draggable handle's 8px grab zone: - `line` (default): a 1px hairline, transparent at rest, tinting on hover/drag. - `grip`: a dotted grip handle. - `none`: no visible divider, just the invisible hit-area. The full grab zone and keyboard/ARIA behavior are identical for all three. */
+  handle?: "line" | "grip" | "none";
+}
+
+export interface KaiResizableItemElementProps {
+  /** Color mode (`auto` follows prefers-color-scheme). */
+  theme?: "light" | "dark" | "auto";
+  /** Initial main-axis size: `"280px"` (fixed) or `"25%"`/`25` (percent). Omitted → flexible. */
+  size?: string;
+  /** Minimum size during resize (px or %). */
+  min?: string;
+  /** Maximum size during resize (px or %). */
+  max?: string;
+  /** Fix this panel's size; adjacent dividers become non-draggable. */
+  locked?: boolean;
+  /** Hide this panel; its divider is dropped and the rest reflow. */
+  hidden?: boolean;
+  /** Collapse this panel. Same layout effect as `hidden` (divider dropped, the rest reflow), but it WORKS as a bare boolean from framework JSX. A plain `<kai-resizable-item collapsed>` in React/Solid/Vue/Svelte collapses the panel at the first render; `hidden` does not, because a JSX boolean sets neither the `hidden` attribute nor the IDL property on a custom element, so the parent never sees it. The facade reflects `collapsed` to a `collapsed` attribute the parent reads. Prefer this over `hidden` for declarative collapse. */
+  collapsed?: boolean;
+}
+
+export interface KaiResponseStreamElementProps {
+  /** Color mode (`auto` follows prefers-color-scheme). */
+  theme?: "light" | "dark" | "auto";
+  /** Text to stream. A string, or an `AsyncIterable<string>` (set as a JS property, since async iterables can't be HTML attributes). */
+  text?: string | AsyncIterable<string>;
+  /** Reveal animation. */
+  mode?: "typewriter" | "fade";
+  /** Characters/segments per tick. */
+  speed?: number;
+  /** Element tag to render as. */
+  as?: string;
+}
+
+export interface KaiScopePickerElementProps {
+  /** Color mode (`auto` follows prefers-color-scheme). */
+  theme?: "light" | "dark" | "auto";
+  /** Authors to offer as scope filters. Omit to drop the Authors section (for a tag-only picker). Set as a JS property. */
+  availableAuthors?: string[];
+  /** Tags to offer as scope filters. Omit to drop the Tags section (for an author-only picker). Set as a JS property. */
+  availableTags?: string[];
+  /** The label shown on the trigger for the active scope. */
+  currentLabel?: string;
+  /** Drive/observe the dropdown's open state (Shoelace-style: settable + reflected to the `open` attribute, the dropdown still self-manages on click/keyboard). Set `el.open = true`, or `<kai-scope-picker open>`; listen for `kai-open-change`. */
+  open?: boolean;
+  /** Initial open state on mount (uncontrolled seed). */
+  defaultOpen?: boolean;
+  /** Disable the trigger: click/keyboard and `show()` no longer open the dropdown. */
+  disabled?: boolean;
+}
+
+export interface KaiScreenElementProps {
+  /** Color mode (`auto` follows prefers-color-scheme). */
+  theme?: "light" | "dark" | "auto";
+  /** Drive/observe open state (Shoelace-style: settable + reflected to the `open` attribute; the element still self-manages). Set `el.open = true`, or `<kai-screen open>`; listen for `kai-open-change`. */
+  open?: boolean;
+  /** Initial open state on mount (uncontrolled seed). */
+  defaultOpen?: boolean;
+  /** Header title text. A projected `title` slot overrides it. (Named `headline` because `title` collides with the global `HTMLElement.title` attribute.) */
+  headline?: string;
+  /** Show the back button (default true). */
+  back?: boolean;
+  /** Opt out of marking sibling elements inert/aria-hidden while open (for unusual layouts). */
+  noInert?: boolean;
+}
+
+export interface KaiScrollAreaElementProps {
+  /** Color mode (`auto` follows prefers-color-scheme). */
+  theme?: "light" | "dark" | "auto";
+  /** Which axis scrolls. `vertical` (default) · `horizontal` · `both`. The cross axis is clamped so content can't overflow it. */
+  orientation?: "vertical" | "horizontal" | "both";
+}
+
+export interface KaiScrollButtonElementProps {
+  /** Color mode (`auto` follows prefers-color-scheme). */
+  theme?: "light" | "dark" | "auto";
+  /** CSS id of the scroll container to control. When omitted the element walks up the DOM (outside its own shadow root) to find the nearest scrollable ancestor. Mirrors the `for` convention of `<label for="...">`. */
+  for?: string;
+  /** Button visual variant: `'outline' | 'ghost' | 'default'`. Defaults to `'outline'`. */
+  variant?: "outline" | "ghost" | "default";
+  /** Button size token. Defaults to `'icon'` (square). */
+  size?: "sm" | "md" | "lg" | "icon" | "icon-sm";
+}
+
+export interface KaiSearchElementProps {
+  /** Color mode (`auto` follows prefers-color-scheme). */
+  theme?: "light" | "dark" | "auto";
+  /** Controlled query. Settable and reflected to the `value` attribute. Read `el.value` for live state. */
+  value?: string;
+  /** Placeholder. Defaults to `Search…`. */
+  placeholder?: string;
+  /** Leading icon-NAME string (a curated name, URL, or text), resolved to a glyph the same way `kai-button`'s `icon` is. Defaults to `search`. */
+  icon?: string;
+  /** Debounce window for `kai-search`, in ms. Defaults to `200`. */
+  debounce?: number;
+  /** Show a spinner in place of the leading icon while results load. */
+  loading?: boolean;
+  /** Optional shortcut hint shown (as a `kai-kbd`) while the field is empty, e.g. `Mod+K`. Display only; it does not bind the key. */
+  shortcut?: string;
+}
+
+export interface KaiSegmentedElementProps {
+  /** Color mode (`auto` follows prefers-color-scheme). */
+  theme?: "light" | "dark" | "auto";
+  /** The selectable segments, left to right. Set as a JS property (array). */
+  options: { value: string; label: string; icon?: undefined | string }[];
+  /** Controlled selected `value`. Settable and reflected to the `value` attribute. `el.value = 'preview'` drives it; choosing a segment updates it and fires `kai-change`. Read `el.value` for live state. */
+  value?: string;
+  /** Control density: `sm` or `md`. Defaults to `md`. */
+  size?: "sm" | "md";
+}
+
+export interface KaiSeparatorElementProps {
+  /** Color mode (`auto` follows prefers-color-scheme). */
+  theme?: "light" | "dark" | "auto";
+  /** `horizontal` (default, block + full-width) or `vertical` (a rule inside a flex/grid row, stretching to the row height). */
+  orientation?: "horizontal" | "vertical";
+}
+
+export interface KaiSettingItemElementProps {
+  /** Color mode (`auto` follows prefers-color-scheme). */
+  theme?: "light" | "dark" | "auto";
+  /** Row label (primary text). Attribute: `label`. */
+  label?: string;
+  /** Optional secondary description under the label. Attribute: `description`. */
+  description?: string;
+}
+
+export interface KaiSettingsGroupElementProps {
+  /** Color mode (`auto` follows prefers-color-scheme). */
+  theme?: "light" | "dark" | "auto";
+  /** Small section heading shown above the card. Attribute: `heading`. */
+  heading?: string;
+  /** Optional muted description under the heading. Attribute: `description`. */
+  description?: string;
+}
+
+export interface KaiSkeletonElementProps {
+  /** Color mode (`auto` follows prefers-color-scheme). */
+  theme?: "light" | "dark" | "auto";
+  /** `text` (one or more lines), `rect` (a block), or `circle` (round). Defaults to `text`. */
+  variant?: "text" | "rect" | "circle";
+  /** CSS width (e.g. `'12rem'`, `'60%'`). Defaults to full width (responsive); for `circle` it is the diameter. */
+  width?: string;
+  /** CSS height. Defaults per variant (a text line height; circle = width). */
+  height?: string;
+  /** `text` only: number of lines; the last is shorter. Defaults to 1. */
+  lines?: number;
+}
+
+export interface KaiSkillsElementProps {
+  /** Color mode (`auto` follows prefers-color-scheme). */
+  theme?: "light" | "dark" | "auto";
+  /** The active skills to badge. Set as a JS property. Omit to supply them as `<kai-skill>` light-DOM children instead; when both are present the property's skills come first. Nothing renders when there are none. */
+  skills?: { id: string; name: string }[];
+}
+
+export interface KaiSourceElementProps {
+  /** Color mode (`auto` follows prefers-color-scheme). */
+  theme?: "light" | "dark" | "auto";
+  /** The URL this citation links to (the domain also seeds the default label/favicon). */
+  href?: string;
+  /** Trigger label (defaults to the domain). */
+  label?: string;
+  /** Hover-card headline. Attribute: `headline` (`title` is avoided because it is a global HTML attribute that reflects in a CE constructor and breaks it). */
+  headline?: string;
+  /** Hover-card body text describing the source. */
+  description?: string;
+  /** Show the source's favicon next to the trigger label. */
+  showFavicon?: boolean;
+}
+
+export interface KaiSourcesElementProps {
+  /** Color mode (`auto` follows prefers-color-scheme). */
+  theme?: "light" | "dark" | "auto";
+  /** The sources to render. Set as a JS property. Omit to supply them as `<kai-source>` light-DOM children instead; when both are present the property's sources come first. */
+  sources?: { href: string; title?: string; description?: string; label?: string; showFavicon?: boolean }[];
+  /** Show favicons on all items (per-item `showFavicon` overrides). */
+  showFavicon?: boolean;
+  /** When true, each citation chip is labelled with its 1-based index in the merged (prop + declarative-children) list (`[1]`, `[2]`, …) instead of the per-item `label` or domain fallback. HTML attribute: `numbered` (boolean: a bare attribute or `numbered="true"`). JS property: `el.numbered = true`. */
+  numbered?: boolean;
+}
+
+export interface KaiStatusElementProps {
+  /** Color mode (`auto` follows prefers-color-scheme). */
+  theme?: "light" | "dark" | "auto";
+  /** Presence/notification state → color. `new` (default) maps to the blue hue. */
+  status?: "new" | "online" | "busy" | "away" | "offline";
+  /** Animated ping ring (off by default; respects prefers-reduced-motion). */
+  pulse?: boolean;
+  /** Accessible name. Without it the dot is decorative. */
+  label?: string;
+  /** `sm` (default) or `md`. */
+  size?: "sm" | "md";
+}
+
+export interface KaiSuggestionsElementProps {
+  /** Color mode (`auto` follows prefers-color-scheme). */
+  theme?: "light" | "dark" | "auto";
+  /** The suggestions. Strings, or `{ label, value }` when the displayed text and the emitted value differ. Set as a JS property. Omit to supply them as `<kai-suggestion>` light-DOM children instead; when both are present the property's suggestions come first. */
+  suggestions?: (string | { label: string; value?: string; icon?: string })[];
+  /** Chip style: `'outline'` (default), `'ghost'`, or `'default'` (filled). */
+  variant?: "outline" | "ghost" | "default";
+  /** Row height for `layout="list"`: `'md'` (default) or `'lg'` for taller rows. Chips are unaffected. */
+  size?: "md" | "lg";
+  /** Layout: `'chips'` (default) renders a wrapping row of rounded pills; `'list'` renders a vertical, full-width "Ideas for you" list where each row is left-aligned with a leading `icon`, a label, and a hover background. */
+  layout?: "chips" | "list";
+  /** Full-width left-aligned rows instead of pills. */
+  block?: boolean;
+  /** Substring to highlight within each suggestion. */
+  highlight?: string;
+}
+
+export interface KaiSwitchElementProps {
+  /** Color mode (`auto` follows prefers-color-scheme). */
+  theme?: "light" | "dark" | "auto";
+  /** Controlled checked state. Settable and reflected to the `checked` attribute. `el.checked = true` (or `<kai-switch checked>`) drives it; the toggle UI updates it and fires `kai-change`. Read `el.checked` for live state. */
+  checked?: boolean;
+  /** Initial checked state on mount (uncontrolled seed). Bare attribute (`<kai-switch default-checked>`) turns it on. */
+  defaultChecked?: boolean;
+  /** Disable interaction. */
+  disabled?: boolean;
+  /** Accessible label. */
+  label?: string;
+  /** Form-control name (paired with `value`). */
+  name?: string;
+  /** Submitted value when checked (paired with `name`). Defaults to `'on'`. */
+  value?: string;
+}
+
+export interface KaiTabsElementProps {
+  /** Color mode (`auto` follows prefers-color-scheme). */
+  theme?: "light" | "dark" | "auto";
+  /** Tabs to render. Set as a JS property, not an HTML attribute. */
+  items?: { id: string; label?: string; icon?: string; disabled?: boolean }[];
+  /** Controlled selected id. Set as a JS property (or the `value` attribute); drive it from your app in response to `kai-tab-change`. Omit for uncontrolled. */
+  value?: string;
+  /** Initial selected id when uncontrolled (use the `default-value` attribute in plain HTML). */
+  defaultValue?: string;
+  /** `segmented` (default, a pill group) or `underline` (an underlined row). */
+  variant?: "segmented" | "underline";
+  /** Stretch the strip to full width, each tab sharing the space equally. */
+  block?: boolean;
+  /** Disable the whole strip. */
+  disabled?: boolean;
+}
+
+export interface KaiTasksElementProps {
+  /** Color mode (`auto` follows prefers-color-scheme). */
+  theme?: "light" | "dark" | "auto";
+  /** The tasks definition (the CardEnvelope.data). Set as a JS PROPERTY: `el.data = { tasks:[…], selectAll, confirmLabel, … }`. Import `TasksCardData` from `@kitn.ai/ui` for the full shape. */
+  data?: { mode?: "select" | "progress"; heading?: string; tasks: { id: string; label: string; description?: string; checked?: boolean; disabled?: boolean }[]; selectAll?: boolean; confirmLabel?: string; allowEmpty?: boolean; min?: number; max?: number; dismissible?: boolean };
+  /** Stable card id correlating every emitted CardEvent. Attribute: `card-id`. */
+  cardId?: string;
+  /** Heading rendered in the card chrome (= CardEnvelope.title). Attribute: `heading`. */
+  heading?: string;
+  /** Set when the user resolved this card; renders the read-only view. Property: `el.resolution = { kind:'submit', data:{ selected:[…] } }`. */
+  resolution?: Record<string, unknown>;
+  /** Controlled selection (task ids; JS property). When set, it wins over local state. */
+  value?: string[];
+  /** Uncontrolled initial selection (task ids; JS property), overlaying per-task `checked`. */
+  defaultValue?: string[];
+  /** Freeze the whole list + Confirm. Attribute: `disabled`. */
+  disabled?: boolean;
+  /** Display-only: rows can't be toggled and show the default cursor (no pointer, hover, or focus affordances). Keeps the look as-is. Attribute: `readonly`. */
+  readonly?: boolean;
+}
+
+export interface KaiTextShimmerElementProps {
+  /** Color mode (`auto` follows prefers-color-scheme). */
+  theme?: "light" | "dark" | "auto";
+  /** The text to shimmer. */
+  text?: string;
+  /** Element tag to render as (default `span`). */
+  as?: string;
+  /** Animation duration in seconds. */
+  duration?: number;
+  /** Gradient spread (5–45). */
+  spread?: number;
+}
+
+export interface KaiThinkingBarElementProps {
+  /** Color mode (`auto` follows prefers-color-scheme). */
+  theme?: "light" | "dark" | "auto";
+  /** The shimmering label, e.g. "Thinking…". */
+  text?: string;
+  /** When true, show a "stop" affordance that fires a `stop` event. */
+  stoppable?: boolean;
+  /** Label for the stop affordance. */
+  stopLabel?: string;
+}
+
+export interface KaiThreadElementProps {
+  /** Color mode (`auto` follows prefers-color-scheme). */
+  theme?: "light" | "dark" | "auto";
+  /** The full message thread to render, newest last. Each entry carries its role, ordered `parts`, and optional actions/avatar/feedback. Set as a JS property (`el.messages = [...]`); a NEW array reference per streaming chunk re-renders (mutating in place does not). */
+  messages?: { id: string; role: "user" | "assistant"; parts: ({ type: "text"; text: string; raw?: { source: string; payload: unknown } } | { type: "reasoning"; text: string; label?: string; index?: number; streamId?: string; signature?: string; raw?: { source: string; payload: unknown } } | { type: "tool"; tool: { type: string; kind?: "command" | "file-change" | "search" | "fetch" | "mcp" | "image" | "generic"; state: "input-streaming" | "input-available" | "output-available" | "output-error"; input?: Record<string, unknown>; rawInput?: string; output?: Record<string, unknown>; toolCallId?: string; errorText?: string; raw?: { source: string; payload: unknown } }; raw?: { source: string; payload: unknown } } | { type: "card"; envelope: { type: string; id: string; data: unknown; title?: string; resolution?: { kind: "action"; action: string; payload?: unknown; at?: string } | { kind: "submit"; data: unknown; at?: string } | { kind: "dismissed"; at?: string } | { kind: "expired"; reason?: string; at?: string } }; raw?: { source: string; payload: unknown } } | { type: "source"; source: { id?: string; url?: string; title?: string; snippet?: string; index?: number }; raw?: { source: string; payload: unknown } } | { type: "file"; attachment: { id: string; type: "file" | "source-document"; filename?: string; mediaType?: string; url?: string; title?: string }; raw?: { source: string; payload: unknown } })[]; actions?: ("copy" | "like" | "dislike" | "regenerate" | "edit" | { id: string; label: string; icon?: string; tooltip?: string })[]; avatar?: { src?: string; fallback?: string; alt?: string }; feedback?: "like" | "dislike" }[];
+  /** Show a typing indicator on the pending assistant turn. Set it while awaiting the assistant's reply. */
+  loading?: boolean;
+  /** Body/prose font scale for rendered markdown (`'xs' | 'sm' | 'base' | 'lg'`). Defaults to `'sm'`. */
+  proseSize?: "xs" | "sm" | "base" | "lg";
+  /** Shiki theme name for syntax-highlighted code blocks (e.g. `'github-dark-dimmed'`). */
+  codeTheme?: string;
+  /** Enable Shiki syntax highlighting in code blocks. Turn off to render plain `<pre>` blocks (lighter, no highlighter load). Default true. */
+  codeHighlight?: boolean;
+  /** Whether each message's action bar is always visible (`'always'`, default) or only revealed on hover of that message row (`'hover'`). */
+  actionsReveal?: "always" | "hover";
+  /** Show the scroll-to-bottom button inside the scroll area. Default true. */
+  scrollButton?: boolean;
+  /** Extra classes applied to the thread's inner root. */
+  class?: string;
+  /** Optional card type -> custom-element tag overrides/additions for `card` parts (merged over the built-ins). Property: `el.cardTypes`. Typed as a plain string map (not the `CardTagMap` alias) so the generated React wrapper inlines it instead of emitting an unresolved named type. */
+  cardTypes?: Record<string, string>;
+  /** 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. */
+  cardSchemas?: Record<string, object>;
+}
+
+export interface KaiToastRegionElementProps {
+  /** Color mode (`auto` follows prefers-color-scheme). */
+  theme?: "light" | "dark" | "auto";
+  /** 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. */
+  toasts?: { id: string; message: string; variant?: "neutral" | "success" | "warning" | "error" | "info"; appearance?: "pill" | "card"; inverse?: boolean; description?: string; action?: { label: string; onAction: () => void | false }; duration?: number; dismissible?: boolean; target?: HTMLElement }[];
+  /** Stack anchor: `'top-center'` (default), `'top-right'`, `'bottom-center'`, … */
+  position?: "top-center" | "top-right" | "top-left" | "bottom-center" | "bottom-right" | "bottom-left";
+  /** Max simultaneously-visible toasts; the rest queue. Defaults to `3`. */
+  max?: number;
+  /** Stacking: 'expanded' (default, full column) | 'collapsed' (Sonner-style pile that expands on hover/focus). Attribute: stack. */
+  stack?: "expanded" | "collapsed";
+  /** Default appearance for this region's toasts: `'pill'` (default, compact) | `'card'` (richer, with a description line). A per-toast `appearance` wins. Attribute: `appearance`. */
+  appearance?: "pill" | "card";
+  /** Default high-contrast inverse treatment for this region's toasts. A per-toast `inverse` wins. Off by default. Attribute: `inverse`. */
+  inverse?: boolean;
+  /** Container element to anchor this region to (JS property). Set by the store for a scoped region; unset = the global viewport region. */
+  target?: HTMLElement;
+}
+
+export interface KaiToolElementProps {
+  /** Color mode (`auto` follows prefers-color-scheme). */
+  theme?: "light" | "dark" | "auto";
+  /** The tool-call to display. Set as a JS property. */
+  tool?: { type: string; kind?: "command" | "file-change" | "search" | "fetch" | "mcp" | "image" | "generic"; state: "input-streaming" | "input-available" | "output-available" | "output-error"; input?: Record<string, unknown>; rawInput?: string; output?: Record<string, unknown>; toolCallId?: string; errorText?: string; raw?: { source: string; payload: unknown } };
+  /** Drive/observe open state (Shoelace-style: settable + reflected to the `open` attribute; the element still self-manages on trigger click). Set `el.open = true`, or `<kai-tool open>`; listen for `kai-open-change`. */
+  open?: boolean;
+  /** Initial open state on mount (uncontrolled seed). */
+  defaultOpen?: boolean;
+  /** Gate the disclosure trigger: programmatic `show()/hide()/toggle()` still work, but the trigger click no longer toggles. */
+  disabled?: boolean;
+}
+
+export interface KaiTooltipElementProps {
+  /** Color mode (`auto` follows prefers-color-scheme). */
+  theme?: "light" | "dark" | "auto";
+  /** The hint text shown on hover/focus of the slotted trigger. */
+  content?: string;
+  /** Delay (ms) before the tooltip appears on hover. Defaults to 600. Focus shows it immediately regardless. */
+  openDelay?: number;
+  /** Delay (ms) before it hides after the pointer leaves. Defaults to 0 (hides immediately). */
+  closeDelay?: number;
+  /** Preferred placement: `'top' | 'bottom' | 'left' | 'right'` (+ optional `-start`/`-end`). Defaults to `'top'`; flips to stay in view. */
+  placement?: string;
+  /** Drive/observe open state (Shoelace-style: settable + reflected to the `open` attribute, the element still self-manages on hover/focus). Set `el.open = true`, or `<kai-tooltip open>`; listen for `kai-open-change`. */
+  open?: boolean;
+  /** Initial open state on mount (uncontrolled seed). */
+  defaultOpen?: boolean;
+  /** Turn the tooltip off while keeping the trigger mounted (hover/focus and `show()` no longer open it). */
+  disabled?: boolean;
+}
+
+export interface KaiVoiceInputElementProps {
+  /** Color mode (`auto` follows prefers-color-scheme). */
+  theme?: "light" | "dark" | "auto";
+  /** 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. */
+  transcribe?: (audio: Blob) => Promise<string>;
+  /** Disable the mic button (non-interactive). */
+  disabled?: boolean;
+  /** BCP-47 language tag for the native `SpeechRecognition` path (e.g. `en-US`). Attribute: `recognition-lang` (the plain `lang` attribute is reserved by `HTMLElement` and can't be a custom-element property). No effect when `transcribe` is set or the browser lacks SpeechRecognition. */
+  recognitionLang?: string;
+  /** Emit live partial transcripts (`kai-transcript-interim`) during native recognition. Attribute: `interim`. No-op on the transcribe/fallback paths. */
+  interim?: boolean;
+}
+
+export interface KaiVoiceOutputElementProps {
+  /** Color mode (`auto` follows prefers-color-scheme). */
+  theme?: "light" | "dark" | "auto";
+  /** The utterance to read aloud. */
+  text?: string;
+  /** Speak automatically when `text` is set/changed. */
+  autoplay?: boolean;
+  /** 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. */
+  synthesize?: (text: string) => Promise<Blob>;
+  /** Disable the button (non-interactive). */
+  disabled?: boolean;
+}
+
+export interface KaiWorkspaceElementProps {
+  /** Color mode (`auto` follows prefers-color-scheme). */
+  theme?: "light" | "dark" | "auto";
+  /** The sidebar's section headers, rendered in array order. A group carries no conversations of its own; it is matched against `conversations` by id, so the two props are complementary rather than alternatives. Omit for an ungrouped sidebar. Set as a JS property. */
+  groups?: { id: string; userId?: string; teamId?: string; name: string; sortOrder: number; createdAt: string }[];
+  /** Every conversation in the sidebar, flat. Each one is filed under the group whose `id` equals its `groupId`; one with no `groupId`, or with a `groupId` matching no entry in `groups`, falls into a trailing ungrouped section (headerless when `compact`), so nothing you pass in is ever dropped. There is no recency bucketing. Set as a JS property. Omit for an empty sidebar, or when `no-conversations` replaces the built-in list with your own `sidebar-header` content. */
+  conversations?: { id: string; title: string; groupId?: string; scope: { type: "document" | "collection"; documentId?: string; filters?: { tags?: string[]; authors?: string[]; contentType?: "transcript" | "markdown"; dateRange?: { from: string; to: string } } }; messageCount: number; lastMessageAt: string; updatedAt: string; trailing?: string }[];
+  /** Id of the open conversation, highlighted in the sidebar. */
+  activeId?: string;
+  /** The active conversation's message thread, newest last. Set as a JS property (`el.messages = [...]`); a NEW array reference per streaming chunk re-renders (mutating in place does not). Omit for an empty thread. */
+  messages?: { id: string; role: "user" | "assistant"; parts: ({ type: "text"; text: string; raw?: { source: string; payload: unknown } } | { type: "reasoning"; text: string; label?: string; index?: number; streamId?: string; signature?: string; raw?: { source: string; payload: unknown } } | { type: "tool"; tool: { type: string; kind?: "command" | "file-change" | "search" | "fetch" | "mcp" | "image" | "generic"; state: "input-streaming" | "input-available" | "output-available" | "output-error"; input?: Record<string, unknown>; rawInput?: string; output?: Record<string, unknown>; toolCallId?: string; errorText?: string; raw?: { source: string; payload: unknown } }; raw?: { source: string; payload: unknown } } | { type: "card"; envelope: { type: string; id: string; data: unknown; title?: string; resolution?: { kind: "action"; action: string; payload?: unknown; at?: string } | { kind: "submit"; data: unknown; at?: string } | { kind: "dismissed"; at?: string } | { kind: "expired"; reason?: string; at?: string } }; raw?: { source: string; payload: unknown } } | { type: "source"; source: { id?: string; url?: string; title?: string; snippet?: string; index?: number }; raw?: { source: string; payload: unknown } } | { type: "file"; attachment: { id: string; type: "file" | "source-document"; filename?: string; mediaType?: string; url?: string; title?: string }; raw?: { source: string; payload: unknown } })[]; actions?: ("copy" | "like" | "dislike" | "regenerate" | "edit" | { id: string; label: string; icon?: string; tooltip?: string })[]; avatar?: { src?: string; fallback?: string; alt?: string }; feedback?: "like" | "dislike" }[];
+  value?: string;
+  placeholder?: string;
+  loading?: boolean;
+  suggestions?: string[];
+  suggestionMode?: "submit" | "fill";
+  proseSize?: "xs" | "sm" | "base" | "lg";
+  codeTheme?: string;
+  codeHighlight?: boolean;
+  chatTitle?: string;
+  models?: { id: string; name: string; provider?: string; description?: string; group?: string }[];
+  currentModel?: string;
+  context?: { usedTokens: number; maxTokens: number; inputTokens?: number; outputTokens?: number; estimatedCost?: number };
+  scrollButton?: boolean;
+  search?: boolean;
+  voice?: boolean;
+  /** Rich entity triggers (`/` skills, `@` agents/plugins) forwarded to the input. */
+  triggers?: { char: string; kind: string; items?: { id: string; label: string; icon?: string; description?: string; group?: string; kind?: string; promptText?: string; data?: Record<string, unknown> }[] }[];
+  /** Default icon per entity kind (kind → image src) forwarded to the input. */
+  kindIcons?: Record<string, string>;
+  /** Sidebar default width as a percent of the workspace (default 26). */
+  sidebarWidth?: number;
+  /** Sidebar min width in px (default 240). */
+  sidebarMinWidth?: number;
+  /** Sidebar max width in px (default 420). */
+  sidebarMaxWidth?: number;
+  /** Controlled collapsed state. Set this as a JS property (`el.sidebarCollapsed = true`) to drive the sidebar from your app, updating it in response to the `kai-sidebar-toggle` event. Omit for uncontrolled (the element manages it). */
+  sidebarCollapsed?: boolean;
+  /** Initial collapsed state when uncontrolled (default false). Use the `default-sidebar-collapsed` attribute to start collapsed in plain HTML. */
+  defaultSidebarCollapsed?: boolean;
+  /** Auto-collapse the rail when the workspace's own width drops below this many px, and re-expand when it grows back above. Uncontrolled only (it never fights an app-driven `sidebarCollapsed`); omit to disable. Fires `kai-sidebar-toggle`. Attribute: `collapse-below`. */
+  collapseBelow?: number;
+  /** Render Recents as dense single-line rows (a leading dot + title, no count). */
+  compact?: boolean;
+  /** Suppress the built-in ConversationList so the `sidebar-header` slot owns the whole rail flex region (for apps that supply their own rail nav). Default false. Attribute: `no-conversations`. */
+  noConversations?: boolean;
+  /** Optional card type -> custom-element tag overrides/additions for `card` parts (merged over the built-ins). Property: `el.cardTypes`. Typed as a plain string map (not the `CardTagMap` alias) so the generated React wrapper inlines it instead of emitting an unresolved named type. */
+  cardTypes?: Record<string, string>;
+  /** 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. */
+  cardSchemas?: Record<string, object>;
+}
+
+export interface KaiAgentCardElementEvents {
+  /** The card was activated by a click, or by Enter / Space while focused. Promote this agent back to focus. */
+  onKaiActivate?: (event: CustomEvent) => void;
+  /** The trailing "..." kebab was clicked. The consumer opens its own menu; the card only surfaces the affordance (the click does not also activate the card). */
+  onKaiMenu?: (event: CustomEvent) => void;
+}
+
+export interface KaiArtifactElementEvents {
+  /** Fired when a file is selected. `detail.path`. */
+  onKaiFileSelect?: (event: CustomEvent<{ path: string }>) => void;
+  /** Artifact's own maximize button toggled (consumer-observable; non-bubbling). */
+  onKaiMaximizeChange?: (event: CustomEvent<{ maximized: boolean }>) => void;
+  /** The maximize PROTOCOL intent, raised as a raw bubbling + composed CustomEvent (not through `dispatch`) so an enclosing `<kai-resizable>` can catch it and maximize the containing panel. Declared here so it is typed and reaches the generated API. Listen for it to drive maximize from your own chrome, or re-emit it to trigger one. */
+  onKaiMaximizeIntent?: (event: CustomEvent<{ requested: boolean }>) => void;
+  /** Fired when the preview navigates. `detail.url` = the new location. */
+  onKaiNavigate?: (event: CustomEvent<{ url: string }>) => void;
+  /** Fired when the Preview|Code tab changes. `detail.tab`. */
+  onKaiTabChange?: (event: CustomEvent<{ tab: "preview" | "code" }>) => void;
+}
+
+export interface KaiAttachmentsElementEvents {
+  /** A remove button was clicked. */
+  onKaiRemove?: (event: CustomEvent<{ id: string }>) => void;
+}
+
+export interface KaiAudioVisualizerElementEvents {
+
+}
+
+export interface KaiAvatarElementEvents {
+
+}
+
+export interface KaiBadgeElementEvents {
+
+}
+
+export interface KaiButtonElementEvents {
+  /** The button was activated (pointer or keyboard). Carries no detail. The native `click` also bubbles (composed) for consumers who prefer it. */
+  onKaiClick?: (event: CustomEvent) => void;
+}
+
+export interface KaiCardElementEvents {
+  /** A `clickable`/`href` card was activated (click, or Enter/Space). */
+  onKaiCardClick?: (event: CustomEvent) => void;
+  /** The card was dismissed via its × (it also hides itself). */
+  onKaiDismiss?: (event: CustomEvent) => void;
+}
+
+export interface KaiCardsElementEvents {
+  /** A child card transitioned to a resolved/deferred state (an action was chosen, a form/tasks submission landed, or it was dismissed). Re-emitted off the host as a non-bubbling convenience event so a consumer can observe resolution centrally without diffing the cards array. `detail` = `{ cardId, resolution }`. (A `reopen` un-resolves a card and has no `CardResolution`, so it does NOT fire this; observe reopen via the underlying bubbling `kai-card` event.) */
+  onKaiCardResolved?: (event: CustomEvent<{ cardId: string; resolution: { kind: "action"; action: string; payload?: unknown; at?: undefined | string } | { kind: "submit"; data: unknown; at?: undefined | string } | { kind: "dismissed"; at?: undefined | string } | { kind: "expired"; reason?: undefined | string; at?: undefined | string } }>) => void;
+}
+
+export interface KaiChainOfThoughtElementEvents {
+  /** The open set changed, by user click OR an expand()/collapse()/toggle() call. `value` is a string in `single` mode, a string[] in `multiple` mode. (Maps Radix Accordion's onValueChange.) */
+  onKaiValueChange?: (event: CustomEvent<{ value: string | string[] }>) => void;
+}
+
+export interface KaiChatElementEvents {
+  /** The staged attachments changed (file added or removed). Carries the full current list so a consumer can react in real time. */
+  onKaiAttachmentsChange?: (event: CustomEvent<{ attachments: { id: string; type: "file" | "source-document"; filename?: undefined | string; mediaType?: undefined | string; url?: undefined | string; title?: undefined | string }[] }>) => void;
+  /** An action button on a message was clicked. `action` is the built-in name or custom id. `state` is present only for the toggleable feedback votes: `'on'` when a like/dislike is set, `'off'` when re-tapped to clear. */
+  onKaiMessageAction?: (event: CustomEvent<{ messageId: string; action: string; state?: undefined | "on" | "off" }>) => void;
+  /** The header model switcher changed. */
+  onKaiModelChange?: (event: CustomEvent<{ modelId: string }>) => void;
+  /** The Search button was clicked. */
+  onKaiSearch?: (event: CustomEvent<Record<string, never>>) => void;
+  /** User submitted a message. */
+  onKaiSubmit?: (event: CustomEvent<{ value: string; attachments: { id: string; type: "file" | "source-document"; filename?: undefined | string; mediaType?: undefined | string; url?: undefined | string; title?: undefined | string }[] }>) => void;
+  /** A suggestion chip was clicked (only in `suggestion-mode="fill"`). */
+  onKaiSuggestionClick?: (event: CustomEvent<{ value: string }>) => void;
+  /** Fired on every input change. */
+  onKaiValueChange?: (event: CustomEvent<{ value: string }>) => void;
+  /** The Mic / voice button was clicked. */
+  onKaiVoice?: (event: CustomEvent<Record<string, never>>) => void;
+}
+
+export interface KaiCheckpointElementEvents {
+  /** The checkpoint was clicked. */
+  onKaiSelect?: (event: CustomEvent) => void;
+}
+
+export interface KaiChoiceElementEvents {
+  /** The selection changed BEFORE submit (a row click or the `select()` method). Distinct from the terminal `action` verb on the `kai-card` contract event. */
+  onKaiValueChange?: (event: CustomEvent<{ value: string }>) => void;
+}
+
+export interface KaiCoachmarkElementEvents {
+  /** The × dismiss button was pressed. The consumer records that this hint was seen so it won't show again. */
+  onKaiDismiss?: (event: CustomEvent<Record<string, never>>) => void;
+  /** The coachmark opened or closed (a method, the ×, or a driven `open`). */
+  onKaiOpenChange?: (event: CustomEvent<{ open: boolean }>) => void;
+}
+
+export interface KaiCodeBlockElementEvents {
+
+}
+
+export interface KaiCommandElementEvents {
+  /** Fired when the highlighted/active item changes, via Arrow keys or when filtering re-clamps the active row. `id` is the newly active item's id, or `undefined` when no item is active (e.g. the filtered list is empty). Lets a host preview the active item without committing a selection. */
+  onKaiActiveChange?: (event: CustomEvent<{ id: string | undefined }>) => void;
+  /** Fired on every keystroke in the search input. */
+  onKaiQueryChange?: (event: CustomEvent<{ value: string }>) => void;
+  /** Fired when the user selects an item (click or Enter). */
+  onKaiSelect?: (event: CustomEvent<{ id: string }>) => void;
+}
+
+export interface KaiCompareElementEvents {
+  /** The user committed a pick. `detail` = `{ chosenId, rejectedIds, at }`. */
+  onKaiCompareSelect?: (event: CustomEvent<{ chosenId: string; rejectedIds: string[]; at?: undefined | number }>) => void;
+  /** The definition was unusable. */
+  onKaiError?: (event: CustomEvent<{ compareId: string; message: string }>) => void;
+  /** Both candidates have settled and the pick is live. */
+  onKaiReady?: (event: CustomEvent<{ compareId: string }>) => void;
+}
+
+export interface KaiComposerElementEvents {
+  /** The composer lost focus. */
+  onKaiBlur?: (event: CustomEvent<{ originalEvent: FocusEvent }>) => void;
+  /** An entity pill was inserted into the composer. */
+  onKaiEntityAdd?: (event: CustomEvent<{ entity: { kind: string; id: string; label: string; icon?: undefined | string; promptText?: undefined | string; data?: undefined | Record<string, unknown> } }>) => void;
+  /** An entity pill was deleted from the composer. */
+  onKaiEntityRemove?: (event: CustomEvent<{ entity: { kind: string; id: string; label: string; icon?: undefined | string; promptText?: undefined | string; data?: undefined | Record<string, unknown> } }>) => void;
+  /** The composer gained focus. `focus`/`blur` are NOT composed natively, so they don't escape the shadow root; these re-expose them on the host. (For `keydown`/`paste`/`focusin`/`focusout`, listen NATIVELY on `<kai-composer>`: they're composed and already cross the shadow boundary.) */
+  onKaiFocus?: (event: CustomEvent<{ originalEvent: FocusEvent }>) => void;
+  /** The user submitted the composer (Enter or programmatic submit). */
+  onKaiSubmit?: (event: 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> }[] }>) => void;
+  /** A trigger character was detected at the caret (e.g. `/` or `@`). */
+  onKaiTrigger?: (event: CustomEvent<{ char: string; query: string; rect: DOMRect }>) => void;
+  /** The active trigger was dismissed (Escape, space, or outside click). */
+  onKaiTriggerClose?: (event: CustomEvent<Record<string, never>>) => void;
+  /** The content changed (fires on every input event). */
+  onKaiValueChange?: (event: 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> }[] }>) => void;
+}
+
+export interface KaiConfirmElementEvents {
+
+}
+
+export interface KaiContextElementEvents {
+  /** Fires when the computed severity level changes (ok → warn → danger or back). `detail.level` is `'ok'`, `'warn'`, or `'danger'`. */
+  onKaiThresholdChange?: (event: CustomEvent<{ level: "ok" | "warn" | "danger" }>) => void;
+}
+
+export interface KaiConversationsElementEvents {
+  /** The rail was collapsed or expanded (via the toggle, the reopen button, or a `collapse()`/`expand()`/`toggle()` call). */
+  onKaiCollapseToggle?: (event: CustomEvent<{ collapsed: boolean }>) => void;
+  /** A conversation was selected. */
+  onKaiConversationSelect?: (event: CustomEvent<{ id: string }>) => void;
+  /** The "New chat" button was clicked. */
+  onKaiNewChat?: (event: CustomEvent<Record<string, never>>) => void;
+  /** The built-in search box query changed (typing, or a programmatic `clear()` which fires it with `''`). Lets a consumer mirror or server-side the filter. */
+  onKaiSearch?: (event: CustomEvent<{ query: string }>) => void;
+  /** The sidebar toggle was clicked. */
+  onKaiToggleSidebar?: (event: CustomEvent<Record<string, never>>) => void;
+}
+
+export interface KaiDialogElementEvents {
+  /** The dialog opened or closed (Escape, backdrop click, a driven `open`, or a method). */
+  onKaiOpenChange?: (event: CustomEvent<{ open: boolean }>) => void;
+}
+
+export interface KaiEditableLabelElementEvents {
+  /** Edit was cancelled (Esc); the text is restored. */
+  onKaiCancel?: (event: CustomEvent<Record<string, never>>) => void;
+  /** Committed a changed value (Enter / blur). */
+  onKaiRename?: (event: CustomEvent<{ value: string }>) => void;
+}
+
+export interface KaiEmbedElementEvents {
+
+}
+
+export interface KaiEmptyElementEvents {
+
+}
+
+export interface KaiFeedbackBarElementEvents {
+  /** The user dismissed the banner. */
+  onKaiClose?: (event: CustomEvent) => void;
+  /** The user rated the response. `value` is `'helpful'` or `'not-helpful'`. */
+  onKaiFeedback?: (event: CustomEvent<{ value: "helpful" | "not-helpful" }>) => void;
+  /** The user submitted the optional detail form (`collect-detail`). */
+  onKaiFeedbackDetail?: (event: CustomEvent<{ value: "helpful" | "not-helpful"; category?: undefined | string; comment?: undefined | string }>) => void;
+}
+
+export interface KaiFileTreeElementEvents {
+  /** Fired when a file is selected. `detail.path` = the file's path. */
+  onKaiSelect?: (event: CustomEvent<{ path: string }>) => void;
+}
+
+export interface KaiFileUploadElementEvents {
+  /** Files were picked or dropped. */
+  onKaiFilesAdded?: (event: CustomEvent<{ files: File[] }>) => void;
+}
+
+export interface KaiFormElementEvents {
+  /** The form's values changed on input. Carries the current coerced values + validity. */
+  onKaiValuesChange?: (event: CustomEvent<{ values: Record<string, unknown>; valid: boolean }>) => void;
+}
+
+export interface KaiHoverCardElementEvents {
+  /** The card opened or closed (by hover/focus, outside-click, or a method). */
+  onKaiOpenChange?: (event: CustomEvent<{ open: boolean }>) => void;
+}
+
+export interface KaiIconElementEvents {
+
+}
+
+export interface KaiImageElementEvents {
+
+}
+
+export interface KaiInputElementEvents {
+  /** The value was committed (blur). */
+  onKaiChange?: (event: CustomEvent<{ value: string }>) => void;
+  /** The value changed per keystroke. */
+  onKaiInput?: (event: CustomEvent<{ value: string }>) => void;
+}
+
+export interface KaiKbdElementEvents {
+
+}
+
+export interface KaiLinkPreviewElementEvents {
+
+}
+
+export interface KaiLoaderElementEvents {
+
+}
+
+export interface KaiMarkdownElementEvents {
+
+}
+
+export interface KaiMenuElementEvents {
+  /** The menu opened or closed (by click, keyboard, Escape, outside-click, or a method). */
+  onKaiOpenChange?: (event: CustomEvent<{ open: boolean }>) => void;
+  /** Fired when the user selects a leaf item. - Plain items: `{ id }`. - Checkbox items: `{ id, checked }` where `checked` is the NEW state. - Radio items: `{ id, radioGroup }`, where the consumer marks `id` as the selected one in `radioGroup` and clears the others. */
+  onKaiSelect?: (event: CustomEvent<{ id: string; checked?: undefined | boolean; radioGroup?: undefined | string }>) => void;
+}
+
+export interface KaiMessageElementEvents {
+  /** An action button was clicked. `action` is the built-in name or custom id. `state` is present only for the toggleable feedback votes: `'on'` when a like/dislike is set, `'off'` when re-tapped to clear. */
+  onKaiMessageAction?: (event: CustomEvent<{ messageId: string; action: string; state?: undefined | "on" | "off" }>) => void;
+}
+
+export interface KaiModelSwitcherElementEvents {
+  /** A model was selected. */
+  onKaiModelChange?: (event: CustomEvent<{ modelId: string }>) => void;
+  /** The model dropdown opened or closed (by click, keyboard, Escape, outside-click, or a method). */
+  onKaiOpenChange?: (event: CustomEvent<{ open: boolean }>) => void;
+}
+
+export interface KaiNavElementEvents {
+  /** A row's trailing `action` button was activated (not a select). `value` is the item id; `action` echoes the item's `{ icon, label }`. */
+  onKaiNavItemAction?: (event: CustomEvent<{ value: string; action?: undefined | { icon: string; label: string } }>) => void;
+  /** A `closable` row's trailing close button was activated (not a select). `value` is the item id. */
+  onKaiNavItemClose?: (event: CustomEvent<{ value: string }>) => void;
+  /** A nav item was activated. */
+  onKaiNavSelect?: (event: CustomEvent<{ id: string }>) => void;
+}
+
+export interface KaiNoticeElementEvents {
+  /** The notice was dismissed via its × (it also hides itself). */
+  onKaiDismiss?: (event: CustomEvent) => void;
+}
+
+export interface KaiPaneElementEvents {
+  /** The close (×) control was clicked. */
+  onKaiClose?: (event: CustomEvent) => void;
+  /** The dock control was clicked (only present when `show-dock`). */
+  onKaiDock?: (event: CustomEvent) => void;
+  /** The maximize/restore control was clicked. `detail.maximized` is the intended NEXT state. Drive the `maximized` prop yourself from it. */
+  onKaiMaximize?: (event: CustomEvent<{ maximized: boolean }>) => void;
+  /** The split control was clicked (only present when `show-split`). */
+  onKaiSplit?: (event: CustomEvent) => void;
+}
+
+export interface KaiPaneGroupElementEvents {
+  /** A tab was selected (click, Enter/Space, or arrow-key move). `detail.id` is the tab's id. */
+  onKaiTabChange?: (event: CustomEvent<{ id: string }>) => void;
+  /** A tab's close (×) was clicked. Drop the tab from `tabs` yourself. */
+  onKaiTabClose?: (event: CustomEvent<{ id: string }>) => void;
+  /** A tab's "…" overflow was clicked. Open your own menu from `detail.id`. */
+  onKaiTabMenu?: (event: CustomEvent<{ id: string }>) => void;
+}
+
+export interface KaiPopoverElementEvents {
+  /** The popover opened or closed (click, Escape, outside-click, or a method). */
+  onKaiOpenChange?: (event: CustomEvent<{ open: boolean }>) => void;
+}
+
+export interface KaiProgressBarElementEvents {
+
+}
+
+export interface KaiPromptDockElementEvents {
+
+}
+
+export interface KaiPromptInputElementEvents {
+  /** The staged attachments changed: a file was added (via the paperclip) or removed (per-chip ×). Carries the full current list so a consumer can react in real time (validate, show upload progress, toggle the send button). */
+  onKaiAttachmentsChange?: (event: CustomEvent<{ attachments: { id: string; type: "file" | "source-document"; filename?: undefined | string; mediaType?: undefined | string; url?: undefined | string; title?: undefined | string }[] }>) => void;
+  /** The Search (Globe) toolbar button was clicked. */
+  onKaiSearch?: (event: CustomEvent<Record<string, never>>) => void;
+  /** The Stop button was clicked while `stoppable` and `loading` are both true. */
+  onKaiStop?: (event: CustomEvent<Record<string, never>>) => void;
+  /** 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. */
+  onKaiSubmit?: (event: 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 }[] }>) => void;
+  /** A suggestion was clicked while `suggestion-mode="fill"`. */
+  onKaiSuggestionClick?: (event: CustomEvent<{ value: string }>) => void;
+  /** A custom `<kai-action>` toolbar button was clicked. `action` is the `id` of the `<kai-action>` element that was clicked. */
+  onKaiToolbarAction?: (event: CustomEvent<{ action: string }>) => void;
+  /** The input changed (fires on every edit). Carries the flattened `value` plus the structured `doc` + `entities`. */
+  onKaiValueChange?: (event: 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> }[] }>) => void;
+  /** The Voice (Mic) toolbar button was clicked. */
+  onKaiVoice?: (event: CustomEvent<Record<string, never>>) => void;
+}
+
+export interface KaiReasoningElementEvents {
+  /** The reasoning block expanded or collapsed (via the trigger, streaming auto-open, or a method). */
+  onKaiOpenChange?: (event: CustomEvent<{ open: boolean }>) => void;
+}
+
+export interface KaiRemoteElementEvents {
+
+}
+
+export interface KaiResizableElementEvents {
+  /** Fired on drag-end / keyboard resize / visibility change. `detail.sizes` = panel sizes in percent. */
+  onKaiChange?: (event: CustomEvent<{ sizes: number[] }>) => void;
+  /** Observe layout maximize state. */
+  onKaiMaximizeChange?: (event: CustomEvent<{ maximized: boolean; index: number | null }>) => void;
+  /** Authoritative maximize state, dispatched as a raw composed CustomEvent (not through `dispatch`) onto the affected `<kai-resizable-item>` and, on restore, onto the group host. A nested element (e.g. `<kai-artifact>`) listens for it to reconcile its own toggle. */
+  onKaiMaximizeState?: (event: CustomEvent<{ maximized: boolean }>) => void;
+}
+
+export interface KaiResizableItemElementEvents {
+  onKaiChange?: (event: CustomEvent<unknown>) => void;
+  onKaiMaximizeChange?: (event: CustomEvent<unknown>) => void;
+  onKaiMaximizeState?: (event: CustomEvent<unknown>) => void;
+}
+
+export interface KaiResponseStreamElementEvents {
+  /** Streaming finished. */
+  onKaiComplete?: (event: CustomEvent) => void;
+}
+
+export interface KaiScopePickerElementEvents {
+  /** The scope dropdown opened or closed (by click, keyboard, Escape, outside-click, or a method). */
+  onKaiOpenChange?: (event: CustomEvent<{ open: boolean }>) => void;
+  /** A scope was chosen (`undefined` filters = "All Content"). */
+  onKaiScopeChange?: (event: CustomEvent<{ filters: { tags?: undefined | string[]; authors?: undefined | string[]; contentType?: undefined | "transcript" | "markdown"; dateRange?: undefined | { from: string; to: string } } | undefined }>) => void;
+}
+
+export interface KaiScreenElementEvents {
+  /** Back navigation intent: the back button or Escape. The consumer flips their own routing in response (the screen knows nothing about the trigger). */
+  onKaiBack?: (event: CustomEvent<Record<string, never>>) => void;
+  /** The screen opened or closed (a method, `Escape` close, or driven `open`). */
+  onKaiOpenChange?: (event: CustomEvent<{ open: boolean }>) => void;
+}
+
+export interface KaiScrollAreaElementEvents {
+
+}
+
+export interface KaiScrollButtonElementEvents {
+  /** Emitted when the user clicks the button and `scrollToBottom()` is called. Carries no detail; consumers use it to know a manual scroll occurred. */
+  onKaiScroll?: (event: CustomEvent) => void;
+}
+
+export interface KaiSearchElementEvents {
+  /** The field committed (blur). */
+  onKaiChange?: (event: CustomEvent<{ value: string }>) => void;
+  /** The query changed (debounced live, and on clear). */
+  onKaiSearch?: (event: CustomEvent<{ value: string }>) => void;
+  /** Enter was pressed. */
+  onKaiSubmit?: (event: CustomEvent<{ value: string }>) => void;
+}
+
+export interface KaiSegmentedElementEvents {
+  /** A segment was chosen. */
+  onKaiChange?: (event: CustomEvent<{ value: string }>) => void;
+}
+
+export interface KaiSeparatorElementEvents {
+
+}
+
+export interface KaiSettingItemElementEvents {
+
+}
+
+export interface KaiSettingsGroupElementEvents {
+
+}
+
+export interface KaiSkeletonElementEvents {
+
+}
+
+export interface KaiSkillsElementEvents {
+
+}
+
+export interface KaiSourceElementEvents {
+
+}
+
+export interface KaiSourcesElementEvents {
+
+}
+
+export interface KaiStatusElementEvents {
+
+}
+
+export interface KaiSuggestionsElementEvents {
+  /** A suggestion was clicked. */
+  onKaiSelect?: (event: CustomEvent<{ value: string }>) => void;
+}
+
+export interface KaiSwitchElementEvents {
+  /** The toggle changed. */
+  onKaiChange?: (event: CustomEvent<{ checked: boolean }>) => void;
+}
+
+export interface KaiTabsElementEvents {
+  /** A tab was selected (click, Enter/Space, or arrow-key move). `value` is the item's id. */
+  onKaiTabChange?: (event: CustomEvent<{ value: string }>) => void;
+}
+
+export interface KaiTasksElementEvents {
+  /** The selection changed on a toggle. Carries the selected ids in input order. */
+  onKaiValueChange?: (event: CustomEvent<{ value: string[] }>) => void;
+}
+
+export interface KaiTextShimmerElementEvents {
+
+}
+
+export interface KaiThinkingBarElementEvents {
+  /** The "stop / answer now" affordance was clicked. */
+  onKaiStop?: (event: CustomEvent) => void;
+}
+
+export interface KaiThreadElementEvents {
+  /** A message's action button was clicked. `action` is the built-in name (`copy` / `like` / `dislike` / `regenerate` / `edit`) or a custom id. `state` is present only for the toggleable feedback votes: `'on'` when a like/dislike is set, `'off'` when re-tapped to clear. */
+  onKaiMessageAction?: (event: CustomEvent<{ messageId: string; action: string; state?: undefined | "on" | "off" }>) => void;
+}
+
+export interface KaiToastRegionElementEvents {
+  /** A toast's action button was pressed. */
+  onKaiAction?: (event: CustomEvent<{ id: string; label: string }>) => void;
+  /** A toast left the stack. `reason` is `'timeout' | 'close' | 'action'`. */
+  onKaiDismiss?: (event: CustomEvent<{ id: string; reason: "timeout" | "close" | "action" }>) => void;
+}
+
+export interface KaiToolElementEvents {
+  /** The panel expanded or collapsed (by trigger click or a method). */
+  onKaiOpenChange?: (event: CustomEvent<{ open: boolean }>) => void;
+}
+
+export interface KaiTooltipElementEvents {
+  /** The tooltip opened or closed (by hover/focus, outside-click, or a method). */
+  onKaiOpenChange?: (event: CustomEvent<{ open: boolean }>) => void;
+}
+
+export interface KaiVoiceInputElementEvents {
+  /** Raw audio captured (before transcription), for hosts that prefer to handle transcription themselves instead of via the `transcribe` property. Also the unsupported-fallback signal: no `transcribe`, no SpeechRecognition, so only the blob is produced (no text). */
+  onKaiAudioCaptured?: (event: CustomEvent<{ blob: Blob }>) => void;
+  /** Recording started or stopped. Lets the host drive its own UI (waveform, push-to-talk indicator) in sync with the mic. Fires on real transitions only (manual click and programmatic start()/stop()), never on mount. */
+  onKaiRecordingChange?: (event: CustomEvent<{ recording: boolean }>) => void;
+  /** Live partial transcript during native recognition (only when `interim` is set). Fires repeatedly before the final `kai-transcription`. */
+  onKaiTranscriptInterim?: (event: CustomEvent<{ text: string }>) => void;
+  /** Final transcript: the `transcribe` property resolved, OR native `SpeechRecognition` produced final text (no `transcribe` set). */
+  onKaiTranscription?: (event: CustomEvent<{ text: string }>) => void;
+}
+
+export interface KaiVoiceOutputElementEvents {
+  /** Playback started or stopped. Drive your own UI in sync. Fires on real transitions only (manual click and programmatic speak()/stop()), never on mount. */
+  onKaiSpeakingChange?: (event: CustomEvent<{ speaking: boolean }>) => void;
+  /** The model path (`synthesize`) resolved audio: the raw `Blob` before playback. */
+  onKaiSynthesized?: (event: CustomEvent<{ blob: Blob }>) => void;
+}
+
+export interface KaiWorkspaceElementEvents {
+  /** A conversation was selected in the sidebar. */
+  onKaiConversationSelect?: (event: CustomEvent<{ id: string }>) => void;
+  /** An action button on a message was clicked. `state` is present only for the toggleable feedback votes: `'on'` when a like/dislike is set, `'off'` when re-tapped to clear. */
+  onKaiMessageAction?: (event: CustomEvent<{ messageId: string; action: string; state?: undefined | "on" | "off" }>) => void;
+  /** The header model switcher changed. */
+  onKaiModelChange?: (event: CustomEvent<{ modelId: string }>) => void;
+  /** The "New chat" button was clicked. */
+  onKaiNewChat?: (event: CustomEvent<Record<string, never>>) => void;
+  /** The Search button was clicked. */
+  onKaiSearch?: (event: CustomEvent<Record<string, never>>) => void;
+  /** The sidebar was collapsed or expanded. */
+  onKaiSidebarToggle?: (event: CustomEvent<{ collapsed: boolean }>) => void;
+  /** User submitted a message. */
+  onKaiSubmit?: (event: CustomEvent<{ value: string; attachments: { id: string; type: "file" | "source-document"; filename?: undefined | string; mediaType?: undefined | string; url?: undefined | string; title?: undefined | string }[] }>) => void;
+  /** A suggestion chip was clicked (only in `suggestion-mode="fill"`). */
+  onKaiSuggestionClick?: (event: CustomEvent<{ value: string }>) => void;
+  /** Fired on every input change. */
+  onKaiValueChange?: (event: CustomEvent<{ value: string }>) => void;
+  /** The Mic / voice button was clicked. */
+  onKaiVoice?: (event: CustomEvent<Record<string, never>>) => void;
+}
+
+/** Attributes every kai-* element tolerates in a Vue template on top of its own
+ *  props: `id`, `data-*`, `aria-*`, directives. The index signature keeps those
+ *  legal under `strictTemplates` WITHOUT weakening the declared props — an
+ *  explicit member always wins over an index signature. */
+export interface KaiElementVueProps {
+  [attr: string]: unknown;
+}
+
+/** A kai-* custom element as Vue's template type-checker sees it. Props are
+ *  `Partial` because the kai- contract allows setting any of them imperatively
+ *  through a ref instead of in the template. */
+export type KaiVueElement<Props, Events> = new () => {
+  $props: Partial<Props> & Events & KaiElementVueProps;
+};
+
+declare module 'vue' {
+  interface GlobalComponents {
+    'kai-agent-card': KaiVueElement<KaiAgentCardElementProps, KaiAgentCardElementEvents>;
+    KaiAgentCard: KaiVueElement<KaiAgentCardElementProps, KaiAgentCardElementEvents>;
+    'kai-artifact': KaiVueElement<KaiArtifactElementProps, KaiArtifactElementEvents>;
+    KaiArtifact: KaiVueElement<KaiArtifactElementProps, KaiArtifactElementEvents>;
+    'kai-attachments': KaiVueElement<KaiAttachmentsElementProps, KaiAttachmentsElementEvents>;
+    KaiAttachments: KaiVueElement<KaiAttachmentsElementProps, KaiAttachmentsElementEvents>;
+    'kai-audio-visualizer': KaiVueElement<KaiAudioVisualizerElementProps, KaiAudioVisualizerElementEvents>;
+    KaiAudioVisualizer: KaiVueElement<KaiAudioVisualizerElementProps, KaiAudioVisualizerElementEvents>;
+    'kai-avatar': KaiVueElement<KaiAvatarElementProps, KaiAvatarElementEvents>;
+    KaiAvatar: KaiVueElement<KaiAvatarElementProps, KaiAvatarElementEvents>;
+    'kai-badge': KaiVueElement<KaiBadgeElementProps, KaiBadgeElementEvents>;
+    KaiBadge: KaiVueElement<KaiBadgeElementProps, KaiBadgeElementEvents>;
+    'kai-button': KaiVueElement<KaiButtonElementProps, KaiButtonElementEvents>;
+    KaiButton: KaiVueElement<KaiButtonElementProps, KaiButtonElementEvents>;
+    'kai-card': KaiVueElement<KaiCardElementProps, KaiCardElementEvents>;
+    KaiCard: KaiVueElement<KaiCardElementProps, KaiCardElementEvents>;
+    'kai-cards': KaiVueElement<KaiCardsElementProps, KaiCardsElementEvents>;
+    KaiCards: KaiVueElement<KaiCardsElementProps, KaiCardsElementEvents>;
+    'kai-chain-of-thought': KaiVueElement<KaiChainOfThoughtElementProps, KaiChainOfThoughtElementEvents>;
+    KaiChainOfThought: KaiVueElement<KaiChainOfThoughtElementProps, KaiChainOfThoughtElementEvents>;
+    'kai-chat': KaiVueElement<KaiChatElementProps, KaiChatElementEvents>;
+    KaiChat: KaiVueElement<KaiChatElementProps, KaiChatElementEvents>;
+    'kai-checkpoint': KaiVueElement<KaiCheckpointElementProps, KaiCheckpointElementEvents>;
+    KaiCheckpoint: KaiVueElement<KaiCheckpointElementProps, KaiCheckpointElementEvents>;
+    'kai-choice': KaiVueElement<KaiChoiceElementProps, KaiChoiceElementEvents>;
+    KaiChoice: KaiVueElement<KaiChoiceElementProps, KaiChoiceElementEvents>;
+    'kai-coachmark': KaiVueElement<KaiCoachmarkElementProps, KaiCoachmarkElementEvents>;
+    KaiCoachmark: KaiVueElement<KaiCoachmarkElementProps, KaiCoachmarkElementEvents>;
+    'kai-code-block': KaiVueElement<KaiCodeBlockElementProps, KaiCodeBlockElementEvents>;
+    KaiCodeBlock: KaiVueElement<KaiCodeBlockElementProps, KaiCodeBlockElementEvents>;
+    'kai-command': KaiVueElement<KaiCommandElementProps, KaiCommandElementEvents>;
+    KaiCommand: KaiVueElement<KaiCommandElementProps, KaiCommandElementEvents>;
+    'kai-compare': KaiVueElement<KaiCompareElementProps, KaiCompareElementEvents>;
+    KaiCompare: KaiVueElement<KaiCompareElementProps, KaiCompareElementEvents>;
+    'kai-composer': KaiVueElement<KaiComposerElementProps, KaiComposerElementEvents>;
+    KaiComposer: KaiVueElement<KaiComposerElementProps, KaiComposerElementEvents>;
+    'kai-confirm': KaiVueElement<KaiConfirmElementProps, KaiConfirmElementEvents>;
+    KaiConfirm: KaiVueElement<KaiConfirmElementProps, KaiConfirmElementEvents>;
+    'kai-context': KaiVueElement<KaiContextElementProps, KaiContextElementEvents>;
+    KaiContext: KaiVueElement<KaiContextElementProps, KaiContextElementEvents>;
+    'kai-conversations': KaiVueElement<KaiConversationsElementProps, KaiConversationsElementEvents>;
+    KaiConversations: KaiVueElement<KaiConversationsElementProps, KaiConversationsElementEvents>;
+    'kai-dialog': KaiVueElement<KaiDialogElementProps, KaiDialogElementEvents>;
+    KaiDialog: KaiVueElement<KaiDialogElementProps, KaiDialogElementEvents>;
+    'kai-editable-label': KaiVueElement<KaiEditableLabelElementProps, KaiEditableLabelElementEvents>;
+    KaiEditableLabel: KaiVueElement<KaiEditableLabelElementProps, KaiEditableLabelElementEvents>;
+    'kai-embed': KaiVueElement<KaiEmbedElementProps, KaiEmbedElementEvents>;
+    KaiEmbed: KaiVueElement<KaiEmbedElementProps, KaiEmbedElementEvents>;
+    'kai-empty': KaiVueElement<KaiEmptyElementProps, KaiEmptyElementEvents>;
+    KaiEmpty: KaiVueElement<KaiEmptyElementProps, KaiEmptyElementEvents>;
+    'kai-feedback-bar': KaiVueElement<KaiFeedbackBarElementProps, KaiFeedbackBarElementEvents>;
+    KaiFeedbackBar: KaiVueElement<KaiFeedbackBarElementProps, KaiFeedbackBarElementEvents>;
+    'kai-file-tree': KaiVueElement<KaiFileTreeElementProps, KaiFileTreeElementEvents>;
+    KaiFileTree: KaiVueElement<KaiFileTreeElementProps, KaiFileTreeElementEvents>;
+    'kai-file-upload': KaiVueElement<KaiFileUploadElementProps, KaiFileUploadElementEvents>;
+    KaiFileUpload: KaiVueElement<KaiFileUploadElementProps, KaiFileUploadElementEvents>;
+    'kai-form': KaiVueElement<KaiFormElementProps, KaiFormElementEvents>;
+    KaiForm: KaiVueElement<KaiFormElementProps, KaiFormElementEvents>;
+    'kai-hover-card': KaiVueElement<KaiHoverCardElementProps, KaiHoverCardElementEvents>;
+    KaiHoverCard: KaiVueElement<KaiHoverCardElementProps, KaiHoverCardElementEvents>;
+    'kai-icon': KaiVueElement<KaiIconElementProps, KaiIconElementEvents>;
+    KaiIcon: KaiVueElement<KaiIconElementProps, KaiIconElementEvents>;
+    'kai-image': KaiVueElement<KaiImageElementProps, KaiImageElementEvents>;
+    KaiImage: KaiVueElement<KaiImageElementProps, KaiImageElementEvents>;
+    'kai-input': KaiVueElement<KaiInputElementProps, KaiInputElementEvents>;
+    KaiInput: KaiVueElement<KaiInputElementProps, KaiInputElementEvents>;
+    'kai-kbd': KaiVueElement<KaiKbdElementProps, KaiKbdElementEvents>;
+    KaiKbd: KaiVueElement<KaiKbdElementProps, KaiKbdElementEvents>;
+    'kai-link-preview': KaiVueElement<KaiLinkPreviewElementProps, KaiLinkPreviewElementEvents>;
+    KaiLinkPreview: KaiVueElement<KaiLinkPreviewElementProps, KaiLinkPreviewElementEvents>;
+    'kai-loader': KaiVueElement<KaiLoaderElementProps, KaiLoaderElementEvents>;
+    KaiLoader: KaiVueElement<KaiLoaderElementProps, KaiLoaderElementEvents>;
+    'kai-markdown': KaiVueElement<KaiMarkdownElementProps, KaiMarkdownElementEvents>;
+    KaiMarkdown: KaiVueElement<KaiMarkdownElementProps, KaiMarkdownElementEvents>;
+    'kai-menu': KaiVueElement<KaiMenuElementProps, KaiMenuElementEvents>;
+    KaiMenu: KaiVueElement<KaiMenuElementProps, KaiMenuElementEvents>;
+    'kai-message': KaiVueElement<KaiMessageElementProps, KaiMessageElementEvents>;
+    KaiMessage: KaiVueElement<KaiMessageElementProps, KaiMessageElementEvents>;
+    'kai-model-switcher': KaiVueElement<KaiModelSwitcherElementProps, KaiModelSwitcherElementEvents>;
+    KaiModelSwitcher: KaiVueElement<KaiModelSwitcherElementProps, KaiModelSwitcherElementEvents>;
+    'kai-nav': KaiVueElement<KaiNavElementProps, KaiNavElementEvents>;
+    KaiNav: KaiVueElement<KaiNavElementProps, KaiNavElementEvents>;
+    'kai-notice': KaiVueElement<KaiNoticeElementProps, KaiNoticeElementEvents>;
+    KaiNotice: KaiVueElement<KaiNoticeElementProps, KaiNoticeElementEvents>;
+    'kai-pane': KaiVueElement<KaiPaneElementProps, KaiPaneElementEvents>;
+    KaiPane: KaiVueElement<KaiPaneElementProps, KaiPaneElementEvents>;
+    'kai-pane-group': KaiVueElement<KaiPaneGroupElementProps, KaiPaneGroupElementEvents>;
+    KaiPaneGroup: KaiVueElement<KaiPaneGroupElementProps, KaiPaneGroupElementEvents>;
+    'kai-popover': KaiVueElement<KaiPopoverElementProps, KaiPopoverElementEvents>;
+    KaiPopover: KaiVueElement<KaiPopoverElementProps, KaiPopoverElementEvents>;
+    'kai-progress-bar': KaiVueElement<KaiProgressBarElementProps, KaiProgressBarElementEvents>;
+    KaiProgressBar: KaiVueElement<KaiProgressBarElementProps, KaiProgressBarElementEvents>;
+    'kai-prompt-dock': KaiVueElement<KaiPromptDockElementProps, KaiPromptDockElementEvents>;
+    KaiPromptDock: KaiVueElement<KaiPromptDockElementProps, KaiPromptDockElementEvents>;
+    'kai-prompt-input': KaiVueElement<KaiPromptInputElementProps, KaiPromptInputElementEvents>;
+    KaiPromptInput: KaiVueElement<KaiPromptInputElementProps, KaiPromptInputElementEvents>;
+    'kai-reasoning': KaiVueElement<KaiReasoningElementProps, KaiReasoningElementEvents>;
+    KaiReasoning: KaiVueElement<KaiReasoningElementProps, KaiReasoningElementEvents>;
+    'kai-remote': KaiVueElement<KaiRemoteElementProps, KaiRemoteElementEvents>;
+    KaiRemote: KaiVueElement<KaiRemoteElementProps, KaiRemoteElementEvents>;
+    'kai-resizable': KaiVueElement<KaiResizableElementProps, KaiResizableElementEvents>;
+    KaiResizable: KaiVueElement<KaiResizableElementProps, KaiResizableElementEvents>;
+    'kai-resizable-item': KaiVueElement<KaiResizableItemElementProps, KaiResizableItemElementEvents>;
+    KaiResizableItem: KaiVueElement<KaiResizableItemElementProps, KaiResizableItemElementEvents>;
+    'kai-response-stream': KaiVueElement<KaiResponseStreamElementProps, KaiResponseStreamElementEvents>;
+    KaiResponseStream: KaiVueElement<KaiResponseStreamElementProps, KaiResponseStreamElementEvents>;
+    'kai-scope-picker': KaiVueElement<KaiScopePickerElementProps, KaiScopePickerElementEvents>;
+    KaiScopePicker: KaiVueElement<KaiScopePickerElementProps, KaiScopePickerElementEvents>;
+    'kai-screen': KaiVueElement<KaiScreenElementProps, KaiScreenElementEvents>;
+    KaiScreen: KaiVueElement<KaiScreenElementProps, KaiScreenElementEvents>;
+    'kai-scroll-area': KaiVueElement<KaiScrollAreaElementProps, KaiScrollAreaElementEvents>;
+    KaiScrollArea: KaiVueElement<KaiScrollAreaElementProps, KaiScrollAreaElementEvents>;
+    'kai-scroll-button': KaiVueElement<KaiScrollButtonElementProps, KaiScrollButtonElementEvents>;
+    KaiScrollButton: KaiVueElement<KaiScrollButtonElementProps, KaiScrollButtonElementEvents>;
+    'kai-search': KaiVueElement<KaiSearchElementProps, KaiSearchElementEvents>;
+    KaiSearch: KaiVueElement<KaiSearchElementProps, KaiSearchElementEvents>;
+    'kai-segmented': KaiVueElement<KaiSegmentedElementProps, KaiSegmentedElementEvents>;
+    KaiSegmented: KaiVueElement<KaiSegmentedElementProps, KaiSegmentedElementEvents>;
+    'kai-separator': KaiVueElement<KaiSeparatorElementProps, KaiSeparatorElementEvents>;
+    KaiSeparator: KaiVueElement<KaiSeparatorElementProps, KaiSeparatorElementEvents>;
+    'kai-setting-item': KaiVueElement<KaiSettingItemElementProps, KaiSettingItemElementEvents>;
+    KaiSettingItem: KaiVueElement<KaiSettingItemElementProps, KaiSettingItemElementEvents>;
+    'kai-settings-group': KaiVueElement<KaiSettingsGroupElementProps, KaiSettingsGroupElementEvents>;
+    KaiSettingsGroup: KaiVueElement<KaiSettingsGroupElementProps, KaiSettingsGroupElementEvents>;
+    'kai-skeleton': KaiVueElement<KaiSkeletonElementProps, KaiSkeletonElementEvents>;
+    KaiSkeleton: KaiVueElement<KaiSkeletonElementProps, KaiSkeletonElementEvents>;
+    'kai-skills': KaiVueElement<KaiSkillsElementProps, KaiSkillsElementEvents>;
+    KaiSkills: KaiVueElement<KaiSkillsElementProps, KaiSkillsElementEvents>;
+    'kai-source': KaiVueElement<KaiSourceElementProps, KaiSourceElementEvents>;
+    KaiSource: KaiVueElement<KaiSourceElementProps, KaiSourceElementEvents>;
+    'kai-sources': KaiVueElement<KaiSourcesElementProps, KaiSourcesElementEvents>;
+    KaiSources: KaiVueElement<KaiSourcesElementProps, KaiSourcesElementEvents>;
+    'kai-status': KaiVueElement<KaiStatusElementProps, KaiStatusElementEvents>;
+    KaiStatus: KaiVueElement<KaiStatusElementProps, KaiStatusElementEvents>;
+    'kai-suggestions': KaiVueElement<KaiSuggestionsElementProps, KaiSuggestionsElementEvents>;
+    KaiSuggestions: KaiVueElement<KaiSuggestionsElementProps, KaiSuggestionsElementEvents>;
+    'kai-switch': KaiVueElement<KaiSwitchElementProps, KaiSwitchElementEvents>;
+    KaiSwitch: KaiVueElement<KaiSwitchElementProps, KaiSwitchElementEvents>;
+    'kai-tabs': KaiVueElement<KaiTabsElementProps, KaiTabsElementEvents>;
+    KaiTabs: KaiVueElement<KaiTabsElementProps, KaiTabsElementEvents>;
+    'kai-tasks': KaiVueElement<KaiTasksElementProps, KaiTasksElementEvents>;
+    KaiTasks: KaiVueElement<KaiTasksElementProps, KaiTasksElementEvents>;
+    'kai-text-shimmer': KaiVueElement<KaiTextShimmerElementProps, KaiTextShimmerElementEvents>;
+    KaiTextShimmer: KaiVueElement<KaiTextShimmerElementProps, KaiTextShimmerElementEvents>;
+    'kai-thinking-bar': KaiVueElement<KaiThinkingBarElementProps, KaiThinkingBarElementEvents>;
+    KaiThinkingBar: KaiVueElement<KaiThinkingBarElementProps, KaiThinkingBarElementEvents>;
+    'kai-thread': KaiVueElement<KaiThreadElementProps, KaiThreadElementEvents>;
+    KaiThread: KaiVueElement<KaiThreadElementProps, KaiThreadElementEvents>;
+    'kai-toast-region': KaiVueElement<KaiToastRegionElementProps, KaiToastRegionElementEvents>;
+    KaiToastRegion: KaiVueElement<KaiToastRegionElementProps, KaiToastRegionElementEvents>;
+    'kai-tool': KaiVueElement<KaiToolElementProps, KaiToolElementEvents>;
+    KaiTool: KaiVueElement<KaiToolElementProps, KaiToolElementEvents>;
+    'kai-tooltip': KaiVueElement<KaiTooltipElementProps, KaiTooltipElementEvents>;
+    KaiTooltip: KaiVueElement<KaiTooltipElementProps, KaiTooltipElementEvents>;
+    'kai-voice-input': KaiVueElement<KaiVoiceInputElementProps, KaiVoiceInputElementEvents>;
+    KaiVoiceInput: KaiVueElement<KaiVoiceInputElementProps, KaiVoiceInputElementEvents>;
+    'kai-voice-output': KaiVueElement<KaiVoiceOutputElementProps, KaiVoiceOutputElementEvents>;
+    KaiVoiceOutput: KaiVueElement<KaiVoiceOutputElementProps, KaiVoiceOutputElementEvents>;
+    'kai-workspace': KaiVueElement<KaiWorkspaceElementProps, KaiWorkspaceElementEvents>;
+    KaiWorkspace: KaiVueElement<KaiWorkspaceElementProps, KaiWorkspaceElementEvents>;
+  }
+}