@kitn.ai/ui 0.17.0 → 0.18.1

package/src/elements/chat-workspace.tsx

@@ -1,13 +1,12 @@
-import { Show } from 'solid-js';
+import { Show, createSignal, onMount, onCleanup } from 'solid-js';
 import { defineWebComponent } from './define';
 import { createControllableSignal } from '../primitives/controllable';
-import { ChatThread, type ChatThreadContextUsage } from '../components/chat-thread';
-import { ConversationList } from '../components/conversation-list';
+import { readSlots, WORKSPACE_SLOTS } from './slots';
+import { ChatThread, type ChatThreadContextUsage, type ChatThreadController } from '../components/chat-thread';
+import { ConversationList, CollapsedRail } from '../components/conversation-list';
 import { ResizablePanelGroup, ResizablePanel, ResizableHandle } from '../ui/resizable';
-import { Button } from '../ui/button';
-import { PanelLeftOpen } from 'lucide-solid';
 import type { AttachmentData } from '../components/attachments';
-import type { SlashCommandItem } from '../components/slash-command';
+import type { TriggerDef } from '../components/composer';
 import type { ChatMessage } from './chat-types';
 import type { ProseSize } from '../primitives/chat-config';
 import type { ModelOption, ConversationGroup, ConversationSummary } from '../types';
@@ -36,12 +35,13 @@ interface Props extends Record<string, unknown> {
   scrollButton?: boolean;
   search?: boolean;
   voice?: boolean;
-  slashCommands?: SlashCommandItem[];
-  slashActiveIds?: string[];
-  slashCompact?: boolean;
-  /** Sidebar default width as a percent of the workspace (default 22). */
+  /** Rich entity triggers (`/` skills, `@` agents/plugins) forwarded to the input. */
+  triggers?: TriggerDef[];
+  /** Default icon per entity kind (kind → image src) forwarded to the input. */
+  kindIcons?: Record<string, string>;
+  /** Sidebar default width as a percent of the workspace (default 26). */
   sidebarWidth?: number;
-  /** Sidebar min width in px (default 200). */
+  /** Sidebar min width in px (default 240). */
   sidebarMinWidth?: number;
   /** Sidebar max width in px (default 420). */
   sidebarMaxWidth?: number;
@@ -52,6 +52,17 @@ interface Props extends Record<string, unknown> {
   /** Initial collapsed state when uncontrolled (default false). Use the
    *  `default-sidebar-collapsed` attribute to start collapsed in plain HTML. */
   defaultSidebarCollapsed?: boolean;
+  /** Auto-collapse the rail when the workspace's own width drops below this many
+   *  px, and re-expand when it grows back above. Uncontrolled only (it never
+   *  fights an app-driven `sidebarCollapsed`); omit to disable. Fires
+   *  `kai-sidebar-toggle`. Attribute: `collapse-below`. */
+  collapseBelow?: number;
+  /** Render Recents as dense single-line rows (a leading dot + title, no count). */
+  compact?: boolean;
+  /** Suppress the built-in ConversationList so the `sidebar-header` slot owns the
+   *  whole rail flex region (for apps that supply their own rail nav). Default
+   *  false. Attribute: `no-conversations`. */
+  noConversations?: boolean;
 }
 
 interface Events {
@@ -75,8 +86,6 @@ interface Events {
   'kai-search': Record<string, never>;
   /** The Mic / voice button was clicked. */
   'kai-voice': Record<string, never>;
-  /** A slash command was chosen from the palette. */
-  'kai-slash-select': { command: SlashCommandItem };
   /** A suggestion chip was clicked (only in `suggestion-mode="fill"`). */
   'kai-suggestion-click': { value: string };
 }
@@ -87,20 +96,83 @@ defineWebComponent<Props, Events>('kai-workspace', {
   suggestions: undefined, suggestionMode: 'submit', proseSize: 'sm',
   codeTheme: 'github-dark-dimmed', codeHighlight: true, chatTitle: undefined,
   models: undefined, currentModel: undefined, context: undefined, scrollButton: true,
-  search: false, voice: false, slashCommands: undefined, slashActiveIds: undefined, slashCompact: false,
-  sidebarWidth: 22, sidebarMinWidth: 200, sidebarMaxWidth: 420,
-  sidebarCollapsed: undefined, defaultSidebarCollapsed: undefined,
-}, (props, { dispatch, flag }) => {
+  search: false, voice: false, triggers: undefined, kindIcons: undefined,
+  sidebarWidth: 26, sidebarMinWidth: 240, sidebarMaxWidth: 420,
+  sidebarCollapsed: undefined, defaultSidebarCollapsed: undefined, collapseBelow: undefined, compact: undefined,
+  noConversations: undefined,
+}, (props, { dispatch, flag, expose, element }) => {
+  // Which injection slots the consumer has filled. A bare <slot> is always a
+  // truthy JSX node, so we render each region wrapper ONLY when readSlots reports
+  // projected light-DOM content (re-read on childList mutation).
+  const [slots, setSlots] = createSignal<Record<string, boolean>>({});
+  onMount(() => {
+    const read = () => setSlots(readSlots(element, WORKSPACE_SLOTS));
+    read();
+    const observer = new MutationObserver(read);
+    observer.observe(element, { childList: true });
+    onCleanup(() => observer.disconnect());
+  });
+
   // Controlled/uncontrolled collapse: `sidebarCollapsed` (when set) wins;
   // otherwise the element manages its own state, seeded from
-  // `defaultSidebarCollapsed`. `toggle` always writes the internal value (a no-op
-  // visually while controlled) and emits `kai-sidebar-toggle` so a controlling app
-  // can update its own state.
+  // `defaultSidebarCollapsed`. `setCollapsedTo` always writes the internal value (a
+  // no-op visually while controlled) and emits `kai-sidebar-toggle` so a controlling
+  // app can update its own state.
   const [collapsed, setCollapsed] = createControllableSignal(
     () => props.sidebarCollapsed as boolean | undefined,
     flag('defaultSidebarCollapsed'),
   );
-  const toggle = () => { const next = !collapsed(); setCollapsed(next); dispatch('kai-sidebar-toggle', { collapsed: next }); };
+  const setCollapsedTo = (next: boolean) => { setCollapsed(next); dispatch('kai-sidebar-toggle', { collapsed: next }); };
+  const toggle = () => setCollapsedTo(!collapsed());
+
+  // Responsive auto-collapse. When `collapseBelow` is set, a ResizeObserver on the
+  // workspace root collapses the rail once the workspace's own width drops below
+  // it and re-expands above it. Uncontrolled only — bail while `sidebarCollapsed`
+  // is set so we never fight an app-driven collapse. `autoCollapsed` tracks whether
+  // WE collapsed it, so a user's manual expand isn't auto-undone on the next tick.
+  let rootEl!: HTMLDivElement;
+  let autoCollapsed = false;
+  onMount(() => {
+    if (typeof ResizeObserver === 'undefined') return;
+    const ro = new ResizeObserver((entries) => {
+      const below = props.collapseBelow as number | undefined;
+      if (below == null || props.sidebarCollapsed !== undefined) return;
+      const width = entries[0]?.contentRect.width ?? rootEl.clientWidth;
+      const isBelow = width < below;
+      if (isBelow && !collapsed()) {
+        autoCollapsed = true;
+        setCollapsedTo(true);
+      } else if (!isBelow && collapsed() && autoCollapsed) {
+        autoCollapsed = false;
+        setCollapsedTo(false);
+      }
+    });
+    ro.observe(rootEl);
+    onCleanup(() => ro.disconnect());
+  });
+
+  // Imperative method API. The sidebar methods drive the same collapse path as the
+  // in-UI toggle (named *Sidebar to avoid the `sidebarCollapsed` prop accessor).
+  // The thread methods delegate to the embedded ChatThread's controller, captured
+  // once below — the thread node is shared across both <Show> branches, so a single
+  // controllerRef is stable across collapse/expand.
+  let controller: ChatThreadController | undefined;
+  expose({
+    /** Collapse/expand the conversation sidebar and fire `kai-sidebar-toggle`. */
+    toggleSidebar: () => toggle(),
+    /** Force the conversation sidebar collapsed (fires `kai-sidebar-toggle`). */
+    collapseSidebar: () => setCollapsedTo(true),
+    /** Force the conversation sidebar expanded (fires `kai-sidebar-toggle`). */
+    expandSidebar: () => setCollapsedTo(false),
+    /** Focus the thread's composer. */
+    focus: (options?: FocusOptions) => controller?.focus(options),
+    /** Clear the thread draft + staged attachments. */
+    clear: () => controller?.clear(),
+    /** Submit the current thread draft programmatically (fires `kai-submit`). */
+    send: () => controller?.send(),
+    /** Scroll the thread to the newest message. */
+    scrollToBottom: (behavior?: ScrollBehavior) => controller?.scrollToBottom(behavior),
+  });
 
   // Create the thread ONCE and reference the same node in both <Show> branches.
   // It's owned by this component root (not by a Show branch), so toggling the
@@ -115,8 +187,8 @@ defineWebComponent<Props, Events>('kai-workspace', {
       chatTitle={props.chatTitle as string | undefined} models={props.models as ModelOption[] | undefined}
       currentModel={props.currentModel as string | undefined} context={props.context as ChatThreadContextUsage | undefined}
       scrollButton={props.scrollButton !== false} search={flag('search')} voice={flag('voice')}
-      slashCommands={props.slashCommands as SlashCommandItem[] | undefined}
-      slashActiveIds={props.slashActiveIds as string[] | undefined} slashCompact={flag('slashCompact')}
+      triggers={props.triggers as TriggerDef[] | undefined}
+      kindIcons={props.kindIcons as Record<string, string> | undefined}
       onValueChange={(value) => dispatch('kai-value-change', { value })}
       onSubmit={(detail) => dispatch('kai-submit', detail)}
       onSuggestionClick={(value) => dispatch('kai-suggestion-click', { value })}
@@ -124,38 +196,78 @@ defineWebComponent<Props, Events>('kai-workspace', {
       onMessageAction={(detail) => dispatch('kai-message-action', detail)}
       onSearch={() => dispatch('kai-search', {})}
       onVoice={() => dispatch('kai-voice', {})}
-      onSlashSelect={(command) => dispatch('kai-slash-select', { command })}
+      controllerRef={(c) => (controller = c)}
     />
   );
 
+  // The main region: an optional top-placed `main-header` band above the thread.
+  // Shared across both collapse branches (the thread node is the same instance).
+  const mainRegion = (
+    <div class="flex h-full flex-col overflow-hidden">
+      <Show when={slots()['main-header']}>
+        <div class="shrink-0 border-b border-border"><slot name="main-header" /></div>
+      </Show>
+      <div class="min-h-0 flex-1">
+        <Show when={slots()['main']} fallback={threadEl}>
+          <slot name="main" />
+        </Show>
+      </div>
+    </div>
+  );
+
   return (
-    <div class="h-full w-full overflow-hidden bg-background">
+    <div ref={rootEl} class="h-full w-full overflow-hidden bg-background">
       <Show
         when={!collapsed()}
         fallback={
-          <div class="relative h-full">
-            <Button
-              variant="ghost" size="icon-sm" aria-label="Open sidebar"
-              class="absolute left-2 top-2 z-10 rounded-full bg-card/80 shadow-sm backdrop-blur"
-              onClick={toggle}
-            >
-              <PanelLeftOpen class="size-4" />
-            </Button>
-            {threadEl}
+          <div class="flex h-full">
+            {/* Collapsed: the reopen control lives in its OWN thin rail column
+                (matching the sidebar's bg-surface) rather than floating over the
+                content. The previous `absolute` overlay sat on top of a
+                `main-header`'s leading title — see the t3code/codex/chatgpt apps,
+                all of which fill that slot — so it both overlapped the header and
+                competed with any in-header toggle. A dedicated column never
+                overlaps and reads as a collapsed sidebar. */}
+            <div class="flex w-11 shrink-0 flex-col items-center border-r border-border bg-surface pt-2.5">
+              <CollapsedRail onExpand={toggle} class="bg-transparent shadow-none backdrop-blur-none" />
+            </div>
+            <div class="min-w-0 flex-1">{mainRegion}</div>
           </div>
         }
       >
         <ResizablePanelGroup orientation="horizontal">
           <ResizablePanel defaultSize={props.sidebarWidth as number} data-min-size={String(props.sidebarMinWidth)} data-max-size={String(props.sidebarMaxWidth)}>
-            <ConversationList
-              groups={props.groups} conversations={props.conversations} activeId={props.activeId as string | undefined}
-              onSelect={(id) => dispatch('kai-conversation-select', { id })}
-              onNewChat={() => dispatch('kai-new-chat', {})}
-              onToggleSidebar={toggle}
-            />
+            {/* The rail: an optional injected header above the list and footer
+                below it (upgrade card / Design trigger / user menu). Carries a
+                subtle, theme-aware default background (bg-surface), exposed as
+                ::part(sidebar) so a consumer can override it. The inner list is
+                made transparent so the part background reads uniformly. */}
+            <div part="sidebar" class="flex h-full flex-col overflow-hidden bg-surface">
+              <Show when={slots()['sidebar-header']}>
+                {/* When `no-conversations` suppresses the built-in list, the
+                    projected header owns the whole rail flex region; otherwise it
+                    sits as a fixed band above the list. */}
+                <div class={flag('noConversations') ? 'min-h-0 flex-1' : 'shrink-0'}><slot name="sidebar-header" /></div>
+              </Show>
+              <Show when={!flag('noConversations')}>
+                <div class="min-h-0 flex-1">
+                  <ConversationList
+                    class="bg-transparent"
+                    groups={props.groups} conversations={props.conversations} activeId={props.activeId as string | undefined}
+                    compact={flag('compact')}
+                    onSelect={(id) => dispatch('kai-conversation-select', { id })}
+                    onNewChat={() => dispatch('kai-new-chat', {})}
+                    onToggleSidebar={toggle}
+                  />
+                </div>
+              </Show>
+              <Show when={slots()['sidebar-footer']}>
+                <div class="shrink-0"><slot name="sidebar-footer" /></div>
+              </Show>
+            </div>
           </ResizablePanel>
           <ResizableHandle withHandle />
-          <ResizablePanel>{threadEl}</ResizablePanel>
+          <ResizablePanel>{mainRegion}</ResizablePanel>
         </ResizablePanelGroup>
       </Show>
     </div>

package/src/elements/chat.tsx

@@ -1,20 +1,25 @@
-import { createSignal, onCleanup, onMount } from 'solid-js';
+import { createEffect, createSignal, onCleanup, onMount } from 'solid-js';
 import { defineWebComponent } from './define';
-import { ChatThread, type ChatThreadProps, type ChatThreadContextUsage } from '../components/chat-thread';
+import { CHAT_SLOTS, readSlots } from './slots';
+import { ChatThread, type ChatThreadProps, type ChatThreadContextUsage, type ChatThreadController } from '../components/chat-thread';
 import type { AttachmentData } from '../components/attachments';
-import type { SlashCommandItem } from '../components/slash-command';
+import type { TriggerDef } from '../components/composer';
+import type { ComposerDoc } from '../primitives/composer-model';
 import type { ProseSize } from '../primitives/chat-config';
 import type { ModelOption } from '../types';
 
 type Props = Omit<ChatThreadProps,
-  'class' | 'onValueChange' | 'onSubmit' | 'onSuggestionClick' | 'onModelChange'
-  | 'onMessageAction' | 'onSearch' | 'onVoice' | 'onSlashSelect'> & Record<string, unknown>;
+  'class' | 'onValueChange' | 'onSubmit' | 'onAttachmentsChange' | 'onSuggestionClick' | 'onModelChange'
+  | 'onMessageAction' | 'onSearch' | 'onVoice' | 'controllerRef'> & Record<string, unknown>;
 
 interface Events {
   /** User submitted a message. */
   'kai-submit': { value: string; attachments: AttachmentData[] };
   /** Fired on every input change. */
   'kai-value-change': { value: string };
+  /** The staged attachments changed (file added or removed). Carries the full
+   *  current list so a consumer can react in real time. */
+  'kai-attachments-change': { attachments: AttachmentData[] };
   /** A suggestion chip was clicked (only in `suggestion-mode="fill"`). */
   'kai-suggestion-click': { value: string };
   /** An action button on a message was clicked. `action` is the built-in name or
@@ -23,8 +28,6 @@ interface Events {
   'kai-message-action': { messageId: string; action: string; state?: 'on' | 'off' };
   /** The header model switcher changed. */
   'kai-model-change': { modelId: string };
-  /** A slash command was chosen from the palette. */
-  'kai-slash-select': { command: SlashCommandItem };
   /** The Search button was clicked. */
   'kai-search': Record<string, never>;
   /** The Mic / voice button was clicked. */
@@ -36,27 +39,39 @@ defineWebComponent<Props, Events>('kai-chat', {
   suggestions: undefined, suggestionMode: 'submit', persistSuggestions: false, proseSize: 'sm',
   codeTheme: 'github-dark-dimmed', codeHighlight: true, chatTitle: undefined,
   models: undefined, currentModel: undefined, context: undefined, scrollButton: true,
-  search: false, voice: false, slashCommands: undefined, slashActiveIds: undefined, slashCompact: false,
+  search: false, voice: false, triggers: undefined, kindIcons: undefined,
   actionsReveal: 'always',
-}, (props, { dispatch, flag, element }) => {
-  // Detect consumer-projected header controls so the header opens for them even
-  // without a title/models/context. Mirrors the <kai-model> light-DOM read pattern.
-  const [hasHeaderStart, setHasHeaderStart] = createSignal(false);
-  const [hasHeaderEnd, setHasHeaderEnd] = createSignal(false);
+}, (props, { dispatch, flag, element, expose }) => {
+  // Slot detection is driven by the CHAT_SLOTS registry (single source of truth)
+  // so slot names never drift between the view, the facade, and the docs.
+  const [slots, setSlots] = createSignal<Record<string, boolean>>({});
+  const slot = (name: string) => slots()[name] === true;
   onMount(() => {
-    const read = () => {
-      setHasHeaderStart(!!element.querySelector(':scope > [slot="header-start"]'));
-      setHasHeaderEnd(!!element.querySelector(':scope > [slot="header-end"]'));
-    };
+    const read = () => setSlots(readSlots(element, CHAT_SLOTS));
     read();
     const observer = new MutationObserver(read);
     observer.observe(element, { childList: true });
     onCleanup(() => observer.disconnect());
   });
 
+  // Reflect streaming state to a host attribute so slotted composer/notice CSS
+  // can react without reading internals (e.g. :host([loading]) ::slotted(...)).
+  createEffect(() => { element.toggleAttribute('loading', flag('loading')); });
+
+  // Imperative method API — forward the chat-thread controller onto the host
+  // (focus the composer, clear it, send programmatically, scroll the thread).
+  let controller: ChatThreadController | undefined;
+  expose({
+    focus: (options?: FocusOptions) => controller?.focus(options),
+    blur: () => (element.shadowRoot?.activeElement as HTMLElement | null)?.blur(),
+    clear: () => controller?.clear(),
+    send: () => controller?.send(),
+    scrollToBottom: (behavior?: ScrollBehavior) => controller?.scrollToBottom(behavior),
+  });
+
   return (
   <ChatThread
-    messages={props.messages} value={props.value as string | undefined} placeholder={props.placeholder as string}
+    messages={props.messages} value={props.value as string | ComposerDoc | undefined} placeholder={props.placeholder as string}
     loading={flag('loading')} suggestions={props.suggestions as string[] | undefined}
     suggestionMode={props.suggestionMode as 'submit' | 'fill'} persistSuggestions={flag('persistSuggestions')}
     proseSize={props.proseSize as ProseSize}
@@ -64,19 +79,26 @@ defineWebComponent<Props, Events>('kai-chat', {
     chatTitle={props.chatTitle as string | undefined} models={props.models as ModelOption[] | undefined}
     currentModel={props.currentModel as string | undefined} context={props.context as ChatThreadContextUsage | undefined}
     scrollButton={props.scrollButton !== false} search={flag('search')} voice={flag('voice')}
-    slashCommands={props.slashCommands as SlashCommandItem[] | undefined}
-    slashActiveIds={props.slashActiveIds as string[] | undefined} slashCompact={flag('slashCompact')}
+    triggers={props.triggers as TriggerDef[] | undefined}
+    kindIcons={props.kindIcons as Record<string, string> | undefined}
     actionsReveal={props.actionsReveal as 'always' | 'hover'}
     onValueChange={(value) => dispatch('kai-value-change', { value })}
     onSubmit={(detail) => dispatch('kai-submit', detail)}
+    onAttachmentsChange={(attachments) => dispatch('kai-attachments-change', { attachments })}
     onSuggestionClick={(value) => dispatch('kai-suggestion-click', { value })}
     onModelChange={(modelId) => dispatch('kai-model-change', { modelId })}
     onMessageAction={(detail) => dispatch('kai-message-action', detail)}
     onSearch={() => dispatch('kai-search', {})}
     onVoice={() => dispatch('kai-voice', {})}
-    onSlashSelect={(command) => dispatch('kai-slash-select', { command })}
-    headerStart={hasHeaderStart()}
-    headerEnd={hasHeaderEnd()}
+    controllerRef={(c) => (controller = c)}
+    headerStart={slot('header-start')}
+    headerEnd={slot('header-end')}
+    headerFull={slot('header')}
+    sidebar={slot('sidebar')}
+    empty={slot('empty')}
+    composer={slot('composer')}
+    composerActions={slot('composer-actions')}
+    footer={slot('footer')}
   />
   );
 });

package/src/elements/choice.tsx

@@ -1,5 +1,5 @@
 import { defineWebComponent } from './define';
-import { ChoiceCard, type ChoiceCardData } from '../components/choice-card';
+import { ChoiceCard, type ChoiceCardData, type ChoiceController } from '../components/choice-card';
 import type { CardResolution } from '../primitives/card-contract';
 
 interface Props extends Record<string, unknown> {
@@ -14,35 +14,87 @@ interface Props extends Record<string, unknown> {
   /** Set when the user resolved this card; renders the read-only view. Property:
    *  `el.resolution = { kind:'action', action:'…' }`. */
   resolution?: Record<string, unknown>;
+  /** Controlled selection — the selected option id. When set, the consumer owns
+   *  the current pick (RadioGroup `value`). Attribute: `value`. */
+  value?: string;
+  /** Option id to pre-select on mount (uncontrolled seed). Attribute: `default-value`. */
+  defaultValue?: string;
+  /** Disable the whole radiogroup + Submit (e.g. while the agent is busy).
+   *  Attribute: `disabled`. */
+  disabled?: boolean;
+}
+
+/** Events fired by `<kai-choice>`. (The terminal submit/dismiss/reopen flow is
+ *  emitted via the bubbling `kai-card` contract event — listen for `kai-card`.) */
+interface Events {
+  /** The selection changed BEFORE submit (a row click or the `select()` method).
+   *  Distinct from the terminal `action` verb on the `kai-card` contract event. */
+  'kai-value-change': { value: string };
 }
 
 /**
  * `<kai-choice>` — a single-select **"pick one of N rich options"** card (set via the
  * `data` property): a prompt + a radiogroup of list rows. Clicking a row **selects** it
- * (no emit); the **Submit** button below then emits the Card contract's **`action`** verb
- * up a bubbling **`kai-card`** CustomEvent (`{ kind:'action', cardId, action: option.id,
- * payload? }`) and resolves the card so the same pick can't double-fire. An optional
- * `allowOther` free-text escape appends a selectable "Other…" row that reveals an inline
- * input; the same Submit emits `action:'__other__'` with `{ text }`. Also emits `ready` on
- * mount and `error` for a malformed definition (inline error). Routes through a
- * `CardProvider` when present, else the bubbling `kai-card` event. Isolated in Shadow DOM;
- * theme-aware via the shared tokens.
+ * (no emit, fires `kai-value-change`); the **Submit** button below then emits the Card
+ * contract's **`action`** verb up a bubbling **`kai-card`** CustomEvent (`{ kind:'action',
+ * cardId, action: option.id, payload? }`) and resolves the card so the same pick can't
+ * double-fire. An optional `allowOther` free-text escape appends a selectable "Other…" row
+ * that reveals an inline input; the same Submit emits `action:'__other__'` with `{ text }`.
+ * Also emits `ready` on mount and `error` for a malformed definition (inline error). Routes
+ * through a `CardProvider` when present, else the bubbling `kai-card` event. Isolated in
+ * Shadow DOM; theme-aware via the shared tokens.
+ *
+ * Supports controlled selection (`value`), an uncontrolled seed (`defaultValue`), a
+ * group-level `disabled`, and instance methods `focus()`/`select(id)`/`send()`/
+ * `dismiss()`/`reopen()`.
  */
-defineWebComponent<Props>(
+defineWebComponent<Props, Events>(
   'kai-choice',
   {
     data: undefined,
     cardId: undefined,
     heading: undefined,
     resolution: undefined,
+    value: undefined,
+    defaultValue: undefined,
+    disabled: undefined,
+  },
+  (props, { element, dispatch, flag, expose }) => {
+    // Pattern C: the ChoiceCard owns selection/submit/dismiss state and hands up a
+    // controller; the facade captures it and exposes delegating methods. The card's
+    // own paths still fire (select → kai-value-change; send → kai-card `action`;
+    // dismiss/reopen → kai-card `dismiss`/`reopen`).
+    let controller: ChoiceController | undefined;
+    expose({
+      /** Focus the radiogroup roving tab stop (or the Other input when selected). */
+      focus: (options?: FocusOptions) => controller?.focus(options),
+      /** Select an option by id locally — no emit, fires kai-value-change (same as
+       *  a row click). Lets a consumer pre-highlight or drive selection externally. */
+      select: (optionId: string) => controller?.select(optionId),
+      /** Submit the current selection — emits the `action` verb on kai-card and
+       *  resolves the card (single-shot). Named `send`, not `submit`, per the shared
+       *  vocabulary. */
+      send: () => controller?.send(),
+      /** Trigger the dismiss path — emits `dismiss` on kai-card and optimistically
+       *  collapses the card to its re-openable stub. */
+      dismiss: () => controller?.dismiss(),
+      /** Re-open a dismissed card from its stub — emits `reopen` on kai-card. */
+      reopen: () => controller?.reopen(),
+    });
+
+    return (
+      <ChoiceCard
+        data={props.data as ChoiceCardData | undefined}
+        cardId={props.cardId ?? (element.id || 'kai-choice')}
+        heading={props.heading}
+        resolution={props.resolution as CardResolution | undefined}
+        value={props.value}
+        defaultValue={props.defaultValue}
+        disabled={flag('disabled')}
+        onValueChange={(value) => dispatch('kai-value-change', { value })}
+        controllerRef={(c) => (controller = c)}
+        hostElement={element}
+      />
+    );
   },
-  (props, { element }) => (
-    <ChoiceCard
-      data={props.data as ChoiceCardData | undefined}
-      cardId={props.cardId ?? (element.id || 'kai-choice')}
-      heading={props.heading}
-      resolution={props.resolution as CardResolution | undefined}
-      hostElement={element}
-    />
-  ),
 );

package/src/elements/coachmark.tsx

@@ -0,0 +1,90 @@
+import { defineWebComponent } from './define';
+import { Coachmark, type CoachmarkController } from '../components/coachmark';
+import { wireDisclosure } from './disclosure';
+
+interface Props extends Record<string, unknown> {
+  /** Drive/observe open state (Shoelace-style: settable + reflected to the `open`
+   *  attribute; the element still self-manages). Set `el.open = true`, or
+   *  `<kai-coachmark open>`; listen for `kai-open-change`. */
+  open?: boolean;
+  /** Initial open state on mount (uncontrolled seed). */
+  defaultOpen?: boolean;
+  /** The bold title. Named `headline` because `title` collides with the global
+   *  `HTMLElement.title` attribute (it throws at registration). */
+  headline?: string;
+  /** A small badge pill beside the headline (e.g. "New"). */
+  badge?: string;
+  /** Floating placement relative to the anchor (default `bottom`). */
+  placement?: string;
+  /** Color tone: `primary` (default, theme accent), `info` (blue), `success`
+   *  (green), `warning` (amber), or `error` (red) — reusing the kit's tool hues. */
+  tone?: 'primary' | 'info' | 'success' | 'warning' | 'error';
+  /** Render the arrow that points at the anchor (default `true`). Set
+   *  `arrow="false"` for a plain bubble with no pointer. */
+  arrow?: boolean;
+}
+
+/** Events fired by `<kai-coachmark>`. */
+interface Events {
+  /** The × dismiss button was pressed. The consumer records that this hint was
+   *  seen so it won't show again. */
+  'kai-dismiss': Record<string, never>;
+  /** The coachmark opened or closed (a method, the ×, or a driven `open`). */
+  'kai-open-change': { open: boolean };
+}
+
+/**
+ * `<kai-coachmark>` — an anchored onboarding hint bubble with an arrow. It WRAPS
+ * a trigger (the default slot) and points a primary-colored bubble at it: a small
+ * `badge` pill, a bold `headline`, the `content` slot body, and a dismiss ×.
+ *
+ * ```html
+ * <kai-coachmark default-open headline="Cowork has a new home" badge="New">
+ *   <button>Cowork</button>
+ *   <span slot="content">Chat with Claude or switch to Cowork from here.</span>
+ * </kai-coachmark>
+ * <script type="module">
+ *   document.querySelector('kai-coachmark')
+ *     .addEventListener('kai-dismiss', () => localStorage.setItem('cowork-hint', 'seen'));
+ * </script>
+ * ```
+ *
+ * Open state is the standard disclosure surface: settable+reflecting `open`,
+ * `kai-open-change`, and `show()`/`hide()`/`toggle()`; seed with `default-open`.
+ * Parts: `bubble` · `arrow` · `badge` · `title` · `dismiss`.
+ */
+defineWebComponent<Props, Events>('kai-coachmark', {
+  open: undefined,
+  defaultOpen: undefined,
+  headline: undefined,
+  badge: undefined,
+  placement: undefined,
+  tone: undefined,
+  arrow: true,
+}, (props, ctx) => {
+  const { flag, dispatch } = ctx;
+  let api: CoachmarkController | undefined;
+
+  // The standard disclosure surface: settable+reflecting `open`, kai-open-change,
+  // show/hide/toggle. See ./disclosure. This is the SOLE emitter of kai-open-change.
+  wireDisclosure(ctx, () => api, () => props.open);
+
+  // headline/badge are scalar string props (NOT slots) — pass through directly so
+  // the component's own `Show when={…}` gating drives whether each region renders.
+  // The body is the `content` slot; an empty `<slot>` renders nothing.
+  return (
+    <Coachmark
+      defaultOpen={flag('defaultOpen')}
+      arrow={flag('arrow')}
+      placement={props.placement as never}
+      tone={props.tone as 'primary' | 'info' | 'success' | 'warning' | 'error' | undefined}
+      headline={props.headline as string | undefined}
+      badge={props.badge as string | undefined}
+      content={<slot name="content" />}
+      controllerRef={(a) => (api = a)}
+      onDismiss={() => dispatch('kai-dismiss', {})}
+    >
+      <slot />
+    </Coachmark>
+  );
+});