@kitn.ai/ui 0.28.0 → 0.29.0

package/src/elements/composer.tsx

@@ -1,162 +0,0 @@
-import { createSignal } from 'solid-js';
-import { defineWebComponent } from './define';
-import type { ComposerDoc, EntityRef } from '../primitives/composer-model';
-import type { TriggerDef, TriggerItem, HighlightRule, ComposerChange, ComposerController } from '../components/composer';
-import { Composer } from '../components/composer';
-
-/**
- * Parse a single light-DOM `<kai-trigger-item>` element into a TriggerItem.
- * Attribute mapping:
- *  - `item-id`     → TriggerItem.id       (required; empty string fallback)
- *  - textContent   → TriggerItem.label    (primary); `label` attr as fallback
- *  - `icon`        → TriggerItem.icon
- *  - `prompt-text` → TriggerItem.promptText
- *  - `data`        is left undefined (complex object, not representable as an attribute)
- *
- * @param n    The `<kai-trigger-item>` element to parse.
- * @param char The trigger character this item belongs to (e.g. `/` or `@`).
- * @param kind The entity kind for this trigger (e.g. `'skill'` or `'mention'`).
- */
-export function parseKaiTriggerItemElement(n: Element, char: string, kind: string): TriggerItem {
-  // char and kind inform the consumer but are not stored on TriggerItem itself.
-  void char;
-  void kind;
-  return {
-    id: n.getAttribute('item-id') ?? '',
-    label: n.textContent?.trim() || n.getAttribute('label') || n.getAttribute('item-id') || '',
-    icon: n.getAttribute('icon') ?? undefined,
-    promptText: n.getAttribute('prompt-text') ?? undefined,
-    data: undefined,
-  };
-}
-
-interface Props extends Record<string, unknown> {
-  /** Controlled value: a string or a full ComposerDoc (set as JS property). */
-  value?: string | ComposerDoc;
-  /** Placeholder text shown when the composer is empty. */
-  placeholder?: string;
-  /** Disable the composer entirely (non-interactive). */
-  disabled?: boolean;
-  /** Show a loading/streaming state and block submit. */
-  loading?: boolean;
-  /** Maximum height in px before the content scrolls. Default 240. */
-  maxHeight?: number | string;
-  /** Whether pressing Enter (without Shift) submits. Default true. */
-  submitOnEnter?: boolean;
-  /** Trigger definitions. Set as a JS property. */
-  triggers?: TriggerDef[];
-  /** Keyword highlight rules. Set as a JS property. */
-  highlights?: HighlightRule[];
-  /** Default icon per entity kind (kind → image URL/data-URI) for items without
-   *  their own `icon`. Overrides the built-in agent/plugin glyphs. JS property. */
-  kindIcons?: Record<string, string>;
-}
-
-/** Events fired by `<kai-composer>`. */
-interface Events {
-  /** The user submitted the composer (Enter or programmatic submit). Note the
-   *  detail carries no `attachments`; `<kai-composer>` is the bare editing
-   *  surface: no send button, toolbar, or attachments. For a drop-in composer
-   *  row with all three, reach for `<kai-prompt-input>`, which is built on this. */
-  'kai-submit': { doc: ComposerDoc; text: string; entities: EntityRef[] };
-  /** The content changed (fires on every input event). */
-  'kai-value-change': { doc: ComposerDoc; text: string; entities: EntityRef[] };
-  /** An entity pill was inserted into the composer. */
-  'kai-entity-add': { entity: EntityRef };
-  /** An entity pill was deleted from the composer. */
-  'kai-entity-remove': { entity: EntityRef };
-  /** A trigger character was detected at the caret (e.g. `/` or `@`). */
-  'kai-trigger': { char: string; query: string; rect: DOMRect };
-  /** The active trigger was dismissed (Escape, space, or outside click). */
-  'kai-trigger-close': Record<string, never>;
-  /** The composer gained focus. `focus`/`blur` are NOT composed natively, so they
-   *  don't escape the shadow root; these re-expose them on the host. (For
-   *  `keydown`/`paste`/`focusin`/`focusout`, listen NATIVELY on `<kai-composer>`:
-   *  they're composed and already cross the shadow boundary.) */
-  'kai-focus': { originalEvent: FocusEvent };
-  /** The composer lost focus. */
-  'kai-blur': { originalEvent: FocusEvent };
-}
-
-/**
- * `<kai-composer>` — the bare editing surface: rich text, entity pills,
- * trigger menus, Enter-to-submit, and nothing else. No send button, no
- * toolbar, no attachments — that division is deliberate. For a drop-in chat
- * composer with a send button, toolbar, and attachment staging, reach for
- * `<kai-prompt-input>`, which is built on this element. Keep `<kai-composer>`
- * when you are composing the input row yourself and want to own those pieces.
- */
-defineWebComponent<Props, Events>('kai-composer', {
-  value: undefined,
-  placeholder: undefined,
-  disabled: false,
-  loading: false,
-  maxHeight: 240,
-  submitOnEnter: true,
-  triggers: undefined,
-  highlights: undefined,
-  kindIcons: undefined,
-}, (props, { dispatch, flag, expose }) => {
-  // Internal signal for uncontrolled value; when the consumer sets `value` as a
-  // JS property the controlled path takes precedence (same pattern as prompt-input).
-  const [internal, setInternal] = createSignal<string | ComposerDoc | undefined>(props.value);
-
-  const current = () => props.value ?? internal();
-
-  // ── Imperative API (instance methods on the host) ──────────────────────────
-  // Pattern C: the Composer component owns the editable + doc state and hands up
-  // a controller; the facade captures it and exposes delegating methods. The
-  // composer's own callbacks still fire (clear → onChange → kai-value-change;
-  // send → onSubmit → kai-submit; insertEntity → onEntityAdd → kai-entity-add).
-  let controller: ComposerController | undefined;
-  expose({
-    /** Focus the editable element. `focus`/`blur` are NOT composed natively, so a
-     *  host-level focus() can't reach the editable inside the shadow root. This is
-     *  the only way to focus the composer programmatically. */
-    focus: (options?: FocusOptions) => controller?.focus(options),
-    /** Blur the editable element. */
-    blur: () => controller?.blur(),
-    /** Empty the composer to a blank doc (resets the internal value + history
-     *  baseline; fires kai-value-change). */
-    clear: () => controller?.clear(),
-    /** Submit the current content programmatically, on the same path as Enter
-     *  (fires kai-submit). Named `send`, not `submit`, to match the shared
-     *  vocabulary and avoid any submit collision. */
-    send: () => controller?.send(),
-    /** Insert an atomic entity pill (skill/agent/plugin) at the caret without
-     *  typing a trigger (fires kai-entity-add). */
-    insertEntity: (entity: EntityRef) => controller?.insertEntity(entity),
-  });
-
-  const handleChange = (change: ComposerChange) => {
-    setInternal(change.doc);
-    dispatch('kai-value-change', { doc: change.doc, text: change.text, entities: change.entities });
-  };
-
-  const handleSubmit = (change: ComposerChange) => {
-    dispatch('kai-submit', { doc: change.doc, text: change.text, entities: change.entities });
-  };
-
-  return (
-    <Composer
-      value={current()}
-      placeholder={props.placeholder}
-      disabled={flag('disabled')}
-      loading={flag('loading')}
-      maxHeight={props.maxHeight as number | string | undefined}
-      submitOnEnter={flag('submitOnEnter')}
-      triggers={props.triggers}
-      highlights={props.highlights}
-      kindIcons={props.kindIcons as Record<string, string> | undefined}
-      onChange={handleChange}
-      onSubmit={handleSubmit}
-      onEntityAdd={(entity) => dispatch('kai-entity-add', { entity })}
-      onEntityRemove={(entity) => dispatch('kai-entity-remove', { entity })}
-      onTrigger={(info) => dispatch('kai-trigger', info)}
-      onTriggerClose={() => dispatch('kai-trigger-close', {})}
-      onFocus={(e) => dispatch('kai-focus', { originalEvent: e })}
-      onBlur={(e) => dispatch('kai-blur', { originalEvent: e })}
-      controllerRef={(c) => (controller = c)}
-    />
-  );
-});

package/src/elements/confirm-card.tsx

@@ -1,76 +0,0 @@
-import { defineWebComponent } from './define';
-import { ConfirmCard, type ConfirmCardData, type ConfirmController } from '../components/confirm-card';
-import type { CardResolution } from '../primitives/card-contract';
-
-interface Props extends Record<string, unknown> {
-  /** The confirm definition (the CardEnvelope.data). Set as a JS PROPERTY:
-   *  `el.data = { body, tone, actions:[…] }`. Import `ConfirmCardData` from
-   *  `@kitn.ai/ui` for the full shape. */
-  data?: ConfirmCardData;
-  /** Stable card id correlating every emitted CardEvent. Attribute: `card-id`. */
-  cardId?: string;
-  /** Heading rendered in the card chrome (= CardEnvelope.title). Attribute: `heading`. */
-  heading?: string;
-  /** Focus the default action on mount (off by default, so nothing steals
-   *  focus). Attribute: `autofocus`. */
-  autofocus?: boolean;
-  /** Set when the user resolved this card; renders the read-only view. Property:
-   *  `el.resolution = { kind:'action', action:'…' }`. */
-  resolution?: Record<string, unknown>;
-}
-
-/**
- * `<kai-confirm>` — a named-intent **approval** card (set via the `data` property):
- * a title + body + a small set of action buttons. Activating an action emits the
- * Card contract's **`action`** verb up a bubbling **`kai-card`** CustomEvent
- * (`{ kind:'action', cardId, action, payload }`) and resolves the card so the same
- * approval can't double-fire. Also emits `ready` on mount, `dismiss` for the
- * optional close affordance, 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 kit tokens.
- *
- * Exposes instance methods `focus()`/`confirm(actionId?)`/`dismiss()`/`reopen()`
- * that drive the same internal paths as the buttons.
- */
-defineWebComponent<Props>(
-  'kai-confirm',
-  {
-    data: undefined,
-    cardId: undefined,
-    heading: undefined,
-    autofocus: false,
-    resolution: undefined,
-  },
-  (props, { element, flag, expose }) => {
-    // Pattern C: the ConfirmCard owns the action/dismiss state and hands up a
-    // controller; the facade captures it and exposes delegating methods. The card's
-    // own paths still fire (confirm → kai-card `action`; dismiss/reopen → kai-card
-    // `dismiss`/`reopen`).
-    let controller: ConfirmController | undefined;
-    expose({
-      /** Focus the default action button (or the first action if none is default).
-       *  The same target `autofocus` focuses on mount, but on demand. */
-      focus: (options?: FocusOptions) => controller?.focus(options),
-      /** Activate an action by id: emits the `action` verb on kai-card and resolves
-       *  the card (single-shot). With no id, invokes the default action. */
-      confirm: (actionId?: string) => controller?.confirm(actionId),
-      /** 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 (
-      <ConfirmCard
-        data={props.data}
-        cardId={props.cardId ?? (element.id || 'kai-confirm')}
-        heading={props.heading}
-        autofocus={flag('autofocus')}
-        resolution={props.resolution as CardResolution | undefined}
-        controllerRef={(c) => (controller = c)}
-        hostElement={element}
-      />
-    );
-  },
-);

package/src/elements/context-meter.tsx

@@ -1,107 +0,0 @@
-import { Show, createEffect, createMemo, on } from 'solid-js';
-import { defineWebComponent } from './define';
-import {
-  Context,
-  ContextTrigger,
-  ContextContent,
-  ContextContentHeader,
-  ContextContentBody,
-  ContextContentFooter,
-  ContextInputUsage,
-  ContextOutputUsage,
-  ContextReasoningUsage,
-  ContextCacheUsage,
-  computeSeverity,
-  DEFAULT_WARN_THRESHOLD,
-  DEFAULT_DANGER_THRESHOLD,
-  type ContextSeverity,
-} from '../components/context';
-// Public shape of the `context` prop; lives in ./element-data-types so the ROOT
-// entry can re-export it (see that file's header).
-import type { KaiContextUsage } from './element-data-types';
-
-interface Props extends Record<string, unknown> {
-  /** Token-usage data. Set as a JS property. */
-  context?: KaiContextUsage;
-  /**
-   * Fraction (0–1) above which the meter turns yellow.
-   * Defaults to `0.7` (70%).
-   */
-  warnThreshold?: number;
-  /**
-   * Fraction (0–1) above which the meter turns red.
-   * Defaults to `0.9` (90%).
-   */
-  dangerThreshold?: number;
-}
-
-/** Events fired by `<kai-context>`. */
-interface Events {
-  /**
-   * Fires when the computed severity level changes (ok → warn → danger or back).
-   * `detail.level` is `'ok'`, `'warn'`, or `'danger'`.
-   */
-  'kai-threshold-change': { level: ContextSeverity };
-}
-
-/**
- * `<kai-context>` — a token/context-window usage meter with a hover-card
- * breakdown (input/output/reasoning/cache + estimated cost). Data via the
- * `context` property.
- *
- * **Color thresholds** are configurable via `warnThreshold` (default `0.7`)
- * and `dangerThreshold` (default `0.9`). When the computed severity level
- * changes, a `kai-threshold-change` event fires with `detail.level` set to
- * `'ok'`, `'warn'`, or `'danger'`.
- */
-defineWebComponent<Props, Events>('kai-context', {
-  context: undefined,
-  warnThreshold: undefined,
-  dangerThreshold: undefined,
-}, (props, { dispatch }) => {
-  const warn = () => (props.warnThreshold as number | undefined) ?? DEFAULT_WARN_THRESHOLD;
-  const danger = () => (props.dangerThreshold as number | undefined) ?? DEFAULT_DANGER_THRESHOLD;
-
-  const severity = createMemo<ContextSeverity>(() => {
-    const ctx = props.context;
-    if (!ctx) return 'ok';
-    return computeSeverity(ctx.usedTokens / ctx.maxTokens, warn(), danger());
-  });
-
-  // Fire kai-threshold-change only when the level actually changes.
-  createEffect(on(severity, (level, prev) => {
-    if (prev !== undefined && level !== prev) {
-      dispatch('kai-threshold-change', { level });
-    }
-  }));
-
-  return (
-    <Show when={props.context}>
-      <Context
-        usedTokens={props.context!.usedTokens}
-        maxTokens={props.context!.maxTokens}
-        inputTokens={props.context!.inputTokens}
-        outputTokens={props.context!.outputTokens}
-        reasoningTokens={props.context!.reasoningTokens}
-        cacheTokens={props.context!.cacheTokens}
-        estimatedCost={props.context!.estimatedCost}
-        warnThreshold={warn()}
-        dangerThreshold={danger()}
-      >
-        <ContextTrigger />
-        <ContextContent>
-          <ContextContentHeader />
-          <ContextContentBody>
-            <div class="space-y-1.5">
-              <ContextInputUsage />
-              <ContextOutputUsage />
-              <Show when={props.context!.reasoningTokens}><ContextReasoningUsage /></Show>
-              <Show when={props.context!.cacheTokens}><ContextCacheUsage /></Show>
-            </div>
-          </ContextContentBody>
-          <ContextContentFooter />
-        </ContextContent>
-      </Context>
-    </Show>
-  );
-});

package/src/elements/conversation-item.tsx

@@ -1,120 +0,0 @@
-import { createSignal, onCleanup, onMount } from 'solid-js';
-import { defineWebComponent } from './define';
-import { readSlots, CONVERSATION_ITEM_SLOTS } from './slots';
-import { SlottedConversationItem } from '../components/conversation-item';
-import { isStandaloneConversationItem, readConversationItemId } from '../components/conversation-list';
-
-interface Props extends Record<string, unknown> {
-  /** The row's identity: the `conversation-id` attribute (host `id` is the
-   *  fallback). Inside `<kai-conversations>` it is handed to the container's
-   *  selection contract (`kai-conversation-select`); standalone it is the `id`
-   *  in this element's own `kai-select` detail. */
-  conversationId?: string;
-  /** Selected state. Reflected as `aria-current` on the row body and a
-   *  `data-active` styling hook on the row; inside a container the container
-   *  drives it from its `activeId`, standalone you set it yourself. */
-  active?: boolean;
-  /** Dense single-line row padding. */
-  compact?: boolean;
-}
-
-interface Events {
-  /** STANDALONE activation only: the row was activated (click, Enter or Space on its body) while the item is NOT a
-   *  direct child of `<kai-conversations>`. `id` is the row's identity: the
-   *  `conversation-id` attribute, else the host `id`. Inside a container this
-   *  never fires: activation surfaces once, as `kai-conversation-select` on the
-   *  container. */
-  'kai-select': { id: string };
-}
-
-/**
- * `<kai-conversation-item>` — one composed row of a consumer-owned conversation
- * loop. Two placements, one activation event each:
- *
- * SLOTTED into `<kai-conversations>`' light DOM (a direct child): the consumer
- * owns the loop (framework-native `map`, `<For>`, `v-for`); the container
- * detects these children, skips its data rendering, and runs the parent-item
- * contract over them — selection state flowing container to item, roving
- * tabindex, arrow-key traversal, and the accessible list/row relationship
- * (list rows with button bodies and `aria-current` marking the active one;
- * axe's nested-interactive and aria-required-children
- * rules are why this is not listbox/option). Activation (click, Enter, Space)
- * surfaces as `kai-conversation-select` on the container, and the item itself
- * fires nothing — no double event.
- *
- * STANDALONE (anywhere else — a hand-composed rail, or wrapped in another
- * element even inside a container, since the container manages only direct
- * children): the row activates ITSELF.
- * Its shadow body is a tabbable `role="button"`, and click / Enter / Space
- * fire `kai-select` on this element with `{ id }` — non-bubbling, like every
- * `kai-*` event, so listen on the item itself. What a standalone row does NOT
- * have is the container's LIST story: roving tabindex across rows, arrow-key
- * traversal, and the shared `role="list"` relationship — each standalone row
- * is an ordinary tab stop, and a hand-composed rail brings its own list
- * semantics (or slots the rows into `<kai-conversations>` and gets them for
- * free).
- *
- * Slots: the default slot is the title; `leading`, `meta` and `menu` are the
- * named regions. The `menu` slot takes your OWN popover (rename, fork, archive
- * live there); the element provides only the region plus focus and ARIA
- * plumbing, never a declarative actions prop, and a click inside it never
- * selects the row — in either placement.
- */
-defineWebComponent<Props, Events>('kai-conversation-item', {
-  conversationId: undefined,
-  active: undefined,
-  compact: undefined,
-}, (props, { element, flag, reflectFlag, dispatch }) => {
-  // Which named regions the consumer has filled; drives the conditional
-  // wrappers so an empty region leaves no stray box behind.
-  const [slots, setSlots] = createSignal<Record<string, boolean>>({});
-  // Standalone vs container-managed, decided at mount (an item is not
-  // reparented in practice; the activation handler re-checks at event time so
-  // a row moved INTO a container can never double-fire).
-  const [standalone, setStandalone] = createSignal(false);
-  onMount(() => {
-    const read = () => setSlots(readSlots(element, CONVERSATION_ITEM_SLOTS));
-    read();
-    const observer = new MutationObserver(read);
-    observer.observe(element, { childList: true, attributes: true, subtree: true });
-    onCleanup(() => observer.disconnect());
-
-    // The HOST is the row LISTITEM:
-    // it wraps the activation body AND the consumer's tabbable menu, so it must
-    // never be the activation control itself — axe nested-interactive bans
-    // focusable descendants of a control. The button role, aria-current and the
-    // tabindex live on the shadow BODY (`data-kai-item-body`): inside a
-    // container its controller stamps them; standalone the component renders
-    // them itself. An authored role wins.
-    if (!element.hasAttribute('role')) element.setAttribute('role', 'listitem');
-
-    setStandalone(isStandaloneConversationItem(element));
-  });
-
-  // Standalone activation → the per-item `kai-select` event. The re-check at
-  // event time keeps this dead the moment the item becomes a container's direct
-  // child, so the container's `kai-conversation-select` stays the only event.
-  const activate = () => {
-    if (!isStandaloneConversationItem(element)) return;
-    dispatch('kai-select', { id: readConversationItemId(element) });
-  };
-
-  // Property and attribute stay in agreement for `active`; the body's
-  // aria-current follows it reactively (nothing is written to the host).
-  reflectFlag('active');
-
-  return (
-    <SlottedConversationItem
-      conversationId={props.conversationId as string | undefined}
-      active={flag('active')}
-      compact={flag('compact')}
-      hostSemantics
-      onActivate={standalone() ? activate : undefined}
-      leading={slots().leading ? <slot name="leading" /> : undefined}
-      meta={slots().meta ? <slot name="meta" /> : undefined}
-      menu={slots().menu ? <slot name="menu" /> : undefined}
-    >
-      <slot />
-    </SlottedConversationItem>
-  );
-});

package/src/elements/conversation-list.tsx

@@ -1,203 +0,0 @@
-import { createSignal, createEffect, onMount, onCleanup, Show } from 'solid-js';
-import { defineWebComponent } from './define';
-import { createControllableSignal } from '../primitives/controllable';
-import { readSlots, CONVERSATIONS_SLOTS } from './slots';
-import {
-  ConversationList, CollapsedRail, createConversationItemsController,
-  type ConversationListController,
-} from '../components/conversation-list';
-import type { ConversationGroup, ConversationSummary } from '../types';
-
-interface Props extends Record<string, unknown> {
-  /** The list's section headers (`{ id, name, sortOrder, createdAt }`), rendered
-   *  in array order. A group carries no conversations of its own; it is matched
-   *  against `conversations` by id, so the two props are complementary rather
-   *  than alternatives. Omit for an ungrouped list. Set as a JS property. */
-  groups?: ConversationGroup[];
-  /** Every conversation the list renders, flat. Each one is filed under the group
-   *  whose `id` equals its `groupId`; one with no `groupId`, or with a `groupId`
-   *  matching no entry in `groups`, falls into a trailing "Ungrouped" section, so
-   *  nothing you pass in is ever dropped. There is no recency bucketing. Set as a
-   *  JS property. Omit to supply them as `<kai-conversation>` light-DOM children
-   *  instead, or for the empty state. A search query that matches nothing shows a
-   *  visible "No conversations match your search" state, distinct from the
-   *  zero-conversations empty state. Slotted `<kai-conversation-item>` children
-   *  switch the list into item mode instead: your own rows win and this array is
-   *  not rendered. */
-  conversations?: ConversationSummary[];
-  /** The id of the currently-open conversation, highlighted in the list. */
-  activeId?: string;
-  /** Controlled collapsed state. Set as a JS property (`el.collapsed = true`) to
-   *  drive the rail from your app, updating it in response to `kai-collapse-toggle`.
-   *  Omit for uncontrolled (the element manages it). Collapsed shrinks the rail to
-   *  a floating reopen button. */
-  collapsed?: boolean;
-  /** Initial collapsed state when uncontrolled (default false). Use the
-   *  `default-collapsed` attribute to start collapsed in plain HTML. */
-  defaultCollapsed?: boolean;
-  /** Dense single-line rows (a leading dot + title, no message count). */
-  compact?: boolean;
-}
-
-interface Events {
-  /** A conversation was selected. The selection event in BOTH modes: a
-   *  batteries data row, or an activated `<kai-conversation-item>` child
-   *  (click, Enter or Space). */
-  'kai-conversation-select': { id: string };
-  /** The "New chat" button was clicked. */
-  'kai-new-chat': Record<string, never>;
-  /** The sidebar toggle was clicked. */
-  'kai-toggle-sidebar': Record<string, never>;
-  /** The rail was collapsed or expanded (via the toggle, the reopen button, or a
-   *  `collapse()`/`expand()`/`toggle()` call). */
-  'kai-collapse-toggle': { collapsed: boolean };
-  /** The built-in search box query changed (typing, or a programmatic `clear()`
-   *  which fires it with `''`). Lets a consumer mirror or server-side the filter. */
-  'kai-search': { query: string };
-}
-
-/** Parse a single light-DOM `<kai-conversation>` element into a `ConversationSummary`.
- *  Attribute mapping:
- *   - `id`       → ConversationSummary.id
- *   - `group-id` → ConversationSummary.groupId (optional)
- *   - textContent → ConversationSummary.title
- *  Fields not expressible as HTML attributes are NOT fabricated: the
- *  optional `scope` and `lastMessageAt` stay absent, and the required
- *  `messageCount`/`updatedAt` get honest defaults — zero messages, and an empty
- *  `updatedAt` from which no trailing relative time is derived (the epoch it
- *  used to fabricate rendered a bogus "many days ago" on every declarative row).
- */
-export function parseKaiConversationElement(n: Element): ConversationSummary {
-  return {
-    id: n.getAttribute('id') ?? '',
-    title: n.textContent?.trim() ?? '',
-    groupId: n.getAttribute('group-id') ?? undefined,
-    messageCount: 0,
-    updatedAt: '',
-  };
-}
-
-defineWebComponent<Props, Events>('kai-conversations', {
-  groups: [],
-  conversations: [],
-  activeId: undefined,
-  collapsed: undefined,
-  defaultCollapsed: undefined,
-  compact: undefined,
-}, (props, { dispatch, element, expose, flag }) => {
-  // Read declarative <kai-conversation> children from light DOM.
-  // Shadow DOM with no <slot> suppresses them visually — they're invisible data carriers.
-  const [slottedConversations, setSlottedConversations] = createSignal<ConversationSummary[]>([]);
-  // Item mode: light-DOM <kai-conversation-item> children
-  // mean the CONSUMER owns the loop — the container skips its data rendering and
-  // runs the parent-item contract over the hosts instead.
-  const [itemHosts, setItemHosts] = createSignal<HTMLElement[]>([]);
-  // Which composition slots (header/empty/footer) the consumer has filled.
-  const [slots, setSlots] = createSignal<Record<string, boolean>>({});
-  onMount(() => {
-    const read = () => {
-      const nodes = [...element.querySelectorAll('kai-conversation')];
-      setSlottedConversations(nodes.map(parseKaiConversationElement));
-      // Reference-stable: a fresh array every observer tick would re-run the
-      // sync effect (whose writes the observer sees) in a feedback loop.
-      const hosts = [...element.querySelectorAll<HTMLElement>(':scope > kai-conversation-item')];
-      setItemHosts((prev) =>
-        prev.length === hosts.length && hosts.every((h, i) => h === prev[i]) ? prev : hosts,
-      );
-      setSlots(readSlots(element, CONVERSATIONS_SLOTS));
-      // Re-sync on EVERY mutation, not only membership changes: an item host
-      // that upgrades after the first sync mutates its own attributes (the
-      // facade's mount), which lands here — and its shadow body needs stamping
-      // even though the hosts array is reference-stable. sync() writes
-      // on-change only, so this cannot feed the observer a loop.
-      if (hosts.length) itemsController.sync();
-    };
-    read();
-    const observer = new MutationObserver(read);
-    observer.observe(element, { childList: true, attributes: true, subtree: true });
-    onCleanup(() => observer.disconnect());
-  });
-
-  const itemMode = () => itemHosts().length > 0;
-
-  // Prop conversations take precedence; slotted children are appended after.
-  const allConversations = () => [...(props.conversations ?? []), ...slottedConversations()];
-
-  // The parent-item contract: selection flowing container→item, roving tabindex,
-  // ARIA list-row bookkeeping — pure DOM, host-agnostic (see the controller's JSDoc in
-  // components/conversation-list.tsx). Solid context cannot cross the element
-  // boundary, so the channel is DOM traversal by construction.
-  const itemsController = createConversationItemsController({
-    getItems: itemHosts,
-    getActiveId: () => props.activeId as string | undefined,
-    onSelect: (id) => dispatch('kai-conversation-select', { id }),
-  });
-  // Re-derive the bookkeeping whenever the children change (the MutationObserver
-  // and the shadow slot's slotchange both funnel into itemHosts) or activeId moves.
-  createEffect(() => {
-    if (itemMode()) itemsController.sync();
-  });
-
-  // ── Rail collapse (controlled/uncontrolled, same pattern as kai-workspace) ──
-  // `collapsed` (when set) wins; otherwise the element manages its own state,
-  // seeded from `defaultCollapsed`. `setCollapsedTo` always writes the internal
-  // value (a no-op visually while controlled) and emits `kai-collapse-toggle` so
-  // a controlling app can update its own state. Collapsed → the shared
-  // CollapsedRail (the same floating reopen button kai-workspace renders).
-  const [collapsed, setCollapsed] = createControllableSignal(
-    () => props.collapsed as boolean | undefined,
-    flag('defaultCollapsed'),
-  );
-  const setCollapsedTo = (next: boolean) => { setCollapsed(next); dispatch('kai-collapse-toggle', { collapsed: next }); };
-
-  // ── Imperative API (instance methods on the host) ──────────────────────────
-  // The search box's query lives inside ConversationList; we capture its
-  // controller (Pattern C) to focus / clear it from the facade.
-  let controller: ConversationListController | undefined;
-  expose({
-    /** Focus the built-in search input inside the shadow root. */
-    focus: (options?: FocusOptions) => {
-      // Prefer the captured controller; fall back to a shadow query (the search
-      // box only renders when there are conversations).
-      if (controller) controller.focus(options);
-      else element.shadowRoot?.querySelector<HTMLInputElement>('input')?.focus(options);
-    },
-    /** Clear the internal search query (resets the list filter) and fire
-     *  kai-search with an empty string. */
-    clear: () => controller?.clearSearch(),
-    /** Programmatically select a conversation by id. The mirror of the
-     *  kai-conversation-select event (a convenience over driving `activeId`). */
-    select: (id: string) => dispatch('kai-conversation-select', { id }),
-    /** Collapse the rail to its floating reopen button (fires `kai-collapse-toggle`). */
-    collapse: () => setCollapsedTo(true),
-    /** Expand the rail back to the full list (fires `kai-collapse-toggle`). */
-    expand: () => setCollapsedTo(false),
-    /** Toggle the rail collapsed/expanded (fires `kai-collapse-toggle`). */
-    toggle: () => setCollapsedTo(!collapsed()),
-  });
-
-  return (
-    <Show
-      when={!collapsed()}
-      fallback={<CollapsedRail onExpand={() => setCollapsedTo(false)} />}
-    >
-      <ConversationList
-        groups={props.groups ?? []}
-        conversations={allConversations()}
-        activeId={props.activeId}
-        onSelect={(id) => dispatch('kai-conversation-select', { id })}
-        onNewChat={() => dispatch('kai-new-chat')}
-        onToggleSidebar={() => { dispatch('kai-toggle-sidebar'); setCollapsedTo(true); }}
-        compact={flag('compact')}
-        onSearchChange={(query) => dispatch('kai-search', { query })}
-        controllerRef={(c) => (controller = c)}
-        items={itemMode() ? <slot /> : undefined}
-        itemsKeyDown={itemsController.handleKeyDown}
-        itemsClick={itemsController.handleClick}
-        header={slots().header ? <slot name="header" /> : undefined}
-        footer={slots().footer ? <slot name="footer" /> : undefined}
-        empty={slots().empty ? <slot name="empty" /> : undefined}
-      />
-    </Show>
-  );
-});