<!-- AUTO-GENERATED by scripts/gen-llms.mjs — do not edit by hand. Run `npm run build`. -->
# @kitn.ai/ui — Full Reference

# @kitn.ai/ui

> Framework-agnostic, Shadow-DOM web components for building AI chat interfaces — works in React, Vue, Angular, Svelte, or plain HTML. 96 custom elements, every one prefixed `kai-` (e.g. `<kai-chat>`, `<kai-artifact>`): streaming responses, markdown + code rendering, reasoning/tool panels, attachments, conversation sidebar, voice input. Zero framework dependency for consumers; the SolidJS runtime it is authored in is bundled in, so the host needs nothing.

## Install

```bash
npm install @kitn.ai/ui
# SolidJS consumers also need the peer dep:
npm install solid-js
```

## #1 rule: array/object data goes on JS PROPERTIES, not HTML attributes

This is the single most common mistake. Arrays and objects (`messages`, `models`, `context`, `suggestions`, `triggers`, …) MUST be assigned as JavaScript properties on the element. They CANNOT be passed as HTML attributes — an HTML attribute is always a string and will be ignored or mis-parsed.

```js
const chat = document.querySelector('kai-chat');
chat.messages = [{ id: '1', role: 'assistant', parts: [{ type: 'text', text: 'Hi!' }] }]; // ✅ property
```
```html
<kai-chat messages="[...]"></kai-chat>  <!-- ❌ never works -->
```

Only scalar values (string/number/boolean) work as attributes (e.g. `placeholder`, `loading`, `theme`).

## Two layers

**Layer 1 — batteries-included web components** (`import '@kitn.ai/ui/elements'`):
Drop an element into any framework (React, Vue, plain HTML). Data in via JS properties; interactions out via non-bubbling CustomEvents.

- `<kai-chat>` — full chat UI (message list + prompt input). The primary starting point.
- `<kai-conversations>` — sidebar conversation browser with group support.
- `<kai-prompt-input>` — standalone composer with send button.

**Layer 2 — composable primitives** (`import { … } from '@kitn.ai/ui'`):
All 96 elements are also exported individually. Use them for custom layouts or features `<kai-chat>` does not expose (ChainOfThought, FeedbackBar, ThinkingBar, VoiceInput, …). Your bundler tree-shakes the rest.

## Key rules for the web components

1. **Array/object data = JS properties** (see above). Scalars may be attributes.
2. **Events are non-bubbling `CustomEvent`s** — listen directly on the element:
   `chat.addEventListener('kai-submit', (e) => console.log(e.detail.value))`
3. **`theme` attribute** (`'light' | 'dark' | 'auto'`) works on every element. Default `auto` follows `prefers-color-scheme`.
4. **Theming via CSS custom properties** — override `--kai-color-*` tokens on `:root`; they pierce Shadow DOM.

## ChatMessage schema (required for `<kai-chat>`)

A message's content is an **ordered `parts` array**. There is no `content` string: it was removed in 0.20.0. Text, reasoning, tool calls, generative-UI cards, citations and file attachments all live in `parts`, in the order the model produced them, so a post-tool answer renders below its tool panel instead of being glued onto the pre-tool text.

```ts
interface ChatMessage {
  id: string;
  role: 'user' | 'assistant';
  /** The ONLY content channel. Ordered. */
  parts: MessagePart[];
  /** Action buttons under the message. Chrome, not content. */
  actions?: ('copy' | 'like' | 'dislike' | 'regenerate' | 'edit' | 'speak')[];
  avatar?: { src?: string; fallback?: string; alt?: string };
  feedback?: 'like' | 'dislike';
}

/** Six variants, one per kind of content. Every variant may also carry `raw`
 *  (`{ source, payload }`), the untranslated provider block the part was
 *  normalized from, for echoing a turn back to the model verbatim. */
type MessagePart =
  | { type: 'text'; text: string; raw?: RawOrigin }
  | { type: 'reasoning'; text: string; label?: string; index?: number; signature?: string; raw?: RawOrigin }
  | { type: 'tool'; tool: ToolPart; raw?: RawOrigin }
  | { type: 'card'; envelope: CardEnvelope; raw?: RawOrigin }
  | { type: 'source'; source: MessageSource; raw?: RawOrigin }
  | { type: 'file'; attachment: AttachmentData; raw?: RawOrigin };

interface ToolPart {
  type: string;
  /** Rendering classification. Derived from `type` when you omit it; an explicit
   *  value you set is preserved across later patches. */
  kind?: 'command' | 'file-change' | 'search' | 'fetch' | 'mcp' | 'image' | 'generic';
  state: 'input-streaming' | 'input-available' | 'output-available' | 'output-error';
  input?: Record<string, unknown>;
  /** Raw accumulated argument fragments, for character-level streaming. */
  rawInput?: string;
  output?: Record<string, unknown>;
  toolCallId?: string;
  errorText?: string;
  raw?: RawOrigin;
}

/** A citation. Exported as `MessageSource` (the bare `Source` name belongs to
 *  the citation-chip component). */
interface MessageSource { id?: string; url?: string; title?: string; snippet?: string; index?: number }
```

The simplest possible message, and one with reasoning + a tool call before its answer:

```js
{ id: '1', role: 'assistant', parts: [{ type: 'text', text: 'Hi!' }] }

{
  id: '2',
  role: 'assistant',
  parts: [
    { type: 'reasoning', text: 'I should search for current pricing.' },
    { type: 'tool', tool: { type: 'search', state: 'output-available', toolCallId: 'tc_1',
        input: { query: 'current pricing' }, output: { results: ['A', 'B'] } } },
    { type: 'text', text: 'Here is what I found.' },
  ],
}
```

Types are importable: `import type { ChatMessage, MessagePart, MessageSource } from '@kitn.ai/ui'` (also from `'@kitn.ai/ui/react'` and `'@kitn.ai/ui/state'`).

## Framework wiring

**Plain HTML / CDN**
```html
<script type="module" src="https://unpkg.com/@kitn.ai/ui/elements"></script>
<kai-chat style="display:block;height:100vh"></kai-chat>
<script type="module">
  const chat = document.querySelector('kai-chat');
  chat.messages = [];
</script>
```

**React** — typed wrappers auto-set properties and expose `on<Event>` props:
```tsx
import { Chat } from '@kitn.ai/ui/react';
<Chat messages={messages} onSubmit={(e) => send(e.detail.value)} />
```

**Vue** — use the element directly; pass arrays via `.prop`:
```vue
<kai-chat :messages.prop="messages" @kai-submit="send" />
```

## Theming

```css
:root {
  --kai-color-background: #0f0f0f;
  --kai-color-primary: #7c3aed;
  --kai-color-muted: #1e1e1e;
}
```

For plain HTML/CDN: `<link rel="stylesheet" href="…/@kitn.ai/ui/theme.tokens.css">`.
For Tailwind builds: `@import "@kitn.ai/ui/theme.css"` in your CSS.

## Docs

- Element reference (all 96 elements, every prop/event/method/slot/part): the "Element reference" section of ./llms-full.txt — https://kitn.dev/llms-full.txt
- Programmatic layer (`@kitn.ai/ui/state` + `@kitn.ai/ui/wire`: streaming folds, the mock responder, the SSE readers/encoders): the "Programmatic layer" section of llms-full.txt
- How to build a chat app in 5 steps (install → pick a layer → handle submit + stream → wire features → theme, with working code): the "How to build a chat app in 5 steps" section of llms-full.txt
- Streaming recipe (the two rules that bite: reassign new references per chunk, fold deltas onto the trailing text part): the "Streaming recipe" section of llms-full.txt
- Icon roster (every name `kai-icon` and the elements' `icon` props resolve; anything else fails loud): the "Icon roster" section of llms-full.txt
- Machine-readable Custom Elements Manifest: https://unpkg.com/@kitn.ai/ui/dist/custom-elements.json
- Working examples: https://github.com/kitn-ai/ui/tree/main/examples
- Storybook: https://storybook.kitn.dev
- Repository: https://github.com/kitn-ai/ui

---

## How to build a chat app in 5 steps

### 1 — Install
```bash
npm install @kitn.ai/ui
```

### 2 — Pick your layer
Drop-in: use `<kai-chat>` for a full chat UI in one tag (`import '@kitn.ai/ui/elements'`).
Composable: combine `<kai-message>`, `<kai-prompt-input>`, `<kai-reasoning>`, … in your own markup.

### 3 — Handle `submit` and stream
```js
import '@kitn.ai/ui/elements';
// The streaming fold. It is 5 lines if you would rather inline it: see the
// Streaming recipe below.
import { appendTextPart } from '@kitn.ai/ui/state';

const chat = document.querySelector('kai-chat');
chat.messages = [];

chat.addEventListener('kai-submit', async (e) => {
  const userText = e.detail.value;

  // Append the user message (new array, see the streaming note)
  const history = [...chat.messages, { id: crypto.randomUUID(), role: 'user', parts: [{ type: 'text', text: userText }] }];
  chat.messages = history;
  chat.loading = true;

  // Add an empty assistant placeholder to stream into
  const aid = crypto.randomUUID();
  chat.messages = [...history, { id: aid, role: 'assistant', parts: [] }];

  for await (const token of streamFromYourAPI(history)) {
    // Fold each delta onto the message's TRAILING text part. Do NOT replace
    // `parts` wholesale: that drops reasoning/tool/card parts already on it.
    chat.messages = chat.messages.map((m) =>
      m.id === aid ? { ...m, parts: appendTextPart(m.parts, token) } : m);
  }
  chat.loading = false;
});
```

### 4 — Wire optional features
- Reasoning: push `{ type: 'reasoning', text: '…' }` onto the message's `parts`.
- Tool calls: push `{ type: 'tool', tool: { type: 'search', state: 'output-available', input: {…}, output: {…} } }`.
- Model switcher: `chat.models = [{ id: 'gpt-4o', name: 'GPT-4o' }]; chat.currentModel = 'gpt-4o';` — listen for `modelchange`.
- Token meter: `chat.context = { usedTokens: 1200, maxTokens: 128000 };`.
- History sidebar: add `<kai-conversations>`; listen for `select` and `newchat`.

### 5 — Theme
Override `--kai-color-*` tokens on `:root` (they pierce Shadow DOM).

---

## Streaming recipe (critical)

Two rules, and both bite:

1. **Reassign a NEW array containing a NEW message object on every chunk.** Mutating an existing message object in place will NOT trigger a re-render.
2. **Fold the delta onto the message's TRAILING text part.** Replacing `parts` with a fresh single-text array re-renders fine but silently deletes any reasoning / tool / card parts the turn already produced.

```js
// The fold. `@kitn.ai/ui/state` exports exactly this as `appendTextPart`.
const appendText = (parts, delta) => {
  const last = parts[parts.length - 1];
  return last?.type === 'text'
    ? [...parts.slice(0, -1), { ...last, text: last.text + delta }]
    : [...parts, { type: 'text', text: delta }];
};

// ✅ re-renders, and keeps every part already on the message
chat.messages = chat.messages.map((m) =>
  m.id === id ? { ...m, parts: appendText(m.parts, delta) } : m);

// ❌ does NOT re-render (same array, same object)
chat.messages[i].parts = appendText(chat.messages[i].parts, delta);

// ❌ re-renders, but drops the message's reasoning/tool/card parts
chat.messages = chat.messages.map((m) =>
  m.id === id ? { ...m, parts: [{ type: 'text', text: answer }] } : m);
```

Opening a new text part when the last part is not text is what stops a post-tool answer being glued onto the pre-tool text.

The same reassign rule applies to every array/object property (`models`, `context`, `suggestions`, …): replace, don't mutate.

---

<!-- kai:programmatic:start -->
## Programmatic layer — `@kitn.ai/ui/state` + `@kitn.ai/ui/wire`

<!-- generated by scripts/gen-llms-programmatic.mjs from the shipped dist/*.d.ts — do not edit by hand -->

The API you write a HOST against — everything below is what a hand-composed surface
(no `<kai-chat>`) wires together. Signatures and docs below are the shipped declaration
files themselves, so they cannot drift from what your editor shows.

The streaming loop, end to end:

```ts
import { createAssistantStream, createMockResponder } from '@kitn.ai/ui/state';
import { readOpenAIStream } from '@kitn.ai/ui/wire';

// 1. A setter with the ONE universal contract: functional updater, new array out.
const stream = createAssistantStream((update) => { el.messages = update(el.messages ?? []); });

// 2. You fetch (or preview with the mock — real SSE frames, no provider, no key):
const mock = createMockResponder();            // or: fetch("/api/chat", …).then(r => r.body)
const result = await readOpenAIStream(mock(prompt), stream);

// 3. THE HOST RESOLVES TOOL CALLS. A provider (and the mock) only ANNOUNCES a tool
//    call — the part sits at state "input-available" forever unless your code answers
//    it. Executing the tool is the app's decision, and this is the call that answers.
//    The ONE exception: a call with `providerExecuted: true` (see ModelToolCall below)
//    was already run by the provider, in-stream — the host must NOT execute those.
for (const call of result.toolCalls) {
  if (call.providerExecuted) continue;
  stream.upsertTool(call.id, { state: 'output-available', output: await runTool(call) });
}
stream.done();                                 // seal the turn; late sink calls are dropped
```

Scripting a mock tool call (so the tool panel renders with zero backend):

```ts
const mock = createMockResponder({
  replies: ['Plain text turn', { text: 'Let me check.', toolCalls: [{ name: 'search_docs', arguments: { query: 'threads' } }] }],
});
```

### `@kitn.ai/ui/state`

I/O-free pure folds over `ChatMessage[]`. No client, no fetch — you own the transport; these functions own the array-identity discipline the elements re-render on.

Every export (57, derived from `dist/state/index.d.ts`):

| Export | Kind | Module |
|---|---|---|
| `appendMessage` | value | `messages` |
| `upsertMessage` | value | `messages` |
| `updateMessage` | value | `messages` |
| `removeMessage` | value | `messages` |
| `appendText` | value | `messages` |
| `textMessage` | value | `messages` |
| `partsToText` | value | `messages` |
| `addSuggestion` | value | `suggestions` |
| `removeSuggestion` | value | `suggestions` |
| `createAssistantStream` | value | `stream` |
| `onStreamSettled` | value | `stream` |
| `SetMessages` | type | `stream` |
| `AssistantStream` | type | `stream` |
| `appendTextPart` | value | `parts` |
| `appendReasoningPart` | value | `parts` |
| `upsertToolPart` | value | `parts` |
| `upsertCardPart` | value | `parts` |
| `fingerprint` | value | `parts` |
| `ReasoningOpts` | type | `parts` |
| `updateThreadMessages` | value | `threads` |
| `bindThreadMessages` | value | `threads` |
| `createThreadSessions` | value | `threads` |
| `ThreadLike` | type | `threads` |
| `SetThreads` | type | `threads` |
| `BindThreadOptions` | type | `threads` |
| `ThreadSessions` | type | `threads` |
| `parseStoredThread` | value | `persistence` |
| `createSaveScheduler` | value | `persistence` |
| `ParsedThread` | type | `persistence` |
| `DroppedStored` | type | `persistence` |
| `SaveScheduler` | type | `persistence` |
| `SaveSchedulerOptions` | type | `persistence` |
| `createMockResponder` | value | `mock` |
| `DEFAULT_MOCK_REPLIES` | value | `mock` |
| `MOCK_BANNER` | value | `mock` |
| `MOCK_MARKER` | value | `mock` |
| `MOCK_MARKER_KEY` | value | `mock` |
| `MOCK_MODEL_ID` | value | `mock` |
| `MockReply` | type | `mock` |
| `MockResponder` | type | `mock` |
| `MockResponderOptions` | type | `mock` |
| `MockSource` | type | `mock` |
| `MockToolCall` | type | `mock` |
| `MockTurn` | type | `mock` |
| `ChatMessage` | type | `../elements/chat-types` |
| `ChatMessageAction` | type | `../elements/chat-types` |
| `CustomAction` | type | `../elements/chat-types` |
| `AvatarData` | type | `../elements/chat-types` |
| `FeedbackVote` | type | `../elements/chat-types` |
| `MessagePart` | type | `../elements/chat-types` |
| `MessageSource` | type | `../elements/chat-types` |
| `RawOrigin` | type | `../elements/chat-types` |
| `ToolPart` | type | `../components/tool-types` |
| `ToolKind` | type | `../components/tool-classify` |
| `classifyTool` | value | `../components/tool-classify` |
| `CardEnvelope` | type | `../primitives/card-contract` |
| `AttachmentData` | type | `../components/attachment-types` |

#### `@kitn.ai/ui/state` · `stream` — the shipped declarations

```ts
/** The one universal contract: a functional-updater setter (React setState shape). */
export type SetMessages = (updater: (prev: ChatMessage[]) => ChatMessage[]) => void;
/** Every OBJECT payload a `MessagePart` variant carries. `type`/`raw` are the
 *  variant's own bookkeeping, not payload; the primitive payloads (`text`,
 *  `label`, `index`, ...) drop out at `Extract<..., object>`. */
type PartPayload = Extract<MessagePart extends infer P ? (P extends object ? P[Exclude<keyof P, 'type' | 'raw'>] : never) : never, object>;
/** Every bag one of these mutators takes: the part payloads plus the options
 *  bags that are not payloads themselves. */
type MutatorBag = PartPayload | ReasoningOpts;
/** `keyof` over a union member-by-member. The bare `keyof (A | B)` is the
 *  INTERSECTION of their keys, which is the opposite of what this needs. */
type KeysOf<T> = T extends unknown ? keyof T : never;
/** `Shape`, but any key that belongs exclusively to a SIBLING bag is a compile
 *  error. Keys `Shape` never heard of are untouched, so a consumer's own
 *  superset of a citation still passes — only the mix-ups fail. That is a
 *  denylist, not an exact type, and deliberately so: boundary point 1. */
type Unmixed<Shape> = Shape & {
    [K in Exclude<KeysOf<MutatorBag>, keyof Shape>]?: never;
};
/** A fluent builder for one in-flight assistant message. Owns no state. */
export interface AssistantStream {
    readonly id: string;
    appendText(delta: string): AssistantStream;
    appendReasoning(delta: string, opts?: Unmixed<ReasoningOpts>): AssistantStream;
    upsertTool(toolCallId: string, patch: Unmixed<Partial<ToolPart>>): AssistantStream;
    /** Adds a card, or REPLACES the existing one with the same `envelope.id`. A
     *  model that revises a card mid-turn re-sends the whole envelope, so a second
     *  call with a known id revises that card in place rather than rendering a
     *  second copy of it. See `upsertCardPart`. */
    addCard(envelope: CardEnvelope): AssistantStream;
    addSource(source: Unmixed<Source>): AssistantStream;
    addFile(attachment: AttachmentData): AssistantStream;
    done(): void;
    /** Settles the turn as FAILED and puts `reason` where the reader can find it.
     *
     *  WHERE THE REASON LANDS, in order:
     *  1. every tool part that has NOT produced a result flips to `output-error`
     *     with `errorText: reason`, so no panel spins forever. A tool ALREADY in
     *     `output-error` with its own non-empty `errorText` is left exactly as it
     *     is: "search index offline" is the answer to what went wrong and
     *     "Connection lost." is the generic outer symptom, so overwriting the
     *     specific with the generic loses the only actionable thing on the
     *     message. It still counts as carrying the failure. A tool in
     *     `output-error` with NO text does get filled in — an error panel with
     *     nothing in it says no more than a blank bubble does.
     *  2. if no part was able to carry it, the reason is APPENDED as its own text
     *     part.
     *
     *  Never both — a turn does not report the same failure twice.
     *
     *  "Where the reader can FIND it" is deliberate, and rule 1 and rule 2 are not
     *  equally loud. Rule 2 is text in the thread: read without any interaction.
     *  Rule 1 is a tool panel, which renders COLLAPSED — the header shows an error
     *  icon and a badge, so the failure is unmissable, but the `errorText` itself
     *  is one click away. That is the right default for a failed tool inside an
     *  otherwise readable answer, and it is why rule 2 exists rather than always
     *  stamping the panel and calling it reported.
     *
     *  Rule 2 is the whole point and it used to be missing. `abort` only ever did
     *  rule 1, so a TEXT-ONLY turn — every turn of a text-only support widget —
     *  had nothing to stamp: the string was discarded and a failed request
     *  rendered an EMPTY assistant bubble, while the consumer that passed a
     *  perfectly good sentence believed it had reported the failure. That is the
     *  repo's "decide loudly" rule broken on the one path where being quiet is
     *  worst, and it shipped because the discard is invisible from the call site.
     *
     *  It is a NEW part, never a merge onto the trailing text: gluing "Connection
     *  lost." onto the model's half-finished sentence reads as the model saying
     *  it. Text that already streamed stays exactly where it is.
     *
     *  The reason is TRIMMED, and `abort()` with no reason — or one that is empty
     *  or all whitespace — appends nothing: there is no reason to discard, and the
     *  kit will not invent copy the consumer did not write. Rule 1 still runs,
     *  with `errorText: undefined`. Whitespace is not a pedantic case here: the
     *  scaffold hands over `err.message`, and an `Error` is free to carry `''`,
     *  which would otherwise render an INVISIBLE text part — a blank bubble that
     *  also claims to have said something.
     *
     *  Settled is settled: after `done()` or a first `abort()`, this is a no-op
     *  like every other mutator, so the reason cannot be appended twice.
     *
     *  The reason is CONSUMER-facing text and is rendered as markdown like any
     *  other text part. Pass a sentence a visitor can read, not a stack trace. */
    abort(reason?: string): void;
}
/** Start an assistant message and drive it through `set`. New refs on every mutation. */
export declare function createAssistantStream(set: SetMessages, init?: Partial<ChatMessage>): AssistantStream;
/** Wrap a stream so `onSettle` fires on done/abort (used to toggle a `loading` flag).
 *  Preserves the fluent chain by returning the wrapper from every mutator. */
export declare function onStreamSettled(inner: AssistantStream, onSettle: () => void): AssistantStream;
```

#### `@kitn.ai/ui/state` · `parts` — the shipped declarations

```ts
/** Stable structural fingerprint. Key order independent, so an identical snapshot
 *  arriving twice compares equal and can be skipped. */
export declare function fingerprint(value: unknown): string;
/** Appends to the trailing text part, or OPENS A NEW ONE if the last part is not
 *  text. This is what stops a post-tool answer being glued onto the pre-tool text. */
export declare function appendTextPart(parts: MessagePart[], delta: string): MessagePart[];
export interface ReasoningOpts {
    index?: number;
    /** Namespaces `index` to one provider response stream. Producers that read more
     *  than one stream into the SAME message must set it. See `appendReasoningPart`. */
    streamId?: string;
    label?: string;
    signature?: string;
    raw?: RawOrigin;
}
/** Keyed by `(streamId, index)` so parallel reasoning blocks stay distinct.
 *
 *  WHY THE KEY IS A PAIR. A block index alone is NOT unique inside one `parts`
 *  array. Anthropic numbers content blocks per MESSAGE and restarts at 0 on the
 *  next one, while a tool loop folds every round into a single assistant turn.
 *  Keyed on index alone, round 2's thinking block (index 0) merges into round 1's
 *  part: the text concatenates and `raw: opts.raw ?? cur.raw` OVERWRITES round 1's
 *  verbatim provider payload with round 2's. `toAnthropicMessages` then emits one
 *  thinking block where two belong, carrying round 2's signature in round 1's
 *  position -- a modified-and-filtered thinking block, which is exactly the 400
 *  the verbatim `raw` channel exists to prevent.
 *
 *  `streamId` is the namespace: one value per provider response stream, attached
 *  by `consumeModelStream`. Two rounds are two streams, so their index 0s are two
 *  parts. Producers that drive a sink from a single stream can omit it; `undefined`
 *  is its own namespace and behaves exactly as before.
 *
 *  Returns the SAME array reference when the merge produces an identical part,
 *  for the same reason `upsertToolPart` does: a new `parts` array is the
 *  re-render signal, so handing one back for a delta that changed nothing is a
 *  spurious render.
 *
 *  An EMPTY delta is not a no-op and must still reach here: it is how a redacted
 *  reasoning block, a `signature_delta` and an assembled `content_block_stop`
 *  block arrive, and how a format opens a block at the right position so block
 *  ORDER survives into `parts`. Those carry a new `raw`/`signature`/index and so
 *  compare unequal and DO rebuild. What the check absorbs is the other empty
 *  frame: one carrying nothing new, which a provider is free to send repeatedly.
 *
 *  `signature` and `raw` resolve with `??`, so an explicit `undefined` from a
 *  later delta never blanks a value an earlier one established. Pass a DEFINED
 *  value to replace either; there is no way to clear them. */
export declare function appendReasoningPart(parts: MessagePart[], delta: string, opts?: ReasoningOpts): MessagePart[];
/** Creates or REPLACES a card part, keyed on `envelope.id`. Returns the SAME array
 *  reference when the incoming envelope is structurally identical to the current
 *  one, for the same reason `upsertToolPart` does: a new `parts` array is the
 *  re-render signal, so handing one back for a revision that changed nothing is a
 *  spurious render.
 *
 *  WHY THIS REPLACES WHERE `upsertToolPart` MERGES. A tool part is patched
 *  fragment-by-fragment as its arguments stream in, which is why that function
 *  needs carry-forward rules for `raw` and `kind` — a later patch that omits a
 *  field is not asserting the field is gone. A card envelope is the opposite: it
 *  arrives WHOLE, as one complete tool result, so an omitted field IS an
 *  assertion. Last-write-wins is both simpler and the only semantics under which
 *  a host can CLEAR `resolution` to re-open a dismissed card — a field-by-field
 *  merge can only ever set that field, never unset it, so `CardPolicy.onReopen`
 *  (see `primitives/card-contract.ts`) would have no way to express its result.
 *
 *  The PART-level `raw` is preserved across a revision. It is a different field
 *  from anything inside the envelope: the untranslated provider payload the part
 *  was built from, attached once by the producer, which a fresh envelope carries
 *  no opinion about.
 *
 *  Position is preserved: a revised card stays where it first appeared in the
 *  thread rather than jumping past the text that followed it. */
export declare function upsertCardPart(parts: MessagePart[], envelope: CardEnvelope): MessagePart[];
/** Creates or merges a tool part. Returns the SAME array reference when the merge
 *  produces an identical tool, so repeated snapshots do not trigger a re-render.
 *
 *  Two fields do NOT follow plain spread semantics, because a streaming provider
 *  hands them over on one fragment and then keeps patching the rest:
 *  - `kind`: a value the consumer set is preserved across later patches instead
 *    of being reverted to `classifyTool(type)` (see `resolveKind`).
 *  - `raw`: an explicit `raw: undefined` never blanks a `raw` an earlier patch
 *    established. Pass a DEFINED `raw` to replace it; there is no way to clear it. */
export declare function upsertToolPart(parts: MessagePart[], toolCallId: string, patch: Partial<ToolPart>): MessagePart[];
```

#### `@kitn.ai/ui/state` · `mock` — the shipped declarations

```ts
/** The `model` every mock frame reports. Not a model any provider serves — see
 *  tell 3 in the header. */
export declare const MOCK_MODEL_ID = "kai-mock";
/** The marker field carried by every mock frame. Tell 2. */
export declare const MOCK_MARKER_KEY = "_kai_mock";
/** The value of that marker: a whole sentence, because it is read by a human
 *  staring at a logged frame and wondering where the reply came from. */
export declare const MOCK_MARKER = "no provider was contacted \u2014 this reply was generated locally by createMockResponder() from @kitn.ai/ui/state";
/** The SSE comment that opens every mock stream. Tell 1. */
export declare const MOCK_BANNER = ": kai-mock \u2014 NO PROVIDER WAS CONTACTED. no provider was contacted \u2014 this reply was generated locally by createMockResponder() from @kitn.ai/ui/state.";
/** The default canned replies, cycled per turn so a multi-turn preview stays
 *  coherent instead of repeating one line forever. */
export declare const DEFAULT_MOCK_REPLIES: readonly string[];
/** One scripted tool call for a mock turn. Framed exactly the way the OpenAI
 *  chat-completions wire frames a real one — an announce fragment carrying
 *  `id`/`function.name`, then the argument JSON streamed in fragments — so the
 *  kit's own reader (`readOpenAIStream`) reassembles it through the same path a
 *  real provider's call takes. */
export interface MockToolCall {
    /** The tool name, e.g. `'get_weather'` or a card tool like `'kai_confirm'`. */
    name: string;
    /** The call's arguments. Serialized with `JSON.stringify` and streamed as
     *  fragments, like a real provider. Defaults to `{}`. */
    arguments?: unknown;
    /** Explicit tool-call id. Defaults to `call_kai-mock-<turn>-<n>`, which keeps
     *  the mock's naming tell (see tell 3): no provider issues ids in that shape. */
    id?: string;
}
/** One scripted citation for a mock turn. Framed as an OpenAI-wire
 *  `url_citation` annotation — the shape `readOpenAIStream` already parses into
 *  a `source` MessagePart — so a scripted citation takes the exact path a real
 *  provider's takes and renders through the same guarded sinks. */
export interface MockSource {
    /** The cited URL. Scheme policy is enforced at the render sink
     *  (`isSafeUrl`), same as for a real model's citation. */
    url: string;
    /** Human title for the citation chip. */
    title?: string;
    /** Quoted snippet; rides the wire as the annotation's `content` field. */
    snippet?: string;
}
/** A scripted mock turn: optional reasoning, then text, then citations, then
 *  tool calls. A turn with tool calls finishes `finish_reason: 'tool_calls'`,
 *  exactly as a real tool-calling turn does; a turn without them finishes
 *  `'stop'`. */
export interface MockTurn {
    /** Reasoning streamed (token by token) BEFORE the text, as `delta.reasoning`
     *  — the OpenRouter-normalized sibling `readOpenAIStream` folds into a
     *  `reasoning` part. Models think before they answer; the mock does too. */
    reasoning?: string;
    /** Text streamed (token by token) before the tool calls. */
    text?: string;
    /** Citations announced after the text, one `url_citation` annotation frame
     *  each, so consecutive `source` parts land the way a real cited answer's
     *  do (and collapse into the citations strip). */
    sources?: readonly MockSource[];
    /** Tool calls announced this turn, in order. */
    toolCalls?: readonly MockToolCall[];
}
/** A canned reply: plain text, or a scripted turn. A string is exactly
 *  `{ text }` — the pre-tool-call API unchanged. */
export type MockReply = string | MockTurn;
export interface MockResponderOptions {
    /** Canned replies, cycled one per turn. Plain strings stream as text; a
     *  `MockTurn` can also script reasoning, citations and tool calls
     *  (`{ reasoning, text, sources, toolCalls }`), which is what lets the
     *  zero-config mock exercise the kit's reasoning/source/tool/card paths
     *  without hand-rolled SSE framing. Defaults to `DEFAULT_MOCK_REPLIES`. */
    replies?: readonly MockReply[];
    /** Delay between chunks, in ms. Defaults to 24 — fast enough to feel alive,
     *  slow enough that the streaming is visible. `0` streams as fast as the
     *  event loop allows, which is what tests want. */
    delayMs?: number;
    /** How many whitespace-delimited tokens ride in each frame. Defaults to 1
     *  (token by token). Larger values coarsen the cadence. */
    chunkSize?: number;
    /** Log a one-time notice on the first turn. Defaults to `true`: the point of
     *  this module is that a mock reply is hard to mistake for a real one, and a
     *  console line is the fastest way for a human to notice. Pass `false` in
     *  tests, or wherever the banner and the frame markers are tell enough. */
    announce?: boolean;
}
/** Produces one turn's worth of SSE frames. Structurally a `StreamSource`, so it
 *  goes straight into `readOpenAIStream(responder(text), stream)`. */
export type MockResponder = (prompt?: string) => AsyncIterable<string>;
/**
 * Build a mock responder.
 *
 * ```ts
 * import { createAssistantStream, createMockResponder } from '@kitn.ai/ui/state';
 * import { readOpenAIStream } from '@kitn.ai/ui/wire';
 *
 * const mockResponse = createMockResponder();
 * const stream = createAssistantStream(setMessages);
 * await readOpenAIStream(mockResponse(value), stream);   // <- swap for fetch()
 * stream.done();
 * ```
 */
export declare function createMockResponder(options?: MockResponderOptions): MockResponder;
```

### `@kitn.ai/ui/wire`

The model-stream adapter. The kit PARSES, the consumer FETCHES: you make the request (your endpoint, your key), hand the response body to a reader, and it folds provider SSE onto message parts. The encoders turn the thread back into provider messages.

Every export (66, derived from `dist/wire/index.d.ts`):

| Export | Kind | Module |
|---|---|---|
| `readModelStream` | value | `read` |
| `readOpenAIStream` | value | `read` |
| `readAnthropicStream` | value | `read` |
| `WireError` | value | `read` |
| `StreamSource` | type | `read` |
| `ReadOptions` | type | `read` |
| `consumeModelStream` | value | `consume` |
| `createToolCallAccumulator` | value | `consume` |
| `applyToolOutput` | value | `sink-helpers` |
| `applyToolFailure` | value | `sink-helpers` |
| `bufferText` | value | `sink-helpers` |
| `toOpenAIMessages` | value | `encode` |
| `toAnthropicMessages` | value | `encode` |
| `WireEncodeError` | value | `encode` |
| `AnthropicContentBlock` | type | `encode` |
| `AnthropicEncodeOptions` | type | `encode` |
| `AnthropicWireMessage` | type | `encode` |
| `FileEncodeOptions` | type | `encode` |
| `OpenAIContentPart` | type | `encode` |
| `OpenAIEncodeOptions` | type | `encode` |
| `OpenAIReasoningDetail` | type | `encode` |
| `OpenAIToolCall` | type | `encode` |
| `OpenAIWireMessage` | type | `encode` |
| `UnencodableFilePolicy` | type | `encode` |
| `encodableMediaTypes` | value | `media-types` |
| `resolveMediaPolicy` | value | `media-types` |
| `EncodableKind` | type | `media-types` |
| `MediaDecision` | type | `media-types` |
| `MediaPolicy` | type | `media-types` |
| `MediaPolicyOptions` | type | `media-types` |
| `MediaTypeFilter` | type | `media-types` |
| `openaiChatFormat` | value | `formats/openai` |
| `anthropicMessagesFormat` | value | `formats/anthropic` |
| `sseDataFrames` | value | `sse` |
| `sseJson` | value | `sse` |
| `readableToAsyncIterable` | value | `sse` |
| `ByteSource` | type | `sse` |
| `subscribeWireDiagnostics` | value | `diagnostics` |
| `AppRequestEvent` | type | `diagnostics` |
| `EncodeAttachmentReport` | type | `diagnostics` |
| `EncodeDroppedEvent` | type | `diagnostics` |
| `EncodeRequestEvent` | type | `diagnostics` |
| `WireCloseEvent` | type | `diagnostics` |
| `WireDiagnosticBase` | type | `diagnostics` |
| `WireDiagnosticEvent` | type | `diagnostics` |
| `WireFailedEvent` | type | `diagnostics` |
| `WireFrameEvent` | type | `diagnostics` |
| `WireInterruptedEvent` | type | `diagnostics` |
| `WireOpenEvent` | type | `diagnostics` |
| `WirePartEvent` | type | `diagnostics` |
| `normalizeStopReason` | value | `chunk` |
| `AssistantStreamSink` | type | `chunk` |
| `ConsumeOptions` | type | `chunk` |
| `ModelStreamChunk` | type | `chunk` |
| `ModelToolCall` | type | `chunk` |
| `ModelToolCallDelta` | type | `chunk` |
| `ModelTurn` | type | `chunk` |
| `ModelUsage` | type | `chunk` |
| `StopReason` | type | `chunk` |
| `WireFormat` | type | `chunk` |
| `WireFormatReader` | type | `chunk` |
| `ChatMessage` | type | `../elements/chat-types` |
| `MessagePart` | type | `../elements/chat-types` |
| `MessageSource` | type | `../elements/chat-types` |
| `RawOrigin` | type | `../elements/chat-types` |
| `ToolPart` | type | `../components/tool-types` |

#### `@kitn.ai/ui/wire` · `read` — the shipped declarations

```ts
export type StreamSource = Response | ReadableStream<Uint8Array> | AsyncIterable<Uint8Array | string>;
export interface ReadOptions extends ConsumeOptions {
    format: WireFormat;
}
/** A non-ok HTTP response from the model endpoint, with the provider's own error
 *  body attached when there is one. Thrown before a single chunk is read, so a
 *  caller can distinguish "the request failed" from "the stream carried an
 *  error", which is `ModelTurn.error`. */
export declare class WireError extends Error {
    readonly status: number;
    readonly statusText: string;
    /** The response body parsed as JSON, or undefined when it was not JSON (an
     *  HTML error page from a proxy, most often). */
    readonly body: unknown;
    /** The raw response body, always. */
    readonly bodyText: string;
    constructor(status: number, statusText: string, bodyText: string, body: unknown);
}
/** Read one turn off the wire in `opts.format` and drive `sink` with it. */
export declare function readModelStream(source: StreamSource, sink: AssistantStreamSink, opts: ReadOptions): Promise<ModelTurn>;
/** OpenAI chat-completions SSE. Also what all nine catalog integrations except
 *  `mock` re-frame to server-side, so this is the common path. */
export declare function readOpenAIStream(source: StreamSource, sink: AssistantStreamSink, opts?: ConsumeOptions): Promise<ModelTurn>;
/** Anthropic Messages SSE. */
export declare function readAnthropicStream(source: StreamSource, sink: AssistantStreamSink, opts?: ConsumeOptions): Promise<ModelTurn>;
```

#### `@kitn.ai/ui/wire` · `encode` — the shipped declarations

```ts
export interface OpenAIToolCall {
    id: string;
    type: 'function';
    function: {
        name: string;
        arguments: string;
    };
}
/** One `reasoning_details` entry. Provider-owned open shape, kept as a record
 *  for the same reason `AnthropicContentBlock` is: an opaque entry has to pass
 *  through UNTOUCHED, and a closed type would be a list of the fields we happen
 *  to have seen. */
export type OpenAIReasoningDetail = Record<string, unknown>;
/** A multimodal user message's content entries. `image_url` takes an https URL
 *  or a `data:` URI in the same field; `file` takes `file_data`, which is a DATA
 *  URI on this wire (`data:application/pdf;base64,...`) and not bare base64. */
export type OpenAIContentPart = {
    type: 'text';
    text: string;
} | {
    type: 'image_url';
    image_url: {
        url: string;
    };
} | {
    type: 'file';
    file: {
        filename?: string;
        file_data: string;
    };
};
export interface OpenAIWireMessage {
    role: 'system' | 'user' | 'assistant' | 'tool';
    /** An ARRAY only when the turn carries an encodable `file` part. A text-only
     *  turn stays a plain string, so adding attachment support changed nothing
     *  about what an existing thread puts on the wire. */
    content: string | OpenAIContentPart[] | null;
    tool_calls?: OpenAIToolCall[];
    tool_call_id?: string;
    name?: string;
    /** Only ever present when `toOpenAIMessages` was asked for it. See
     *  `OpenAIEncodeOptions.reasoning`. */
    reasoning_details?: OpenAIReasoningDetail[];
}
/** EXTENDS rather than restates the file options: `onUnencodableFile` and
 *  `accept` mean the same thing on both wires, and a second declaration of them
 *  here is a second place to forget to update. */
export interface OpenAIEncodeOptions extends FileEncodeOptions {
    /**
     * Whether to send the assistant's own reasoning back with the thread.
     *
     * DEFAULT `'omit'`, and that default is a measurement, not caution. Omitting
     * reasoning is accepted by every configuration tested -- five live omission
     * trials plus 28 recorded live requests per configuration across the spike's
     * conformance sweep, zero 400s -- so the path that ships today demonstrably
     * works, while including reasoning cost about 25% more prompt tokens per round
     * when measured (665 -> 834 on a two-round loop). A library does not get to
     * raise every consumer's bill and add a new provider-validation surface as a
     * side effect of a bug fix.
     *
     * `'include'` is for a multi-round TOOL loop, which is where OpenRouter says it
     * pays: "when you post tool results, including the original reasoning ensures
     * the model can continue its reasoning from where it left off". Measured
     * accepted (HTTP 200) for a signed Anthropic block and for an OpenAI encrypted
     * block, over the OpenAI-compatible wire.
     *
     * The Anthropic wire has no such knob because it has no such choice: a filtered
     * or rebuilt thinking block there is a hard 400.
     */
    reasoning?: 'omit' | 'include';
}
/**
 * What to do with a `file` part this wire cannot carry.
 *
 * DEFAULT `'throw'`, and the default is the whole point. Skipping is how
 * attachments came to render perfectly in the thread and reach the model as
 * nothing: the developer wires up upload, watches it work, and ships a model
 * that cannot see the file. A throw here names the message, the part and the
 * reason, which is strictly more than a 400 at request time would tell you.
 *
 * `'skip'` restores the lenient behaviour for a host that would rather send a
 * degraded turn than fail one. It is silent, but it is silence the developer
 * asked for by name, which is the difference that matters.
 */
export type UnencodableFilePolicy = 'throw' | 'skip';
export interface FileEncodeOptions {
    onUnencodableFile?: UnencodableFilePolicy;
    /**
     * Narrow which attachment media types reach the wire, as HTML `accept` syntax
     * (`'image/*,application/pdf'`) or an array of the same.
     *
     * THE SAME STRING the composer takes as `<kai-chat accept="...">`, resolved by
     * the same function against the same declaration -- so a developer writes the
     * set once as a constant and hands it to both ends. Omitted means the kit's
     * full capability set, which is `encodableMediaTypes()`.
     *
     * It can only NARROW. Naming a type the encoders cannot represent does not
     * enable it; that would just move the failure to a provider 400.
     */
    accept?: MediaTypeFilter;
    /**
     * The app's own id for the logical turn this encode belongs to, carried onto
     * every diagnostic event the encode emits. Purely diagnostic: nothing here
     * branches on it and it never reaches a provider.
     *
     * THE SAME FIELD, THE SAME MEANING, as `ConsumeOptions.traceId` -- and that
     * symmetry is the whole payoff. Encoding happens BEFORE a read opens, so
     * there is no stream to attach an encode to and the kit will not invent one.
     * Pass the same id to both halves:
     *
     *   const body = toOpenAIMessages(messages, { traceId: 'turn-42' });
     *   readOpenAIStream(res, sink, { traceId: 'turn-42' });
     *
     * and the request and the response it produced sit together, with a tool loop
     * or a sub-agent fan-out grouping into one trace. Without it you still see
     * both halves; they are simply unlinked, which is the honest rendering --
     * pinning an encode to "the next stream that opens" would be a guess, and an
     * encode may be followed by no stream at all.
     */
    traceId?: string;
    /** The app's name for this call inside its trace (`'planner'`, `'retry-2'`).
     *  Same field and same meaning as `ConsumeOptions.label`. Absent when not
     *  supplied. */
    label?: string;
}
export type AnthropicEncodeOptions = FileEncodeOptions;
/** Anthropic content blocks are an open, provider-owned union. Keeping them as
 *  records is what lets a verbatim `thinking` payload pass through UNTOUCHED,
 *  which is the entire point of this encoder. */
export type AnthropicContentBlock = Record<string, unknown>;
export interface AnthropicWireMessage {
    role: 'user' | 'assistant';
    content: AnthropicContentBlock[];
}
/** A message cannot be encoded without losing something the provider will reject.
 *  Thrown at encode time, on purpose: a throw here beats a 400 at request time,
 *  because here you still know which message and which part caused it. */
export declare class WireEncodeError extends Error {
    readonly messageId: string;
    readonly partIndex: number;
    constructor(message: string, messageId: string, partIndex: number);
}
/**
 * ChatMessage[] to an OpenAI chat-completions `messages` array.
 *
 * ONE ChatMessage CAN BECOME SEVERAL WIRE MESSAGES. The kit streams a whole
 * assistant turn into a single message, so text, a tool call and the model's
 * answer to that call all live in one `parts` array. The OpenAI wire has no such
 * shape: a `role:'tool'` result must sit between the assistant message that
 * announced the call and whatever the model said afterwards. So the turn is
 * SPLIT at each tool boundary, into
 *
 *   assistant(pre-tool text + tool_calls) -> tool(result)... -> assistant(answer)
 *
 * Flattening instead would put the model's answer BEFORE the result it was based
 * on. No endpoint rejects that, which is exactly why it is worth spelling out:
 * it quietly degrades every later round of a tool loop.
 *
 * Consecutive tool parts stay in ONE assistant message, because parallel calls
 * are announced together and their results follow together.
 *
 * A turn that encodes to nothing is SKIPPED, never sent as `{ content: null }`
 * with no `tool_calls`: OpenAI treats `content` as required unless `tool_calls`
 * is present, and strict-compatible endpoints reject it.
 *
 * REASONING IS OPT-IN, and off by default. OpenRouter's OpenAI-compatible
 * endpoint does have a channel on the way back in -- `reasoning_details` on the
 * assistant message -- and `{ reasoning: 'include' }` uses it, one entry per
 * reasoning part, in part order, reassembled by `reasoningDetailOf` rather than
 * echoed out of `part.raw`. Read that function for which blocks make it and why.
 * The default omits, because omitting is measured-accepted everywhere and costs
 * about 25% fewer prompt tokens per round; see `OpenAIEncodeOptions.reasoning`.
 *
 * Reasoning alone still encodes to NOTHING. A block is content the model already
 * produced, not a reason to send a turn, so a message carrying reasoning and no
 * text and no settled tool is skipped exactly as before, rather than becoming
 * `{ content: null }` with no `tool_calls`.
 *
 * `card` and `source` parts are never encoded; they are kit-side.
 *
 * `file` parts ARE encoded, on a USER turn, and a turn carrying nothing but an
 * attachment is now a real message rather than nothing. Images become
 * `image_url` (https URL or `data:` URI alike); a base64 PDF becomes a `file`
 * part whose `file_data` is the data URI. Two cases have no form here and THROW
 * by default: a remote PDF, because this wire's `file` part has no URL variant,
 * and anything that is neither -- see `UnencodableFilePolicy` for why the
 * default is a throw and not a skip.
 *
 * A `file` part on an ASSISTANT turn is still dropped. Neither API accepts image
 * or document content in an assistant message, so there is nothing to encode it
 * to; attachments belong to the user turn that sent them.
 */
export declare function toOpenAIMessages(messages: ChatMessage[], options?: OpenAIEncodeOptions): OpenAIWireMessage[];
/**
 * ChatMessage[] to an Anthropic Messages `messages` array. THE ROUND-TRIP
 * ENCODER.
 *
 * A reasoning block is emitted as `part.raw.payload` verbatim and is NEVER
 * rebuilt from `text` plus `signature`: Anthropic returns 400 if a thinking
 * block in the most recent assistant message is modified, reordered, filtered or
 * reconstructed. A reasoning part with no `raw`, or with a `raw` captured from
 * some other format, therefore THROWS rather than silently producing a request
 * that will fail.
 *
 * Block order follows part order, which follows stream order, with no filtering,
 * because the API validates order too. An empty-text reasoning part (an omitted
 * or redacted block) is still emitted: the docs require sending back every block
 * "including any blocks with empty thinking fields".
 *
 * ONE ChatMessage CAN BECOME SEVERAL WIRE MESSAGES, for the same reason as
 * `toOpenAIMessages`: the kit streams a whole assistant turn into one message, so
 * the tool call and the model's answer to it share a `parts` array, but Anthropic
 * carries the result in a SEPARATE user message that has to sit between them. So
 * the turn is SPLIT at each tool boundary, into
 *
 *   assistant(pre-tool blocks + tool_use) -> user(tool_result)... -> assistant(answer)
 *
 * Flattening instead puts the model's answer BEFORE the result it was based on,
 * and strands every later round's thinking block in the first assistant message.
 * Consecutive tool parts stay in ONE assistant message, because parallel calls are
 * announced together and their results come back together.
 *
 * Adjacent user messages are MERGED. The API combines consecutive same-role turns
 * itself rather than rejecting them, so this is not what stands between you and a
 * 400; it is emitted anyway because the tool-result turn and a following user turn
 * are one turn, several OpenAI-compatible Anthropic proxies do enforce strict
 * alternation, and the merged form is what the models are trained on. Ordering is
 * safe by construction: `results` is only non-empty when `blocks` is, so a
 * tool_result message always follows its assistant message and can never be
 * appended after a plain user turn.
 *
 * `file` parts on a USER turn become `image` and `document` blocks, in part
 * order. Both take `source: {type:'base64'}` and `source: {type:'url'}`, so this
 * wire can carry a remote PDF that `toOpenAIMessages` has to refuse. Anything
 * neither API accepts as message content THROWS by default; see
 * `UnencodableFilePolicy`. A `file` part on an ASSISTANT turn is dropped, because
 * an assistant message here carries only text, thinking and tool_use.
 *
 * Asymmetry worth knowing: `tool_use.input` is a parsed OBJECT on this wire, not
 * a string, so it uses `input` and not `rawInput`. Only thinking blocks carry a
 * verbatim requirement.
 */
export declare function toAnthropicMessages(messages: ChatMessage[], options?: AnthropicEncodeOptions): AnthropicWireMessage[];
```

#### `@kitn.ai/ui/wire` · `chunk` — the shipped declarations

```ts
/** One fragment of a tool call. */
export interface ModelToolCallDelta {
    /**
     * The ONLY thing correlating fragments, and its NAMESPACE IS FORMAT-DEFINED.
     * `openaiChatFormat` uses the position in `delta.tool_calls`;
     * `anthropicMessagesFormat` uses the content-block index. Both are correct and
     * both are stable within one stream, but they are not the same number, so a
     * third-party format must pick one and stay consistent with itself.
     */
    index: number;
    id?: string;
    /** Usually whole on the first fragment; a few providers split it. */
    name?: string;
    /** A FRAGMENT of the JSON arguments string, not valid JSON on its own. */
    arguments?: string;
    /** A result the PROVIDER executed (Anthropic web_search_tool_result, an OpenAI
     *  built-in). Completes the panel with no host work. */
    output?: Record<string, unknown>;
    /** A provider-executed tool that failed. */
    outputError?: string;
}
/** Field names are deliberately provider-neutral. OpenAI says prompt/completion,
 *  Anthropic says input/output; input/output is the one that reads correctly for
 *  both. */
export interface ModelUsage {
    inputTokens?: number;
    outputTokens?: number;
    totalTokens?: number;
    /** Non-zero proves the model reasoned even when no reasoning text streamed. */
    reasoningTokens?: number;
    cachedInputTokens?: number;
    costUsd?: number;
}
export interface ModelStreamChunk {
    text?: string;
    /**
     * The model id the RESPONSE stated, verbatim; REPORT, NEVER INFER.
     *
     * Read from the response rather than the request, which is what makes it work
     * at all when the app builds its own fetch and the kit never sees what was
     * asked for. Providers commonly resolve an alias (ask for `gpt-4o`, get
     * `gpt-4o-2024-08-06`); through a gateway the value is the gateway's own id.
     * Both are reasons to pass the string through untouched.
     *
     * It is NOT guaranteed. A proxy can strip or rewrite it and a custom endpoint
     * may omit it, so a consumer renders it as ABSENT when it is absent. Filling
     * the gap with the requested id would lie in exactly the requested-vs-served
     * mismatch this field exists to catch.
     */
    model?: string;
    /**
     * Reasoning delta. `''` is MEANINGFUL, not a no-op: a redacted block has no
     * readable text but still carries a payload that must round-trip, and a format
     * uses an empty delta to OPEN a reasoning part at the right position in the
     * stream so block order survives into `parts`.
     */
    reasoning?: string;
    /** The provider's BLOCK index. Keeps parallel reasoning blocks distinct.
     *  Omitted means block 0, the single-block case every provider degrades to. */
    reasoningIndex?: number;
    /**
     * The UNTRANSLATED provider payload for this reasoning block. Valid on a chunk
     * with NO reasoning text at all, which is the whole point: Anthropic returns
     * 400 if a `thinking` block is modified, reordered or RECONSTRUCTED, so an
     * encoder has to echo the original block rather than rebuild one from `text`
     * plus `signature`.
     */
    reasoningRaw?: RawOrigin;
    /** Informational. `reasoningRaw` is the round-trip channel, not this. */
    reasoningSignature?: string;
    toolCalls?: ModelToolCallDelta[];
    /** Citations the model produced. A run of consecutive `source` parts renders
     *  as one citation row (`part="citations"`), outside the message bubble. */
    sources?: MessageSource[];
    /** Provider VERBATIM: 'stop' | 'tool_calls' | 'end_turn' | 'max_tokens' | ...
     *  Normalizing in place would destroy information consumers branch on. */
    finishReason?: string | null;
    usage?: ModelUsage;
    /** An in-band provider error (the HTTP response was already 200). */
    error?: {
        code?: string | number;
        message: string;
    };
}
/** One vocabulary across formats, for code that has to BRANCH. `finishReason`
 *  stays beside it, verbatim, for code that has to REPORT. */
export type StopReason = 'stop' | 'length' | 'tool-calls' | 'content-filter' | 'error' | 'other';
/** Unknown reasons degrade to 'other' rather than throwing: providers add stop
 *  reasons without warning and a new one must not take a turn down. */
export declare function normalizeStopReason(finishReason: string | null | undefined): StopReason | undefined;
/**
 * The subset of the kit's `AssistantStream` the adapter drives. Declared
 * STRUCTURALLY so the adapter has no runtime dependency on a stream
 * implementation and can be tested against a recorder. The kit's real
 * `AssistantStream` satisfies it as-is: same method names, same arities, and its
 * `AssistantStream` returns are assignable to `unknown`.
 *
 * `addSource` is optional so a hand-rolled three-method sink still compiles.
 */
export interface AssistantStreamSink {
    appendText(delta: string): unknown;
    appendReasoning(delta: string, opts?: ReasoningOpts): unknown;
    /** Create-or-merge. There is no separate "announce" call: handing a patch for
     *  an unknown `toolCallId` creates the ToolPart, and every later patch merges. */
    upsertTool(toolCallId: string, patch: Partial<ToolPart>): unknown;
    addSource?(source: MessageSource): unknown;
}
/** One tool call reassembled out of the stream's fragments. */
export interface ModelToolCall {
    /** The delta index that correlated this call's fragments. */
    index: number;
    /** Provider call id (synthesised as `call_<index>` if the provider omits it). */
    id: string;
    name: string;
    /** The RAW accumulated argument fragments. Echo THIS back on the next turn,
     *  not a re-stringified parse. */
    argumentsText: string;
    /** Parsed arguments: present only when `argumentsText` was a valid JSON object. */
    input?: Record<string, unknown>;
    /** Present only for a call the PROVIDER executed. */
    output?: Record<string, unknown>;
    /** True when the provider ran the tool and returned its result in-stream. The
     *  host must NOT execute these. */
    providerExecuted?: boolean;
    /** Why this call is unusable (malformed or truncated args, missing name). */
    error?: string;
}
/** Everything one assistant turn produced. */
export interface ModelTurn {
    /** The turn as ORDERED MESSAGE PARTS, built with the kit's own part builders,
     *  so it is exactly what the sink was driven with. Covers this turn only. */
    parts: MessagePart[];
    /** Flat concatenation of the text deltas. The provider wire format is a flat
     *  string, so this is kept for encoders. Not the content model. */
    text: string;
    /** Flat concatenation of the reasoning deltas, for the same reason. */
    reasoning: string;
    toolCalls: ModelToolCall[];
    sources: MessageSource[];
    /** The provider's own word for why it stopped. Never normalized. */
    finishReason: string | null;
    /** The same fact in one vocabulary. Branch on this. */
    stopReason?: StopReason;
    error?: {
        code?: string | number;
        message: string;
    };
    usage?: ModelUsage;
    /** How many chunks carried a NON-EMPTY reasoning delta. Zero with a non-zero
     *  `usage.reasoningTokens` means the provider hid the thinking text. */
    reasoningChunks: number;
    chunks: number;
}
export interface ConsumeOptions {
    /** Label for the reasoning disclosure. Defaults to 'Thinking'. */
    reasoningLabel?: string;
    /**
     * Correlates diagnostics and namespaces reasoning parts for this consume call;
     * assigned automatically when absent.
     *
     * Supply one only to tie a read to an id you already hold. Two reads into the
     * SAME sink must not share a value: the id is what keeps a second round's
     * block 0 from merging into the first round's reasoning part.
     */
    streamId?: string;
    /**
     * The app's own grouping of several reads into ONE logical turn, carried onto
     * every diagnostic event this read emits.
     *
     * THE KIT REPORTS WHAT THE APP DECLARES AND GROUPS NOTHING ON ITS OWN. A chat
     * app running a tool loop, or fanning out to sub-agents, makes several model
     * calls that belong to one turn; the kit sees one Response at a time and has
     * no way to know which ones those are. So it does not guess:
     *
     *   readOpenAIStream(res, sink, { traceId: 'turn-42', label: 'planner' })
     *
     * Absent when not supplied -- the key is not present on the events at all,
     * rather than present and undefined. Purely diagnostic: nothing in the parse
     * branches on it and it never reaches a provider.
     */
    traceId?: string;
    /** The app's name for THIS read inside its trace (`'planner'`,
     *  `'executor'`, `'retry-2'`). Carried onto every diagnostic event, and
     *  absent when not supplied. Never derived from the format or the model.
     *
     *  Not to be confused with `reasoningLabel`, which is UI copy for the
     *  reasoning disclosure; this one is never rendered to an end user. */
    label?: string;
    /** Fires once per tool call the moment its arguments parse cleanly. This is
     *  the hook a host's tool loop waits on. There is deliberately no
     *  per-fragment callback: `ToolPart.rawInput` is written on every fragment,
     *  so the streaming text is already on the part. */
    onToolCallReady?: (call: ModelToolCall) => void;
}
/** Per-stream state for one format. */
export interface WireFormatReader {
    /**
     * Map one decoded frame onto zero or more neutral chunks. Returns an ARRAY
     * because the mapping is not one-to-one: an Anthropic `message_start` yields
     * usage, a `content_block_start` for `tool_use` yields an id-plus-name delta,
     * a `ping` yields nothing.
     *
     * MUST NOT throw on an unrecognized frame. Return `[]` instead: providers add
     * event types without warning.
     */
    push(frame: unknown): ModelStreamChunk[];
}
/** A pluggable wire format. Values, not a flag, so a third party can add one
 *  without a PR to this repo. */
export interface WireFormat {
    readonly id: string;
    /** Called once per stream so a format can hold per-stream state. Two calls
     *  must share NOTHING. */
    open(): WireFormatReader;
}
```

### The `ChatRequestBody` preamble (what your route receives)

Every backend route the `kai` MCP scaffolds narrows `await request.json()` ONCE at the
edge, through this type — `request.json()` is `Promise<unknown>` under a Node/undici
tsconfig, so destructuring it raw fails a stock `npm run build` even though it ran fine
in dev. The front end sends `toOpenAIMessages(thread)`; this is what that produces, so
the two halves stay pinned to one type. Do not hand-roll a second narrowing.

```ts
/**
 * What the front end POSTs. `request.json()` is `unknown` (it is whatever the
 * client sent), so the body is narrowed once here instead of at every use —
 * without it this route does not compile under a server tsconfig. Widen it as
 * you add fields of your own.
 */
type ChatRequestBody = {
  messages: OpenAIWireMessage[];
  model?: string;
  tools?: unknown[];
};
```

The scaffolded routes pair it with a `readChatRequest(request)` guard that turns a bare
GET or malformed JSON into a status response instead of an unhandled throw — re-scaffold
any integration with the `kai` MCP `scaffold` tool to get the full preamble.
<!-- kai:programmatic:end -->

---

## Icon roster (77 names, derived from NAMED_ICONS in src/ui/icon.tsx)

Every name `kai-icon` (and every `icon` prop/attribute across the elements) resolves — derived from the `NAMED_ICONS` map in `src/ui/icon.tsx` (also exported at runtime as `ICON_NAMES`). An icon-shaped name outside this roster renders a fallback glyph and logs a console error, in dev and prod alike; URLs render an `<img>`, and emoji/arbitrary text passes through as text.

`archive` · `arrow-down` · `arrow-left` · `arrow-right` · `arrow-up` · `audio-lines` · `bell` · `book-open` · `bookmark` · `box` · `briefcase` · `check` · `chevron-down` · `chevron-left` · `chevron-right` · `chevron-up` · `circle` · `circle-alert` · `circle-check` · `circle-x` · `clock` · `code` · `copy` · `desktop` · `download` · `ellipsis` · `external-link` · `eye` · `eye-off` · `file-text` · `flag` · `folder` · `git-branch` · `git-pull-request` · `github` · `globe` · `home` · `image` · `info` · `laptop` · `link` · `list-filter` · `lock` · `maximize-2` · `message-circle` · `message-square` · `mic` · `minimize-2` · `minus` · `mobile` · `monitor` · `moon` · `more-horizontal` · `panel-left` · `panel-right` · `paperclip` · `pencil` · `play` · `plus` · `rotate-ccw` · `rotate-cw` · `search` · `settings` · `share` · `sliders-horizontal` · `smartphone` · `smile` · `sparkles` · `square` · `square-pen` · `sun` · `tablet` · `trash` · `triangle-alert` · `upload` · `workflow` · `x`

---

## Element reference (96 elements, generated from custom-elements.json)

Every element also accepts the `theme` attribute. Array/object properties are marked with a `—` attribute: they must be set as JS properties.

### `kai-agent-card` / `AgentCard`

**Properties** (every element also accepts `theme="light|dark|auto"`; only scalar props work as HTML attributes):

| Property | Attribute | Type | Description |
|---|---|---|---|
| `theme` | `theme` | `"light" \| "dark" \| "auto"` | Color mode (`auto` follows prefers-color-scheme). |
| `name` | `name` | `undefined \| string` | The agent's name, the primary label. Attribute: `name`. |
| `active` | `active` | `undefined \| false \| true` | Selected / focused state: highlighted border + surface. Attribute: `active`. |
| `needsAttention` | `needs-attention` | `undefined \| false \| true` | 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`. |
| `status` | — | `undefined \| { tone: "working" \| "idle" \| "done" \| "error" \| "blocked"; label?: undefined \| string; pulse?: undefined \| false \| 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 }`. |

**Events** (non-bubbling `CustomEvent`s — listen directly on the element):

| Event | `detail` type | Description |
|---|---|---|
| `kai-activate` | `CustomEvent` | The card was activated by a click, or by Enter / Space while focused. Promote this agent back to focus. |
| `kai-menu` | `CustomEvent` | 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). |

**Styleable parts** (restyle from outside via `kai-agent-card::part(name)`):

| Part | Description |
|---|---|
| `::part(status)` | The leading tone-colored status dot. — `kai-agent-card::part(status) { width: 0.625rem; height: 0.625rem }` |
| `::part(menu)` | The trailing overflow ("...") menu button. — `kai-agent-card::part(menu) { opacity: 1 }` |

---

### `kai-artifact` / `Artifact`

**Properties** (every element also accepts `theme="light|dark|auto"`; only scalar props work as HTML attributes):

| Property | Attribute | Type | Description |
|---|---|---|---|
| `theme` | `theme` | `"light" \| "dark" \| "auto"` | Color mode (`auto` follows prefers-color-scheme). |
| `src` | `src` | `undefined \| string` | URL the preview iframe frames. Consumer-controlled. |
| `files` | — | `undefined \| { path: string; url?: undefined \| string; code?: undefined \| string; language?: undefined \| string; type?: undefined \| "html" \| "pdf" \| "image" \| "other"; additions?: undefined \| number; deletions?: undefined \| number; status?: undefined \| "added" \| "modified" \| "deleted" \| "renamed" \| "untracked" }[]` | 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). |
| `tab` | `tab` | `undefined \| "preview" \| "code"` | Controlled active tab: `preview` or `code`. When set, the artifact follows it (re-asserted on change). Leave unset for an uncontrolled tab (see `defaultTab`). |
| `defaultTab` | `default-tab` | `undefined \| "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`. |
| `activeFile` | `active-file` | `undefined \| string` | Selected file path. Syncs the tree highlight, Code source, and preview. |
| `sandbox` | `sandbox` | `undefined \| string` | iframe `sandbox` override. Secure default `allow-scripts allow-forms` (NOT `allow-same-origin`). |
| `iframeTitle` | `iframe-title` | `undefined \| string` | Accessible title for the preview iframe. |
| `maximized` | `maximized` | `undefined \| false \| true` | Reflects the artifact's own maximized view-state (usually driven by the protocol). |
| `expandable` | `expandable` | `undefined \| false \| true` | Show the expand-to-fill button (OPT-IN). |
| `openInTab` | `open-in-tab` | `undefined \| false \| true` | Show the open-in-new-tab button (OPT-IN). |
| `noNav` | `no-nav` | `undefined \| false \| true` | Hide back/forward. |
| `noReload` | `no-reload` | `undefined \| false \| true` | Hide reload. |
| `noHome` | `no-home` | `undefined \| false \| true` | Hide home. |
| `noPathField` | `no-path-field` | `undefined \| false \| true` | Hide the address field. |
| `noTabs` | `no-tabs` | `undefined \| false \| true` | Hide the Preview\|Code toggle. |
| `standalone` | `standalone` | `undefined \| false \| true` | Standalone chrome: rounded corners + border (else square, borderless in-panel). |
| `readonlyPath` | `readonly-path` | `undefined \| false \| true` | Show the address but make it read-only (visible, nav-tracking, non-editable). |
| `displayUrl` | `display-url` | `undefined \| string` | 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. |

**Events** (non-bubbling `CustomEvent`s — listen directly on the element):

| Event | `detail` type | Description |
|---|---|---|
| `kai-file-select` | `CustomEvent<{ path: string }>` | Fired when a file is selected. `detail.path`. |
| `kai-maximize-change` | `CustomEvent<{ maximized: false \| true }>` | Artifact's own maximize button toggled (consumer-observable; non-bubbling). |
| `kai-maximize-intent` | `CustomEvent<{ requested: false \| true }>` | 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. |
| `kai-navigate` | `CustomEvent<{ url: string }>` | Fired when the preview navigates. `detail.url` = the new location. |
| `kai-tab-change` | `CustomEvent<{ tab: "preview" \| "code" }>` | Fired when the Preview\|Code tab changes. `detail.tab`. |

**Methods** (call on the element instance: `document.querySelector('kai-artifact').back()`):

| Method | Signature | Description |
|---|---|---|
| `back` | `(): void` | Go back in the artifact's own history stack (no-op when there's no prior entry). |
| `forward` | `(): void` | Go forward in the history stack (no-op when there's no forward entry). |
| `reload` | `(): void` | Force-reload the current preview url (also re-renders an inline PDF). |
| `home` | `(): void` | Navigate to the `src` home url (no-op when there's no `src`). |
| `navigate` | `(url: string): void` | Push + load a url in the preview, the path-field submit path (fires kai-navigate). |
| `selectFile` | `(path: 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. |
| `openExternal` | `(): 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). |
| `maximize` | `(): void` | Enter the maximized view-state (fires kai-maximize-change{maximized:true}). Named maximize, NOT maximized, which is a prop. |
| `restore` | `(): void` | Exit the maximized view-state (fires kai-maximize-change{maximized:false}). |

---

### `kai-attachments` / `Attachments`

**Properties** (every element also accepts `theme="light|dark|auto"`; only scalar props work as HTML attributes):

| Property | Attribute | Type | Description |
|---|---|---|---|
| `theme` | `theme` | `"light" \| "dark" \| "auto"` | Color mode (`auto` follows prefers-color-scheme). |
| `items` | — | `undefined \| { id: string; type: "file" \| "source-document"; filename?: undefined \| string; mediaType?: undefined \| string; url?: undefined \| string; title?: undefined \| string }[]` | The attachments to render. Omit (or pass an empty array) for the empty state, which shows `emptyText` if set and nothing otherwise. Set as a JS property (array). Each item's `url` must be a `data:` URI or an https URL, never `URL.createObjectURL`: a `blob:` URL previews here but the wire encoders (`toOpenAIMessages`/`toAnthropicMessages`) refuse it. |
| `variant` | `variant` | `undefined \| "grid" \| "inline" \| "list"` | Layout: `grid` = visual tiles, `inline` = icon + label chips, `list` = rows. |
| `hoverCard` | `hover-card` | `undefined \| false \| true` | Wrap each item in a hover card that previews its details. |
| `removable` | `removable` | `undefined \| false \| true` | Show a remove button per item; clicking it fires a `kai-remove` event. |
| `showMediaType` | `show-media-type` | `undefined \| false \| true` | Also show the media type beneath the filename (non-grid variants). |
| `emptyText` | `empty-text` | `undefined \| string` | Text shown when `items` is empty. |

**Events** (non-bubbling `CustomEvent`s — listen directly on the element):

| Event | `detail` type | Description |
|---|---|---|
| `kai-remove` | `CustomEvent<{ id: string }>` | A remove button was clicked. |

**Styleable parts** (restyle from outside via `kai-attachments::part(name)`):

| Part | Description |
|---|---|
| `::part(preview)` | The image shown in an attachment’s hover-card preview. Bounded by default (max ~320×256, aspect preserved) so a large image never blows up the card. Raise or lower the cap from outside. — `kai-attachments::part(preview) { max-width: 32rem; max-height: 24rem }` |
| `::part(attachment)` | One attachment item: the chip, row or tile, whichever variant is rendering. Restyle its background, radius or border from outside without caring which layout it is. — `kai-chat::part(attachment) { border-radius: 0.25rem }` |
| `::part(attachment-name)` | The attachment’s filename label. Present in every variant that shows one (a grid tile omits it for an image, which is its own label). Retune its type or hide it entirely. — `kai-chat::part(attachment-name) { font-size: 0.75rem }` |

---

### `kai-audio-visualizer` / `AudioVisualizer`

**Properties** (every element also accepts `theme="light|dark|auto"`; only scalar props work as HTML attributes):

| Property | Attribute | Type | Description |
|---|---|---|---|
| `theme` | `theme` | `"light" \| "dark" \| "auto"` | Color mode (`auto` follows prefers-color-scheme). |
| `variant` | `variant` | `undefined \| string` | Look to render: `bar` (default), `grid`, `radial`, `wave`, `aurora`, `custom`. `aura` is accepted as a LiveKit-markup alias for `aurora`. Attribute: `variant`. |
| `state` | `state` | `undefined \| 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`. |
| `size` | `size` | `undefined \| string` | `icon` \| `sm` \| `md` (default) \| `lg` \| `xl`. Attribute: `size`. |
| `barCount` | `bar-count` | `undefined \| number` | Bars to draw. Bar and radial only. Attribute: `bar-count`. |
| `count` | `count` | `undefined \| number` | Grid only: rows and columns of the (always square) grid. Attribute: `count`. |
| `radius` | `radius` | `undefined \| number` | Radial only: ring distance from center, in px. Attribute: `radius`. |
| `spread` | `spread` | `undefined \| number` | Grid only: ring distance for the connecting animation, in cells. Attribute: `spread`. |
| `interval` | `interval` | `undefined \| number` | Grid only: ms between scripted frames. Attribute: `interval`. |
| `color` | `color` | `undefined \| string` | CSS color for the geometry, overriding the inherited `currentColor`. Attribute: `color`. |
| `complexity` | `complexity` | `undefined \| number` | Shader variants only: pattern density, 0..1. Attribute: `complexity`. |
| `label` | `label` | `undefined \| string` | Setting this makes the element an announced image (`role="img"`) instead of decorative (`aria-hidden`). Attribute: `label`. |
| `stream` | — | `undefined \| MediaStream` | Live microphone or WebRTC audio to analyze. JS property only. NOTE: amplitude renders only while state is "speaking" unless listening-amplitude is set; every other state plays its scripted animation and ignores the audio. |
| `audioElement` | — | `undefined \| HTMLMediaElement` | An `<audio>` or `<video>` element to tap for its audio. JS property only. NOTE: amplitude renders only while state is "speaking" unless listening-amplitude is set; every other state plays its scripted animation and ignores the audio. |
| `bands` | — | `undefined \| number[]` | 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. NOTE: amplitude renders only while state is "speaking" unless listening-amplitude is set; every other state plays its scripted animation and ignores the audio. |
| `listeningAmplitude` | `listening-amplitude` | `undefined \| false \| true` | Render live amplitude during the listening state as well, using the same presentation as speaking. Off by default, which keeps LiveKit parity: amplitude from stream, audio-element or bands renders only while state is "speaking". Set it to show a real mic-level picture while the user is the one talking. Boolean. Attribute: `listening-amplitude` (a bare attribute means true; reflected, so the property reads back what the attribute set). |
| `shader` | — | `undefined \| { fragment: string; uniforms?: undefined \| Record<string, { type: "1f" \| "1i" \| "1fv" \| "2f" \| "3f" \| "3fv" \| "4f" \| "4fv" \| "Matrix2fv" \| "Matrix3fv" \| "Matrix4fv"; value: number \| number[] }> }` | Custom fragment shader for `variant="custom"`. JS property only. |
| `animateWhenNotVisible` | `animate-when-not-visible` | `undefined \| false \| true` | 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`. |

_No events._

**Styleable parts** (restyle from outside via `kai-audio-visualizer::part(name)`):

| Part | Description |
|---|---|
| `::part(bar)` | A single bar in the `bar` variant, or a single spoke in the `radial` variant. Also carries `data-kai-index` and `data-kai-highlighted` ("true"/"false") for use inside the shadow root; to style the lit state from OUTSIDE, combine with the `highlighted` part below rather than an attribute selector. — `kai-audio-visualizer::part(bar) { border-radius: 2px } kai-audio-visualizer::part(bar highlighted) { background: var(--brand) }` |
| `::part(cell)` | A single dot in the `grid` variant. Also carries `data-kai-index` and `data-kai-highlighted` ("true"/"false") for use inside the shadow root; to style the lit state from OUTSIDE, combine with the `highlighted` part below rather than an attribute selector. — `kai-audio-visualizer::part(cell) { border-radius: 9999px } kai-audio-visualizer::part(cell highlighted) { background: var(--brand) }` |
| `::part(highlighted)` | A second part TOKEN present on a `bar` or `cell` exactly when the sequencer or live audio has it lit, not a standalone styleable element. Combine it in the same `::part()` argument: `::part(bar highlighted)` or `::part(cell highlighted)`. This is the external equivalent of the internal `data-kai-highlighted="true"` attribute, which a `::part()` selector cannot reach (an attribute selector cannot follow a pseudo-element). — `kai-audio-visualizer::part(bar highlighted) { background: var(--brand) } kai-audio-visualizer::part(cell highlighted) { background: var(--brand) }` |
| `::part(canvas)` | The WebGL canvas backing the `wave` and `aurora` variants. Restyle its size or radius, or layer a mask/filter, from outside. — `kai-audio-visualizer::part(canvas) { border-radius: 0.75rem }` |

---

### `kai-avatar` / `Avatar`

**Properties** (every element also accepts `theme="light|dark|auto"`; only scalar props work as HTML attributes):

| Property | Attribute | Type | Description |
|---|---|---|---|
| `theme` | `theme` | `"light" \| "dark" \| "auto"` | Color mode (`auto` follows prefers-color-scheme). |
| `src` | `src` | `undefined \| string` | Image URL/data-URI. When absent, the `fallback` initials show instead. |
| `alt` | `alt` | `undefined \| string` | Alt text for the image. Defaults to `fallback`. |
| `fallback` | `fallback` | `undefined \| string` | Short text shown when there's no image, usually initials (e.g. "JD", "AI"). |
| `size` | `size` | `undefined \| "sm" \| "md" \| "lg"` | Size token: `sm` \| `md` (default) \| `lg`. |

_No events._

---

### `kai-badge` / `Badge`

**Properties** (every element also accepts `theme="light|dark|auto"`; only scalar props work as HTML attributes):

| Property | Attribute | Type | Description |
|---|---|---|---|
| `theme` | `theme` | `"light" \| "dark" \| "auto"` | Color mode (`auto` follows prefers-color-scheme). |
| `variant` | `variant` | `undefined \| "default" \| "count" \| "citation"` | `default` (muted pill) · `count` (compact number badge) · `citation` (filled primary, for inline citation markers). Defaults to `default`. |

_No events._

**Slots** (project your own markup via `slot="name"` on a light-DOM child):

| Slot | Mode | Description |
|---|---|---|
| _(default)_ | inject | The badge's label: text, or a small inline icon plus text. |

**Styleable parts** (restyle from outside via `kai-badge::part(name)`):

| Part | Description |
|---|---|
| `::part(badge)` | The badge pill. Restyle its background, color, or shape; the `variant` prop (default/count/citation) sets the defaults. — `kai-badge::part(badge) { background: var(--color-primary); color: var(--color-primary-foreground) }` |

---

### `kai-button` / `Button`

**Properties** (every element also accepts `theme="light|dark|auto"`; only scalar props work as HTML attributes):

| Property | Attribute | Type | Description |
|---|---|---|---|
| `theme` | `theme` | `"light" \| "dark" \| "auto"` | Color mode (`auto` follows prefers-color-scheme). |
| `variant` | `variant` | `undefined \| "default" \| "subtle" \| "ghost" \| "outline" \| "destructive"` | Visual style. `default` (filled), `subtle` (muted text, hover tint, the toolbar icon look), `ghost` (transparent, hover fill), `outline`, or `destructive`. Defaults to `default`. |
| `size` | `size` | `undefined \| "sm" \| "md" \| "lg" \| "icon" \| "icon-sm"` | Size token. `icon` / `icon-sm` are square (for icon-only buttons); `sm` / `md` / `lg` size text buttons. Defaults to `md`. |
| `icon` | `icon` | `undefined \| string` | Leading icon: a named icon (e.g. `"mic"`, `"plus"`), an image URL/data-URI, or plain text. Renders before any slotted label. |
| `iconTrailing` | `icon-trailing` | `undefined \| string` | Trailing icon, after the label (e.g. `"chevron-down"` for a menu affordance). |
| `label` | `label` | `undefined \| string` | Accessible name. REQUIRED for icon-only buttons (no visible text); ignored when you slot visible text, which already names the button. An `aria-label` on top of visible text REPLACES that name rather than adding to it, so a button reading "Save" that answers to "Submit" is unusable by speech input (WCAG 2.5.3, Label in Name). The visible text wins. An `icon` / `icon-sm` size hides the slot, which makes the button icon-only whatever you slotted, so `label` is what names it there. |
| `disabled` | `disabled` | `undefined \| false \| true` | Disable the button (non-interactive, dimmed). |
| `full` | `full` | `undefined \| false \| true` | Stretch the button to the full width of its container (a block button), e.g. a card CTA or a stacked action. Attribute: `full`. |
| `align` | `align` | `undefined \| "start" \| "center" \| "end"` | Justify the button's content: `start`, `center` (default), or `end`. Combine with `full` for a full-width, left-aligned button. |
| `type` | `type` | `undefined \| "button" \| "submit" \| "reset"` | Native button `type`. Defaults to `button` (so it never submits a form). |

**Events** (non-bubbling `CustomEvent`s — listen directly on the element):

| Event | `detail` type | Description |
|---|---|---|
| `kai-click` | `CustomEvent` | The button was activated (pointer or keyboard). Carries no detail. The native `click` also bubbles (composed) for consumers who prefer it. |

**Methods** (call on the element instance: `document.querySelector('kai-button').focus(…)`):

| Method | Signature | Description |
|---|---|---|
| `focus` | `(options?: FocusOptions): void` | Focus the inner `<button>` (host.focus() would focus the wrapper). |
| `blur` | `(): void` | Blur the inner `<button>`. |
| `click` | `(): 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. |

**Slots** (project your own markup via `slot="name"` on a light-DOM child):

| Slot | Mode | Description |
|---|---|---|
| _(default)_ | inject | The button's label. Omit it for an icon-only button (pair with `aria-label`). |
| `icon` | replace | A custom leading icon (any inline SVG, inherits `currentColor`). Wins over the `icon` prop. |

**Styleable parts** (restyle from outside via `kai-button::part(name)`):

| Part | Description |
|---|---|
| `::part(button)` | The button element. Restyle radius, padding, colors, or weight from outside; the `variant`/`size` props set the defaults. — `kai-button::part(button) { border-radius: 9999px; font-weight: 600 }` |

---

### `kai-card` / `Card`

**Properties** (every element also accepts `theme="light|dark|auto"`; only scalar props work as HTML attributes):

| Property | Attribute | Type | Description |
|---|---|---|---|
| `theme` | `theme` | `"light" \| "dark" \| "auto"` | Color mode (`auto` follows prefers-color-scheme). |
| `appearance` | `appearance` | `undefined \| "outlined" \| "filled" \| "plain" \| "accent"` | Surface treatment: `outlined` (default) \| `filled` \| `plain` \| `accent`. Attribute: `appearance`. |
| `orientation` | `orientation` | `undefined \| "vertical" \| "horizontal" \| "responsive"` | `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`. |
| `collapse` | `collapse` | `undefined \| string` | The card width below which a `responsive` card collapses to vertical and the footer actions stack. A CSS length; default `28rem`. Attribute: `collapse`. |
| `dense` | `dense` | `undefined \| false \| true` | Tighter spacing for dense lists. Attribute: `dense`. |
| `dismissible` | `dismissible` | `undefined \| false \| true` | Show a close (×) that hides the card and emits `kai-dismiss`. Attribute: `dismissible`. Off by default. |
| `href` | `href` | `undefined \| string` | Render the whole card as a link. Attribute: `href`. Wins over `clickable`. |
| `target` | `target` | `undefined \| string` | `target` for the `href` anchor. Attribute: `target`. |
| `rel` | `rel` | `undefined \| string` | `rel` for the `href` anchor. Attribute: `rel`. |
| `clickable` | `clickable` | `undefined \| false \| true` | Make the whole card a button (`role="button"`, Enter/Space, hover affordance) that emits `kai-card-click`. Attribute: `clickable`. Ignored when `href` is set. |

**Events** (non-bubbling `CustomEvent`s — listen directly on the element):

| Event | `detail` type | Description |
|---|---|---|
| `kai-card-click` | `CustomEvent` | A `clickable`/`href` card was activated (click, or Enter/Space). |
| `kai-dismiss` | `CustomEvent` | The card was dismissed via its × (it also hides itself). |

**Slots** (project your own markup via `slot="name"` on a light-DOM child):

| Slot | Mode | Description |
|---|---|---|
| _(default)_ | inject | The card body, below the header/media regions. |
| `media` | inject | Full-bleed media (image/video/illustration) at the top (vertical) or start (horizontal). Clipped to the card corners. |
| `header` | inject | Header content, e.g. a title. Rendered above the body. |
| `header-actions` | inject | An actions cluster pinned to the end of the header row. |
| `footer` | inject | Footer content rendered below the body. |
| `footer-actions` | inject | Action buttons pinned to the end of the footer. Do NOT combine with a clickable/href card (nested interactive). |

**Styleable parts** (restyle from outside via `kai-card::part(name)`):

| Part | Description |
|---|---|
| `::part(card)` | The card root (a div, or an a when href is set). Restyle its radius, border, or background; set --kai-card-spacing for padding/gaps (the dense prop sets the compact default). — `kai-card::part(card) { border-radius: 1rem; --kai-card-spacing: 1.5rem }` |
| `::part(media)` | The full-bleed media region. Cap or crop it from outside (e.g. a fixed height with object-fit). — `kai-card::part(media) { max-height: 12rem }` |
| `::part(header)` | The header row (header content + header-actions). Add a divider or adjust its alignment. — `kai-card::part(header) { border-bottom: 1px solid var(--color-border) }` |
| `::part(body)` | The default-slot body region. — `kai-card::part(body) { font-size: 0.9375rem }` |
| `::part(footer)` | The footer row (footer content + footer-actions). — `kai-card::part(footer) { border-top: 1px solid var(--color-border) }` |
| `::part(dismiss)` | The dismiss (×) button shown when dismissible. Recolor or reposition it from outside. — `kai-card::part(dismiss) { color: var(--color-muted-foreground) }` |

---

### `kai-cards` / `Cards`

**Properties** (every element also accepts `theme="light|dark|auto"`; only scalar props work as HTML attributes):

| Property | Attribute | Type | Description |
|---|---|---|---|
| `theme` | `theme` | `"light" \| "dark" \| "auto"` | Color mode (`auto` follows prefers-color-scheme). |
| `cards` | — | `undefined \| { type: string; id: string; data: unknown; title?: undefined \| string; resolution?: undefined \| { kind: "action"; action: string; payload?: unknown; at?: undefined \| string } \| { kind: "submit"; data: unknown; at?: undefined \| string } \| { kind: "dismissed"; at?: undefined \| string } \| { kind: "expired"; reason?: undefined \| string; at?: undefined \| string } }[]` | The stream of card envelopes to render. Set as a JS PROPERTY: `el.cards = [...]`. |
| `types` | — | `undefined \| Record<string, 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. |
| `schemas` | — | `undefined \| Record<string, object>` | 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. |
| `policy` | — | `undefined \| { onSubmit?: undefined \| ((cardId: string, data: unknown) => void); onAction?: undefined \| ((cardId: string, action: string, payload?: unknown) => void); onSendPrompt?: undefined \| ((text: string, opts: { mode: "compose" \| "send"; context?: unknown }) => void); onOpen?: undefined \| ((url: string, target: "tab" \| "artifact") => void); onState?: undefined \| ((cardId: string, patch: unknown) => void); onDismiss?: undefined \| ((cardId: string) => void); onReopen?: undefined \| ((cardId: string) => void); onError?: undefined \| ((cardId: string, message: string) => void); maxSendPromptMode?: undefined \| "compose" \| "send" }` | Optional CardPolicy handling child events. Property: `el.policy`. |
| `validateCards` | `validate-cards` | `undefined \| false \| true` | 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. |

**Events** (non-bubbling `CustomEvent`s — listen directly on the element):

| Event | `detail` type | Description |
|---|---|---|
| `kai-card-resolved` | `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 } }>` | 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.) |

**Methods** (call on the element instance: `document.querySelector('kai-cards').resolve(…)`):

| Method | Signature | Description |
|---|---|---|
| `resolve` | `(cardId: string, resolution: CardResolution): void` | 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. |
| `dismiss` | `(cardId: string): void` | Collapse a card to its re-openable stub from the host side. Convenience for `resolve(cardId, { kind: 'dismissed' })`. |
| `getCard` | `(cardId: string): HTMLElement \| null` | 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. |

---

### `kai-chain-of-thought` / `ChainOfThought`

**Properties** (every element also accepts `theme="light|dark|auto"`; only scalar props work as HTML attributes):

| Property | Attribute | Type | Description |
|---|---|---|---|
| `theme` | `theme` | `"light" \| "dark" \| "auto"` | Color mode (`auto` follows prefers-color-scheme). |
| `steps` | — | `undefined \| { label: string; content?: undefined \| string; id?: 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? }`. Omit to supply the steps as `<kai-step>` light-DOM children instead; when both are present the property's steps come first. |
| `type` | `type` | `undefined \| "single" \| "multiple"` | Open mode: `'multiple'` (default, any number of steps open at once) or `'single'` (at most one open; opening a step closes the others). |
| `value` | — | `undefined \| string \| string[]` | 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. |
| `defaultValue` | — | `undefined \| string \| string[]` | Uncontrolled INITIAL open step key(s), seeding which steps render expanded. Ignored once `value` is provided. Set as a JS property. |

**Events** (non-bubbling `CustomEvent`s — listen directly on the element):

| Event | `detail` type | Description |
|---|---|---|
| `kai-value-change` | `CustomEvent<{ value: string \| string[] }>` | 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.) |

**Methods** (call on the element instance: `document.querySelector('kai-chain-of-thought').expand(…)`):

| Method | Signature | Description |
|---|---|---|
| `expand` | `(index?: number): void` | 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). |
| `collapse` | `(index?: number): void` | Close one step's detail by index, or ALL steps when called with no arg. |
| `toggle` | `(index?: number): void` | Flip one step's open state by index. |

**Declarative children** (compose these in light DOM instead of setting the JS property):

| Child element | Attributes | Text content | Notes |
|---|---|---|---|
| `<kai-step>` | `label`, `step-id` | yes | Parse a single light-DOM `<kai-step>` element into a `Step` descriptor. Attribute mapping: - `label` → Step.label (the always-visible heading) - `step-id` → Step.id (optional stable open-set key) - textContent → Step.content (optional expandable detail) |

---

### `kai-chat` / `Chat`

**Properties** (every element also accepts `theme="light|dark|auto"`; only scalar props work as HTML attributes):

| Property | Attribute | Type | Description |
|---|---|---|---|
| `theme` | `theme` | `"light" \| "dark" \| "auto"` | Color mode (`auto` follows prefers-color-scheme). |
| `value` | — | `undefined \| string \| ({ type: "text"; text: string } \| { type: "entity"; entity: { kind: string; id: string; label: string; icon?: undefined \| string; promptText?: undefined \| string; data?: undefined \| Record<string, unknown> } })[]` | 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. |
| `placeholder` | `placeholder` | `undefined \| string` | Placeholder text shown in the empty input. |
| `loading` | `loading` | `undefined \| false \| true` | When true, shows the loading/streaming state and disables submit (use while awaiting the assistant's reply). |
| `suggestions` | — | `undefined \| string[]` | Starter prompts shown above the input when the thread is empty. Clicking one follows `suggestionMode`. Set as a JS property. |
| `suggestionMode` | `suggestion-mode` | `undefined \| "submit" \| "fill"` | What clicking a suggestion does: `'submit'` (default) sends it immediately as if typed and submitted; `'fill'` just places it in the input. |
| `persistSuggestions` | `persist-suggestions` | `undefined \| false \| true` | 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. |
| `proseSize` | `prose-size` | `undefined \| "xs" \| "sm" \| "base" \| "lg"` | Body/prose font scale for rendered markdown (`'xs' \| 'sm' \| 'base' \| 'lg'`). Defaults to `'sm'`. |
| `codeTheme` | `code-theme` | `undefined \| string` | Shiki theme name for syntax-highlighted code blocks (e.g. `'github-dark-dimmed'`). |
| `codeHighlight` | `code-highlight` | `undefined \| false \| true` | Enable Shiki syntax highlighting in code blocks. Turn off to render plain `<pre>` blocks (lighter, no highlighter load). Default true. |
| `reasoning` | `reasoning` | `undefined \| "full" \| "compact" \| "off"` | How `reasoning` parts render across the thread. `'full'` (default) is the current collapsible-disclosure behavior; `'compact'` shows only a shimmer loader while a reasoning part streams and nothing once it settles (no expandable detail); `'off'` renders reasoning parts not at all. Forwarded to every `MessageBody` as `reasoningMode`. |
| `reasoningOpen` | `reasoning-open` | `undefined \| false \| true` | Seeds the reasoning disclosure open AND keeps it tracking the stream (open while streaming, closes when it settles): the pre-Task-19f `full` behavior. Default false/absent: the panel starts closed (just the "Thinking" shimmer chip) and only opens on click, the current default (owner ruling, 2026-08-26). Meaningless when `reasoning` is `'compact'` or `'off'`. Forwarded to every `MessageBody` as `reasoningDefaultOpen`. |
| `chatTitle` | `chat-title` | `undefined \| string` | Optional header title shown on the left of the header. |
| `models` | — | `undefined \| { id: string; name: string; provider?: undefined \| string; description?: undefined \| string; group?: undefined \| string }[]` | Optional model list. When set (>1 model) a ModelSwitcher is shown in the header and a `kai-model-change` event fires on selection. |
| `currentModel` | `current-model` | `undefined \| string` | The currently selected model id (pairs with `models`). |
| `context` | — | `undefined \| { usedTokens: number; maxTokens: number; inputTokens?: undefined \| number; outputTokens?: undefined \| number; estimatedCost?: undefined \| number }` | Optional context-window token usage. When set, a Context token meter is shown in the header. |
| `scrollButton` | `scroll-button` | `undefined \| false \| true` | Show the scroll-to-bottom button inside the scroll area. Default true. |
| `headerStart` | `header-start` | `undefined \| false \| true` | 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. |
| `headerEnd` | `header-end` | `undefined \| false \| true` | Whether the host has `slot="header-end"` content (right of the controls). |
| `headerFull` | `header-full` | `undefined \| false \| true` | REPLACE: full custom header in place of the built-in title/model/context bar. |
| `homeFull` | `home-full` | `undefined \| false \| true` | REPLACE: custom home-tab content in place of the built-in home screen (greeting, recent-conversation card, links). Rendered only while the home view is showing, so it is meaningful only when `home` is set; the tab bar and navigation stay the kit's own. Set by the facade when light-DOM `slot="home"` content is projected (region slots, P-6). |
| `sidebar` | `sidebar` | `undefined \| false \| true` | INJECT: left sidebar column (e.g. a conversation list / your own nav). |
| `empty` | `empty` | `undefined \| false \| true` | 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). |
| `composer` | `composer` | `undefined \| false \| true` | REPLACE: full custom composer in place of the built-in prompt input. The projected content wires its own submit (the data-flow boundary). |
| `composerActions` | `composer-actions` | `undefined \| false \| true` | INJECT: accessory row just above the composer (e.g. extra actions). |
| `footer` | `footer` | `undefined \| false \| true` | INJECT: footer row below the composer (disclaimers, token meter, …). |
| `attach` | `attach` | `undefined \| false \| true` | When `false`, hides the built-in paperclip attach button. Defaults to `true` (undeclared keeps today's behavior: attach visible), matching `DefaultPromptInput`'s own default: only an explicit `false` hides it. |
| `webSearch` | `web-search` | `undefined \| false \| true` | Show a web-search (Globe) button in the input toolbar; calls `onWebSearch`. |
| `voice` | `voice` | `undefined \| false \| true` | Show a Voice (Mic) button in the input toolbar; fires a `voice` event. |
| `triggers` | — | `undefined \| { char: string; kind: string; items?: undefined \| { id: string; label: string; icon?: undefined \| string; description?: undefined \| string; group?: undefined \| string; kind?: undefined \| string; promptText?: undefined \| string; data?: undefined \| Record<string, unknown> }[] }[]` | 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. |
| `kindIcons` | — | `undefined \| Record<string, string>` | Default icon per entity kind (kind → image src) for pills/menu items. |
| `actionsReveal` | `actions-reveal` | `undefined \| "always" \| "hover"` | Whether each message's action bar is always visible (`'always'`, default) or only revealed on hover of that message row (`'hover'`). |
| `userActions` | — | `undefined \| ("copy" \| "dislike" \| "edit" \| "like" \| "regenerate" \| "speak" \| { id: string; label: string; icon?: undefined \| string; tooltip?: undefined \| string })[]` | Role-scoped DEFAULT action bars (B-7b): a user message with no `actions` of its own gets `userActions`; an assistant message, `assistantActions`. A per-message `m.actions` OVERRIDES the role default (replace, not merge), so a message that sets `actions: []` renders NO action bar even when a role default is set. Set as JS properties. |
| `assistantActions` | — | `undefined \| ("copy" \| "dislike" \| "edit" \| "like" \| "regenerate" \| "speak" \| { id: string; label: string; icon?: undefined \| string; tooltip?: undefined \| string })[]` | See `userActions`, the assistant-role default. |
| `hideSources` | `hide-sources` | `undefined \| false \| true` | Hide the citations row consecutive `source` parts collapse into (`part="citations"`, message.tsx). Named as a HIDE, not `sources: boolean`, so absence-means-default stays unambiguous: absent/false is today's rendering, byte-for-byte (B-8). |
| `accept` | `accept` | `undefined \| string` | Which attachment media types the user may stage, in HTML `accept` syntax: `<kai-chat accept="image/*,application/pdf">`. A plain string, so unlike `messages` it DOES work as an attribute. Omitted means no filter. MEDIA TYPES ONLY -- exact (`image/png`) or subtype wildcard (`text/*`). HTML allows a file extension here and this does not: `accept=".py"` THROWS with the entry named, rather than silently resolving to a picker that accepts nothing. It can only NARROW what the kit can already encode: `accept="image/*"` resolves to the four image formats both APIs take, not to every image type the OS offers. Pass the SAME string to `toOpenAIMessages(msgs, { accept })` and the picker and the wire cannot disagree -- both resolve it through `resolveMediaPolicy` against one declaration. That declaration is readable as `encodableMediaTypes()` from `@kitn.ai/ui/wire`, if you would rather build your own picker than use this prop. |
| `messages` | — | `undefined \| { id: string; role: "user" \| "assistant"; parts: ({ type: "text"; text: string; raw?: undefined \| { source: string; payload: unknown } } \| { type: "reasoning"; text: string; label?: undefined \| string; index?: undefined \| number; streamId?: undefined \| string; signature?: undefined \| string; raw?: undefined \| { source: string; payload: unknown } } \| { type: "tool"; tool: { type: string; kind?: undefined \| "command" \| "file-change" \| "search" \| "fetch" \| "mcp" \| "image" \| "generic"; state: "input-streaming" \| "input-available" \| "output-available" \| "output-error"; input?: undefined \| Record<string, unknown>; rawInput?: undefined \| string; output?: undefined \| Record<string, unknown>; toolCallId?: undefined \| string; errorText?: undefined \| string; raw?: undefined \| { source: string; payload: unknown } }; raw?: undefined \| { source: string; payload: unknown } } \| { type: "card"; envelope: { type: string; id: string; data: unknown; title?: undefined \| string; resolution?: undefined \| { kind: "action"; action: string; payload?: unknown; at?: undefined \| string } \| { kind: "submit"; data: unknown; at?: undefined \| string } \| { kind: "dismissed"; at?: undefined \| string } \| { kind: "expired"; reason?: undefined \| string; at?: undefined \| string } }; raw?: undefined \| { source: string; payload: unknown } } \| { type: "source"; source: { id?: undefined \| string; url?: undefined \| string; title?: undefined \| string; snippet?: undefined \| string; index?: undefined \| number }; raw?: undefined \| { source: string; payload: unknown } } \| { type: "file"; attachment: { id: string; type: "file" \| "source-document"; filename?: undefined \| string; mediaType?: undefined \| string; url?: undefined \| string; title?: undefined \| string }; raw?: undefined \| { source: string; payload: unknown } })[]; actions?: undefined \| ("copy" \| "dislike" \| "edit" \| "like" \| "regenerate" \| "speak" \| { 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 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>`. |
| `cardTypes` | — | `undefined \| Record<string, 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. |
| `cardSchemas` | — | `undefined \| Record<string, object>` | 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. |
| `conversations` | `conversations` | `undefined \| false \| true` | Turns on the prior-conversations list (a list-toggle button in the header, plus a second list view sharing the panel, C-1). Attribute- settable like every other boolean flag on this element: `<kai-chat conversations>`. Requires `store`. A row select, "new conversation," or the visitor's mount-time auto-restore all deliver their messages the same way: listen for `kai-conversation-load` and set `el.messages` from `event.detail.messages` (a fresh array): this element does not update `messages` for you. Set with no `store`, the underlying `ChatThread` decides loudly (one console.error) and stays visually off; this facade always supplies its own internal load handler (the `kai-conversation-load` dispatch below), so the second ChatThread guard, missing `onConversationLoad`, never trips here, even for a consumer who never listens for the event. Default false. |
| `store` | — | `undefined \| { list: () => Promise<{ id: string; title: string; groupId?: undefined \| string; scope?: undefined \| { type: "document" \| "collection"; documentId?: undefined \| string; filters?: undefined \| { tags?: undefined \| string[]; authors?: undefined \| string[]; contentType?: undefined \| "transcript" \| "markdown"; dateRange?: undefined \| { from: string; to: string } } }; messageCount: number; lastMessageAt?: undefined \| string; updatedAt: string; trailing?: undefined \| string; lastReadAt?: undefined \| string }[]>; load: (id: string) => Promise<{ id: string; role: "user" \| "assistant"; parts: ({ type: "text"; text: string; raw?: undefined \| { source: string; payload: unknown } } \| { type: "reasoning"; text: string; label?: undefined \| string; index?: undefined \| number; streamId?: undefined \| string; signature?: undefined \| string; raw?: undefined \| { source: string; payload: unknown } } \| { type: "tool"; tool: { type: string; kind?: undefined \| "command" \| "file-change" \| "search" \| "fetch" \| "mcp" \| "image" \| "generic"; state: "input-streaming" \| "input-available" \| "output-available" \| "output-error"; input?: undefined \| Record<string, unknown>; rawInput?: undefined \| string; output?: undefined \| Record<string, unknown>; toolCallId?: undefined \| string; errorText?: undefined \| string; raw?: undefined \| { source: string; payload: unknown } }; raw?: undefined \| { source: string; payload: unknown } } \| { type: "card"; envelope: { type: string; id: string; data: unknown; title?: undefined \| string; resolution?: undefined \| { kind: "action"; action: string; payload?: unknown; at?: undefined \| string } \| { kind: "submit"; data: unknown; at?: undefined \| string } \| { kind: "dismissed"; at?: undefined \| string } \| { kind: "expired"; reason?: undefined \| string; at?: undefined \| string } }; raw?: undefined \| { source: string; payload: unknown } } \| { type: "source"; source: { id?: undefined \| string; url?: undefined \| string; title?: undefined \| string; snippet?: undefined \| string; index?: undefined \| number }; raw?: undefined \| { source: string; payload: unknown } } \| { type: "file"; attachment: { id: string; type: "file" \| "source-document"; filename?: undefined \| string; mediaType?: undefined \| string; url?: undefined \| string; title?: undefined \| string }; raw?: undefined \| { source: string; payload: unknown } })[]; actions?: undefined \| ("copy" \| "dislike" \| "edit" \| "like" \| "regenerate" \| "speak" \| { id: string; label: string; icon?: undefined \| string; tooltip?: undefined \| string })[]; avatar?: undefined \| { src?: undefined \| string; fallback?: undefined \| string; alt?: undefined \| string }; feedback?: undefined \| "like" \| "dislike" }[]>; save: (id: string, messages: { id: string; role: "user" \| "assistant"; parts: ({ type: "text"; text: string; raw?: undefined \| { source: string; payload: unknown } } \| { type: "reasoning"; text: string; label?: undefined \| string; index?: undefined \| number; streamId?: undefined \| string; signature?: undefined \| string; raw?: undefined \| { source: string; payload: unknown } } \| { type: "tool"; tool: { type: string; kind?: undefined \| "command" \| "file-change" \| "search" \| "fetch" \| "mcp" \| "image" \| "generic"; state: "input-streaming" \| "input-available" \| "output-available" \| "output-error"; input?: undefined \| Record<string, unknown>; rawInput?: undefined \| string; output?: undefined \| Record<string, unknown>; toolCallId?: undefined \| string; errorText?: undefined \| string; raw?: undefined \| { source: string; payload: unknown } }; raw?: undefined \| { source: string; payload: unknown } } \| { type: "card"; envelope: { type: string; id: string; data: unknown; title?: undefined \| string; resolution?: undefined \| { kind: "action"; action: string; payload?: unknown; at?: undefined \| string } \| { kind: "submit"; data: unknown; at?: undefined \| string } \| { kind: "dismissed"; at?: undefined \| string } \| { kind: "expired"; reason?: undefined \| string; at?: undefined \| string } }; raw?: undefined \| { source: string; payload: unknown } } \| { type: "source"; source: { id?: undefined \| string; url?: undefined \| string; title?: undefined \| string; snippet?: undefined \| string; index?: undefined \| number }; raw?: undefined \| { source: string; payload: unknown } } \| { type: "file"; attachment: { id: string; type: "file" \| "source-document"; filename?: undefined \| string; mediaType?: undefined \| string; url?: undefined \| string; title?: undefined \| string }; raw?: undefined \| { source: string; payload: unknown } })[]; actions?: undefined \| ("copy" \| "dislike" \| "edit" \| "like" \| "regenerate" \| "speak" \| { id: string; label: string; icon?: undefined \| string; tooltip?: undefined \| string })[]; avatar?: undefined \| { src?: undefined \| string; fallback?: undefined \| string; alt?: undefined \| string }; feedback?: undefined \| "like" \| "dislike" }[]) => Promise<void>; markRead?: undefined \| ((id: string) => Promise<void>) }` | The adapter this thread persists conversations through: an object of three functions (`list`/`load`/`save`; `ConversationStore`, exported from `@kitn.ai/ui`'s `primitives/conversation-store`). A JS PROPERTY ONLY: `el.store = myAdapter`. It can never be an attribute, since a function-bearing object has no HTML string form, the same reasoning that keeps `messages`/`cardSchemas` property-only (the kai- contract: array/object props are JS properties, never attributes). Two built-ins ship: `localStorageStore(name, userId?)` and `fetchStore(url, userId?)`. |
| `home` | — | `undefined \| { greeting?: undefined \| { title?: undefined \| string; subtitle?: undefined \| string }; recentConversation?: undefined \| false \| true; newConversation?: undefined \| { label?: undefined \| string }; links?: undefined \| { label: string; href?: undefined \| string; description?: undefined \| string; icon?: undefined \| string }[] }` | Turns on the widget home screen (Intercom-pattern): the panel boots into a `home` view, with a greeting, most-recent-conversation card, a "new conversation" CTA, and host-defined links, plus a Home/Messages tab bar for switching back to the thread. An OBJECT, so it is a JS property only: `el.home = { greeting: { title: 'Hey' }, links: [...] }`, never an attribute (the kai- contract: array/object props are JS properties). A `links` entry with no `href` fires `kai-home-link` with that entry when tapped, rather than navigating; one WITH `href` opens it directly (only when the URL passes the kit's own scheme allowlist). Omit for the no-home widget (chat view only, unchanged). |
| `hostOpen` | `host-open` | `undefined \| false \| true` | Whether the chrome that HOSTS this element is currently VISIBLE to the visitor, e.g. a composed launcher/dock's open state. Set as a JS PROPERTY (`el.hostOpen = open`), never an attribute: the default is `true` and an HTML attribute's presence can only ever say "true", so there is no attribute form that expresses the one value worth setting (`false`). Meaningful only with `conversations` on, where it is the third leg of "seen": the active conversation is marked read only while it is active AND the chat view is showing AND this is `true`. Leave it unset for any layout with no show/hide concept (fullscreen, aside, split); that just means unread never distinguishes "closed" from "open". The companion of the `kai-unread-change` event: set this from your launcher's open state, mirror that event onto its badge. |

**Events** (non-bubbling `CustomEvent`s — listen directly on the element):

| Event | `detail` type | Description |
|---|---|---|
| `kai-attachments-change` | `CustomEvent<{ attachments: { id: string; type: "file" \| "source-document"; filename?: undefined \| string; mediaType?: undefined \| string; url?: undefined \| string; title?: undefined \| string }[] }>` | The staged attachments changed (file added or removed). Carries the full current list so a consumer can react in real time. |
| `kai-attachments-rejected` | `CustomEvent<{ rejected: { filename: string; mediaType: string; reason: "filtered" \| "unsupported" }[] }>` | One or more picked files were refused because `accept` excluded them. The element renders NO message of its own: it reports the facts (name, media type, whether the kit could have sent it) and what the user should see is the application's call. Only ever fires when `accept` is set. |
| `kai-conversation-load` | `CustomEvent<{ id: string \| undefined; messages: { id: string; role: "user" \| "assistant"; parts: ({ type: "text"; text: string; raw?: undefined \| { source: string; payload: unknown } } \| { type: "reasoning"; text: string; label?: undefined \| string; index?: undefined \| number; streamId?: undefined \| string; signature?: undefined \| string; raw?: undefined \| { source: string; payload: unknown } } \| { type: "tool"; tool: { type: string; kind?: undefined \| "command" \| "file-change" \| "search" \| "fetch" \| "mcp" \| "image" \| "generic"; state: "input-streaming" \| "input-available" \| "output-available" \| "output-error"; input?: undefined \| Record<string, unknown>; rawInput?: undefined \| string; output?: undefined \| Record<string, unknown>; toolCallId?: undefined \| string; errorText?: undefined \| string; raw?: undefined \| { source: string; payload: unknown } }; raw?: undefined \| { source: string; payload: unknown } } \| { type: "card"; envelope: { type: string; id: string; data: unknown; title?: undefined \| string; resolution?: undefined \| { kind: "action"; action: string; payload?: unknown; at?: undefined \| string } \| { kind: "submit"; data: unknown; at?: undefined \| string } \| { kind: "dismissed"; at?: undefined \| string } \| { kind: "expired"; reason?: undefined \| string; at?: undefined \| string } }; raw?: undefined \| { source: string; payload: unknown } } \| { type: "source"; source: { id?: undefined \| string; url?: undefined \| string; title?: undefined \| string; snippet?: undefined \| string; index?: undefined \| number }; raw?: undefined \| { source: string; payload: unknown } } \| { type: "file"; attachment: { id: string; type: "file" \| "source-document"; filename?: undefined \| string; mediaType?: undefined \| string; url?: undefined \| string; title?: undefined \| string }; raw?: undefined \| { source: string; payload: unknown } })[]; actions?: undefined \| ("copy" \| "dislike" \| "edit" \| "like" \| "regenerate" \| "speak" \| { 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" }[] }>` | A conversation's history loaded: a row tap in the list, "new conversation," or the visitor's own mount-time auto-restore of their most recent thread (only fires when `conversations` is on and a `store` is set). `detail.id` is that conversation's id, `undefined` for the "new conversation" case (no id exists until the first message mints one, C-6). Set `el.messages = event.detail.messages` (already a fresh array) to actually render it, since this element does not do that for you; `messages` stays your own state like everywhere else on this element. |
| `kai-home-link` | `CustomEvent<{ entry: { label: string; href?: undefined \| string; description?: undefined \| string; icon?: undefined \| string } }>` | A `home.links` entry with no `href` was activated (tapped/clicked/Enter). Meaningful only when `home` is set. |
| `kai-message-action` | `CustomEvent<{ messageId: string; action: string; state?: undefined \| "on" \| "off" }>` | 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. |
| `kai-model-change` | `CustomEvent<{ modelId: string }>` | The header model switcher changed. |
| `kai-submit` | `CustomEvent<{ value: string; attachments: { id: string; type: "file" \| "source-document"; filename?: undefined \| string; mediaType?: undefined \| string; url?: undefined \| string; title?: undefined \| string }[] }>` | User submitted a message. |
| `kai-suggestion-click` | `CustomEvent<{ value: string }>` | A suggestion chip was clicked (only in `suggestion-mode="fill"`). |
| `kai-unread-change` | `CustomEvent<{ unread: false \| true }>` | "Is any conversation OTHER than the currently-seen one unread" changed. This is the same value this element already renders as the dot on its own header list toggle, reported outward so a sibling control with no view into the internal conversation-summary state (a composed launcher's badge, a `kai-dock`'s `unread` prop) can mirror it: set `dock.unread = event.detail.unread`. Fires on every change, including the initial `false`. Only meaningful with `conversations` on; pairs with the `hostOpen` property, which is what lets "arrived while the widget was closed" count as unread for the active conversation too. |
| `kai-value-change` | `CustomEvent<{ value: string }>` | Fired on every input change. |
| `kai-voice` | `CustomEvent<Record<string, never>>` | The Mic / voice button was clicked. |
| `kai-web-search` | `CustomEvent<Record<string, never>>` | The web-search (Globe) toolbar button was clicked. |

**Methods** (call on the element instance: `document.querySelector('kai-chat').focus(…)`):

| Method | Signature | Description |
|---|---|---|
| `focus` | `(options?: FocusOptions): void` | 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. |
| `blur` | `(): 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. |
| `clear` | `(): 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. |
| `send` | `(): 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. |
| `scrollToBottom` | `(behavior?: ScrollBehavior): void` | Scroll the message viewport to the newest message. Defaults to `'smooth'`; pass `'instant'` to jump without animating. |
| `closeConversationsList` | `(): void` | Force the widget back to its default landing view: `'home'` when the `home` property is set, `'chat'` otherwise (a no-op if already there, or if neither `home` nor `conversations` is on). This element has no knowledge of whatever chrome hosts it, so it cannot know when that host closes; a composed launcher/dock calls this on every hide so the NEXT open lands on the default screen rather than wherever the conversations list was left. `kai-dock`'s `kai-open-change` fires on every close path (header X, launcher toggle, Escape), so one listener covers all three. |
| `startNewConversation` | `(): void` | Start a fresh conversation, on the same path as the list view's "+ New conversation" row: clears the active conversation id, returns to the chat view, and delivers `[]` through `kai-conversation-load` (set `el.messages = event.detail.messages` like every other load; this element never updates `messages` for you). The seam a composed app's own "New conversation" control drives (B-10; the construct shell palette's entry rides the same controller call). No id is minted until the first message (C-6), so calling this on an already-empty new conversation is a harmless no-op. |

**Slots** (project your own markup via `slot="name"` on a light-DOM child):

| Slot | Mode | Description |
|---|---|---|
| `header-start` | inject | Leading header controls, left of the title. |
| `header-end` | inject | Trailing header controls. |
| `header` | replace | Full custom header; replaces the built-in title/model/context bar. |
| `sidebar` | inject | Left column (your nav / conversation list). Fixed width; use compose-your-own for resizable. |
| `home` | replace | Custom home-tab content in place of the built-in home screen (greeting, recent-conversation card, links). Rendered only while the home view is showing, so it needs the `home` property set; the tab bar and navigation stay built in. |
| `empty` | replace | Custom zero-state rendered in the message area while the thread is empty. Replaces the empty message list only; the composer and any suggestions still render. |
| `composer` | replace | Full custom composer; you own submit + loading, drive the thread via messages. |
| `composer-actions` | inject | Accessory row above the composer. |
| `footer` | inject | Row below the composer (disclaimers, token meter). |

**Styleable parts** (restyle from outside via `kai-chat::part(name)`):

| Part | Description |
|---|---|
| `::part(header-bar)` | The built-in header bar (the title / model-switcher / context row that hosts the header-start/header-end inject slots). Restyle its height, padding, or gap from outside without replacing the whole header via the `header` slot. — `kai-chat::part(header-bar) { height: 3.5rem; padding-inline: 1rem; gap: 0.5rem }` |
| `::part(header)` | Full custom header; replaces the built-in title/model/context bar. |
| `::part(sidebar)` | Left column (your nav / conversation list). Fixed width; use compose-your-own for resizable. |
| `::part(footer)` | Row below the composer (disclaimers, token meter). |

---

### `kai-checkbox` / `Checkbox`

**Properties** (every element also accepts `theme="light|dark|auto"`; only scalar props work as HTML attributes):

| Property | Attribute | Type | Description |
|---|---|---|---|
| `theme` | `theme` | `"light" \| "dark" \| "auto"` | Color mode (`auto` follows prefers-color-scheme). |
| `checked` | `checked` | `undefined \| false \| true` | Controlled checked state. Settable and reflected to the `checked` attribute. `el.checked = true` (or `<kai-checkbox checked>`) drives it; ticking the box updates it and fires `kai-change`. Read `el.checked` for live state. |
| `defaultChecked` | `default-checked` | `undefined \| false \| true` | Initial checked state on mount (uncontrolled seed). Bare attribute (`<kai-checkbox default-checked>`) turns it on. |
| `indeterminate` | `indeterminate` | `undefined \| false \| true` | The mixed state, for a parent box whose children are partly ticked. Visual plus an accessibility hint: the box still reports `checked === false`. |
| `disabled` | `disabled` | `undefined \| false \| true` | Disable interaction. |
| `required` | `required` | `undefined \| false \| true` | Set the native `required` attribute, and nothing more. Whether an unticked box is an error is the application's rule, not the kit's. |
| `label` | `label` | `undefined \| string` | Accessible label. The visible text beside the box is the consumer's to render. |
| `name` | `name` | `undefined \| string` | Form-control name (paired with `value`). |
| `value` | `value` | `undefined \| string` | Submitted value when checked (paired with `name`). Defaults to `'on'`. |

**Events** (non-bubbling `CustomEvent`s — listen directly on the element):

| Event | `detail` type | Description |
|---|---|---|
| `kai-change` | `CustomEvent<{ checked: false \| true }>` | The box was ticked or unticked. |

**Methods** (call on the element instance: `document.querySelector('kai-checkbox').toggle()`):

| Method | Signature | Description |
|---|---|---|
| `toggle` | `(): void` | Flip the box and fire `kai-change` (no-op while disabled). |
| `focus` | `(options?: FocusOptions): void` | Focus the inner input (the host element can't reach it). |

---

### `kai-checkbox-group` / `CheckboxGroup`

**Properties** (every element also accepts `theme="light|dark|auto"`; only scalar props work as HTML attributes):

| Property | Attribute | Type | Description |
|---|---|---|---|
| `theme` | `theme` | `"light" \| "dark" \| "auto"` | Color mode (`auto` follows prefers-color-scheme). |
| `options` | — | `{ value: string; label: string; description?: undefined \| string; disabled?: undefined \| false \| true }[]` | The choices, top to bottom. Set as a JS PROPERTY (array), never an attribute. Rendered in full: the kit never truncates, re-orders or de-duplicates them. |
| `value` | `value` | `undefined \| string` | The FIRST selected value. Settable and reflected to the `value` attribute, so `:host([value])` and `el.value` see live state, and a seed can be written in markup. Writing it makes that the whole selection; to read or drive the rest, use `el.values`. |
| `name` | `name` | `undefined \| string` | The shared form-control name every box carries, so `FormData.getAll(name)` reads the whole selection back under one key. NO DEFAULT, unlike `<kai-radio-group>`. A radio set needs a shared `name` for the browser to make it exclusive and arrow-navigable, so one is generated when none is given; checkboxes are independent controls and behave correctly with no name at all. Generating one here would submit the selection under a random key, which is worse than submitting nothing. The element is NOT form-associated (no `ElementInternals`, no `setFormValue()`), the same known gap `<kai-input>` records: the boxes live in a shadow root, so a surrounding `<form>` collects nothing from them whether or not `name` is set. Read `el.values`. The name still lands on every inner input, so it is right the day form association arrives. |
| `disabled` | `disabled` | `undefined \| false \| true` | Disable every row. Individual rows carry their own `disabled`. |
| `label` | `label` | `undefined \| string` | Accessible name for the group. |

**Events** (non-bubbling `CustomEvent`s — listen directly on the element):

| Event | `detail` type | Description |
|---|---|---|
| `kai-change` | `CustomEvent<{ value: string; values: string[] }>` | A row was ticked or unticked. `values` is the whole selection after the change, which is what a multi-select control needs; `value` is the first of them (empty when nothing is selected). Both are always present, so neither shape silently loses the other. This is `<kai-select>`'s detail, deliberately. |

**Methods** (call on the element instance: `document.querySelector('kai-checkbox-group').focus(…)`):

| Method | Signature | Description |
|---|---|---|
| `focus` | `(options?: FocusOptions): void` | Focus the group's first box. Not "the first ticked one", which is `<kai-radio-group>`'s rule: a radio group is ONE tab stop that lands on the selection, while every checkbox here is its own tab stop, so the entry point is simply the top of the list. |

---

### `kai-checkpoint` / `Checkpoint`

**Properties** (every element also accepts `theme="light|dark|auto"`; only scalar props work as HTML attributes):

| Property | Attribute | Type | Description |
|---|---|---|---|
| `theme` | `theme` | `"light" \| "dark" \| "auto"` | Color mode (`auto` follows prefers-color-scheme). |
| `label` | `label` | `undefined \| string` | Optional text beside the icon. |
| `tooltip` | `tooltip` | `undefined \| string` | Tooltip on hover. |
| `variant` | `variant` | `undefined \| "ghost" \| "default" \| "outline"` | Visual button style. |
| `size` | `size` | `undefined \| "sm" \| "md" \| "lg" \| "icon" \| "icon-sm"` | Button size (use an `icon*` size for an icon-only checkpoint). |

**Events** (non-bubbling `CustomEvent`s — listen directly on the element):

| Event | `detail` type | Description |
|---|---|---|
| `kai-select` | `CustomEvent` | The checkpoint was clicked. |

---

### `kai-choice` / `Choice`

**Properties** (every element also accepts `theme="light|dark|auto"`; only scalar props work as HTML attributes):

| Property | Attribute | Type | Description |
|---|---|---|---|
| `theme` | `theme` | `"light" \| "dark" \| "auto"` | Color mode (`auto` follows prefers-color-scheme). |
| `data` | — | `undefined \| { prompt?: undefined \| string; options: { id: string; label: string; description?: undefined \| string; media?: undefined \| { image?: undefined \| string; imageAlt?: undefined \| string; icon?: undefined \| string }; meta?: undefined \| string; recommended?: undefined \| false \| true; disabled?: undefined \| false \| true; payload?: unknown }[]; allowOther?: undefined \| false \| true \| { label?: undefined \| string; placeholder?: undefined \| string }; submitLabel?: undefined \| string; dismissible?: undefined \| false \| true }` | 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. |
| `cardId` | `card-id` | `undefined \| string` | Stable card id correlating every emitted CardEvent. Attribute: `card-id`. |
| `heading` | `heading` | `undefined \| string` | Heading rendered in the card chrome (= CardEnvelope.title). Attribute: `heading`. |
| `resolution` | — | `undefined \| Record<string, unknown>` | Set when the user resolved this card; renders the read-only view. Property: `el.resolution = { kind:'action', action:'…' }`. |
| `value` | `value` | `undefined \| string` | Controlled selection: the selected option id. When set, the consumer owns the current pick (RadioGroup `value`). Attribute: `value`. |
| `defaultValue` | `default-value` | `undefined \| string` | Option id to pre-select on mount (uncontrolled seed). Attribute: `default-value`. |
| `disabled` | `disabled` | `undefined \| false \| true` | Disable the whole radiogroup + Submit (e.g. while the agent is busy). Attribute: `disabled`. |

**Events** (non-bubbling `CustomEvent`s — listen directly on the element):

| Event | `detail` type | Description |
|---|---|---|
| `kai-value-change` | `CustomEvent<{ value: string }>` | The selection changed BEFORE submit (a row click or the `select()` method). Distinct from the terminal `action` verb on the `kai-card` contract event. |

**Methods** (call on the element instance: `document.querySelector('kai-choice').focus(…)`):

| Method | Signature | Description |
|---|---|---|
| `focus` | `(options?: FocusOptions): void` | Focus the radiogroup roving tab stop (or the Other input when selected). |
| `select` | `(optionId: string): 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. |
| `send` | `(): 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. |
| `dismiss` | `(): void` | Trigger the dismiss path: emits `dismiss` on kai-card and optimistically collapses the card to its re-openable stub. |
| `reopen` | `(): void` | Re-open a dismissed card from its stub: emits `reopen` on kai-card. |

---

### `kai-coachmark` / `Coachmark`

**Properties** (every element also accepts `theme="light|dark|auto"`; only scalar props work as HTML attributes):

| Property | Attribute | Type | Description |
|---|---|---|---|
| `theme` | `theme` | `"light" \| "dark" \| "auto"` | Color mode (`auto` follows prefers-color-scheme). |
| `open` | `open` | `undefined \| false \| true` | 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`. |
| `defaultOpen` | `default-open` | `undefined \| false \| true` | Initial open state on mount (uncontrolled seed). |
| `headline` | `headline` | `undefined \| string` | The bold title. Named `headline` because `title` collides with the global `HTMLElement.title` attribute (it throws at registration). |
| `badge` | `badge` | `undefined \| string` | A small badge pill beside the headline (e.g. "New"). |
| `placement` | `placement` | `undefined \| string` | Floating placement relative to the anchor (default `bottom`). |
| `tone` | `tone` | `undefined \| "primary" \| "info" \| "success" \| "warning" \| "error"` | Color tone: `primary` (default, theme accent), `info` (blue), `success` (green), `warning` (amber), or `error` (red), reusing the kit's tool hues. |
| `arrow` | `arrow` | `undefined \| false \| true` | Render the arrow that points at the anchor (default `true`). Set `arrow="false"` for a plain bubble with no pointer. |

**Events** (non-bubbling `CustomEvent`s — listen directly on the element):

| Event | `detail` type | Description |
|---|---|---|
| `kai-dismiss` | `CustomEvent<Record<string, never>>` | The × dismiss button was pressed. The consumer records that this hint was seen so it won't show again. |
| `kai-open-change` | `CustomEvent<{ open: false \| true }>` | The coachmark opened or closed (a method, the ×, or a driven `open`). |

**Methods** (call on the element instance: `document.querySelector('kai-coachmark').show()`):

| Method | Signature | Description |
|---|---|---|
| `show` | `(): void` | Open it programmatically (no-op while disabled). |
| `hide` | `(): void` | Close it programmatically. |
| `toggle` | `(): void` | Flip the open state (closes while disabled). |

**Slots** (project your own markup via `slot="name"` on a light-DOM child):

| Slot | Mode | Description |
|---|---|---|
| _(default)_ | inject | The ANCHOR the coachmark points at: the element it attaches to and positions against. The bubble body is the `content` slot. |
| `content` | replace | The bubble body text shown under the headline. |

**Styleable parts** (restyle from outside via `kai-coachmark::part(name)`):

| Part | Description |
|---|---|
| `::part(bubble)` | The hint bubble panel. Restyle its background, radius, or padding from outside; the default is bg-primary. — `kai-coachmark::part(bubble) { border-radius: 1rem }` |
| `::part(arrow)` | The arrow pointing at the anchor. Inherits the bubble color; recolor it alongside the bubble. — `kai-coachmark::part(arrow) { background: var(--color-accent) }` |
| `::part(badge)` | The small badge pill beside the headline (e.g. "New"). — `kai-coachmark::part(badge) { text-transform: none }` |
| `::part(title)` | The bold headline text. — `kai-coachmark::part(title) { font-size: 0.9375rem }` |
| `::part(dismiss)` | The dismiss button. Recolor or reposition it from outside. — `kai-coachmark::part(dismiss) { color: var(--color-primary-foreground) }` |

---

### `kai-code-block` / `CodeBlock`

**Properties** (every element also accepts `theme="light|dark|auto"`; only scalar props work as HTML attributes):

| Property | Attribute | Type | Description |
|---|---|---|---|
| `theme` | `theme` | `"light" \| "dark" \| "auto"` | Color mode (`auto` follows prefers-color-scheme). |
| `code` | `code` | `string` | The source code to render. |
| `language` | `language` | `undefined \| string` | Language grammar (e.g. `js`, `python`). Defaults to `tsx`. |
| `codeTheme` | `code-theme` | `undefined \| string` | Shiki theme name. |
| `codeHighlight` | `code-highlight` | `undefined \| false \| true` | Disable syntax highlighting (renders plain text, no Shiki). |
| `copy` | `copy` | `undefined \| false \| true` | Show the copy button. **Defaults to ON**, because this element is documented as shipping one. Opt out with `copy="false"` or `el.copy = false`. |
| `proseSize` | `prose-size` | `undefined \| "xs" \| "sm" \| "base" \| "lg"` | Code text sizing. |

_No events._

**Styleable parts** (restyle from outside via `kai-code-block::part(name)`):

| Part | Description |
|---|---|
| `::part(copy)` | The copy-to-clipboard button in the header row. Hide it with `copy="false"` rather than CSS. — `kai-code-block::part(copy) { color: var(--color-primary) }` |

---

### `kai-command` / `Command`

**Properties** (every element also accepts `theme="light|dark|auto"`; only scalar props work as HTML attributes):

| Property | Attribute | Type | Description |
|---|---|---|---|
| `theme` | `theme` | `"light" \| "dark" \| "auto"` | Color mode (`auto` follows prefers-color-scheme). |
| `items` | — | `undefined \| { id: string; label: string; icon?: undefined \| string; description?: undefined \| string; shortcut?: undefined \| string; group?: undefined \| string }[]` | Flat list of items. Set as a JS property, not an HTML attribute. |
| `placeholder` | `placeholder` | `undefined \| string` | Placeholder text for the search input. |
| `emptyLabel` | `empty-label` | `undefined \| string` | Label shown when no items match the current query. |

**Events** (non-bubbling `CustomEvent`s — listen directly on the element):

| Event | `detail` type | Description |
|---|---|---|
| `kai-active-change` | `CustomEvent<{ id: string \| undefined }>` | 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. |
| `kai-query-change` | `CustomEvent<{ value: string }>` | Fired on every keystroke in the search input. |
| `kai-select` | `CustomEvent<{ id: string }>` | Fired when the user selects an item (click or Enter). |

**Methods** (call on the element instance: `document.querySelector('kai-command').focus(…)`):

| Method | Signature | Description |
|---|---|---|
| `focus` | `(options?: FocusOptions): void` | 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). |
| `blur` | `(): void` | Blur the focused search input. |
| `clear` | `(): void` | Reset the search query to empty, re-showing all items, and fire `kai-query-change` with `''`. Mirrors the Escape-key behavior. |

**Styleable parts** (restyle from outside via `kai-command::part(name)`):

| Part | Description |
|---|---|
| `::part(shortcut)` | The right-aligned per-row keyboard shortcut, rendered as kai-kbd key caps. Shown only when a row carries a `shortcut`. — `kai-command::part(shortcut) { opacity: 0.8 }` |

---

### `kai-compare` / `Compare`

**Properties** (every element also accepts `theme="light|dark|auto"`; only scalar props work as HTML attributes):

| Property | Attribute | Type | Description |
|---|---|---|---|
| `theme` | `theme` | `"light" \| "dark" \| "auto"` | Color mode (`auto` follows prefers-color-scheme). |
| `data` | — | `undefined \| Record<string, unknown>` | 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. |
| `compareId` | `compare-id` | `undefined \| string` | Stable id correlating every emitted event. Attribute: `compare-id`. |
| `selection` | — | `undefined \| Record<string, unknown>` | Re-hydrate / control the user's pick. Set as a JS PROPERTY: `el.selection = { chosenId, rejectedIds }`. Renders the collapsed winner. |
| `layout` | `layout` | `undefined \| "auto" \| "columns" \| "tabs"` | Layout: `'auto'` (default, columns when wide, tabs when narrow, by CONTAINER width) \| `'columns'` (side-by-side) \| `'tabs'` (pills to switch). Attribute: `layout`. |
| `proseSize` | `prose-size` | `undefined \| "xs" \| "sm" \| "base" \| "lg"` | Prose/text size for the rendered candidates. Attribute: `prose-size`. |
| `codeTheme` | `code-theme` | `undefined \| string` | Shiki theme for code blocks in the candidates. Attribute: `code-theme`. |
| `codeHighlight` | `code-highlight` | `undefined \| false \| true` | Whether code blocks are syntax-highlighted. Attribute: `code-highlight`. |

**Events** (non-bubbling `CustomEvent`s — listen directly on the element):

| Event | `detail` type | Description |
|---|---|---|
| `kai-compare-select` | `CustomEvent<{ chosenId: string; rejectedIds: string[]; at?: undefined \| number }>` | The user committed a pick. `detail` = `{ chosenId, rejectedIds, at }`. |
| `kai-error` | `CustomEvent<{ compareId: string; message: string }>` | The definition was unusable. |
| `kai-ready` | `CustomEvent<{ compareId: string }>` | Both candidates have settled and the pick is live. |

**Methods** (call on the element instance: `document.querySelector('kai-compare').select(…)`):

| Method | Signature | Description |
|---|---|---|
| `select` | `(candidateId: string): void` | 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). |
| `focus` | `(options?: FocusOptions): void` | Focus the current roving tab stop (the focused candidate's "Pick this" radio) so a consumer can move keyboard focus into the radiogroup. |

---

### `kai-composer` / `Composer`

**Properties** (every element also accepts `theme="light|dark|auto"`; only scalar props work as HTML attributes):

| Property | Attribute | Type | Description |
|---|---|---|---|
| `theme` | `theme` | `"light" \| "dark" \| "auto"` | Color mode (`auto` follows prefers-color-scheme). |
| `value` | — | `undefined \| string \| ({ type: "text"; text: string } \| { type: "entity"; entity: { kind: string; id: string; label: string; icon?: undefined \| string; promptText?: undefined \| string; data?: undefined \| Record<string, unknown> } })[]` | Controlled value: a string or a full ComposerDoc (set as JS property). |
| `placeholder` | `placeholder` | `undefined \| string` | Placeholder text shown when the composer is empty. |
| `disabled` | `disabled` | `undefined \| false \| true` | Disable the composer entirely (non-interactive). |
| `loading` | `loading` | `undefined \| false \| true` | Show a loading/streaming state and block submit. |
| `maxHeight` | `max-height` | `undefined \| number \| string` | Maximum height in px before the content scrolls. Default 240. |
| `submitOnEnter` | `submit-on-enter` | `undefined \| false \| true` | Whether pressing Enter (without Shift) submits. Default true. |
| `triggers` | — | `undefined \| { char: string; kind: string; items?: undefined \| { id: string; label: string; icon?: undefined \| string; description?: undefined \| string; group?: undefined \| string; kind?: undefined \| string; promptText?: undefined \| string; data?: undefined \| Record<string, unknown> }[] }[]` | Trigger definitions. Set as a JS property. |
| `highlights` | — | `undefined \| (string \| { pattern: string; flags?: undefined \| string; class?: undefined \| string })[]` | Keyword highlight rules. Set as a JS property. |
| `kindIcons` | — | `undefined \| Record<string, 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. |

**Events** (non-bubbling `CustomEvent`s — listen directly on the element):

| Event | `detail` type | Description |
|---|---|---|
| `kai-blur` | `CustomEvent<{ originalEvent: FocusEvent }>` | The composer lost focus. |
| `kai-entity-add` | `CustomEvent<{ entity: { kind: string; id: string; label: string; icon?: undefined \| string; promptText?: undefined \| string; data?: undefined \| Record<string, unknown> } }>` | An entity pill was inserted into the composer. |
| `kai-entity-remove` | `CustomEvent<{ entity: { kind: string; id: string; label: string; icon?: undefined \| string; promptText?: undefined \| string; data?: undefined \| Record<string, unknown> } }>` | An entity pill was deleted from the composer. |
| `kai-focus` | `CustomEvent<{ originalEvent: FocusEvent }>` | 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.) |
| `kai-submit` | `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> }[] }>` | The user submitted the composer (Enter or programmatic submit). Note the detail carries no `attachments`; `<kai-composer>` is the bare editing surface: no send button, toolbar, or attachments. For a drop-in composer row with all three, reach for `<kai-prompt-input>`, which is built on this. |
| `kai-trigger` | `CustomEvent<{ char: string; query: string; rect: DOMRect }>` | A trigger character was detected at the caret (e.g. `/` or `@`). |
| `kai-trigger-close` | `CustomEvent<Record<string, never>>` | The active trigger was dismissed (Escape, space, or outside click). |
| `kai-value-change` | `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> }[] }>` | The content changed (fires on every input event). |

**Methods** (call on the element instance: `document.querySelector('kai-composer').focus(…)`):

| Method | Signature | Description |
|---|---|---|
| `focus` | `(options?: FocusOptions): void` | 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. |
| `blur` | `(): void` | Blur the editable element. |
| `clear` | `(): void` | Empty the composer to a blank doc (resets the internal value + history baseline; fires kai-value-change). |
| `send` | `(): 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. |
| `insertEntity` | `(entity: EntityRef): void` | Insert an atomic entity pill (skill/agent/plugin) at the caret without typing a trigger (fires kai-entity-add). |

---

### `kai-confirm` / `Confirm`

**Properties** (every element also accepts `theme="light|dark|auto"`; only scalar props work as HTML attributes):

| Property | Attribute | Type | Description |
|---|---|---|---|
| `theme` | `theme` | `"light" \| "dark" \| "auto"` | Color mode (`auto` follows prefers-color-scheme). |
| `data` | — | `undefined \| { heading?: undefined \| string; body?: undefined \| string; tone?: undefined \| "default" \| "warning" \| "danger"; actions: { id: string; label: string; style?: undefined \| "primary" \| "default" \| "destructive"; payload?: unknown; default?: undefined \| false \| true }[]; dismissible?: undefined \| false \| true }` | 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. |
| `cardId` | `card-id` | `undefined \| string` | Stable card id correlating every emitted CardEvent. Attribute: `card-id`. |
| `heading` | `heading` | `undefined \| string` | Heading rendered in the card chrome (= CardEnvelope.title). Attribute: `heading`. |
| `autofocus` | `autofocus` | `undefined \| false \| true` | Focus the default action on mount (off by default, so nothing steals focus). Attribute: `autofocus`. |
| `resolution` | — | `undefined \| Record<string, unknown>` | Set when the user resolved this card; renders the read-only view. Property: `el.resolution = { kind:'action', action:'…' }`. |

_No events._

**Methods** (call on the element instance: `document.querySelector('kai-confirm').focus(…)`):

| Method | Signature | Description |
|---|---|---|
| `focus` | `(options?: FocusOptions): void` | Focus the default action button (or the first action if none is default). The same target `autofocus` focuses on mount, but on demand. |
| `confirm` | `(actionId?: string): 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. |
| `dismiss` | `(): void` | Trigger the dismiss path: emits `dismiss` on kai-card and optimistically collapses the card to its re-openable stub. |
| `reopen` | `(): void` | Re-open a dismissed card from its stub: emits `reopen` on kai-card. |

---

### `kai-context` / `Context`

**Properties** (every element also accepts `theme="light|dark|auto"`; only scalar props work as HTML attributes):

| Property | Attribute | Type | Description |
|---|---|---|---|
| `theme` | `theme` | `"light" \| "dark" \| "auto"` | Color mode (`auto` follows prefers-color-scheme). |
| `context` | — | `undefined \| { usedTokens: number; maxTokens: number; inputTokens?: undefined \| number; outputTokens?: undefined \| number; reasoningTokens?: undefined \| number; cacheTokens?: undefined \| number; estimatedCost?: undefined \| number }` | Token-usage data. Set as a JS property. |
| `warnThreshold` | `warn-threshold` | `undefined \| number` | Fraction (0–1) above which the meter turns yellow. Defaults to `0.7` (70%). |
| `dangerThreshold` | `danger-threshold` | `undefined \| number` | Fraction (0–1) above which the meter turns red. Defaults to `0.9` (90%). |

**Events** (non-bubbling `CustomEvent`s — listen directly on the element):

| Event | `detail` type | Description |
|---|---|---|
| `kai-threshold-change` | `CustomEvent<{ level: "ok" \| "warn" \| "danger" }>` | Fires when the computed severity level changes (ok → warn → danger or back). `detail.level` is `'ok'`, `'warn'`, or `'danger'`. |

**Styleable parts** (restyle from outside via `kai-context::part(name)`):

| Part | Description |
|---|---|
| `::part(track)` | The usage meter track inside the hover-card breakdown. Carries `role="progressbar"` and is in the DOM only while the card is open. Restyle its height, radius, or background from outside. — `kai-context::part(track) { height: 0.5rem }` |
| `::part(fill)` | The used-tokens portion of that meter. Its width follows `usedTokens / maxTokens`; its default color is the severity hue picked by `warnThreshold` / `dangerThreshold`, so recoloring it from outside replaces that signal. — `kai-context::part(fill) { background: var(--color-tool-blue) }` |

---

### `kai-conversation-item` / `ConversationItem`

**Properties** (every element also accepts `theme="light|dark|auto"`; only scalar props work as HTML attributes):

| Property | Attribute | Type | Description |
|---|---|---|---|
| `theme` | `theme` | `"light" \| "dark" \| "auto"` | Color mode (`auto` follows prefers-color-scheme). |
| `conversationId` | `conversation-id` | `undefined \| string` | The row's identity: the `conversation-id` attribute (host `id` is the fallback). Inside `<kai-conversations>` it is handed to the container's selection contract (`kai-conversation-select`); standalone it is the `id` in this element's own `kai-select` detail. |
| `active` | `active` | `undefined \| false \| true` | Selected state. Reflected as `aria-current` on the row body and a `data-active` styling hook on the row; inside a container the container drives it from its `activeId`, standalone you set it yourself. |
| `compact` | `compact` | `undefined \| false \| true` | Dense single-line row padding. |
| `density` | `density` | `undefined \| "default" \| "compact" \| "panel"` | Row density: `default`, `compact` (same as the `compact` flag), or `panel`, the widget-panel presentation matching the facade panel's measured row box (12px/10px padding, a 40px single-line row). Previously that box was a private interior class a composition could only approximate by smuggling padding through slotted spans (2026-08-31 composition spike, phase 3 round 3). An explicit density wins over `compact`. |
| `unread` | `unread` | `undefined \| false \| true` | Show the unread indicator dot at the row's trailing edge, inside the activation surface and before the `menu` region, with a screen-reader "Unread" label. Drive it from `isConversationUnread` (exported from the package root and from `dist/stores.js`). |

**Events** (non-bubbling `CustomEvent`s — listen directly on the element):

| Event | `detail` type | Description |
|---|---|---|
| `kai-select` | `CustomEvent<{ id: string }>` | STANDALONE activation only: the row was activated (click, Enter or Space on its body) while the item is NOT a direct child of `<kai-conversations>`. `id` is the row's identity: the `conversation-id` attribute, else the host `id`. Inside a container this never fires: activation surfaces once, as `kai-conversation-select` on the container. |

**Slots** (project your own markup via `slot="name"` on a light-DOM child):

| Slot | Mode | Description |
|---|---|---|
| _(default)_ | inject | The row title. `leading`, `meta` and `menu` are the named regions around it. |
| `leading` | inject | Leading region before the title (an icon or avatar). |
| `meta` | inject | Meta region under the title (a timestamp or status line). |
| `menu` | inject | Your own row menu (a popover trigger). Never selects the row. |

**Styleable parts** (restyle from outside via `kai-conversation-item::part(name)`):

| Part | Description |
|---|---|
| `::part(body)` | The activation surface inside the row (button role; carries aria-current and the roving tabindex). The focus ring paints here. — `kai-conversation-item::part(body) { outline-offset: 2px }` |
| `::part(row)` | The whole row surface. Carries `data-active` while selected. — `kai-conversation-item::part(row) { border-radius: 0.5rem }` |
| `::part(title)` | The title line (the default slot renders inside it). — `kai-conversation-item::part(title) { font-weight: 600 }` |
| `::part(unread)` | The unread indicator dot at the body's trailing edge, before the `menu` region (renders only while the `unread` flag is set; a screen-reader "Unread" label rides along). — `kai-conversation-item::part(unread) { background: var(--color-primary) }` |
| `::part(leading)` | Leading region before the title (an icon or avatar). |
| `::part(meta)` | Meta region under the title (a timestamp or status line). |
| `::part(menu)` | Your own row menu (a popover trigger). Never selects the row. |

---

### `kai-conversations` / `Conversations`

**Properties** (every element also accepts `theme="light|dark|auto"`; only scalar props work as HTML attributes):

| Property | Attribute | Type | Description |
|---|---|---|---|
| `theme` | `theme` | `"light" \| "dark" \| "auto"` | Color mode (`auto` follows prefers-color-scheme). |
| `groups` | — | `undefined \| { id: string; userId?: undefined \| string; teamId?: undefined \| string; name: string; sortOrder: number; createdAt: string }[]` | 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. |
| `conversations` | — | `undefined \| { id: string; title: string; groupId?: undefined \| string; scope?: undefined \| { type: "document" \| "collection"; documentId?: undefined \| string; filters?: undefined \| { tags?: undefined \| string[]; authors?: undefined \| string[]; contentType?: undefined \| "transcript" \| "markdown"; dateRange?: undefined \| { from: string; to: string } } }; messageCount: number; lastMessageAt?: undefined \| string; updatedAt: string; trailing?: undefined \| string; lastReadAt?: undefined \| string }[]` | Every conversation the list renders, flat. Each one is filed under the group whose `id` equals its `groupId`; one with no `groupId`, or with a `groupId` matching no entry in `groups`, falls into a trailing "Ungrouped" section, so nothing you pass in is ever dropped. There is no recency bucketing. Set as a JS property. Omit to supply them as `<kai-conversation>` light-DOM children instead, or for the empty state. A search query that matches nothing shows a visible "No conversations match your search" state, distinct from the zero-conversations empty state. Slotted `<kai-conversation-item>` children switch the list into item mode instead: your own rows win and this array is not rendered. |
| `activeId` | `active-id` | `undefined \| string` | The id of the currently-open conversation, highlighted in the list. |
| `collapsed` | `collapsed` | `undefined \| false \| true` | 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. |
| `defaultCollapsed` | `default-collapsed` | `undefined \| false \| true` | Initial collapsed state when uncontrolled (default false). Use the `default-collapsed` attribute to start collapsed in plain HTML. |
| `compact` | `compact` | `undefined \| false \| true` | Dense single-line rows (a leading dot + title, no message count). |
| `density` | `density` | `undefined \| "default" \| "compact" \| "panel"` | Row density for the data rows: `default`, `compact` (same as the `compact` flag), or `panel`, the widget-panel presentation matching the facade panel's measured row box (12px/10px padding, a 40px single-line row with a right-aligned relative time and an optional preview line carrying the unread dot). An explicit density wins over `compact`. Item mode is unaffected: slotted `<kai-conversation-item>` rows carry their own `density` attribute. |
| `searchable` | `searchable` | `undefined \| false \| true` | Show the built-in search box above the list. Default `true`. Set `searchable="false"` (or `el.searchable = false`) to hide it: the widget-box case, where the facade's own list view renders no search and a fine-grain composition previously had no way to match it (2026-08-31 composition spike, phase 3 round 2). Same default-true flag convention as `<kai-prompt-input attach>`: `<kai-conversations searchable>` and omitting it are both ON. Hidden, the `focus()`/`clear()` methods reach no input and `kai-search` never fires. |

**Events** (non-bubbling `CustomEvent`s — listen directly on the element):

| Event | `detail` type | Description |
|---|---|---|
| `kai-collapse-toggle` | `CustomEvent<{ collapsed: false \| true }>` | The rail was collapsed or expanded (via the toggle, the reopen button, or a `collapse()`/`expand()`/`toggle()` call). |
| `kai-conversation-select` | `CustomEvent<{ id: string }>` | A conversation was selected. The selection event in BOTH modes: a batteries data row, or an activated `<kai-conversation-item>` child (click, Enter or Space). |
| `kai-new-chat` | `CustomEvent<Record<string, never>>` | The "New chat" button was clicked. |
| `kai-search` | `CustomEvent<{ query: string }>` | 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. |
| `kai-toggle-sidebar` | `CustomEvent<Record<string, never>>` | The sidebar toggle was clicked. |

**Methods** (call on the element instance: `document.querySelector('kai-conversations').focus(…)`):

| Method | Signature | Description |
|---|---|---|
| `focus` | `(options?: FocusOptions): void` | Focus the built-in search input inside the shadow root. |
| `clear` | `(): void` | Clear the internal search query (resets the list filter) and fire kai-search with an empty string. |
| `select` | `(id: string): void` | Programmatically select a conversation by id. The mirror of the kai-conversation-select event (a convenience over driving `activeId`). |
| `collapse` | `(): void` | Collapse the rail to its floating reopen button (fires `kai-collapse-toggle`). |
| `expand` | `(): void` | Expand the rail back to the full list (fires `kai-collapse-toggle`). |
| `toggle` | `(): void` | Toggle the rail collapsed/expanded (fires `kai-collapse-toggle`). |

**Slots** (project your own markup via `slot="name"` on a light-DOM child):

| Slot | Mode | Description |
|---|---|---|
| _(default)_ | inject | Your own `<kai-conversation-item>` rows (item mode: the consumer-owned loop). Data rows do not render while any are present. |
| `header` | replace | Full custom title bar; replaces the built-in toggle / "Chats" / New-chat row. |
| `empty` | replace | Custom zero-state shown when there are no conversations; replaces the built-in "No conversations yet". |
| `footer` | inject | A row below the list: account, settings, or usage. |

**Declarative children** (compose these in light DOM instead of setting the JS property):

| Child element | Attributes | Text content | Notes |
|---|---|---|---|
| `<kai-conversation>` | `group-id`, `id` | yes | Parse a single light-DOM `<kai-conversation>` element into a `ConversationSummary`. Attribute mapping: - `id` → ConversationSummary.id - `group-id` → ConversationSummary.groupId (optional) - textContent → ConversationSummary.title Fields not expressible as HTML attributes are NOT fabricated: the optional `scope` and `lastMessageAt` stay absent, and the required `messageCount`/`updatedAt` get honest defaults — zero messages, and an empty `updatedAt` from which no trailing relative time is derived (the epoch it used to fabricate rendered a bogus "many days ago" on every declarative row). |

**Styleable parts** (restyle from outside via `kai-conversations::part(name)`):

| Part | Description |
|---|---|
| `::part(trailing)` | The right-aligned trailing text on each conversation row (a count, status, or relative time). Set it per item via the `trailing` field; otherwise a short auto relative time is derived from `updatedAt`. Recolor or resize it from outside. — `kai-conversations::part(trailing) { color: var(--color-primary); font-variant-numeric: tabular-nums }` |
| `::part(items)` | The item-mode listbox region wrapping your slotted `<kai-conversation-item>` children. — `kai-conversations::part(items) { gap: 2px }` |

---

### `kai-dialog` / `Dialog`

**Properties** (every element also accepts `theme="light|dark|auto"`; only scalar props work as HTML attributes):

| Property | Attribute | Type | Description |
|---|---|---|---|
| `theme` | `theme` | `"light" \| "dark" \| "auto"` | Color mode (`auto` follows prefers-color-scheme). |
| `open` | `open` | `undefined \| false \| true` | 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`. |
| `defaultOpen` | `default-open` | `undefined \| false \| true` | Initial open state on mount (uncontrolled seed). |
| `label` | `label` | `undefined \| string` | Accessible name for the modal, used when no `header` slot is projected: `<kai-dialog label="Delete workspace">`. A projected `header` WINS over this (it becomes `aria-labelledby`), because ARIA resolves `aria-labelledby` ahead of `aria-label` and the visible heading is the name both a sighted and a screen-reader user can be talked through. Defaults to `Dialog` so a modal is never nameless. |

**Events** (non-bubbling `CustomEvent`s — listen directly on the element):

| Event | `detail` type | Description |
|---|---|---|
| `kai-open-change` | `CustomEvent<{ open: false \| true }>` | The dialog opened or closed (Escape, backdrop click, a driven `open`, or a method). |

**Methods** (call on the element instance: `document.querySelector('kai-dialog').show()`):

| Method | Signature | Description |
|---|---|---|
| `show` | `(): void` | Open it programmatically (no-op while disabled). |
| `hide` | `(): void` | Close it programmatically. |
| `toggle` | `(): void` | Flip the open state (closes while disabled). |
| `focus` | `(options?: FocusOptions): void` | Move focus to the dialog panel (no-op while closed). |

**Slots** (project your own markup via `slot="name"` on a light-DOM child):

| Slot | Mode | Description |
|---|---|---|
| _(default)_ | inject | The dialog body, between the `header` and `footer` slots. |
| `header` | inject | Optional title region at the top of the panel. |
| `footer` | inject | Optional actions region at the bottom of the panel. |

**Styleable parts** (restyle from outside via `kai-dialog::part(name)`):

| Part | Description |
|---|---|
| `::part(backdrop)` | The full-area scrim behind the panel. Restyle its color/blur. — `kai-dialog::part(backdrop) { background: rgb(0 0 0 / 0.6) }` |
| `::part(panel)` | The centered modal panel. Restyle width, radius, padding. — `kai-dialog::part(panel) { max-width: 32rem }` |
| `::part(body)` | The scrolling content region (the default slot). — `kai-dialog::part(body) { padding: 1.25rem }` |
| `::part(header)` | Optional title region at the top of the panel. |
| `::part(footer)` | Optional actions region at the bottom of the panel. |

---

### `kai-dock` / `Dock`

**Properties** (every element also accepts `theme="light|dark|auto"`; only scalar props work as HTML attributes):

| Property | Attribute | Type | Description |
|---|---|---|---|
| `theme` | `theme` | `"light" \| "dark" \| "auto"` | Color mode (`auto` follows prefers-color-scheme). |
| `open` | `open` | `undefined \| false \| true` | Drive/observe open state (Shoelace-style: settable + reflected to the `open` attribute; the element still self-manages on the launcher and Escape). Set `el.open = true`, or `<kai-dock open>`; listen for `kai-open-change`. |
| `defaultOpen` | `default-open` | `undefined \| false \| true` | Initial open state on mount (uncontrolled seed). |
| `position` | `position` | `undefined \| "bottom-end" \| "bottom-start" \| "top-end" \| "top-start"` | Which corner the dock sits in. Logical, so `-end` follows the writing direction and an RTL page docks on the left. Attribute: `position`. |
| `label` | `label` | `undefined \| string` | The widget's NAME. Derives the panel's accessible name and both launcher names (`Open ${label}` / `Close ${label}`). Defaults to `Chat`. |
| `openLabel` | `open-label` | `undefined \| string` | i18n override for the launcher's name while closed (default `Open ${label}`). |
| `closeLabel` | `close-label` | `undefined \| string` | i18n override for the launcher's name while open (default `Close ${label}`). |
| `unread` | `unread` | `undefined \| false \| true` | Show the unread dot. YOURS: it renders only while closed, and the dock never writes it back. Clear it in your `kai-open-change` handler. |
| `disabled` | `disabled` | `undefined \| false \| true` | Disable the launcher; `show()` and `toggle()` are gated on it. |
| `hideClose` | `hide-close` | `undefined \| false \| true` | Suppress the dock's own built-in mobile close X. Set this when your slotted panel content supplies its own close affordance (e.g. a `<kai-chat slot="header-end">` close button), otherwise the two stack. TRADEOFF: the mobile panel reserves a padding band above its content so the built-in X never paints over slotted content; that band stays reserved unless you set this true, so only set it once your own control is actually in place. Attribute: `hide-close`. |
| `focusOnOpen` | `focus-on-open` | `undefined \| "content" \| "panel" \| "none"` | Where focus lands on open: `content` (default, the first element you slotted), `panel`, or `none`. Attribute: `focus-on-open`. |

**Events** (non-bubbling `CustomEvent`s — listen directly on the element):

| Event | `detail` type | Description |
|---|---|---|
| `kai-open-change` | `CustomEvent<{ open: false \| true }>` | The dock opened or closed (the launcher, Escape, a driven `open`, or a method). |

**Methods** (call on the element instance: `document.querySelector('kai-dock').show()`):

| Method | Signature | Description |
|---|---|---|
| `show` | `(): void` | Open it programmatically (no-op while disabled). |
| `hide` | `(): void` | Close it programmatically. |
| `toggle` | `(): void` | Flip the open state (closes while disabled). |
| `focus` | `(options?: FocusOptions): void` | Move focus to the panel while open, or to the launcher while closed. |

**Slots** (project your own markup via `slot="name"` on a light-DOM child):

| Slot | Mode | Description |
|---|---|---|
| _(default)_ | inject | The panel body, the same region as `slot="panel"`. |
| `panel` | replace | The panel body. ANY element: a `<kai-chat>`, a form, your own component. The dock never reads or types it, and the default slot is the same region. |
| `launcher` | inject | Content inside the built-in button while CLOSED; defaults to a chat glyph. Text works as well as an icon: the button keeps its height and grows sideways into a pill, so a label like "Support" is not clipped. The BUTTON is never slotted away, because it owns aria-expanded, aria-controls, the toggle wiring and the focus return. |
| `launcher-open` | inject | Content inside the button while OPEN; defaults to a ✕. Fill only `launcher` and that glyph stays while open rather than morphing into a built-in that clashes with it. |

**Styleable parts** (restyle from outside via `kai-dock::part(name)`):

| Part | Description |
|---|---|
| `::part(launcher)` | The launcher button pinned to the corner: a disc by default, a pill once you slot a text label. Restyle its surface or shadow; --kai-dock-launcher-size sets its height and its minimum width. — `kai-dock::part(launcher) { background: var(--color-info) }` |
| `::part(badge)` | The unread dot on the launcher, rendered only while closed and only when `unread` is set. Restyle its color or size. — `kai-dock::part(badge) { background: var(--color-success) }` |
| `::part(panel)` | The panel body. ANY element: a `<kai-chat>`, a form, your own component. The dock never reads or types it, and the default slot is the same region. |

---

### `kai-dropdown` / `Dropdown`

**Properties** (every element also accepts `theme="light|dark|auto"`; only scalar props work as HTML attributes):

| Property | Attribute | Type | Description |
|---|---|---|---|
| `theme` | `theme` | `"light" \| "dark" \| "auto"` | Color mode (`auto` follows prefers-color-scheme). |
| `triggerIcon` | `trigger-icon` | `undefined \| string` | Built-in trigger: leading icon (a named icon like `"plus"`, an image URL/data-URI, or text). A slotted `slot="trigger"` overrides it. |
| `triggerLabel` | `trigger-label` | `undefined \| string` | Built-in trigger: a text label. This is the trigger's VISIBLE text, so it is also its accessible name, and `label` does not override it: an accessible name that does not contain the visible text is unreachable by speech input (WCAG 2.5.3, Label in Name). Same rule `kai-menu` follows. |
| `triggerIconTrailing` | `trigger-icon-trailing` | `undefined \| string` | Built-in trigger: a trailing icon (e.g. `"chevron-down"` for a select look). |
| `label` | `label` | `undefined \| string` | Accessible name for a trigger with no visible label. Ignored when `triggerLabel` is set, which is already the visible name. It DOES name a slotted `slot="trigger"`, which is VISUAL content with the name supplied separately: the same two-slot distinction `kai-menu` documents. |
| `full` | `full` | `undefined \| false \| true` | Stretch the trigger to the full width of its container (a block row). Attribute: `full`. |
| `open` | `open` | `undefined \| false \| true` | 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-dropdown open>`; listen for `kai-open-change`. |
| `defaultOpen` | `default-open` | `undefined \| false \| true` | Initial open state on mount (uncontrolled seed). |
| `disabled` | `disabled` | `undefined \| false \| true` | Disable the trigger: click/keyboard and `show()` no longer open the menu. |

**Events** (non-bubbling `CustomEvent`s — listen directly on the element):

| Event | `detail` type | Description |
|---|---|---|
| `kai-open-change` | `CustomEvent<{ open: false \| true }>` | The menu opened or closed (click, keyboard, Escape, outside-click, or a method). |

**Methods** (call on the element instance: `document.querySelector('kai-dropdown').show()`):

| Method | Signature | Description |
|---|---|---|
| `show` | `(): void` | Open it programmatically (no-op while disabled). |
| `hide` | `(): void` | Close it programmatically. |
| `toggle` | `(): void` | Flip the open state (closes while disabled). |

**Slots** (project your own markup via `slot="name"` on a light-DOM child):

| Slot | Mode | Description |
|---|---|---|
| _(default)_ | inject | The menu body: your own rows. Give each `role="menuitem"`. The control that opens it is the `trigger` slot. |
| `trigger` | replace | Visual content of the trigger button (an icon, text, an `<svg>`). Replaces the built-in trigger* content; name it with `label`. |

---

### `kai-editable-label` / `EditableLabel`

**Properties** (every element also accepts `theme="light|dark|auto"`; only scalar props work as HTML attributes):

| Property | Attribute | Type | Description |
|---|---|---|---|
| `theme` | `theme` | `"light" \| "dark" \| "auto"` | Color mode (`auto` follows prefers-color-scheme). |
| `value` | `value` | `undefined \| string` | The label text. Settable and reflected to the `value` attribute. Read `el.value` for live state. |
| `editing` | `editing` | `undefined \| false \| true` | Controlled edit state. `el.editing = true` opens the field; reflected to the `editing` attribute. |
| `placeholder` | `placeholder` | `undefined \| string` | Placeholder shown while editing / when the value is empty. |
| `disabled` | `disabled` | `undefined \| false \| true` | Disable entering edit mode. |

**Events** (non-bubbling `CustomEvent`s — listen directly on the element):

| Event | `detail` type | Description |
|---|---|---|
| `kai-cancel` | `CustomEvent<Record<string, never>>` | Edit was cancelled (Esc); the text is restored. |
| `kai-rename` | `CustomEvent<{ value: string }>` | Committed a changed value (Enter / blur). |

**Methods** (call on the element instance: `document.querySelector('kai-editable-label').edit()`):

| Method | Signature | Description |
|---|---|---|
| `edit` | `(): void` | 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. |
| `commit` | `(): 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. |
| `cancel` | `(): 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. |

**Styleable parts** (restyle from outside via `kai-editable-label::part(name)`):

| Part | Description |
|---|---|
| `::part(text)` | The read-mode label text. Restyle its typography; it swaps to the input on edit. — `kai-editable-label::part(text) { font-weight: 600 }` |
| `::part(input)` | The edit-mode input (the composed kai-input field). — `kai-editable-label::part(input) { font: inherit }` |

---

### `kai-embed` / `Embed`

**Properties** (every element also accepts `theme="light|dark|auto"`; only scalar props work as HTML attributes):

| Property | Attribute | Type | Description |
|---|---|---|---|
| `theme` | `theme` | `"light" \| "dark" \| "auto"` | Color mode (`auto` follows prefers-color-scheme). |
| `cardId` | `card-id` | `undefined \| string` | Stable card id correlating every emitted event. Set as an attribute or property. |
| `data` | — | `undefined \| { provider: "youtube" \| "vimeo" \| "generic"; id?: undefined \| string; url?: undefined \| string; title?: undefined \| string; poster?: undefined \| string; start?: undefined \| number; aspectRatio?: undefined \| "16:9" \| "4:3" \| "1:1" \| "9:16" }` | The embed payload (provider + id/url + options). Set as a JS **property** (object). |

_No events._

---

### `kai-empty` / `Empty`

**Properties** (every element also accepts `theme="light|dark|auto"`; only scalar props work as HTML attributes):

| Property | Attribute | Type | Description |
|---|---|---|---|
| `theme` | `theme` | `"light" \| "dark" \| "auto"` | Color mode (`auto` follows prefers-color-scheme). |
| `emptyTitle` | `empty-title` | `undefined \| string` | Title text. Attribute: `empty-title` (`title` is a global HTML attribute). |
| `description` | `description` | `undefined \| string` | Description text. |

_No events._

**Slots** (project your own markup via `slot="name"` on a light-DOM child):

| Slot | Mode | Description |
|---|---|---|
| _(default)_ | inject | The empty-state body below the title/description, usually the call to action. |
| `media` | replace | The leading illustration or icon above the title (any inline SVG or <img>). Replaces the built-in media box. |

---

### `kai-feedback-bar` / `FeedbackBar`

**Properties** (every element also accepts `theme="light|dark|auto"`; only scalar props work as HTML attributes):

| Property | Attribute | Type | Description |
|---|---|---|---|
| `theme` | `theme` | `"light" \| "dark" \| "auto"` | Color mode (`auto` follows prefers-color-scheme). |
| `barTitle` | `bar-title` | `undefined \| string` | The banner label (e.g. "Was this helpful?"). Attribute: `bar-title` (`title` is avoided because it is a global HTML attribute). |
| `collectDetail` | `collect-detail` | `undefined \| false \| true` | When set, a not-helpful vote opens an optional detail form before the thank-you confirmation. Attribute: `collect-detail`. |
| `categories` | — | `undefined \| string[]` | Optional category chips for the detail form. Set as a JS property (array). |
| `detailTitle` | `detail-title` | `undefined \| string` | Heading for the detail form. Attribute: `detail-title`. |
| `detailPlaceholder` | `detail-placeholder` | `undefined \| string` | Placeholder for the detail comment box. Attribute: `detail-placeholder`. |
| `submitLabel` | `submit-label` | `undefined \| string` | Submit button label in the detail form. Attribute: `submit-label`. |
| `thanksMessage` | `thanks-message` | `undefined \| string` | Confirmation copy shown after a vote/submit. Attribute: `thanks-message`. |

**Events** (non-bubbling `CustomEvent`s — listen directly on the element):

| Event | `detail` type | Description |
|---|---|---|
| `kai-close` | `CustomEvent` | The user dismissed the banner. |
| `kai-feedback` | `CustomEvent<{ value: "helpful" \| "not-helpful" }>` | The user rated the response. `value` is `'helpful'` or `'not-helpful'`. |
| `kai-feedback-detail` | `CustomEvent<{ value: "helpful" \| "not-helpful"; category?: undefined \| string; comment?: undefined \| string }>` | The user submitted the optional detail form (`collect-detail`). |

---

### `kai-file-tree` / `FileTree`

**Properties** (every element also accepts `theme="light|dark|auto"`; only scalar props work as HTML attributes):

| Property | Attribute | Type | Description |
|---|---|---|---|
| `theme` | `theme` | `"light" \| "dark" \| "auto"` | Color mode (`auto` follows prefers-color-scheme). |
| `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" }[]` | The files to render. Set as a JS property (array of `{ path, url?, code?, language?, type?, additions?, deletions?, status? }`). |
| `activeFile` | `active-file` | `undefined \| string` | Selected file path, highlighted in the tree. |
| `defaultExpanded` | — | `undefined \| string[]` | Folder paths expanded initially. Omit to start with all folders open. |
| `summary` | `summary` | `undefined \| false \| true` | Show a changed-files summary header (file count + summed `+/-` + Collapse-all). Attribute: `summary`. Off by default. |

**Events** (non-bubbling `CustomEvent`s — listen directly on the element):

| Event | `detail` type | Description |
|---|---|---|
| `kai-select` | `CustomEvent<{ path: string }>` | Fired when a file is selected. `detail.path` = the file's path. |

**Styleable parts** (restyle from outside via `kai-file-tree::part(name)`):

| Part | Description |
|---|---|
| `::part(summary)` | The changed-files summary header (the file count, the summed +additions/-deletions, and the Collapse-all/Expand-all toggle). Rendered only when the `summary` attribute is set; restyle or hide it from outside. — `kai-file-tree::part(summary) { border-bottom: none; padding-block: 0.5rem }` |
| `::part(status)` | The per-row change-status letter (A/M/D/R/U), shown when a file carries a `status`. Colored with the conventional VCS tool hues; restyle from outside. — `kai-file-tree::part(status) { font-weight: 700 }` |
| `::part(stat-additions)` | The trailing `+N` additions stat on a file row (success/green tool hue, tabular-nums). Shown only when a file carries `additions`. — `kai-file-tree::part(stat-additions) { color: var(--color-tool-green) }` |
| `::part(stat-deletions)` | The trailing `-N` deletions stat on a file row (error/red tool hue, tabular-nums). Shown only when a file carries `deletions`. — `kai-file-tree::part(stat-deletions) { color: var(--color-tool-red) }` |

---

### `kai-file-upload` / `FileUpload`

**Properties** (every element also accepts `theme="light|dark|auto"`; only scalar props work as HTML attributes):

| Property | Attribute | Type | Description |
|---|---|---|---|
| `theme` | `theme` | `"light" \| "dark" \| "auto"` | Color mode (`auto` follows prefers-color-scheme). |
| `multiple` | `multiple` | `undefined \| false \| true` | Allow selecting multiple files (default true). |
| `accept` | `accept` | `undefined \| string` | `accept` attribute for the file picker (e.g. `image/*`). |
| `disabled` | `disabled` | `undefined \| false \| true` | Disable the dropzone: no clicking, no drag-and-drop. |
| `label` | `label` | `undefined \| string` | Default dropzone label (overridable via the default slot). |

**Events** (non-bubbling `CustomEvent`s — listen directly on the element):

| Event | `detail` type | Description |
|---|---|---|
| `kai-files-added` | `CustomEvent<{ files: File[] }>` | Files were picked or dropped. |

**Slots** (project your own markup via `slot="name"` on a light-DOM child):

| Slot | Mode | Description |
|---|---|---|
| _(default)_ | inject | Custom dropzone content, replacing the default label (the `label` prop is the fallback). |

---

### `kai-form` / `Form`

**Properties** (every element also accepts `theme="light|dark|auto"`; only scalar props work as HTML attributes):

| Property | Attribute | Type | Description |
|---|---|---|---|
| `theme` | `theme` | `"light" \| "dark" \| "auto"` | Color mode (`auto` follows prefers-color-scheme). |
| `data` | — | `undefined \| { type: "object"; title?: undefined \| string; description?: undefined \| string; required?: undefined \| string[]; properties: Record<string, { type: "string" \| "number" \| "integer" \| "boolean" \| "array" \| "object"; title?: undefined \| string; description?: undefined \| string; default?: unknown; enum?: undefined \| unknown[]; format?: undefined \| "email" \| "uri" \| "url" \| "date" \| "date-time" \| "time"; minimum?: undefined \| number; maximum?: undefined \| number; minLength?: undefined \| number; maxLength?: undefined \| number; pattern?: undefined \| string; minItems?: undefined \| number; maxItems?: undefined \| number; items?: undefined \| Record<string, unknown> \| { enum: unknown[] }; properties?: undefined \| Record<string, Record<string, unknown>>; required?: undefined \| string[]; readOnly?: undefined \| false \| true; "x-kai-widget"?: undefined \| "textarea" \| "slider" \| "rating" \| "radio" \| "select" \| "checkbox" \| "password" \| "switch"; "x-kai-placeholder"?: undefined \| string; "x-kai-step"?: undefined \| number; "x-kai-format"?: undefined \| "tel" \| "ssn" \| "credit-card" \| "custom"; "x-kai-mask"?: undefined \| string; "x-kai-mask-guide"?: undefined \| string }>; "x-kai-order"?: undefined \| string[]; "x-kai-inlineMax"?: undefined \| number; "x-kai-submitLabel"?: undefined \| string; "x-kai-dismissible"?: undefined \| false \| true; "x-kai-actions"?: undefined \| { id: string; label: string; variant?: undefined \| "default" \| "ghost" \| "outline" }[] }` | 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. |
| `cardId` | `card-id` | `undefined \| string` | Stable card id correlating every emitted CardEvent. Attribute: `card-id`. |
| `heading` | `heading` | `undefined \| string` | Heading rendered in the card chrome (= CardEnvelope.title). Attribute: `heading`. |
| `resolution` | — | `undefined \| Record<string, unknown>` | Set when the user resolved this card; renders the read-only view. Property: `el.resolution = { kind:'submit', data:{…} }`. |
| `values` | — | `undefined \| Record<string, unknown>` | Controlled field values (JS property). When set, it wins over local edits. |
| `defaultValues` | — | `undefined \| Record<string, unknown>` | Initial values overlaying the schema defaults (uncontrolled seed; JS property). |
| `disabled` | `disabled` | `undefined \| false \| true` | Disable all fields + submit. Attribute: `disabled`. |

**Events** (non-bubbling `CustomEvent`s — listen directly on the element):

| Event | `detail` type | Description |
|---|---|---|
| `kai-values-change` | `CustomEvent<{ values: Record<string, unknown>; valid: false \| true }>` | The form's values changed on input. Carries the current coerced values + validity. |

**Methods** (call on the element instance: `document.querySelector('kai-form').focus(…)`):

| Method | Signature | Description |
|---|---|---|
| `focus` | `(options?: FocusOptions): void` | Focus the first control, or the first INVALID control after a failed validation. |
| `send` | `(): void` | Validate + submit programmatically: focus the first invalid field on failure, else emit the `submit` CardEvent and resolve. Named `send`, not `submit`. |
| `validate` | `(): void` | Run client-side validation now and return `{ valid, errors? }` WITHOUT submitting. |
| `reset` | `(): void` | Re-seed the form from each field's `default` and clear errors. |
| `dismiss` | `(): void` | Trigger the dismiss path (emit `dismiss` + collapse to the re-openable stub). |
| `reopen` | `(): void` | Re-open a dismissed card from its stub (emit `reopen`). |

---

### `kai-hover-card` / `HoverCard`

**Properties** (every element also accepts `theme="light|dark|auto"`; only scalar props work as HTML attributes):

| Property | Attribute | Type | Description |
|---|---|---|---|
| `theme` | `theme` | `"light" \| "dark" \| "auto"` | Color mode (`auto` follows prefers-color-scheme). |
| `openDelay` | `open-delay` | `undefined \| number` | Delay (ms) before the card opens on hover. Defaults to 0 (focus opens it immediately too). |
| `closeDelay` | `close-delay` | `undefined \| number` | Delay (ms) before it closes after the pointer leaves. Defaults to 300. |
| `placement` | `placement` | `undefined \| string` | Preferred placement: `'top' \| 'bottom' \| 'left' \| 'right'` (+ optional `-start`/`-end`). Defaults to `'bottom'`; flips to stay in view. |
| `open` | `open` | `undefined \| false \| true` | 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`. |
| `defaultOpen` | `default-open` | `undefined \| false \| true` | Initial open state on mount (uncontrolled seed). |
| `disabled` | `disabled` | `undefined \| false \| true` | Suppress the hover behavior entirely without unmounting. |

**Events** (non-bubbling `CustomEvent`s — listen directly on the element):

| Event | `detail` type | Description |
|---|---|---|
| `kai-open-change` | `CustomEvent<{ open: false \| true }>` | The card opened or closed (by hover/focus, outside-click, or a method). |

**Methods** (call on the element instance: `document.querySelector('kai-hover-card').show()`):

| Method | Signature | Description |
|---|---|---|
| `show` | `(): void` | Open it programmatically (no-op while disabled). |
| `hide` | `(): void` | Close it programmatically. |
| `toggle` | `(): void` | Flip the open state (closes while disabled). |

**Slots** (project your own markup via `slot="name"` on a light-DOM child):

| Slot | Mode | Description |
|---|---|---|
| _(default)_ | inject | The TRIGGER the card hovers off. The card body is the `card` slot. |
| `card` | inject | The rich content shown in the floating hover card. |

---

### `kai-icon` / `Icon`

**Properties** (every element also accepts `theme="light|dark|auto"`; only scalar props work as HTML attributes):

| Property | Attribute | Type | Description |
|---|---|---|---|
| `theme` | `theme` | `"light" \| "dark" \| "auto"` | Color mode (`auto` follows prefers-color-scheme). |
| `name` | `name` | `undefined \| string` | A curated icon name (e.g. `"mic"`, `"globe"`), an image URL/data-URI, or plain text. |
| `size` | `size` | `undefined \| "sm" \| "md" \| "lg"` | Size token: `sm` \| `md` (default) \| `lg`. |

_No events._

**Styleable parts** (restyle from outside via `kai-icon::part(name)`):

| Part | Description |
|---|---|
| `::part(icon)` | The icon wrapper. Inherits `currentColor` and the `size` prop by default; recolor or resize it from outside. — `kai-icon::part(icon) { color: var(--color-primary) }` |

---

### `kai-image` / `Image`

**Properties** (every element also accepts `theme="light|dark|auto"`; only scalar props work as HTML attributes):

| Property | Attribute | Type | Description |
|---|---|---|---|
| `theme` | `theme` | `"light" \| "dark" \| "auto"` | Color mode (`auto` follows prefers-color-scheme). |
| `base64` | `base64` | `undefined \| string` | Base64-encoded image data (pair with `media-type`). |
| `bytes` | — | `undefined \| Uint8Array<ArrayBufferLike>` | Raw image bytes (set as a JS property). |
| `alt` | `alt` | `undefined \| string` | Alt text. |
| `mediaType` | `media-type` | `undefined \| string` | MIME type (default `image/png`). |

_No events._

---

### `kai-input` / `Input`

**Properties** (every element also accepts `theme="light|dark|auto"`; only scalar props work as HTML attributes):

| Property | Attribute | Type | Description |
|---|---|---|---|
| `theme` | `theme` | `"light" \| "dark" \| "auto"` | Color mode (`auto` follows prefers-color-scheme). |
| `type` | `type` | `undefined \| string` | Native input type: `text` (default) · `email` · `url` · `search` · `tel` · `password` · `number`. Single-line only. |
| `value` | `value` | `undefined \| string` | Controlled value, and always the CANONICAL one when a mask is active: digits for `tel` / `ssn` / `credit-card`, the formatted text for `custom`. Settable and reflected to the `value` attribute. `el.value = '5551234567'` drives it (no event) and is re-fitted to the mask on the way in, so the field shows `555-123-4567`. Read `el.value` for live state; the formatted text rides along on every `kai-input` / `kai-change` detail as `formattedValue`. |
| `placeholder` | `placeholder` | `undefined \| string` | Placeholder shown when empty. |
| `label` | `label` | `undefined \| string` | Field label, linked to the input. |
| `hint` | `hint` | `undefined \| string` | Helper text below the control. |
| `error` | `error` | `undefined \| string` | Error text; flips the field invalid (`aria-invalid` + destructive border). |
| `size` | `size` | `undefined \| "sm" \| "md"` | Control density: `sm` or `md`. Defaults to `md`. |
| `disabled` | `disabled` | `undefined \| false \| true` | Disable interaction. |
| `readonly` | `readonly` | `undefined \| false \| true` | Make the input read-only. |
| `required` | `required` | `undefined \| false \| true` | Mark the input required. |
| `invalid` | `invalid` | `undefined \| false \| true` | Force the invalid state without an `error` string. |
| `name` | `name` | `undefined \| string` | Form-control name. |
| `autocomplete` | `autocomplete` | `undefined \| string` | Autofill hint forwarded to the inner input (e.g. `email`, `current-password`). |
| `inputmode` | `inputmode` | `undefined \| string` | Virtual-keyboard hint forwarded to the inner input (e.g. `numeric`, `email`). |
| `format` | `format` | `undefined \| string` | Mask pattern: `#` a digit, `@` a letter or digit, `*` an obscurable letter or digit, and every other character a positional literal (`@@@-####` → `CHG-4821`). The literal `default` is the opt-in sentinel: it resolves to the default format of `semantic` (`tel` → `###-###-####`). A bare `semantic` never starts masking on its own, so an opt-in token is what turns tier 2 on. |
| `guide` | `guide` | `undefined \| string` | Placeholder guide shown at unfilled positions, aligned position for position with `format`: `mm/dd/yyyy` against `##/##/####`. Spaces are a valid guide character, so a guide of blanks and separators is how a phone field shows its shape without showing letters. Without a guide the field shows only up to the last typed character. A guide is a visual aid, never an accessible name: keep the `hint` text as well. |
| `semantic` | `semantic` | `undefined \| "credit-card" \| "custom" \| "ssn" \| "tel"` | Semantic field type: `tel` · `ssn` · `credit-card` · `custom`. On its own it sets `inputmode` / `autocomplete` / `spellcheck` / `autocorrect` / `autocapitalize` and decides the canonical value; it never starts masking by itself. |
| `caseMode` | `case-mode` | `undefined \| "preserve" \| "upper" \| "lower"` | Case folding applied to typed and pasted text: `preserve` (default) · `upper` · `lower`. Attribute: `case-mode`. |
| `copyPolicy` | `copy-policy` | `undefined \| "formatted" \| "canonical" \| "obscured" \| "blocked"` | What a copy or cut of a masked field puts on the clipboard: `canonical` (default) · `formatted` · `obscured` · `blocked`. Attribute: `copy-policy`. |

**Events** (non-bubbling `CustomEvent`s — listen directly on the element):

| Event | `detail` type | Description |
|---|---|---|
| `kai-change` | `CustomEvent<{ value: string; formattedValue: string }>` | The value was committed (blur). Same detail shape as `kai-input`. |
| `kai-input` | `CustomEvent<{ value: string; formattedValue: string }>` | The value changed per keystroke. `value` is the canonical value (what a backend wants); `formattedValue` is the text on screen. With no mask the two are equal. |
| `kai-input-rejected` | `CustomEvent<{ reason: "full" \| "wrong-class" \| "over-capacity" \| "format-change-clipped"; data: string }>` | A mask refused, or partly refused, some content. The reasons are `full` (no free position left), `wrong-class` (a letter into a digit position), `over-capacity` (a paste longer than the mask holds; what fits was kept), and `format-change-clipped` (the `format` changed under a value that no longer fits). `data` is the content that was refused. The first three are USER-INPUT errors, and are the ones worth announcing in a polite live region. `format-change-clipped` is not one: it follows the app changing its own configuration, so it reports and nothing more. None of the four touches validity, so `invalid` and `error` stay the consumer decision. |

**Methods** (call on the element instance: `document.querySelector('kai-input').focus(…)`):

| Method | Signature | Description |
|---|---|---|
| `focus` | `(options?: FocusOptions): void` | Focus the inner input (the host can't reach into the shadow root). |
| `select` | `(): void` | Select the inner input's text. |
| `getRawValue` | `(): string` | The canonical value: digits for `tel` / `ssn` / `credit-card`, the formatted text for `custom`, and the field text when no mask is on. Identical to reading `el.value`, under the name backends use for the submitted form of a masked field. The mask engine has a third, narrower notion of raw (the fill characters with no literals at all) and that one is internal: it is not what any backend wants and it is not exposed here. |
| `getFormattedValue` | `(): string` | The text on screen, literals and guide included. The counterpart to `formattedValue` on the `kai-input` / `kai-change` details, for a consumer that needs it outside an event. |
| `clear` | `(): void` | Empty the value and fire `kai-change` with `''`. On a masked field this resets the mask itself, not just the text on screen, so the next character starts over. |

**Slots** (project your own markup via `slot="name"` on a light-DOM child):

| Slot | Mode | Description |
|---|---|---|
| `leading` | inject | A glyph, prefix, or affix at the start of the field, inside the border. |
| `trailing` | inject | A button, unit, or affix at the end of the field, inside the border. |

**Styleable parts** (restyle from outside via `kai-input::part(name)`):

| Part | Description |
|---|---|
| `::part(field)` | The bordered control box (the row wrapping any affixes plus the input). Restyle its border, radius, surface, or focus ring. — `kai-input::part(field) { border-radius: 0.75rem }` |
| `::part(input)` | The inner input element. Restyle its text, padding, or placeholder. — `kai-input::part(input) { font-variant-numeric: tabular-nums }` |
| `::part(label)` | The field label above the control. Restyle its typography or spacing. — `kai-input::part(label) { font-weight: 600 }` |
| `::part(hint)` | The hint or error line below the control. Restyle its typography. — `kai-input::part(hint) { font-style: italic }` |

---

### `kai-kbd` / `Kbd`

**Properties** (every element also accepts `theme="light|dark|auto"`; only scalar props work as HTML attributes):

| Property | Attribute | Type | Description |
|---|---|---|---|
| `theme` | `theme` | `"light" \| "dark" \| "auto"` | Color mode (`auto` follows prefers-color-scheme). |
| `keys` | `keys` | `undefined \| string` | 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. |
| `platform` | `platform` | `undefined \| "auto" \| "mac" \| "other"` | `mac` uses ⌘/⌥, `other` uses Ctrl. `auto` (default) sniffs the OS. |
| `size` | `size` | `undefined \| "sm" \| "md"` | Cap size: `sm` or `md`. Defaults to `md`. |

_No events._

**Slots** (project your own markup via `slot="name"` on a light-DOM child):

| Slot | Mode | Description |
|---|---|---|
| _(default)_ | inject | Literal key text, when you are not using the `keys` prop to render key caps. |

**Styleable parts** (restyle from outside via `kai-kbd::part(name)`):

| Part | Description |
|---|---|
| `::part(key)` | Each key cap. Restyle its surface, border, radius, or font. — `kai-kbd::part(key) { border-radius: 0.375rem }` |
| `::part(separator)` | The gap between key caps. Inject a literal joiner (e.g. a plus sign) from outside. — `kai-kbd::part(separator)::after { content: "+" }` |

---

### `kai-link-preview` / `LinkPreview`

**Properties** (every element also accepts `theme="light|dark|auto"`; only scalar props work as HTML attributes):

| Property | Attribute | Type | Description |
|---|---|---|---|
| `theme` | `theme` | `"light" \| "dark" \| "auto"` | Color mode (`auto` follows prefers-color-scheme). |
| `cardId` | `card-id` | `undefined \| string` | Stable card id correlating every emitted event. Set as an attribute or property. |
| `data` | — | `undefined \| { url: string; title?: undefined \| string; description?: undefined \| string; image?: undefined \| string; imageAlt?: undefined \| string; favicon?: undefined \| string; domain?: undefined \| string; siteName?: undefined \| string }` | The link payload (OG metadata). Set as a JS **property** (object). |

_No events._

---

### `kai-loader` / `Loader`

**Properties** (every element also accepts `theme="light|dark|auto"`; only scalar props work as HTML attributes):

| Property | Attribute | Type | Description |
|---|---|---|---|
| `theme` | `theme` | `"light" \| "dark" \| "auto"` | Color mode (`auto` follows prefers-color-scheme). |
| `variant` | `variant` | `undefined \| "circular" \| "classic" \| "pulse" \| "pulse-dot" \| "dots" \| "typing" \| "wave" \| "bars" \| "terminal" \| "text-blink" \| "text-shimmer" \| "loading-dots"` | The animation style: `'circular' \| 'classic' \| 'pulse' \| 'pulse-dot' \| 'dots' \| 'typing' \| 'wave' \| 'bars' \| 'terminal' \| 'text-blink' \| 'text-shimmer' \| 'loading-dots'`. Defaults to `'circular'`. |
| `size` | `size` | `undefined \| "sm" \| "md" \| "lg"` | Loader size: `'sm' \| 'md' \| 'lg'`. Defaults to `'md'`. |
| `text` | `text` | `undefined \| string` | Label for the text-based variants. |

_No events._

---

### `kai-markdown` / `Markdown`

**Properties** (every element also accepts `theme="light|dark|auto"`; only scalar props work as HTML attributes):

| Property | Attribute | Type | Description |
|---|---|---|---|
| `theme` | `theme` | `"light" \| "dark" \| "auto"` | Color mode (`auto` follows prefers-color-scheme). |
| `content` | `content` | `string` | The markdown source to render. |
| `proseSize` | `prose-size` | `undefined \| "xs" \| "sm" \| "base" \| "lg"` | Text/markdown sizing. |
| `codeTheme` | `code-theme` | `undefined \| string` | Shiki theme for fenced code blocks. |
| `codeHighlight` | `code-highlight` | `undefined \| false \| true` | Disable syntax highlighting (no Shiki loads). |

_No events._

---

### `kai-menu` / `Menu`

**Properties** (every element also accepts `theme="light|dark|auto"`; only scalar props work as HTML attributes):

| Property | Attribute | Type | Description |
|---|---|---|---|
| `theme` | `theme` | `"light" \| "dark" \| "auto"` | Color mode (`auto` follows prefers-color-scheme). |
| `items` | — | `undefined \| { id?: undefined \| string; label?: undefined \| string; icon?: undefined \| string; shortcut?: undefined \| string; checked?: undefined \| false \| true; radioGroup?: undefined \| string; disabled?: undefined \| false \| true; separator?: undefined \| false \| true; heading?: undefined \| false \| true; items?: undefined \| Record<string, unknown>[] }[]` | Tree of menu items. Set as a JS property, not an HTML attribute. |
| `placement` | `placement` | `undefined \| string` | Optional placement hint (unused by the underlying Dropdown which always positions bottom-start, kept for future extension). |
| `triggerIcon` | `trigger-icon` | `undefined \| 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. |
| `triggerLabel` | `trigger-label` | `undefined \| string` | Built-in trigger: a text label (e.g. `"High"`). This is the trigger's VISIBLE text, so it is also its accessible name, and `label` does not override it: an accessible name that does not contain the visible text is unreachable by speech input, which is what WCAG 2.5.3 (Label in Name) exists for. A slotted `slot="trigger"` replaces this built-in trigger entirely and is named differently; see `label`. |
| `triggerIconTrailing` | `trigger-icon-trailing` | `undefined \| string` | Built-in trigger: a trailing icon (e.g. `"chevron-down"` for a select look). |
| `label` | `label` | `undefined \| string` | Accessible name for a trigger with no visible label. Ignored when `triggerLabel` is set, which is already the visible name. It DOES name a slotted `slot="trigger"`, and that is a difference in what the two slots MEAN, not a limitation. `<kai-button>`'s slot IS the button's label, so text slotted there is the name and `label` steps aside. This slot is VISUAL content, a `+` or an `<svg>`, with the name supplied separately: decoration beside a name, never a second name competing with one. So `label` names the trigger here by design. Slotting a real WORD rather than a glyph makes that word a visible label, and an accessible name has to contain the visible text. Then either drop `label` or make it contain the word you slotted. |
| `full` | `full` | `undefined \| false \| true` | Stretch the trigger to the full width of the menu's container (a block row), e.g. a sidebar-footer account row. Same affordance as `<kai-button full>`. Attribute: `full`. |
| `open` | `open` | `undefined \| false \| true` | 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`. |
| `defaultOpen` | `default-open` | `undefined \| false \| true` | Initial open state on mount (uncontrolled seed). |
| `disabled` | `disabled` | `undefined \| false \| true` | Disable the trigger: click/keyboard and `show()` no longer open the menu. |

**Events** (non-bubbling `CustomEvent`s — listen directly on the element):

| Event | `detail` type | Description |
|---|---|---|
| `kai-open-change` | `CustomEvent<{ open: false \| true }>` | The menu opened or closed (by click, keyboard, Escape, outside-click, or a method). |
| `kai-select` | `CustomEvent<{ id: string; checked?: undefined \| false \| true; radioGroup?: undefined \| string }>` | 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. |

**Methods** (call on the element instance: `document.querySelector('kai-menu').show()`):

| Method | Signature | Description |
|---|---|---|
| `show` | `(): void` | Open it programmatically (no-op while disabled). |
| `hide` | `(): void` | Close it programmatically. |
| `toggle` | `(): void` | Flip the open state (closes while disabled). |

**Slots** (project your own markup via `slot="name"` on a light-DOM child):

| Slot | Mode | Description |
|---|---|---|
| `trigger` | replace | Your own trigger element; replaces the built-in button driven by the `trigger-icon` / `trigger-label` props. |

**Styleable parts** (restyle from outside via `kai-menu::part(name)`):

| Part | Description |
|---|---|
| `::part(shortcut)` | The right-aligned per-item keyboard shortcut, rendered as kai-kbd key caps. Shown only when an item carries a `shortcut`. — `kai-menu::part(shortcut) { opacity: 0.8 }` |

---

### `kai-message` / `Message`

**Properties** (every element also accepts `theme="light|dark|auto"`; only scalar props work as HTML attributes):

| Property | Attribute | Type | Description |
|---|---|---|---|
| `theme` | `theme` | `"light" \| "dark" \| "auto"` | Color mode (`auto` follows prefers-color-scheme). |
| `message` | — | `undefined \| { id: string; role: "user" \| "assistant"; parts: ({ type: "text"; text: string; raw?: undefined \| { source: string; payload: unknown } } \| { type: "reasoning"; text: string; label?: undefined \| string; index?: undefined \| number; streamId?: undefined \| string; signature?: undefined \| string; raw?: undefined \| { source: string; payload: unknown } } \| { type: "tool"; tool: { type: string; kind?: undefined \| "command" \| "file-change" \| "search" \| "fetch" \| "mcp" \| "image" \| "generic"; state: "input-streaming" \| "input-available" \| "output-available" \| "output-error"; input?: undefined \| Record<string, unknown>; rawInput?: undefined \| string; output?: undefined \| Record<string, unknown>; toolCallId?: undefined \| string; errorText?: undefined \| string; raw?: undefined \| { source: string; payload: unknown } }; raw?: undefined \| { source: string; payload: unknown } } \| { type: "card"; envelope: { type: string; id: string; data: unknown; title?: undefined \| string; resolution?: undefined \| { kind: "action"; action: string; payload?: unknown; at?: undefined \| string } \| { kind: "submit"; data: unknown; at?: undefined \| string } \| { kind: "dismissed"; at?: undefined \| string } \| { kind: "expired"; reason?: undefined \| string; at?: undefined \| string } }; raw?: undefined \| { source: string; payload: unknown } } \| { type: "source"; source: { id?: undefined \| string; url?: undefined \| string; title?: undefined \| string; snippet?: undefined \| string; index?: undefined \| number }; raw?: undefined \| { source: string; payload: unknown } } \| { type: "file"; attachment: { id: string; type: "file" \| "source-document"; filename?: undefined \| string; mediaType?: undefined \| string; url?: undefined \| string; title?: undefined \| string }; raw?: undefined \| { source: string; payload: unknown } })[]; actions?: undefined \| ("copy" \| "dislike" \| "edit" \| "like" \| "regenerate" \| "speak" \| { 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 full message object. Set as a JS property. |
| `role` | `role` | `undefined \| "user" \| "assistant"` | 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. |
| `markdown` | `markdown` | `undefined \| false \| true` | Force markdown on/off. Defaults to on for assistant, off for user. |
| `proseSize` | `prose-size` | `undefined \| "xs" \| "sm" \| "base" \| "lg"` | Text/markdown sizing for the message body. |
| `codeTheme` | `code-theme` | `undefined \| string` | Shiki theme name used for fenced code blocks in the content. |
| `codeHighlight` | `code-highlight` | `undefined \| false \| true` | Disable syntax highlighting for code blocks (no Shiki loads). |
| `actionsReveal` | `actions-reveal` | `undefined \| "always" \| "hover"` | Whether the action bar is always visible (`'always'`, default) or only revealed on hover of the message row (`'hover'`). |
| `avatarSrc` | `avatar-src` | `undefined \| string` | Convenience avatar image URL (used when `message.avatar` is not set). |
| `avatarFallback` | `avatar-fallback` | `undefined \| string` | Convenience avatar fallback text (used when `message.avatar` is not set). |
| `avatar` | `avatar` | `undefined \| 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). |
| `cardTypes` | — | `undefined \| Record<string, 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. |
| `cardSchemas` | — | `undefined \| Record<string, object>` | 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. |

**Events** (non-bubbling `CustomEvent`s — listen directly on the element):

| Event | `detail` type | Description |
|---|---|---|
| `kai-message-action` | `CustomEvent<{ messageId: string; action: string; state?: undefined \| "on" \| "off" }>` | 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. |

**Methods** (call on the element instance: `document.querySelector('kai-message').copy()`):

| Method | Signature | Description |
|---|---|---|
| `copy` | `(): void` | Copy the message content to the clipboard and show the copied check. |

**Slots** (project your own markup via `slot="name"` on a light-DOM child):

| Slot | Mode | Description |
|---|---|---|
| `before-body` | inject | A per-message header at the TOP of the body, above reasoning/tools/content: a model-name label, a role + timestamp line. |
| `after-body` | inject | A row at the BOTTOM of the body, below the action bar: a citation/sources row, a token-cost/latency line. |
| `avatar` | replace | Replaces the built-in avatar rail with your own node. Use `avatar="none"` to omit the rail and let the body span the full row. |

**Declarative children** (compose these in light DOM instead of setting the JS property):

| Child element | Attributes | Text content | Notes |
|---|---|---|---|
| `<kai-action>` | `action`, `icon`, `id`, `label`, `tooltip` | yes |  |

**Styleable parts** (restyle from outside via `kai-message::part(name)`):

| Part | Description |
|---|---|
| `::part(row)` | The message row wrapper (avatar rail + body column). Restyle its gap or alignment from outside. — `kai-message::part(row) { gap: 0.75rem }` |
| `::part(bubble)` | The content bubble wrapper. Restyle its background, radius, or padding; for a user message this is the rounded chat bubble. — `kai-message::part(bubble) { background: var(--color-primary); color: var(--color-primary-foreground) }` |
| `::part(content)` | The rendered message text/markdown region (same node as `bubble`). Target it to tune typography from outside. — `kai-message::part(content) { font-size: 0.9375rem }` |
| `::part(actions)` | The action-bar row (copy / like / regenerate …). Restyle its spacing or hide it entirely from outside. — `kai-message::part(actions) { gap: 0.25rem }` |
| `::part(citations)` | The citation row rendered from the message’s `source` parts: a wrapped row of chips below the bubble, never inside it. Restyle its spacing or hide it entirely from outside. — `kai-message::part(citations) { gap: 0.5rem }` |
| `::part(attachment)` | One attachment item: the chip, row or tile, whichever variant is rendering. Restyle its background, radius or border from outside without caring which layout it is. — `kai-chat::part(attachment) { border-radius: 0.25rem }` |
| `::part(attachment-name)` | The attachment’s filename label. Present in every variant that shows one (a grid tile omits it for an image, which is its own label). Retune its type or hide it entirely. — `kai-chat::part(attachment-name) { font-size: 0.75rem }` |
| `::part(avatar)` | Replaces the built-in avatar rail with your own node. Use `avatar="none"` to omit the rail and let the body span the full row. |

---

### `kai-model-switcher` / `ModelSwitcher`

**Properties** (every element also accepts `theme="light|dark|auto"`; only scalar props work as HTML attributes):

| Property | Attribute | Type | Description |
|---|---|---|---|
| `theme` | `theme` | `"light" \| "dark" \| "auto"` | Color mode (`auto` follows prefers-color-scheme). |
| `models` | — | `undefined \| { id: string; name: string; provider?: undefined \| string; description?: undefined \| string; group?: undefined \| string }[]` | 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. |
| `currentModel` | `current-model` | `undefined \| string` | The currently-selected model id. Defaults to the first model. |
| `open` | `open` | `undefined \| false \| true` | 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`. |
| `defaultOpen` | `default-open` | `undefined \| false \| true` | Initial open state on mount (uncontrolled seed). |
| `disabled` | `disabled` | `undefined \| false \| true` | Disable the trigger: click/keyboard and `show()` no longer open the dropdown. |

**Events** (non-bubbling `CustomEvent`s — listen directly on the element):

| Event | `detail` type | Description |
|---|---|---|
| `kai-model-change` | `CustomEvent<{ modelId: string }>` | A model was selected. |
| `kai-open-change` | `CustomEvent<{ open: false \| true }>` | The model dropdown opened or closed (by click, keyboard, Escape, outside-click, or a method). |

**Methods** (call on the element instance: `document.querySelector('kai-model-switcher').show()`):

| Method | Signature | Description |
|---|---|---|
| `show` | `(): void` | Open it programmatically (no-op while disabled). |
| `hide` | `(): void` | Close it programmatically. |
| `toggle` | `(): void` | Flip the open state (closes while disabled). |

**Declarative children** (compose these in light DOM instead of setting the JS property):

| Child element | Attributes | Text content | Notes |
|---|---|---|---|
| `<kai-model>` | `description`, `group`, `id`, `provider` | yes | Parse a single light-DOM `<kai-model>` element into a `ModelOption` descriptor. Attribute mapping: - `id` → ModelOption.id - textContent → ModelOption.name - `provider` → ModelOption.provider (optional) - `description` → ModelOption.description (optional subtitle) - `group` → ModelOption.group (optional collapsible section) |

---

### `kai-nav` / `Nav`

**Properties** (every element also accepts `theme="light|dark|auto"`; only scalar props work as HTML attributes):

| Property | Attribute | Type | Description |
|---|---|---|---|
| `theme` | `theme` | `"light" \| "dark" \| "auto"` | Color mode (`auto` follows prefers-color-scheme). |
| `items` | — | `undefined \| { id: string; label?: undefined \| string; icon?: undefined \| string; badge?: undefined \| string; trailing?: undefined \| string; disabled?: undefined \| false \| true; children?: undefined \| Record<string, unknown>[]; status?: undefined \| { tone: "primary" \| "info" \| "success" \| "warning" \| "error" \| "neutral"; label?: undefined \| string; pulse?: undefined \| false \| true }; meta?: undefined \| string; action?: undefined \| { icon: string; label: string }; closable?: undefined \| false \| true }[]` | 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. |
| `value` | `value` | `undefined \| string` | Active item id (controlled). |
| `defaultValue` | `default-value` | `undefined \| string` | Initial active id when uncontrolled. |
| `defaultCollapsed` | — | `undefined \| string[]` | Ids of group items collapsed on first render (groups default to expanded). Set as a JS property (array). |

**Events** (non-bubbling `CustomEvent`s — listen directly on the element):

| Event | `detail` type | Description |
|---|---|---|
| `kai-nav-item-action` | `CustomEvent<{ value: string; action?: undefined \| { icon: string; label: string } }>` | A row's trailing `action` button was activated (not a select). `value` is the item id; `action` echoes the item's `{ icon, label }`. |
| `kai-nav-item-close` | `CustomEvent<{ value: string }>` | A `closable` row's trailing close button was activated (not a select). `value` is the item id. |
| `kai-nav-select` | `CustomEvent<{ id: string }>` | A nav item was activated. |

**Methods** (call on the element instance: `document.querySelector('kai-nav').select(…)`):

| Method | Signature | Description |
|---|---|---|
| `select` | `(id: string): void` | Activate an item by id (fires kai-nav-select). |

**Styleable parts** (restyle from outside via `kai-nav::part(name)`):

| Part | Description |
|---|---|
| `::part(nav)` | The nav list container. Restyle its gap or padding from outside. — `kai-nav::part(nav) { gap: 0.25rem }` |
| `::part(item)` | A nav item button (leaf or group parent). The active leaf carries aria-current="page" and a group parent carries aria-expanded; target `::part(item)[aria-current]` for the selected look or `::part(item)[aria-expanded]` for a group row. — `kai-nav::part(item)[aria-current] { background: var(--color-accent) }` |
| `::part(group)` | The nested child list rendered under an expanded group item. Add a left guide line or tune its indent from outside. — `kai-nav::part(group) { border-left: 1px solid var(--color-border); margin-left: 1.1rem }` |
| `::part(chevron)` | The disclosure chevron on a group row (rotates when expanded). Recolor or resize it from outside. — `kai-nav::part(chevron) { opacity: 1; color: var(--color-primary) }` |
| `::part(status)` | The per-item status cluster (a colored dot in the tone hue + an optional label). Shown only when an item carries a `status`; the `pulse` flag animates the dot. Restyle from outside. — `kai-nav::part(status) { gap: 0.5rem }` |
| `::part(meta)` | The right-aligned muted trailing text on a row (e.g. a relative time). Shown only when an item carries `meta`; restyle from outside. — `kai-nav::part(meta) { color: var(--color-foreground); font-variant-numeric: tabular-nums }` |
| `::part(item-action)` | The trailing per-item action / close button, a sibling of the item button. Shown only when an item carries `action` or `closable`; reveal it on hover or pin it visible from outside. — `kai-nav::part(item-action) { opacity: 1 }` |

---

### `kai-notice` / `Notice`

**Properties** (every element also accepts `theme="light|dark|auto"`; only scalar props work as HTML attributes):

| Property | Attribute | Type | Description |
|---|---|---|---|
| `theme` | `theme` | `"light" \| "dark" \| "auto"` | Color mode (`auto` follows prefers-color-scheme). |
| `severity` | `severity` | `undefined \| "neutral" \| "info" \| "warning" \| "error" \| "success"` | `neutral` (default) · `info` · `warning` · `error` · `success`. Drives the leading icon's color and the a11y role (`alert` for errors, else `status`). |
| `icon` | `icon` | `undefined \| string` | Leading icon: omit for the severity default, `"none"` to hide it, or a named icon to override. |
| `dismissible` | `dismissible` | `undefined \| false \| true` | Show a dismiss (×) that hides the notice and emits `kai-dismiss`. |

**Events** (non-bubbling `CustomEvent`s — listen directly on the element):

| Event | `detail` type | Description |
|---|---|---|
| `kai-dismiss` | `CustomEvent` | The notice was dismissed via its × (it also hides itself). |

**Slots** (project your own markup via `slot="name"` on a light-DOM child):

| Slot | Mode | Description |
|---|---|---|
| _(default)_ | inject | The notice message. `icon` and `action` are the named seams around it. |
| `action` | inject | A trailing action beside the message: a link or button. |
| `icon` | replace | A custom leading icon (any inline SVG, inherits `currentColor`). Overrides the severity default and the `icon` prop, the same escape hatch as `kai-button`. |

---

### `kai-pane` / `Pane`

**Properties** (every element also accepts `theme="light|dark|auto"`; only scalar props work as HTML attributes):

| Property | Attribute | Type | Description |
|---|---|---|---|
| `theme` | `theme` | `"light" \| "dark" \| "auto"` | Color mode (`auto` follows prefers-color-scheme). |
| `headline` | `headline` | `undefined \| string` | The pane title (the agent / window name). Named `headline` because `title` collides with the global `HTMLElement.title` attribute (it throws at registration). Attribute: `headline`. |
| `subtitle` | `subtitle` | `undefined \| string` | A role / label shown under the title (e.g. "Reviewer", "claude-sonnet"). Attribute: `subtitle`. |
| `maximized` | `maximized` | `undefined \| false \| true` | Show the restore glyph instead of maximize, and signal the maximized view-state. Drive it yourself in response to `kai-maximize`. Attribute: `maximized`. |
| `focused` | `focused` | `undefined \| false \| true` | Highlight the frame with a ring/border to mark the ACTIVE pane. Attribute: `focused`. |
| `showSplit` | `show-split` | `undefined \| false \| true` | Show a split-pane window control that fires `kai-split`. Off by default. Attribute: `show-split`. |
| `showDock` | `show-dock` | `undefined \| false \| true` | Show a dock-to-side window control that fires `kai-dock`. Off by default. Attribute: `show-dock`. |
| `status` | — | `undefined \| { tone: "working" \| "idle" \| "done" \| "error" \| "blocked"; label?: undefined \| string; pulse?: undefined \| false \| true }` | A tone-colored status dot (+ optional label) in the header. An object `{ tone, label?, pulse? }` set as a JS PROPERTY (not an attribute). |

**Events** (non-bubbling `CustomEvent`s — listen directly on the element):

| Event | `detail` type | Description |
|---|---|---|
| `kai-close` | `CustomEvent` | The close (×) control was clicked. |
| `kai-dock` | `CustomEvent` | The dock control was clicked (only present when `show-dock`). |
| `kai-maximize` | `CustomEvent<{ maximized: false \| true }>` | The maximize/restore control was clicked. `detail.maximized` is the intended NEXT state. Drive the `maximized` prop yourself from it. |
| `kai-split` | `CustomEvent` | The split control was clicked (only present when `show-split`). |

**Slots** (project your own markup via `slot="name"` on a light-DOM child):

| Slot | Mode | Description |
|---|---|---|
| _(default)_ | inject | The pane body, below the header row. |
| `leading` | inject | A glyph or avatar at the start of the pane header. |
| `actions` | inject | Extra header controls, before the built-in window controls. |
| `footer` | inject | A pinned row below the body (e.g. a composer). |

**Styleable parts** (restyle from outside via `kai-pane::part(name)`):

| Part | Description |
|---|---|
| `::part(header)` | The pane header bar (leading + title/status + actions + window controls). — `kai-pane::part(header) { padding-inline: 0.75rem }` |
| `::part(body)` | The scrolling body region (the default slot). — `kai-pane::part(body) { padding: 1rem }` |
| `::part(controls)` | The window-control cluster (maximize/close, and split/dock when enabled). — `kai-pane::part(controls) { gap: 0.25rem }` |
| `::part(footer)` | A pinned row below the body (e.g. a composer). |

---

### `kai-pane-grid` / `PaneGrid`

**Properties** (every element also accepts `theme="light|dark|auto"`; only scalar props work as HTML attributes):

| Property | Attribute | Type | Description |
|---|---|---|---|
| `theme` | `theme` | `"light" \| "dark" \| "auto"` | Color mode (`auto` follows prefers-color-scheme). |
| `minPaneWidth` | `min-pane-width` | `undefined \| number` | Minimum width of every pane, in px, before columns drop / the grid scrolls. Defaults to `280`. Attribute: `min-pane-width`. |
| `minPaneHeight` | `min-pane-height` | `undefined \| number` | Minimum height of every pane, in px, before the grid scrolls vertically. Defaults to `200`. Attribute: `min-pane-height`. |
| `maxColumns` | `max-columns` | `undefined \| number` | Column cap when the container is wide (default `3`). Attribute: `max-columns`. |
| `gap` | `gap` | `undefined \| string` | Gap between panes, any CSS length. Defaults to the kit gap (`var(--kai-pane-grid-gap, 0.5rem)`). Attribute: `gap`. |
| `maximizedIndex` | — | `undefined \| number \| null` | When set to a valid child index, render ONLY that pane full-bleed: a simple maximize hook the consumer drives (pair it with `<kai-pane>`'s `kai-maximize` event). Clear it (or point out of range) for the full tiled grid. Attribute: `maximized-index`. |

_No events._

---

### `kai-pane-group` / `PaneGroup`

**Properties** (every element also accepts `theme="light|dark|auto"`; only scalar props work as HTML attributes):

| Property | Attribute | Type | Description |
|---|---|---|---|
| `theme` | `theme` | `"light" \| "dark" \| "auto"` | Color mode (`auto` follows prefers-color-scheme). |
| `tabs` | — | `undefined \| { id: string; name: string; status?: undefined \| { tone: "working" \| "idle" \| "done" \| "error" \| "blocked"; label?: undefined \| string; pulse?: undefined \| false \| true }; needsAttention?: undefined \| false \| true; number?: undefined \| number }[]` | The tabs to render. An array of `{ id, name, status?, needsAttention?, number? }` set as a JS PROPERTY (not an HTML attribute). |
| `active` | `active` | `undefined \| string` | 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). |
| `focused` | `focused` | `undefined \| false \| true` | Highlight the frame as the ACTIVE group in a multi-group layout. Attribute: `focused`. |

**Events** (non-bubbling `CustomEvent`s — listen directly on the element):

| Event | `detail` type | Description |
|---|---|---|
| `kai-tab-change` | `CustomEvent<{ id: string }>` | A tab was selected (click, Enter/Space, or arrow-key move). `detail.id` is the tab's id. |
| `kai-tab-close` | `CustomEvent<{ id: string }>` | A tab's close (×) was clicked. Drop the tab from `tabs` yourself. |
| `kai-tab-menu` | `CustomEvent<{ id: string }>` | A tab's "…" overflow was clicked. Open your own menu from `detail.id`. |

**Methods** (call on the element instance: `document.querySelector('kai-pane-group').select(…)`):

| Method | Signature | Description |
|---|---|---|
| `select` | `(id: string): void` | Select a tab by id (fires `kai-tab-change`). Ignores unknown ids. |
| `focus` | `(): void` | Focus the active tab in the strip. |

**Slots** (project your own markup via `slot="name"` on a light-DOM child):

| Slot | Mode | Description |
|---|---|---|
| _(default)_ | inject | Content shown for every tab. Use it INSTEAD of the per-tab `slot="<tab id>"` seams when you swap the content yourself. |

**Styleable parts** (restyle from outside via `kai-pane-group::part(name)`):

| Part | Description |
|---|---|
| `::part(tabs)` | The tab strip (role="tablist"). Restyle its background, height, padding, or gap from outside. — `kai-pane-group::part(tabs) { background: var(--color-card); gap: 0.25rem }` |
| `::part(tab)` | A single tab button. The active tab carries `[aria-selected="true"]`; target `::part(tab)[aria-selected="true"]` for the selected look. — `kai-pane-group::part(tab)[aria-selected="true"] { background: var(--color-accent) }` |
| `::part(body)` | The active tab's content region (the named/default slot host). — `kai-pane-group::part(body) { padding: 0.75rem }` |
| `::part(menu)` | The per-tab "…" overflow button. Reveal it on hover or pin it visible from outside. — `kai-pane-group::part(menu) { opacity: 1 }` |
| `::part(close)` | The per-tab close ("×") button. Recolor, resize, or hide it from outside. — `kai-pane-group::part(close) { color: var(--color-muted-foreground) }` |

---

### `kai-panel` / `Panel`

**Properties** (every element also accepts `theme="light|dark|auto"`; only scalar props work as HTML attributes):

| Property | Attribute | Type | Description |
|---|---|---|---|
| `theme` | `theme` | `"light" \| "dark" \| "auto"` | Color mode (`auto` follows prefers-color-scheme). |
| `frame` | `frame` | `undefined \| false \| true` | Standalone widget-box chrome: border, radius and shadow on the panel itself. Off (the default), the panel inherits its container's radius and clips to it, the right posture inside an already-framed container such as `kai-dock`'s floating panel. |

_No events._

**Slots** (project your own markup via `slot="name"` on a light-DOM child):

| Slot | Mode | Description |
|---|---|---|
| _(default)_ | inject | The view content that fills the body region (a `<kai-thread>`, a `<kai-view-stack>`, a home screen). Stretched to fill the remaining height between the `header` and `footer` slots. |
| `header` | inject | The header region above the view container: put a `<kai-panel-header>` there, or anything. Keeps its natural height and never scrolls away. |
| `footer` | inject | The row below the view container (a "Powered by" line, a disclaimer). Keeps its natural height and never scrolls away. |

**Styleable parts** (restyle from outside via `kai-panel::part(name)`):

| Part | Description |
|---|---|
| `::part(panel)` | The panel frame itself: the flex column that fills the host. With the `frame` flag it carries the standalone border, radius and shadow. — `kai-panel::part(panel) { border-radius: 1.25rem }` |
| `::part(body)` | The view container between header and footer: fills the remaining height, clips, and anchors floating children. — `kai-panel::part(body) { background: var(--color-muted) }` |
| `::part(header)` | The header region above the view container: put a `<kai-panel-header>` there, or anything. Keeps its natural height and never scrolls away. |
| `::part(footer)` | The row below the view container (a "Powered by" line, a disclaimer). Keeps its natural height and never scrolls away. |

---

### `kai-panel-header` / `PanelHeader`

**Properties** (every element also accepts `theme="light|dark|auto"`; only scalar props work as HTML attributes):

| Property | Attribute | Type | Description |
|---|---|---|---|
| `theme` | `theme` | `"light" \| "dark" \| "auto"` | Color mode (`auto` follows prefers-color-scheme). |

_No events._

**Slots** (project your own markup via `slot="name"` on a light-DOM child):

| Slot | Mode | Description |
|---|---|---|
| _(default)_ | inject | The title text. `start` and `end` are the clusters around it: back arrows and close buttons are slotted content, never props. |
| `start` | inject | The leading cluster, before the title: a back arrow, an avatar. |
| `end` | inject | The trailing cluster, after the title: a close or overflow button. |

**Styleable parts** (restyle from outside via `kai-panel-header::part(name)`):

| Part | Description |
|---|---|
| `::part(header)` | The 56px header row itself (bottom border included). — `kai-panel-header::part(header) { border-bottom: none }` |
| `::part(start)` | The leading cluster wrapper (the `start` slot renders inside it). — `kai-panel-header::part(start) { gap: 0.25rem }` |
| `::part(title)` | The title line (the default slot renders inside it). — `kai-panel-header::part(title) { font-weight: 700 }` |
| `::part(end)` | The trailing cluster wrapper (the `end` slot renders inside it). — `kai-panel-header::part(end) { gap: 0.25rem }` |

---

### `kai-popover` / `Popover`

**Properties** (every element also accepts `theme="light|dark|auto"`; only scalar props work as HTML attributes):

| Property | Attribute | Type | Description |
|---|---|---|---|
| `theme` | `theme` | `"light" \| "dark" \| "auto"` | Color mode (`auto` follows prefers-color-scheme). |
| `placement` | `placement` | `undefined \| "top" \| "right" \| "bottom" \| "left" \| "bottom-end" \| "bottom-start" \| "left-end" \| "left-start" \| "right-end" \| "right-start" \| "top-end" \| "top-start"` | Floating placement relative to the trigger (floating-ui placement). |
| `gutter` | `gutter` | `undefined \| number` | Gap in px between the trigger and the panel. |
| `open` | `open` | `undefined \| false \| true` | 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`. |
| `defaultOpen` | `default-open` | `undefined \| false \| true` | Initial open state on mount (uncontrolled seed). |
| `disabled` | `disabled` | `undefined \| false \| true` | Turn the popover off while keeping the trigger mounted (clicks and `show()` no longer open it). |

**Events** (non-bubbling `CustomEvent`s — listen directly on the element):

| Event | `detail` type | Description |
|---|---|---|
| `kai-open-change` | `CustomEvent<{ open: false \| true }>` | The popover opened or closed (click, Escape, outside-click, or a method). |

**Methods** (call on the element instance: `document.querySelector('kai-popover').show()`):

| Method | Signature | Description |
|---|---|---|
| `show` | `(): void` | Open it programmatically (no-op while disabled). |
| `hide` | `(): void` | Close it programmatically. |
| `toggle` | `(): void` | Flip the open state (closes while disabled). |

**Slots** (project your own markup via `slot="name"` on a light-DOM child):

| Slot | Mode | Description |
|---|---|---|
| _(default)_ | inject | The popover panel body. The control that opens it is the `trigger` slot. |
| `trigger` | replace | The control that opens the popover (a button, an avatar, …). The panel anchors to it. |

---

### `kai-progress-bar` / `ProgressBar`

**Properties** (every element also accepts `theme="light|dark|auto"`; only scalar props work as HTML attributes):

| Property | Attribute | Type | Description |
|---|---|---|---|
| `theme` | `theme` | `"light" \| "dark" \| "auto"` | Color mode (`auto` follows prefers-color-scheme). |
| `value` | `value` | `undefined \| number` | Current progress value (0..max). Attribute: `value`. |
| `max` | `max` | `undefined \| number` | The value `value` runs to (default 100). Attribute: `max`. |
| `label` | `label` | `undefined \| string` | Optional caption above the track. Attribute: `label`. |
| `tone` | `tone` | `undefined \| string` | Fill color: `primary` (default), `success`, `warning`, `error`, `info`. Attribute: `tone`. |

_No events._

**Styleable parts** (restyle from outside via `kai-progress-bar::part(name)`):

| Part | Description |
|---|---|
| `::part(track)` | The progress track (the background bar). Restyle its height, radius, or background from outside. — `kai-progress-bar::part(track) { height: 0.5rem }` |
| `::part(fill)` | The filled portion; its width follows value/max. Recolor it from outside. — `kai-progress-bar::part(fill) { background: var(--color-tool-green) }` |

---

### `kai-prompt-dock` / `PromptDock`

**Properties** (every element also accepts `theme="light|dark|auto"`; only scalar props work as HTML attributes):

| Property | Attribute | Type | Description |
|---|---|---|---|
| `theme` | `theme` | `"light" \| "dark" \| "auto"` | Color mode (`auto` follows prefers-color-scheme). |
| `frame` | `frame` | `undefined \| "inset" \| "edge" \| "none"` | 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`. |
| `appearance` | `appearance` | `undefined \| "soft" \| "outlined" \| "filled" \| "plain"` | 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`. |

_No events._

**Slots** (project your own markup via `slot="name"` on a light-DOM child):

| Slot | Mode | Description |
|---|---|---|
| _(default)_ | inject | The input the dock wraps, typically a `<kai-prompt-input>`. The `top`/`bottom` slots are the lips around it. |
| `top` | inject | The top lip: a notice or banner above the input. Rendered only when filled. |
| `bottom` | inject | The bottom lip: a mode or controls row below the input. Rendered only when filled. |

**Styleable parts** (restyle from outside via `kai-prompt-dock::part(name)`):

| Part | Description |
|---|---|
| `::part(tray)` | The recessed tray that frames the input. The `appearance`/`frame` props set the defaults; the --kai-prompt-dock-* tokens fine-tune surface/border/radius/inset. — `kai-prompt-dock::part(tray) { --kai-prompt-dock-radius: 1rem }` |
| `::part(top)` | The top lip: a notice or banner above the input. Rendered only when filled. |
| `::part(bottom)` | The bottom lip: a mode or controls row below the input. Rendered only when filled. |

---

### `kai-prompt-input` / `PromptInput`

**Properties** (every element also accepts `theme="light|dark|auto"`; only scalar props work as HTML attributes):

| Property | Attribute | Type | Description |
|---|---|---|---|
| `theme` | `theme` | `"light" \| "dark" \| "auto"` | Color mode (`auto` follows prefers-color-scheme). |
| `value` | — | `undefined \| string \| ({ type: "text"; text: string } \| { type: "entity"; entity: { kind: string; id: string; label: string; icon?: undefined \| string; promptText?: undefined \| string; data?: undefined \| Record<string, unknown> } })[]` | 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`. |
| `placeholder` | `placeholder` | `undefined \| string` | Placeholder text shown in the empty input. |
| `disabled` | `disabled` | `undefined \| false \| true` | Disable the input and submit button entirely (non-interactive). |
| `loading` | `loading` | `undefined \| false \| true` | Show the loading/streaming state and block submit (use while awaiting a reply). |
| `suggestions` | — | `undefined \| string[]` | Starter prompts shown above the input. Clicking one follows `suggestionMode`. Set as a JS property. |
| `suggestionMode` | `suggestion-mode` | `undefined \| "submit" \| "fill"` | What clicking a suggestion does: `'submit'` (default) sends it immediately as if typed and submitted; `'fill'` just places it in the input. |
| `webSearch` | `web-search` | `undefined \| false \| true` | Show a web-search (Globe) button in the left toolbar; clicking it fires a `kai-web-search` event. Attribute: `web-search`. |
| `voice` | `voice` | `undefined \| false \| true` | Show a Voice (Mic) button in the left toolbar; clicking it fires a `voice` event. |
| `stoppable` | `stoppable` | `undefined \| false \| true` | 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`. |
| `submit` | `submit` | `undefined \| "always" \| "auto"` | 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. |
| `attach` | `attach` | `undefined \| false \| true` | 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`. |
| `attachments` | — | `undefined \| { id: string; type: "file" \| "source-document"; filename?: undefined \| string; mediaType?: undefined \| string; url?: undefined \| string; title?: undefined \| string }[]` | Attachments to seed the input with (so a consumer can pre-populate staged files without an upload). Set as a JS property; the element then manages its own attachment state from there (add via the paperclip, remove per chip). Each item's `url` must be a `data:` URI or an https URL, never `URL.createObjectURL`: a `blob:` URL previews perfectly and is meaningless outside this tab, so `toOpenAIMessages`/`toAnthropicMessages` refuse it. (The built-in paperclip already stages files as `data:` URIs.) |
| `triggers` | — | `undefined \| { char: string; kind: string; items?: undefined \| { id: string; label: string; icon?: undefined \| string; description?: undefined \| string; group?: undefined \| string; kind?: undefined \| string; promptText?: undefined \| string; data?: undefined \| Record<string, unknown> }[] }[]` | 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. |
| `kindIcons` | — | `undefined \| Record<string, string>` | 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. |

**Events** (non-bubbling `CustomEvent`s — listen directly on the element):

| Event | `detail` type | Description |
|---|---|---|
| `kai-attachments-change` | `CustomEvent<{ attachments: { id: string; type: "file" \| "source-document"; filename?: undefined \| string; mediaType?: undefined \| string; url?: undefined \| string; title?: undefined \| string }[] }>` | 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). |
| `kai-stop` | `CustomEvent<Record<string, never>>` | The Stop button was clicked while `stoppable` and `loading` are both true. |
| `kai-submit` | `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 }[] }>` | The user submitted the prompt (Enter or send button). `value` is the flattened text (back-compat); `doc` is the structured document and `entities` the inserted pills (skills/agents) for downstream expansion. `<kai-prompt-input>` is the batteries-included composer row (send button, toolbar, attachment staging) built on `<kai-composer>`, the bare editor. |
| `kai-suggestion-click` | `CustomEvent<{ value: string }>` | A suggestion was clicked while `suggestion-mode="fill"`. |
| `kai-toolbar-action` | `CustomEvent<{ action: string }>` | A custom `<kai-action>` toolbar button was clicked. `action` is the `id` of the `<kai-action>` element that was clicked. |
| `kai-value-change` | `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> }[] }>` | The input changed (fires on every edit). Carries the flattened `value` plus the structured `doc` + `entities`. |
| `kai-voice` | `CustomEvent<Record<string, never>>` | The Voice (Mic) toolbar button was clicked. |
| `kai-web-search` | `CustomEvent<Record<string, never>>` | The web-search (Globe) toolbar button was clicked. |

**Methods** (call on the element instance: `document.querySelector('kai-prompt-input').focus(…)`):

| Method | Signature | Description |
|---|---|---|
| `focus` | `(options?: FocusOptions): void` | Focus the text editor inside the shadow root (not the hidden file input). |
| `blur` | `(): void` | Blur the focused input control. |
| `clear` | `(): void` | Clear the text and any staged attachments (fires kai-value-change / kai-attachments-change so a controlled consumer can react). |
| `send` | `(): 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. |

**Slots** (project your own markup via `slot="name"` on a light-DOM child):

| Slot | Mode | Description |
|---|---|---|
| `input-top` | inject | Inside the card, above the textarea (e.g. an inline status strip). For content above/below the whole card, use your own layout; that is light DOM you control. |
| `toolbar-start` | inject | Leading controls in the input toolbar, where a + menu goes. |
| `toolbar-end` | inject | Trailing controls in the toolbar, before the Send button. |

**Declarative children** (compose these in light DOM instead of setting the JS property):

| Child element | Attributes | Text content | Notes |
|---|---|---|---|
| `<kai-action>` | `action`, `icon`, `id`, `label`, `tooltip` | yes |  |

**Styleable parts** (restyle from outside via `kai-prompt-input::part(name)`):

| Part | Description |
|---|---|
| `::part(send)` | The send button. Restyle from outside, or hide it entirely (Enter-only). Hiding is pure CSS, which is why there is no `submit="never"`. — `kai-prompt-input::part(send) { display: none } /* Enter-only; or restyle: background, border-radius, … */` |

---

### `kai-radio-group` / `RadioGroup`

**Properties** (every element also accepts `theme="light|dark|auto"`; only scalar props work as HTML attributes):

| Property | Attribute | Type | Description |
|---|---|---|---|
| `theme` | `theme` | `"light" \| "dark" \| "auto"` | Color mode (`auto` follows prefers-color-scheme). |
| `options` | — | `{ value: string; label: string; description?: undefined \| string; disabled?: undefined \| false \| true }[]` | The choices, top to bottom. Set as a JS PROPERTY (array), never an attribute. |
| `value` | `value` | `undefined \| string` | Controlled selected `value`. Settable and reflected to the `value` attribute. `el.value = 'degraded'` drives it; choosing a row updates it and fires `kai-change`. Read `el.value` for live state. |
| `name` | `name` | `undefined \| string` | Shared form-control name for every radio in the group. Defaults to a generated id, so the group is exclusive and keyboard-navigable even when nothing is submitted. |
| `disabled` | `disabled` | `undefined \| false \| true` | Disable every row. Individual rows carry their own `disabled`. |
| `label` | `label` | `undefined \| string` | Accessible name for the group. |

**Events** (non-bubbling `CustomEvent`s — listen directly on the element):

| Event | `detail` type | Description |
|---|---|---|
| `kai-change` | `CustomEvent<{ value: string }>` | A row was chosen. |

**Methods** (call on the element instance: `document.querySelector('kai-radio-group').focus(…)`):

| Method | Signature | Description |
|---|---|---|
| `focus` | `(options?: FocusOptions): void` | Focus the group's tab stop. That is the selected radio, or the first row when nothing is selected yet. |

---

### `kai-reasoning` / `Reasoning`

**Properties** (every element also accepts `theme="light|dark|auto"`; only scalar props work as HTML attributes):

| Property | Attribute | Type | Description |
|---|---|---|---|
| `theme` | `theme` | `"light" \| "dark" \| "auto"` | Color mode (`auto` follows prefers-color-scheme). |
| `text` | `text` | `string` | The reasoning text to display. |
| `label` | `label` | `undefined \| string` | Trigger label. |
| `open` | `open` | `undefined \| false \| true` | 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`. |
| `defaultOpen` | `default-open` | `undefined \| false \| true` | Initial open state on mount (uncontrolled seed). |
| `streaming` | `streaming` | `undefined \| false \| true` | While true, auto-expands (and re-collapses when it flips false). |
| `markdown` | `markdown` | `undefined \| false \| true` | Render `text` as markdown. |
| `disabled` | `disabled` | `undefined \| false \| true` | Gate the disclosure trigger: programmatic `show()/hide()/toggle()` still work, but the trigger click no longer toggles. |

**Events** (non-bubbling `CustomEvent`s — listen directly on the element):

| Event | `detail` type | Description |
|---|---|---|
| `kai-open-change` | `CustomEvent<{ open: false \| true }>` | The reasoning block expanded or collapsed (via the trigger, streaming auto-open, or a method). |

**Methods** (call on the element instance: `document.querySelector('kai-reasoning').show()`):

| Method | Signature | Description |
|---|---|---|
| `show` | `(): void` | Open it programmatically (no-op while disabled). |
| `hide` | `(): void` | Close it programmatically. |
| `toggle` | `(): void` | Flip the open state (closes while disabled). |

---

### `kai-remote` / `Remote`

**Properties** (every element also accepts `theme="light|dark|auto"`; only scalar props work as HTML attributes):

| Property | Attribute | Type | Description |
|---|---|---|---|
| `theme` | `theme` | `"light" \| "dark" \| "auto"` | Color mode (`auto` follows prefers-color-scheme). |
| `src` | `src` | `undefined \| string` | The remote card URL. Attribute: `src`. |
| `providerOrigin` | `provider-origin` | `undefined \| string` | Exact provider origin (https: or http://localhost for dev). Attribute: `provider-origin`. |
| `envelope` | — | `undefined \| Record<string, unknown>` | The card envelope to render. JS property only. |
| `policy` | — | `undefined \| Record<string, unknown>` | Optional routing policy. JS property only. |

_No events._

---

### `kai-resizable` / `Resizable`

**Properties** (every element also accepts `theme="light|dark|auto"`; only scalar props work as HTML attributes):

| Property | Attribute | Type | Description |
|---|---|---|---|
| `theme` | `theme` | `"light" \| "dark" \| "auto"` | Color mode (`auto` follows prefers-color-scheme). |
| `orientation` | `orientation` | `undefined \| "horizontal" \| "vertical"` | Layout axis: `horizontal` (row, default) or `vertical` (column). |
| `maximizedIndex` | — | `undefined \| number \| null` | Which item index is maximized (null = none). Declarative source of truth. |
| `handle` | `handle` | `undefined \| "line" \| "grip" \| "none"` | 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. |

**Events** (non-bubbling `CustomEvent`s — listen directly on the element):

| Event | `detail` type | Description |
|---|---|---|
| `kai-change` | `CustomEvent<{ sizes: number[] }>` | Fired on drag-end / keyboard resize / visibility change. `detail.sizes` = panel sizes in percent. |
| `kai-maximize-change` | `CustomEvent<{ maximized: false \| true; index: number \| null }>` | Observe layout maximize state. |
| `kai-maximize-state` | `CustomEvent<{ maximized: false \| true }>` | 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. |

**Methods** (call on the element instance: `document.querySelector('kai-resizable').maximize(…)`):

| Method | Signature | Description |
|---|---|---|
| `maximize` | `(index: number): void` | Imperatively maximize the item at `index` (thin wrapper over `maximizedIndex`). |
| `restore` | `(): void` | Imperatively restore from the maximized layout. |

**Slots** (project your own markup via `slot="name"` on a light-DOM child):

| Slot | Mode | Description |
|---|---|---|
| _(default)_ | inject | The `<kai-resizable-item>` panels, in order. Dividers are inserted between them. |

---

### `kai-resizable-item` / `ResizableItem`

**Properties** (every element also accepts `theme="light|dark|auto"`; only scalar props work as HTML attributes):

| Property | Attribute | Type | Description |
|---|---|---|---|
| `theme` | `theme` | `"light" \| "dark" \| "auto"` | Color mode (`auto` follows prefers-color-scheme). |
| `size` | `size` | `undefined \| string` | Initial main-axis size: `"280px"` (fixed) or `"25%"`/`25` (percent). Omitted → flexible. |
| `min` | `min` | `undefined \| string` | Minimum size during resize (px or %). |
| `max` | `max` | `undefined \| string` | Maximum size during resize (px or %). |
| `locked` | `locked` | `undefined \| false \| true` | Fix this panel's size; adjacent dividers become non-draggable. |
| `hidden` | `hidden` | `undefined \| false \| true` | Hide this panel; its divider is dropped and the rest reflow. |
| `collapsed` | `collapsed` | `undefined \| false \| true` | 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. |

**Events** (non-bubbling `CustomEvent`s — listen directly on the element):

| Event | `detail` type | Description |
|---|---|---|
| `kai-change` | `CustomEvent<unknown>` |  |
| `kai-maximize-change` | `CustomEvent<unknown>` |  |
| `kai-maximize-state` | `CustomEvent<unknown>` |  |

**Slots** (project your own markup via `slot="name"` on a light-DOM child):

| Slot | Mode | Description |
|---|---|---|
| _(default)_ | inject | This panel's content. |

---

### `kai-response-stream` / `ResponseStream`

**Properties** (every element also accepts `theme="light|dark|auto"`; only scalar props work as HTML attributes):

| Property | Attribute | Type | Description |
|---|---|---|---|
| `theme` | `theme` | `"light" \| "dark" \| "auto"` | Color mode (`auto` follows prefers-color-scheme). |
| `text` | — | `undefined \| string \| AsyncIterable<string>` | Text to stream. A string, or an `AsyncIterable<string>` (set as a JS property, since async iterables can't be HTML attributes). |
| `mode` | `mode` | `undefined \| "typewriter" \| "fade"` | Reveal animation. |
| `speed` | `speed` | `undefined \| number` | Characters/segments per tick. |
| `as` | `as` | `undefined \| string` | Element tag to render as. |

**Events** (non-bubbling `CustomEvent`s — listen directly on the element):

| Event | `detail` type | Description |
|---|---|---|
| `kai-complete` | `CustomEvent` | Streaming finished. |

---

### `kai-row` / `Row`

**Properties** (every element also accepts `theme="light|dark|auto"`; only scalar props work as HTML attributes):

| Property | Attribute | Type | Description |
|---|---|---|---|
| `theme` | `theme` | `"light" \| "dark" \| "auto"` | Color mode (`auto` follows prefers-color-scheme). |
| `interactive` | `interactive` | `undefined \| false \| true` | Pressable row: renders real button semantics (click, Enter, Space) and fires `kai-click` on activation. Ignored when `href` is set. |
| `href` | `href` | `undefined \| string` | Navigate on press: the row renders as a real anchor opening in a new tab. An href outside the kit's safe URL schemes renders a plain non-interactive row instead (label visible, nothing clickable). |
| `chevron` | `chevron` | `undefined \| false \| true` | Show a trailing chevron affordance at the row's end. |

**Events** (non-bubbling `CustomEvent`s — listen directly on the element):

| Event | `detail` type | Description |
|---|---|---|
| `kai-click` | `CustomEvent` | The row was activated (click, Enter or Space) while `interactive` is set and no `href` is present. Non-bubbling: listen on the element itself. |

**Slots** (project your own markup via `slot="name"` on a light-DOM child):

| Slot | Mode | Description |
|---|---|---|
| _(default)_ | inject | The row title. `leading`, `subtitle` and `trailing` are the named regions around it. |
| `leading` | inject | Leading region before the title (an icon or avatar). |
| `subtitle` | inject | Secondary line under the title. |
| `trailing` | inject | Right-aligned trailing region (a timestamp, value, or badge). |

**Styleable parts** (restyle from outside via `kai-row::part(name)`):

| Part | Description |
|---|---|
| `::part(row)` | The whole row surface: the button when interactive, the anchor when `href` is set, a plain div otherwise. — `kai-row::part(row) { border-radius: 0 }` |
| `::part(title)` | The title line (the default slot renders inside it). — `kai-row::part(title) { font-weight: 600 }` |
| `::part(chevron)` | The trailing chevron affordance (renders only with the `chevron` flag). — `kai-row::part(chevron) { color: var(--color-primary) }` |
| `::part(leading)` | Leading region before the title (an icon or avatar). |
| `::part(subtitle)` | Secondary line under the title. |
| `::part(trailing)` | Right-aligned trailing region (a timestamp, value, or badge). |

---

### `kai-scope-picker` / `ScopePicker`

**Properties** (every element also accepts `theme="light|dark|auto"`; only scalar props work as HTML attributes):

| Property | Attribute | Type | Description |
|---|---|---|---|
| `theme` | `theme` | `"light" \| "dark" \| "auto"` | Color mode (`auto` follows prefers-color-scheme). |
| `availableAuthors` | — | `undefined \| string[]` | Authors to offer as scope filters. Omit to drop the Authors section (for a tag-only picker). Set as a JS property. |
| `availableTags` | — | `undefined \| string[]` | Tags to offer as scope filters. Omit to drop the Tags section (for an author-only picker). Set as a JS property. |
| `currentLabel` | `current-label` | `undefined \| string` | The label shown on the trigger for the active scope. |
| `open` | `open` | `undefined \| false \| true` | 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`. |
| `defaultOpen` | `default-open` | `undefined \| false \| true` | Initial open state on mount (uncontrolled seed). |
| `disabled` | `disabled` | `undefined \| false \| true` | Disable the trigger: click/keyboard and `show()` no longer open the dropdown. |

**Events** (non-bubbling `CustomEvent`s — listen directly on the element):

| Event | `detail` type | Description |
|---|---|---|
| `kai-open-change` | `CustomEvent<{ open: false \| true }>` | The scope dropdown opened or closed (by click, keyboard, Escape, outside-click, or a method). |
| `kai-scope-change` | `CustomEvent<{ filters: { tags?: undefined \| string[]; authors?: undefined \| string[]; contentType?: undefined \| "transcript" \| "markdown"; dateRange?: undefined \| { from: string; to: string } } \| undefined }>` | A scope was chosen (`undefined` filters = "All Content"). |

**Methods** (call on the element instance: `document.querySelector('kai-scope-picker').show()`):

| Method | Signature | Description |
|---|---|---|
| `show` | `(): void` | Open it programmatically (no-op while disabled). |
| `hide` | `(): void` | Close it programmatically. |
| `toggle` | `(): void` | Flip the open state (closes while disabled). |

---

### `kai-screen` / `Screen`

**Properties** (every element also accepts `theme="light|dark|auto"`; only scalar props work as HTML attributes):

| Property | Attribute | Type | Description |
|---|---|---|---|
| `theme` | `theme` | `"light" \| "dark" \| "auto"` | Color mode (`auto` follows prefers-color-scheme). |
| `open` | `open` | `undefined \| false \| true` | 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`. |
| `defaultOpen` | `default-open` | `undefined \| false \| true` | Initial open state on mount (uncontrolled seed). |
| `headline` | `headline` | `undefined \| string` | Header title text. A projected `title` slot overrides it. (Named `headline` because `title` collides with the global `HTMLElement.title` attribute.) |
| `back` | `back` | `undefined \| false \| true` | Show the back button (default true). |
| `noInert` | `no-inert` | `undefined \| false \| true` | Opt out of marking sibling elements inert/aria-hidden while open (for unusual layouts). |

**Events** (non-bubbling `CustomEvent`s — listen directly on the element):

| Event | `detail` type | Description |
|---|---|---|
| `kai-back` | `CustomEvent<Record<string, never>>` | Back navigation intent: the back button or Escape. The consumer flips their own routing in response (the screen knows nothing about the trigger). |
| `kai-open-change` | `CustomEvent<{ open: false \| true }>` | The screen opened or closed (a method, `Escape` close, or driven `open`). |

**Methods** (call on the element instance: `document.querySelector('kai-screen').show()`):

| Method | Signature | Description |
|---|---|---|
| `show` | `(): void` | Open it programmatically (no-op while disabled). |
| `hide` | `(): void` | Close it programmatically. |
| `toggle` | `(): void` | Flip the open state (closes while disabled). |
| `focus` | `(options?: FocusOptions): void` | Move focus to the screen surface (no-op while closed). |

**Slots** (project your own markup via `slot="name"` on a light-DOM child):

| Slot | Mode | Description |
|---|---|---|
| _(default)_ | inject | The screen body, below the title bar. |
| `title` | replace | Rich header title; overrides the `headline` prop. |
| `actions` | inject | Header trailing cluster (e.g. an avatar or overflow menu). |

**Styleable parts** (restyle from outside via `kai-screen::part(name)`):

| Part | Description |
|---|---|
| `::part(header)` | The back-header bar (back button + title + actions). Restyle its height, padding, or border from outside. — `kai-screen::part(header) { height: 3.25rem; padding-inline: 1rem }` |
| `::part(back)` | The back button. Restyle or hide it from outside; `back="false"` removes it entirely. — `kai-screen::part(back) { border-radius: 9999px }` |
| `::part(body)` | The full-bleed surface that fills the mount point and scrolls its content. Tune padding or background from outside. — `kai-screen::part(body) { background: var(--color-card) }` |
| `::part(title)` | Rich header title; overrides the `headline` prop. |

---

### `kai-scroll-area` / `ScrollArea`

**Properties** (every element also accepts `theme="light|dark|auto"`; only scalar props work as HTML attributes):

| Property | Attribute | Type | Description |
|---|---|---|---|
| `theme` | `theme` | `"light" \| "dark" \| "auto"` | Color mode (`auto` follows prefers-color-scheme). |
| `orientation` | `orientation` | `undefined \| "vertical" \| "horizontal" \| "both"` | Which axis scrolls. `vertical` (default) · `horizontal` · `both`. The cross axis is clamped so content can't overflow it. |

_No events._

**Slots** (project your own markup via `slot="name"` on a light-DOM child):

| Slot | Mode | Description |
|---|---|---|
| _(default)_ | inject | The scrollable content. |

**Styleable parts** (restyle from outside via `kai-scroll-area::part(name)`):

| Part | Description |
|---|---|
| `::part(viewport)` | The scrolling container. Add padding or a max-height from outside; the thin scrollbar follows `--color-scrollbar-thumb`. — `kai-scroll-area::part(viewport) { padding-right: 0.5rem }` |

---

### `kai-scroll-button` / `ScrollButton`

**Properties** (every element also accepts `theme="light|dark|auto"`; only scalar props work as HTML attributes):

| Property | Attribute | Type | Description |
|---|---|---|---|
| `theme` | `theme` | `"light" \| "dark" \| "auto"` | Color mode (`auto` follows prefers-color-scheme). |
| `for` | `for` | `undefined \| string` | 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="...">`. |
| `variant` | `variant` | `undefined \| "outline" \| "ghost" \| "default"` | Button visual variant: `'outline' \| 'ghost' \| 'default'`. Defaults to `'outline'`. |
| `size` | `size` | `undefined \| "sm" \| "md" \| "lg" \| "icon" \| "icon-sm"` | Button size token. Defaults to `'icon'` (square). |
| `label` | `label` | `undefined \| string` | The button's accessible name. It is announced whether or not the label is visible, so the text is always localisable. Defaults to `'Scroll to bottom'`. |
| `showLabel` | `show-label` | `undefined \| false \| true` | Also render `label` visibly beside the icon. Defaults to `false`, which is the icon-only button. When the text is visible it IS the accessible name, so nothing gets announced twice. |

**Events** (non-bubbling `CustomEvent`s — listen directly on the element):

| Event | `detail` type | Description |
|---|---|---|
| `kai-scroll` | `CustomEvent` | Emitted when the user clicks the button and `scrollToBottom()` is called. Carries no detail; consumers use it to know a manual scroll occurred. |

---

### `kai-search` / `Search`

**Properties** (every element also accepts `theme="light|dark|auto"`; only scalar props work as HTML attributes):

| Property | Attribute | Type | Description |
|---|---|---|---|
| `theme` | `theme` | `"light" \| "dark" \| "auto"` | Color mode (`auto` follows prefers-color-scheme). |
| `value` | `value` | `undefined \| string` | Controlled query. Settable and reflected to the `value` attribute. Read `el.value` for live state. |
| `placeholder` | `placeholder` | `undefined \| string` | Placeholder. Defaults to `Search…`. |
| `icon` | `icon` | `undefined \| 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`. |
| `debounce` | `debounce` | `undefined \| number` | Debounce window for `kai-search`, in ms. Defaults to `200`. |
| `loading` | `loading` | `undefined \| false \| true` | Show a spinner in place of the leading icon while results load. |
| `shortcut` | `shortcut` | `undefined \| string` | 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. |

**Events** (non-bubbling `CustomEvent`s — listen directly on the element):

| Event | `detail` type | Description |
|---|---|---|
| `kai-change` | `CustomEvent<{ value: string }>` | The field committed (blur). |
| `kai-search` | `CustomEvent<{ value: string }>` | The query changed (debounced live, and on clear). |
| `kai-submit` | `CustomEvent<{ value: string }>` | Enter was pressed. |

**Methods** (call on the element instance: `document.querySelector('kai-search').focus()`):

| Method | Signature | Description |
|---|---|---|
| `focus` | `(): void` | Focus the search input inside the shadow root. A native `focus()` on the host lands on the host itself and never reaches it. |
| `clear` | `(): 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. |

**Styleable parts** (restyle from outside via `kai-search::part(name)`):

| Part | Description |
|---|---|
| `::part(field)` | The bordered control box (the row wrapping the search icon, input, and clear button). — `kai-search::part(field) { border-radius: 9999px }` |
| `::part(input)` | The inner search input element. — `kai-search::part(input) { font-size: 0.875rem }` |
| `::part(clear)` | The trailing clear ("x") button, shown when the field is non-empty. — `kai-search::part(clear) { opacity: 1 }` |

---

### `kai-segmented` / `Segmented`

**Properties** (every element also accepts `theme="light|dark|auto"`; only scalar props work as HTML attributes):

| Property | Attribute | Type | Description |
|---|---|---|---|
| `theme` | `theme` | `"light" \| "dark" \| "auto"` | Color mode (`auto` follows prefers-color-scheme). |
| `options` | — | `{ value: string; label: string; icon?: undefined \| string }[]` | The selectable segments, left to right. Set as a JS property (array). |
| `value` | `value` | `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. |
| `size` | `size` | `undefined \| "sm" \| "md"` | Control density: `sm` or `md`. Defaults to `md`. |

**Events** (non-bubbling `CustomEvent`s — listen directly on the element):

| Event | `detail` type | Description |
|---|---|---|
| `kai-change` | `CustomEvent<{ value: string }>` | A segment was chosen. |

**Styleable parts** (restyle from outside via `kai-segmented::part(name)`):

| Part | Description |
|---|---|
| `::part(track)` | The segmented track (the pill container holding the segments). Restyle its background, radius, or padding. — `kai-segmented::part(track) { border-radius: 9999px }` |
| `::part(segment)` | Each segment button. Restyle padding, font weight, or the selected look. — `kai-segmented::part(segment) { font-weight: 600 }` |

---

### `kai-select` / `Select`

**Properties** (every element also accepts `theme="light|dark|auto"`; only scalar props work as HTML attributes):

| Property | Attribute | Type | Description |
|---|---|---|---|
| `theme` | `theme` | `"light" \| "dark" \| "auto"` | Color mode (`auto` follows prefers-color-scheme). |
| `options` | — | `{ value: string; label?: undefined \| string; disabled?: undefined \| false \| true }[]` | The choices, in display order. Set as a JS PROPERTY (array), never an attribute. Rendered in full: the kit never truncates, re-orders or de-duplicates them. |
| `value` | `value` | `undefined \| string` | Controlled selected value. Settable and reflected to the `value` attribute. `el.value = 'high'` drives it; choosing an option updates it and fires `kai-change`. Read `el.value` for live state; for a `multiple` select read `el.values` instead. |
| `placeholder` | `placeholder` | `undefined \| string` | Text for a leading, disabled, empty option: the "nothing chosen yet" row. Omitted means no such row at all; there is no default wording, because inventing one would put words in your UI. |
| `multiple` | `multiple` | `undefined \| false \| true` | Allow more than one selection. Turns the control into the platform's list box, so the kit's chevron is not drawn. |
| `invalid` | `invalid` | `undefined \| false \| true` | Force the invalid (destructive-border) state. |
| `disabled` | `disabled` | `undefined \| false \| true` | Disable interaction. |
| `required` | `required` | `undefined \| false \| true` | Set the native `required` attribute, and nothing more. Whether an empty select is an error is the application's rule, not the kit's. |
| `label` | `label` | `undefined \| string` | Accessible label for the control. |
| `name` | `name` | `undefined \| string` | Form-control name, for a native form submit. |

**Events** (non-bubbling `CustomEvent`s — listen directly on the element):

| Event | `detail` type | Description |
|---|---|---|
| `kai-change` | `CustomEvent<{ value: string; values: string[] }>` | A choice was made. `value` is the first selected option (empty when nothing is selected); `values` is every selected option, which is what a `multiple` select needs. Both are always present, so neither shape silently loses the other. |

**Methods** (call on the element instance: `document.querySelector('kai-select').focus(…)`):

| Method | Signature | Description |
|---|---|---|
| `focus` | `(options?: FocusOptions): void` | Focus the inner select (the host element can't reach it). |

---

### `kai-separator` / `Separator`

**Properties** (every element also accepts `theme="light|dark|auto"`; only scalar props work as HTML attributes):

| Property | Attribute | Type | Description |
|---|---|---|---|
| `theme` | `theme` | `"light" \| "dark" \| "auto"` | Color mode (`auto` follows prefers-color-scheme). |
| `orientation` | `orientation` | `undefined \| "horizontal" \| "vertical"` | `horizontal` (default, block + full-width) or `vertical` (a rule inside a flex/grid row, stretching to the row height). |

_No events._

**Styleable parts** (restyle from outside via `kai-separator::part(name)`):

| Part | Description |
|---|---|
| `::part(separator)` | The divider line. Restyle its color, thickness, or inset from outside. — `kai-separator::part(separator) { background: var(--color-border) }` |

---

### `kai-setting-item` / `SettingItem`

**Properties** (every element also accepts `theme="light|dark|auto"`; only scalar props work as HTML attributes):

| Property | Attribute | Type | Description |
|---|---|---|---|
| `theme` | `theme` | `"light" \| "dark" \| "auto"` | Color mode (`auto` follows prefers-color-scheme). |
| `label` | `label` | `undefined \| string` | Row label (primary text). Attribute: `label`. |
| `description` | `description` | `undefined \| string` | Optional secondary description under the label. Attribute: `description`. |

_No events._

**Slots** (project your own markup via `slot="name"` on a light-DOM child):

| Slot | Mode | Description |
|---|---|---|
| `control` | inject | The row control (a switch, segmented, select, etc.), right-aligned. Omit it for a label-only row. |

**Styleable parts** (restyle from outside via `kai-setting-item::part(name)`):

| Part | Description |
|---|---|
| `::part(label)` | The label + description block on the left of the row. Restyle its typography or spacing. — `kai-setting-item::part(label) { gap: 0.125rem }` |
| `::part(control)` | The row control (a switch, segmented, select, etc.), right-aligned. Omit it for a label-only row. |

---

### `kai-settings-group` / `SettingsGroup`

**Properties** (every element also accepts `theme="light|dark|auto"`; only scalar props work as HTML attributes):

| Property | Attribute | Type | Description |
|---|---|---|---|
| `theme` | `theme` | `"light" \| "dark" \| "auto"` | Color mode (`auto` follows prefers-color-scheme). |
| `heading` | `heading` | `undefined \| string` | Small section heading shown above the card. Attribute: `heading`. |
| `description` | `description` | `undefined \| string` | Optional muted description under the heading. Attribute: `description`. |

_No events._

**Slots** (project your own markup via `slot="name"` on a light-DOM child):

| Slot | Mode | Description |
|---|---|---|
| _(default)_ | inject | The `<kai-setting-item>` rows in this group. |

**Styleable parts** (restyle from outside via `kai-settings-group::part(name)`):

| Part | Description |
|---|---|
| `::part(header)` | The group heading + description block. Restyle its spacing or typography. — `kai-settings-group::part(header) { margin-bottom: 0.75rem }` |
| `::part(body)` | The bordered card holding the setting rows. Restyle its surface, border, or radius. — `kai-settings-group::part(body) { border-radius: 1rem }` |

---

### `kai-skeleton` / `Skeleton`

**Properties** (every element also accepts `theme="light|dark|auto"`; only scalar props work as HTML attributes):

| Property | Attribute | Type | Description |
|---|---|---|---|
| `theme` | `theme` | `"light" \| "dark" \| "auto"` | Color mode (`auto` follows prefers-color-scheme). |
| `variant` | `variant` | `undefined \| "text" \| "rect" \| "circle"` | `text` (one or more lines), `rect` (a block), or `circle` (round). Defaults to `text`. |
| `width` | `width` | `undefined \| string` | CSS width (e.g. `'12rem'`, `'60%'`). Defaults to full width (responsive); for `circle` it is the diameter. |
| `height` | `height` | `undefined \| string` | CSS height. Defaults per variant (a text line height; circle = width). |
| `lines` | `lines` | `undefined \| number` | `text` only: number of lines; the last is shorter. Defaults to 1. |

_No events._

**Styleable parts** (restyle from outside via `kai-skeleton::part(name)`):

| Part | Description |
|---|---|
| `::part(skeleton)` | The shimmer block(s). Recolor or change the opacity from outside; the default is a low-contrast foreground tint that reads in both light and dark. — `kai-skeleton::part(skeleton) { background: var(--color-primary); opacity: 0.15 }` |

---

### `kai-skills` / `Skills`

**Properties** (every element also accepts `theme="light|dark|auto"`; only scalar props work as HTML attributes):

| Property | Attribute | Type | Description |
|---|---|---|---|
| `theme` | `theme` | `"light" \| "dark" \| "auto"` | Color mode (`auto` follows prefers-color-scheme). |
| `skills` | — | `undefined \| { id: string; name: string }[]` | 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. |

_No events._

**Declarative children** (compose these in light DOM instead of setting the JS property):

| Child element | Attributes | Text content | Notes |
|---|---|---|---|
| `<kai-skill>` | `id` | yes | Parse a single light-DOM `<kai-skill>` element into a `Skill` descriptor. Attribute / content mapping: - `id` → Skill.id (falls back to `name` when absent) - `textContent` → Skill.name (the human-readable badge label) Example: `<kai-skill id="web-search">Web Search</kai-skill>` |

---

### `kai-slider` / `Slider`

**Properties** (every element also accepts `theme="light|dark|auto"`; only scalar props work as HTML attributes):

| Property | Attribute | Type | Description |
|---|---|---|---|
| `theme` | `theme` | `"light" \| "dark" \| "auto"` | Color mode (`auto` follows prefers-color-scheme). |
| `min` | `min` | `undefined \| number` | Lowest selectable value. Required: a range with no bounds is a guess, and the guess belongs to whoever knows what the number means. |
| `max` | `max` | `undefined \| number` | Highest selectable value. Required, for the same reason as `min`. |
| `step` | `step` | `undefined \| number \| "any"` | Granularity. Omitted means the native default of 1; `any` means continuous. |
| `value` | `value` | `undefined \| number` | Controlled value. Settable and reflected to the `value` attribute. `el.value = 40` drives it; dragging updates it and fires `kai-input` per step, `kai-change` on release. Read `el.value` for live state. |
| `disabled` | `disabled` | `undefined \| false \| true` | Disable interaction. |
| `label` | `label` | `undefined \| string` | Accessible label for the slider. |
| `name` | `name` | `undefined \| string` | Form-control name, for a native form submit. |
| `valueLabel` | — | `undefined \| false \| true \| ((value: number) => string)` | Show the current value beside the track. Off by default. Two ways in, because one of them is not a scalar. As a bare ATTRIBUTE (`<kai-slider value-label>`) it renders the raw number. As a JS PROPERTY it also accepts a formatter function (`el.valueLabel = (v) => v + '%'`), for a slider that is not counting bare numbers. A function cannot survive an attribute, so that half is property-only. The readout is hidden from assistive tech: the slider already reports the same number, and an exposed copy would be announced twice. |

**Events** (non-bubbling `CustomEvent`s — listen directly on the element):

| Event | `detail` type | Description |
|---|---|---|
| `kai-change` | `CustomEvent<{ value: number }>` | The value was committed: pointer released, or a key press finished. |
| `kai-input` | `CustomEvent<{ value: number }>` | The thumb moved. Fires per step during a drag or a key press. |

**Methods** (call on the element instance: `document.querySelector('kai-slider').focus(…)`):

| Method | Signature | Description |
|---|---|---|
| `focus` | `(options?: FocusOptions): void` | Focus the inner range input (the host element can't reach it). |

---

### `kai-source` / `Source`

**Properties** (every element also accepts `theme="light|dark|auto"`; only scalar props work as HTML attributes):

| Property | Attribute | Type | Description |
|---|---|---|---|
| `theme` | `theme` | `"light" \| "dark" \| "auto"` | Color mode (`auto` follows prefers-color-scheme). |
| `href` | `href` | `undefined \| string` | The URL this citation links to (the domain also seeds the default label/favicon). |
| `label` | `label` | `undefined \| string` | Trigger label (defaults to the domain). |
| `headline` | `headline` | `undefined \| 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). |
| `description` | `description` | `undefined \| string` | Hover-card body text describing the source. |
| `showFavicon` | `show-favicon` | `undefined \| false \| true` | Show the source's favicon next to the trigger label. |

_No events._

---

### `kai-sources` / `Sources`

**Properties** (every element also accepts `theme="light|dark|auto"`; only scalar props work as HTML attributes):

| Property | Attribute | Type | Description |
|---|---|---|---|
| `theme` | `theme` | `"light" \| "dark" \| "auto"` | Color mode (`auto` follows prefers-color-scheme). |
| `sources` | — | `undefined \| { href: string; title?: undefined \| string; description?: undefined \| string; label?: undefined \| string; showFavicon?: undefined \| false \| true }[]` | 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. |
| `showFavicon` | `show-favicon` | `undefined \| false \| true` | Show favicons on all items (per-item `showFavicon` overrides). |
| `numbered` | `numbered` | `undefined \| false \| 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`. |

_No events._

**Declarative children** (compose these in light DOM instead of setting the JS property):

| Child element | Attributes | Text content | Notes |
|---|---|---|---|
| `<kai-source>` | `description`, `headline`, `href`, `label`, `show-favicon` | — | Parse a single light-DOM `<kai-source>` element into a `KaiSourceItem` descriptor. Attribute mapping: - `href` → KaiSourceItem.href - `label` → KaiSourceItem.label - `headline` → KaiSourceItem.title (matches kai-source's prop name; "title" is a reserved HTMLElement attribute so kai-source uses "headline") - `description` → KaiSourceItem.description - `show-favicon`→ KaiSourceItem.showFavicon (bare boolean attribute) |

---

### `kai-status` / `Status`

**Properties** (every element also accepts `theme="light|dark|auto"`; only scalar props work as HTML attributes):

| Property | Attribute | Type | Description |
|---|---|---|---|
| `theme` | `theme` | `"light" \| "dark" \| "auto"` | Color mode (`auto` follows prefers-color-scheme). |
| `status` | `status` | `undefined \| "new" \| "online" \| "busy" \| "away" \| "offline"` | Presence/notification state → color. `new` (default) maps to the blue hue. |
| `pulse` | `pulse` | `undefined \| false \| true` | Animated ping ring (off by default; respects prefers-reduced-motion). |
| `label` | `label` | `undefined \| string` | Accessible name. Without it the dot is decorative. |
| `size` | `size` | `undefined \| "sm" \| "md"` | `sm` (default) or `md`. |

_No events._

**Styleable parts** (restyle from outside via `kai-status::part(name)`):

| Part | Description |
|---|---|
| `::part(dot)` | The status dot. Recolor or resize it from outside; the `status` prop sets the default hue. — `kai-status::part(dot) { background: var(--color-tool-green) }` |

---

### `kai-suggestions` / `Suggestions`

**Properties** (every element also accepts `theme="light|dark|auto"`; only scalar props work as HTML attributes):

| Property | Attribute | Type | Description |
|---|---|---|---|
| `theme` | `theme` | `"light" \| "dark" \| "auto"` | Color mode (`auto` follows prefers-color-scheme). |
| `suggestions` | — | `undefined \| (string \| { label: string; value?: undefined \| string; icon?: undefined \| string })[]` | 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. |
| `variant` | `variant` | `undefined \| "outline" \| "ghost" \| "default"` | Chip style: `'outline'` (default), `'ghost'`, or `'default'` (filled). |
| `size` | `size` | `undefined \| "md" \| "lg"` | Row height for `layout="list"`: `'md'` (default) or `'lg'` for taller rows. Chips are unaffected. |
| `layout` | `layout` | `undefined \| "chips" \| "list"` | 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. |
| `block` | `block` | `undefined \| false \| true` | Full-width left-aligned rows instead of pills. |
| `highlight` | `highlight` | `undefined \| string` | Substring to highlight within each suggestion. |

**Events** (non-bubbling `CustomEvent`s — listen directly on the element):

| Event | `detail` type | Description |
|---|---|---|
| `kai-select` | `CustomEvent<{ value: string }>` | A suggestion was clicked. |

**Declarative children** (compose these in light DOM instead of setting the JS property):

| Child element | Attributes | Text content | Notes |
|---|---|---|---|
| `<kai-suggestion>` | `icon`, `value` | yes | Parse a single `<kai-suggestion>` node into an `Item` descriptor. |

---

### `kai-switch` / `Switch`

**Properties** (every element also accepts `theme="light|dark|auto"`; only scalar props work as HTML attributes):

| Property | Attribute | Type | Description |
|---|---|---|---|
| `theme` | `theme` | `"light" \| "dark" \| "auto"` | Color mode (`auto` follows prefers-color-scheme). |
| `checked` | `checked` | `undefined \| false \| true` | 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. |
| `defaultChecked` | `default-checked` | `undefined \| false \| true` | Initial checked state on mount (uncontrolled seed). Bare attribute (`<kai-switch default-checked>`) turns it on. |
| `disabled` | `disabled` | `undefined \| false \| true` | Disable interaction. |
| `label` | `label` | `undefined \| string` | Accessible label. |
| `name` | `name` | `undefined \| string` | Form-control name (paired with `value`). |
| `value` | `value` | `undefined \| string` | Submitted value when checked (paired with `name`). Defaults to `'on'`. |

**Events** (non-bubbling `CustomEvent`s — listen directly on the element):

| Event | `detail` type | Description |
|---|---|---|
| `kai-change` | `CustomEvent<{ checked: false \| true }>` | The toggle changed. |

**Methods** (call on the element instance: `document.querySelector('kai-switch').toggle()`):

| Method | Signature | Description |
|---|---|---|
| `toggle` | `(): void` | Flip the switch and fire `kai-change` (no-op while disabled). |
| `focus` | `(options?: FocusOptions): void` | Focus the inner `role="switch"` button (the host element can't reach it). |

---

### `kai-tab-bar` / `TabBar`

**Properties** (every element also accepts `theme="light|dark|auto"`; only scalar props work as HTML attributes):

| Property | Attribute | Type | Description |
|---|---|---|---|
| `theme` | `theme` | `"light" \| "dark" \| "auto"` | Color mode (`auto` follows prefers-color-scheme). |
| `value` | `value` | `undefined \| string` | Controlled selected value. Set the property or the `value` attribute and drive it from your app in response to `kai-tab-change`. Omit for uncontrolled: the bar manages its own selection, seeded from `defaultValue`, else the first enabled tab. |
| `defaultValue` | `default-value` | `undefined \| string` | Initial selected value when uncontrolled (the `default-value` attribute in plain HTML). |
| `iconOnly` | `icon-only` | `undefined \| false \| true` | Icon-only mode: every tab hides its label visually. The slotted labels still name the tabs for assistive tech. |
| `label` | `label` | `undefined \| string` | Accessible name for the tablist (default "Navigation"). |

**Events** (non-bubbling `CustomEvent`s — listen directly on the element):

| Event | `detail` type | Description |
|---|---|---|
| `kai-tab-change` | `CustomEvent<{ value: string }>` | A tab was selected (click, Enter/Space, or arrow-key move). `value` is the item's `value` attribute, else its host `id`. |

**Methods** (call on the element instance: `document.querySelector('kai-tab-bar').select(…)`):

| Method | Signature | Description |
|---|---|---|
| `select` | `(next: string): void` | Select a tab by value (fires `kai-tab-change`). Ignores unknown and disabled values. |
| `focus` | `(): void` | Focus the active tab (or the first focusable tab). |

**Slots** (project your own markup via `slot="name"` on a light-DOM child):

| Slot | Mode | Description |
|---|---|---|
| _(default)_ | inject | The `<kai-tab-bar-item>` tabs, direct children in tab order. |

**Styleable parts** (restyle from outside via `kai-tab-bar::part(name)`):

| Part | Description |
|---|---|
| `::part(tablist)` | The bar itself: the `role="tablist"` row the item children slot into. — `kai-tab-bar::part(tablist) { border-top: 1px solid var(--color-border) }` |

---

### `kai-tab-bar-item` / `TabBarItem`

**Properties** (every element also accepts `theme="light|dark|auto"`; only scalar props work as HTML attributes):

| Property | Attribute | Type | Description |
|---|---|---|---|
| `theme` | `theme` | `"light" \| "dark" \| "auto"` | Color mode (`auto` follows prefers-color-scheme). |
| `value` | `value` | `undefined \| string` | The tab's identity: the `value` attribute (host `id` is the fallback). It is the `value` in the bar's `kai-tab-change` detail. |
| `icon` | `icon` | `undefined \| string` | Named icon from the kit roster (e.g. "home", "message-square"). The icon renders at the element's own default size, so equal glyphs across tabs need no consumer sizing. |
| `dot` | `dot` | `undefined \| false \| true` | Unread dot on the icon's corner. Reaches the tab's accessible name too: a dot alone is invisible to assistive tech. |
| `badge` | `badge` | `undefined \| string \| number` | Count badge on the icon's corner; wins over `dot` when both are set. Reaches the accessible name too. |
| `disabled` | `disabled` | `undefined \| false \| true` | Disabled tabs are skipped by arrow keys and cannot be selected. |
| `active` | `active` | `undefined \| false \| true` | Selected state. Inside `<kai-tab-bar>` the bar drives it from its `value`; the active tab retints with the primary token. |
| `iconOnly` | `icon-only` | `undefined \| false \| true` | Hide the label visually (the slotted text still names the tab for assistive tech). Inside `<kai-tab-bar>` the bar drives it from its own `icon-only` attribute. |

_No events._

**Slots** (project your own markup via `slot="name"` on a light-DOM child):

| Slot | Mode | Description |
|---|---|---|
| _(default)_ | inject | The tab's label text (it also names the tab for assistive tech, even in icon-only mode). |

**Styleable parts** (restyle from outside via `kai-tab-bar-item::part(name)`):

| Part | Description |
|---|---|
| `::part(tab)` | The tab button (icon-over-label column). Carries `data-active` while selected. — `kai-tab-bar-item::part(tab) { gap: 2px }` |

---

### `kai-tabs` / `Tabs`

**Properties** (every element also accepts `theme="light|dark|auto"`; only scalar props work as HTML attributes):

| Property | Attribute | Type | Description |
|---|---|---|---|
| `theme` | `theme` | `"light" \| "dark" \| "auto"` | Color mode (`auto` follows prefers-color-scheme). |
| `items` | — | `undefined \| { id: string; label?: undefined \| string; icon?: undefined \| string; disabled?: undefined \| false \| true }[]` | Tabs to render. Set as a JS property, not an HTML attribute. |
| `value` | `value` | `undefined \| string` | 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. |
| `defaultValue` | `default-value` | `undefined \| string` | Initial selected id when uncontrolled (use the `default-value` attribute in plain HTML). |
| `variant` | `variant` | `undefined \| "segmented" \| "underline"` | `segmented` (default, a pill group) or `underline` (an underlined row). |
| `block` | `block` | `undefined \| false \| true` | Stretch the strip to full width, each tab sharing the space equally. |
| `disabled` | `disabled` | `undefined \| false \| true` | Disable the whole strip. |

**Events** (non-bubbling `CustomEvent`s — listen directly on the element):

| Event | `detail` type | Description |
|---|---|---|
| `kai-tab-change` | `CustomEvent<{ value: string }>` | A tab was selected (click, Enter/Space, or arrow-key move). `value` is the item's id. |

**Methods** (call on the element instance: `document.querySelector('kai-tabs').select(…)`):

| Method | Signature | Description |
|---|---|---|
| `select` | `(id: string): void` | Select a tab by id (fires `kai-tab-change`). Ignores unknown/disabled ids. |
| `focus` | `(): void` | Focus the active tab (or the first focusable tab). |

**Styleable parts** (restyle from outside via `kai-tabs::part(name)`):

| Part | Description |
|---|---|
| `::part(tablist)` | The tab strip container (role="tablist"). Restyle its gap, padding, background, or radius from outside; the `variant` prop sets the segmented/underline defaults. — `kai-tabs::part(tablist) { gap: 0.5rem; background: var(--color-card) }` |
| `::part(tab)` | A single tab button. Restyle from outside; the active tab carries a `[data-active]` attribute, so target `::part(tab)[data-active]` for the selected look. — `kai-tabs::part(tab)[data-active] { color: var(--color-primary); font-weight: 600 }` |

---

### `kai-tasks` / `Tasks`

**Properties** (every element also accepts `theme="light|dark|auto"`; only scalar props work as HTML attributes):

| Property | Attribute | Type | Description |
|---|---|---|---|
| `theme` | `theme` | `"light" \| "dark" \| "auto"` | Color mode (`auto` follows prefers-color-scheme). |
| `data` | — | `undefined \| { mode?: undefined \| "select" \| "progress"; heading?: undefined \| string; tasks: { id: string; label: string; description?: undefined \| string; checked?: undefined \| false \| true; disabled?: undefined \| false \| true }[]; selectAll?: undefined \| false \| true; confirmLabel?: undefined \| string; allowEmpty?: undefined \| false \| true; min?: undefined \| number; max?: undefined \| number; dismissible?: undefined \| false \| true }` | 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. |
| `cardId` | `card-id` | `undefined \| string` | Stable card id correlating every emitted CardEvent. Attribute: `card-id`. |
| `heading` | `heading` | `undefined \| string` | Heading rendered in the card chrome (= CardEnvelope.title). Attribute: `heading`. |
| `resolution` | — | `undefined \| Record<string, unknown>` | Set when the user resolved this card; renders the read-only view. Property: `el.resolution = { kind:'submit', data:{ selected:[…] } }`. |
| `value` | — | `undefined \| string[]` | Controlled selection (task ids; JS property). When set, it wins over local state. |
| `defaultValue` | — | `undefined \| string[]` | Uncontrolled initial selection (task ids; JS property), overlaying per-task `checked`. |
| `disabled` | `disabled` | `undefined \| false \| true` | Freeze the whole list + Confirm. Attribute: `disabled`. |
| `readonly` | `readonly` | `undefined \| false \| true` | 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`. |

**Events** (non-bubbling `CustomEvent`s — listen directly on the element):

| Event | `detail` type | Description |
|---|---|---|
| `kai-value-change` | `CustomEvent<{ value: string[] }>` | The selection changed on a toggle. Carries the selected ids in input order. |

**Methods** (call on the element instance: `document.querySelector('kai-tasks').select(…)`):

| Method | Signature | Description |
|---|---|---|
| `select` | `(taskIds?: string[]): void` | Set the checked task ids (local-only, no emit), respecting disabled/max. With no arg, select all toggleable rows. |
| `toggle` | `(taskId: string, checked?: boolean): void` | Toggle one task by id, honoring the max gate (no `checked` = flip). |
| `send` | `(): void` | Confirm the current selection: emits the `submit` CardEvent + resolves (only when the min/max gate passes). Named `send`, not `submit`. |
| `focus` | `(options?: FocusOptions): void` | Focus the task group (select-all checkbox if shown, else the first row). |
| `dismiss` | `(): void` | Trigger the dismiss path (emit `dismiss` + collapse to the re-openable stub). |
| `reopen` | `(): void` | Re-open a dismissed card from its stub (emit `reopen`). |

---

### `kai-text-shimmer` / `TextShimmer`

**Properties** (every element also accepts `theme="light|dark|auto"`; only scalar props work as HTML attributes):

| Property | Attribute | Type | Description |
|---|---|---|---|
| `theme` | `theme` | `"light" \| "dark" \| "auto"` | Color mode (`auto` follows prefers-color-scheme). |
| `text` | `text` | `undefined \| string` | The text to shimmer. |
| `as` | `as` | `undefined \| string` | Element tag to render as (default `span`). |
| `duration` | `duration` | `undefined \| number` | Animation duration in seconds. |
| `spread` | `spread` | `undefined \| number` | Gradient spread (5–45). |

_No events._

---

### `kai-thinking-bar` / `ThinkingBar`

**Properties** (every element also accepts `theme="light|dark|auto"`; only scalar props work as HTML attributes):

| Property | Attribute | Type | Description |
|---|---|---|---|
| `theme` | `theme` | `"light" \| "dark" \| "auto"` | Color mode (`auto` follows prefers-color-scheme). |
| `text` | `text` | `undefined \| string` | The shimmering label, e.g. "Thinking…". |
| `stoppable` | `stoppable` | `undefined \| false \| true` | When true, show a "stop" affordance that fires a `stop` event. |
| `stopLabel` | `stop-label` | `undefined \| string` | Label for the stop affordance. |

**Events** (non-bubbling `CustomEvent`s — listen directly on the element):

| Event | `detail` type | Description |
|---|---|---|
| `kai-stop` | `CustomEvent` | The "stop / answer now" affordance was clicked. |

---

### `kai-thread` / `Thread`

**Properties** (every element also accepts `theme="light|dark|auto"`; only scalar props work as HTML attributes):

| Property | Attribute | Type | Description |
|---|---|---|---|
| `theme` | `theme` | `"light" \| "dark" \| "auto"` | Color mode (`auto` follows prefers-color-scheme). |
| `messages` | — | `undefined \| { id: string; role: "user" \| "assistant"; parts: ({ type: "text"; text: string; raw?: undefined \| { source: string; payload: unknown } } \| { type: "reasoning"; text: string; label?: undefined \| string; index?: undefined \| number; streamId?: undefined \| string; signature?: undefined \| string; raw?: undefined \| { source: string; payload: unknown } } \| { type: "tool"; tool: { type: string; kind?: undefined \| "command" \| "file-change" \| "search" \| "fetch" \| "mcp" \| "image" \| "generic"; state: "input-streaming" \| "input-available" \| "output-available" \| "output-error"; input?: undefined \| Record<string, unknown>; rawInput?: undefined \| string; output?: undefined \| Record<string, unknown>; toolCallId?: undefined \| string; errorText?: undefined \| string; raw?: undefined \| { source: string; payload: unknown } }; raw?: undefined \| { source: string; payload: unknown } } \| { type: "card"; envelope: { type: string; id: string; data: unknown; title?: undefined \| string; resolution?: undefined \| { kind: "action"; action: string; payload?: unknown; at?: undefined \| string } \| { kind: "submit"; data: unknown; at?: undefined \| string } \| { kind: "dismissed"; at?: undefined \| string } \| { kind: "expired"; reason?: undefined \| string; at?: undefined \| string } }; raw?: undefined \| { source: string; payload: unknown } } \| { type: "source"; source: { id?: undefined \| string; url?: undefined \| string; title?: undefined \| string; snippet?: undefined \| string; index?: undefined \| number }; raw?: undefined \| { source: string; payload: unknown } } \| { type: "file"; attachment: { id: string; type: "file" \| "source-document"; filename?: undefined \| string; mediaType?: undefined \| string; url?: undefined \| string; title?: undefined \| string }; raw?: undefined \| { source: string; payload: unknown } })[]; actions?: undefined \| ("copy" \| "dislike" \| "edit" \| "like" \| "regenerate" \| "speak" \| { 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 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). |
| `loading` | `loading` | `undefined \| false \| true` | Show a typing indicator on the pending assistant turn. Set it while awaiting the assistant's reply. |
| `proseSize` | `prose-size` | `undefined \| "xs" \| "sm" \| "base" \| "lg"` | Body/prose font scale for rendered markdown (`'xs' \| 'sm' \| 'base' \| 'lg'`). Defaults to `'sm'`. |
| `codeTheme` | `code-theme` | `undefined \| string` | Shiki theme name for syntax-highlighted code blocks (e.g. `'github-dark-dimmed'`). |
| `codeHighlight` | `code-highlight` | `undefined \| false \| true` | Enable Shiki syntax highlighting in code blocks. Turn off to render plain `<pre>` blocks (lighter, no highlighter load). Default true. |
| `actionsReveal` | `actions-reveal` | `undefined \| "always" \| "hover"` | Whether each message's action bar is always visible (`'always'`, default) or only revealed on hover of that message row (`'hover'`). |
| `scrollButton` | `scroll-button` | `undefined \| false \| true` | Show the scroll-to-bottom button inside the scroll area. Default true. |
| `class` | `class` | `undefined \| string` | Extra classes applied to the thread's inner root. |
| `cardTypes` | — | `undefined \| Record<string, 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. |
| `cardSchemas` | — | `undefined \| Record<string, object>` | 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. |

**Events** (non-bubbling `CustomEvent`s — listen directly on the element):

| Event | `detail` type | Description |
|---|---|---|
| `kai-message-action` | `CustomEvent<{ messageId: string; action: string; state?: undefined \| "on" \| "off" }>` | 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. |

**Methods** (call on the element instance: `document.querySelector('kai-thread').scrollToBottom(…)`):

| Method | Signature | Description |
|---|---|---|
| `scrollToBottom` | `(behavior?: ScrollBehavior): void` | Scroll the message list to the bottom (default `'smooth'`). |

**Slots** (project your own markup via `slot="name"` on a light-DOM child):

| Slot | Mode | Description |
|---|---|---|
| `empty` | replace | Custom zero-state rendered in the message area while the thread is empty; replaces the built-in default. |

---

### `kai-toast-region` / `ToastRegion`

**Properties** (every element also accepts `theme="light|dark|auto"`; only scalar props work as HTML attributes):

| Property | Attribute | Type | Description |
|---|---|---|---|
| `theme` | `theme` | `"light" \| "dark" \| "auto"` | Color mode (`auto` follows prefers-color-scheme). |
| `toasts` | — | `undefined \| { id: string; message: string; variant?: undefined \| "neutral" \| "success" \| "warning" \| "error" \| "info"; appearance?: undefined \| "pill" \| "card"; inverse?: undefined \| false \| true; description?: undefined \| string; action?: undefined \| { label: string; onAction: () => void \| false }; duration?: undefined \| number; dismissible?: undefined \| false \| true; target?: undefined \| HTMLElement }[]` | The toasts to render. Newest is shown on top. Set as a JS property (array); pass a new array reference to update. Omit for an empty region, which is the normal resting state and how the imperative `toast()` API starts. Note the handover: the first `toast()` call ADOPTS a region you placed in markup (no second region mounts) and binds the imperative store to this property, replacing any array you set. Drive a region as data OR via `toast()`, not both at once. |
| `position` | `position` | `undefined \| "top-center" \| "top-right" \| "top-left" \| "bottom-center" \| "bottom-right" \| "bottom-left"` | Stack anchor: `'top-center'` (default), `'top-right'`, `'bottom-center'`, … |
| `max` | `max` | `undefined \| number` | Max simultaneously-visible toasts; the rest queue. Defaults to `3`. |
| `stack` | `stack` | `undefined \| "expanded" \| "collapsed"` | Stacking: 'expanded' (default, full column) \| 'collapsed' (Sonner-style pile that expands on hover/focus). Attribute: stack. |
| `appearance` | `appearance` | `undefined \| "pill" \| "card"` | Default appearance for this region's toasts: `'pill'` (default, compact) \| `'card'` (richer, with a description line). A per-toast `appearance` wins. Attribute: `appearance`. |
| `inverse` | `inverse` | `undefined \| false \| true` | Default high-contrast inverse treatment for this region's toasts. A per-toast `inverse` wins. Off by default. Attribute: `inverse`. |
| `target` | — | `undefined \| HTMLElement` | Container element to anchor this region to (JS property). Set by the store for a scoped region; unset = the global viewport region. |

**Events** (non-bubbling `CustomEvent`s — listen directly on the element):

| Event | `detail` type | Description |
|---|---|---|
| `kai-action` | `CustomEvent<{ id: string; label: string }>` | A toast's action button was pressed. |
| `kai-dismiss` | `CustomEvent<{ id: string; reason: "timeout" \| "close" \| "action" }>` | A toast left the stack. `reason` is `'timeout' \| 'close' \| 'action'`. |

---

### `kai-tool` / `Tool`

**Properties** (every element also accepts `theme="light|dark|auto"`; only scalar props work as HTML attributes):

| Property | Attribute | Type | Description |
|---|---|---|---|
| `theme` | `theme` | `"light" \| "dark" \| "auto"` | Color mode (`auto` follows prefers-color-scheme). |
| `tool` | — | `undefined \| { type: string; kind?: undefined \| "command" \| "file-change" \| "search" \| "fetch" \| "mcp" \| "image" \| "generic"; state: "input-streaming" \| "input-available" \| "output-available" \| "output-error"; input?: undefined \| Record<string, unknown>; rawInput?: undefined \| string; output?: undefined \| Record<string, unknown>; toolCallId?: undefined \| string; errorText?: undefined \| string; raw?: undefined \| { source: string; payload: unknown } }` | The tool-call to display. Set as a JS property. |
| `open` | `open` | `undefined \| false \| true` | 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`. |
| `defaultOpen` | `default-open` | `undefined \| false \| true` | Initial open state on mount (uncontrolled seed). |
| `disabled` | `disabled` | `undefined \| false \| true` | Gate the disclosure trigger: programmatic `show()/hide()/toggle()` still work, but the trigger click no longer toggles. |

**Events** (non-bubbling `CustomEvent`s — listen directly on the element):

| Event | `detail` type | Description |
|---|---|---|
| `kai-open-change` | `CustomEvent<{ open: false \| true }>` | The panel expanded or collapsed (by trigger click or a method). |

**Methods** (call on the element instance: `document.querySelector('kai-tool').show()`):

| Method | Signature | Description |
|---|---|---|
| `show` | `(): void` | Open it programmatically (no-op while disabled). |
| `hide` | `(): void` | Close it programmatically. |
| `toggle` | `(): void` | Flip the open state (closes while disabled). |

---

### `kai-tooltip` / `Tooltip`

**Properties** (every element also accepts `theme="light|dark|auto"`; only scalar props work as HTML attributes):

| Property | Attribute | Type | Description |
|---|---|---|---|
| `theme` | `theme` | `"light" \| "dark" \| "auto"` | Color mode (`auto` follows prefers-color-scheme). |
| `content` | `content` | `undefined \| string` | The hint text shown on hover/focus of the slotted trigger. |
| `openDelay` | `open-delay` | `undefined \| number` | Delay (ms) before the tooltip appears on hover. Defaults to 600. Focus shows it immediately regardless. |
| `closeDelay` | `close-delay` | `undefined \| number` | Delay (ms) before it hides after the pointer leaves. Defaults to 0 (hides immediately). |
| `placement` | `placement` | `undefined \| string` | Preferred placement: `'top' \| 'bottom' \| 'left' \| 'right'` (+ optional `-start`/`-end`). Defaults to `'top'`; flips to stay in view. |
| `open` | `open` | `undefined \| false \| true` | 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`. |
| `defaultOpen` | `default-open` | `undefined \| false \| true` | Initial open state on mount (uncontrolled seed). |
| `disabled` | `disabled` | `undefined \| false \| true` | Turn the tooltip off while keeping the trigger mounted (hover/focus and `show()` no longer open it). |

**Events** (non-bubbling `CustomEvent`s — listen directly on the element):

| Event | `detail` type | Description |
|---|---|---|
| `kai-open-change` | `CustomEvent<{ open: false \| true }>` | The tooltip opened or closed (by hover/focus, outside-click, or a method). |

**Methods** (call on the element instance: `document.querySelector('kai-tooltip').show()`):

| Method | Signature | Description |
|---|---|---|
| `show` | `(): void` | Open it programmatically (no-op while disabled). |
| `hide` | `(): void` | Close it programmatically. |
| `toggle` | `(): void` | Flip the open state (closes while disabled). |

**Slots** (project your own markup via `slot="name"` on a light-DOM child):

| Slot | Mode | Description |
|---|---|---|
| _(default)_ | inject | The TRIGGER the tooltip describes. The tip text is the `text` prop. |

---

### `kai-view` / `View`

**Properties** (every element also accepts `theme="light|dark|auto"`; only scalar props work as HTML attributes):

| Property | Attribute | Type | Description |
|---|---|---|---|
| `theme` | `theme` | `"light" \| "dark" \| "auto"` | Color mode (`auto` follows prefers-color-scheme). |
| `name` | `name` | `undefined \| string` | The view's name: what `push()` / `selectTab()` / the stack's `view` attribute address. Attribute: `name`. |
| `tabRoot` | `tab-root` | `undefined \| false \| true` | Marks this view as a TAB ROOT: it shows the tab bar and never a back affordance, and a tab switch lands on it directly. Views without it are DRILL views, reached by `push()` and left by `back()`. Attribute: `tab-root`. |

_No events._

**Slots** (project your own markup via `slot="name"` on a light-DOM child):

| Slot | Mode | Description |
|---|---|---|
| _(default)_ | inject | This view's content. It stays mounted while hidden, so switching views resets nothing. |

---

### `kai-view-stack` / `ViewStack`

**Properties** (every element also accepts `theme="light|dark|auto"`; only scalar props work as HTML attributes):

| Property | Attribute | Type | Description |
|---|---|---|---|
| `theme` | `theme` | `"light" \| "dark" \| "auto"` | Color mode (`auto` follows prefers-color-scheme). |
| `view` | `view` | `undefined \| string` | Deep link / initial view name; reflected to the `view` ATTRIBUTE as navigation happens, so `kai-view-stack[view="chat"]` selectors follow. Setting it later navigates (tab root selects that tab; a drill view replaces the top while drilled, or pushes from a root). |
| `drilled` | `drilled` | `undefined \| false \| true` | READ-ONLY reflection of the drilled state, present while a pushed (non-root) view is showing. THE rule this element owns: drilled hides the tab bar and shows a back affordance, so a sibling tab bar hides itself on `kai-view-stack[drilled]` (or from `kai-view-change`), and a header shows its back arrow the same way. |

**Events** (non-bubbling `CustomEvent`s — listen directly on the element):

| Event | `detail` type | Description |
|---|---|---|
| `kai-view-change` | `CustomEvent<{ view: string \| undefined; root: string \| undefined; drilled: false \| true; stack: string[] }>` | The visible view or the drilled flag changed (push, back, replace, tab switch, or a `view` attribute write). `detail`: `{ view, root, drilled, stack }`; `root` is what the tab bar should mark active, defined even while drilled. |

**Methods** (call on the element instance: `document.querySelector('kai-view-stack').push(…)`):

| Method | Signature | Description |
|---|---|---|
| `push` | `(name: string): void` | Drill into a view (fires `kai-view-change`). A tab-root name routes to `selectTab`; unknown names are ignored. |
| `back` | `(): void` | Pop one drilled view. No-op at a tab root. |
| `replace` | `(name: string): void` | Swap the current view without touching history. |
| `selectTab` | `(name: string): void` | Switch tab roots and clear any drill. Ignores non-root names. |
| `navigate` | `(name: string): void` | Deep-link navigation: what the `view` attribute drives. |

**Slots** (project your own markup via `slot="name"` on a light-DOM child):

| Slot | Mode | Description |
|---|---|---|
| _(default)_ | inject | The named `<kai-view>` children: tab roots (`tab-root`) side by side behind a tab bar, the rest drill views reached by `push()`. |

---

### `kai-voice-input` / `VoiceInput`

**Properties** (every element also accepts `theme="light|dark|auto"`; only scalar props work as HTML attributes):

| Property | Attribute | Type | Description |
|---|---|---|---|
| `theme` | `theme` | `"light" \| "dark" \| "auto"` | Color mode (`auto` follows prefers-color-scheme). |
| `transcribe` | — | `undefined \| ((audio: Blob) => Promise<string>)` | 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. |
| `disabled` | `disabled` | `undefined \| false \| true` | Disable the mic button (non-interactive). |
| `recognitionLang` | `recognition-lang` | `undefined \| string` | 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. |
| `interim` | `interim` | `undefined \| false \| true` | Emit live partial transcripts (`kai-transcript-interim`) during native recognition. Attribute: `interim`. No-op on the transcribe/fallback paths. |

**Events** (non-bubbling `CustomEvent`s — listen directly on the element):

| Event | `detail` type | Description |
|---|---|---|
| `kai-audio-captured` | `CustomEvent<{ blob: Blob }>` | 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). |
| `kai-recording-change` | `CustomEvent<{ recording: false \| true }>` | 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. |
| `kai-transcript-interim` | `CustomEvent<{ text: string }>` | Live partial transcript during native recognition (only when `interim` is set). Fires repeatedly before the final `kai-transcription`. |
| `kai-transcription` | `CustomEvent<{ text: string }>` | Final transcript: the `transcribe` property resolved, OR native `SpeechRecognition` produced final text (no `transcribe` set). |
| `kai-voice-error` | `CustomEvent<{ source: "recognition"; error: string; message: string }>` | A voice session failed, so no failure is ever silent. `detail.source` names the failing side (`recognition` on `<kai-voice-input>`, `synthesis` on `<kai-voice-output>`), `detail.error` carries the platform error code, the thrown exception's name, or `no-result` when recognition ended with no error and no text (the user said nothing), and `detail.message` is human-readable. Deliberate cancellation does not fire. |

**Methods** (call on the element instance: `document.querySelector('kai-voice-input').start()`):

| Method | Signature | Description |
|---|---|---|
| `start` | `(): void` | 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. |
| `stop` | `(): void` | Stop the in-progress recording, producing the blob (→ kai-audio-captured) and running transcription. Pairs with start() for push-to-talk. |

---

### `kai-voice-output` / `VoiceOutput`

**Properties** (every element also accepts `theme="light|dark|auto"`; only scalar props work as HTML attributes):

| Property | Attribute | Type | Description |
|---|---|---|---|
| `theme` | `theme` | `"light" \| "dark" \| "auto"` | Color mode (`auto` follows prefers-color-scheme). |
| `text` | `text` | `undefined \| string` | The utterance to read aloud. |
| `autoplay` | `autoplay` | `undefined \| false \| true` | Speak automatically when `text` is set/changed. |
| `synthesize` | — | `undefined \| ((text: string) => Promise<Blob>)` | 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. |
| `disabled` | `disabled` | `undefined \| false \| true` | Disable the button (non-interactive). |

**Events** (non-bubbling `CustomEvent`s — listen directly on the element):

| Event | `detail` type | Description |
|---|---|---|
| `kai-speaking-change` | `CustomEvent<{ speaking: false \| true }>` | Playback started or stopped. Drive your own UI in sync. `speaking: true` fires when audio actually starts (utterance.onstart natively; audio playback beginning on the `synthesize` path), not when speak() is called; earlier releases fired it optimistically inside speak() itself. Fires on real transitions only (manual click and programmatic speak()/stop()), never on mount. |
| `kai-synthesized` | `CustomEvent<{ blob: Blob }>` | The model path (`synthesize`) resolved audio: the raw `Blob` before playback. |
| `kai-voice-error` | `CustomEvent<{ source: "synthesis"; error: string; message: string }>` | A voice session failed, so no failure is ever silent. `detail.source` names the failing side (`recognition` on `<kai-voice-input>`, `synthesis` on `<kai-voice-output>`), `detail.error` carries the platform error code, the thrown exception's name, or `no-result` when recognition ended with no error and no text (the user said nothing), and `detail.message` is human-readable. Deliberate cancellation does not fire. |

**Methods** (call on the element instance: `document.querySelector('kai-voice-output').speak()`):

| Method | Signature | Description |
|---|---|---|
| `speak` | `(): void` | Speak the current `text` (native, or via `synthesize` if set). |
| `pause` | `(): void` | Pause playback (resumable). |
| `resume` | `(): void` | Resume paused playback. |
| `stop` | `(): void` | Stop playback and reset. |

**Styleable parts** (restyle from outside via `kai-voice-output::part(name)`):

| Part | Description |
|---|---|
| `::part(button)` | The speaker/play button. Restyle radius, size, padding, or colors from outside; it is a ghost icon button by default. — `kai-voice-output::part(button) { border-radius: 9999px; color: var(--color-primary) }` |

---

### `kai-workspace` / `Workspace`

**Properties** (every element also accepts `theme="light|dark|auto"`; only scalar props work as HTML attributes):

| Property | Attribute | Type | Description |
|---|---|---|---|
| `theme` | `theme` | `"light" \| "dark" \| "auto"` | Color mode (`auto` follows prefers-color-scheme). |
| `startCollapsed` | `start-collapsed` | `undefined \| false \| true` | Controlled collapsed state of the start aside. Set this as a JS property (`el.startCollapsed = true`) to drive the aside from your app, updating it in response to the `kai-aside-toggle` event. Omit for uncontrolled (the element manages it). |
| `defaultStartCollapsed` | `default-start-collapsed` | `undefined \| false \| true` | Initial collapsed state of the start aside when uncontrolled (default false). Use the `default-start-collapsed` attribute to start collapsed in plain HTML. |
| `endCollapsed` | `end-collapsed` | `undefined \| false \| true` | Controlled collapsed state of the end aside. Set this as a JS property (`el.endCollapsed = true`) to drive the aside from your app, updating it in response to the `kai-aside-toggle` event. Omit for uncontrolled (the element manages it). |
| `defaultEndCollapsed` | `default-end-collapsed` | `undefined \| false \| true` | Initial collapsed state of the end aside when uncontrolled (default false). Use the `default-end-collapsed` attribute to start collapsed in plain HTML. |
| `collapseBelow` | `collapse-below` | `undefined \| number` | Auto-collapse both asides when the shell's own width drops below this many px, and re-expand when it grows back above. Applies to uncontrolled asides only (it never fights an app-driven collapsed prop); omit to disable. Fires `kai-aside-toggle`. Attribute: `collapse-below`. |
| `drawerBelow` | `drawer-below` | `undefined \| number` | Below this shell width in px, an expanded aside renders as an overlay drawer over the main region instead of a column beside it. Escape inside the drawer closes it and returns focus to the element focused before it opened. Omit to disable. Attribute: `drawer-below`. |
| `compact` | `compact` | `undefined \| false \| true` | Density hint. Reflected as a `data-compact` hook on the root (and as the `compact` attribute on the element) for your CSS and slotted content; the shell itself keeps no other opinion about density. |

**Events** (non-bubbling `CustomEvent`s — listen directly on the element):

| Event | `detail` type | Description |
|---|---|---|
| `kai-aside-resize` | `CustomEvent<{ side: "start" \| "end"; width: number }>` | The aside was resized (fires per drag step, keyboard nudge, or a handle double-click reset), width in px. |
| `kai-aside-toggle` | `CustomEvent<{ side: "start" \| "end"; collapsed: false \| true }>` | An aside collapsed or expanded (a method, the breakpoint, the drawer's Escape). |

**Methods** (call on the element instance: `document.querySelector('kai-workspace').toggleAside(…)`):

| Method | Signature | Description |
|---|---|---|
| `toggleAside` | `(side: WorkspaceAsideSide): void` | Collapse/expand one aside (fires `kai-aside-toggle`). |
| `collapseAside` | `(side: WorkspaceAsideSide): void` | Force one aside collapsed (fires `kai-aside-toggle`). |
| `expandAside` | `(side: WorkspaceAsideSide): void` | Force one aside expanded (fires `kai-aside-toggle`). |

**Slots** (project your own markup via `slot="name"` on a light-DOM child):

| Slot | Mode | Description |
|---|---|---|
| _(default)_ | inject | The main region content (same region as the `main` slot): your `<kai-chat>`, or any app view. |
| `header` | inject | The top band across the full shell width (app bar, tabs, breadcrumbs). |
| `start` | inject | The inline-start aside column (a conversation rail, a nav, a file tree). Resizable and collapsible. |
| `main` | inject | The main region. Unnamed children project here too, via the default slot. |
| `end` | inject | The inline-end aside column (inspector, notes, preview). Resizable and collapsible. |
| `footer` | inject | The bottom band across the full shell width (status bar, disclaimers). |

**Styleable parts** (restyle from outside via `kai-workspace::part(name)`):

| Part | Description |
|---|---|
| `::part(aside)` | Both aside columns match this part (each also matches its own start/end part). Restyle the shared aside surface or border from outside; the --kai-workspace-start-* and --kai-workspace-end-* custom properties set the widths. — `kai-workspace::part(aside) { background: var(--color-card) }` |
| `::part(header)` | The top band across the full shell width (app bar, tabs, breadcrumbs). |
| `::part(start)` | The inline-start aside column (a conversation rail, a nav, a file tree). Resizable and collapsible. |
| `::part(main)` | The main region. Unnamed children project here too, via the default slot. |
| `::part(end)` | The inline-end aside column (inspector, notes, preview). Resizable and collapsible. |
| `::part(footer)` | The bottom band across the full shell width (status bar, disclaimers). |

---