@kitn.ai/ui 0.25.2 → 0.27.0

package/llms-full.txt

@@ -3,7 +3,7 @@
 
 # @kitn.ai/ui
 
-> Framework-agnostic, Shadow-DOM web components for building AI chat interfaces — works in React, Vue, Angular, Svelte, or plain HTML. 80 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.
+> Framework-agnostic, Shadow-DOM web components for building AI chat interfaces — works in React, Vue, Angular, Svelte, or plain HTML. 89 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
 
@@ -37,7 +37,7 @@ Drop an element into any framework (React, Vue, plain HTML). Data in via JS prop
 - `<kai-prompt-input>` — standalone composer with send button.
 
 **Layer 2 — composable primitives** (`import { … } from '@kitn.ai/ui'`):
-All 80 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.
+All 89 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
 
@@ -151,7 +151,10 @@ For Tailwind builds: `@import "@kitn.ai/ui/theme.css"` in your CSS.
 
 ## Docs
 
-- Full element reference (all 80 elements, every prop/event): ./llms-full.txt — https://kitn.dev/llms-full.txt
+- Element reference (all 89 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
 - 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
@@ -248,7 +251,979 @@ The same reassign rule applies to every array/object property (`models`, `contex
 
 ---
 
-## Element reference (80 elements, generated from custom-elements.json)
+<!-- 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 (56, 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` |
+| `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;
+}
+/** A scripted mock turn: optional text, then optional 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 {
+    /** Text streamed (token by token) before the tool calls. */
+    text?: string;
+    /** 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 tool calls (`{ text, toolCalls }`), which is
+     *  what lets the zero-config mock exercise the kit's tool/card path 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 -->
+
+---
+
+## Element reference (89 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.
 
@@ -339,7 +1314,7 @@ Every element also accepts the `theme` attribute. Array/object properties are ma
 | 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). |
+| `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. |
@@ -357,6 +1332,8 @@ Every element also accepts the `theme` attribute. Array/object properties are ma
 | 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 }` |
 
 ---
 
@@ -378,9 +1355,10 @@ Every element also accepts the `theme` attribute. Array/object properties are ma
 | `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. |
-| `audioElement` | — | `undefined \| HTMLMediaElement` | An `<audio>` or `<video>` element to tap for its audio. JS property only. |
-| `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. |
+| `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`. |
 
@@ -542,7 +1520,7 @@ _No events._
 | `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`. |
+| `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):
@@ -602,7 +1580,6 @@ _No events._
 | Property | Attribute | Type | Description |
 |---|---|---|---|
 | `theme` | `theme` | `"light" \| "dark" \| "auto"` | Color mode (`auto` follows prefers-color-scheme). |
-| `search` | `search` | `undefined \| false \| true` | Show a Search (Globe) button in the input toolbar; fires a `search` event. |
 | `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). |
@@ -612,6 +1589,8 @@ _No events._
 | `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`). |
@@ -625,6 +1604,8 @@ _No events._
 | `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. |
@@ -642,11 +1623,11 @@ _No events._
 | `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-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-search` | `CustomEvent<Record<string, never>>` | The Search button was clicked. |
 | `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-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(…)`):
 
@@ -682,6 +1663,64 @@ _No events._
 
 ---
 
+### `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):
@@ -795,10 +1834,17 @@ _No events._
 | `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`
@@ -893,7 +1939,7 @@ _No events._
 | `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). |
+| `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). |
@@ -962,6 +2008,45 @@ _No events._
 
 ---
 
+### `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. |
+
+**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(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):
@@ -970,17 +2055,18 @@ _No events._
 |---|---|---|---|
 | `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: { type: "document" \| "collection"; documentId?: undefined \| string; filters?: undefined \| { tags?: undefined \| string[]; authors?: undefined \| string[]; contentType?: undefined \| "transcript" \| "markdown"; dateRange?: undefined \| { from: string; to: string } } }; messageCount: number; lastMessageAt: string; updatedAt: string; trailing?: undefined \| string }[]` | Every conversation the list renders, flat. Each one is filed under the group whose `id` equals its `groupId`; one with no `groupId`, or with a `groupId` matching no entry in `groups`, falls into a trailing "Ungrouped" section, so nothing you pass in is ever dropped. There is no recency bucketing. Set as a JS property. Omit to supply them as `<kai-conversation>` light-DOM children instead, or for the empty state. |
+| `conversations` | — | `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 }[]` | 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). |
 
 **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. |
+| `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. |
@@ -1000,6 +2086,7 @@ _No events._
 
 | 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. |
@@ -1008,13 +2095,14 @@ _No events._
 
 | 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 Required fields not expressible as HTML attributes (`scope`, `messageCount`, `lastMessageAt`, `updatedAt`) receive safe defaults so the rendered list item is fully functional with just `id` + title text. |
+| `<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 }` |
 
 ---
 
@@ -1027,6 +2115,7 @@ _No events._
 | `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):
 
@@ -1063,6 +2152,97 @@ _No events._
 
 ---
 
+### `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):
@@ -1221,7 +2401,7 @@ _No events._
 | 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-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. |
+| `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:{…} }`. |
@@ -1329,7 +2509,7 @@ _No events._
 |---|---|---|---|
 | `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. Settable and reflected to the `value` attribute. `el.value = 'hi'` drives it (no event); typing updates it and fires `kai-input`. Read `el.value` for live state. |
+| `value` | `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. |
@@ -1342,13 +2522,19 @@ _No events._
 | `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 }>` | The value was committed (blur). |
-| `kai-input` | `CustomEvent<{ value: string }>` | The value changed per keystroke. |
+| `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(…)`):
 
@@ -1356,7 +2542,9 @@ _No events._
 |---|---|---|
 | `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. |
-| `clear` | `(): void` | Empty the value and fire `kai-change` with `''`. |
+| `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):
 
@@ -1462,6 +2650,7 @@ _No events._
 | `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. |
@@ -1550,6 +2739,8 @@ _No events._
 | `::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. |
 
 ---
@@ -1701,6 +2892,23 @@ _No events._
 
 ---
 
+### `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):
@@ -1847,12 +3055,12 @@ _No events._
 | `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. |
-| `search` | `search` | `undefined \| false \| true` | Show a Search (Globe) button in the left toolbar; clicking it fires a `search` event. |
+| `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). |
+| `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. |
 
@@ -1861,13 +3069,13 @@ _No events._
 | 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-search` | `CustomEvent<Record<string, never>>` | The Search (Globe) toolbar button was clicked. |
 | `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-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(…)`):
 
@@ -1900,6 +3108,33 @@ _No events._
 
 ---
 
+### `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):
@@ -2145,6 +3380,8 @@ _No events._
 | `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):
 
@@ -2219,6 +3456,37 @@ _No events._
 
 ---
 
+### `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):
@@ -2333,6 +3601,37 @@ _No events._
 
 ---
 
+### `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):
@@ -2601,7 +3900,7 @@ _No events._
 | 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. |
+| `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. |
@@ -2690,7 +3989,7 @@ _No events._
 | 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. |
+| `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. |
@@ -2703,6 +4002,7 @@ _No events._
 | `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()`):
 
@@ -2722,15 +4022,16 @@ _No events._
 | `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. |
+| `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. Fires on real transitions only (manual click and programmatic speak()/stop()), never on mount. |
+| `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()`):
 
@@ -2756,79 +4057,50 @@ _No events._
 | 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 sidebar's section headers, rendered in array order. A group carries no conversations of its own; it is matched against `conversations` by id, so the two props are complementary rather than alternatives. Omit for an ungrouped sidebar. Set as a JS property. |
-| `conversations` | — | `undefined \| { id: string; title: string; groupId?: undefined \| string; scope: { type: "document" \| "collection"; documentId?: undefined \| string; filters?: undefined \| { tags?: undefined \| string[]; authors?: undefined \| string[]; contentType?: undefined \| "transcript" \| "markdown"; dateRange?: undefined \| { from: string; to: string } } }; messageCount: number; lastMessageAt: string; updatedAt: string; trailing?: undefined \| string }[]` | Every conversation in the sidebar, flat. Each one is filed under the group whose `id` equals its `groupId`; one with no `groupId`, or with a `groupId` matching no entry in `groups`, falls into a trailing ungrouped section (headerless when `compact`), so nothing you pass in is ever dropped. There is no recency bucketing. Set as a JS property. Omit for an empty sidebar, or when `no-conversations` replaces the built-in list with your own `sidebar-header` content. |
-| `activeId` | `active-id` | `undefined \| string` | Id of the open conversation, highlighted in the sidebar. |
-| `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" \| "like" \| "dislike" \| "regenerate" \| "edit" \| { id: string; label: string; icon?: undefined \| string; tooltip?: undefined \| string })[]; avatar?: undefined \| { src?: undefined \| string; fallback?: undefined \| string; alt?: undefined \| string }; feedback?: undefined \| "like" \| "dislike" }[]` | The active conversation's message thread, newest last. Set as a JS property (`el.messages = [...]`); a NEW array reference per streaming chunk re-renders (mutating in place does not). Omit for an empty thread. |
-| `value` | `value` | `undefined \| string` |  |
-| `placeholder` | `placeholder` | `undefined \| string` |  |
-| `loading` | `loading` | `undefined \| false \| true` |  |
-| `suggestions` | — | `undefined \| string[]` |  |
-| `suggestionMode` | `suggestion-mode` | `undefined \| "submit" \| "fill"` |  |
-| `proseSize` | `prose-size` | `undefined \| "xs" \| "sm" \| "base" \| "lg"` |  |
-| `codeTheme` | `code-theme` | `undefined \| string` |  |
-| `codeHighlight` | `code-highlight` | `undefined \| false \| true` |  |
-| `chatTitle` | `chat-title` | `undefined \| string` |  |
-| `models` | — | `undefined \| { id: string; name: string; provider?: undefined \| string; description?: undefined \| string; group?: undefined \| string }[]` |  |
-| `currentModel` | `current-model` | `undefined \| string` |  |
-| `context` | — | `undefined \| { usedTokens: number; maxTokens: number; inputTokens?: undefined \| number; outputTokens?: undefined \| number; estimatedCost?: undefined \| number }` |  |
-| `scrollButton` | `scroll-button` | `undefined \| false \| true` |  |
-| `search` | `search` | `undefined \| false \| true` |  |
-| `voice` | `voice` | `undefined \| false \| 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> }[] }[]` | Rich entity triggers (`/` skills, `@` agents/plugins) forwarded to the input. |
-| `kindIcons` | — | `undefined \| Record<string, string>` | Default icon per entity kind (kind → image src) forwarded to the input. |
-| `sidebarWidth` | `sidebar-width` | `undefined \| number` | Sidebar default width as a percent of the workspace (default 26). |
-| `sidebarMinWidth` | `sidebar-min-width` | `undefined \| number` | Sidebar min width in px (default 240). |
-| `sidebarMaxWidth` | `sidebar-max-width` | `undefined \| number` | Sidebar max width in px (default 420). |
-| `sidebarCollapsed` | `sidebar-collapsed` | `undefined \| false \| true` | Controlled collapsed state. Set this as a JS property (`el.sidebarCollapsed = true`) to drive the sidebar from your app, updating it in response to the `kai-sidebar-toggle` event. Omit for uncontrolled (the element manages it). |
-| `defaultSidebarCollapsed` | `default-sidebar-collapsed` | `undefined \| false \| true` | Initial collapsed state when uncontrolled (default false). Use the `default-sidebar-collapsed` attribute to start collapsed in plain HTML. |
-| `collapseBelow` | `collapse-below` | `undefined \| number` | Auto-collapse the rail when the workspace's own width drops below this many px, and re-expand when it grows back above. Uncontrolled only (it never fights an app-driven `sidebarCollapsed`); omit to disable. Fires `kai-sidebar-toggle`. Attribute: `collapse-below`. |
-| `compact` | `compact` | `undefined \| false \| true` | Render Recents as dense single-line rows (a leading dot + title, no count). |
-| `noConversations` | `no-conversations` | `undefined \| false \| true` | Suppress the built-in ConversationList so the `sidebar-header` slot owns the whole rail flex region (for apps that supply their own rail nav). Default false. Attribute: `no-conversations`. |
-| `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. |
+| `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-conversation-select` | `CustomEvent<{ id: string }>` | A conversation was selected in the sidebar. |
-| `kai-message-action` | `CustomEvent<{ messageId: string; action: string; state?: undefined \| "on" \| "off" }>` | An action button on a message was clicked. `state` is present only for the toggleable feedback votes: `'on'` when a like/dislike is set, `'off'` when re-tapped to clear. |
-| `kai-model-change` | `CustomEvent<{ modelId: string }>` | The header model switcher changed. |
-| `kai-new-chat` | `CustomEvent<Record<string, never>>` | The "New chat" button was clicked. |
-| `kai-search` | `CustomEvent<Record<string, never>>` | The Search button was clicked. |
-| `kai-sidebar-toggle` | `CustomEvent<{ collapsed: false \| true }>` | The sidebar was collapsed or expanded. |
-| `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-value-change` | `CustomEvent<{ value: string }>` | Fired on every input change. |
-| `kai-voice` | `CustomEvent<Record<string, never>>` | The Mic / voice button was clicked. |
+| `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').toggleSidebar()`):
+**Methods** (call on the element instance: `document.querySelector('kai-workspace').toggleAside(…)`):
 
 | Method | Signature | Description |
 |---|---|---|
-| `toggleSidebar` | `(): void` | Collapse/expand the conversation sidebar and fire `kai-sidebar-toggle`. |
-| `collapseSidebar` | `(): void` | Force the conversation sidebar collapsed (fires `kai-sidebar-toggle`). |
-| `expandSidebar` | `(): void` | Force the conversation sidebar expanded (fires `kai-sidebar-toggle`). |
-| `focus` | `(options?: FocusOptions): void` | Focus the thread's composer. |
-| `clear` | `(): void` | Clear the thread draft + staged attachments. |
-| `send` | `(): void` | Submit the current thread draft programmatically (fires `kai-submit`). |
-| `scrollToBottom` | `(behavior?: ScrollBehavior): void` | Scroll the thread to the newest message. |
+| `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 |
 |---|---|---|
-| `sidebar-header` | inject | Top of the conversation rail (brand, a kai-tabs strip). |
-| `sidebar-footer` | inject | Bottom of the rail: an upgrade card, a Design trigger, a user-menu cluster. |
-| `main-header` | inject | Top of the main region (a top-placed banner or a corner action). |
-| `main` | replace | Replace the built-in chat thread with your own main view (a home or dashboard screen). Omit to keep the thread. |
+| _(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(sidebar)` | The conversation rail. Carries a subtle, theme-aware default background (bg-surface); override its background, border, or width from outside. `sidebar-min-width` sets its min px width and `collapse-below` auto-collapses it under a width. — `kai-workspace::part(sidebar) { background: var(--color-card); border-right: 1px solid var(--color-border) }` |
+| `::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). |
 
 ---