@kitn.ai/ui 0.25.2 → 0.27.0

package/src/components/composer.tsx

@@ -11,6 +11,7 @@ import {
   For,
 } from 'solid-js';
 import { cn } from '../utils/cn';
+import { useChatConfig, textClass } from '../primitives/chat-config';
 import {
   type ComposerDoc,
   type EntityRef,
@@ -242,6 +243,7 @@ function setCaretToOffset(root: HTMLElement, offset: number): void {
 }
 
 export function Composer(props: ComposerProps): JSX.Element {
+  const config = useChatConfig();
   let editable!: HTMLDivElement;
   // A SIGNAL (not a plain `let`): usePosition's floating ref must be reactive so
   // Floating UI recomputes once the menu mounts. A non-reactive ref left the menu
@@ -799,16 +801,78 @@ export function Composer(props: ComposerProps): JSX.Element {
   // This is covered by updateTriggerState() in handleInput.
 
   const maxH = () => props.maxHeight ?? 240;
+  // This element is `contenteditable` with `role="textbox"` — a real tab stop,
+  // and the primary one in the kit — so it must never be left with NO focus
+  // affordance. WHICH element draws it depends on who owns the frame:
+  //
+  //  - Standalone (the `else` branch below renders the rounded shell): the FRAME
+  //    owns the ring via `focus-within:ring-*`, exactly like `PromptInput`, so
+  //    the editable neutralizes its own. The editable is a square, full-bleed
+  //    box inside a `rounded-xl` shell, so an outline on IT painted a sharp
+  //    rectangle hugging the text region inside the rounded border — the bug.
+  //  - Bare: the host owns radius/bg/padding and may draw nothing at all
+  //    (`PromptInput` passes its own `editableClass` and rings its frame), so
+  //    the editable keeps `kai-focus-inset` — a ring inside the border box,
+  //    since an outset one would be clipped by a rounded host shell.
+  //
+  // A consumer passing `editableClass` still replaces this wholesale — including
+  // the `text-start` pin below, so a replacement string owes its own (`PromptInput`,
+  // the one in-repo caller, carries it).
   const editableCls = () =>
     props.editableClass ??
-    'text-foreground min-h-[44px] w-full overflow-y-auto outline-none whitespace-pre-wrap break-words';
+    cn(
+      // `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.
+      'text-foreground min-h-[44px] w-full text-start overflow-y-auto whitespace-pre-wrap break-words',
+      // Size from the SAME token every other text surface reads (`ChatConfig`'s
+      // proseSize, default `sm` = the 14px the rest of the kit sets explicitly) —
+      // `Markdown`, `MessageContent` and `PromptInputTextarea` all go through
+      // `textClass`. Without it the editable set no size at all and just inherited
+      // whatever the shadow root's base was (16px in a stock page), so the composer
+      // read a step larger than every component beside it. Going through the token
+      // also means `proseSize` moves the composer like it moves `PromptInput`,
+      // rather than leaving one input deaf to it.
+      textClass(config.proseSize()),
+      props.bare
+        ? 'kai-focus-inset'
+        : 'outline-none focus-visible:outline-none focus-visible:ring-0 focus-visible:ring-offset-0',
+    );
 
   const inner = (
     <>
       {/* Static style for CSS Custom Highlight API decoration.
           No-op in browsers that don't support ::highlight(); the selector
           is simply unrecognized and dropped. */}
-      <style>{`::highlight(${highlightName}) { background-color: color-mix(in srgb, var(--color-primary, #6366f1) 22%, transparent); }`}</style>
+      <style>{`
+        /* MARKED text, not selected text. Reads --color-highlight (overridable via
+           --kai-color-highlight), a warm <mark> yellow. It used to be a 22% tint of
+           --color-primary with a #6366f1 indigo fallback — but the kit's
+           --color-primary is a NEUTRAL (near-black in light, near-white in dark),
+           so the indigo the fallback implied never appeared and the highlight
+           rendered plain grey in both themes.
+
+           NO \`prefers-color-scheme\` here, deliberately — the same trap that put
+           the pill hues below at 2.33:1. The OS scheme and the kit's RESOLVED
+           theme are different questions, and \`theme="light"\` on a dark-OS machine
+           is an ordinary configuration; a scheme-keyed value would paint the dark
+           amber on the light field. The pills answer this by scoping to \`.dark\`,
+           which is NOT available here: \`::highlight()\` names a document-registered
+           highlight, so there is no wrapper to hang a descendant selector on.
+
+           It does not need one. \`--color-highlight\` reaches this pseudo through
+           highlight inheritance from the ORIGINATING element — the text inside the
+           \`.dark\` wrapper — so the token already answers the resolved theme,
+           verified by rendering the dark amber under \`theme="dark"\` with only the
+           LIGHT literal below as a fallback. The literal is therefore reachable
+           only when no kit stylesheet is loaded at all, and it is deliberately the
+           light one: an unstyled page is a white page, and guessing from the OS is
+           exactly the failure above. */
+        ::highlight(${highlightName}) { background-color: var(--color-highlight, hsl(45 96% 78%)); }
+      `}</style>
       {/* Atomic entity pill styling. Self-contained (currentColor-based) so it
           renders correctly without depending on a Tailwind rebuild for the
           custom .kai-composer-pill class. */}
@@ -839,12 +903,24 @@ export function Composer(props: ComposerProps): JSX.Element {
         .kai-composer-pill[data-kind="agent"] { color: var(--kai-pill-agent, #7c3aed); }
         /* Brighter hues on dark so they don't muddy against a dark field. The
            consumer's --kai-pill-* override still wins (it's the var value); only
-           the FALLBACK shifts per scheme. */
-        @media (prefers-color-scheme: dark) {
-          .kai-composer-pill[data-kind="skill"] { color: var(--kai-pill-skill, #6ea8fe); }
-          .kai-composer-pill[data-kind="agent"] { color: var(--kai-pill-agent, #c4a7fc); }
-        }
-        .kai-composer-pill-sigil { opacity: 0.6; font-weight: 600; }
+           the FALLBACK shifts per scheme.
+
+           Keyed on the kit's RESOLVED theme (the \`.dark\` wrapper an element
+           facade puts inside its shadow root, and the \`.dark\` class the docs /
+           Storybook put on <html>) — NOT \`prefers-color-scheme\`. Those are
+           different questions: \`theme="light"\` on a machine whose OS is dark is
+           an ordinary, common configuration, and the media query answered the OS
+           while the surface under the pill answered the attribute. That painted
+           the DARK hue (#6ea8fe) on the LIGHT field: 2.33:1, under both the
+           4.5:1 text floor (SC 1.4.3) and even 3:1. Matched pairs looked fine,
+           which is why it survived — never scheme-match a colour whose backdrop
+           is chosen by the theme attribute. */
+        .dark .kai-composer-pill[data-kind="skill"] { color: var(--kai-pill-skill, #6ea8fe); }
+        .dark .kai-composer-pill[data-kind="agent"] { color: var(--kai-pill-agent, #c4a7fc); }
+        /* Dimmer than the label, but the sigil is what makes a pill read as
+           \`/skill\` vs \`@agent\`, so it is a meaningful glyph and owes 3:1
+           (SC 1.4.11). At 0.6 the light-mode composite was 2.52:1. */
+        .kai-composer-pill-sigil { opacity: 0.8; font-weight: 600; }
         /* Plugins (and any other/unknown kind): the richer CHIP — background +
            icon — so a composite bundle reads differently at a glance. */
         .kai-composer-pill:not([data-kind="skill"]):not([data-kind="agent"]) {
@@ -984,7 +1060,12 @@ export function Composer(props: ComposerProps): JSX.Element {
   ) : (
     <div
       class={cn(
+        // Same frame-owns-the-ring pattern as `PromptInput`: the editable inside
+        // neutralizes its own outline (see `editableCls`), so this rounded shell
+        // draws the focus affordance and the ring follows `rounded-xl` instead of
+        // painting a square box around the inner text region.
         'kai-composer relative rounded-xl bg-surface p-2',
+        'focus-within:ring-2 focus-within:ring-ring focus-within:ring-offset-0',
         props.disabled && 'cursor-not-allowed opacity-60',
       )}
     >

package/src/components/confirm-card.tsx

@@ -18,7 +18,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 { AlertTriangle, Check, X } from 'lucide-solid';
+import { AlertTriangle, Check } from 'lucide-solid';
 
 // ─────────────────────────────────────────────────────────────────────────────
 // Types (confirm.schema.json) — AUTHORED IN ../primitives/card-data-types.ts.
@@ -316,14 +316,23 @@ export function ConfirmCard(props: ConfirmCardProps): JSX.Element {
             >
               <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>
                 <div ref={actionsRef} class="ml-auto flex flex-wrap items-center gap-2">
@@ -375,7 +384,14 @@ export function ConfirmCard(props: ConfirmCardProps): JSX.Element {
               <p class="text-sm font-semibold text-foreground">{local.data?.heading}</p>
             </Show>
             <Show when={local.data?.body}>
-              <p class="text-sm text-foreground">{local.data?.body}</p>
+              {/* The supporting sentence sits directly under the heading it
+                  supports, muted — the same contrast step the shell header makes
+                  between `heading` and `description`. It stays in the BODY (not
+                  the shell's `description` slot, where `form`'s and `choice`'s
+                  live) because `data.heading` is a documented IN-BODY heading
+                  that this sentence has to stay beneath, and because this div is
+                  the Enter-to-confirm tab stop. */}
+              <p class="text-sm text-muted-foreground">{local.data?.body}</p>
             </Show>
           </div>
         </Card>

package/src/components/conversation-item.tsx

@@ -1,4 +1,4 @@
-import { Show, splitProps, createMemo } from 'solid-js';
+import { Show, splitProps, createMemo, type JSX } from 'solid-js';
 import { MessageSquare } from 'lucide-solid';
 import { cn } from '../utils/cn';
 import type { ConversationSummary } from '../types';
@@ -31,12 +31,146 @@ export function relativeTimeShort(iso?: string, now: number = Date.now()): strin
   return `${Math.floor(hours / 24)}d ago`;
 }
 
+/**
+ * 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 function SlottedConversationItem(props: SlottedConversationItemProps) {
+  const [local] = splitProps(props, ['conversationId', 'active', 'compact', 'leading', 'meta', 'menu', 'children', 'hostSemantics', 'onActivate', 'class']);
+  return (
+    // The sibling restructure: axe nested-interactive
+    // bans focusable descendants of an activation control, so the control role
+    // sits on the row BODY and the consumer's menu is its tabbable SIBLING
+    // (the nav.tsx TrailingActions precedent). The vocabulary is
+    // list/listitem/button + aria-current — NOT listbox/option, because axe
+    // aria-required-children lets a listbox subtree own nothing but options
+    // (and groups of options), which outlaws a sibling menu ANYWHERE inside
+    // it; button + aria-current is also exactly what the batteries-mode
+    // ConversationItem row above renders, so the two modes speak one dialect.
+    <div
+      part="row"
+      role={local.hostSemantics ? 'presentation' : 'listitem'}
+      data-active={local.active ? '' : undefined}
+      data-conversation-id={local.conversationId}
+      class={cn(
+        'flex w-full items-center gap-2.5 rounded-lg text-left transition-colors',
+        local.compact ? 'px-2.5 py-1.5' : 'px-2.5 py-2',
+        local.active ? 'bg-muted' : 'hover:bg-muted/50',
+        local.class,
+      )}
+    >
+      <div
+        part="body"
+        role="button"
+        data-kai-item-body
+        aria-current={local.active ? 'true' : 'false'}
+        // Standalone activation only: with `onActivate` unset —
+        // the inside-a-container case — no tabindex and no handlers render, so
+        // the container's delegated activation stays the single path.
+        tabindex={local.onActivate ? 0 : undefined}
+        onClick={() => local.onActivate?.()}
+        onKeyDown={(e: KeyboardEvent) => {
+          if (!local.onActivate) return;
+          if (e.key === 'Enter' || e.key === ' ') {
+            e.preventDefault(); // Space must not scroll the page
+            local.onActivate();
+          }
+        }}
+        class="flex min-w-0 flex-1 cursor-pointer items-center gap-2.5 rounded-md focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring"
+      >
+        <Show when={local.leading}>
+          <span part="leading" class="flex shrink-0 items-center text-muted-foreground">{local.leading}</span>
+        </Show>
+        <div class="min-w-0 flex-1">
+          <div part="title" class={cn('truncate text-sm', local.active ? 'font-medium text-foreground' : 'text-foreground/80')}>
+            {local.children}
+          </div>
+          <Show when={local.meta}>
+            <div part="meta" class="mt-0.5 truncate text-xs text-muted-foreground">{local.meta}</div>
+          </Show>
+        </div>
+      </div>
+      <Show when={local.menu}>
+        <span part="menu" data-kai-item-menu class="ml-auto flex shrink-0 items-center">{local.menu}</span>
+      </Show>
+    </div>
+  );
+}
+
 export function ConversationItem(props: ConversationItemProps) {
   const [local] = splitProps(props, ['conversation', 'isActive', 'onSelect', 'compact', 'class']);
   // The trailing text: the consumer's own `trailing` field, else an auto relative
-  // time from updatedAt (fallback lastMessageAt). REACTIVITY: this (and the auto
-  // time) update when the consumer re-assigns the `conversations` array with a new
-  // reference — the kit's standard reactivity model — not via an internal clock.
+  // time from updatedAt (fallback lastMessageAt). Never an internal clock — it is a
+  // render-time snapshot.
+  //
+  // REACTIVITY, and the weaker version of this note is what #224 was filed against:
+  // a new `conversations` array reference is NOT sufficient. `ConversationList` renders
+  // these rows through a reference-keyed `<For>` that captures `conv` as a VALUE, so a
+  // row whose item object is unchanged is never re-invoked and never re-reads anything
+  // below. The consumer needs BOTH — a new array (which is what notifies at all) and a
+  // new object for the item that changed (which is what this row can see). Adds,
+  // removes and reorders are fine on a fresh array alone, since those rows' identities
+  // already differ. Pinned by `src/components/reactivity-contract.test.tsx`.
   const trailing = createMemo(
     () => local.conversation.trailing ?? relativeTimeShort(local.conversation.updatedAt ?? local.conversation.lastMessageAt),
   );

package/src/components/conversation-list.tsx

@@ -30,6 +30,175 @@ 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;
+}
+
+/** 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 function isStandaloneConversationItem(el: Element): boolean {
+  return el.parentElement?.localName !== 'kai-conversations';
+}
+
+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 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: 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 +220,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;
 }
 
@@ -64,8 +247,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,32 +318,61 @@ 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>
             <input ref={searchInput} type="text" value={searchQuery()} onInput={(e) => setQuery(e.currentTarget.value)} placeholder="Search chats..."
               aria-label="Search chats"
-              class="bg-transparent text-[13px] text-foreground placeholder:text-muted-foreground rounded-sm focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring w-full" />
+              class="bg-transparent text-compact text-foreground placeholder:text-muted-foreground rounded-sm focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring w-full" />
           </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. */}
+      <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 +397,7 @@ export function ConversationList(props: ConversationListProps) {
             </Show>
           </Show>
         </ScrollArea>
+        </Show>
       </Show>
       {/* footer (inject): a row below the list (account / settings / …). */}
       <Show when={local.footer}>
@@ -196,11 +411,11 @@ function GroupSection(props: { name: string; count: number; conversations: Conve
   const [open, setOpen] = createSignal(true);
   return (
     <Collapsible open={open()} onOpenChange={setOpen}>
-      <CollapsibleTrigger class="flex items-center gap-1.5 w-full px-1.5 py-1 rounded-md text-[13px] text-muted-foreground font-medium hover:bg-muted/30 transition-colors cursor-pointer mt-1.5">
+      <CollapsibleTrigger class="flex items-center gap-1.5 w-full px-1.5 py-1 rounded-md text-compact text-muted-foreground font-medium hover:bg-muted/30 transition-colors cursor-pointer mt-1.5">
         <svg width="10" height="10" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"
           class={cn('transition-transform', !open() && '-rotate-90')}><polyline points="6 9 12 15 18 9"/></svg>
         <span>{props.name}</span>
-        <Badge variant="count" class="ml-auto text-[11px]">{props.count}</Badge>
+        <Badge variant="count" class="ml-auto text-caption">{props.count}</Badge>
       </CollapsibleTrigger>
       <CollapsibleContent>
         <div class="pl-2 mt-0.5 space-y-0.5">