@kitn.ai/ui 0.26.0 → 0.28.0

package/src/components/choice-card.tsx

@@ -14,6 +14,7 @@ import {
 } from 'solid-js';
 import { cn } from '../utils/cn';
 import { Button } from '../ui/button';
+import { Radio } from '../ui/radio';
 import { HoverCard } from '../ui/hover-card';
 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, X } from 'lucide-solid';
+import { Check } from 'lucide-solid';
 
 // ─────────────────────────────────────────────────────────────────────────────
 // Types (choice.schema.json) — AUTHORED IN ../primitives/card-data-types.ts.
@@ -430,6 +431,10 @@ export function ChoiceCard(props: ChoiceCardProps): JSX.Element {
   const groupLabel = (): string => local.heading ?? local.data?.prompt ?? 'Choose an option';
   const promptId = `kai-choice-prompt-${uid}`;
   const otherInputId = `kai-choice-other-${uid}`;
+  // The shared `name` is what makes the rows ONE native control: mutual exclusion,
+  // form participation and "2 of 4" from a screen reader all come from it. Scoped to
+  // this card's uid so two ChoiceCards on a page never de-select each other.
+  const radioName = `kai-choice-${uid}`;
 
   return (
     <Show when={valid()} fallback={<Card heading={local.heading} errorMessage={errorMessage()} />}>
@@ -443,14 +448,18 @@ export function ChoiceCard(props: ChoiceCardProps): JSX.Element {
           when={!res.isDeferred()}
           fallback={<DismissedStub type={CHOICE_CARD_TYPE} title={local.heading} onReopen={onReopen} />}
         >
-        <Card heading={local.heading}>
+        {/* `prompt` is the card's supporting sentence — the same role `form`'s
+            `description` plays — so it goes through the shell's `description`
+            slot rather than being re-implemented in the body. That is what gives
+            it the muted colour: at full `text-foreground` it was the same colour
+            as the heading above it, which flattened the hierarchy. `descriptionId`
+            keeps the radiogroup's `aria-describedby` pointing at it. */}
+        <Card
+          heading={local.heading}
+          description={local.data?.prompt}
+          descriptionId={promptId}
+        >
           <div class={cn('flex flex-col gap-3', local.class)}>
-            <Show when={local.data?.prompt}>
-              <p id={promptId} class="text-sm text-foreground">
-                {local.data?.prompt}
-              </p>
-            </Show>
-
             <Show
               when={!res.isResolved()}
               fallback={<ResolvedChoice choice={resolvedChoice()!} optimistic={res.isOptimistic()} />}
@@ -462,7 +471,7 @@ export function ChoiceCard(props: ChoiceCardProps): JSX.Element {
                 aria-describedby={local.data?.prompt ? promptId : undefined}
                 aria-disabled={isDisabled() ? 'true' : undefined}
                 class={cn(
-                  'divide-y divide-border overflow-hidden rounded-lg border border-input',
+                  'divide-y divide-border overflow-hidden rounded-lg border border-border',
                   isDisabled() && 'cursor-not-allowed opacity-60',
                 )}
                 onKeyDown={onGroupKeyDown}
@@ -477,8 +486,10 @@ export function ChoiceCard(props: ChoiceCardProps): JSX.Element {
                     return (
                       <ListRow
                         opt={opt}
+                        name={radioName}
                         checked={checked()}
                         tabStop={tabStop()}
+                        groupDisabled={isDisabled()}
                         descId={descId}
                         hasDesc={hasDesc()}
                         onPick={() => {
@@ -518,14 +529,23 @@ export function ChoiceCard(props: ChoiceCardProps): 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>
                 <Button type="button" class="ml-auto" disabled={!canSubmit()} onClick={submit}>
@@ -542,14 +562,19 @@ export function ChoiceCard(props: ChoiceCardProps): JSX.Element {
 }
 
 // ─────────────────────────────────────────────────────────────────────────────
-// Internal list-row presentation: a `role="radio"` with the kit's
-// selectable-list styling.
+// Internal list-row presentation: a `<label>` row wrapping a REAL
+// `<input type="radio">` (the `Radio` primitive), with the kit's selectable-list
+// styling.
 // ─────────────────────────────────────────────────────────────────────────────
 
 interface RowProps {
   opt: ChoiceOption;
+  /** The shared form-control name every radio in this card's group carries. */
+  name: string;
   checked: boolean;
   tabStop: boolean;
+  /** The whole group is frozen (`disabled` prop), not just this row. */
+  groupDisabled: boolean;
   descId: string;
   hasDesc: boolean;
   onPick: () => void;
@@ -558,7 +583,7 @@ interface RowProps {
 
 function RecommendedPill(): JSX.Element {
   return (
-    <span class="inline-flex items-center rounded-full bg-[var(--color-primary)] px-1.5 py-0.5 text-[0.625rem] font-medium uppercase leading-none tracking-wide text-[var(--color-primary-foreground,white)]">
+    <span class="inline-flex items-center rounded-full bg-[var(--color-primary)] px-1.5 py-0.5 text-micro font-medium uppercase leading-none tracking-wide text-[var(--color-primary-foreground,white)]">
       Recommended
     </span>
   );
@@ -587,25 +612,76 @@ function IconBadge(props: { name: string }): JSX.Element {
   );
 }
 
+/**
+ * One row of the radiogroup.
+ *
+ * The control is a REAL `<input type="radio">` (the `Radio` primitive over
+ * `.kai-radio`), not the `aria-hidden` ring-shaped `<span>` this row used to draw.
+ * That is what buys form participation — a `name`, a `value`, and a real entry in a
+ * native `FormData` — which a `<div role="radio">` can never have, and it removes the
+ * fourth hand-rolled radio from the kit.
+ *
+ * WHY `role="radio"` IS ON THE INPUT AND NOT ON THE ROW. `choice-card.tsx`'s own
+ * keyboard handler and `response-compare.tsx` both drive `[role="radio"]`, an
+ * ATTRIBUTE selector that a native radio's implicit role does not match, so the role
+ * has to be written somewhere. Putting it on the `<label>` wrapper (which the plan
+ * suggested) would nest a radio inside a radio and announce the row twice; putting it
+ * on the input states the role the input already has. `aria-checked` / `aria-disabled`
+ * are likewise redundant with `checked` / `disabled` and kept in lockstep with them —
+ * they are the state the element tests read, and a redundant ARIA attribute that never
+ * disagrees with the DOM is harmless where a second radio in the a11y tree is not.
+ *
+ * The row's `<label>` is what makes a click anywhere on it select the option, which is
+ * the browser's own behaviour rather than the `onClick` re-implementation it replaces.
+ * The `onClick` is kept as well: it is the path the existing tests fire, and both paths
+ * land on the same idempotent `select()`.
+ */
 function ListRow(props: RowProps): JSX.Element {
+  // The row is inert when the option itself is disabled OR the whole group is frozen.
+  // The group case has to reach the native `disabled` attribute: an enabled input
+  // would visibly check itself on click while `select()` refuses the state change, and
+  // the DOM would then be lying about the selection.
+  const inert = (): boolean => props.opt.disabled === true || props.groupDisabled;
+  const pick = (): void => {
+    if (inert()) return;
+    props.onPick();
+  };
   return (
-    <div
-      role="radio"
-      aria-checked={props.checked}
-      aria-disabled={props.opt.disabled ? 'true' : undefined}
-      aria-describedby={props.hasDesc ? props.descId : undefined}
-      data-option-id={props.opt.id}
-      tabindex={props.opt.disabled ? -1 : props.tabStop ? 0 : -1}
-      onClick={() => !props.opt.disabled && props.onPick()}
-      onFocus={props.onFocus}
+    <label
+      onClick={pick}
       class={cn(
-        'flex items-center gap-3 px-3 py-2.5 text-sm outline-none transition-colors focus-visible:ring-2 focus-visible:ring-inset focus-visible:ring-ring',
+        'flex items-center gap-3 px-3 py-2.5 text-sm transition-colors',
+        // The focus ring stays on the ROW and stays inset — the same 2px inset ring the
+        // focusable `div` painted. Focus now lands on the input inside it, so the
+        // selector moves from `focus-visible:` to `has-[:focus-visible]:`; the input's
+        // own outline is suppressed below so there is one ring, not two. That is the
+        // pattern src/elements/styles.css sanctions at its `:focus-visible` rule.
+        'has-[:focus-visible]:ring-2 has-[:focus-visible]:ring-inset has-[:focus-visible]:ring-ring',
         props.opt.disabled
           ? 'cursor-not-allowed opacity-60 text-foreground'
           : 'cursor-pointer hover:bg-muted/50',
         props.checked ? 'bg-accent font-medium text-accent-foreground' : 'text-foreground',
       )}
     >
+      {/* FIRST in the row, ahead of any media. It used to sit AFTER the thumbnail/icon
+          badge, so a list where only some options carried media had a ragged control
+          column (measured 98px vs 50px in the `WithOther` story). The control column is
+          the one thing every row shares, so it leads. */}
+      <Radio
+        role="radio"
+        name={props.name}
+        value={props.opt.id}
+        checked={props.checked}
+        disabled={inert()}
+        aria-checked={props.checked}
+        aria-disabled={props.opt.disabled ? 'true' : undefined}
+        aria-describedby={props.hasDesc ? props.descId : undefined}
+        data-option-id={props.opt.id}
+        tabindex={props.opt.disabled ? -1 : props.tabStop ? 0 : -1}
+        class="focus-visible:outline-none"
+        onChange={pick}
+        onFocus={props.onFocus}
+      />
       <Show when={props.opt.media?.image}>
         <HoverCard
           openDelay={150}
@@ -623,17 +699,6 @@ function ListRow(props: RowProps): JSX.Element {
       <Show when={!props.opt.media?.image && props.opt.media?.icon}>
         <IconBadge name={props.opt.media!.icon!} />
       </Show>
-      <span
-        aria-hidden="true"
-        class={cn(
-          'flex h-[1.125rem] w-[1.125rem] shrink-0 items-center justify-center rounded-full border-[1.5px] transition-colors',
-          props.checked ? 'border-[var(--color-primary)]' : 'border-input bg-background',
-        )}
-      >
-        <Show when={props.checked}>
-          <span class="h-2 w-2 rounded-full bg-[var(--color-primary)]" />
-        </Show>
-      </span>
       <span class="flex min-w-0 flex-col gap-0.5">
         <span class="flex items-center gap-2">
           <span class="truncate">{props.opt.label}</span>
@@ -652,7 +717,7 @@ function ListRow(props: RowProps): JSX.Element {
           {props.opt.meta}
         </span>
       </Show>
-    </div>
+    </label>
   );
 }
 
@@ -663,7 +728,7 @@ function ResolvedChoice(props: {
   const c = props.choice;
   return (
     <div
-      class="flex items-center gap-3 rounded-lg border border-input bg-accent px-3 py-2.5 text-sm font-medium text-accent-foreground"
+      class="flex items-center gap-3 rounded-lg border border-border bg-accent px-3 py-2.5 text-sm font-medium text-accent-foreground"
       role={props.optimistic ? 'status' : undefined}
     >
       <Check size={16} aria-hidden="true" />

package/src/components/coachmark.tsx

@@ -228,7 +228,7 @@ export function Coachmark(props: CoachmarkProps) {
                 <Show when={props.badge}>
                   <span
                     part="badge"
-                    class={cn('inline-flex items-center rounded-full px-1.5 py-0.5 text-[0.625rem] font-medium uppercase leading-none tracking-wide', BADGE_CLS)}
+                    class={cn('inline-flex items-center rounded-full px-1.5 py-0.5 text-micro font-medium uppercase leading-none tracking-wide', BADGE_CLS)}
                   >
                     {props.badge}
                   </span>

package/src/components/code-block.tsx

@@ -122,8 +122,8 @@ function CodeBlockCode(props: CodeBlockCodeProps) {
 
   const codeTextSize = () => {
     switch (config.proseSize()) {
-      case 'xs': return 'text-[11px]';
-      case 'sm': return 'text-[13px]';
+      case 'xs': return 'text-caption';
+      case 'sm': return 'text-compact';
       case 'base': return 'text-sm';
       case 'lg': return 'text-base';
     }

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,23 +801,78 @@ 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.
+  // 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 kai-focus-inset 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. */}
@@ -846,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"]) {
@@ -991,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

@@ -31,9 +31,32 @@ export function relativeTimeShort(iso?: string, now: number = Date.now()): strin
   return `${Math.floor(hours / 24)}d ago`;
 }
 
+/**
+ * Whether a conversation should show an unread indicator (owner round,
+ * 2026-08-26). `lastReadAt`'s own doc (`types.ts`) has the full contract;
+ * this is the one place that reads it, so both list surfaces (this file's
+ * `ConversationItem` and the widget-box `ConversationPanel`) derive it
+ * identically rather than each restating the comparison.
+ *
+ * Absent `lastReadAt` reads as NOT unread — the decide-loudly default for a
+ * store that never implements `ConversationStore.markRead` at all (every
+ * summary it returns leaves the field undefined forever, so this always
+ * returns `false` for it) rather than guessing "probably unread" from a
+ * signal the store never actually provided. Defensive `Date.parse`, same
+ * pattern as `relativeTimeShort` above: an unparsable date reads as not
+ * unread rather than throwing.
+ */
+export function isConversationUnread(conv: Pick<ConversationSummary, 'updatedAt' | 'lastReadAt'>): boolean {
+  if (!conv.lastReadAt) return false;
+  const updated = Date.parse(conv.updatedAt);
+  const read = Date.parse(conv.lastReadAt);
+  if (Number.isNaN(updated) || Number.isNaN(read)) return false;
+  return updated > read;
+}
+
 /**
  * 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
+ * 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`.
  *
@@ -41,16 +64,19 @@ export function relativeTimeShort(iso?: string, now: number = Date.now()): strin
  * 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.
+ * 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
- * (ratified 2026-08-20; axe `nested-interactive` bans focusable descendants of
+ * (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
@@ -80,13 +106,22 @@ export interface SlottedConversationItemProps {
    *  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', 'class']);
+  const [local] = splitProps(props, ['conversationId', 'active', 'compact', 'leading', 'meta', 'menu', 'children', 'hostSemantics', 'onActivate', 'class']);
   return (
-    // The sibling restructure (ratified 2026-08-20): axe nested-interactive
+    // 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
@@ -112,6 +147,18 @@ export function SlottedConversationItem(props: SlottedConversationItemProps) {
         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}>