@kitn.ai/ui 0.25.2 → 0.26.0

package/README.md

@@ -75,7 +75,7 @@ The element bundle is a self-contained ES module — load it directly from [jsDe
 ```
 
 <!-- x-release-please-start-version -->
-The URLs above track the **latest** release — handy for trying things out. **For production, pin an exact version** (e.g. `@kitn.ai/ui@0.25.2/dist/kai.es.js`): pinned URLs are immutable and cached far more aggressively, and — since this package is pre-1.0 — pinning shields you from breaking changes in a future minor release.
+The URLs above track the **latest** release — handy for trying things out. **For production, pin an exact version** (e.g. `@kitn.ai/ui@0.26.0/dist/kai.es.js`): pinned URLs are immutable and cached far more aggressively, and — since this package is pre-1.0 — pinning shields you from breaking changes in a future minor release.
 <!-- x-release-please-end -->
 
 > **Pin `0.25.0` or newer.** Every version from `0.14.1` through `0.24.0` is covered by a [critical security advisory](https://github.com/kitn-ai/ui/security/advisories) and is deprecated on npm. `npm install` warns you about a deprecated version; **a CDN fetch does not**, so an old pinned URL in a page keeps serving the vulnerable bundle silently.
@@ -191,7 +191,7 @@ The components are deliberately **transport-agnostic**: `<kai-chat>` just render
 </script>
 ```
 
-Key point: `chat.messages` has to be reassigned with a **new array containing a new object** for the streaming message on each chunk. That's what triggers the re-render. Mutating the existing object in place won't update the view. `createAssistantStream` is what satisfies that rule for you; if you drive `messages` by hand, you own it.
+Key point, and it is not only a streaming rule: `chat.messages` has to be reassigned with a **new array**, and any message you changed has to be a **new object**. The array reference is what tells the element something changed — reassigning the same array is a no-op even if you swapped a message inside it. The new message object is what makes the change visible, because the list keys its rows by item identity. Adds, removes and reorders need only the fresh array; editing an existing message needs both, and mutating one in place won't update the view even inside a fresh array. `createAssistantStream` satisfies both halves for you; if you drive `messages` by hand — editing a message, renaming a conversation — you own it.
 
 `@kitn.ai/ui/wire` also ships `readAnthropicStream`, the helpers for a multi-round tool loop, and a seam for a custom wire format. See the [wire adapter recipe](https://ui.kitn.ai/guides/recipes/wire-adapter/).
 

package/dist/components/attachment-types.d.ts

@@ -8,5 +8,50 @@ export interface AttachmentData {
     url?: string;
     title?: string;
 }
-export type AttachmentMediaCategory = 'image' | 'video' | 'audio' | 'document' | 'source' | 'unknown';
+/**
+ * How an attachment is DRAWN, derived from what the wire can do with it.
+ *
+ * ★ THIS IS NOT A LIST OF MEDIA TYPES, and that is the whole point. It used to
+ * be one in disguise (`image | video | audio | document`, decided by a prefix
+ * switch in `attachments.tsx`), and it disagreed with `wire/media-types.ts` in
+ * both directions: SVG and MP4 drew a convincing preview that then threw at
+ * encode time, while PDF and text — the formats the wire handles best — drew
+ * the same anonymous icon as a `.zip`. `getMediaCategory` now asks the media
+ * policy and returns what it says, so there is one declaration and this is a
+ * projection of it.
+ *
+ * `image` / `document` / `text` ARE `EncodableKind` from `wire/media-types.ts`.
+ * They are spelled out rather than imported because this module is deliberately
+ * JSX-free and dependency-free for the framework-neutral consumers; the runtime
+ * agreement is pinned by `attachment-media-policy.test.tsx`, whose drift guard
+ * derives both sides from the policy.
+ *
+ * `video` and `audio` are GONE on purpose. No wire this kit ships can carry
+ * either, so they were categories whose only job was to make an unsendable file
+ * look sendable; both now land in `unsendable`.
+ */
+export type AttachmentMediaCategory = 
+/** A raster image in one of the four formats both APIs document. */
+'image'
+/** A PDF. Named for the Anthropic `document` block it becomes. */
+ | 'document'
+/** Text content — `text/*`, JSON, XML, YAML. Rides as text on both wires. */
+ | 'text'
+/** A RAG citation chip, not something the user staged. Never encoded. */
+ | 'source'
+/**
+ * No wire format this kit ships can carry this type — SVG, BMP, video, audio,
+ * archives. That is a fact about the kit's encoders, knowable at render time
+ * and true of every provider, which is why it is safe to show the user.
+ *
+ * It is NOT "this will fail to send": the renderer does not know which
+ * provider a thread is bound for, and must not pretend to.
+ */
+ | 'unsendable'
+/**
+ * Nobody named this file, so nothing is known yet. Its bytes decide it (see
+ * `classifyAttachment`), and they have not been read at render time. Marking
+ * it `unsendable` would be a guess wearing a fact's clothes.
+ */
+ | 'unknown';
 export type AttachmentVariant = 'grid' | 'inline' | 'list';

package/dist/components/attachments.d.ts

@@ -1,7 +1,38 @@
 import { JSX } from 'solid-js';
 import { AttachmentData, AttachmentMediaCategory, AttachmentVariant } from './attachment-types.js';
 export type { AttachmentData, AttachmentMediaCategory, AttachmentVariant } from './attachment-types.js';
+/**
+ * What to DRAW for this attachment, asked of the one module that knows.
+ *
+ * ★ NO MEDIA TYPES APPEAR BELOW, and that is the fix. This function used to be
+ * a prefix switch — `image/` → image, `video/` → video, `application/` or
+ * `text/` → document — a second list of media types in a repo whose media-type
+ * declaration says, at its own definition, "if you find yourself writing a
+ * second list of media types anywhere in this repo, delete it and read this".
+ * It had drifted in both directions: `image/svg+xml` came back `image` and drew
+ * a real thumbnail for a format the encoder refuses outright, while
+ * `application/json` came back `document` when the wire carries it as text.
+ *
+ * `DEFAULT_MEDIA_POLICY` and not a narrowed one, on purpose. A developer's
+ * `accept` filter says what a user may STAGE; it says nothing about what an
+ * already-staged attachment IS, and narrowing here would redraw a message
+ * retroactively when a host changed a prop. The default policy is the kit's
+ * full capability set, so `unsupported` against it means exactly "no wire
+ * format this kit ships can carry this" — which is the only claim about
+ * sendability the renderer can honestly make without knowing the provider.
+ */
 export declare const getMediaCategory: (data: AttachmentData) => AttachmentMediaCategory;
+/**
+ * The fact, written out, for the one category where the kit knows something the
+ * user needs to know.
+ *
+ * A FACT ABOUT THE FORMATS, NOT A PREDICTION ABOUT THIS REQUEST. At render time
+ * the kit does not know which provider the thread is bound for, so "this will
+ * fail" is not its to say. What it does know is that no wire format it ships
+ * has any representation for the type at all, which is true of every provider
+ * and is what this sentence claims.
+ */
+export declare const getUnsendableNote: (data: AttachmentData) => string | undefined;
 export declare const getAttachmentLabel: (data: AttachmentData) => string;
 interface AttachmentsContextValue {
     variant: AttachmentVariant;

package/dist/components/audio-visualizer/fit-scale.d.ts

@@ -0,0 +1,50 @@
+import { Accessor } from 'solid-js';
+/**
+ * Fit-to-container scaling (owner finding, rung 2): the size tiers are fixed
+ * px by design (`sizes.ts`), so a container narrower than a tier's natural
+ * footprint used to CLIP the picture at its edges. The dispatcher now scales
+ * the WHOLE visualization down proportionally to fit, and renders byte-equal
+ * to the designed px metrics whenever the container is at least natural size.
+ *
+ * Why a transform-scale wrapper rather than relative units or reflow:
+ * - The px tiers ARE the design (LiveKit parity); switching the geometry to
+ *   relative units would change rendering at every container size, not just
+ *   the overflowing ones.
+ * - Reflowing (fewer bars, smaller gaps) changes what the animation MEANS;
+ *   proportional scale keeps the exact picture, just smaller.
+ * - A transform also covers the shader variants for free: their canvases size
+ *   their backing store from layout size (`clientWidth`), which a transform
+ *   does not change, so the bitmap stays at full natural resolution and only
+ *   the composited output shrinks. No variant needs an exception.
+ *
+ * Both sizes are MEASURED (one ResizeObserver watching both wrappers), never
+ * restated from `sizes.ts`: the natural footprint depends on variant, size
+ * tier, barCount/count/radius and the consumer's own part styling, and a
+ * hand-derived width table would rot the day any of those moved.
+ *
+ * Where ResizeObserver does not exist (SSR, jsdom) this is inert: scale stays
+ * 1 and nothing is written, which is exactly the pre-fix rendering.
+ */
+export declare function computeFitScale(available: number | undefined, natural: number | undefined): number;
+export interface FitScale {
+    /** Ref for the outer wrapper (the host box, clamped by `max-width: 100%`). */
+    observeOuter: (el: HTMLElement) => void;
+    /** Ref for the inner wrapper (the natural-size content that gets scaled). */
+    observeInner: (el: HTMLElement) => void;
+    /** 1 when the content fits; the proportional shrink factor when it does not. */
+    scale: Accessor<number>;
+    /** The scaled content height in px while shrunk, else undefined: the outer
+     *  wrapper adopts it so the page never reserves the unscaled height. */
+    scaledHeight: Accessor<number | undefined>;
+}
+/**
+ * One ResizeObserver over both wrappers. ResizeObserver reports layout
+ * (border-box/content-box) sizes, which CSS transforms do not affect, so the
+ * inner wrapper keeps reporting its NATURAL size even while scaled, and the
+ * outer wrapper (whose `max-width: 100%` is what lets a narrow parent
+ * actually constrain it) reports the width the container is offering. The
+ * ratio of the two is the scale, with `computeFitScale` guarding the
+ * unmeasured/degenerate cases to 1 so a bad reading can never blank the
+ * element.
+ */
+export declare function createFitScale(): FitScale;

package/dist/components/audio-visualizer/index.d.ts

@@ -52,10 +52,24 @@ export interface AudioVisualizerProps {
     complexity?: number;
     /** Setting this makes the element an announced image instead of decorative. */
     label?: string;
+    /** Live audio to analyze. NOTE: amplitude renders only while
+     *  `state === 'speaking'` unless `listeningAmplitude` is set; every other
+     *  state plays its scripted animation and the analysis output is unused. */
     stream?: MediaStream;
+    /** Same speaking-only amplitude rule as `stream`: see `listeningAmplitude`. */
     audioElement?: HTMLMediaElement;
-    /** Pre-computed levels. Set this and no AudioContext is ever constructed. */
+    /** Pre-computed levels. Set this and no AudioContext is ever constructed.
+     *  Same speaking-only amplitude rule as `stream`: see `listeningAmplitude`. */
     bands?: number[];
+    /**
+     * Opt in to rendering live amplitude during `listening` as well, using the
+     * same presentation as `speaking`. Default off, which keeps LiveKit parity:
+     * amplitude (from `stream`, `audioElement` or `bands`) renders only while
+     * `state === 'speaking'`. Set this to show a real mic-level picture while
+     * the USER is the one talking. Forwarded to every variant; see
+     * `amplitudeRenderState` in variant-bar for the single mapping they share.
+     */
+    listeningAmplitude?: boolean;
     /**
      * Custom fragment shader for `variant="custom"`. See `ShaderSpec` for the
      * full contract -- most importantly, `fragment` MUST output premultiplied

package/dist/components/audio-visualizer/variant-bar.d.ts

@@ -5,8 +5,18 @@ import { VisualizerSize } from './sizes.js';
 export interface VariantProps {
     state: VisualizerState;
     size: VisualizerSize;
-    /** Multiband levels, 0..1. Only read while `state === 'speaking'`. */
+    /** Multiband levels, 0..1. Only read while `state === 'speaking'`, or also
+     *  while `'listening'` when `listeningAmplitude` is set. */
     bands: number[];
+    /**
+     * Opt in to rendering live amplitude during `listening` as well: the
+     * variant presents `listening` exactly as it presents `speaking` (live
+     * levels, lit geometry) while the host keeps reporting the real state via
+     * `data-kai-state`. Default off, which preserves LiveKit parity: amplitude
+     * renders only while `state === 'speaking'`, and every other state plays
+     * its scripted sequence. See `amplitudeRenderState`.
+     */
+    listeningAmplitude?: boolean;
     /** `prefers-reduced-motion`: pin the sequencer at its first frame. */
     frozen: boolean;
     /** Overrides the inherited `currentColor` the bars are painted with. */
@@ -41,6 +51,19 @@ export interface VariantProps {
  * `packages/shadcn/components/agents-ui/agent-audio-visualizer-bar.tsx`
  * (Apache License 2.0).
  */
+/**
+ * The state the RENDERING follows, as opposed to the state the consumer set.
+ *
+ * `listeningAmplitude` opts the `listening` state into the full speaking
+ * presentation: every variant routes its state-driven decisions (levels,
+ * highlight sequence, thresholds, volume overrides) through this ONE mapping
+ * rather than each patching its own `=== 'speaking'` gates, so the opt-in
+ * cannot half-apply within a variant. The host's `data-kai-state` deliberately
+ * keeps the REAL state, so CSS hooks and consumers observing the element are
+ * never lied to. With the flag absent or false this is the identity mapping,
+ * which is what keeps the default byte-identical to LiveKit parity.
+ */
+export declare function amplitudeRenderState(state: VisualizerState, listeningAmplitude: boolean | undefined): VisualizerState;
 export declare function BarVisualizer(props: VariantProps & {
     barCount?: number;
 }): JSX.Element;

package/dist/components/chat-thread.d.ts

@@ -98,8 +98,8 @@ export interface ChatThreadProps {
     accept?: MediaTypeFilter;
     /** Files the composer refused because `accept` excluded them. */
     onAttachmentsRejected?: (rejected: RejectedAttachment[]) => void;
-    /** Show a Search (Globe) button in the input toolbar; fires a `search` event. */
-    search?: boolean;
+    /** Show a web-search (Globe) button in the input toolbar; calls `onWebSearch`. */
+    webSearch?: boolean;
     /** Show a Voice (Mic) button in the input toolbar; fires a `voice` event. */
     voice?: boolean;
     /** Rich entity triggers. Each `{ char, kind, items }` opens a caret-anchored
@@ -120,7 +120,7 @@ export interface ChatThreadProps {
     onSuggestionClick?: (value: string) => void;
     onModelChange?: (modelId: string) => void;
     onMessageAction?: (detail: MessageActionDetail) => void;
-    onSearch?: () => void;
+    onWebSearch?: () => void;
     onVoice?: () => void;
     /** Receive the imperative controller once mounted. The kai-chat facade forwards
      *  these as element methods (focus/clear/send/scrollToBottom). */
@@ -134,42 +134,4 @@ export interface ChatThreadController {
     send(): void;
     scrollToBottom(behavior?: ScrollBehavior): void;
 }
-/**
- * THE MESSAGE LIST'S KEY, and the reason it is not the message object. This is
- * the canonical note; `thread.tsx` keys its identical list the same way and
- * points here.
- *
- *  `<For>` is REFERENCE-keyed, and a streaming assistant message gets a brand
- *  new object identity on every delta — `createAssistantStream` rebuilds it as
- *  `{ ...prev[i], parts: next }` because a new reference IS the re-render
- *  signal. Keyed on the objects, every chunk therefore looks like an entirely
- *  new list: the whole message row is torn down and rebuilt, and everything the
- *  user did inside it dies with it. Expanding a tool or reasoning panel
- *  mid-stream did nothing at all — the disclosure opened and was discarded
- *  microseconds later by the next token. (`MessageBody` keys its PARTS by
- *  position for exactly this reason; that fix was dead while its parent kept
- *  destroying the subtree above it.)
- *
- *  So key on `message.id`, which is stable across the object churn: `<For>` over
- *  the id array diffs by string value, a delta produces an identical id list,
- *  and no row moves. The row then reads its message through `messages[i()]` —
- *  `<For>`'s index accessor, which it keeps current across inserts, removals and
- *  moves — so the CONTENT keeps updating through accessors while the DOM stays
- *  put.
- *
- *  WHY NOT `<Index>`, the other way to survive the churn: `<Index>` keys by
- *  POSITION, so a row's local state (an open panel, a half-filled form card)
- *  belongs to the slot rather than to the message. Appends and tail truncations
- *  (regenerate/edit) are fine, but prepending older turns — load-earlier-history,
- *  which every real chat grows — shifts every row, and each open disclosure
- *  stays behind with the wrong message. Position IS a valid key inside a
- *  message, where the folds only ever append or patch a part in place; it is not
- *  one for the message list, where the host owns the array and splices it.
- *  Both approaches require the row to read through accessors — that is inherent
- *  in keeping a row mounted while its object is replaced, not a cost unique to
- *  either.
- *
- *  Contract: `id` must be unique per message. It already had to be — the
- *  feedback/copy state above this list is keyed by it.
- */
 export declare function ChatThread(props: ChatThreadProps): import("solid-js").JSX.Element;

package/dist/components/code-block.d.ts

@@ -1,6 +1,28 @@
 import { JSX } from 'solid-js';
 export interface CodeBlockProps extends JSX.HTMLAttributes<HTMLDivElement> {
     children?: JSX.Element;
+    /**
+     * Render a copy button in a header row above the code.
+     *
+     * DEFAULT OFF, and deliberately. This component is shared by three surfaces —
+     * `markdown.tsx` (every fenced block in every assistant message), `artifact.tsx`
+     * (the code panel), and the `<kai-code-block>` facade — and only the ELEMENT is
+     * documented as shipping a copy button. Defaulting on would add one to every code
+     * block in every message, a kit-wide visible change. The facade opts in; the other
+     * two are untouched, which `tests/elements/code-block.test.tsx` pins both
+     * behaviourally and at the call sites.
+     */
+    copy?: boolean;
+    /**
+     * The exact text the copy button puts on the clipboard.
+     *
+     * Named for what it DOES rather than what it holds, because the distinction is the
+     * whole contract: by the time the button is clicked the source has been through
+     * Shiki, so anything read back out of the DOM is either `<span>`-laden HTML or a
+     * `textContent` reconstruction — and the reconstruction is where tabs, blank lines
+     * and trailing newlines quietly change. This prop never goes near the highlighter.
+     */
+    copyText?: string;
 }
 declare function CodeBlock(props: CodeBlockProps): JSX.Element;
 export interface CodeBlockCodeProps extends JSX.HTMLAttributes<HTMLDivElement> {

package/dist/components/conversation-item.d.ts

@@ -1,3 +1,4 @@
+import { JSX } from 'solid-js';
 import { ConversationSummary } from '../types.js';
 export interface ConversationItemProps {
     conversation: ConversationSummary;
@@ -14,4 +15,56 @@ export interface ConversationItemProps {
  * ticking clock. Returns '' for a missing or unparseable date.
  */
 export declare function relativeTimeShort(iso?: string, now?: number): string;
-export declare function ConversationItem(props: ConversationItemProps): import("solid-js").JSX.Element;
+/**
+ * The slotted-item shape rendered by `<kai-conversation-item>` — the composed
+ * row of the consumer-owned loop (spec 2026-08-20 § 2a). Distinct from the
+ * data-mode `ConversationItem` above, which batteries mode keeps rendering
+ * unchanged: this one takes REGIONS, not a `ConversationSummary`.
+ *
+ * Regions map 1:1 to the element's slots: `children` = the default slot (the
+ * title), plus `leading`, `meta`, and `menu`. The `menu` region takes the
+ * consumer's OWN popover (rename / fork / archive live there); the component
+ * provides only the region plus focus and ARIA plumbing, never a declarative
+ * actions prop. Activation semantics live in the CONTAINER
+ * (`createConversationItemsController` in conversation-list.tsx): this row is
+ * presentational, and the `data-kai-item-menu` marker on the menu region is what
+ * the container's activation guard keys off so a click in the consumer's menu
+ * never also selects the row.
+ *
+ * ARIA contract for direct Solid use: the row renders `role="listitem"` holding
+ * a `role="button"` body (`aria-current` marks the active row, the same dialect
+ * as the batteries-mode row above) with the menu as the body's tabbable SIBLING
+ * (ratified 2026-08-20; axe `nested-interactive` bans focusable descendants of
+ * a control, and `aria-required-children` outlaws non-option content anywhere
+ * inside a listbox, which is why the vocabulary is not listbox/option). Render
+ * your loop's rows inside a `role="list"` ancestor; element mode has no such
+ * burden: `<kai-conversations>`' items region provides it for slotted items.
+ */
+export interface SlottedConversationItemProps {
+    /** The row's identity, handed to the container's selection contract. In the
+     *  element this is the `conversation-id` attribute (host `id` is the fallback). */
+    conversationId?: string;
+    /** Selected state. Reflected as `aria-current` on the row body and a
+     *  `data-active` styling hook on the row; the container drives it from its
+     *  `activeId`. */
+    active?: boolean;
+    /** Dense single-line row padding. */
+    compact?: boolean;
+    /** Leading region before the title (an icon or avatar). */
+    leading?: JSX.Element;
+    /** Meta region under the title (a timestamp or status line). */
+    meta?: JSX.Element;
+    /** Your own row menu (a popover trigger). Never selects the row. */
+    menu?: JSX.Element;
+    /** The title (the element's default slot). */
+    children?: JSX.Element;
+    /** Set when the element HOST carries the row-group semantics: the inner row
+     *  then renders `role="presentation"` so the accessibility tree sees one
+     *  group (the host), never two. The `kai-conversation-item` facade sets it;
+     *  Solid consumers rendering the component directly leave it off and the row
+     *  itself is the group. */
+    hostSemantics?: boolean;
+    class?: string;
+}
+export declare function SlottedConversationItem(props: SlottedConversationItemProps): JSX.Element;
+export declare function ConversationItem(props: ConversationItemProps): JSX.Element;

package/dist/components/conversation-list.d.ts

@@ -13,6 +13,57 @@ export interface CollapsedRailProps {
     class?: string;
 }
 export declare function CollapsedRail(props: CollapsedRailProps): JSX.Element;
+/** Read a conversation item's identity the way the container does: the
+ *  `conversationId` property, else the `conversation-id` attribute, else the
+ *  host `id`. The property is what a framework loop sets; the attributes are
+ *  the plain-HTML spellings (host `id` matches the `<kai-conversation>`
+ *  data-carrier precedent). */
+export declare function readConversationItemId(el: Element): string;
+export interface ConversationItemsControllerOptions {
+    /** The current slotted item hosts, in DOM order. */
+    getItems: () => HTMLElement[];
+    /** The container's active conversation id. */
+    getActiveId: () => string | undefined;
+    /** Item activation (click / Enter / Space). Surfaces as
+     *  `kai-conversation-select` on the element. */
+    onSelect: (id: string) => void;
+}
+export interface ConversationItemsController {
+    /** Re-derive the ARIA/roving-tabindex bookkeeping over the current items.
+     *  Call on slotchange / child mutation and whenever `activeId` changes. */
+    sync(): void;
+    /** The container's items-region click handler (composed-path aware). */
+    handleClick(e: MouseEvent): void;
+    /** The container's items-region keydown handler (arrows, Home/End,
+     *  Enter/Space). */
+    handleKeyDown(e: KeyboardEvent): void;
+}
+/**
+ * The parent-item contract of item mode (spec 2026-08-20 § 2a), as a pure-DOM
+ * controller so it is host-agnostic: the `kai-conversations` facade wires it over
+ * its slotted `kai-conversation-item` children, and the jsdom contract tests
+ * drive it over plain nodes. Solid context cannot cross the element boundary
+ * (each facade is its own Solid root), so the channel is DOM traversal by
+ * construction:
+ *
+ * - selection flows container to item — exactly one item's BODY node (the
+ *   shadow body of a `kai-conversation-item`, else the node itself; see
+ *   `bodyOf`) is `aria-current="true"`, plus the `active` property on the
+ *   host for the item's own styling hook;
+ * - `role="button"` is ensured on each item's body node (an authored role is
+ *   left alone);
+ * - roving tabindex — exactly one body node `tabindex="0"` (the active
+ *   item's, else the first's), the rest `-1`, re-derived on every `sync()`;
+ *   menu content keeps its natural tab order (it is the body's SIBLING, per
+ *   the ratified 2026-08-20 sibling restructure);
+ * - activation (click / Enter / Space) calls `onSelect` with the item's id, and
+ *   is SUPPRESSED when the composed path crosses the item's `menu` region
+ *   (light-DOM `slot="menu"` content or the shadow `data-kai-item-menu`
+ *   wrapper), so the consumer's own popover never also selects the row;
+ * - ArrowUp/ArrowDown/Home/End move focus item-to-item, tabindex following the
+ *   focused item.
+ */
+export declare function createConversationItemsController(opts: ConversationItemsControllerOptions): ConversationItemsController;
 export interface ConversationListProps {
     groups: ConversationGroup[];
     conversations: ConversationSummary[];
@@ -34,6 +85,20 @@ export interface ConversationListProps {
     /** Receive the imperative controller once mounted. The `kai-conversations`
      *  facade uses it to focus / clear the internal search input. */
     controllerRef?: (controller: ConversationListController) => void;
+    /** Item mode (spec 2026-08-20 § 2a): the consumer's OWN rows, rendered inside
+     *  a list region in place of the data rows. When set, the built-in search
+     *  filter, grouping and empty/no-match states do not apply — the consumer's
+     *  loop owns them — while the chrome (header, search box, new-chat, footer)
+     *  still renders and `onSearchChange` still reports queries. The
+     *  `kai-conversations` facade passes its default `<slot>` here when it detects
+     *  `kai-conversation-item` children. */
+    items?: JSX.Element;
+    /** Keydown handler for the item-mode list region (the facade wires
+     *  `createConversationItemsController.handleKeyDown`). */
+    itemsKeyDown?: (e: KeyboardEvent) => void;
+    /** Click handler for the item-mode list region (the facade wires
+     *  `createConversationItemsController.handleClick`). */
+    itemsClick?: (e: MouseEvent) => void;
     class?: string;
 }
 /** Imperative handle exposed via `controllerRef` — surfaces the internal search

package/dist/components/form.d.ts

@@ -94,3 +94,45 @@ export interface FormProps {
  * `kai-card` CustomEvent.
  */
 export declare function Form(props: FormProps): JSX.Element;
+interface FieldRowProps {
+    fieldKey: string;
+    field: FormField;
+    required: boolean;
+    inlineMax: number;
+    value: () => unknown;
+    error: () => string | undefined;
+    disabled: boolean;
+    onInput: (value: unknown) => void;
+    onBlur: () => void;
+}
+/**
+ * The widget prop bag for one field row. **Internal** — exported only so the
+ * subscription contract can be pinned directly
+ * (`tests/components/form-field-subscriptions.test.tsx`); it is not re-exported
+ * from the package.
+ *
+ * GETTERS, NOT AN OBJECT FACTORY, and this is the whole point (K-D12b). The
+ * factory read `props.value()` alongside everything else and rebuilt the bag on
+ * every call, so a reader of ANY prop — `invalid`, say — subscribed to `value`
+ * too and re-ran on every keystroke. Combined with the `<input>` being rebuilt
+ * when its class expression re-ran (K-D12a), that is what made typing into a
+ * `kai-form` text field lose focus after each character.
+ *
+ * One stable object with one getter per prop: each reader tracks exactly the
+ * signal behind the prop it read. The object identity is constant, so the
+ * `WidgetSwitch` prop below never changes either.
+ */
+export declare function fieldCommon(props: FieldRowProps, id: string, placeholder: () => string | undefined, label: () => string, describedBy?: () => string | undefined): ReturnType<FieldRowCommon>;
+type FieldRowCommon = () => {
+    id: string;
+    value: unknown;
+    field: FormField;
+    disabled: boolean;
+    placeholder?: string;
+    required: boolean;
+    invalid: boolean;
+    describedBy?: string;
+    label: string;
+    onInput: (v: unknown) => void;
+    onBlur: () => void;
+};

package/dist/components/message.d.ts

@@ -123,6 +123,13 @@ export interface MessageBodyProps {
     activeFeedback?: FeedbackVote;
     /** When true, the copy button shows its "copied" check icon. */
     copied?: boolean;
+    /** Whether this message is the one currently streaming. Forwarded to each
+     *  reasoning part's `<Reasoning>` so the disclosure auto-opens while the
+     *  model is thinking and settles back once the stream ends (F-21: without it
+     *  the user watches a static collapsed "Reasoning" label for the whole
+     *  thinking window). The caller owns the definition of "streaming" — for
+     *  `ChatThread` that is `loading` + being the last assistant message. */
+    isStreaming?: boolean;
     /** INJECT slot projected at the TOP of the body — above the reasoning / tools /
      *  content. A per-message header: a model-name label, a role + timestamp line.
      *  In the `<kai-message>` shadow this is `<slot name="before-body" />`. */

package/dist/components/toast.d.ts

@@ -53,6 +53,7 @@ export declare function Toast(props: ToastProps): import("solid-js").JSX.Element
  * Renders a stack of toasts at a viewport edge. Caps the visible count at `max`
  * (newest on top); overflow waits in a queue and is promoted as visible toasts
  * leave. `aria-live=polite` / `role=region` so screen readers announce new
- * toasts without stealing focus.
+ * toasts without stealing focus. Your app chrome must stay below the toast
+ * layer; set `--kai-toast-z` (default 100) on the host to move the layer.
  */
 export declare function ToastRegion(props: ToastRegionProps): import("solid-js").JSX.Element;

package/dist/components/voice-input.d.ts

@@ -30,5 +30,13 @@ export interface VoiceInputProps {
     /** Receive the imperative controller once mounted. The `<kai-voice-input>`
      *  facade forwards these as element methods (start/stop). */
     controllerRef?: (controller: VoiceInputController) => void;
+    /** A recognition session failed or produced nothing. `error` is the platform
+     *  error code, the thrown exception's name, or `no-result` when the session
+     *  ended with no error and no text. The facade maps this to kai-voice-error. */
+    onError?: (detail: {
+        source: 'recognition';
+        error: string;
+        message: string;
+    }) => void;
 }
 export declare function VoiceInput(props: VoiceInputProps): import("solid-js").JSX.Element;

package/dist/components/voice-output.d.ts

@@ -20,8 +20,19 @@ export interface VoiceOutputProps {
     /** TTS model seam: given text, return an audio Blob to play. When set, the
      *  native speechSynthesis path is bypassed. Mirrors VoiceInput's `onTranscribe`. */
     onSynthesize?: (text: string) => Promise<Blob>;
-    /** Fires whenever playback starts or stops. */
+    /** Fires whenever playback starts or stops. `speaking: true` means audio has
+     *  actually started (utterance.onstart on the native path; audio.play()
+     *  resolving on the model path), not that speak() was called. */
     onSpeakingChange?: (speaking: boolean) => void;
+    /** Synthesis failed: a native utterance error, a rejecting `onSynthesize`, or
+     *  audio playback failing to start. `error` is the platform error code or the
+     *  exception's name. Deliberate cancellation (stop(), a new speak()) is not a
+     *  failure and does not fire. The facade maps this to kai-voice-error. */
+    onError?: (detail: {
+        source: 'synthesis';
+        error: string;
+        message: string;
+    }) => void;
     /** Fires once the model path resolves audio (model path only). */
     onSynthesized?: (blob: Blob) => void;
     disabled?: boolean;