@kitn.ai/ui 0.16.0 → 0.18.0

package/src/components/artifact.tsx

@@ -35,13 +35,43 @@ export type ArtifactTab = 'preview' | 'code';
 /** A file the artifact can preview + show source for. */
 export type ArtifactFile = FileTreeFile;
 
+/** Imperative handle exposed via `controllerRef` — surfaces the artifact's latent
+ *  toolbar capabilities (history back/forward/reload/home, programmatic navigate,
+ *  file selection, open-in-new-tab, maximize/restore) so the `<kai-artifact>`
+ *  facade can forward them as instance methods. Each delegates to the SAME internal
+ *  handler the toolbar buttons use, so every existing event still fires. */
+export interface ArtifactController {
+  /** Go back in the artifact's own history stack (no-op when there's no prior entry). */
+  back(): void;
+  /** Go forward in the history stack (no-op when there's no forward entry). */
+  forward(): void;
+  /** Force-reload the current preview url (also re-renders an inline PDF). */
+  reload(): void;
+  /** Navigate to the `src` home url (no-op when there's no `src`). */
+  home(): void;
+  /** Push + load a url in the preview (the path-field submit path). */
+  navigate(url: string): void;
+  /** Select a file by path: highlights the tree, shows its source, navigates the preview. */
+  selectFile(path: string): void;
+  /** Open the current url in a new browser tab (no-op when there's no concrete url). */
+  openExternal(): void;
+  /** Enter the maximized view-state (fires onMaximizeChange/kai-maximize-change). */
+  maximize(): void;
+  /** Exit the maximized view-state. */
+  restore(): void;
+}
+
 export interface ArtifactProps extends Omit<JSX.HTMLAttributes<HTMLDivElement>, 'onSelect'> {
   /** URL the preview iframe frames. */
   src?: string;
   /** Files for the Code tab's tree (+ each file's preview `url`). */
   files?: ArtifactFile[];
-  /** Active tab. Default `preview`. */
+  /** Controlled active tab — when set, the artifact follows it (re-asserted on
+   *  every change). When undefined the tab is uncontrolled (see `defaultTab`). */
   tab?: ArtifactTab;
+  /** Uncontrolled INITIAL tab (used only when `tab` is undefined). The user can
+   *  then freely switch tabs; defaults to `preview`. */
+  defaultTab?: ArtifactTab;
   /** Selected file path (syncs tree highlight + Code source + preview). */
   activeFile?: string;
   /** iframe `sandbox` override. Default `allow-scripts allow-forms`. */
@@ -80,6 +110,15 @@ export interface ArtifactProps extends Omit<JSX.HTMLAttributes<HTMLDivElement>,
   standalone?: boolean;
   /** Make the path field read-only (visible, nav-tracking, non-editable). */
   readonlyPath?: boolean;
+  /** Friendly address shown in the path field INSTEAD of the real current url
+   *  (read-only, non-navigable). Use when the framed url is not consumer-facing
+   *  (e.g. a `data:` blob) so a clean address is shown instead of leaking it.
+   *  Unset = show the real url (editable per `readonlyPath`). */
+  displayUrl?: string;
+  /** Receive the imperative controller once mounted. The `<kai-artifact>` facade
+   *  forwards these as element methods (back/forward/reload/home/navigate/
+   *  selectFile/openExternal/maximize/restore). */
+  controllerRef?: (controller: ArtifactController) => void;
 }
 
 const DEFAULT_SANDBOX = 'allow-scripts allow-forms';
@@ -116,7 +155,9 @@ export function Artifact(props: ArtifactProps): JSX.Element {
   const merged = mergeProps(
     {
       files: [] as ArtifactFile[],
-      tab: 'preview' as ArtifactTab,
+      // No `tab` default: a present `tab` means controlled. The uncontrolled
+      // initial tab comes from `defaultTab` (seeded into the internal signal below).
+      defaultTab: 'preview' as ArtifactTab,
       sandbox: DEFAULT_SANDBOX,
       showNav: true,
       showReload: true,
@@ -135,6 +176,7 @@ export function Artifact(props: ArtifactProps): JSX.Element {
     'src',
     'files',
     'tab',
+    'defaultTab',
     'activeFile',
     'sandbox',
     'iframeTitle',
@@ -152,6 +194,8 @@ export function Artifact(props: ArtifactProps): JSX.Element {
     'openInTab',
     'standalone',
     'readonlyPath',
+    'displayUrl',
+    'controllerRef',
     'class',
   ]);
 
@@ -169,7 +213,11 @@ export function Artifact(props: ArtifactProps): JSX.Element {
   const canBack = () => cursor() > 0;
   const canForward = () => cursor() < history().length - 1;
 
-  const [tab, setTab] = createSignal<ArtifactTab>(local.tab);
+  // Seed the internal tab: a present `tab` (controlled) wins; otherwise the
+  // uncontrolled `defaultTab` (which merges to 'preview'). The user can then
+  // switch freely unless `tab` is set (the effect below re-asserts the controlled
+  // value on each change).
+  const [tab, setTab] = createSignal<ArtifactTab>(local.tab ?? local.defaultTab);
   const [activeFile, setActiveFile] = createSignal<string | undefined>(local.activeFile);
   const [reloadKey, setReloadKey] = createSignal(0);
 
@@ -208,8 +256,12 @@ export function Artifact(props: ArtifactProps): JSX.Element {
 
   let iframeEl: HTMLIFrameElement | undefined;
 
-  // Controlled syncing: when the consumer changes the props, follow them.
-  createEffect(() => setTab(local.tab));
+  // Controlled syncing: when the consumer changes the props, follow them. `tab` is
+  // followed ONLY when it's actually set — an undefined `tab` means uncontrolled,
+  // so the internal signal (seeded from defaultTab) is left for the user to drive.
+  createEffect(() => {
+    if (local.tab !== undefined) setTab(local.tab);
+  });
   createEffect(() => setActiveFile(local.activeFile));
   // `src` change → navigate. Use `on(local.src, …)` so the effect tracks ONLY
   // the `src` prop — NOT `currentUrl()` — otherwise navigating away (file click,
@@ -290,6 +342,38 @@ export function Artifact(props: ArtifactProps): JSX.Element {
     if (local.src) navigate(local.src);
   };
 
+  // Explicitly drive the maximize view-state to a target (the imperative twin of
+  // the toggle button). Fires onMaximizeChange only when the value actually flips,
+  // matching toggleMaximize's "report on change" contract.
+  const setMaximizeState = (next: boolean) => {
+    if (maximized() === next) return;
+    setMaximized(next);
+    local.onMaximizeChange?.(next);
+  };
+
+  // --- Imperative controller (Pattern C): hand the facade a handle over the
+  //     artifact's latent toolbar capabilities. Every method delegates to the
+  //     SAME internal handler the toolbar buttons use, so navigate/tab-change/
+  //     file-select/maximize-change all still fire. ---
+  onMount(() => {
+    local.controllerRef?.({
+      back: () => goBack(),
+      forward: () => goForward(),
+      reload: () => reload(),
+      home: () => goHome(),
+      navigate: (url) => navigate(url),
+      // Resolve the file for the path so highlight + source + preview all sync;
+      // a path with no matching file entry is a no-op (nothing to show).
+      selectFile: (path) => {
+        const file = fileFor(path);
+        if (file) selectFile(path, file);
+      },
+      openExternal: () => openInNewTab(),
+      maximize: () => setMaximizeState(true),
+      restore: () => setMaximizeState(false),
+    });
+  });
+
   // Best-effort: if the consumer opted into `allow-same-origin`, keep the path
   // field truthful as the framed doc navigates itself. Cross-origin (the secure
   // default) throws and we keep our own stack.
@@ -311,9 +395,10 @@ export function Artifact(props: ArtifactProps): JSX.Element {
     const input = (e.currentTarget as HTMLFormElement).elements.namedItem(
       'kai-artifact-path',
     ) as HTMLInputElement | null;
-    if (local.readonlyPath) {
-      // Submit is a no-op while read-only; keep the field reflecting currentUrl.
-      if (input) input.value = currentUrl();
+    if (local.readonlyPath || local.displayUrl != null) {
+      // Submit is a no-op while read-only or showing a friendly displayUrl; keep
+      // the field reflecting the shown value (never push the real, possibly data:, url).
+      if (input) input.value = local.displayUrl ?? currentUrl();
       return;
     }
     if (input && input.value) navigate(input.value);
@@ -330,7 +415,7 @@ export function Artifact(props: ArtifactProps): JSX.Element {
     >
       <Show when={showAnyToolbar()}>
         <ArtifactToolbar
-          url={currentUrl}
+          url={() => local.displayUrl ?? currentUrl()}
           tab={tab}
           canBack={canBack}
           canForward={canForward}
@@ -352,7 +437,7 @@ export function Artifact(props: ArtifactProps): JSX.Element {
           onToggleMaximize={toggleMaximize}
           canOpenInTab={canOpenInTab}
           onOpenInTab={openInNewTab}
-          readonlyPath={() => local.readonlyPath}
+          readonlyPath={() => local.readonlyPath || local.displayUrl != null}
         />
       </Show>
       <div class="relative min-h-0 flex-1">
@@ -420,7 +505,7 @@ function ArtifactToolbar(props: ToolbarProps): JSX.Element {
   return (
     <div
       data-artifact-toolbar
-      class="flex shrink-0 items-center gap-1.5 border-b border-border bg-muted/40 px-2 py-1.5"
+      class="flex shrink-0 items-center gap-1.5 border-b border-border bg-surface px-2 py-1.5"
     >
       <Show when={props.showNav()}>
         <Button
@@ -595,7 +680,7 @@ interface CodeProps {
 function ArtifactCode(props: CodeProps): JSX.Element {
   return (
     <div class="absolute inset-0 flex">
-      <div class="w-56 shrink-0 overflow-auto border-r border-border bg-muted/20 py-1.5 scrollbar-thin">
+      <div class="w-56 shrink-0 overflow-auto border-r border-border bg-surface-sunken py-1.5 scrollbar-thin">
         <FileTree
           files={props.files}
           activeFile={props.activeFile()}
@@ -728,7 +813,7 @@ function ArtifactPdfPreview(props: { url: string; reloadKey: number }): JSX.Elem
         aria-label="PDF preview"
         aria-busy={state() === 'loading'}
         tabindex="0"
-        class="absolute inset-0 flex flex-col items-center gap-3 overflow-auto bg-muted/20 p-3 scrollbar-thin focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-inset"
+        class="absolute inset-0 flex flex-col items-center gap-3 overflow-auto bg-surface-sunken p-3 scrollbar-thin focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-inset"
       />
       <Show when={isPdfPreviewEnabled() && state() === 'loading'}>
         <div class="pointer-events-none absolute inset-0 flex items-center justify-center">

package/src/components/attachment-types.ts

@@ -0,0 +1,13 @@
+/** A message attachment descriptor. Pure type — kept JSX-free for the
+ *  framework-neutral consumers (state core, React hook typecheck). */
+export interface AttachmentData {
+  id: string;
+  type: 'file' | 'source-document';
+  filename?: string;
+  mediaType?: string;
+  url?: string;
+  title?: string;
+}
+
+export type AttachmentMediaCategory = 'image' | 'video' | 'audio' | 'document' | 'source' | 'unknown';
+export type AttachmentVariant = 'grid' | 'inline' | 'list';

package/src/components/attachments.tsx

@@ -11,23 +11,13 @@ import {
   Video,
   X,
 } from 'lucide-solid';
+import type { AttachmentData, AttachmentMediaCategory, AttachmentVariant } from './attachment-types';
+export type { AttachmentData, AttachmentMediaCategory, AttachmentVariant } from './attachment-types';
 
 // ============================================================================
 // Types
 // ============================================================================
 
-export interface AttachmentData {
-  id: string;
-  type: 'file' | 'source-document';
-  filename?: string;
-  mediaType?: string;
-  url?: string;
-  title?: string;
-}
-
-export type AttachmentMediaCategory = 'image' | 'video' | 'audio' | 'document' | 'source' | 'unknown';
-export type AttachmentVariant = 'grid' | 'inline' | 'list';
-
 const mediaCategoryIcons: Record<AttachmentMediaCategory, typeof ImageIcon> = {
   audio: Music2,
   document: FileText,
@@ -159,12 +149,12 @@ function Attachment(props: AttachmentProps) {
           ctx.variant === 'grid' && 'size-24 overflow-hidden rounded-lg',
           ctx.variant === 'inline' && [
             'flex h-8 cursor-pointer select-none items-center gap-1.5',
-            'rounded-md bg-muted/50 px-1.5 text-foreground',
+            'rounded-md bg-surface-strong px-1.5 text-foreground',
             'font-medium text-sm transition-all',
             'hover:bg-muted',
           ],
           ctx.variant === 'list' && [
-            'flex w-full items-center gap-3 rounded-lg bg-muted/30 p-3 text-foreground',
+            'flex w-full items-center gap-3 rounded-lg bg-surface p-3 text-foreground',
             'hover:bg-muted/50',
           ],
           local.class,

package/src/components/card.tsx

@@ -1,6 +1,7 @@
-import { type JSX, Show, splitProps, mergeProps, createUniqueId } from 'solid-js';
+import { type JSX, Show, splitProps, mergeProps, createSignal, createUniqueId } from 'solid-js';
+import { Dynamic } from 'solid-js/web';
 import { cn } from '../utils/cn';
-import { AlertTriangle } from 'lucide-solid';
+import { AlertTriangle, X } from 'lucide-solid';
 
 export interface CardProps extends JSX.HTMLAttributes<HTMLDivElement> {
   /** Heading rendered in the card chrome (the contract's CardEnvelope.title).
@@ -19,6 +20,25 @@ export interface CardProps extends JSX.HTMLAttributes<HTMLDivElement> {
   /** Stable id for the heading (so composing cards can `aria-labelledby` it).
    *  Auto-generated when omitted. */
   headingId?: string;
+  /** Render a dismiss (×) button that hides the card and calls `onDismiss`.
+   *  Opt-in, OFF by default — the contract cards never set it, so they are
+   *  unaffected. */
+  dismissible?: boolean;
+  /** Called after the card is dismissed via its ×. */
+  onDismiss?: () => void;
+  /** Render the whole card as a link (`<a>`). Wins over `clickable`. */
+  href?: string;
+  /** `target` for the `href` anchor. */
+  target?: string;
+  /** `rel` for the `href` anchor (default `noopener noreferrer` when `target="_blank"`). */
+  rel?: string;
+  /** Make the whole card behave like a button: `role="button"`, a tabindex, and
+   *  Enter/Space activation, firing `onCardClick`. Ignored when `href` is set.
+   *  A clickable/href card must NOT also contain footer action buttons — that
+   *  nests interactive elements. Use `actions` OR clickable, never both. */
+  clickable?: boolean;
+  /** Called when a `clickable` (or `href`) card is activated (click, or Enter/Space). */
+  onCardClick?: (event: MouseEvent | KeyboardEvent) => void;
 }
 
 /**
@@ -28,6 +48,14 @@ export interface CardProps extends JSX.HTMLAttributes<HTMLDivElement> {
  * "never a broken/partial card" rule). It is intentionally chrome-only: it reads
  * no `CardContext` and emits no `CardEvent` — the cards that compose it (e.g.
  * `kai-form`) own the contract interaction.
+ *
+ * The optional `dismissible` / `href` / `clickable` behaviors are all OFF by
+ * default, so the contract cards (which set none of them) keep their original
+ * presentational behavior unchanged.
+ *
+ * a11y: a `clickable` or `href` card MUST NOT also contain footer action buttons
+ * — that nests interactive controls inside a button/link. Use `actions` OR
+ * make the card clickable, never both.
  */
 export function Card(props: CardProps): JSX.Element {
   const merged = mergeProps({ dense: false }, props);
@@ -39,6 +67,13 @@ export function Card(props: CardProps): JSX.Element {
     'errorMessage',
     'dense',
     'headingId',
+    'dismissible',
+    'onDismiss',
+    'href',
+    'target',
+    'rel',
+    'clickable',
+    'onCardClick',
     'class',
     'children',
   ]);
@@ -48,19 +83,36 @@ export function Card(props: CardProps): JSX.Element {
   const hasError = () => local.errorMessage !== undefined && local.errorMessage !== '';
   const hasHeader = () => Boolean(local.heading) || Boolean(local.description);
 
-  return (
-    <div
-      class={cn(
-        'flex flex-col rounded-xl border border-border bg-card text-card-foreground kai-elevation-sm',
-        local.dense ? 'gap-2.5 p-3.5' : 'gap-4 p-5',
-        local.class,
-      )}
-      {...rest}
-    >
-      <Show when={local.media}>
-        <div class="overflow-hidden rounded-lg">{local.media}</div>
-      </Show>
+  const [open, setOpen] = createSignal(true);
+  const dismiss = (event: MouseEvent) => {
+    // Don't let the × activate a clickable/href card underneath it.
+    event.stopPropagation();
+    setOpen(false);
+    local.onDismiss?.();
+  };
+
+  const isLink = () => Boolean(local.href);
+  const isButton = () => !isLink() && Boolean(local.clickable);
+  const isInteractive = () => isLink() || isButton();
 
+  const activate = (event: MouseEvent | KeyboardEvent) => local.onCardClick?.(event);
+  const onKeyDown = (event: KeyboardEvent) => {
+    if (!isButton()) return;
+    if (event.key === 'Enter' || event.key === ' ' || event.key === 'Spacebar') {
+      event.preventDefault();
+      activate(event);
+    }
+  };
+
+  // The interactive elements (`<a>` / role="button") get keyboard + hover/focus
+  // affordances; the plain card is a `<div>`. Anchors carry a safe default `rel`
+  // when opening a new tab.
+  const rel = () =>
+    local.rel ?? (local.target === '_blank' ? 'noopener noreferrer' : undefined);
+
+  // The card's heading + body + actions column.
+  const inner = (
+    <>
       <Show when={hasHeader()}>
         <div
           class={cn(
@@ -105,6 +157,48 @@ export function Card(props: CardProps): JSX.Element {
           <span>{local.errorMessage}</span>
         </div>
       </Show>
-    </div>
+    </>
+  );
+
+  return (
+    <Show when={open()}>
+      <Dynamic
+        component={isLink() ? 'a' : 'div'}
+        part="card"
+        href={isLink() ? local.href : undefined}
+        target={isLink() ? local.target : undefined}
+        rel={isLink() ? rel() : undefined}
+        role={isButton() ? 'button' : undefined}
+        tabindex={isButton() ? 0 : undefined}
+        onClick={isInteractive() ? activate : undefined}
+        onKeyDown={isButton() ? onKeyDown : undefined}
+        class={cn(
+          'relative flex flex-col rounded-xl border border-border bg-card text-card-foreground kai-elevation-sm',
+          local.dense ? 'gap-2.5 p-3.5' : 'gap-4 p-5',
+          isInteractive() &&
+            'cursor-pointer no-underline transition-colors hover:border-ring hover:bg-accent/40 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring',
+          local.class,
+        )}
+        {...rest}
+      >
+        <Show when={local.dismissible}>
+          <button
+            type="button"
+            part="dismiss"
+            aria-label="Dismiss"
+            onClick={dismiss}
+            class="absolute right-2.5 top-2.5 z-10 shrink-0 rounded p-1 text-muted-foreground transition-colors hover:bg-accent hover:text-foreground"
+          >
+            <X class="size-3.5" aria-hidden="true" />
+          </button>
+        </Show>
+
+        <Show when={local.media}>
+          <div class="overflow-hidden rounded-lg">{local.media}</div>
+        </Show>
+
+        {inner}
+      </Dynamic>
+    </Show>
   );
 }

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

@@ -1,4 +1,11 @@
-import { type JSX, splitProps, children as resolveChildren, For, Show } from 'solid-js';
+import {
+  type JSX,
+  type Accessor,
+  splitProps,
+  createSignal,
+  For,
+  Show,
+} from 'solid-js';
 import { cn } from '../utils/cn';
 import { Collapsible, CollapsibleTrigger, CollapsibleContent } from '../ui/collapsible';
 import { ChevronDown, Circle } from 'lucide-solid';
@@ -114,6 +121,15 @@ export interface ChainOfThoughtStepProps {
   children: JSX.Element;
   class?: string;
   isLast?: boolean;
+  /** Controlled open state. When provided, the step's Collapsible is driven by
+   *  this value (the parent owns it — used by the Accordion model below). When
+   *  OMITTED the step stays uncontrolled, preserving the original behaviour
+   *  (every step independently toggleable, starting closed). */
+  open?: boolean;
+  /** Called with the desired next open state when the user clicks the trigger.
+   *  Only meaningful when `open` is also provided (controlled mode); the parent
+   *  Accordion routes this through its open-set handler. */
+  onOpenChange?: (open: boolean) => void;
 }
 
 function ChainOfThoughtStep(props: ChainOfThoughtStepProps) {
@@ -121,6 +137,8 @@ function ChainOfThoughtStep(props: ChainOfThoughtStepProps) {
     <Collapsible
       class={cn('group', props.class)}
       data-last={props.isLast ?? false}
+      open={props.open}
+      onOpenChange={props.onOpenChange}
     >
       {props.children}
       <div class="flex justify-start group-data-[last=true]:hidden">
@@ -130,10 +148,201 @@ function ChainOfThoughtStep(props: ChainOfThoughtStepProps) {
   );
 }
 
+// --- Accordion model (the kai-chain-of-thought interaction surface) ---
+
+/** Open-mode: `multiple` (any number of steps open at once — the historical
+ *  default) or `single` (at most one open; opening a step closes the others). */
+export type ChainOfThoughtType = 'single' | 'multiple';
+
+/**
+ * A reasoning step descriptor. `id` is an OPTIONAL stable key — the Accordion's
+ * open-set keys use `step.id` when present, else `String(index)`. So a consumer
+ * who wants to drive `value`/`defaultValue` (or read `kai-value-change`) by a
+ * meaningful key should set `id`; otherwise the step's position is its key.
+ */
+export interface ChainOfThoughtStepData {
+  /** The step's heading (the always-visible trigger). */
+  label: string;
+  /** Optional expandable detail. */
+  content?: string;
+  /** Optional stable key for the open-set/value model (defaults to the index). */
+  id?: string;
+}
+
+/**
+ * Imperative handle exposed via `controllerRef` so the `<kai-chain-of-thought>`
+ * facade can drive/observe the Accordion's open set. Index-based to match the
+ * `expand(index?)`/`collapse(index?)`/`toggle(index?)` method signatures; the
+ * controller resolves the index → step key internally. All setters flow through
+ * the same open-set mutate path as user clicks, so they all emit
+ * `kai-value-change` via `onValueChange`.
+ */
+export interface ChainOfThoughtController {
+  /** Current open keys, normalised per `type` (string in single, string[] in multiple). */
+  value: Accessor<string | string[]>;
+  /** Open one step by index, or ALL steps when `index` is omitted. */
+  expand: (index?: number) => void;
+  /** Close one step by index, or ALL steps when `index` is omitted. */
+  collapse: (index?: number) => void;
+  /** Flip one step's open state by index. */
+  toggle: (index?: number) => void;
+}
+
+export interface ChainOfThoughtAccordionProps {
+  /** The reasoning steps to render. */
+  steps: ChainOfThoughtStepData[];
+  /** Open mode. Default `multiple` (the historical behaviour). */
+  type?: ChainOfThoughtType;
+  /** Controlled open step key(s). When provided it WINS over internal state. */
+  value?: string | string[];
+  /** Uncontrolled initial open step key(s). Seeds the internal open-set. */
+  defaultValue?: string | string[];
+  /** Fired whenever the open set changes (user click OR a controller method).
+   *  The single emit point — the facade turns this into `kai-value-change`. The
+   *  payload is a string in `single` mode, a string[] in `multiple` mode. */
+  onValueChange?: (value: string | string[]) => void;
+  /** Receive the imperative controller once set up (Pattern C). */
+  controllerRef?: (api: ChainOfThoughtController) => void;
+  class?: string;
+}
+
+/** Normalise a `string | string[]` (or undefined) seed to a Set of keys. */
+function toKeySet(value: string | string[] | undefined): Set<string> {
+  if (value == null) return new Set();
+  return new Set(Array.isArray(value) ? value : [value]);
+}
+
+/**
+ * The full Accordion-model root used by `<kai-chain-of-thought>`. Lifts each
+ * step's open state into a controlled/uncontrolled open-set:
+ *  - seeded from `defaultValue` (normalised string|string[] → Set);
+ *  - when `value` is provided it WINS (controlled);
+ *  - a trigger click updates the set respecting `single` vs `multiple` and emits
+ *    via `onValueChange` — in single mode opening a step closes the others;
+ *  - each step's Collapsible is driven (controlled) by its membership in the set.
+ *
+ * With NO new props (type defaults to `multiple`, no value/defaultValue), every
+ * step starts closed and is independently toggleable — identical to the old
+ * behaviour, just with the open state lifted here so methods/events can observe
+ * and drive it.
+ */
+function ChainOfThoughtAccordion(props: ChainOfThoughtAccordionProps) {
+  const [internal, setInternal] = createSignal<Set<string>>(toKeySet(props.defaultValue));
+
+  const type = (): ChainOfThoughtType => props.type ?? 'multiple';
+
+  // The step key: explicit id when present, else the index as a string.
+  const keyOf = (step: ChainOfThoughtStepData, index: number) => step.id ?? String(index);
+
+  // Controlled `value` wins; otherwise the internal signal owns the open-set.
+  const isControlled = () => props.value !== undefined;
+  const openSet = (): Set<string> => (isControlled() ? toKeySet(props.value) : internal());
+
+  const isOpen = (key: string) => openSet().has(key);
+
+  // Shape the open-set as the public value: a single string (or '') in single
+  // mode, a string[] in multiple mode.
+  const toValue = (set: Set<string>): string | string[] => {
+    if (type() === 'single') {
+      const first = set.values().next();
+      return first.done ? '' : first.value;
+    }
+    return [...set];
+  };
+
+  // The single mutate path — shared by trigger clicks and controller methods.
+  // Computes the next open-set, writes it (uncontrolled only) and ALWAYS emits
+  // onValueChange so both user + programmatic changes flow to kai-value-change.
+  const commit = (next: Set<string>) => {
+    const cur = openSet();
+    // No-op if the set is unchanged (avoids redundant events).
+    if (cur.size === next.size && [...cur].every((k) => next.has(k))) return;
+    if (!isControlled()) setInternal(next);
+    props.onValueChange?.(toValue(next));
+  };
+
+  // Set a single key's open state, respecting single vs multiple.
+  const setKeyOpen = (key: string, open: boolean) => {
+    if (type() === 'single') {
+      commit(open ? new Set([key]) : new Set());
+      return;
+    }
+    const next = new Set(openSet());
+    if (open) next.add(key); else next.delete(key);
+    commit(next);
+  };
+
+  // Resolve a step index → key (undefined when out of range).
+  const keyAt = (index: number): string | undefined => {
+    const step = props.steps[index];
+    return step ? keyOf(step, index) : undefined;
+  };
+
+  const allKeys = (): string[] => props.steps.map((s, i) => keyOf(s, i));
+
+  // --- Controller (Pattern C): hand the facade an index-based handle. Every
+  //     setter routes through commit() so methods + clicks share one emit point.
+  props.controllerRef?.({
+    value: () => toValue(openSet()),
+    expand: (index?: number) => {
+      if (index === undefined) {
+        // Open all. In single mode only one can be open — keep the last step.
+        if (type() === 'single') {
+          const keys = allKeys();
+          commit(keys.length ? new Set([keys[keys.length - 1]]) : new Set());
+        } else {
+          commit(new Set(allKeys()));
+        }
+        return;
+      }
+      const key = keyAt(index);
+      if (key !== undefined) setKeyOpen(key, true);
+    },
+    collapse: (index?: number) => {
+      if (index === undefined) {
+        commit(new Set());
+        return;
+      }
+      const key = keyAt(index);
+      if (key !== undefined) setKeyOpen(key, false);
+    },
+    toggle: (index?: number) => {
+      if (index === undefined) return;
+      const key = keyAt(index);
+      if (key !== undefined) setKeyOpen(key, !isOpen(key));
+    },
+  });
+
+  return (
+    <ChainOfThought class={props.class}>
+      <For each={props.steps}>
+        {(step, i) => {
+          const key = () => keyOf(step, i());
+          return (
+            <ChainOfThoughtStep
+              isLast={i() === props.steps.length - 1}
+              open={isOpen(key())}
+              onOpenChange={(open) => setKeyOpen(key(), open)}
+            >
+              <ChainOfThoughtTrigger>{step.label}</ChainOfThoughtTrigger>
+              <Show when={step.content}>
+                <ChainOfThoughtContent>
+                  <ChainOfThoughtItem>{step.content}</ChainOfThoughtItem>
+                </ChainOfThoughtContent>
+              </Show>
+            </ChainOfThoughtStep>
+          );
+        }}
+      </For>
+    </ChainOfThought>
+  );
+}
+
 export {
   ChainOfThought,
   ChainOfThoughtStep,
   ChainOfThoughtTrigger,
   ChainOfThoughtContent,
   ChainOfThoughtItem,
+  ChainOfThoughtAccordion,
 };