@kitn.ai/ui 0.17.0 → 0.18.0

package/src/components/chat-thread.tsx

@@ -1,5 +1,6 @@
-import { createSignal, For, Show } from 'solid-js';
+import { createSignal, createEffect, For, Show, onMount } from 'solid-js';
 import { ChatConfig, useChatConfig } from '../primitives/chat-config';
+import { type ComposerDoc, normalizeValue, serializeToText } from '../primitives/composer-model';
 import { ChatContainer, ChatContainerContent, ChatContainerScrollAnchor } from './chat-container';
 import { Message, MessageAvatar, MessageBody } from './message';
 import { type AttachmentData } from './attachments';
@@ -11,7 +12,7 @@ import {
   ContextContentBody, ContextContentFooter, ContextInputUsage, ContextOutputUsage,
 } from './context';
 import { DefaultPromptInput } from '../elements/default-input';
-import type { SlashCommandItem } from './slash-command';
+import type { TriggerDef } from './composer';
 import type { ChatMessage } from '../elements/chat-types';
 import type { ProseSize } from '../primitives/chat-config';
 import type { ModelOption } from '../types';
@@ -31,9 +32,10 @@ export interface ChatThreadProps {
    *  content, and optional reasoning/tools/attachments/actions. Set as a JS
    *  property (`el.messages = [...]`). */
   messages: ChatMessage[];
-  /** Controlled value of the input. When set, the host owns the input text and
-   *  must update it on `kai-value-change`; leave unset for uncontrolled behavior. */
-  value?: string;
+  /** Value of the input. A **string** is controlled (the host owns the text and
+   *  updates it on `kai-value-change`). A **ComposerDoc** is a one-time seed that
+   *  pre-populates pills; the user then edits freely. Leave unset for uncontrolled. */
+  value?: string | ComposerDoc;
   /** Placeholder text shown in the empty input. */
   placeholder?: string;
   /** When true, shows the loading/streaming state and disables submit (use while
@@ -75,29 +77,63 @@ export interface ChatThreadProps {
   headerStart?: boolean;
   /** Whether the host has `slot="header-end"` content (right of the controls). */
   headerEnd?: boolean;
+  // ── Composition slots ─────────────────────────────────────────────────────
+  // Each flag below is set by the `<kai-chat>` facade when matching light-DOM
+  // `slot="…"` content is projected, and gates one composition slot. Two kinds:
+  //   • INJECT  — additive: project YOUR markup into a region (sidebar, footer,
+  //               composer-actions, header-start/-end).
+  //   • REPLACE — substitutive: your markup stands in for a whole region
+  //               (header, empty, composer). A replaced region's projected
+  //               content owns its own data/events — a slotted (light-DOM) node
+  //               can't read this component's reactive state. That boundary is
+  //               the whole reason `messages` stays a data prop, not a slot.
+  /** REPLACE — full custom header in place of the built-in title/model/context bar. */
+  headerFull?: boolean;
+  /** INJECT — left sidebar column (e.g. a conversation list / your own nav). */
+  sidebar?: boolean;
+  /** REPLACE — custom zero-state rendered in the message area while the thread is empty (replaces the empty message list only; the composer and its suggestions still render). */
+  empty?: boolean;
+  /** REPLACE — full custom composer in place of the built-in prompt input. The
+   *  projected content wires its own submit (the data-flow boundary). */
+  composer?: boolean;
+  /** INJECT — accessory row just above the composer (e.g. extra actions). */
+  composerActions?: boolean;
+  /** INJECT — footer row below the composer (disclaimers, token meter, …). */
+  footer?: boolean;
   /** Show a Search (Globe) button in the input toolbar; fires a `search` event. */
   search?: boolean;
   /** Show a Voice (Mic) button in the input toolbar; fires a `voice` event. */
   voice?: boolean;
-  /** Slash commands — when set, typing `/` in the input opens the command
-   *  palette and fires `kai-slash-select`. Set as a JS property. */
-  slashCommands?: SlashCommandItem[];
-  /** Command ids to highlight as active in the palette. */
-  slashActiveIds?: string[];
-  /** Single-line palette rows. */
-  slashCompact?: boolean;
+  /** Rich entity triggers — each `{ char, kind, items }` opens a caret-anchored
+   *  menu that inserts an atomic pill (`/` skills, `@` agents/plugins). Set as a
+   *  JS property; forwarded to the input. */
+  triggers?: TriggerDef[];
+  /** Default icon per entity kind (kind → image src) for pills/menu items. */
+  kindIcons?: Record<string, string>;
   /** Whether each message's action bar is always visible (`'always'`, default)
    *  or only revealed on hover of that message row (`'hover'`). */
   actionsReveal?: 'always' | 'hover';
   // callbacks (the facade maps these to dispatch())
   onValueChange?: (value: string) => void;
   onSubmit?: (detail: { value: string; attachments: AttachmentData[] }) => void;
+  onAttachmentsChange?: (attachments: AttachmentData[]) => void;
   onSuggestionClick?: (value: string) => void;
   onModelChange?: (modelId: string) => void;
   onMessageAction?: (detail: MessageActionDetail) => void;
   onSearch?: () => void;
   onVoice?: () => void;
-  onSlashSelect?: (command: SlashCommandItem) => void;
+  /** Receive the imperative controller once mounted. The kai-chat facade forwards
+   *  these as element methods (focus/clear/send/scrollToBottom). */
+  controllerRef?: (controller: ChatThreadController) => void;
+}
+
+/** Imperative handle exposed via `controllerRef` — the input half of the chat's
+ *  interaction surface, forwarded onto `<kai-chat>` as instance methods. */
+export interface ChatThreadController {
+  focus(options?: FocusOptions): void;
+  clear(): void;
+  send(): void;
+  scrollToBottom(behavior?: ScrollBehavior): void;
 }
 
 export function ChatThread(props: ChatThreadProps) {
@@ -112,14 +148,26 @@ export function ChatThread(props: ChatThreadProps) {
     emit: (detail) => props.onMessageAction?.(detail),
     target: () => rootEl,
   });
-  const [internal, setInternal] = createSignal(props.value ?? '');
+  const [internal, setInternal] = createSignal<string | ComposerDoc>(props.value ?? '');
   const [attachments, setAttachments] = createSignal<AttachmentData[]>([]);
-  const current = () => props.value ?? internal();
+  // A string `value` is controlled; a ComposerDoc `value` is a one-time seed that
+  // lives in `internal` so the user's (string) edits replace it without a fight.
+  const current = (): string | ComposerDoc =>
+    typeof props.value === 'string' ? props.value : internal();
+  createEffect(() => {
+    const v = props.value;
+    if (v != null && typeof v !== 'string') setInternal(v);
+  });
   const handleChange = (v: string) => { setInternal(v); props.onValueChange?.(v); };
-  const handleSubmit = () => { props.onSubmit?.({ value: current(), attachments: attachments() }); setAttachments([]); };
+  // After a send, reset the composer. Clear the internal draft ONLY when the value is
+  // uncontrolled (props.value === undefined) — a controlled host owns its own value and
+  // clears it itself. This lets the batteries-included hooks (useKaiChat/createKaiChat),
+  // whose `bind` does not control `value`, get a clean composer after each submit.
+  const afterSubmit = () => { setAttachments([]); if (props.value === undefined) setInternal(''); };
+  const handleSubmit = () => { props.onSubmit?.({ value: serializeToText(normalizeValue(current())), attachments: attachments() }); afterSubmit(); };
   const handleSuggestionClick = (v: string) => {
     if ((props.suggestionMode ?? 'submit') === 'fill') { handleChange(v); props.onSuggestionClick?.(v); }
-    else { props.onSubmit?.({ value: v, attachments: attachments() }); setAttachments([]); }
+    else { props.onSubmit?.({ value: v, attachments: attachments() }); afterSubmit(); }
   };
   const showHeader = () => !!(props.chatTitle || props.models || props.context || props.headerStart || props.headerEnd);
   // Suggestions are conversation starters: show only on an empty thread unless
@@ -128,112 +176,173 @@ export function ChatThread(props: ChatThreadProps) {
     props.persistSuggestions || props.messages.length === 0 ? props.suggestions : undefined;
   const showScrollButton = () => props.scrollButton !== false;
 
+  // Hand the imperative controller to the facade once mounted (rootEl is set).
+  onMount(() => {
+    props.controllerRef?.({
+      focus: (options) =>
+        rootEl
+          ?.querySelector<HTMLElement>('[contenteditable]:not([contenteditable="false"]), textarea')
+          ?.focus(options),
+      clear: () => { setInternal(''); setAttachments([]); props.onValueChange?.(''); },
+      send: () => handleSubmit(),
+      scrollToBottom: (behavior) => {
+        const vp = rootEl?.querySelector<HTMLElement>('.overflow-y-auto');
+        vp?.scrollTo({ top: vp.scrollHeight, behavior: behavior ?? 'smooth' });
+      },
+    });
+  });
+
   return (
     <ChatConfig proseSize={props.proseSize} codeTheme={props.codeTheme} codeHighlight={props.codeHighlight !== false} portalMount={outer.portalMount()}>
-      <div ref={(e) => (rootEl = e as HTMLElement)} class={`flex h-full flex-col bg-background ${props.class ?? ''}`}>
-        <Show when={showHeader()}>
-          <header class="flex h-14 shrink-0 items-center justify-between border-b border-border px-5">
-            <div class="flex items-center gap-2">
-              {/* Consumer-injected leading controls (sidebar-toggle, compose, a
-                  popover title-button). Projects light-DOM `slot="header-start"`
-                  children of <kai-chat>; inert outside a shadow root. */}
-              <slot name="header-start" />
-              <Show when={props.chatTitle}>
-                <div class="text-sm font-semibold text-foreground">{props.chatTitle}</div>
+      {/* The root is a ROW so a `sidebar` slot can sit beside the main column.
+          With no sidebar projected it collapses to the original column. */}
+      <div ref={(e) => (rootEl = e as HTMLElement)} class={`flex h-full bg-background ${props.class ?? ''}`}>
+        <Show when={props.sidebar}>
+          <aside part="sidebar" class="flex w-64 shrink-0 flex-col overflow-hidden border-r border-border">
+            <slot name="sidebar" />
+          </aside>
+        </Show>
+        <div class="flex h-full min-w-0 flex-1 flex-col">
+          {/* Header: a full `header` slot REPLACES the built-in bar; otherwise the
+              built-in header renders, itself carrying the header-start/header-end
+              INJECT slots. */}
+          <Show
+            when={props.headerFull}
+            fallback={
+              <Show when={showHeader()}>
+                <header part="header-bar" class="flex h-14 shrink-0 items-center justify-between border-b border-border px-5">
+                  <div class="flex items-center gap-2">
+                    {/* Consumer-injected leading controls (sidebar-toggle, compose, a
+                        popover title-button). Projects light-DOM `slot="header-start"`
+                        children of <kai-chat>; inert outside a shadow root. */}
+                    <slot name="header-start" />
+                    <Show when={props.chatTitle}>
+                      <div class="text-sm font-semibold text-foreground">{props.chatTitle}</div>
+                    </Show>
+                  </div>
+                  <div class="flex items-center gap-2">
+                    <Show when={props.models}>
+                      <ModelSwitcher
+                        models={props.models!}
+                        currentModelId={props.currentModel ?? props.models![0]?.id ?? ''}
+                        onModelChange={(modelId) => props.onModelChange?.(modelId)}
+                      />
+                    </Show>
+                    <Show when={props.context}>
+                      <Context
+                        usedTokens={props.context!.usedTokens} maxTokens={props.context!.maxTokens}
+                        inputTokens={props.context!.inputTokens} outputTokens={props.context!.outputTokens}
+                        estimatedCost={props.context!.estimatedCost}
+                      >
+                        <ContextTrigger />
+                        <ContextContent>
+                          <ContextContentHeader />
+                          <ContextContentBody><div class="space-y-1.5"><ContextInputUsage /><ContextOutputUsage /></div></ContextContentBody>
+                          <ContextContentFooter />
+                        </ContextContent>
+                      </Context>
+                    </Show>
+                    {/* Consumer-injected trailing controls (share, settings, …).
+                        Projects light-DOM `slot="header-end"` children of <kai-chat>. */}
+                    <slot name="header-end" />
+                  </div>
+                </header>
               </Show>
-            </div>
-            <div class="flex items-center gap-2">
-              <Show when={props.models}>
-                <ModelSwitcher
-                  models={props.models!}
-                  currentModelId={props.currentModel ?? props.models![0]?.id ?? ''}
-                  onModelChange={(modelId) => props.onModelChange?.(modelId)}
-                />
+            }
+          >
+            <header part="header" class="shrink-0"><slot name="header" /></header>
+          </Show>
+          <div class="relative flex-1 overflow-hidden">
+            <ChatContainer class="h-full px-4 py-3">
+              <ChatContainerContent class="mx-auto w-full max-w-3xl space-y-4">
+                {/* REPLACE — custom empty-state slot, shown only while the thread is
+                    empty. The component still owns WHEN it shows (data state); the
+                    consumer owns WHAT it looks like. */}
+                <Show when={props.empty && props.messages.length === 0}>
+                  <slot name="empty" />
+                </Show>
+                <For each={props.messages}>
+                  {(m) => {
+                    const body = (
+                      <MessageBody
+                        content={m.content}
+                        reasoning={m.reasoning}
+                        tools={m.tools}
+                        attachments={m.attachments}
+                        isUser={m.role === 'user'}
+                        markdown={m.role === 'assistant'}
+                        actions={m.actions}
+                        actionsReveal={reveal()}
+                        activeFeedback={feedback.resolveFeedback(m)}
+                        copied={feedback.isCopied(m.id)}
+                        onAction={(action) => feedback.handleAction(m, action)}
+                      />
+                    );
+                    const rowGroup = reveal() === 'hover' ? 'group ' : '';
+                    return (
+                      <Show
+                        when={m.avatar}
+                        fallback={
+                          <Message class={`${rowGroup}${m.role === 'user' ? 'flex-col items-end' : 'flex-col items-start'}`}>
+                            {body}
+                          </Message>
+                        }
+                      >
+                        {(av) => (
+                          <Message 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'}`}>
+                              {body}
+                            </div>
+                          </Message>
+                        )}
+                      </Show>
+                    );
+                  }}
+                </For>
+                <ChatContainerScrollAnchor />
+              </ChatContainerContent>
+              <Show when={showScrollButton()}>
+                <div class="absolute bottom-4 left-1/2 flex w-full max-w-3xl -translate-x-1/2 justify-center px-5">
+                  <ScrollButton class="shadow-sm" />
+                </div>
               </Show>
-              <Show when={props.context}>
-                <Context
-                  usedTokens={props.context!.usedTokens} maxTokens={props.context!.maxTokens}
-                  inputTokens={props.context!.inputTokens} outputTokens={props.context!.outputTokens}
-                  estimatedCost={props.context!.estimatedCost}
-                >
-                  <ContextTrigger />
-                  <ContextContent>
-                    <ContextContentHeader />
-                    <ContextContentBody><div class="space-y-1.5"><ContextInputUsage /><ContextOutputUsage /></div></ContextContentBody>
-                    <ContextContentFooter />
-                  </ContextContent>
-                </Context>
+            </ChatContainer>
+          </div>
+          {/* INJECT — accessory row above the composer (extra actions/toolbar). */}
+          <Show when={props.composerActions}>
+            <div class="shrink-0 px-4">
+              <div class="mx-auto flex max-w-3xl items-center gap-2 pb-2"><slot name="composer-actions" /></div>
+            </div>
+          </Show>
+          <div class="shrink-0 px-4 pb-4">
+            <div class="mx-auto max-w-3xl">
+              {/* REPLACE — a full `composer` slot stands in for the built-in input.
+                  The slotted content owns its own submit/loading wiring. */}
+              <Show
+                when={props.composer}
+                fallback={
+                  <DefaultPromptInput
+                    value={current()} placeholder={props.placeholder} loading={props.loading === true}
+                    suggestions={visibleSuggestions()} attachments={attachments()}
+                    search={props.search === 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?.()}
+                  />
+                }
+              >
+                <slot name="composer" />
               </Show>
-              {/* Consumer-injected trailing controls (share, settings, …).
-                  Projects light-DOM `slot="header-end"` children of <kai-chat>. */}
-              <slot name="header-end" />
             </div>
-          </header>
-        </Show>
-        <div class="relative flex-1 overflow-hidden">
-          <ChatContainer class="h-full px-4 py-3">
-            <ChatContainerContent class="mx-auto w-full max-w-3xl space-y-4">
-              <For each={props.messages}>
-                {(m) => {
-                  const body = (
-                    <MessageBody
-                      content={m.content}
-                      reasoning={m.reasoning}
-                      tools={m.tools}
-                      attachments={m.attachments}
-                      isUser={m.role === 'user'}
-                      markdown={m.role === 'assistant'}
-                      actions={m.actions}
-                      actionsReveal={reveal()}
-                      activeFeedback={feedback.resolveFeedback(m)}
-                      copied={feedback.isCopied(m.id)}
-                      onAction={(action) => feedback.handleAction(m, action)}
-                    />
-                  );
-                  const rowGroup = reveal() === 'hover' ? 'group ' : '';
-                  return (
-                    <Show
-                      when={m.avatar}
-                      fallback={
-                        <Message class={`${rowGroup}${m.role === 'user' ? 'flex-col items-end' : 'flex-col items-start'}`}>
-                          {body}
-                        </Message>
-                      }
-                    >
-                      {(av) => (
-                        <Message 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'}`}>
-                            {body}
-                          </div>
-                        </Message>
-                      )}
-                    </Show>
-                  );
-                }}
-              </For>
-              <ChatContainerScrollAnchor />
-            </ChatContainerContent>
-            <Show when={showScrollButton()}>
-              <div class="absolute bottom-4 left-1/2 flex w-full max-w-3xl -translate-x-1/2 justify-center px-5">
-                <ScrollButton class="shadow-sm" />
-              </div>
-            </Show>
-          </ChatContainer>
-        </div>
-        <div class="shrink-0 px-4 pb-4">
-          <div class="mx-auto max-w-3xl">
-            <DefaultPromptInput
-              value={current()} placeholder={props.placeholder} loading={props.loading === true}
-              suggestions={visibleSuggestions()} attachments={attachments()}
-              search={props.search === true} voice={props.voice === true}
-              slashCommands={props.slashCommands} slashActiveIds={props.slashActiveIds} slashCompact={props.slashCompact === true}
-              onValueChange={handleChange} onSubmit={handleSubmit} onSuggestionClick={handleSuggestionClick}
-              onAttachmentsChange={setAttachments}
-              onSearch={() => props.onSearch?.()} onVoice={() => props.onVoice?.()}
-              onSlashSelect={(command) => props.onSlashSelect?.(command)}
-            />
           </div>
+          {/* INJECT — footer row below the composer. */}
+          <Show when={props.footer}>
+            <div part="footer" class="shrink-0 px-4 pb-3">
+              <div class="mx-auto max-w-3xl text-center text-xs text-muted-foreground"><slot name="footer" /></div>
+            </div>
+          </Show>
         </div>
       </div>
     </ChatConfig>

package/src/components/choice-card.tsx

@@ -8,6 +8,7 @@ import {
   createMemo,
   createEffect,
   on,
+  onMount,
   ErrorBoundary,
   createUniqueId,
 } from 'solid-js';
@@ -151,6 +152,22 @@ export function firstEnabledIndex(options: ChoiceOption[]): number {
 // The <ChoiceCard> component.
 // ─────────────────────────────────────────────────────────────────────────────
 
+/** Imperative handle exposed via `controllerRef` — surfaces the choice card's
+ *  latent selection/submit/dismiss capabilities so the `<kai-choice>` facade can
+ *  forward them as instance methods (focus/select/send/dismiss/reopen). */
+export interface ChoiceController {
+  /** Focus the radiogroup roving tab stop (or the Other input when selected). */
+  focus(options?: FocusOptions): void;
+  /** Select an option by id locally (no emit) — same as a row click. */
+  select(optionId: string): void;
+  /** Submit the current selection — emits the `action` verb + resolves single-shot. */
+  send(): void;
+  /** Dismiss the card — emits `dismiss` + optimistically collapses to the stub. */
+  dismiss(): void;
+  /** Re-open a dismissed card from its stub — emits `reopen`. */
+  reopen(): void;
+}
+
 export interface ChoiceCardProps {
   /** The choice definition (CardEnvelope.data). */
   data?: ChoiceCardData;
@@ -166,6 +183,17 @@ export interface ChoiceCardProps {
   class?: string;
   /** When set, render the chromed read-only view instead of the interactive radiogroup. */
   resolution?: CardResolution;
+  /** Controlled selection (option id). When set, the consumer owns the current pick. */
+  value?: string;
+  /** Option id to pre-select on mount (uncontrolled seed). */
+  defaultValue?: string;
+  /** Disable the whole radiogroup + Submit (e.g. while the agent is busy). */
+  disabled?: boolean;
+  /** Fires when the selection changes BEFORE submit (row click or select()). */
+  onValueChange?: (value: string) => void;
+  /** Receive the imperative controller once mounted. The `<kai-choice>` facade
+   *  forwards these as element methods (focus/select/send/dismiss/reopen). */
+  controllerRef?: (controller: ChoiceController) => void;
 }
 
 /**
@@ -182,7 +210,20 @@ export interface ChoiceCardProps {
  */
 export function ChoiceCard(props: ChoiceCardProps): JSX.Element {
   const merged = mergeProps({ cardId: 'kai-choice' }, props);
-  const [local] = splitProps(merged, ['data', 'cardId', 'heading', 'host', 'hostElement', 'class', 'resolution']);
+  const [local] = splitProps(merged, [
+    'data',
+    'cardId',
+    'heading',
+    'host',
+    'hostElement',
+    'class',
+    'resolution',
+    'value',
+    'defaultValue',
+    'disabled',
+    'onValueChange',
+    'controllerRef',
+  ]);
 
   const ctxHost = useCardHost();
   const uid = createUniqueId();
@@ -214,20 +255,33 @@ export function ChoiceCard(props: ChoiceCardProps): JSX.Element {
   });
 
   const [focusIndex, setFocusIndex] = createSignal(0);
-  const [selectedId, setSelectedId] = createSignal<string | undefined>(undefined);
+  // Uncontrolled selection store, seeded from `defaultValue`. When the consumer
+  // sets the `value` prop the controlled path wins (same pattern as the composer):
+  // `selectedId()` reads value ?? internal, and `setSelection()` writes the
+  // internal store + fires onValueChange so a controlled host can mirror it.
+  const [internalId, setInternalId] = createSignal<string | undefined>(props.defaultValue);
+  const selectedId = createMemo<string | undefined>(() => local.value ?? internalId());
+  const setSelection = (id: string): void => {
+    if (selectedId() === id) return;
+    setInternalId(id);
+    local.onValueChange?.(id);
+  };
   const [otherText, setOtherText] = createSignal('');
 
+  const isDisabled = (): boolean => local.disabled === true;
+
   let groupRef: HTMLDivElement | undefined;
   let otherInputRef: HTMLInputElement | undefined;
 
   const otherSelected = createMemo(() => selectedId() === OTHER_ACTION);
 
-  // Reset all transient state whenever a NEW definition arrives.
+  // Reset all transient state whenever a NEW definition arrives (re-seed the
+  // uncontrolled selection from `defaultValue`).
   createEffect(
     on(
       () => local.data,
       () => {
-        setSelectedId(undefined);
+        setInternalId(local.defaultValue);
         setOtherText('');
         setFocusIndex(Math.max(0, firstEnabledIndex(options())));
       },
@@ -264,11 +318,12 @@ export function ChoiceCard(props: ChoiceCardProps): JSX.Element {
 
   const isOther = (opt: ChoiceOption): boolean => opt.id === OTHER_ACTION;
 
-  // Select (do NOT emit) the given option locally.
+  // Select (do NOT emit) the given option locally; fires onValueChange.
   const select = (opt: ChoiceOption): void => {
     if (res.isResolved()) return; // single-shot
+    if (isDisabled()) return; // group-level freeze
     if (opt.disabled) return;
-    setSelectedId(opt.id);
+    setSelection(opt.id);
     if (isOther(opt)) {
       queueMicrotask(() => otherInputRef?.focus());
     }
@@ -277,6 +332,7 @@ export function ChoiceCard(props: ChoiceCardProps): JSX.Element {
   // Whether the current selection is submittable.
   const canSubmit = createMemo(() => {
     if (res.isResolved()) return false;
+    if (isDisabled()) return false; // group-level freeze
     const id = selectedId();
     if (id === undefined) return false;
     if (id === OTHER_ACTION) return otherText().trim().length > 0;
@@ -288,6 +344,7 @@ export function ChoiceCard(props: ChoiceCardProps): JSX.Element {
   // Submit the current selection: emit `action` then resolve (single-shot).
   const submit = (): void => {
     if (res.isResolved()) return;
+    if (isDisabled()) return; // group-level freeze
     const id = selectedId();
     if (id === undefined) return;
     if (id === OTHER_ACTION) {
@@ -321,13 +378,43 @@ export function ChoiceCard(props: ChoiceCardProps): JSX.Element {
   };
   const onReopen = (): void => emit({ kind: 'reopen', cardId: local.cardId });
 
-  const focusRadio = (index: number): void => {
+  const focusRadio = (index: number, options?: FocusOptions): void => {
     const radios = groupRef?.querySelectorAll<HTMLElement>('[role="radio"]');
-    radios?.[index]?.focus();
+    radios?.[index]?.focus(options);
   };
 
+  // ── Imperative controller (Pattern C): hand the facade a handle over the
+  //    card's latent selection/submit/dismiss capabilities. Every method drives
+  //    the SAME internal path the buttons/keyboard drive, so the same kai-card
+  //    events fire (and onValueChange for select()). ─────────────────────────────
+  onMount(() => {
+    local.controllerRef?.({
+      // Focus the roving radiogroup tab stop, or the Other input when it's selected.
+      focus: (options) => {
+        if (otherSelected() && otherInputRef) otherInputRef.focus(options);
+        else focusRadio(focusIndex(), options);
+      },
+      // Select an option by id locally (no emit) — same as a row click; respects
+      // disabled/resolved gating and moves the roving focus to the picked row.
+      select: (optionId) => {
+        const opts = options();
+        const idx = opts.findIndex((o) => o.id === optionId);
+        if (idx === -1) return;
+        setFocusIndex(idx);
+        select(opts[idx]);
+      },
+      // Submit the current selection (the Submit-button path).
+      send: () => submit(),
+      // Trigger the dismiss path (the X-button path).
+      dismiss: () => onDismiss(),
+      // Re-open a dismissed card (the stub's affordance path).
+      reopen: () => onReopen(),
+    });
+  });
+
   const onGroupKeyDown = (e: KeyboardEvent): void => {
     if (res.isResolved()) return;
+    if (isDisabled()) return; // group-level freeze
     const opts = options();
     const i = focusIndex();
     if (e.key === 'ArrowDown' || e.key === 'ArrowRight') {
@@ -385,14 +472,18 @@ export function ChoiceCard(props: ChoiceCardProps): JSX.Element {
                 role="radiogroup"
                 aria-label={groupLabel()}
                 aria-describedby={local.data?.prompt ? promptId : undefined}
-                class="divide-y divide-border overflow-hidden rounded-lg border border-input"
+                aria-disabled={isDisabled() ? 'true' : undefined}
+                class={cn(
+                  'divide-y divide-border overflow-hidden rounded-lg border border-input',
+                  isDisabled() && 'cursor-not-allowed opacity-60',
+                )}
                 onKeyDown={onGroupKeyDown}
               >
                 <For each={options()}>
                   {(opt, index) => {
                     const checked = () => selectedId() === opt.id;
                     const tabStop = () =>
-                      !opt.disabled && index() === focusIndex() && !res.isResolved();
+                      !opt.disabled && !isDisabled() && index() === focusIndex() && !res.isResolved();
                     const descId = `kai-choice-desc-${uid}-${opt.id}`;
                     const hasDesc = () => Boolean(opt.description);
                     return (
@@ -422,7 +513,8 @@ export function ChoiceCard(props: ChoiceCardProps): JSX.Element {
                     id={otherInputId}
                     ref={otherInputRef}
                     type="text"
-                    class="w-full rounded-md border border-input bg-background px-3 py-2 text-sm text-foreground placeholder:text-muted-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring"
+                    disabled={isDisabled()}
+                    class="w-full rounded-md border border-input bg-background px-3 py-2 text-sm text-foreground placeholder:text-muted-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring disabled:cursor-not-allowed disabled:opacity-60"
                     placeholder={otherCfg()?.placeholder}
                     value={otherText()}
                     onInput={(e) => setOtherText(e.currentTarget.value)}