@kitn.ai/ui 0.17.0 → 0.18.1

package/src/components/message.tsx

@@ -20,7 +20,7 @@ export interface MessageProps extends JSX.HTMLAttributes<HTMLDivElement> {
 function Message(props: MessageProps) {
   const [local, rest] = splitProps(props, ["children", "class"]);
   return (
-    <div class={cn("flex items-start gap-3", local.class)} {...rest}>
+    <div part="row" class={cn("flex items-start gap-3", local.class)} {...rest}>
       {local.children}
     </div>
   );
@@ -38,6 +38,7 @@ export interface MessageAvatarProps {
 function MessageAvatar(props: MessageAvatarProps) {
   return (
     <div
+      part="avatar"
       class={cn("h-8 w-8 shrink-0 overflow-hidden rounded-full", props.class)}
     >
       <Show
@@ -65,10 +66,14 @@ function MessageAvatar(props: MessageAvatarProps) {
 export interface MessageContentProps extends JSX.HTMLAttributes<HTMLDivElement> {
   children: JSX.Element | string;
   markdown?: boolean;
+  /** `::part` name(s) exposed on the content node. The body passes
+   *  `"bubble content"` so consumers can target either the rounded bubble or the
+   *  text region from outside the shadow boundary. */
+  part?: string;
 }
 
 function MessageContent(props: MessageContentProps) {
-  const [local, rest] = splitProps(props, ["children", "markdown", "class"]);
+  const [local, rest] = splitProps(props, ["children", "markdown", "class", "part"]);
   const config = useChatConfig();
   const classNames = () =>
     cn(
@@ -81,12 +86,12 @@ function MessageContent(props: MessageContentProps) {
     <Show
       when={local.markdown}
       fallback={
-        <div class={classNames()} {...rest}>
+        <div part={local.part} class={classNames()} {...rest}>
           {local.children}
         </div>
       }
     >
-      <Markdown content={local.children as string} class={classNames()} />
+      <Markdown part={local.part} content={local.children as string} class={classNames()} />
     </Show>
   );
 }
@@ -163,6 +168,7 @@ function feedbackVoteOf(a: ChatMessageAction | CustomAction): FeedbackVote | und
 function MessageActionBar(props: MessageActionBarProps) {
   return (
     <MessageActions
+      part="actions"
       class={cn(
         'mt-1 flex gap-0',
         props.reveal === 'hover' && 'opacity-0 transition-opacity group-hover:opacity-100',
@@ -273,6 +279,14 @@ export interface MessageBodyProps {
   activeFeedback?: FeedbackVote;
   /** When true, the copy button shows its "copied" check icon. */
   copied?: boolean;
+  /** INJECT slot projected at the TOP of the body — above the reasoning / tools /
+   *  content. A per-message header: a model-name label, a role + timestamp line.
+   *  In the `<kai-message>` shadow this is `<slot name="before-body" />`. */
+  beforeBody?: JSX.Element;
+  /** INJECT slot projected at the BOTTOM of the body — below the action bar. A
+   *  citation / sources row, a token-cost / latency line. In the `<kai-message>`
+   *  shadow this is `<slot name="after-body" />`. */
+  afterBody?: JSX.Element;
 }
 
 /**
@@ -286,6 +300,8 @@ export interface MessageBodyProps {
 function MessageBody(props: MessageBodyProps) {
   return (
     <>
+      {/* before-body (inject): a per-message header above everything else. */}
+      <Show when={props.beforeBody}>{props.beforeBody}</Show>
       <Show when={props.reasoning}>
         {(r) => (
           <Reasoning class="mb-2 w-full">
@@ -303,6 +319,7 @@ function MessageBody(props: MessageBodyProps) {
         </Attachments>
       </Show>
       <MessageContent
+        part="bubble content"
         markdown={props.markdown}
         class={props.isUser
           ? 'bg-muted text-primary max-w-[85%] rounded-2xl px-4 py-2'
@@ -319,6 +336,8 @@ function MessageBody(props: MessageBodyProps) {
           onAction={(id) => props.onAction?.(id)}
         />
       </Show>
+      {/* after-body (inject): a citation row / cost line below the action bar. */}
+      <Show when={props.afterBody}>{props.afterBody}</Show>
     </>
   );
 }

package/src/components/model-switcher.tsx

@@ -1,10 +1,21 @@
 import { splitProps, For, Show, createSignal } from 'solid-js';
 import { cn } from '../utils/cn';
-import { Dropdown, DropdownTrigger, DropdownContent, DropdownItem } from '../ui/dropdown';
+import { Dropdown, DropdownTrigger, DropdownContent, DropdownItem, type DropdownController } from '../ui/dropdown';
 import { Button } from '../ui/button';
 import type { ModelOption } from '../types';
 
-export interface ModelSwitcherProps { models: ModelOption[]; currentModelId: string; onModelChange: (modelId: string) => void; class?: string; }
+export interface ModelSwitcherProps {
+  models: ModelOption[];
+  currentModelId: string;
+  onModelChange: (modelId: string) => void;
+  class?: string;
+  /** Initial open state of the dropdown (uncontrolled seed). */
+  defaultOpen?: boolean;
+  /** Disable the trigger — click/keyboard no longer open the dropdown. */
+  disabled?: boolean;
+  /** Receive the dropdown's open controller (forwarded from the inner Dropdown). */
+  controllerRef?: (api: DropdownController) => void;
+}
 
 const Chevron = (props: { class?: string }) => (
   <svg width="12" height="12" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" class={props.class}>
@@ -25,7 +36,7 @@ function ModelRow(props: { model: ModelOption; currentModelId: string; onModelCh
 }
 
 export function ModelSwitcher(props: ModelSwitcherProps) {
-  const [local] = splitProps(props, ['models', 'currentModelId', 'onModelChange', 'class']);
+  const [local] = splitProps(props, ['models', 'currentModelId', 'onModelChange', 'class', 'defaultOpen', 'disabled', 'controllerRef']);
   const currentModel = () => local.models.find((m) => m.id === local.currentModelId);
 
   // Ungrouped models list first; grouped models collect under their group name,
@@ -44,7 +55,11 @@ export function ModelSwitcher(props: ModelSwitcherProps) {
 
   return (
     <Show when={local.models.length > 1}>
-      <Dropdown>
+      <Dropdown
+        defaultOpen={local.defaultOpen}
+        disabled={local.disabled}
+        controllerRef={local.controllerRef}
+      >
         <DropdownTrigger as={(triggerProps: any) => (
           <Button variant="ghost" size="sm" class={cn('gap-1 text-meta text-muted-foreground', local.class)} {...triggerProps}>
             {currentModel()?.name ?? local.currentModelId}

package/src/components/prompt-input.tsx

@@ -1,18 +1,21 @@
-import { type JSX, splitProps, createSignal, createContext, useContext, createEffect, on } from 'solid-js';
+import { type JSX, splitProps, createSignal, createContext, useContext } from 'solid-js';
 import { cn } from '../utils/cn';
 import { useChatConfig, textClass } from '../primitives/chat-config';
+import { Composer, type TriggerDef, type ComposerChange } from './composer';
+import type { ComposerDoc } from '../primitives/composer-model';
 
 // --- Context ---
 
 interface PromptInputContextType {
   isLoading: boolean;
-  value: () => string;
+  // A string (controlled text) or a ComposerDoc (a seed that pre-populates pills).
+  value: () => string | ComposerDoc;
   setValue: (value: string) => void;
   maxHeight: number | string;
   onSubmit?: () => void;
   disabled?: boolean;
-  textareaRef: HTMLTextAreaElement | undefined;
-  setTextareaRef: (el: HTMLTextAreaElement) => void;
+  textareaRef: HTMLElement | undefined;
+  setTextareaRef: (el: HTMLElement) => void;
 }
 
 const PromptInputContext = createContext<PromptInputContextType>();
@@ -27,7 +30,8 @@ function usePromptInput() {
 
 export interface PromptInputProps extends JSX.HTMLAttributes<HTMLDivElement> {
   isLoading?: boolean;
-  value?: string;
+  /** String = controlled text; ComposerDoc = a seed that pre-populates pills. */
+  value?: string | ComposerDoc;
   onValueChange?: (value: string) => void;
   maxHeight?: number | string;
   onSubmit?: () => void;
@@ -41,8 +45,8 @@ function PromptInput(props: PromptInputProps) {
     'children', 'disabled', 'class', 'onClick',
   ]);
 
-  const [internalValue, setInternalValue] = createSignal(local.value ?? '');
-  let textareaRef: HTMLTextAreaElement | undefined;
+  const [internalValue, setInternalValue] = createSignal<string | ComposerDoc>(local.value ?? '');
+  let textareaRef: HTMLElement | undefined;
 
   const handleChange = (newValue: string) => {
     setInternalValue(newValue);
@@ -70,13 +74,14 @@ function PromptInput(props: PromptInputProps) {
       }}
     >
       <div
+        data-prompt-input
         onClick={handleClick}
         class={cn(
           // The inner textarea neutralizes its own ring (focus-visible:ring-0),
           // so the FRAME owns the focus affordance: a blue ring whenever a
           // control inside it is focused. Without this the composer had no
           // visible keyboard-focus state.
-          'bg-muted/40 cursor-text rounded-xl p-2 shadow-xs',
+          'bg-surface cursor-text rounded-xl p-2 shadow-xs',
           'focus-within:ring-2 focus-within:ring-ring focus-within:ring-offset-0',
           local.disabled && 'cursor-not-allowed opacity-60',
           local.class
@@ -93,83 +98,49 @@ function PromptInput(props: PromptInputProps) {
 
 export interface PromptInputTextareaProps extends JSX.TextareaHTMLAttributes<HTMLTextAreaElement> {
   disableAutosize?: boolean;
+  /** Rich entity triggers (`/`, `@`) forwarded to the composer. */
+  triggers?: TriggerDef[];
+  /** Default icon per entity kind (kind → image src), forwarded to the composer. */
+  kindIcons?: Record<string, string>;
+  /** Structured change (doc + entities) from the composer, on every edit. */
+  onComposerChange?: (change: ComposerChange) => void;
 }
 
 function PromptInputTextarea(props: PromptInputTextareaProps) {
-  const [local, rest] = splitProps(props, ['class', 'onKeyDown', 'disableAutosize']);
+  const [local] = splitProps(props, ['class', 'placeholder', 'aria-label', 'triggers', 'kindIcons', 'onComposerChange']);
   const ctx = usePromptInput();
   const config = useChatConfig();
 
-  function adjustHeight(el: HTMLTextAreaElement | undefined) {
-    if (!el || local.disableAutosize) return;
-    el.style.height = 'auto';
-    const maxH = ctx.maxHeight;
-    if (typeof maxH === 'number') {
-      el.style.height = `${Math.min(el.scrollHeight, maxH)}px`;
-    } else {
-      el.style.height = `min(${el.scrollHeight}px, ${maxH})`;
-    }
-  }
-
-  function handleRef(el: HTMLTextAreaElement) {
-    ctx.setTextareaRef(el);
-    adjustHeight(el);
-  }
-
-  createEffect(on(
-    () => [ctx.value(), ctx.maxHeight, local.disableAutosize],
-    () => {
-      if (ctx.textareaRef && !local.disableAutosize) {
-        adjustHeight(ctx.textareaRef);
-      }
-    }
-  ));
-
-  function handleInput(e: InputEvent & { currentTarget: HTMLTextAreaElement }) {
-    const el = e.currentTarget;
-    let value = el.value;
-    // Disallow leading whitespace — a prompt can't start with a space or blank
-    // line. Strip it (covers typing a space at the start AND pasting) and keep
-    // the caret in the right place.
-    if (/^\s/.test(value)) {
-      const stripped = value.replace(/^\s+/, '');
-      const removed = value.length - stripped.length;
-      const caret = Math.max(0, (el.selectionStart ?? 0) - removed);
-      el.value = stripped;
-      el.setSelectionRange(caret, caret);
-      value = stripped;
-    }
-    adjustHeight(el);
-    ctx.setValue(value);
-  }
-
-  function handleKeyDown(e: KeyboardEvent & { currentTarget: HTMLTextAreaElement }) {
-    if (e.key === 'Enter' && !e.shiftKey) {
-      e.preventDefault();
-      // A disabled composer is non-interactive: Enter must not submit.
-      if (!ctx.disabled) ctx.onSubmit?.();
-    }
-    if (typeof local.onKeyDown === 'function') {
-      (local.onKeyDown as (e: KeyboardEvent & { currentTarget: HTMLTextAreaElement }) => void)(e);
-    }
-  }
+  // The editable mirrors the original <textarea>'s classes EXACTLY so swapping in
+  // the contenteditable composer is visually identical. The frame (PromptInput
+  // root) still owns radius/bg/padding/focus-ring; auto-grow is native to a
+  // contenteditable block (capped via max-height on the editable).
+  const editableClass = () =>
+    cn(
+      'text-foreground min-h-[44px] w-full bg-transparent shadow-none outline-none focus-visible:ring-0 focus-visible:ring-offset-0 overflow-y-auto whitespace-pre-wrap break-words',
+      textClass(config.proseSize()),
+      local.class,
+    );
 
   return (
-    <textarea
-      ref={handleRef}
+    <Composer
+      bare
       value={ctx.value()}
-      onInput={handleInput}
-      onKeyDown={handleKeyDown}
-      class={cn(
-        // Typed text uses the normal foreground (light/dark), NOT the brand/accent
-        // color — the composer should read as plain text, not tinted.
-        'text-foreground min-h-[44px] w-full resize-none border-none bg-transparent shadow-none outline-none focus-visible:ring-0 focus-visible:ring-offset-0',
-        textClass(config.proseSize()),
-        local.class
-      )}
-      rows={1}
+      placeholder={local.placeholder as string | undefined}
+      ariaLabel={local['aria-label'] as string | undefined}
       disabled={ctx.disabled}
-      {...rest}
+      maxHeight={ctx.maxHeight}
+      editableClass={editableClass()}
+      editableRef={(el) => ctx.setTextareaRef(el)}
+      triggers={local.triggers}
+      kindIcons={local.kindIcons}
+      // Surface the structured change (doc/entities) BEFORE the string value, so a
+      // consumer that enriches its events has the latest doc when value-change fires.
+      // A prompt can't start with whitespace — strip leading whitespace from the
+      // string value (parity with the old textarea); the controlled round-trip
+      // re-renders the editable so the stripped value shows too.
+      onChange={(c) => { local.onComposerChange?.(c); ctx.setValue(c.text.replace(/^\s+/, '')); }}
+      onSubmit={() => { if (!ctx.disabled) ctx.onSubmit?.(); }}
     />
   );
 }

package/src/components/prompt-suggestion.tsx

@@ -1,20 +1,30 @@
 import { type JSX, Show, splitProps } from 'solid-js';
 import { cn } from '../utils/cn';
 import { Button } from '../ui/button';
+import { renderIcon } from '../ui/icon';
 
 export interface PromptSuggestionProps extends JSX.ButtonHTMLAttributes<HTMLButtonElement> {
   children: JSX.Element | string;
   variant?: 'outline' | 'ghost' | 'default';
-  size?: 'sm' | 'md' | 'lg' | 'icon' | 'icon-sm';
+  /** Row height for the `list` layout: `'md'` (default) or `'lg'` for taller
+   *  rows (more vertical padding). Chips/block/highlight are unaffected. */
+  size?: 'md' | 'lg';
+  /** Optional leading icon (named icon, image URL/data-URI, or text). */
+  icon?: string;
   highlight?: string;
   /** Render as a full-width, left-aligned list row (the "suggested questions"
    *  idiom) instead of a rounded pill. Wraps long text. Ignored in highlight
    *  mode, which is always a list row. */
   block?: boolean;
+  /** Render as a full-width "Ideas for you" list row: a leading icon, a
+   *  left-aligned label, and a hover background. Like `block`, but keeps the
+   *  leading icon. Ignored in highlight mode. */
+  list?: boolean;
 }
 
 function PromptSuggestion(props: PromptSuggestionProps) {
-  const [local, rest] = splitProps(props, ['children', 'variant', 'size', 'class', 'highlight', 'block']);
+  const [local, rest] = splitProps(props, ['children', 'variant', 'size', 'class', 'icon', 'highlight', 'block', 'list']);
+  const Icon = () => <Show when={local.icon}>{renderIcon(local.icon, { class: 'size-3.5 shrink-0' })}</Show>;
 
   const isHighlightMode = () => local.highlight !== undefined && local.highlight.trim() !== '';
   const content = () => typeof local.children === 'string' ? local.children : '';
@@ -24,29 +34,51 @@ function PromptSuggestion(props: PromptSuggestionProps) {
       when={isHighlightMode()}
       fallback={
         <Show
-          when={local.block}
+          when={local.list}
           fallback={
-            <Button
-              variant={local.variant ?? 'outline'}
-              size={local.size ?? 'lg'}
-              class={cn('rounded-full', local.class)}
-              {...rest}
+            <Show
+              when={local.block}
+              fallback={
+                <Button
+                  variant={local.variant ?? 'outline'}
+                  size="lg"
+                  class={cn('rounded-full', local.class)}
+                  {...rest}
+                >
+                  <Icon />
+                  {local.children}
+                </Button>
+              }
             >
-              {local.children}
-            </Button>
+              <Button
+                variant={local.variant ?? 'outline'}
+                size="md"
+                class={cn(
+                  'h-auto w-full cursor-pointer justify-start rounded-xl px-4 py-2.5',
+                  'text-left text-sm leading-snug whitespace-normal text-pretty',
+                  local.class,
+                )}
+                {...rest}
+              >
+                {local.children}
+              </Button>
+            </Show>
           }
         >
           <Button
-            variant={local.variant ?? 'outline'}
-            size={local.size ?? 'md'}
+            variant={local.variant ?? 'ghost'}
+            size="md"
             class={cn(
-              'h-auto w-full cursor-pointer justify-start rounded-xl px-4 py-2.5',
+              'group h-auto w-full cursor-pointer items-center justify-start gap-2.5 rounded-xl px-3',
+              local.size === 'lg' ? 'py-3.5' : 'py-2.5',
               'text-left text-sm leading-snug whitespace-normal text-pretty',
+              'hover:bg-accent',
               local.class,
             )}
             {...rest}
           >
-            {local.children}
+            <Icon />
+            <span class="min-w-0 flex-1">{local.children}</span>
           </Button>
         </Show>
       }
@@ -56,7 +88,7 @@ function PromptSuggestion(props: PromptSuggestionProps) {
         fallback={
           <Button
             variant={local.variant ?? 'ghost'}
-            size={local.size ?? 'sm'}
+            size="sm"
             class={cn(
               'w-full cursor-pointer justify-start rounded-xl py-2',
               'hover:bg-accent',
@@ -70,7 +102,7 @@ function PromptSuggestion(props: PromptSuggestionProps) {
       >
         <Button
           variant={local.variant ?? 'ghost'}
-          size={local.size ?? 'sm'}
+          size="sm"
           class={cn(
             'w-full cursor-pointer justify-start gap-0 rounded-xl py-2',
             'hover:bg-accent',

package/src/components/reasoning.tsx

@@ -1,4 +1,4 @@
-import { type JSX, splitProps, createSignal, createContext, useContext, createEffect, onCleanup, Show } from 'solid-js';
+import { type JSX, type Accessor, splitProps, createSignal, createContext, useContext, createEffect, onCleanup, Show } from 'solid-js';
 import { cn } from '../utils/cn';
 import { ChevronDown } from 'lucide-solid';
 import { Markdown } from './markdown';
@@ -7,8 +7,14 @@ import { observeContentHeight } from '../primitives/use-resize-observer';
 interface ReasoningContextValue {
   isOpen: () => boolean;
   onOpenChange: (open: boolean) => void;
+  disabled: () => boolean;
 }
 
+/** Imperative open controller, handed to a parent (the kai-reasoning facade) via
+ *  `controllerRef` so it can drive/observe open state — mirrors
+ *  CollapsibleController/HoverCardController. */
+export interface ReasoningController { open: Accessor<boolean>; setOpen: (v: boolean) => void; }
+
 const ReasoningContext = createContext<ReasoningContextValue>();
 
 function useReasoningContext() {
@@ -25,19 +31,30 @@ export interface ReasoningProps {
   children: JSX.Element;
   class?: string;
   open?: boolean;
+  /** Initial open state (uncontrolled seed). */
+  defaultOpen?: boolean;
   onOpenChange?: (open: boolean) => void;
   isStreaming?: boolean;
+  /** Gate the trigger — programmatic control via the controller still works. */
+  disabled?: boolean;
+  /** Receive the open controller (open accessor + setOpen) once mounted. */
+  controllerRef?: (api: ReasoningController) => void;
 }
 
 function Reasoning(props: ReasoningProps) {
-  const [local] = splitProps(props, ['children', 'class', 'open', 'onOpenChange', 'isStreaming']);
-  const [internalOpen, setInternalOpen] = createSignal(false);
+  const [local] = splitProps(props, ['children', 'class', 'open', 'defaultOpen', 'onOpenChange', 'isStreaming', 'disabled', 'controllerRef']);
+  const [internalOpen, setInternalOpen] = createSignal(local.defaultOpen ?? false);
   const [wasAutoOpened, setWasAutoOpened] = createSignal(false);
 
   const isControlled = () => local.open !== undefined;
   const isOpen = () => (isControlled() ? local.open! : internalOpen());
+  const disabled = () => !!local.disabled;
 
+  // The single open-mutate path, shared by the trigger and the imperative
+  // controller. In controlled mode we don't touch internal state; the consumer
+  // reflects via the `open` prop and observes via onOpenChange.
   const handleOpenChange = (newOpen: boolean) => {
+    if (isOpen() === newOpen) return;
     if (!isControlled()) {
       setInternalOpen(newOpen);
     }
@@ -56,8 +73,13 @@ function Reasoning(props: ReasoningProps) {
     }
   });
 
+  // Hand the controller up once. setOpen routes through handleOpenChange so it
+  // notifies onOpenChange and respects controlled/uncontrolled mode. Not gated
+  // by disabled — the facade's wireDisclosure applies disabled-gating itself.
+  local.controllerRef?.({ open: isOpen, setOpen: handleOpenChange });
+
   return (
-    <ReasoningContext.Provider value={{ isOpen, onOpenChange: handleOpenChange }}>
+    <ReasoningContext.Provider value={{ isOpen, onOpenChange: handleOpenChange, disabled }}>
       <div class={local.class}>{local.children}</div>
     </ReasoningContext.Provider>
   );
@@ -71,12 +93,13 @@ export interface ReasoningTriggerProps extends JSX.ButtonHTMLAttributes<HTMLButt
 
 function ReasoningTrigger(props: ReasoningTriggerProps) {
   const [local, rest] = splitProps(props, ['children', 'class']);
-  const { isOpen, onOpenChange } = useReasoningContext();
+  const { isOpen, onOpenChange, disabled } = useReasoningContext();
 
   return (
     <button
       class={cn('flex cursor-pointer items-center gap-2 text-meta', local.class)}
-      onClick={() => onOpenChange(!isOpen())}
+      disabled={disabled() || undefined}
+      onClick={() => { if (!disabled()) onOpenChange(!isOpen()); }}
       {...rest}
     >
       <span class="text-primary">{local.children}</span>

package/src/components/response-compare.tsx

@@ -41,6 +41,18 @@ export { normalizeCandidates, buildSelection, isAnyStreaming } from './response-
 
 export type CompareLayout = 'auto' | 'columns' | 'tabs';
 
+/** Imperative handle exposed via `controllerRef` — surfaces the compare's latent
+ *  capabilities (commit a pick by candidate id, focus the roving tab stop) so the
+ *  `<kai-compare>` facade can forward them as instance methods (Pattern C). */
+export interface ResponseCompareController {
+  /** Commit a pick by candidate id — same path as the "Pick this" button: emits
+   *  onSelect + optimistically collapses (single-shot; inert while streaming or
+   *  already resolved). No-op for an unknown id. */
+  select(candidateId: string): void;
+  /** Focus the current roving tab stop (the focused candidate's "Pick this" radio). */
+  focus(options?: FocusOptions): void;
+}
+
 // ─────────────────────────────────────────────────────────────────────────────
 // Resolution controller — a sibling of `useCardResolution` for `CompareSelection`,
 // which has no `kind` field (so it can't satisfy `R extends CardResolution`). Same
@@ -88,6 +100,9 @@ export interface ResponseCompareProps {
    *  component is ≥640px wide, tabs when narrower (e.g. on a phone). */
   layout?: CompareLayout;
   class?: string;
+  /** Receive the imperative controller once mounted. The `<kai-compare>` facade
+   *  forwards these as element methods (select/focus). */
+  controllerRef?: (controller: ResponseCompareController) => void;
   /** Fired when the user commits a pick. */
   onSelect?: (sel: CompareSelection) => void;
   /** Fired once both candidates have settled (stopped streaming) and a valid
@@ -119,6 +134,7 @@ export function ResponseCompare(props: ResponseCompareProps): JSX.Element {
     'selection',
     'layout',
     'class',
+    'controllerRef',
     'onSelect',
     'onReady',
     'onError',
@@ -178,11 +194,24 @@ export function ResponseCompare(props: ResponseCompareProps): JSX.Element {
     res.setLocal(sel);
   };
 
-  const focusColumn = (index: number): void => {
+  const focusColumn = (index: number, options?: FocusOptions): void => {
     const cols = groupRef?.querySelectorAll<HTMLElement>('[role="radio"]');
-    cols?.[index]?.focus();
+    cols?.[index]?.focus(options);
   };
 
+  // Imperative controller (Pattern C): hand the facade a handle over the latent
+  // pick + roving-focus capabilities. `pick`/`focusColumn` are already wired
+  // internally — this just surfaces them. `select` looks the candidate up by id
+  // (the public surface is id-based; `pick` is candidate-based internally) and
+  // is a no-op for an unknown id, while streaming, or once resolved (via pick()).
+  local.controllerRef?.({
+    select: (candidateId: string) => {
+      const cand = pair()?.find((c) => c.id === candidateId);
+      if (cand) pick(cand);
+    },
+    focus: (options?: FocusOptions) => focusColumn(focusIndex(), options),
+  });
+
   // Two-item roving tabindex (A↔B). Arrows toggle the focused column; Enter/Space
   // picks it. No-op once resolved.
   const onGroupKeyDown = (e: KeyboardEvent): void => {