@kitn.ai/ui 0.16.0 → 0.18.0

package/src/elements/avatar.tsx

@@ -0,0 +1,33 @@
+import { Avatar } from '../ui/avatar';
+import { defineWebComponent } from './define';
+
+interface Props extends Record<string, unknown> {
+  /** Image URL/data-URI. When absent, the `fallback` initials show instead. */
+  src?: string;
+  /** Alt text for the image. Defaults to `fallback`. */
+  alt?: string;
+  /** Short text shown when there's no image — usually initials (e.g. "JD", "AI"). */
+  fallback?: string;
+  /** Size token: `sm` | `md` (default) | `lg`. */
+  size?: 'sm' | 'md' | 'lg';
+}
+
+/**
+ * `<kai-avatar>` — a person/entity avatar: a rounded image that falls back to
+ * initials when there's no `src`. This is an *identity* badge (the thing next to
+ * a message or in a conversation list), not a generic icon — for a glyph, use an
+ * `icon` prop on another element.
+ *
+ * ```html
+ * <kai-avatar src="/me.jpg" fallback="JD"></kai-avatar>
+ * <kai-avatar fallback="AI" size="sm"></kai-avatar>
+ * ```
+ */
+defineWebComponent<Props>('kai-avatar', {
+  src: undefined,
+  alt: undefined,
+  fallback: '',
+  size: 'md',
+}, (props) => (
+  <Avatar src={props.src} alt={props.alt} fallback={props.fallback ?? ''} size={props.size ?? 'md'} />
+));

package/src/elements/badge.tsx

@@ -0,0 +1,32 @@
+import { Badge } from '../ui/badge';
+import { defineWebComponent } from './define';
+
+interface Props extends Record<string, unknown> {
+  /** `default` (muted pill) · `count` (compact number badge) · `citation`
+   *  (filled primary, for inline citation markers). Defaults to `default`. */
+  variant?: 'default' | 'count' | 'citation';
+}
+
+/**
+ * `<kai-badge>` — a small pill for labels, status, counts, or citation markers.
+ * Put the content as light-DOM text.
+ *
+ * ```html
+ * <kai-badge>Beta</kai-badge>
+ * <kai-badge variant="count">3</kai-badge>
+ * <kai-badge variant="citation">1</kai-badge>
+ * ```
+ * Restyle via `::part(badge)`.
+ */
+defineWebComponent<Props>('kai-badge', {
+  variant: 'default',
+}, (props) => (
+  <>
+    {/* Base sets `:host{display:block}`; a badge/pill flows inline with text and
+        beside sibling badges, so inline-flex like kai-button. */}
+    <style>{':host{display:inline-flex}'}</style>
+    <Badge variant={props.variant ?? 'default'} part="badge">
+      <slot />
+    </Badge>
+  </>
+));

package/src/elements/button.tsx

@@ -0,0 +1,126 @@
+import { Show } from 'solid-js';
+import { Button } from '../ui/button';
+import { renderIcon } from '../ui/icon';
+import { defineWebComponent } from './define';
+
+interface Props extends Record<string, unknown> {
+  /** Visual style. `default` (filled), `subtle` (muted text, hover tint — the
+   *  toolbar icon look), `ghost` (transparent, hover fill), `outline`, or
+   *  `destructive`. Defaults to `default`. */
+  variant?: 'default' | 'subtle' | 'ghost' | 'outline' | 'destructive';
+  /** Size token. `icon` / `icon-sm` are square (for icon-only buttons); `sm` /
+   *  `md` / `lg` size text buttons. Defaults to `md`. */
+  size?: 'sm' | 'md' | 'lg' | 'icon' | 'icon-sm';
+  /** Leading icon: a named icon (e.g. `"mic"`, `"plus"`), an image URL/data-URI,
+   *  or plain text. Renders before any slotted label. */
+  icon?: string;
+  /** Trailing icon, after the label (e.g. `"chevron-down"` for a menu affordance). */
+  iconTrailing?: string;
+  /** Accessible name. REQUIRED for icon-only buttons (no visible text); ignored
+   *  when you slot visible text, which already names the button. */
+  label?: string;
+  /** Disable the button (non-interactive, dimmed). */
+  disabled?: boolean;
+  /** Stretch the button to the full width of its container (a block button) —
+   *  e.g. a card CTA or a stacked action. Attribute: `full`. */
+  full?: boolean;
+  /** Justify the button's content: `start`, `center` (default), or `end`.
+   *  Combine with `full` for a full-width, left-aligned button. */
+  align?: 'start' | 'center' | 'end';
+  /** Native button `type`. Defaults to `button` (so it never submits a form). */
+  type?: 'button' | 'submit' | 'reset';
+}
+
+/** Events fired by `<kai-button>`. */
+interface Events {
+  /** The button was activated (pointer or keyboard). Carries no detail. The
+   *  native `click` also bubbles (composed) for consumers who prefer it. */
+  'kai-click': void;
+}
+
+/**
+ * `<kai-button>` — the kit's button as a drop-in element, so consumers compose
+ * polished, theme-aware controls instead of hand-rolling `<button>` + inline
+ * hover styles. Put the label as light-DOM text; use `icon` for a leading glyph
+ * and `label` to name an icon-only button.
+ *
+ * ```html
+ * <kai-button variant="subtle" size="icon" icon="mic" label="Voice input"></kai-button>
+ * <kai-button variant="ghost" icon-trailing="chevron-down">High</kai-button>
+ * <kai-button>Send</kai-button>
+ * <kai-button label="Ship"><svg slot="icon" viewBox="0 0 24 24">…</svg></kai-button>
+ * ```
+ *
+ * The `icon` prop renders a curated/URL icon; for anything else, slot your own
+ * inline SVG via `slot="icon"` (it wins over `icon`). Restyle via `::part(button)`.
+ * Emits `kai-click`.
+ */
+defineWebComponent<Props, Events>('kai-button', {
+  variant: 'default',
+  size: 'md',
+  icon: undefined,
+  iconTrailing: undefined,
+  label: undefined,
+  disabled: false,
+  full: false,
+  align: 'center',
+  type: 'button',
+}, (props, { dispatch, flag, element, expose }) => {
+  // `icon` / `icon-sm` are square, icon-ONLY sizes: suppress the text label and
+  // trailing icon so a stray label doesn't get cramped into the square (the
+  // `label` prop still names it for assistive tech).
+  const iconOnly = () => props.size === 'icon' || props.size === 'icon-sm';
+
+  // ── Imperative API (instance methods on the host) ──────────────────────────
+  // The real <button> lives in the shadow root, so native focus()/blur()/click()
+  // on the host hit the wrapper, not the control. Forward to the inner button.
+  // These shadow the inherited HTMLElement methods — intended; expose() uses
+  // defineProperty so the override sticks. No collision with the props above.
+  expose({
+    /** Focus the inner `<button>` (host.focus() would focus the wrapper). */
+    focus: (options?: FocusOptions) =>
+      element.shadowRoot?.querySelector('button')?.focus(options),
+    /** Blur the inner `<button>`. */
+    blur: () => element.shadowRoot?.querySelector('button')?.blur(),
+    /** Programmatically activate the button — runs the same path as a user
+     *  click and fires kai-click. Forwarding to the inner button means
+     *  `disabled` is respected automatically. */
+    click: () => element.shadowRoot?.querySelector('button')?.click(),
+  });
+  return (
+    <>
+      {/* The host shrinks to the label by default (inline-flex), so a text button
+          is only as wide as its content — until a parent stretches it. A text
+          button's inner control is w-full, so when the host IS stretched (a flex
+          column with items-stretch, e.g. a card's collapsed footer, or an explicit
+          `full`) the button fills it. `full` forces that standalone (a block CTA).
+          Icon buttons stay square (no w-full). */}
+      <style>{':host{display:inline-flex}:host([full]){display:block}'}</style>
+    <Button
+      part="button"
+      variant={props.variant ?? 'default'}
+      size={props.size ?? 'md'}
+      align={props.align ?? 'center'}
+      full={flag('full') || !iconOnly()}
+      type={props.type ?? 'button'}
+      disabled={flag('disabled')}
+      aria-label={props.label}
+      onClick={() => dispatch('kai-click')}
+    >
+      {/* Leading icon: a slotted SVG (slot="icon") wins — drop in any icon
+          library or your own; otherwise the `icon` prop renders a curated/URL one. */}
+      <slot name="icon">
+        <Show when={props.icon}>
+          {renderIcon(props.icon, { class: 'size-4 shrink-0', imgClass: 'size-4 shrink-0', spanClass: 'inline-flex size-4 shrink-0 items-center justify-center', ariaHidden: true })}
+        </Show>
+      </slot>
+      <Show when={!iconOnly()}>
+        <slot />
+      </Show>
+      <Show when={props.iconTrailing && !iconOnly()}>
+        {renderIcon(props.iconTrailing, { class: 'size-4 shrink-0 opacity-60', imgClass: 'size-4 shrink-0', spanClass: 'inline-flex size-4 shrink-0 items-center justify-center', ariaHidden: true })}
+      </Show>
+    </Button>
+    </>
+  );
+});

package/src/elements/card.tsx

@@ -1,40 +1,133 @@
+import { createSignal, onCleanup, onMount } from 'solid-js';
 import { defineWebComponent } from './define';
-import { Card } from '../components/card';
+import { Card, type CardAppearance, type CardOrientation } from '../ui/card';
 
 interface Props extends Record<string, unknown> {
-  /** Heading rendered in the card chrome (= CardEnvelope.title). Attribute: `heading`. */
-  heading?: string;
-  /** Supporting text under the heading. Attribute: `description`. */
-  description?: string;
-  /** When set, the card renders its inline error state instead of the body.
-   *  Attribute: `error-message`. */
-  errorMessage?: string;
-  /** Compact spacing for dense lists. Attribute: `dense`. */
+  /** Surface treatment: `outlined` (default) | `filled` | `plain` | `accent`.
+   *  Attribute: `appearance`. */
+  appearance?: CardAppearance;
+  /** `vertical` (default, media on top) | `horizontal` (media at the start) |
+   *  `responsive` (horizontal when the card's container is wide enough, else
+   *  vertical — a container query on the card's own width). Attribute: `orientation`. */
+  orientation?: CardOrientation;
+  /** The card width below which a `responsive` card collapses to vertical and the
+   *  footer actions stack. A CSS length; default `28rem`. Attribute: `collapse`. */
+  collapse?: string;
+  /** Tighter spacing for dense lists. Attribute: `dense`. */
   dense?: boolean;
+  /** Show a close (×) that hides the card and emits `kai-dismiss`. Attribute:
+   *  `dismissible`. Off by default. */
+  dismissible?: boolean;
+  /** Render the whole card as a link. Attribute: `href`. Wins over `clickable`. */
+  href?: string;
+  /** `target` for the `href` anchor. Attribute: `target`. */
+  target?: string;
+  /** `rel` for the `href` anchor. Attribute: `rel`. */
+  rel?: string;
+  /** Make the whole card a button (`role="button"`, Enter/Space, hover affordance)
+   *  that emits `kai-card-click`. Attribute: `clickable`. Ignored when `href` is set. */
+  clickable?: boolean;
 }
 
+/** Events fired by `<kai-card>`. */
+interface Events {
+  /** The card was dismissed via its × (it also hides itself). */
+  'kai-dismiss': void;
+  /** A `clickable`/`href` card was activated (click, or Enter/Space). */
+  'kai-card-click': void;
+}
+
+/** The named slots whose occupancy gates a card region. An empty `<slot>` is
+ *  always a truthy node, so the facade tracks which are actually filled and only
+ *  passes those regions to the primitive. */
+const SLOT_NAMES = ['media', 'header', 'header-actions', 'footer', 'footer-actions'] as const;
+type SlotName = (typeof SLOT_NAMES)[number];
+
 /**
- * `<kai-card>` — the shared, presentational card chrome every native card composes
- * from: an optional media region (`slot="media"`), a heading + description, a body
- * (default slot), an actions footer (`slot="actions"`), and one consistent inline
- * **error** state (`error-message`). It emits **no** events and reads no context —
- * it is chrome only; the cards that compose it (e.g. `<kai-form>`) own the contract
- * interaction. Isolated in Shadow DOM; theme-aware via the shared kit tokens.
+ * `<kai-card>` — the kit's presentational card, modeled on the WebAwesome card:
+ * ONE element whose flexibility comes from a few structural slots, `appearance`
+ * and `orientation` variants, themeable `::part`s, and a single
+ * `--kai-card-spacing` knob. The title/description are not slots — they are body
+ * (default slot) or `slot="header"` content you mark up yourself.
+ *
+ * Slots: `media` (full-bleed image/video/illustration), `header` + `header-actions`,
+ * the default slot (body), `footer` + `footer-actions`.
+ *
+ * Behaviors (all OFF by default): `dismissible` (× → `kai-dismiss`), and
+ * `href`/`clickable` (whole card a link/button → `kai-card-click`). A
+ * clickable/href card must NOT also contain action buttons.
+ *
+ * ```html
+ * <kai-card appearance="filled" dismissible>
+ *   <div slot="media"><img src="…" alt="…" /></div>
+ *   <h3 slot="header">2× usage</h3>
+ *   Do more with a higher session limit.
+ *   <kai-button slot="footer-actions">Start task</kai-button>
+ * </kai-card>
+ * ```
  */
-defineWebComponent<Props>('kai-card', {
-  heading: undefined,
-  description: undefined,
-  errorMessage: undefined,
+defineWebComponent<Props, Events>('kai-card', {
+  appearance: 'outlined',
+  orientation: 'vertical',
+  collapse: '28rem',
   dense: false,
-}, (props, { flag }) => (
-  <Card
-    heading={props.heading}
-    description={props.description}
-    errorMessage={props.errorMessage}
-    dense={flag('dense')}
-    media={<slot name="media" />}
-    actions={<slot name="actions" />}
-  >
-    <slot />
-  </Card>
-));
+  dismissible: false,
+  href: undefined,
+  target: undefined,
+  rel: undefined,
+  clickable: false,
+}, (props, { element, dispatch, flag }) => {
+  // Track which named slots are filled, plus whether the default slot (body) has
+  // any content. Re-read on child mutations so streamed/late content lights up
+  // its region. An unfilled region is never rendered (no stray padding/divider).
+  const [filled, setFilled] = createSignal<Record<SlotName, boolean>>({
+    'media': false, 'header': false, 'header-actions': false, 'footer': false, 'footer-actions': false,
+  });
+  const [hasBody, setHasBody] = createSignal(false);
+
+  onMount(() => {
+    const read = () => {
+      const next = {} as Record<SlotName, boolean>;
+      for (const name of SLOT_NAMES) next[name] = !!element.querySelector(`:scope > [slot="${name}"]`);
+      setFilled(next);
+      // Body = any direct child without a slot attribute (element, or non-blank text).
+      setHasBody(
+        Array.from(element.childNodes).some(
+          (n) =>
+            (n.nodeType === Node.ELEMENT_NODE && !(n as Element).hasAttribute('slot')) ||
+            (n.nodeType === Node.TEXT_NODE && (n.textContent ?? '').trim() !== ''),
+        ),
+      );
+    };
+    read();
+    const observer = new MutationObserver(read);
+    observer.observe(element, { childList: true, characterData: true, subtree: true });
+    onCleanup(() => observer.disconnect());
+  });
+
+  const region = (name: SlotName) => (filled()[name] ? <slot name={name} /> : undefined);
+
+  return (
+    <Card
+      appearance={props.appearance as CardAppearance}
+      orientation={props.orientation as CardOrientation}
+      collapse={props.collapse as string}
+      dense={flag('dense')}
+      dismissible={flag('dismissible')}
+      href={props.href}
+      target={props.target}
+      rel={props.rel}
+      clickable={flag('clickable')}
+      onDismiss={() => dispatch('kai-dismiss')}
+      onCardClick={() => dispatch('kai-card-click')}
+      media={region('media')}
+      header={region('header')}
+      headerActions={region('header-actions')}
+      footer={region('footer')}
+      footerActions={region('footer-actions')}
+      hasBody={hasBody()}
+    >
+      <slot />
+    </Card>
+  );
+});

package/src/elements/cards.tsx

@@ -4,10 +4,10 @@
 // `kai-card` events through an optional `policy`. The raw events keep bubbling past
 // <kai-cards> (composed) so document-level listeners still work. Unknown types render
 // the Solid CardFallback inline and emit a contract `error`.
-import { For, Show, createEffect, onCleanup, onMount, type JSX } from 'solid-js';
+import { For, Show, createEffect, createSignal, on, onCleanup, onMount, type JSX } from 'solid-js';
 import { Dynamic } from 'solid-js/web';
 import { defineWebComponent } from './define';
-import type { CardEnvelope, CardEvent, CardPolicy } from '../primitives/card-contract';
+import type { CardEnvelope, CardEvent, CardPolicy, CardResolution } from '../primitives/card-contract';
 import { CARD_EVENT_NAME, emitCardEvent, routeCardEvent } from '../primitives/card-routing';
 import { mergeCardTags } from '../primitives/card-registry';
 import { CardFallback } from '../components/card-fallback';
@@ -30,6 +30,33 @@ interface Props extends Record<string, unknown> {
   policy?: CardPolicy;
 }
 
+/** Events fired by `<kai-cards>`. */
+interface Events {
+  /** A child card transitioned to a resolved/deferred state (an action was chosen,
+   *  a form/tasks submission landed, or it was dismissed) — re-emitted off the host
+   *  as a non-bubbling convenience event so a consumer can observe resolution
+   *  centrally without diffing the cards array. `detail` = `{ cardId, resolution }`.
+   *  (A `reopen` un-resolves a card and has no `CardResolution`, so it does NOT fire
+   *  this — observe reopen via the underlying bubbling `kai-card` event.) */
+  'kai-card-resolved': { cardId: string; resolution: CardResolution };
+}
+
+/** Map a terminal/deferred child CardEvent to the CardResolution it produces. Returns
+ *  `undefined` for events that don't resolve a card (ready/error/etc.) and for
+ *  `reopen` (which clears resolution → no CardResolution to convey). */
+function resolutionFromEvent(e: CardEvent): CardResolution | undefined {
+  switch (e.kind) {
+    case 'action':
+      return { kind: 'action', action: e.action, payload: e.payload };
+    case 'submit':
+      return { kind: 'submit', data: e.data };
+    case 'dismiss':
+      return { kind: 'dismissed' };
+    default:
+      return undefined;
+  }
+}
+
 /** A single resolved child: a known kai-* tag (props set imperatively) or the fallback. */
 function CardSlot(props: { envelope: CardEnvelope; tag?: string; theme: string; emit: (e: CardEvent) => void }): JSX.Element {
   let ref: HTMLElement | undefined;
@@ -41,6 +68,9 @@ function CardSlot(props: { envelope: CardEnvelope; tag?: string; theme: string;
     if (props.envelope.title != null) (ref as unknown as { heading: string }).heading = props.envelope.title;
     (ref as unknown as { resolution: unknown }).resolution = props.envelope.resolution;
     ref.setAttribute('theme', props.theme);
+    // Stable, queryable id so the host's getCard()/resolve() can find this child
+    // node without relying on the (private, scalar-only) cardId property reflecting.
+    ref.setAttribute('data-card-id', props.envelope.id);
   });
   // Hoist the unknown-type error emit to onMount to avoid side-effect-in-JSX lint issue
   // and to ensure exactly one error fires.
@@ -59,20 +89,64 @@ function CardSlot(props: { envelope: CardEnvelope; tag?: string; theme: string;
   );
 }
 
-defineWebComponent<Props>(
+defineWebComponent<Props, Events>(
   'kai-cards',
   { cards: undefined, types: undefined, policy: undefined },
-  (props, { element }) => {
+  (props, { element, dispatch, expose }) => {
+    // Local working copy of the card list. The `cards` PROP still drives rendering
+    // (a new prop array re-seeds this), but holding a settable copy lets the
+    // imperative resolve()/dismiss() methods flip one envelope's resolution and
+    // re-render the matching child — the imperative twin of a consumer cloning +
+    // reassigning the whole cards array. `on(..., { defer: true })` re-seeds only on
+    // a genuine prop change (mount uses the createSignal seed below), preserving any
+    // pending imperative resolution until the consumer supplies a new prop array.
+    const [cards, setCards] = createSignal<CardEnvelope[]>(props.cards ?? []);
+    createEffect(on(() => props.cards, (next) => setCards(next ?? []), { defer: true }));
+
     // Route children's bubbling kai-card events through the policy. Attached to the host
     // element so composed events from each child's shadow root are caught as they bubble.
     // The handler reads `props.policy` at EVENT time (not mount time) so setting
     // `el.policy` after the element is in the DOM — the standard host pattern — works.
     onMount(() => {
-      const handler = (e: Event) =>
-        routeCardEvent(props.policy ?? {}, (e as CustomEvent<CardEvent>).detail);
+      const handler = (e: Event) => {
+        const detail = (e as CustomEvent<CardEvent>).detail;
+        routeCardEvent(props.policy ?? {}, detail);
+        // Additionally re-emit the non-bubbling convenience event when a child
+        // transitions to a resolved/deferred state — alongside (not instead of) the
+        // existing policy routing + the raw bubbling kai-card event.
+        const resolution = resolutionFromEvent(detail);
+        if (resolution) dispatch('kai-card-resolved', { cardId: detail.cardId, resolution });
+      };
       element.addEventListener(CARD_EVENT_NAME, handler as EventListener);
       onCleanup(() => element.removeEventListener(CARD_EVENT_NAME, handler as EventListener));
     });
+
+    // ── Imperative API (instance methods on the host) ──────────────────────────
+    // Pattern B: the methods operate on the facade's own working copy + the rendered
+    // child DOM nodes. Resolving an envelope sets its `resolution`, which flows down
+    // through CardSlot's effect (sets the child's `resolution` prop) so the child
+    // re-renders into its chromed read-only view.
+    const resolveCard = (cardId: string, resolution: CardResolution) =>
+      setCards((list) =>
+        list.some((env) => env.id === cardId)
+          ? list.map((env) => (env.id === cardId ? { ...env, resolution } : env))
+          : list,
+      );
+    expose({
+      /** Programmatically resolve a child card by id: set that envelope's
+       *  `resolution` so the child re-renders into its read-only/resolved view — the
+       *  imperative twin of the consumer mutating the cards array. No-op for an
+       *  unknown id. */
+      resolve: (cardId: string, resolution: CardResolution) => resolveCard(cardId, resolution),
+      /** Collapse a card to its re-openable stub from the host side — convenience for
+       *  `resolve(cardId, { kind: 'dismissed' })`. */
+      dismiss: (cardId: string) => resolveCard(cardId, { kind: 'dismissed' }),
+      /** Return the live child element node for a card id (or null) so consumers can
+       *  call that card's own methods (focus/expand/…) without a shadow-DOM query. */
+      getCard: (cardId: string): HTMLElement | null =>
+        element.shadowRoot?.querySelector<HTMLElement>(`[data-card-id="${CSS.escape(cardId)}"]`) ?? null,
+    });
+
     // Read the facade's REACTIVE `theme` prop, not element.getAttribute (which is
     // not a tracked dependency) — otherwise a theme change on <kai-cards> after the
     // children first render never propagates, leaving each child card stuck on its
@@ -81,7 +155,7 @@ defineWebComponent<Props>(
     const tags = () => mergeCardTags(props.types);
     return (
       <div class="flex flex-col gap-3">
-        <For each={props.cards ?? []}>
+        <For each={cards()}>
           {(env) => (
             <CardSlot
               envelope={env}

package/src/elements/chain-of-thought.tsx

@@ -1,49 +1,74 @@
-import { For, Show, createSignal, onMount, onCleanup } from 'solid-js';
+import { createSignal, onMount, onCleanup } from 'solid-js';
 import { defineWebComponent } from './define';
 import {
-  ChainOfThought,
-  ChainOfThoughtStep,
-  ChainOfThoughtTrigger,
-  ChainOfThoughtContent,
-  ChainOfThoughtItem,
+  ChainOfThoughtAccordion,
+  type ChainOfThoughtController,
+  type ChainOfThoughtStepData,
+  type ChainOfThoughtType,
 } from '../components/chain-of-thought';
 
-interface Step {
-  /** The step's heading (the always-visible trigger). */
-  label: string;
-  /** Optional expandable detail. */
-  content?: string;
-}
+/**
+ * A reasoning step descriptor.
+ *
+ * `id` is an OPTIONAL stable key. The Accordion's open-set keys (used by `value`,
+ * `defaultValue`, the `kai-value-change` payload, and the index→key resolution
+ * behind the methods) are `step.id` when present, else `String(index)`. Set `id`
+ * if you want to drive/observe a step by a meaningful key rather than position.
+ */
+type Step = ChainOfThoughtStepData;
 
 interface Props extends Record<string, unknown> {
   /** The reasoning steps. Set as a JS property. Compound sub-parts collapse to
-   *  this one data model (Route 1). */
+   *  this one data model (Route 1). Each `{ label, content?, id? }`. */
   steps: Step[];
+  /** Open mode: `'multiple'` (default — any number of steps open at once) or
+   *  `'single'` (at most one open; opening a step closes the others). */
+  type?: ChainOfThoughtType;
+  /** Controlled open step key(s). When set, it WINS over user interaction (the
+   *  consumer owns the open set). String in `single` mode, string[] in
+   *  `multiple` mode. Set as a JS property. */
+  value?: string | string[];
+  /** Uncontrolled INITIAL open step key(s) — seeds which steps render expanded.
+   *  Ignored once `value` is provided. Set as a JS property. */
+  defaultValue?: string | string[];
+}
+
+/** Events fired by `<kai-chain-of-thought>`. */
+interface Events {
+  /** The open set changed — by user click OR an expand()/collapse()/toggle()
+   *  call. `value` is a string in `single` mode, a string[] in `multiple` mode.
+   *  (Maps Radix Accordion's onValueChange.) */
+  'kai-value-change': { value: string | string[] };
 }
 
 /** Parse a single light-DOM `<kai-step>` element into a `Step` descriptor.
  *  Attribute mapping:
  *   - `label`       → Step.label   (the always-visible heading)
+ *   - `step-id`     → Step.id      (optional stable open-set key)
  *   - textContent   → Step.content (optional expandable detail)
  */
 export function parseKaiStepElement(n: Element): Step {
   return {
     label: n.getAttribute('label') ?? '',
     content: n.textContent?.trim() || undefined,
+    id: n.getAttribute('step-id') ?? undefined,
   };
 }
 
 /**
  * `<kai-chain-of-thought>` — step-by-step reasoning with connectors and
- * per-step collapsible detail.
+ * per-step collapsible detail. An Accordion: by default every step is
+ * independently collapsible (`type="multiple"`, all closed); set
+ * `type="single"` for one-open-at-a-time.
  *
  * **Route 1 — JS property:** set the `steps` property to an array of
- * `{ label, content? }` objects.
+ * `{ label, content?, id? }` objects.
  *
  * **Route 2 — declarative children:** compose `<kai-step>` child elements in
  * light DOM (hidden by the Shadow DOM — pure data carriers). The `label`
  * attribute becomes the step heading; `textContent` becomes the expandable
- * detail. Children are merged after any prop steps.
+ * detail; an optional `step-id` becomes the open-set key. Children are merged
+ * after any prop steps.
  *
  * ```html
  * <kai-chain-of-thought>
@@ -53,9 +78,12 @@ export function parseKaiStepElement(n: Element): Step {
  * </kai-chain-of-thought>
  * ```
  */
-defineWebComponent<Props>('kai-chain-of-thought', {
+defineWebComponent<Props, Events>('kai-chain-of-thought', {
   steps: [],
-}, (props, { element }) => {
+  type: undefined,
+  value: undefined,
+  defaultValue: undefined,
+}, (props, { element, dispatch, expose }) => {
   // Read declarative <kai-step> children from light DOM.
   // Shadow DOM with no <slot> suppresses them visually — they're invisible data carriers.
   const [slottedSteps, setSlottedSteps] = createSignal<Step[]>([]);
@@ -73,20 +101,37 @@ defineWebComponent<Props>('kai-chain-of-thought', {
   // Prop steps first; declarative children appended after.
   const allSteps = () => [...props.steps, ...slottedSteps()];
 
+  // ── Imperative API (instance methods on the host) ──────────────────────────
+  // Pattern C: the Accordion component owns the open-set; the facade captures its
+  // controller and exposes index-based methods. Every setter routes through the
+  // component's onValueChange (handleValueChange below) — the single emit point —
+  // so user clicks AND method calls both fire kai-value-change. No prop collisions:
+  // the only props are steps/type/value/defaultValue.
+  let controller: ChainOfThoughtController | undefined;
+  expose({
+    /** Open one step's detail by index, or — with no arg — ALL steps. In `single`
+     *  mode opening one step closes the others (expand-all keeps the last). */
+    expand: (index?: number) => controller?.expand(index),
+    /** Close one step's detail by index, or — with no arg — ALL steps. */
+    collapse: (index?: number) => controller?.collapse(index),
+    /** Flip one step's open state by index. */
+    toggle: (index?: number) => controller?.toggle(index),
+  });
+
+  // Single emit point for the open set — both user clicks and the methods above
+  // flow through the component's onValueChange to here.
+  const handleValueChange = (value: string | string[]) => {
+    dispatch('kai-value-change', { value });
+  };
+
   return (
-    <ChainOfThought>
-      <For each={allSteps()}>
-        {(step, i) => (
-          <ChainOfThoughtStep isLast={i() === allSteps().length - 1}>
-            <ChainOfThoughtTrigger>{step.label}</ChainOfThoughtTrigger>
-            <Show when={step.content}>
-              <ChainOfThoughtContent>
-                <ChainOfThoughtItem>{step.content}</ChainOfThoughtItem>
-              </ChainOfThoughtContent>
-            </Show>
-          </ChainOfThoughtStep>
-        )}
-      </For>
-    </ChainOfThought>
+    <ChainOfThoughtAccordion
+      steps={allSteps()}
+      type={props.type as ChainOfThoughtType | undefined}
+      value={props.value as string | string[] | undefined}
+      defaultValue={props.defaultValue as string | string[] | undefined}
+      onValueChange={handleValueChange}
+      controllerRef={(c) => (controller = c)}
+    />
   );
 });