@kitn.ai/ui 0.25.1 → 0.26.0

package/src/components/audio-visualizer/variant-grid.tsx

@@ -4,7 +4,7 @@ import { normalizeVolumeBands } from '../../primitives/audio-bands';
 import { useSequencer } from '../../primitives/use-sequencer';
 import { gridSequence } from '../../primitives/visualizer-sequences';
 import { GRID_CELL, GRID_GAP, defaultGridCount } from './sizes';
-import type { VariantProps } from './variant-bar';
+import { amplitudeRenderState, type VariantProps } from './variant-bar';
 
 /*
  * NOTE: The speaking thresholds below DIVERGE from upstream's GridCell math,
@@ -64,20 +64,25 @@ export function GridVisualizer(
   const interval = () => props.interval ?? 100;
   const items = () => Array.from({ length: rows() * cols() }, (_, i) => i);
 
+  // The state the rendering follows: `listeningAmplitude` folds `listening`
+  // into the speaking presentation. See amplitudeRenderState in variant-bar.
+  const renderState = () => amplitudeRenderState(props.state, props.listeningAmplitude);
+
   const tick = useSequencer(() =>
     // Speaking is driven by audio, not the clock; freezing also parks it.
-    props.frozen || props.state === 'speaking' ? Infinity : interval(),
+    props.frozen || renderState() === 'speaking' ? Infinity : interval(),
   );
 
-  const sequence = () => gridSequence(props.state, rows(), cols(), props.spread);
+  const sequence = () => gridSequence(renderState(), rows(), cols(), props.spread);
   const active = () => sequence()[tick() % sequence().length] ?? { x: -1, y: -1 };
 
-  // Bands only mean anything while speaking. Everywhere else the sequence is
-  // the whole story, so a stale level never leaks into a scripted state (same
-  // guard as BarVisualizer, so the render-prop's `value` means one thing
-  // across every variant).
+  // Bands only mean anything while speaking (or listening under the
+  // `listeningAmplitude` opt-in, folded in by renderState). Everywhere else
+  // the sequence is the whole story, so a stale level never leaks into a
+  // scripted state (same guard as BarVisualizer, so the render-prop's `value`
+  // means one thing across every variant).
   const levels = () =>
-    props.state === 'speaking' ? normalizeVolumeBands(props.bands, cols()) : new Array(cols()).fill(0);
+    renderState() === 'speaking' ? normalizeVolumeBands(props.bands, cols()) : new Array(cols()).fill(0);
 
   /**
    * While speaking, a cell lights when its column's level clears a threshold
@@ -87,7 +92,7 @@ export function GridVisualizer(
    * both per the divergence note at the top of this file.
    */
   function isLit(index: number): boolean {
-    if (props.state === 'speaking') {
+    if (renderState() === 'speaking') {
       const y = Math.floor(index / cols());
       const mid = Math.floor(rows() / 2);
       const scaled = (Math.abs(mid - y) / (mid + 1)) * SPEECH_LEVEL_CEILING;
@@ -100,13 +105,13 @@ export function GridVisualizer(
     // upstream rests one stationary centre cell here. 'disconnected' (first-
     // class 2026-08-10) mirrors idle's dark grid for now, pending the LiveKit
     // disconnected-state measurement.
-    if (props.state === 'idle' || props.state === 'disconnected') return false;
+    if (renderState() === 'idle' || renderState() === 'disconnected') return false;
     return active().x === index % cols() && active().y === Math.floor(index / cols());
   }
 
   /** Snap on, fade off: highlighted cells transition 10x faster than they decay. */
   function transition(index: number): string {
-    if (props.state === 'speaking') return '150ms';
+    if (renderState() === 'speaking') return '150ms';
     return `${interval() / (isLit(index) ? 1000 : 100)}s`;
   }
 

package/src/components/audio-visualizer/variant-radial.tsx

@@ -4,7 +4,7 @@ import { normalizeVolumeBands } from '../../primitives/audio-bands';
 import { useSequencer } from '../../primitives/use-sequencer';
 import { radialSequence, radialInterval } from '../../primitives/visualizer-sequences';
 import { CONTAINER_HEIGHT, RADIAL_RADIUS, defaultRadialBarCount } from './sizes';
-import type { VariantProps } from './variant-bar';
+import { amplitudeRenderState, type VariantProps } from './variant-bar';
 
 /**
  * Bars arranged around a circle, growing outward with the audio.
@@ -40,10 +40,14 @@ export function RadialVisualizer(
   // many bars are on the ring.
   const dotSize = () => (radius() * Math.PI) / count();
 
+  // The state the rendering follows: `listeningAmplitude` folds `listening`
+  // into the speaking presentation. See amplitudeRenderState in variant-bar.
+  const renderState = () => amplitudeRenderState(props.state, props.listeningAmplitude);
+
   // Frozen (reduced motion) parks the sequence on frame 0 rather than stopping
   // the component: the shape still reads, it just does not move.
-  const tick = useSequencer(() => (props.frozen ? Infinity : radialInterval(props.state)));
-  const sequence = () => radialSequence(props.state, count());
+  const tick = useSequencer(() => (props.frozen ? Infinity : radialInterval(renderState())));
+  const sequence = () => radialSequence(renderState(), count());
 
   // `thinking` parks the sequencer itself (radialInterval returns Infinity)
   // and spins the whole ring in CSS instead, so every bar reads as lit rather
@@ -52,20 +56,21 @@ export function RadialVisualizer(
   // purpose: they interleave the ring so it still looks even while rotating,
   // not so a subset blinks).
   const highlighted = () =>
-    props.state === 'thinking'
+    renderState() === 'thinking'
       ? Array.from({ length: count() }, (_, i) => i)
       : (sequence()[tick() % sequence().length] ?? []);
 
-  // Bands only mean anything while speaking. Everywhere else the sequence is
-  // the whole story, so a stale level never leaks into a scripted state (same
-  // guard as the other two variants, so the render-prop's `value` means one
-  // thing across every variant).
+  // Bands only mean anything while speaking (or listening under the
+  // `listeningAmplitude` opt-in, folded in by renderState). Everywhere else
+  // the sequence is the whole story, so a stale level never leaks into a
+  // scripted state (same guard as the other two variants, so the
+  // render-prop's `value` means one thing across every variant).
   const levels = () =>
-    props.state === 'speaking'
+    renderState() === 'speaking'
       ? normalizeVolumeBands(props.bands, count())
       : new Array(count()).fill(0);
 
-  const spinning = () => props.state === 'thinking' && !props.frozen;
+  const spinning = () => renderState() === 'thinking' && !props.frozen;
 
   return (
     <div

package/src/components/audio-visualizer/variant-wave.tsx

@@ -3,6 +3,7 @@ import { ShaderCanvas, hexToRgb, DEFAULT_SHADER_COLOR } from './shader-canvas';
 import { createTween } from '../../primitives/create-tween';
 import { waveTargets } from '../../primitives/visualizer-sequences';
 import { CONTAINER_HEIGHT } from './sizes';
+import { amplitudeRenderState } from './variant-bar';
 import type { ShaderVariantProps } from './index';
 import waveShader from './wave.glsl';
 
@@ -26,7 +27,11 @@ export default function WaveVisualizer(props: ShaderVariantProps): JSX.Element {
   const frequency = createTween(0);
   const opacity = createTween(1);
 
-  const targets = () => waveTargets(props.state);
+  // The state the rendering follows: `listeningAmplitude` folds `listening`
+  // into the speaking presentation (live-volume amplitude/frequency). See
+  // amplitudeRenderState in variant-bar. `data-kai-state` keeps the real state.
+  const renderState = () => amplitudeRenderState(props.state, props.listeningAmplitude);
+  const targets = () => waveTargets(renderState());
 
   // Reduced motion: land on the target immediately and skip every pulse.
   const transition = () =>
@@ -61,7 +66,7 @@ export default function WaveVisualizer(props: ShaderVariantProps): JSX.Element {
   // effect, one writer, ordering can no longer matter. Same effect-race
   // class as b5795ac's shared() finding.
   createEffect(() => {
-    if (props.state === 'speaking') {
+    if (renderState() === 'speaking') {
       // Live volume drives amplitude and frequency instantly while
       // speaking, so the line never lags the audio -- and lands at the
       // override immediately on re-entry, matching upstream's same-commit

package/src/components/chat-container.tsx

@@ -28,7 +28,10 @@ function ChatContainerRoot(props: ChatContainerRootProps) {
     <ChatContainerContext.Provider value={{ isAtBottom, scrollToBottom }}>
       <div
         ref={ref}
-        class={cn('flex flex-col overflow-y-auto', local.class)}
+        // `kai-focus-inset`: the log fills a clipping container, so the default
+        // focus outline (drawn outside the border box) was clipped away
+        // entirely — this region was tabbable with no visible indicator.
+        class={cn('flex flex-col overflow-y-auto kai-focus-inset', local.class)}
         role="log"
         // Keyboard users must be able to scroll the conversation even when no
         // message contains a focusable control (WCAG 2.1.1 — axe

package/src/components/chat-thread.tsx

@@ -120,8 +120,8 @@ export interface ChatThreadProps {
   accept?: MediaTypeFilter;
   /** Files the composer refused because `accept` excluded them. */
   onAttachmentsRejected?: (rejected: RejectedAttachment[]) => void;
-  /** Show a Search (Globe) button in the input toolbar; fires a `search` event. */
-  search?: boolean;
+  /** Show a web-search (Globe) button in the input toolbar; calls `onWebSearch`. */
+  webSearch?: boolean;
   /** Show a Voice (Mic) button in the input toolbar; fires a `voice` event. */
   voice?: boolean;
   /** Rich entity triggers. Each `{ char, kind, items }` opens a caret-anchored
@@ -140,7 +140,7 @@ export interface ChatThreadProps {
   onSuggestionClick?: (value: string) => void;
   onModelChange?: (modelId: string) => void;
   onMessageAction?: (detail: MessageActionDetail) => void;
-  onSearch?: () => void;
+  onWebSearch?: () => void;
   onVoice?: () => void;
   /** Receive the imperative controller once mounted. The kai-chat facade forwards
    *  these as element methods (focus/clear/send/scrollToBottom). */
@@ -194,6 +194,30 @@ export interface ChatThreadController {
  *  Contract: `id` must be unique per message. It already had to be — the
  *  feedback/copy state above this list is keyed by it.
  */
+/** How an ASSISTANT row aligns its parts across the column (K-D11).
+ *
+ *  `stretch`, not `start`. An assistant turn is a `flex flex-col` box, so under
+ *  `items-start` every part is a flex item with a fit-content cross size —
+ *  `min(max-content, column)`. Prose is wider than the column so a text bubble
+ *  looked right, and a generative-UI card was as wide as its widest button: the
+ *  ops-console parameters form measured 285px inside a 768px column while the
+ *  approval card beside it filled all 768. A card in a chat thread filling its
+ *  column is a fact about the medium, and no consumer can reach it — the card
+ *  element is created inside `<kai-chat>`'s shadow root.
+ *
+ *  Stretch rather than `w-full` on the cards, for two reasons: it is one lever
+ *  instead of one per card surface (the Solid `Card` root AND every `kai-*`
+ *  card host, whose shadow wrapper is `display: contents`), and stretching only
+ *  applies where the cross size is `auto`, so a part that states its own width
+ *  is untouched — `Attachments variant="grid"` stays `w-fit`. `Tool` and
+ *  `Reasoning` already asked for `w-full` explicitly; this is the same
+ *  intention, applied once.
+ *
+ *  USER rows keep `items-end`: their bubble is `max-w-[85%]` and right aligned,
+ *  and stretching it would break both.
+ */
+const ASSISTANT_ALIGN = 'items-stretch';
+
 export function ChatThread(props: ChatThreadProps) {
   const outer = useChatConfig();
   const reveal = () => (props.actionsReveal === 'hover' ? 'hover' : 'always');
@@ -335,6 +359,11 @@ export function ChatThread(props: ChatThreadProps) {
                         const body = (
                           <MessageBody
                             parts={m().parts}
+                            /* F-21: streaming-ness = the thread's ONE existing
+                               loading signal + being the last message and an
+                               assistant turn. No second streaming source; the
+                               reasoning disclosure auto-opens on it. */
+                            isStreaming={props.loading === true && m().role === 'assistant' && i() === props.messages.length - 1}
                             cardTypes={props.cardTypes}
                             cardSchemas={props.cardSchemas}
                             isUser={m().role === 'user'}
@@ -356,7 +385,7 @@ export function ChatThread(props: ChatThreadProps) {
                           <Show
                             when={m().avatar}
                             fallback={
-                              <Message role={m().role} class={`${rowGroup()}${m().role === 'user' ? 'flex-col items-end' : 'flex-col items-start'}`}>
+                              <Message role={m().role} class={`${rowGroup()}${m().role === 'user' ? 'flex-col items-end' : `flex-col ${ASSISTANT_ALIGN}`}`}>
                                 {body}
                               </Message>
                             }
@@ -364,7 +393,7 @@ export function ChatThread(props: ChatThreadProps) {
                             {(av) => (
                               <Message role={m().role} class={rowGroup()}>
                                 <MessageAvatar src={av().src ?? ''} alt={av().alt ?? ''} fallback={av().fallback} />
-                                <div class={`flex min-w-0 flex-1 flex-col ${m().role === 'user' ? 'items-end' : 'items-start'}`}>
+                                <div class={`flex min-w-0 flex-1 flex-col ${m().role === 'user' ? 'items-end' : ASSISTANT_ALIGN}`}>
                                   {body}
                                 </div>
                               </Message>
@@ -401,11 +430,11 @@ export function ChatThread(props: ChatThreadProps) {
                     value={current()} placeholder={props.placeholder} loading={props.loading === true}
                     suggestions={visibleSuggestions()} attachments={attachments()}
                     accept={props.accept} onAttachmentsRejected={props.onAttachmentsRejected}
-                    search={props.search === true} voice={props.voice === true}
+                    webSearch={props.webSearch === true} voice={props.voice === true}
                     triggers={props.triggers} kindIcons={props.kindIcons}
                     onValueChange={handleChange} onSubmit={handleSubmit} onSuggestionClick={handleSuggestionClick}
                     onAttachmentsChange={(a) => { setAttachments(a); props.onAttachmentsChange?.(a); }}
-                    onSearch={() => props.onSearch?.()} onVoice={() => props.onVoice?.()}
+                    onWebSearch={() => props.onWebSearch?.()} onVoice={() => props.onVoice?.()}
                   />
                 }
               >

package/src/components/code-block.tsx

@@ -1,4 +1,5 @@
-import { type JSX, splitProps, createResource, Show } from 'solid-js';
+import { type JSX, splitProps, createResource, createSignal, onCleanup, Show } from 'solid-js';
+import { Copy, Check } from 'lucide-solid';
 import { cn } from '../utils/cn';
 import { useChatConfig } from '../primitives/chat-config';
 import { highlight, isCodeHighlightingEnabled } from '../primitives/highlighter';
@@ -7,10 +8,69 @@ import { highlight, isCodeHighlightingEnabled } from '../primitives/highlighter'
 
 export interface CodeBlockProps extends JSX.HTMLAttributes<HTMLDivElement> {
   children?: JSX.Element;
+  /**
+   * Render a copy button in a header row above the code.
+   *
+   * DEFAULT OFF, and deliberately. This component is shared by three surfaces —
+   * `markdown.tsx` (every fenced block in every assistant message), `artifact.tsx`
+   * (the code panel), and the `<kai-code-block>` facade — and only the ELEMENT is
+   * documented as shipping a copy button. Defaulting on would add one to every code
+   * block in every message, a kit-wide visible change. The facade opts in; the other
+   * two are untouched, which `tests/elements/code-block.test.tsx` pins both
+   * behaviourally and at the call sites.
+   */
+  copy?: boolean;
+  /**
+   * The exact text the copy button puts on the clipboard.
+   *
+   * Named for what it DOES rather than what it holds, because the distinction is the
+   * whole contract: by the time the button is clicked the source has been through
+   * Shiki, so anything read back out of the DOM is either `<span>`-laden HTML or a
+   * `textContent` reconstruction — and the reconstruction is where tabs, blank lines
+   * and trailing newlines quietly change. This prop never goes near the highlighter.
+   */
+  copyText?: string;
+}
+
+/** How long the button stays in its acknowledged state. Matches MessageCopyButton. */
+const COPIED_MS = 2000;
+
+function CodeBlockCopyButton(props: { text: string }) {
+  const [copied, setCopied] = createSignal(false);
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  // A click just before unmount would otherwise set state on a disposed owner.
+  onCleanup(() => clearTimeout(timer));
+
+  return (
+    <button
+      type="button"
+      part="copy"
+      // The name carries the state, so a screen-reader user gets the same
+      // acknowledgement the icon swap gives a sighted one. The glyph is decorative.
+      aria-label={copied() ? 'Copied' : 'Copy code'}
+      class={cn(
+        'inline-flex items-center justify-center rounded-md p-1.5',
+        'text-muted-foreground transition-colors hover:bg-muted hover:text-foreground',
+        'focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring',
+      )}
+      onClick={() => {
+        // Same mechanism as MessageCopyButton. A rejected promise (no permission,
+        // insecure context) must not become an unhandled rejection.
+        void Promise.resolve(navigator.clipboard?.writeText(props.text)).catch(() => {});
+        setCopied(true);
+        clearTimeout(timer);
+        timer = setTimeout(() => setCopied(false), COPIED_MS);
+      }}
+    >
+      <Show when={copied()} fallback={<Copy size={14} aria-hidden="true" />}>
+        <Check size={14} aria-hidden="true" class="text-emerald-500" />
+      </Show>
+    </button>
+  );
 }
 
 function CodeBlock(props: CodeBlockProps) {
-  const [local, rest] = splitProps(props, ['children', 'class']);
+  const [local, rest] = splitProps(props, ['children', 'class', 'copy', 'copyText']);
   return (
     <div
       class={cn(
@@ -23,6 +83,15 @@ function CodeBlock(props: CodeBlockProps) {
       )}
       {...rest}
     >
+      <Show when={local.copy}>
+        {/* A header row, NOT an overlay on the code: the code region scrolls
+            horizontally, so a button inside it would ride off-screen with the code.
+            Always visible — hover-only affordances fail touch outright and are
+            undiscoverable everywhere else. */}
+        <CodeBlockGroup class="justify-end border-b border-border px-2 py-1">
+          <CodeBlockCopyButton text={local.copyText ?? ''} />
+        </CodeBlockGroup>
+      </Show>
       {local.children}
     </div>
   );
@@ -62,7 +131,11 @@ function CodeBlockCode(props: CodeBlockCodeProps) {
 
   const classNames = () =>
     cn(
-      'w-full overflow-x-auto [&>pre]:px-4 [&>pre]:py-4',
+      // `kai-focus-inset`: this region fills a rounded `overflow: clip` wrapper,
+      // so the default focus outline (offset 2px, i.e. entirely outside the
+      // border box) was clipped away and keyboard users saw nothing. The inset
+      // ring is drawn inside the box, where the wrapper cannot erase it.
+      'w-full overflow-x-auto kai-focus-inset [&>pre]:px-4 [&>pre]:py-4',
       codeTextSize(),
       local.class
     );
@@ -102,4 +175,7 @@ function CodeBlockGroup(props: CodeBlockGroupProps) {
   );
 }
 
+// CodeBlockCopyButton is deliberately NOT exported: `src/index.ts` re-exports this
+// module's public trio, and adding a fourth symbol here that index.ts does not carry
+// would create a half-public component. It is an implementation detail of `copy`.
 export { CodeBlock, CodeBlockCode, CodeBlockGroup };

package/src/components/composer.tsx

@@ -799,9 +799,16 @@ export function Composer(props: ComposerProps): JSX.Element {
   // This is covered by updateTriggerState() in handleInput.
 
   const maxH = () => props.maxHeight ?? 240;
+  // No `outline-none` in the default class. This element is `contenteditable`
+  // with `role="textbox"` — a real tab stop, and the primary one in the kit —
+  // and suppressing the outline left keyboard users with no indication that the
+  // message input was focused. `kai-focus-inset` draws the ring inside the
+  // border box, because the editable fills a rounded, clipping composer shell
+  // that would otherwise erase an outset one. A consumer passing
+  // `editableClass` still replaces this wholesale.
   const editableCls = () =>
     props.editableClass ??
-    'text-foreground min-h-[44px] w-full overflow-y-auto outline-none whitespace-pre-wrap break-words';
+    'text-foreground min-h-[44px] w-full overflow-y-auto kai-focus-inset whitespace-pre-wrap break-words';
 
   const inner = (
     <>

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