@kitn.ai/ui 0.25.2 → 0.26.0

package/src/components/conversation-list.tsx

@@ -30,6 +30,160 @@ export function CollapsedRail(props: CollapsedRailProps) {
   );
 }
 
+/** 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 function readConversationItemId(el: Element): string {
+  const prop = (el as Element & { conversationId?: unknown }).conversationId;
+  if (typeof prop === 'string' && prop) return prop;
+  return el.getAttribute('conversation-id') ?? el.id;
+}
+
+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 function createConversationItemsController(
+  opts: ConversationItemsControllerOptions,
+): ConversationItemsController {
+  const itemFromEvent = (e: Event): HTMLElement | undefined => {
+    const items = opts.getItems();
+    return e.composedPath().find((n): n is HTMLElement => items.includes(n as HTMLElement));
+  };
+  /** The item's ACTIVATION node — the target of role/aria-current/tabindex/
+   *  focus. For a `kai-conversation-item` host that is its shadow body (the
+   *  sibling restructure, ratified 2026-08-20: the host is the row listitem
+   *  wrapping the body AND the consumer's tabbable menu, so the control
+   *  semantics must sit below it). A bare node with no such body is its own
+   *  control. */
+  const bodyOf = (item: HTMLElement): HTMLElement =>
+    (item.shadowRoot?.querySelector('[data-kai-item-body]') as HTMLElement | null) ?? item;
+  const menuInPath = (e: Event): boolean =>
+    e.composedPath().some(
+      (n) =>
+        n instanceof Element &&
+        (n.hasAttribute('data-kai-item-menu') || n.getAttribute('slot') === 'menu'),
+    );
+  // Write-on-change only. `setAttribute` records a mutation even when the value
+  // is identical, and the facade re-syncs from a MutationObserver over these very
+  // nodes — unconditional writes would feed the observer forever.
+  const setAttr = (el: Element, name: string, value: string) => {
+    if (el.getAttribute(name) !== value) el.setAttribute(name, value);
+  };
+  /** An item whose shadow body has not RENDERED yet must not be stamped: the
+   *  fallback would write control semantics onto the HOST, they would stick
+   *  (the item facade defers to an authored role), and axe then sees exactly
+   *  the role="button"-host-with-focusable-menu shape the restructure removed.
+   *  Measured in the focus-order probe: the container's first sync can run
+   *  before the item elements upgrade. A later sync catches them — the
+   *  facade's own mount mutates host attributes, which re-runs sync through
+   *  the container's MutationObserver read(). Bare nodes (no dash: the jsdom
+   *  stand-ins) are always ready. */
+  const readyBodies = (items: HTMLElement[]) => {
+    const out = new Map<HTMLElement, HTMLElement>();
+    for (const item of items) {
+      const body = bodyOf(item);
+      if (body === item && item.localName.includes('-')) continue;
+      out.set(item, body);
+    }
+    return out;
+  };
+
+  const rove = (items: HTMLElement[], target: HTMLElement | undefined) => {
+    for (const [item, body] of readyBodies(items)) setAttr(body, 'tabindex', item === target ? '0' : '-1');
+  };
+
+  const sync = () => {
+    const items = opts.getItems();
+    const activeId = opts.getActiveId();
+    const bodies = readyBodies(items);
+    let anchor: HTMLElement | undefined;
+    for (const [item, body] of bodies) {
+      const isActive = activeId !== undefined && readConversationItemId(item) === activeId;
+      if (!body.hasAttribute('role')) body.setAttribute('role', 'button');
+      setAttr(body, 'aria-current', isActive ? 'true' : 'false');
+      const host = item as HTMLElement & { active?: boolean };
+      if (host.active !== isActive) host.active = isActive;
+      if (isActive) anchor = item;
+    }
+    rove(items, anchor ?? (bodies.keys().next().value as HTMLElement | undefined));
+  };
+
+  return {
+    sync,
+    handleClick(e) {
+      const item = itemFromEvent(e);
+      if (!item || menuInPath(e)) return;
+      opts.onSelect(readConversationItemId(item));
+    },
+    handleKeyDown(e) {
+      const items = opts.getItems();
+      if (items.length === 0) return;
+      const item = itemFromEvent(e);
+      if (e.key === 'Enter' || e.key === ' ') {
+        if (!item || menuInPath(e)) return;
+        e.preventDefault();
+        opts.onSelect(readConversationItemId(item));
+        return;
+      }
+      let next: HTMLElement | undefined;
+      const idx = item ? items.indexOf(item) : items.findIndex((i) => bodyOf(i).getAttribute('tabindex') === '0');
+      if (e.key === 'ArrowDown') next = items[Math.min(idx + 1, items.length - 1)];
+      else if (e.key === 'ArrowUp') next = items[Math.max(idx - 1, 0)];
+      else if (e.key === 'Home') next = items[0];
+      else if (e.key === 'End') next = items[items.length - 1];
+      if (!next) return;
+      e.preventDefault();
+      rove(items, next);
+      bodyOf(next).focus();
+    },
+  };
+}
+
 export interface ConversationListProps {
   groups: ConversationGroup[];
   conversations: ConversationSummary[];
@@ -51,6 +205,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;
 }
 
@@ -64,8 +232,10 @@ export interface ConversationListController {
 }
 
 export function ConversationList(props: ConversationListProps) {
-  const [local] = splitProps(props, ['groups', 'conversations', 'activeId', 'onSelect', 'onNewChat', 'onToggleSidebar', 'header', 'footer', 'empty', 'compact', 'onSearchChange', 'controllerRef', 'class']);
+  const [local] = splitProps(props, ['groups', 'conversations', 'activeId', 'onSelect', 'onNewChat', 'onToggleSidebar', 'header', 'footer', 'empty', 'compact', 'onSearchChange', 'controllerRef', 'items', 'itemsKeyDown', 'itemsClick', 'class']);
   const [searchQuery, setSearchQuery] = createSignal('');
+  // Item mode: the consumer's own rows replace the data rendering wholesale.
+  const itemMode = createMemo(() => local.items != null);
   const isEmpty = createMemo(() => local.conversations.length === 0);
   // The search query is owned here; setQuery is the single mutation point so both
   // typing and the imperative clearSearch() notify the facade (→ kai-search).
@@ -133,7 +303,7 @@ export function ConversationList(props: ConversationListProps) {
       >
         {local.header}
       </Show>
-      <Show when={!isEmpty()}>
+      <Show when={itemMode() || !isEmpty()}>
         <div class="px-3 pb-2">
           <div class="flex items-center gap-2 rounded-md bg-surface-strong px-2.5 py-1.5">
             <svg width="13" height="13" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" class="text-muted-foreground"><circle cx="11" cy="11" r="8"/><line x1="21" y1="21" x2="16.65" y2="16.65"/></svg>
@@ -143,22 +313,51 @@ export function ConversationList(props: ConversationListProps) {
           </div>
         </div>
       </Show>
+      {/* Item mode: the consumer's own rows in a list region. The container's
+          filter/grouping/empty states do not apply — the consumer's loop owns
+          them (spec § 2a batteries boundary). */}
+      <Show when={itemMode()}>
+        <ScrollArea class="flex-1 px-2">
+          <div
+            role="list"
+            aria-label="Conversations"
+            part="items"
+            class="space-y-0.5 py-1"
+            onKeyDown={(e) => local.itemsKeyDown?.(e)}
+            onClick={(e) => local.itemsClick?.(e)}
+          >
+            {local.items}
+          </div>
+        </ScrollArea>
+      </Show>
       {/* list, or the empty state (replace) when there are no conversations. */}
       <Show
-        when={!isEmpty()}
+        when={!itemMode() && !isEmpty()}
         fallback={
-          <Show
-            when={local.empty}
-            fallback={
-              <div class="flex flex-1 flex-col items-center justify-center gap-1 p-6 text-center text-sm text-muted-foreground">
-                No conversations yet
-              </div>
-            }
-          >
-            {local.empty}
+          <Show when={!itemMode()}>
+            <Show
+              when={local.empty}
+              fallback={
+                <div class="flex flex-1 flex-col items-center justify-center gap-1 p-6 text-center text-sm text-muted-foreground">
+                  No conversations yet
+                </div>
+              }
+            >
+              {local.empty}
+            </Show>
           </Show>
         }
       >
+        {/* F-04, decide loudly: a query matching nothing renders a VISIBLE
+            no-match state, keyed off the FILTERED count — distinct from the
+            zero-conversations empty state above, which keys off the unfiltered
+            list (and still owns the `empty` override). */}
+        <Show when={filteredConversations().length === 0}>
+          <div class="flex flex-1 flex-col items-center justify-center gap-1 p-6 text-center text-sm text-muted-foreground">
+            No conversations match your search
+          </div>
+        </Show>
+        <Show when={filteredConversations().length > 0}>
         <ScrollArea class="flex-1 px-2">
           <For each={local.groups}>
             {(group) => {
@@ -183,6 +382,7 @@ export function ConversationList(props: ConversationListProps) {
             </Show>
           </Show>
         </ScrollArea>
+        </Show>
       </Show>
       {/* footer (inject): a row below the list (account / settings / …). */}
       <Show when={local.footer}>

package/src/components/embed.tsx

@@ -159,6 +159,10 @@ export function Embed(props: EmbedProps): JSX.Element {
               </button>
             }
           >
+            {/* `outline-none` is DELIBERATE here and must stay: a `tabindex="-1"`
+                wrapper focused programmatically after the user activates the
+                player, so keyboard context lands on the embed. Not a tab stop —
+                the iframe inside it takes focus from there. */}
             <div ref={(el) => (playerRegion = el)} tabindex="-1" class="absolute inset-0 outline-none">
               <iframe
                 src={(resolved() as { value: ResolvedEmbed }).value.embedUrl}

package/src/components/form.tsx

@@ -748,19 +748,7 @@ function FieldRow(props: FieldRowProps): JSX.Element {
       .filter(Boolean)
       .join(' ') || undefined;
 
-  const common = () => ({
-    id,
-    value: props.value(),
-    field: props.field,
-    disabled: props.disabled || props.field.readOnly === true,
-    placeholder: placeholder(),
-    required: props.required,
-    invalid: Boolean(props.error()),
-    describedBy: describedBy(),
-    label: label(),
-    onInput: props.onInput,
-    onBlur: props.onBlur,
-  });
+  const common = fieldCommon(props, id, placeholder, label, describedBy);
 
   // A nested fieldset / repeater / checkbox-group provide their own grouping
   // label, so the row's <label> is only rendered for simple single controls.
@@ -784,7 +772,7 @@ function FieldRow(props: FieldRowProps): JSX.Element {
         </p>
       </Show>
 
-      <WidgetSwitch widget={widget()} common={common()} fieldKey={props.fieldKey} />
+      <WidgetSwitch widget={widget()} common={common} fieldKey={props.fieldKey} />
 
       <Show when={props.error()}>
         <p id={errorId} role="alert" class="text-xs text-destructive dark:text-red-400">
@@ -795,6 +783,45 @@ function FieldRow(props: FieldRowProps): JSX.Element {
   );
 }
 
+/**
+ * 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 function fieldCommon(
+  props: FieldRowProps,
+  id: string,
+  placeholder: () => string | undefined,
+  label: () => string,
+  describedBy: () => string | undefined = () => undefined,
+): ReturnType<FieldRowCommon> {
+  return {
+    id,
+    get value() { return props.value(); },
+    get field() { return props.field; },
+    get disabled() { return props.disabled || props.field.readOnly === true; },
+    get placeholder() { return placeholder(); },
+    get required() { return props.required; },
+    get invalid() { return Boolean(props.error()); },
+    get describedBy() { return describedBy(); },
+    get label() { return label(); },
+    onInput: (v) => props.onInput(v),
+    onBlur: () => props.onBlur(),
+  };
+}
+
 interface WidgetSwitchProps {
   widget: WidgetKind;
   fieldKey: string;

package/src/components/message.tsx

@@ -9,7 +9,17 @@ import type { ChatMessageAction, CustomAction, FeedbackVote, MessagePart, Messag
 import { useChatConfig, textClass } from "../primitives/chat-config";
 import { Reasoning, ReasoningTrigger, ReasoningContent } from "./reasoning";
 import { Tool } from "./tool";
-import { Attachments, Attachment, AttachmentPreview, AttachmentInfo } from "./attachments";
+import {
+  Attachments,
+  Attachment,
+  AttachmentPreview,
+  AttachmentInfo,
+  AttachmentHoverCard,
+  AttachmentHoverCardTrigger,
+  AttachmentHoverCardContent,
+  getAttachmentLabel,
+  getMediaCategory,
+} from "./attachments";
 import { Source, SourceTrigger, SourceContent, SourceList } from "./source";
 import { CardRenderer, type CardSchemaMap } from "./card-renderer";
 import type { CardComponentMap } from "../primitives/card-registry";
@@ -336,6 +346,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" />`. */
@@ -477,15 +494,68 @@ function MessageBody(props: MessageBodyProps) {
           <Switch fallback={null}>
             <Match when={groupAs(group(), 'files')}>
               {(g) => (
-                <Attachments variant="inline" class={props.isUser ? 'mb-2 justify-end' : 'mb-2'}>
+                /* `grid`, NOT `inline`. The inline chip gives an image a 20x20
+                   preview — a thumbnail nobody can read — while the 96px tile
+                   and the hover-card full preview both already existed here and
+                   the thread used neither.
+
+                   WHY GRID AND NOT LIST, since `list` shows the filename
+                   outright: `list` stacks (`flex-col`), so a message carrying
+                   four attachments becomes four full-width rows and pushes the
+                   conversation off screen. `grid` is `flex-wrap w-fit`, so the
+                   same four are one 96px-tall row of tiles. Density is what
+                   keeps a thread readable, and it is the whole reason the
+                   thread is not the composer's chip strip.
+
+                   A grid tile draws no filename of its own, and hiding one
+                   behind the hover card is not good enough: that serves a
+                   pointer and nothing else. So `<AttachmentInfo>` renders a
+                   VISIBLE truncated caption on every non-image tile — no hover,
+                   no focus, no tap required — and the hover card is an upgrade
+                   to the full name and media type rather than the only way to
+                   get either. */
+                <Attachments variant="grid" class={props.isUser ? 'mb-2 ml-auto' : 'mb-2'}>
                   {/* Reference-keyed <For> is right HERE: the run's part objects
                       are carried over untouched by the folds, and an attachment
                       holds no state worth preserving. */}
                   <For each={g().parts}>
                     {(fp) => (
                       <Attachment data={fp.attachment}>
-                        <AttachmentPreview />
-                        <AttachmentInfo />
+                        <AttachmentHoverCard>
+                          <AttachmentHoverCardTrigger class="block size-full">
+                            <AttachmentPreview />
+                            <AttachmentInfo />
+                          </AttachmentHoverCardTrigger>
+                          <AttachmentHoverCardContent>
+                            {/* An image gets the full preview; everything else
+                                gets the name and type the tile could not fit. */}
+                            <Show
+                              when={
+                                getMediaCategory(fp.attachment) === 'image' &&
+                                fp.attachment.type === 'file' &&
+                                fp.attachment.url
+                              }
+                              fallback={
+                                <>
+                                  <div class="text-body font-medium">
+                                    {getAttachmentLabel(fp.attachment)}
+                                  </div>
+                                  <Show when={fp.attachment.mediaType}>
+                                    <div class="text-muted-foreground text-caption">
+                                      {fp.attachment.mediaType}
+                                    </div>
+                                  </Show>
+                                </>
+                              }
+                            >
+                              <img
+                                alt={getAttachmentLabel(fp.attachment)}
+                                class="block max-h-64 max-w-xs rounded object-contain"
+                                src={fp.attachment.url}
+                              />
+                            </Show>
+                          </AttachmentHoverCardContent>
+                        </AttachmentHoverCard>
                       </Attachment>
                     )}
                   </For>
@@ -553,7 +623,7 @@ function MessageBody(props: MessageBodyProps) {
                     <Match when={carrierOnly()}>{null}</Match>
                     <Match when={shownReasoning()}>
                       {(p) => (
-                        <Reasoning class="mb-2 w-full">
+                        <Reasoning class="mb-2 w-full" isStreaming={props.isStreaming}>
                           <ReasoningTrigger>{p().label ?? 'Reasoning'}</ReasoningTrigger>
                           <ReasoningContent markdown>{p().text}</ReasoningContent>
                         </Reasoning>

package/src/components/response-stream.tsx

@@ -1,6 +1,7 @@
 import { splitProps, Show, For, createEffect, on } from 'solid-js';
+import { Dynamic } from 'solid-js/web';
 import { cn } from '../utils/cn';
-import { useTextStream } from '../primitives/use-text-stream';
+import { useTextStream, defaultFadeDuration, defaultSegmentDelay } from '../primitives/use-text-stream';
 
 export type Mode = 'typewriter' | 'fade';
 
@@ -30,6 +31,7 @@ function ResponseStream(props: ResponseStreamProps) {
     speed: speed(),
     characterChunkSize: local.characterChunkSize,
     fadeDuration: local.fadeDuration,
+    segmentDelay: local.segmentDelay,
   });
 
   createEffect(on(
@@ -39,15 +41,20 @@ function ResponseStream(props: ResponseStreamProps) {
     }
   ));
 
+  // Deferred: `isComplete` INITIALISES true (nothing has streamed yet), so an
+  // undeferred first run would announce completion at mount — the same
+  // no-event-on-mount contract kai-tool pins for kai-open-change. Only the
+  // false -> true transition of a real stream may call onComplete.
   createEffect(on(
     () => stream.isComplete(),
     (complete) => {
       if (complete) local.onComplete?.();
-    }
+    },
+    { defer: true }
   ));
 
   const fadeStyle = () => {
-    const dur = local.fadeDuration ?? Math.round(1000 / Math.sqrt(Math.min(100, Math.max(1, speed()))));
+    const dur = local.fadeDuration ?? defaultFadeDuration(speed());
     return `
       @keyframes fadeIn {
         from { opacity: 0; }
@@ -66,12 +73,11 @@ function ResponseStream(props: ResponseStreamProps) {
 
   const segDelay = () => {
     if (typeof local.segmentDelay === 'number') return Math.max(0, local.segmentDelay);
-    const normalizedSpeed = Math.min(100, Math.max(1, speed()));
-    return Math.max(1, Math.round(100 / Math.sqrt(normalizedSpeed)));
+    return defaultSegmentDelay(speed());
   };
 
   return (
-    <div class={local.class}>
+    <Dynamic component={local.as ?? 'div'} class={local.class}>
       <Show
         when={mode() === 'fade'}
         fallback={<>{stream.displayedText()}</>}
@@ -96,7 +102,7 @@ function ResponseStream(props: ResponseStreamProps) {
           </For>
         </div>
       </Show>
-    </div>
+    </Dynamic>
   );
 }
 

package/src/components/screen.tsx

@@ -144,6 +144,11 @@ export function Screen(props: ScreenProps) {
         data-expanded={presence.state() === 'open' ? '' : undefined}
         data-closed={presence.state() === 'closed' ? '' : undefined}
         onKeyDown={onKeyDown}
+        // `outline-none` is DELIBERATE here and must stay: this is the
+        // `tabindex="-1"` screen container, focused programmatically on open so
+        // keyboard and screen-reader context follows the screen. It is not a
+        // tab stop, so a ring around the whole surface would be noise. Its
+        // interactive children carry their own.
         class={cn(
           'absolute inset-0 z-40 flex flex-col bg-background text-foreground outline-none',
           'animate-in fade-in-0 slide-in-from-bottom-2 motion-reduce:animate-none',

package/src/components/scroll-button.tsx

@@ -17,6 +17,13 @@ function ScrollButton(props: ScrollButtonProps) {
       variant={props.variant ?? 'outline'}
       size={props.size ?? 'sm'}
       aria-label="Scroll to bottom"
+      // At the bottom of the thread this button is fully transparent and
+      // pointer-inert, but it stayed in the tab order — a keyboard user landed
+      // on a control they could not see, with a focus ring painted on nothing.
+      // Take it out of the tab order and hide it from assistive tech while it
+      // is invisible; both revert the moment it animates back in.
+      tabindex={isAtBottom() ? -1 : 0}
+      aria-hidden={isAtBottom() ? 'true' : undefined}
       class={cn(
         'h-10 w-10 rounded-full transition-all duration-150 ease-out',
         !isAtBottom()

package/src/components/toast.tsx

@@ -320,11 +320,17 @@ function anchorStyle(position: ToastPosition, r: TargetRect): Record<string, str
   }
 }
 
+/** The overlay layer both region roots sit on (F-20). One token, one default:
+ *  your app chrome must stay below the toast layer; set `--kai-toast-z`
+ *  (default 100) on the host to move the layer. */
+const TOAST_Z = 'var(--kai-toast-z, 100)';
+
 /**
  * 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 function ToastRegion(props: ToastRegionProps) {
   const max = () => props.max ?? 3;
@@ -425,12 +431,12 @@ export function ToastRegion(props: ToastRegionProps) {
           aria-live="polite"
           data-stack="expanded"
           class={cn(
-            'pointer-events-none fixed z-[100] flex flex-col gap-2',
+            'pointer-events-none fixed flex flex-col gap-2',
             anchor()
               ? ANCHOR_FLEX[position()]
               : cn('max-w-[min(30rem,calc(100vw-2rem))]', POSITION_CLASSES[position()]),
           )}
-          style={anchor() ? anchorStyle(position(), anchor()!) : undefined}
+          style={{ 'z-index': TOAST_Z, ...(anchor() ? anchorStyle(position(), anchor()!) : undefined) }}
         >
           <For each={visible()}>
             {(item) => (
@@ -456,8 +462,8 @@ export function ToastRegion(props: ToastRegionProps) {
         onPointerLeave={() => setHovered(false)}
         onFocusIn={() => setFocused(true)}
         onFocusOut={() => setFocused(false)}
-        class={cn('pointer-events-none fixed z-[100]', !anchor() && POSITION_CLASSES[position()])}
-        style={anchor() ? anchorStyle(position(), anchor()!) : undefined}
+        class={cn('pointer-events-none fixed', !anchor() && POSITION_CLASSES[position()])}
+        style={{ 'z-index': TOAST_Z, ...(anchor() ? anchorStyle(position(), anchor()!) : undefined) }}
       >
         {/* Relative stage with an explicit height so it's ONE continuous hover
             surface (pointer-events-auto) — no flicker when the cursor crosses gaps

package/src/components/voice-input.tsx

@@ -38,6 +38,10 @@ 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 function VoiceInput(props: VoiceInputProps) {
@@ -59,15 +63,43 @@ export function VoiceInput(props: VoiceInputProps) {
 
   // Native path: SpeechRecognition resolves with the final transcript when it
   // ends (click again or controller.stop()). Final text → onTranscription.
+  // Every other outcome reaches onError, so a session can never end in silence
+  // (W4 symptom 1: runtime errors set a signal nothing read, and an empty
+  // result fired no event at all).
   async function beginRecognition() {
+    let errored = false;
     try {
       const text = await speech.start({
         lang: props.lang,
         onInterim: props.interim ? (t) => props.onInterim?.(t) : undefined,
+        onError: (error, message) => {
+          errored = true;
+          props.onError?.({ source: 'recognition', error, message });
+        },
       });
-      if (text.trim()) local.onTranscription(text.trim());
-    } catch {
-      /* surfaced via speech.error; the mic returns to idle */
+      if (text.trim()) {
+        local.onTranscription(text.trim());
+      } else if (!errored) {
+        // No error, no text: the session ended cleanly having heard nothing.
+        // Reported through the SAME error event (as `no-result`) rather than an
+        // empty kai-transcription, so kai-transcription keeps its contract
+        // (final text exists) and one listener covers every failed session; the
+        // code distinguishes "user said nothing" from "recognition broke".
+        props.onError?.({
+          source: 'recognition',
+          error: 'no-result',
+          message: 'Speech recognition ended without capturing any text',
+        });
+      }
+    } catch (err) {
+      // start() itself threw (unsupported, or the platform refused to start).
+      if (!errored) {
+        props.onError?.({
+          source: 'recognition',
+          error: err instanceof Error ? err.name : 'unknown',
+          message: err instanceof Error ? err.message : String(err),
+        });
+      }
     }
   }