@kitn.ai/ui 0.17.0 → 0.18.1

package/dist/elements.d.ts

@@ -25,20 +25,119 @@ export interface CodeHighlightingOptions {
   aliases?: Record<string, string>;
 }
 
-// Runtime values live in the compiled `default` (dist/kitn-chat.es.js); we only
+// Runtime values live in the compiled `default` (dist/kai.es.js); we only
 // DECLARE their signatures here so the .d.ts pulls no source.
 export declare function configureCodeHighlighting(options: CodeHighlightingOptions): void;
 export declare function isCodeHighlightingEnabled(): boolean;
 
+/** Resolves once the kai-* elements are registered (browser); inert on the server. */
+export declare const elementsReady: Promise<unknown>;
+
+// --- Inlined from src/primitives/toast-store.ts (kept self-contained: no source imports) ---
+export type ToastVariant = 'neutral' | 'success' | 'warning' | 'error' | 'info';
+
+export interface ToastConfig {
+  stack?: 'expanded' | 'collapsed';
+  position?: 'top-center' | 'top-right' | 'top-left' | 'bottom-center' | 'bottom-right' | 'bottom-left';
+  max?: number;
+  /** Default appearance for imperatively-raised toasts. Defaults to `'pill'`. */
+  appearance?: 'pill' | 'card';
+  /** Default high-contrast inverse treatment. Defaults to `false`. */
+  inverse?: boolean;
+}
+
+/** An action button rendered inside the toast. Returning `false` from `onAction`
+ *  keeps the toast open; any other return value dismisses it. */
+export interface ToastAction {
+  label: string;
+  onAction: () => void | false;
+}
+
+export interface ToastItem {
+  id: string;
+  message: string;
+  variant?: ToastVariant;
+  /** Visual treatment: `'pill'` (default) or `'card'`. */
+  appearance?: 'pill' | 'card';
+  /** High-contrast inverse surface. Defaults to `false`. */
+  inverse?: boolean;
+  /** Secondary line shown below the message in the `'card'` appearance. */
+  description?: string;
+  action?: ToastAction;
+  /** Auto-dismiss delay in ms. `0` = sticky. */
+  duration?: number;
+  /** Whether the close affordance is shown. Defaults to `true`. */
+  dismissible?: boolean;
+  /** Container to scope this toast within instead of the viewport. */
+  target?: HTMLElement;
+}
+
+/** Options accepted by `toast()` — everything but the message. */
+export interface ToastOptions {
+  id?: string;
+  variant?: ToastVariant;
+  appearance?: 'pill' | 'card';
+  inverse?: boolean;
+  description?: string;
+  action?: ToastAction;
+  duration?: number;
+  dismissible?: boolean;
+  target?: HTMLElement;
+}
+
+/** Handle returned from `toast()` for imperative control. */
+export interface ToastHandle {
+  id: string;
+  dismiss: () => void;
+  update: (patch: Partial<Omit<ToastItem, 'id'>>) => void;
+}
+
+// Runtime values live in the compiled `default` (dist/kai.es.js); we only
+// DECLARE their signatures here so the .d.ts pulls no source.
+/** Raise a transient toast. `toast('Saved')`, `toast.success('Copied')`,
+ *  `toast.dismiss(id)`. Returns a `{ id, dismiss, update }` handle. */
+export declare const toast: {
+  (message: string, opts?: ToastOptions): ToastHandle;
+  /** Raise a success (green check) toast. */
+  success: (message: string, opts?: ToastOptions) => ToastHandle;
+  /** Raise a warning (amber) toast. */
+  warning: (message: string, opts?: ToastOptions) => ToastHandle;
+  /** Raise an error (destructive/red) toast. */
+  error: (message: string, opts?: ToastOptions) => ToastHandle;
+  /** Raise an info (blue) toast. */
+  info: (message: string, opts?: ToastOptions) => ToastHandle;
+  /** Dismiss a toast by id. */
+  dismiss: (id: string) => void;
+  /** Dismiss every active toast. */
+  clear: () => void;
+};
+/** Configure the imperative `toast()` singleton — call once at app start. */
+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`. */
+  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`. */
+  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 KaiArtifactElement extends HTMLElement {
   /** 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`. Set as a JS property (array). */
-  files: { path: string; url?: undefined | string; code?: undefined | string; language?: undefined | string; type?: undefined | "html" | "pdf" | "image" | "other" }[];
-  /** Active tab: `preview` (default) or `code`. */
+  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" }[];
+  /** 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`). */
@@ -65,6 +164,8 @@ export interface KaiArtifactElement extends HTMLElement {
   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 KaiAttachmentsElement extends HTMLElement {
@@ -84,17 +185,70 @@ export interface KaiAttachmentsElement extends HTMLElement {
   emptyText?: string;
 }
 
+export interface KaiAvatarElement extends HTMLElement {
+  /** 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 KaiBadgeElement extends HTMLElement {
+  /** 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 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`. */
+  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 KaiCardElement extends HTMLElement {
   /** Color mode (`auto` follows prefers-color-scheme). */
   theme?: 'light' | 'dark' | 'auto';
-  /** Heading rendered in the card chrome (= CardEnvelope.title). Attribute: `heading`. */
-  heading?: string;
-  /** Supporting text under the heading. Attribute: `description`. */
-  description?: string;
-  /** When set, the card renders its inline error state instead of the body. Attribute: `error-message`. */
-  errorMessage?: string;
-  /** Compact spacing for dense lists. Attribute: `dense`. */
+  /** 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`. */
+  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 KaiCardsElement extends HTMLElement {
@@ -111,8 +265,14 @@ export interface KaiCardsElement extends HTMLElement {
 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). */
-  steps: { label: string; content?: undefined | string }[];
+  /** 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). */
+  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. */
+  defaultValue?: string | string[];
 }
 
 export interface KaiChatElement extends HTMLElement {
@@ -120,8 +280,8 @@ export interface KaiChatElement extends HTMLElement {
   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" }[];
-  /** Controlled value of the input. When set, the host owns the input text and must update it on `kai-value-change`; leave unset for uncontrolled behavior. */
-  value?: string;
+  /** 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). */
@@ -133,7 +293,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?: "xs" | "sm" | "base" | "lg";
+  proseSize?: "sm" | "lg" | "xs" | "base";
   /** 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. */
@@ -152,16 +312,26 @@ export interface KaiChatElement extends HTMLElement {
   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 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;
-  /** Slash commands — when set, typing `/` in the input opens the command palette and fires `kai-slash-select`. Set as a JS property. */
-  slashCommands?: { id: string; label: string; description?: string; category?: string }[];
-  /** Command ids to highlight as active in the palette. */
-  slashActiveIds?: string[];
-  /** Single-line palette rows. */
-  slashCompact?: 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";
 }
@@ -174,9 +344,9 @@ export interface KaiCheckpointElement extends HTMLElement {
   /** Tooltip on hover. */
   tooltip?: string;
   /** Visual button style. */
-  variant?: "ghost" | "default" | "outline";
+  variant?: "default" | "ghost" | "outline";
   /** Button size (use an `icon*` size for an icon-only checkpoint). */
-  size?: "sm" | "lg" | "md" | "icon" | "icon-sm";
+  size?: "sm" | "md" | "lg" | "icon" | "icon-sm";
 }
 
 export interface KaiChoiceElement extends HTMLElement {
@@ -190,6 +360,31 @@ export interface KaiChoiceElement extends HTMLElement {
   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 KaiCoachmarkElement extends HTMLElement {
+  /** 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?: "error" | "primary" | "info" | "success" | "warning";
+  /** Render the arrow that points at the anchor (default `true`). Set `arrow="false"` for a plain bubble with no pointer. */
+  arrow?: boolean;
 }
 
 export interface KaiCodeBlockElement extends HTMLElement {
@@ -204,7 +399,18 @@ export interface KaiCodeBlockElement extends HTMLElement {
   /** Disable syntax highlighting (renders plain text, no Shiki). */
   codeHighlight?: boolean;
   /** Code text sizing. */
-  proseSize?: "xs" | "sm" | "base" | "lg";
+  proseSize?: "sm" | "lg" | "xs" | "base";
+}
+
+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. */
+  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 KaiCompareElement extends HTMLElement {
@@ -219,13 +425,36 @@ export interface KaiCompareElement extends HTMLElement {
   /** 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";
+  proseSize?: "sm" | "lg" | "xs" | "base";
   /** 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 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). */
+  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?: string | number;
+  /** 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 KaiConfirmElement extends HTMLElement {
   /** Color mode (`auto` follows prefers-color-scheme). */
   theme?: 'light' | 'dark' | 'auto';
@@ -258,9 +487,35 @@ export interface KaiConversationsElement extends HTMLElement {
   /** 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 }[];
+  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 }[];
   /** 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 KaiDialogElement extends HTMLElement {
+  /** 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 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. */
+  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 KaiEmbedElement extends HTMLElement {
@@ -303,12 +558,14 @@ export interface KaiFeedbackBarElement extends HTMLElement {
 export interface KaiFileTreeElement extends HTMLElement {
   /** 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? }`). */
-  files: { path: string; url?: undefined | string; code?: undefined | string; language?: undefined | string; type?: undefined | "html" | "pdf" | "image" | "other" }[];
+  /** 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 KaiFileUploadElement extends HTMLElement {
@@ -335,6 +592,38 @@ export interface KaiFormElement extends HTMLElement {
   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 KaiHoverCardElement extends HTMLElement {
+  /** 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 KaiIconElement extends HTMLElement {
+  /** 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 KaiImageElement extends HTMLElement {
@@ -350,6 +639,50 @@ export interface KaiImageElement extends HTMLElement {
   mediaType?: string;
 }
 
+export interface KaiInputElement extends HTMLElement {
+  /** 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 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. */
+  keys?: string;
+  /** `mac` uses ⌘/⌥, `other` uses Ctrl. `auto` (default) sniffs the OS. */
+  platform?: "other" | "auto" | "mac";
+  /** 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';
@@ -365,7 +698,7 @@ export interface KaiLoaderElement extends HTMLElement {
   /** 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" | "lg" | "md";
+  size?: "sm" | "md" | "lg";
   /** Label for the text-based variants. */
   text?: string;
 }
@@ -376,13 +709,36 @@ export interface KaiMarkdownElement extends HTMLElement {
   /** The markdown source to render. */
   content: string;
   /** Text/markdown sizing. */
-  proseSize?: "xs" | "sm" | "base" | "lg";
+  proseSize?: "sm" | "lg" | "xs" | "base";
   /** Shiki theme for fenced code blocks. */
   codeTheme?: string;
   /** Disable syntax highlighting (no Shiki loads). */
   codeHighlight?: boolean;
 }
 
+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. */
+  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 KaiMessageElement extends HTMLElement {
   /** Color mode (`auto` follows prefers-color-scheme). */
   theme?: 'light' | 'dark' | 'auto';
@@ -395,7 +751,7 @@ export interface KaiMessageElement extends HTMLElement {
   /** 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";
+  proseSize?: "sm" | "lg" | "xs" | "base";
   /** Shiki theme name used for fenced code blocks in the content. */
   codeTheme?: string;
   /** Disable syntax highlighting for code blocks (no Shiki loads). */
@@ -406,6 +762,8 @@ export interface KaiMessageElement extends HTMLElement {
   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;
 }
 
 export interface KaiModelSwitcherElement extends HTMLElement {
@@ -415,6 +773,66 @@ export interface KaiModelSwitcherElement extends HTMLElement {
   models: { id: string; name: string; provider?: undefined | string; description?: undefined | string; group?: undefined | 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 KaiNavElement extends HTMLElement {
+  /** 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: "error" | "primary" | "info" | "success" | "warning" | "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 KaiNoticeElement extends HTMLElement {
+  /** 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?: "error" | "info" | "success" | "warning" | "neutral";
+  /** 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 KaiPaneElement extends HTMLElement {
+  /** 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 KaiPaneGroupElement extends HTMLElement {
+  /** 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 KaiPopoverElement extends HTMLElement {
@@ -424,15 +842,41 @@ export interface KaiPopoverElement extends HTMLElement {
   placement?: "top" | "right" | "bottom" | "left" | "top-start" | "top-end" | "right-start" | "right-end" | "bottom-start" | "bottom-end" | "left-start" | "left-end";
   /** Gap in px between the trigger and the panel. */
   gutter?: number;
-  /** Controlled open state. Set as a JS property (`el.open = true`) to drive the popover from your app; omit for the default click-to-toggle behaviour. */
+  /** 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 KaiProgressBarElement extends HTMLElement {
+  /** 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 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";
 }
 
 export interface KaiPromptInputElement extends HTMLElement {
   /** Color mode (`auto` follows prefers-color-scheme). */
   theme?: 'light' | 'dark' | 'auto';
-  /** Controlled value of the input. When set, the host owns the text and must update it on `kai-value-change`; leave unset for uncontrolled behavior. */
-  value?: string;
+  /** 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). */
@@ -443,20 +887,22 @@ export interface KaiPromptInputElement extends HTMLElement {
   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";
-  /** Slash commands — when set, typing `/` opens the command palette. Set as a JS property. */
-  slashCommands?: { id: string; label: string; description?: string; category?: string }[];
-  /** Command ids to highlight as active. */
-  slashActiveIds?: string[];
-  /** Single-line palette rows. */
-  slashCompact?: boolean;
   /** 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 — 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 KaiReasoningElement extends HTMLElement {
@@ -466,12 +912,16 @@ export interface KaiReasoningElement extends HTMLElement {
   text: string;
   /** Trigger label. */
   label?: string;
-  /** Controlled open state — set as a property (`el.open = true`). Omit for uncontrolled (the trigger toggles it). */
+  /** 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 KaiRemoteElement extends HTMLElement {
@@ -491,7 +941,7 @@ export interface KaiResizableElement extends HTMLElement {
   /** Color mode (`auto` follows prefers-color-scheme). */
   theme?: 'light' | 'dark' | 'auto';
   /** Layout axis: `horizontal` (row, default) or `vertical` (column). */
-  orientation?: "horizontal" | "vertical";
+  orientation?: "vertical" | "horizontal";
   /** Which item index is maximized (null = none). Declarative source of truth. */
   maximizedIndex?: null | number;
 }
@@ -509,6 +959,8 @@ export interface KaiResizableItemElement extends HTMLElement {
   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 KaiResponseStreamElement extends HTMLElement {
@@ -533,6 +985,34 @@ export interface KaiScopePickerElement extends HTMLElement {
   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 KaiScreenElement extends HTMLElement {
+  /** 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 KaiScrollAreaElement extends HTMLElement {
+  /** 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 KaiScrollButtonElement extends HTMLElement {
@@ -541,9 +1021,75 @@ export interface KaiScrollButtonElement extends HTMLElement {
   /** 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?: "ghost" | "default" | "outline";
+  variant?: "default" | "ghost" | "outline";
   /** Button size token. Defaults to `'icon'` (square). */
-  size?: "sm" | "lg" | "md" | "icon" | "icon-sm";
+  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. */
+  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 KaiSegmentedElement extends HTMLElement {
+  /** 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 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";
+}
+
+export interface KaiSettingItemElement extends HTMLElement {
+  /** 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 KaiSettingsGroupElement extends HTMLElement {
+  /** 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 KaiSkeletonElement extends HTMLElement {
+  /** 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 KaiSkillsElement extends HTMLElement {
@@ -579,15 +1125,30 @@ export interface KaiSourcesElement extends HTMLElement {
   numbered?: boolean;
 }
 
+export interface KaiStatusElement extends HTMLElement {
+  /** 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 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 })[];
+  suggestions: (string | { label: string; value?: undefined | string; icon?: undefined | string })[];
   /** Chip style: `'outline'` (default), `'ghost'`, or `'default'` (filled). */
-  variant?: "ghost" | "default" | "outline";
-  /** Size preset for each chip. Defaults to the pill default (`'lg'`); pass `'sm'` for smaller pills (or `'md'`). */
-  size?: "sm" | "lg" | "md" | "icon" | "icon-sm";
+  variant?: "default" | "ghost" | "outline";
+  /** 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";
   /** Full-width left-aligned rows instead of pills. */
   block?: boolean;
   /** Substring to highlight within each suggestion. */
@@ -597,12 +1158,35 @@ export interface KaiSuggestionsElement extends HTMLElement {
 export interface KaiSwitchElement extends HTMLElement {
   /** Color mode (`auto` follows prefers-color-scheme). */
   theme?: 'light' | 'dark' | 'auto';
-  /** Initial checked state. Bare attribute (`<kai-switch checked>`) turns it on. */
+  /** 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 KaiTabsElement extends HTMLElement {
+  /** 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 KaiTasksElement extends HTMLElement {
@@ -616,6 +1200,14 @@ export interface KaiTasksElement extends HTMLElement {
   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 KaiTextShimmerElement extends HTMLElement {
@@ -646,13 +1238,17 @@ 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 | "neutral" | "success"; action?: undefined | { label: string; onAction: () => void | false }; duration?: undefined | number; dismissible?: undefined | boolean; target?: undefined | HTMLElement }[];
+  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 }[];
   /** 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;
 }
@@ -662,8 +1258,31 @@ export interface KaiToolElement extends HTMLElement {
   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 };
-  /** Start expanded. */
+  /** 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 KaiTooltipElement extends HTMLElement {
+  /** 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 KaiVoiceInputElement extends HTMLElement {
@@ -673,6 +1292,23 @@ export interface KaiVoiceInputElement extends HTMLElement {
   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 KaiVoiceOutputElement extends HTMLElement {
+  /** 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 KaiWorkspaceElement extends HTMLElement {
@@ -681,7 +1317,7 @@ export interface KaiWorkspaceElement extends HTMLElement {
   /** 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 }[];
+  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 }[];
   /** Id of the open conversation, highlighted in the sidebar. */
   activeId?: string;
   /** The active conversation's message thread, newest last. Set as a JS property. */
@@ -691,7 +1327,7 @@ export interface KaiWorkspaceElement extends HTMLElement {
   loading?: boolean;
   suggestions?: string[];
   suggestionMode?: "submit" | "fill";
-  proseSize?: "xs" | "sm" | "base" | "lg";
+  proseSize?: "sm" | "lg" | "xs" | "base";
   codeTheme?: string;
   codeHighlight?: boolean;
   chatTitle?: string;
@@ -701,12 +1337,13 @@ export interface KaiWorkspaceElement extends HTMLElement {
   scrollButton?: boolean;
   search?: boolean;
   voice?: boolean;
-  slashCommands?: { id: string; label: string; description?: string; category?: string }[];
-  slashActiveIds?: string[];
-  slashCompact?: boolean;
-  /** Sidebar default width as a percent of the workspace (default 22). */
+  /** 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 200). */
+  /** Sidebar min width in px (default 240). */
   sidebarMinWidth?: number;
   /** Sidebar max width in px (default 420). */
   sidebarMaxWidth?: number;
@@ -714,36 +1351,62 @@ export interface KaiWorkspaceElement extends HTMLElement {
   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;
 }
 
 declare global {
   interface HTMLElementTagNameMap {
+    'kai-agent-card': KaiAgentCardElement;
     'kai-artifact': KaiArtifactElement;
     'kai-attachments': KaiAttachmentsElement;
+    'kai-avatar': KaiAvatarElement;
+    'kai-badge': KaiBadgeElement;
+    'kai-button': KaiButtonElement;
     'kai-card': KaiCardElement;
     'kai-cards': KaiCardsElement;
     'kai-chain-of-thought': KaiChainOfThoughtElement;
     'kai-chat': KaiChatElement;
     'kai-checkpoint': KaiCheckpointElement;
     'kai-choice': KaiChoiceElement;
+    'kai-coachmark': KaiCoachmarkElement;
     'kai-code-block': KaiCodeBlockElement;
+    'kai-command': KaiCommandElement;
     'kai-compare': KaiCompareElement;
+    'kai-composer': KaiComposerElement;
     'kai-confirm': KaiConfirmElement;
     'kai-context': KaiContextElement;
     'kai-conversations': KaiConversationsElement;
+    'kai-dialog': KaiDialogElement;
+    'kai-editable-label': KaiEditableLabelElement;
     'kai-embed': KaiEmbedElement;
     'kai-empty': KaiEmptyElement;
     'kai-feedback-bar': KaiFeedbackBarElement;
     'kai-file-tree': KaiFileTreeElement;
     'kai-file-upload': KaiFileUploadElement;
     'kai-form': KaiFormElement;
+    'kai-hover-card': KaiHoverCardElement;
+    'kai-icon': KaiIconElement;
     'kai-image': KaiImageElement;
+    'kai-input': KaiInputElement;
+    'kai-kbd': KaiKbdElement;
     'kai-link-preview': KaiLinkPreviewElement;
     'kai-loader': KaiLoaderElement;
     'kai-markdown': KaiMarkdownElement;
+    'kai-menu': KaiMenuElement;
     'kai-message': KaiMessageElement;
     'kai-model-switcher': KaiModelSwitcherElement;
+    'kai-nav': KaiNavElement;
+    'kai-notice': KaiNoticeElement;
+    'kai-pane': KaiPaneElement;
+    'kai-pane-group': KaiPaneGroupElement;
     'kai-popover': KaiPopoverElement;
+    'kai-progress-bar': KaiProgressBarElement;
+    'kai-prompt-dock': KaiPromptDockElement;
     'kai-prompt-input': KaiPromptInputElement;
     'kai-reasoning': KaiReasoningElement;
     'kai-remote': KaiRemoteElement;
@@ -751,18 +1414,30 @@ declare global {
     'kai-resizable-item': KaiResizableItemElement;
     'kai-response-stream': KaiResponseStreamElement;
     'kai-scope-picker': KaiScopePickerElement;
+    'kai-screen': KaiScreenElement;
+    'kai-scroll-area': KaiScrollAreaElement;
     'kai-scroll-button': KaiScrollButtonElement;
+    'kai-search': KaiSearchElement;
+    'kai-segmented': KaiSegmentedElement;
+    'kai-separator': KaiSeparatorElement;
+    'kai-setting-item': KaiSettingItemElement;
+    'kai-settings-group': KaiSettingsGroupElement;
+    'kai-skeleton': KaiSkeletonElement;
     'kai-skills': KaiSkillsElement;
     'kai-source': KaiSourceElement;
     'kai-sources': KaiSourcesElement;
+    'kai-status': KaiStatusElement;
     'kai-suggestions': KaiSuggestionsElement;
     'kai-switch': KaiSwitchElement;
+    'kai-tabs': KaiTabsElement;
     'kai-tasks': KaiTasksElement;
     'kai-text-shimmer': KaiTextShimmerElement;
     'kai-thinking-bar': KaiThinkingBarElement;
     'kai-toast-region': KaiToastRegionElement;
     'kai-tool': KaiToolElement;
+    'kai-tooltip': KaiTooltipElement;
     'kai-voice-input': KaiVoiceInputElement;
+    'kai-voice-output': KaiVoiceOutputElement;
     'kai-workspace': KaiWorkspaceElement;
   }
 }