@kitn.ai/ui 0.25.2 → 0.27.0

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,68 @@ 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. 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 has two modes: inside `<kai-conversations>` it
+ * lives in the CONTAINER (`createConversationItemsController` in
+ * conversation-list.tsx — this row renders no handler 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); STANDALONE, `onActivate` makes the row body
+ * its own tabbable button-role control — click / Enter / Space — with the menu
+ * still outside the control as the body's sibling.
+ *
+ * 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
+ * (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;
+    /** STANDALONE activation: when set, the row body is itself the
+     *  activation control — `tabindex="0"` on the `role="button"` body, and
+     *  click / Enter / Space call this. The menu region never triggers it (it is
+     *  the body's sibling, outside the control). Inside `<kai-conversations>`
+     *  leave it UNSET: the container's controller owns activation (its delegated
+     *  click/keydown → `kai-conversation-select`) plus roving tabindex, and a
+     *  handler here would double-fire. The `kai-conversation-item` facade passes
+     *  it only when the item is standalone. */
+    onActivate?: () => void;
+    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,69 @@ 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;
+/** Whether a `<kai-conversation-item>` is STANDALONE — outside the management
+ *  of a `<kai-conversations>` container — and therefore activates ITSELF:
+ *  the facade makes its row body a
+ *  tabbable button and fires `kai-select` on click / Enter / Space. Derived
+ *  from the container's own membership rule, not from mere ancestry: item mode
+ *  queries `:scope > kai-conversation-item` (direct children only), so an item
+ *  wrapped in another element inside a container is standalone too — the
+ *  container's controller never stamps or activates it. Inside a container
+ *  (a direct child), the parent-item contract is the ONLY activation
+ *  path: the container dispatches `kai-conversation-select` and owns roving
+ *  tabindex, and the item fires nothing of its own. */
+export declare function isStandaloneConversationItem(el: Element): boolean;
+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, 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, not a
+ *   descendant);
+ * - 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 +97,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: your 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-widgets.d.ts

@@ -1,16 +1,37 @@
 import { JSX } from 'solid-js';
-import { FormField } from './form.js';
+import { FieldMaskHint, FormField } from './form.js';
 /** The shared prop shape every leaf widget receives from FieldRow. */
 export interface WidgetProps {
     id: string;
     value: unknown;
     field: FormField;
+    /**
+     * The field's resolved format hints, or an empty resolution.
+     *
+     * RESOLVED IN `FieldRow`, not here. The row already has to resolve them to render
+     * the format hint text and put its id in `aria-describedby`, and resolving the same
+     * untrusted `x-kai-*` keys a second time in the widget would warn twice about the
+     * same bad hint and could disagree with what the row said out loud.
+     */
+    mask?: FieldMaskHint;
     disabled: boolean;
     placeholder?: string;
     required: boolean;
     invalid: boolean;
     describedBy?: string;
     label: string;
+    /**
+     * The id of the row's VISIBLE label element, for widgets whose control is a group
+     * rather than one labelable input.
+     *
+     * `FieldRow` used to suppress its `<label>` for those kinds and each widget named
+     * itself with `aria-label={props.label}`, which is a name only a screen reader can
+     * reach: "Severity", "Environments" and "Tags" were announced and invisible. The row
+     * now always renders the text and hands its id down here, so one string names the
+     * group and everybody can see it. Absent means the widget is on its own (a bare
+     * widget rendered outside `FieldRow`), so `aria-label` stays the fallback.
+     */
+    labelledBy?: string;
     onInput: (value: unknown) => void;
     onBlur: () => void;
 }
@@ -22,10 +43,54 @@ export declare function TextareaWidget(props: WidgetProps): JSX.Element;
 export declare function NumberWidget(props: WidgetProps): JSX.Element;
 export declare function SliderWidget(props: WidgetProps): JSX.Element;
 export declare function RatingWidget(props: WidgetProps): JSX.Element;
+/**
+ * The boolean field's switch IS `ui/switch.tsx` — it is not a lookalike.
+ *
+ * This used to hand-roll its own `<button role="switch">` at 44×24 while
+ * `<kai-switch>` shipped the same control at 36×20, so a consumer putting the two
+ * side by side saw two different switches; and its thumb used `bg-background`,
+ * re-introducing in the copy the dark-mode disappearing-thumb bug that
+ * `ui/switch.tsx:80` carries a comment about having fixed. Delegating removes both.
+ * The size convergence (44×24 → 36×20) is visible inside `kai-form` and intended.
+ *
+ * The four form-only hooks — `id`, `data-control` and the `aria-required` /
+ * `aria-invalid` / `aria-describedby` trio — are ordinary props now (plan decision
+ * D-7). They used to be stamped onto the button through `buttonRef` + a
+ * `createEffect`, which worked but meant this widget reached into the primitive's
+ * DOM to make `form.focusField()` land. `Switch` forwards anything it does not own
+ * to its inner button, exactly like `Checkbox` and `Radio` forward to their inputs,
+ * so all four ride the same path every other widget's hooks do.
+ */
 export declare function SwitchWidget(props: WidgetProps): JSX.Element;
 export declare function CheckboxWidget(props: WidgetProps): JSX.Element;
 export declare function RadioGroupWidget(props: WidgetProps): JSX.Element;
 export declare function SelectWidget(props: WidgetProps): JSX.Element;
-export declare function CheckboxGroupWidget(props: WidgetProps): JSX.Element;
+/**
+ * An array field whose items are an `enum`, as a list of checkboxes.
+ *
+ * The bordered/divided row chrome, the `role="group"` wrapper and the rows themselves
+ * live in `ui/checkbox-group.tsx` now — this widget only turns a JSON-Schema
+ * `items.enum` into options and owns the array in and out. It used to hand-roll the
+ * identical chrome beside `RadioGroup`, which already owned it.
+ *
+ * The emitted array holds the SCHEMA's values, not their string forms, so a numeric
+ * or boolean enum survives a round trip.
+ */
+export declare function CheckboxGroupWidget(props: WidgetProps & {
+    class?: string;
+}): JSX.Element;
+/**
+ * The LONG version of `checkbox-group`: an array-of-enum field whose option list is
+ * over the row's `inlineMax`.
+ *
+ * This was a `<select multiple>` until decision D-3 was ruled. `<select multiple>` is a
+ * poor control on every platform — the multi-select affordance is invisible, discovering
+ * it means knowing to ctrl/cmd-click, and there is no touch story at all. It is the same
+ * control as `checkbox-group`, so it renders as one, with a scroll cap because the only
+ * thing that made a long list bearable in a chat card was the select's fixed-height box.
+ *
+ * The scroll cap is a presentation decision (how a long list fits), not a limit: every
+ * option is rendered, nothing is truncated or dropped.
+ */
 export declare function MultiSelectWidget(props: WidgetProps): JSX.Element;
 export declare function TagListWidget(props: WidgetProps): JSX.Element;

package/dist/components/form.d.ts

@@ -1,5 +1,6 @@
 import { JSX } from 'solid-js';
 import { CardHost, CardResolution } from '../primitives/card-contract.js';
+import { FieldSemanticType } from '../primitives/field-semantics.js';
 import { FormDefinition, FormField } from '../primitives/card-data-types.js';
 export type { FormCardEnvelope, FormDefinition, FormField, } from '../primitives/card-data-types.js';
 /** The internal widget identifiers `widgetFor` resolves to. */
@@ -8,6 +9,49 @@ export declare const DEFAULT_INLINE_MAX = 4;
 /** Resolve the widget for a field. An explicit valid `x-kai-widget` always wins;
  *  otherwise the type/format/enum/constraint combination selects the widget. */
 export declare function widgetFor(field: FormField, inlineMax: number): WidgetKind;
+/**
+ * What one field's `x-kai-*` format hints resolve to.
+ *
+ * The three props on the left are `Input`'s masking surface verbatim;
+ * `hint` is the TEXT statement of the expected format, which `FieldRow` renders and
+ * links through its EXISTING `aria-describedby` chain (no third channel).
+ * Every field is `undefined` when the field carries no hints, which is what "byte for
+ * byte the behavior of today" means here.
+ */
+export interface FieldMaskHint {
+    /** The compiled-clean mask pattern handed to `Input`'s `format`. */
+    format?: string;
+    /** An explicit, aligned display guide. Absent = the pattern derives its own. */
+    guide?: string;
+    /** The tier-1 semantic type: `inputmode`, `autocomplete`, and the canonical form. */
+    semantic?: FieldSemanticType;
+    /** The expected format, stated in text for the description chain. */
+    hint?: string;
+    /**
+     * Everything that was ignored and why, as DATA rather than as a side effect.
+     *
+     * Resolution runs inside a memo on a render path, so it must never throw and must
+     * not warn twice for the same reason on a re-render. Returning the messages lets
+     * `FieldRow` own the once-per-row discipline and lets the pure tests assert the
+     * wording without a console spy.
+     */
+    warnings: string[];
+}
+/** The resolution of a field with no format hints: shared, frozen, and the default
+ *  every non-text widget carries so the prop bag has one shape. */
+export declare const EMPTY_MASK_HINT: FieldMaskHint;
+/**
+ * Resolve a field's `x-kai-format` / `x-kai-mask` / `x-kai-mask-guide` into the
+ * masking props `Input` takes, or into nothing at all.
+ *
+ * EVERY INPUT HERE IS MODEL OUTPUT and therefore untrusted. The hints are
+ * display-only — they produce text and caret positions, never HTML, a URL or an
+ * attribute on a navigable element — so this is about denial of service and
+ * confusion, not injection: an unknown token, a pattern the engine refuses and a
+ * misaligned guide each degrade to the largest thing that still works, and say so.
+ * A THROW here would take out the whole card, including the fields that were fine.
+ */
+export declare function resolveFieldMask(field: FormField, fieldKey?: string): FieldMaskHint;
 /** Humanize a camelCase / snake_case property key into a label. */
 export declare function humanize(key: string): string;
 /** Field order: `x-kai-order` (filtered to known keys, missing appended) if
@@ -94,3 +138,48 @@ 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, mask?: () => FieldMaskHint, labelledBy?: () => string | undefined): ReturnType<FieldRowCommon>;
+type FieldRowCommon = () => {
+    id: string;
+    value: unknown;
+    mask: FieldMaskHint;
+    field: FormField;
+    disabled: boolean;
+    placeholder?: string;
+    required: boolean;
+    invalid: boolean;
+    describedBy?: string;
+    label: string;
+    /** The id of the row's visible <label>, for widgets that name a GROUP. */
+    labelledBy?: string;
+    onInput: (v: unknown) => void;
+    onBlur: () => void;
+};

package/dist/components/message.d.ts

@@ -105,6 +105,12 @@ export interface MessageBodyProps {
      *  the kit checks its own seven built-ins and leaves your own card type
      *  unvalidated. A schema here WINS over a built-in of the same name. */
     cardSchemas?: CardSchemaMap;
+    /** The custom-element host node to emit card events off when no `CardProvider`
+     *  is above this body, forwarded to `CardRenderer` as `hostElement`. The
+     *  `<kai-chat>`/`<kai-message>`/`<kai-thread>` facades pass their own element,
+     *  so a `card` part's events leave as the bubbling `kai-card` CustomEvent
+     *  instead of being silently discarded. */
+    cardHostElement?: HTMLElement;
     /** Whether this is a user message (right-aligned bubble) vs an assistant
      *  message (full-width transparent). */
     isUser: boolean;
@@ -123,6 +129,29 @@ 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. 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;
+    /** How a `reasoning` part renders. `'full'` (default) is the current
+     *  behavior: the collapsible `<Reasoning>` disclosure, with the "Thinking…"
+     *  shimmer on its trigger while `isStreaming`. `'compact'` drops the
+     *  disclosure entirely and shows only a shimmer loader while the part is
+     *  streaming — nothing once it settles, so there is no expandable detail to
+     *  open. `'off'` renders the part not at all, in either state. Kit-decides-
+     *  HOW: this is a display-mode fact about the medium, not a per-message
+     *  toggle, so it applies uniformly to every reasoning part in the body. */
+    reasoningMode?: 'full' | 'compact' | 'off';
+    /** 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 `reasoningMode` is
+     *  `'compact'`/`'off'` (no disclosure exists to open). */
+    reasoningDefaultOpen?: 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/reasoning.d.ts

@@ -18,6 +18,12 @@ export interface ReasoningProps {
     disabled?: boolean;
     /** Receive the open controller (open accessor + setOpen) once mounted. */
     controllerRef?: (api: ReasoningController) => void;
+    /** Keep auto-opening while streaming and auto-closing when it settles (the
+     *  pre-Task-19f `full` behavior). Default false: the panel starts per
+     *  `defaultOpen` and stays exactly where the user leaves it — streaming only
+     *  changes the trigger's label (shimmer), never the open state, matching the
+     *  "closed chip, expand on click" default (owner ruling, 2026-08-26). */
+    openOnStream?: boolean;
 }
 declare function Reasoning(props: ReasoningProps): JSX.Element;
 export interface ReasoningTriggerProps extends JSX.ButtonHTMLAttributes<HTMLButtonElement> {

package/dist/components/scroll-button.d.ts

@@ -2,6 +2,17 @@ export interface ScrollButtonProps {
     class?: string;
     variant?: 'outline' | 'ghost' | 'default';
     size?: 'sm' | 'md' | 'lg' | 'icon' | 'icon-sm';
+    /**
+     * The button's accessible name. Used whether or not the label is visible, so
+     * the announced text is always localisable. Defaults to `"Scroll to bottom"`.
+     */
+    label?: string;
+    /**
+     * Also render `label` visibly beside the icon. Defaults to `false` (icon
+     * only). When it is visible the text IS the accessible name, so nothing is
+     * announced twice.
+     */
+    showLabel?: boolean;
 }
 declare function ScrollButton(props: ScrollButtonProps): import("solid-js").JSX.Element;
 export { ScrollButton };

package/dist/components/thread.d.ts

@@ -27,6 +27,11 @@ export interface ThreadProps {
      *  the kit checks its own seven built-ins and leaves your own card type
      *  unvalidated. A schema here WINS over a built-in of the same name. */
     cardSchemas?: CardSchemaMap;
+    /** The custom-element host node to emit card events off when no `CardProvider`
+     *  is present, forwarded through `MessageBody` to `CardRenderer`. The
+     *  element facades pass their own host element so card events leave as the
+     *  bubbling `kai-card` CustomEvent. */
+    cardHostElement?: HTMLElement;
     /** Show a typing indicator on the pending assistant turn — use while awaiting
      *  the assistant's reply. */
     loading?: boolean;

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/tool-types.d.ts

@@ -23,6 +23,15 @@ export interface ToolPart {
     type: string;
     /** Semantic classification for rendering. Derive with classifyTool(type). */
     kind?: ToolKind;
+    /** The call's lifecycle. A provider stream (real or `createMockResponder`)
+     *  only ever ANNOUNCES a call: arguments stream in (`input-streaming`), then
+     *  the part parks at `input-available` — and stays there. The kit parses and
+     *  renders the call; EXECUTING it and answering is the host's side of the
+     *  seam: after the read settles, run the tool and patch the part forward with
+     *  `stream.upsertTool(id, { state: 'output-available', output })` (or
+     *  `upsertToolPart`), or `output-error` + `errorText` on failure. The one
+     *  exception is a call the provider ran itself (`raw` carries the result and
+     *  the wire sets `output` directly) — never re-execute those. */
     state: 'input-streaming' | 'input-available' | 'output-available' | 'output-error';
     /** Last VALID parsed snapshot, fingerprint-deduped. The primary channel: this is
      *  what the kit renders. */

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;

package/dist/components/workspace-shell.d.ts

@@ -0,0 +1,87 @@
+import { JSX } from 'solid-js';
+/** The two aside columns of the shell, named logically (`start` follows the
+ *  writing direction; on an RTL page it is the right column). */
+export type WorkspaceAsideSide = 'start' | 'end';
+/** Detail of an aside collapse/expand, however it happened (a method, the
+ *  breakpoint, the drawer's Escape). */
+export interface WorkspaceAsideToggleDetail {
+    side: WorkspaceAsideSide;
+    collapsed: boolean;
+}
+/** Detail of an aside resize (fires per drag step, keyboard nudge, or a handle double-click reset), width in px. */
+export interface WorkspaceAsideResizeDetail {
+    side: WorkspaceAsideSide;
+    width: number;
+}
+/** Imperative surface exposed through `controllerRef` (the facade forwards it
+ *  as element methods). */
+export interface WorkspaceShellController {
+    /** Collapse/expand one aside (reports through onAsideToggle). */
+    toggleAside(side: WorkspaceAsideSide): void;
+    /** Force one aside collapsed (reports through onAsideToggle). */
+    collapseAside(side: WorkspaceAsideSide): void;
+    /** Force one aside expanded (reports through onAsideToggle). */
+    expandAside(side: WorkspaceAsideSide): void;
+}
+export interface WorkspaceShellProps {
+    /** Header band content. The region renders only when this is provided. */
+    header?: JSX.Element;
+    /** Start aside content (the inline-start column: a rail, a nav, a file tree).
+     *  The region renders only when this is provided. */
+    start?: JSX.Element;
+    /** End aside content (the inline-end column: inspector, notes, preview).
+     *  The region renders only when this is provided. */
+    end?: JSX.Element;
+    /** Footer band content. The region renders only when this is provided. */
+    footer?: JSX.Element;
+    /** Main region content. Always rendered. */
+    children?: JSX.Element;
+    /** Controlled collapsed state of the start aside. Omit for uncontrolled. */
+    startCollapsed?: boolean;
+    /** Initial collapsed state of the start aside when uncontrolled (default false). */
+    defaultStartCollapsed?: boolean;
+    /** Controlled collapsed state of the end aside. Omit for uncontrolled. */
+    endCollapsed?: boolean;
+    /** Initial collapsed state of the end aside when uncontrolled (default false). */
+    defaultEndCollapsed?: boolean;
+    /** Start aside default width in px (default 280). */
+    startWidth?: number;
+    /** Start aside minimum width in px during resize (default 200). */
+    startMinWidth?: number;
+    /** Start aside maximum width in px during resize (default 480). */
+    startMaxWidth?: number;
+    /** End aside default width in px (default 320). */
+    endWidth?: number;
+    /** End aside minimum width in px during resize (default 200). */
+    endMinWidth?: number;
+    /** End aside maximum width in px during resize (default 480). */
+    endMaxWidth?: 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. */
+    collapseBelow?: 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. */
+    drawerBelow?: number;
+    /** 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. */
+    compact?: boolean;
+    /** An aside collapsed or expanded (any path: method, breakpoint, drawer Escape). */
+    onAsideToggle?: (detail: WorkspaceAsideToggleDetail) => void;
+    /** The aside was resized (fires per drag step, keyboard nudge, or a handle double-click reset), width in px. */
+    onAsideResize?: (detail: WorkspaceAsideResizeDetail) => void;
+    /** Receives the imperative controller once on mount. */
+    controllerRef?: (controller: WorkspaceShellController) => void;
+    class?: string;
+}
+/**
+ * The chat-agnostic workspace layout shell: five regions (header · start aside ·
+ * main · end aside · footer) with resize handles between the columns, per-aside
+ * controlled/uncontrolled collapse, collapse-below-breakpoint, and a mobile
+ * drawer mode for the asides. It knows nothing about chat: a file tree in
+ * `start` is as valid as a conversation rail.
+ */
+export declare function WorkspaceShell(props: WorkspaceShellProps): JSX.Element;