@kitn.ai/ui 0.26.0 → 0.28.0

package/src/components/message.tsx

@@ -8,6 +8,7 @@ import { actionIcon, BUILTIN_ACTION_LABEL } from "../ui/action-icons";
 import type { ChatMessageAction, CustomAction, FeedbackVote, MessagePart, MessageSource } from "../elements/chat-types";
 import { useChatConfig, textClass } from "../primitives/chat-config";
 import { Reasoning, ReasoningTrigger, ReasoningContent } from "./reasoning";
+import { Loader } from "./loader";
 import { Tool } from "./tool";
 import {
   Attachments,
@@ -328,6 +329,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;
@@ -348,11 +355,27 @@ export interface MessageBodyProps {
   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
+   *  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" />`. */
@@ -613,7 +636,17 @@ function MessageBody(props: MessageBodyProps) {
                           part="bubble content"
                           markdown={props.markdown}
                           class={props.isUser
-                            ? 'bg-muted text-primary max-w-[85%] rounded-2xl px-4 py-2'
+                            // Content token, not the brand token: `--color-primary`
+                            // is the documented consumer brand override
+                            // (theme.css `--kai-color-primary`), so toking message
+                            // TEXT to it means every consumer that brands primary
+                            // gets brand-colored message text. `text-foreground` is
+                            // already `MessageContent`'s base color (matches the
+                            // assistant path's `bg-transparent p-0`, which carries
+                            // no color override and falls through to the same
+                            // base) — dropping `text-primary` here just lets that
+                            // base apply on the user bubble too.
+                            ? 'bg-muted max-w-[85%] rounded-2xl px-4 py-2'
                             : 'bg-transparent p-0'}
                         >
                           {p().text}
@@ -622,18 +655,45 @@ function MessageBody(props: MessageBodyProps) {
                     </Match>
                     <Match when={carrierOnly()}>{null}</Match>
                     <Match when={shownReasoning()}>
-                      {(p) => (
-                        <Reasoning class="mb-2 w-full" isStreaming={props.isStreaming}>
-                          <ReasoningTrigger>{p().label ?? 'Reasoning'}</ReasoningTrigger>
-                          <ReasoningContent markdown>{p().text}</ReasoningContent>
-                        </Reasoning>
-                      )}
+                      {(p) => {
+                        // Default 'full' is the pre-existing DISPLAY MODE byte
+                        // for byte; the OPEN behavior changed under Task 19f —
+                        // it no longer auto-opens while streaming by default
+                        // (owner ruling 2026-08-26). `reasoningDefaultOpen`
+                        // reproduces the old always-auto-opens behavior when set.
+                        const mode = () => props.reasoningMode ?? 'full';
+                        return (
+                          <Switch fallback={null}>
+                            <Match when={mode() === 'full'}>
+                              <Reasoning
+                                class="mb-2 w-full"
+                                isStreaming={props.isStreaming}
+                                defaultOpen={props.reasoningDefaultOpen}
+                                openOnStream={props.reasoningDefaultOpen}
+                              >
+                                <ReasoningTrigger>{p().label ?? 'Reasoning'}</ReasoningTrigger>
+                                <ReasoningContent markdown>{p().text}</ReasoningContent>
+                              </Reasoning>
+                            </Match>
+                            {/* 'compact': the same "Thinking…" shimmer the full
+                                disclosure's trigger shows while streaming — no
+                                <Reasoning>/<ReasoningContent>, so there is no
+                                expandable detail and nothing left once the part
+                                settles (isStreaming false → this Match doesn't
+                                fire, matching 'off'). 'off' never reaches here:
+                                its Match doesn't fire either. */}
+                            <Match when={mode() === 'compact' && props.isStreaming}>
+                              <Loader variant="text-shimmer" text={p().label ?? 'Reasoning'} class="mb-2" />
+                            </Match>
+                          </Switch>
+                        );
+                      }}
                     </Match>
                     <Match when={partAs(part(), 'tool')}>
                       {(p) => <Tool toolPart={p().tool} class="mb-2 w-full" />}
                     </Match>
                     <Match when={partAs(part(), 'card')}>
-                      {(p) => <CardRenderer envelope={p().envelope} types={props.cardTypes} schemas={props.cardSchemas} />}
+                      {(p) => <CardRenderer envelope={p().envelope} types={props.cardTypes} schemas={props.cardSchemas} hostElement={props.cardHostElement} />}
                     </Match>
                     {/* No `source` match here on purpose: source parts never
                         reach a 'single' group — they are collapsed into a

package/src/components/prompt-input.tsx

@@ -115,9 +115,15 @@ function PromptInputTextarea(props: PromptInputTextareaProps) {
   // the contenteditable composer is visually identical. The frame (PromptInput
   // root) still owns radius/bg/padding/focus-ring; auto-grow is native to a
   // contenteditable block (capped via max-height on the editable).
+  // `text-start` is a PIN, not a style choice: `text-align` inherits, so any
+  // centered ancestor (`Empty`'s root did exactly this) reached in and centered
+  // the placeholder AND the typed text. An input control's text alignment is a
+  // fact about the control, so it states it rather than inheriting it. LOGICAL
+  // (`start`), not `text-left` — in RTL the correct edge is the right one, and
+  // pinning the physical value would be a worse bug than the one it fixes.
   const editableClass = () =>
     cn(
-      'text-foreground min-h-[44px] w-full bg-transparent shadow-none outline-none focus-visible:ring-0 focus-visible:ring-offset-0 overflow-y-auto whitespace-pre-wrap break-words',
+      'text-foreground min-h-[44px] w-full bg-transparent text-start shadow-none outline-none focus-visible:ring-0 focus-visible:ring-offset-0 overflow-y-auto whitespace-pre-wrap break-words',
       textClass(config.proseSize()),
       local.class,
     );

package/src/components/prompt-suggestion.tsx

@@ -136,7 +136,10 @@ function renderHighlighted(text: string, highlight: string) {
       <Show when={before}>
         <span class="text-foreground/70 whitespace-pre-wrap">{before}</span>
       </Show>
-      <span class="text-primary font-medium whitespace-pre-wrap">{matched}</span>
+      {/* Matched-substring highlight is CONTENT, not a control — was the BRAND
+          token. Full-strength `text-foreground` against the `/70`-opacity
+          siblings above/below is what actually carries the highlight. */}
+      <span class="text-foreground font-medium whitespace-pre-wrap">{matched}</span>
       <Show when={after}>
         <span class="text-foreground/70 whitespace-pre-wrap">{after}</span>
       </Show>

package/src/components/reasoning.tsx

@@ -3,6 +3,7 @@ import { cn } from '../utils/cn';
 import { ChevronDown } from 'lucide-solid';
 import { Markdown } from './markdown';
 import { observeContentHeight } from '../primitives/use-resize-observer';
+import { TextShimmer } from './text-shimmer';
 
 interface ReasoningContextValue {
   isOpen: () => boolean;
@@ -18,6 +19,11 @@ interface ReasoningContextValue {
   /** The registered trigger. Deliberately a plain getter over a mutable
    *  variable, NOT a signal — registration must not re-run the content effect. */
   trigger: () => HTMLElement | undefined;
+  /** Whether the reasoning is currently streaming — read by `ReasoningTrigger`
+   *  to decide how its own label renders (shimmer while streaming, plain
+   *  neutral text once settled). Kit-decides-HOW: every consumer gets the same
+   *  "Thinking…" shimmer behavior for free, with no prop of their own. */
+  isStreaming: () => boolean;
 }
 
 /** Imperative open controller, handed to a parent (the kai-reasoning facade) via
@@ -49,10 +55,16 @@ 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;
 }
 
 function Reasoning(props: ReasoningProps) {
-  const [local] = splitProps(props, ['children', 'class', 'open', 'defaultOpen', 'onOpenChange', 'isStreaming', 'disabled', 'controllerRef']);
+  const [local] = splitProps(props, ['children', 'class', 'open', 'defaultOpen', 'onOpenChange', 'isStreaming', 'disabled', 'controllerRef', 'openOnStream']);
   const [internalOpen, setInternalOpen] = createSignal(local.defaultOpen ?? false);
   const [wasAutoOpened, setWasAutoOpened] = createSignal(false);
 
@@ -72,6 +84,7 @@ function Reasoning(props: ReasoningProps) {
   };
 
   createEffect(() => {
+    if (!local.openOnStream) return;
     const streaming = local.isStreaming;
     if (streaming && !wasAutoOpened()) {
       if (!isControlled()) setInternalOpen(true);
@@ -104,6 +117,7 @@ function Reasoning(props: ReasoningProps) {
         contentId,
         registerTrigger: (el) => { triggerEl = el; },
         trigger: () => triggerEl,
+        isStreaming: () => !!local.isStreaming,
       }}
     >
       <div class={local.class}>{local.children}</div>
@@ -122,7 +136,7 @@ function ReasoningTrigger(props: ReasoningTriggerProps) {
   // to register as the panel's focus-return target, and a spread `ref` would
   // silently replace it. The consumer's ref is forwarded below instead.
   const [local, rest] = splitProps(props, ['children', 'class', 'ref']);
-  const { isOpen, onOpenChange, disabled, contentId, registerTrigger } = useReasoningContext();
+  const { isOpen, onOpenChange, disabled, contentId, registerTrigger, isStreaming } = useReasoningContext();
 
   return (
     // The same disclosure contract as CollapsibleTrigger: an explicit
@@ -149,7 +163,20 @@ function ReasoningTrigger(props: ReasoningTriggerProps) {
       onClick={() => { if (!disabled()) onOpenChange(!isOpen()); }}
       {...rest}
     >
-      <span class="text-primary">{local.children}</span>
+      {/* Content/chrome, not a control: was `text-primary`, the BRAND token, so
+          a consumer's branded --kai-color-primary bled onto the "Thinking"
+          label. `text-foreground` matches the sibling `<Tool>` disclosure
+          trigger's label (rendered via `Button variant="ghost"`, itself
+          `text-foreground`) — the established neutral for a disclosure
+          trigger's own label text in this codebase.
+          Kit-decides-HOW: while streaming, the label renders with the kit's
+          own `TextShimmer` (the common "Thinking…" shimmer, already used by
+          `Loader`'s `text-shimmer` variant) instead of static text; once
+          settled it's the plain neutral span above. Every consumer gets this
+          for free — no prop of their own. */}
+      <Show when={isStreaming()} fallback={<span class="text-foreground">{local.children}</span>}>
+        <TextShimmer class="font-medium">{local.children}</TextShimmer>
+      </Show>
       <div
         class={cn(
           'transform transition-transform',

package/src/components/response-compare.tsx

@@ -365,7 +365,7 @@ function CompareColumn(props: ColumnProps): JSX.Element {
   return (
     <div
       class={cn(
-        'flex min-w-0 flex-col gap-3 rounded-lg border border-input bg-background/40 p-3',
+        'flex min-w-0 flex-col gap-3 rounded-lg border border-border bg-background/40 p-3',
         props.hiddenClass?.(),
       )}
     >
@@ -432,7 +432,7 @@ function CollapsedWinner(props: {
 }): JSX.Element {
   return (
     <div
-      class="flex flex-col gap-2 rounded-lg border border-input bg-accent/40 p-3"
+      class="flex flex-col gap-2 rounded-lg border border-border bg-accent/40 p-3"
       role={props.optimistic ? 'status' : undefined}
     >
       <div class="flex items-center gap-2 text-sm font-medium text-accent-foreground">

package/src/components/scroll-button.tsx

@@ -1,22 +1,62 @@
+import { Show } from 'solid-js';
 import { cn } from '../utils/cn';
 import { Button } from '../ui/button';
 import { useChatContainer } from './chat-container';
-import { ChevronDown } from 'lucide-solid';
+import { ArrowDown } from 'lucide-solid';
+
+/** The accessible name used when the consumer does not supply one. */
+const DEFAULT_LABEL = 'Scroll to bottom';
 
 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;
+}
+
+/**
+ * The floating chip surface.
+ *
+ * The shared `outline` button variant is `bg-muted/50` — half-transparent, so
+ * message text showed through a control that floats over scrolling content, and
+ * its edge measured 1.05:1 against the thread behind it (SC 1.4.11 wants 3:1).
+ * `bg-card` is the same opaque surface popovers, dropdowns and hover cards sit
+ * on; `border-input` is the kit's control edge and clears 3:1 in both themes;
+ * `kai-elevation` is the shared, themeable float shadow (`--kai-shadow-color`),
+ * which is what keeps an opaque button reading as ABOVE the content.
+ *
+ * `ghost` and `default` are explicit consumer choices about the fill, so they
+ * keep theirs; every variant gets the elevation and the rounded-square radius.
+ */
+function surfaceClasses(variant: ScrollButtonProps['variant']) {
+  return (variant ?? 'outline') === 'outline'
+    ? 'border border-input bg-card text-card-foreground kai-elevation'
+    : 'kai-elevation';
 }
 
 function ScrollButton(props: ScrollButtonProps) {
   const { isAtBottom, scrollToBottom } = useChatContainer();
+  const label = () => props.label ?? DEFAULT_LABEL;
+  const showLabel = () => props.showLabel === true;
 
   return (
     <Button
       variant={props.variant ?? 'outline'}
       size={props.size ?? 'sm'}
-      aria-label="Scroll to bottom"
+      // When the label is visible it IS the accessible name. An aria-label on
+      // top of it would override the visible text and leave the two able to
+      // disagree, so it is only set for the icon-only case.
+      aria-label={showLabel() ? undefined : label()}
       // 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.
@@ -25,7 +65,10 @@ function ScrollButton(props: ScrollButtonProps) {
       tabindex={isAtBottom() ? -1 : 0}
       aria-hidden={isAtBottom() ? 'true' : undefined}
       class={cn(
-        'h-10 w-10 rounded-full transition-all duration-150 ease-out',
+        'rounded-lg transition-all duration-150 ease-out',
+        surfaceClasses(props.variant),
+        // Square while icon-only; a pill-ish labelled button once the text is in.
+        showLabel() ? 'h-10 w-auto gap-1.5 px-3.5 text-sm' : 'h-10 w-10 px-0',
         !isAtBottom()
           ? 'translate-y-0 scale-100 opacity-100'
           : 'pointer-events-none translate-y-4 scale-95 opacity-0',
@@ -33,7 +76,16 @@ function ScrollButton(props: ScrollButtonProps) {
       )}
       onClick={() => scrollToBottom()}
     >
-      <ChevronDown class="h-5 w-5" />
+      {/* h-4, not the h-5 the chevron used. A ChevronDown only inks the lower
+          part of its 24px viewBox, so at a 20px box its visible mass is small;
+          ArrowDown inks the full height (stem + head), and at 20px inside a 40px
+          button it read as half the button wide and crowded the padding. 16px
+          balances the icon-only square and is the size lucide pairs with
+          text-sm, which is what the label renders at. */}
+      <ArrowDown class="h-4 w-4 shrink-0" aria-hidden="true" />
+      <Show when={showLabel()}>
+        <span>{label()}</span>
+      </Show>
     </Button>
   );
 }

package/src/components/source.tsx

@@ -152,7 +152,12 @@ function SourceContent(props: SourceContentProps) {
               width={16}
               height={16}
             />
-            <div class="text-primary truncate text-sm">
+            {/* Citation title/domain is CONTENT, not a control — was the BRAND
+                token. `text-foreground/80` matches how `SourceTrigger` above
+                already renders this same domain text (inherited from its `<a
+                class="... text-foreground/80 ...">`), so the hover-card header
+                and the trigger chip agree on the same domain's color. */}
+            <div class="text-foreground/80 truncate text-sm">
               {ctx.domain.replace('www.', '')}
             </div>
           </div>

package/src/components/tasks-card.tsx

@@ -14,6 +14,7 @@ import {
 } from 'solid-js';
 import { cn } from '../utils/cn';
 import { Button } from '../ui/button';
+import { Checkbox } from '../ui/checkbox';
 import { ProgressBar } from '../ui/progress-bar';
 import { Card } from './card';
 import { DismissedStub } from './dismissed-stub';
@@ -21,7 +22,7 @@ import type { CardEnvelope, CardEvent, CardHost, CardResolution } from '../primi
 import { useCardResolution } from './use-card-resolution';
 import { emitCardEvent } from '../primitives/card-routing';
 import { useCardHost } from '../primitives/card-host';
-import { Check, Circle, CircleCheck, X } from 'lucide-solid';
+import { Check, Circle, CircleCheck } from 'lucide-solid';
 
 // ─────────────────────────────────────────────────────────────────────────────
 // Types (tasks.schema.json) — AUTHORED IN ../primitives/card-data-types.ts.
@@ -415,14 +416,23 @@ export function TasksCard(props: TasksCardProps): JSX.Element {
             progress() || res.isResolved() || readOnly() ? undefined : (
               <div class="flex w-full flex-wrap items-center justify-between gap-2">
                 <Show when={local.data?.dismissible === true}>
+                  {/* The contract `dismiss` verb — a footer ACTION (it emits
+                      `{kind:'dismiss'}` and collapses the card to a re-openable
+                      stub), not the chrome close in `Card`'s own `dismissible`
+                      prop, which the contract cards deliberately never set.
+                      Labelled rather than a bare ghost ✕: every other control in
+                      this row says what it does, and an unlabelled 28px glyph
+                      300px from the primary button reads as stray chrome. Same
+                      shape in all four cards — `form` already looked like this.
+                      `aria-label` is kept (redundant with the text) so the
+                      element tests that select on it keep working. */}
                   <Button
                     type="button"
                     variant="ghost"
-                    size="icon-sm"
                     aria-label="Dismiss"
                     onClick={onDismiss}
                   >
-                    <X size={16} aria-hidden="true" />
+                    Dismiss
                   </Button>
                 </Show>
                 <span id={countId} aria-live="polite" class="text-xs text-muted-foreground">
@@ -485,7 +495,7 @@ export function TasksCard(props: TasksCardProps): JSX.Element {
                 if (confirmEnabled()) onConfirm();
               }}
             >
-              <div class="divide-y divide-border overflow-hidden rounded-lg border border-input">
+              <div class="divide-y divide-border overflow-hidden rounded-lg border border-border">
                 <Show when={showMaster()}>
                   {(() => {
                     const indeterminate = () => masterState() === 'indeterminate';
@@ -501,17 +511,20 @@ export function TasksCard(props: TasksCardProps): JSX.Element {
                               : 'text-foreground hover:bg-muted/50',
                         )}
                       >
-                        <input
-                          type="checkbox"
-                          class="kai-checkbox"
+                        {/* SQUARE `Checkbox` (the `.kai-checkbox` look), and the checklist below draws a
+                            ROUND lucide Circle/CircleCheck instead. Deliberate, not drift: this
+                            is `select` mode — a pick-list whose rows are a pending selection that
+                            only commits when the confirm button fires, which is what a checkbox
+                            means everywhere else. `progress` mode has no confirm and toggling a
+                            row IS the action, so it uses the done/not-done affordance of a todo
+                            list. See the D-2 row in
+                            docs/superpowers/plans/2026-08-25-form-control-primitives.md; owner has
+                            not ruled, so do not converge these on your own. */}
+                        <Checkbox
                           checked={masterState() === 'checked'}
                           disabled={groupDisabled() || readOnly()}
+                          indeterminate={indeterminate()}
                           aria-checked={indeterminate() ? 'mixed' : masterState() === 'checked'}
-                          ref={(el) => {
-                            createEffect(() => {
-                              el.indeterminate = indeterminate();
-                            });
-                          }}
                           onChange={(e) => toggleAll(e.currentTarget.checked)}
                         />
                         <span>Select all</span>
@@ -541,9 +554,8 @@ export function TasksCard(props: TasksCardProps): JSX.Element {
                         )}
                         data-task-id={task.id}
                       >
-                        <input
-                          type="checkbox"
-                          class="kai-checkbox mt-0.5"
+                        <Checkbox
+                          class="mt-0.5"
                           checked={checked()}
                           disabled={blocked() || readOnly()}
                           aria-disabled={blocked() ? 'true' : undefined}
@@ -603,7 +615,10 @@ function ProgressChecklist(props: {
     <div class={cn('flex flex-col gap-3', props.groupClass)}>
       <Show when={props.heading}>
         <div class="flex items-center justify-between gap-3">
-          <span id={props.headingId} class="text-sm font-medium text-foreground">
+          <span
+            id={props.headingId}
+            class="text-title font-semibold tracking-tight text-foreground"
+          >
             {props.heading}
           </span>
           <span
@@ -646,8 +661,23 @@ function ProgressChecklist(props: {
                     // row doesn't leave a noisy persistent outline — and it makes a
                     // Tab-focused completed row's open description perceivable. Dropped
                     // entirely when readonly (the row isn't focusable then).
+                    //
+                    // TWO tab stops exist per row and the ring has to cover both.
+                    // `focus-visible:` matches only when the LABEL itself is focused,
+                    // which is completed rows only (the `tabindex` below). Every row's
+                    // other — and for an incomplete row, only — tab stop is the sr-only
+                    // checkbox inside, so without `has-[:focus-visible]:` tabbing to an
+                    // unchecked row put focus on an off-screen input with no indicator
+                    // anywhere on screen. Both halves stay on the focus-VISIBLE axis on
+                    // purpose: `focus-within:` would also fire for a mouse click (which
+                    // forwards focus from the label to the checkbox), which is exactly
+                    // the persistent-outline noise the paragraph above rejects. The
+                    // description reveal below uses `group-focus-within:` because a
+                    // hover-or-focus reveal wants the looser condition.
                     !props.readonly &&
                       'focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-inset focus-visible:ring-ring',
+                    !props.readonly &&
+                      'has-[:focus-visible]:outline-none has-[:focus-visible]:ring-2 has-[:focus-visible]:ring-inset has-[:focus-visible]:ring-ring',
                     props.readonly
                       ? 'cursor-default'
                       : blocked()
@@ -680,6 +710,18 @@ function ProgressChecklist(props: {
                     )}
                     aria-hidden="true"
                   >
+                    {/* ROUND, where `select` mode uses the square `Checkbox`. Deliberate:
+                        this mode has no confirm button, so ticking a row IS the action and the
+                        row is done-or-not rather than selected-or-not — the todo-list
+                        affordance, which is how this mode has been described since it landed
+                        (see the `mode` argType in tasks-card.stories.tsx and the JSDoc on
+                        src/elements/tasks.tsx). D-2 in
+                        docs/superpowers/plans/2026-08-25-form-control-primitives.md tracks
+                        whether to keep the split; unruled, so leave both. NOTE the cost: the
+                        icon replaces the visible native control, which is why the real input
+                        above is `sr-only` and why the row's focus ring has to be driven by
+                        `has-[:focus-visible]:`. Converging on `Checkbox` would take that
+                        hazard away with it. */}
                     <Show
                       when={checked()}
                       fallback={<Circle size={18} />}

package/src/components/thread.tsx

@@ -34,6 +34,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;
@@ -146,6 +151,7 @@ export function Thread(props: ThreadProps) {
                         parts={m().parts}
                         cardTypes={props.cardTypes}
                         cardSchemas={props.cardSchemas}
+                        cardHostElement={props.cardHostElement}
                         isUser={m().role === 'user'}
                         markdown={m().role === 'assistant'}
                         actions={m().actions}
@@ -209,7 +215,10 @@ export function Thread(props: ThreadProps) {
           </ChatContainerContent>
           <Show when={showScrollButton()}>
             <div class="absolute bottom-4 left-1/2 flex w-full max-w-3xl -translate-x-1/2 justify-center px-5">
-              <ScrollButton class="shadow-sm" />
+              {/* The button now owns its elevation (kai-elevation); a `shadow-sm`
+                  here would set box-shadow a second time and the winner would
+                  be stylesheet order, not this call site. */}
+              <ScrollButton />
             </div>
           </Show>
         </ChatContainer>

package/src/components/toast.tsx

@@ -320,7 +320,7 @@ function anchorStyle(position: ToastPosition, r: TargetRect): Record<string, str
   }
 }
 
-/** The overlay layer both region roots sit on (F-20). One token, one default:
+/** The overlay layer both region roots sit on. 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)';

package/src/components/tool-types.ts

@@ -25,6 +25,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/src/components/widget-tab-bar.tsx

@@ -0,0 +1,73 @@
+import { Show } from 'solid-js';
+import { cn } from '../utils/cn';
+import { renderIcon } from '../ui/icon';
+
+export interface WidgetTabBarProps {
+  active: 'home' | 'messages';
+  onChange: (tab: 'home' | 'messages') => void;
+  /** Whether the Messages tab has unread activity. Reaches BOTH the visible
+   *  dot and the tab's accessible name (`aria-label`) — a dot alone is
+   *  invisible to assistive tech, the #336 lesson this test pins. */
+  unread?: boolean;
+  homeLabel?: string;
+  messagesLabel?: string;
+}
+
+/**
+ * The widget's Home/Messages tab bar (Intercom-pattern chrome, H-2/H-6). Real
+ * `tablist`/`tab` semantics — this is a persistent view switch within the
+ * widget, not page navigation, so it is not `<Nav>`'s `role="page"` dialect.
+ */
+export function WidgetTabBar(props: WidgetTabBarProps) {
+  const home = () => props.homeLabel ?? 'Home';
+  const messages = () => props.messagesLabel ?? 'Messages';
+  const messagesLabel = () => (props.unread ? `${messages()} (unread)` : messages());
+
+  return (
+    <nav
+      role="tablist"
+      aria-label="Widget navigation"
+      class="flex h-14 shrink-0 items-stretch border-t border-border bg-background"
+    >
+      <button
+        type="button"
+        role="tab"
+        data-kai-tab-home
+        aria-selected={props.active === 'home'}
+        aria-label={home()}
+        onClick={() => props.onChange('home')}
+        class={cn(
+          'flex flex-1 flex-col items-center justify-center gap-0.5 text-xs transition-colors',
+          props.active === 'home' ? 'text-primary' : 'text-muted-foreground hover:text-foreground',
+        )}
+      >
+        {renderIcon('home', { class: 'size-5' })}
+        <span>{home()}</span>
+      </button>
+      <button
+        type="button"
+        role="tab"
+        data-kai-tab-messages
+        aria-selected={props.active === 'messages'}
+        aria-label={messagesLabel()}
+        onClick={() => props.onChange('messages')}
+        class={cn(
+          'flex flex-1 flex-col items-center justify-center gap-0.5 text-xs transition-colors',
+          props.active === 'messages' ? 'text-primary' : 'text-muted-foreground hover:text-foreground',
+        )}
+      >
+        <span class="relative">
+          {renderIcon('message-square', { class: 'size-5' })}
+          <Show when={props.unread}>
+            <span
+              data-kai-tab-unread
+              aria-hidden="true"
+              class="absolute -right-0.5 -top-0.5 size-1.5 rounded-full bg-unread"
+            />
+          </Show>
+        </span>
+        <span>{messages()}</span>
+      </button>
+    </nav>
+  );
+}