@kitn.ai/ui 0.16.0 → 0.18.0

package/src/elements/voice-input.tsx

@@ -1,5 +1,5 @@
 import { defineWebComponent } from './define';
-import { VoiceInput } from '../components/voice-input';
+import { VoiceInput, type VoiceInputController } from '../components/voice-input';
 
 interface Props extends Record<string, unknown> {
   /**
@@ -10,32 +10,82 @@ interface Props extends Record<string, unknown> {
   transcribe?: (audio: Blob) => Promise<string>;
   /** Disable the mic button (non-interactive). */
   disabled?: boolean;
+  /**
+   * BCP-47 language tag for the native `SpeechRecognition` path (e.g. `en-US`).
+   * Attribute: `recognition-lang` (the plain `lang` attribute is reserved by
+   * `HTMLElement` and can't be a custom-element property). No effect when
+   * `transcribe` is set or the browser lacks SpeechRecognition.
+   */
+  recognitionLang?: string;
+  /** Emit live partial transcripts (`kai-transcript-interim`) during native
+   *  recognition. Attribute: `interim`. No-op on the transcribe/fallback paths. */
+  interim?: boolean;
 }
 
 /** Events fired by `<kai-voice-input>`. */
 interface Events {
   /** Raw audio captured (before transcription) — for hosts that prefer to
-   *  handle transcription themselves instead of via the `transcribe` property. */
+   *  handle transcription themselves instead of via the `transcribe` property.
+   *  Also the unsupported-fallback signal: no `transcribe`, no SpeechRecognition,
+   *  so only the blob is produced (no text). */
   'kai-audio-captured': { blob: Blob };
-  /** Transcription completed (the `transcribe` property resolved). */
+  /** Final transcript — the `transcribe` property resolved, OR native
+   *  `SpeechRecognition` produced final text (no `transcribe` set). */
   'kai-transcription': { text: string };
+  /** Live partial transcript during native recognition (only when `interim` is
+   *  set). Fires repeatedly before the final `kai-transcription`. */
+  'kai-transcript-interim': { text: string };
+  /** Recording started or stopped — lets the host drive its own UI (waveform,
+   *  push-to-talk indicator) in sync with the mic. Fires on real transitions
+   *  only (manual click and programmatic start()/stop()), never on mount. */
+  'kai-recording-change': { recording: boolean };
 }
 
 /**
- * `<kai-voice-input>` — a mic button that records and transcribes. The
- * canonical **function-property** element: set `el.transcribe` to your async
- * transcriber. Also emits `kai-audio-captured` (raw blob) and `kai-transcription` (text).
+ * `<kai-voice-input>` — a mic button that records and transcribes. Works
+ * natively by default: with no `transcribe` callback it uses the browser's
+ * `SpeechRecognition` (Chrome/Safari; no Firefox — and cloud-based in Chrome).
+ * Set `el.transcribe` to route audio through your own async transcriber instead.
+ * Where neither is available it records the blob and emits `kai-audio-captured`
+ * with no text. Also emits `kai-transcription` (final text) and, with `interim`,
+ * `kai-transcript-interim` (live partials).
  */
 defineWebComponent<Props, Events>('kai-voice-input', {
   transcribe: undefined,
   disabled: false,
-}, (props, { dispatch, flag }) => (
-  <VoiceInput
-    disabled={flag('disabled')}
-    onTranscribe={async (blob) => {
-      dispatch('kai-audio-captured', { blob });
-      return props.transcribe ? props.transcribe(blob) : '';
-    }}
-    onTranscription={(text) => dispatch('kai-transcription', { text })}
-  />
-));
+  recognitionLang: undefined,
+  interim: false,
+}, (props, { dispatch, flag, expose }) => {
+  // Pattern C: the VoiceInput component owns useVoiceRecorder; it hands up a
+  // start/stop controller and an onRecordingChange callback. The facade captures
+  // the controller and exposes delegating methods (start/stop both run the same
+  // record→transcribe path as the mic click, so manual + programmatic emit the
+  // same kai-audio-captured/kai-transcription/kai-recording-change events).
+  let controller: VoiceInputController | undefined;
+  expose({
+    /** Begin recording programmatically (e.g. push-to-talk bound to a global
+     *  key). Runs the same getUserMedia path as clicking the mic; no-ops if
+     *  already recording. */
+    start: () => controller?.start(),
+    /** Stop the in-progress recording, producing the blob (→ kai-audio-captured)
+     *  and running transcription. Pairs with start() for push-to-talk. */
+    stop: () => controller?.stop(),
+  });
+
+  return (
+    <VoiceInput
+      disabled={flag('disabled')}
+      hasTranscribe={typeof props.transcribe === 'function'}
+      lang={props.recognitionLang}
+      interim={flag('interim')}
+      onTranscribe={async (blob) => {
+        dispatch('kai-audio-captured', { blob });
+        return props.transcribe ? props.transcribe(blob) : '';
+      }}
+      onTranscription={(text) => dispatch('kai-transcription', { text })}
+      onInterim={(text) => dispatch('kai-transcript-interim', { text })}
+      onRecordingChange={(recording) => dispatch('kai-recording-change', { recording })}
+      controllerRef={(c) => (controller = c)}
+    />
+  );
+});

package/src/elements/voice-output.tsx

@@ -0,0 +1,69 @@
+import { defineWebComponent } from './define';
+import { VoiceOutput, type VoiceOutputController } from '../components/voice-output';
+
+interface Props extends Record<string, unknown> {
+  /** The utterance to read aloud. */
+  text?: string;
+  /** Speak automatically when `text` is set/changed. */
+  autoplay?: boolean;
+  /**
+   * TTS model seam the host supplies — given text, returns an audio `Blob` to
+   * play. This is a **function-valued property** (`el.synthesize = async text =>
+   * blob`); when set, the native `speechSynthesis` path is bypassed. Mirrors
+   * `<kai-voice-input>`'s `transcribe`. A value-returning callback can't be
+   * modelled as a fire-and-forget event, hence a property.
+   */
+  synthesize?: (text: string) => Promise<Blob>;
+  /** Disable the button (non-interactive). */
+  disabled?: boolean;
+}
+
+/** Events fired by `<kai-voice-output>`. */
+interface Events {
+  /** Playback started or stopped — drive your own UI in sync. Fires on real
+   *  transitions only (manual click and programmatic speak()/stop()), never on mount. */
+  'kai-speaking-change': { speaking: boolean };
+  /** The model path (`synthesize`) resolved audio — the raw `Blob` before playback. */
+  'kai-synthesized': { blob: Blob };
+}
+
+/**
+ * `<kai-voice-output>` — a speaker button that reads `text` aloud. Native by
+ * default (`speechSynthesis`); set `el.synthesize` to route through your TTS
+ * model instead. The output sibling of `<kai-voice-input>`. Emits
+ * `kai-speaking-change` and (model path) `kai-synthesized`.
+ */
+defineWebComponent<Props, Events>('kai-voice-output', {
+  text: '',
+  autoplay: false,
+  synthesize: undefined,
+  disabled: false,
+}, (props, { dispatch, flag, expose }) => {
+  // Pattern C: the VoiceOutput component owns playback; it hands up a
+  // speak/pause/resume/stop controller. The facade captures it and exposes
+  // delegating methods (manual + programmatic run the same path, so both emit
+  // the same kai-speaking-change / kai-synthesized events).
+  let controller: VoiceOutputController | undefined;
+  expose({
+    /** Speak the current `text` (native, or via `synthesize` if set). */
+    speak: () => controller?.speak(),
+    /** Pause playback (resumable). */
+    pause: () => controller?.pause(),
+    /** Resume paused playback. */
+    resume: () => controller?.resume(),
+    /** Stop playback and reset. */
+    stop: () => controller?.stop(),
+  });
+
+  return (
+    <VoiceOutput
+      text={(props.text as string | undefined) ?? ''}
+      autoplay={flag('autoplay')}
+      disabled={flag('disabled')}
+      onSynthesize={props.synthesize ? (text) => props.synthesize!(text) : undefined}
+      onSpeakingChange={(speaking) => dispatch('kai-speaking-change', { speaking })}
+      onSynthesized={(blob) => dispatch('kai-synthesized', { blob })}
+      controllerRef={(c) => (controller = c)}
+    />
+  );
+});

package/src/index.ts

@@ -5,6 +5,8 @@ export type { ModelOption, SearchFilters, ConversationScope, ConversationSummary
 export { cn } from './utils/cn';
 
 // Layer 1: Headless Primitives
+export { createKaiChat } from './primitives/create-kai-chat';
+export type { CreateKaiChatOptions, KaiChatStore } from './primitives/create-kai-chat';
 export { useAutoResize } from './primitives/use-auto-resize';
 export { useStickToBottom } from './primitives/use-stick-to-bottom';
 export { useTextStream } from './primitives/use-text-stream';
@@ -18,6 +20,16 @@ export type { CodeHighlightingOptions } from './primitives/highlighter';
 export { configurePdfPreview, isPdfPreviewEnabled } from './primitives/pdf-preview';
 export type { PdfPreviewOptions } from './primitives/pdf-preview';
 
+// Toasts: imperative `toast()` API + the reactive store behind <kai-toast-region>
+export { toast, configureToasts, ensureMounted as ensureToastRegion, getToasts } from './primitives/toast-store';
+export type {
+  ToastItem, ToastVariant, ToastAction, ToastOptions, ToastHandle, ToastFn, ToastConfig,
+} from './primitives/toast-store';
+export { Toast, ToastRegion } from './components/toast';
+export type {
+  ToastRegionProps, ToastDismissReason, ToastPosition,
+} from './components/toast';
+
 // Card Contract (generative-UI foundation)
 export { CARD_CONTRACT_VERSION } from './primitives/card-contract';
 export type {
@@ -27,6 +39,10 @@ export { applyResolution, resolutionFromEvent } from './primitives/card-resoluti
 export { CardProvider, useCardHost } from './primitives/card-host';
 export type { CardProviderProps } from './primitives/card-host';
 export { CARD_EVENT_NAME, emitCardEvent, routeCardEvent, listenForCardEvents } from './primitives/card-routing';
+export { dismissRecovery, defaultIsReopenable } from './primitives/card-recovery';
+export type {
+  RecoveryToast, ReopenEnv, DismissRecoveryOptions,
+} from './primitives/card-recovery';
 export { validateAgainstSchema } from './primitives/card-validate';
 export type { JsonSchema, ValidationResult } from './primitives/card-validate';
 
@@ -47,6 +63,8 @@ export type { CardComponent, CardComponentMap, CardTagMap } from './primitives/c
 // Card: kai-card (base shell) + kai-form (JSON-Schema form renderer)
 export { Card } from './components/card';
 export type { CardProps } from './components/card';
+export { DismissedStub, stubIntent } from './components/dismissed-stub';
+export type { DismissedStubProps, DismissedCardType } from './components/dismissed-stub';
 export { Form, validateForm, buildResult, widgetFor, orderedKeys, coerceValue } from './components/form';
 export type {
   FormProps,
@@ -168,14 +186,26 @@ export {
 } from './components/chat-container';
 export { Message, MessageAvatar, MessageContent, MessageActions, MessageAction, MessageCopyButton } from './components/message';
 export type { MessageCopyButtonProps } from './components/message';
+export { ResponseCompare, useResolved } from './components/response-compare';
+export type { ResponseCompareProps, CompareLayout, ResolvedController } from './components/response-compare';
+export {
+  normalizeCandidates,
+  buildSelection,
+  isAnyStreaming,
+} from './components/response-compare';
+export type {
+  CompareCandidate,
+  ComparePair,
+  CompareCollapse,
+  ResponseCompareData,
+  CompareSelection,
+} from './components/response-compare';
 export { MessageSkills } from './components/message-skills';
 export type { Skill as MessageSkill } from './components/message-skills';
 export {
   PromptInput, PromptInputTextarea, PromptInputActions, PromptInputAction,
   usePromptInput,
 } from './components/prompt-input';
-export { SlashCommand } from './components/slash-command';
-export type { SlashCommandItem, SlashCommandProps } from './components/slash-command';
 export { ResponseStream } from './components/response-stream';
 export { Markdown } from './components/markdown';
 export { CodeBlock, CodeBlockCode, CodeBlockGroup } from './components/code-block';
@@ -251,3 +281,6 @@ export type {
   AttachmentInfoProps, AttachmentRemoveProps, AttachmentEmptyProps,
   AttachmentHoverCardProps, AttachmentHoverCardTriggerProps, AttachmentHoverCardContentProps,
 } from './components/attachments';
+
+// Chat message types — public API for consumers who need to type their own message arrays.
+export type { ChatMessage, ChatMessageAction, CustomAction, AvatarData, FeedbackVote } from './elements/chat-types';

package/src/primitives/card-contract.ts

@@ -38,18 +38,24 @@ export type CardEvent =
   | { kind: 'resize'; cardId: string; height: number }
   | { kind: 'state'; cardId: string; patch: unknown }
   | { kind: 'dismiss'; cardId: string }
+  | { kind: 'reopen'; cardId: string }
   | { kind: 'error'; cardId: string; message: string };
 
 export type CardEventKind = CardEvent['kind'];
 
 /** How a card was resolved by the user — the re-hydration channel for the chromed
- *  read-only state. Mirrors the two terminal CardEvents (minus `cardId`): the
- *  resolution is just the event that resolved the card. `at` is optional ISO-8601
- *  provenance (data only; never rendered). Additive — does not bump the contract
- *  version. */
+ *  read-only state. The terminal kinds (`action`/`submit`) mirror the two terminal
+ *  CardEvents (minus `cardId`): the resolution is just the event that resolved the
+ *  card. `dismissed` is a DEFERRED (non-terminal) state — the user set the card
+ *  aside; it can be re-opened. `expired` is terminal — a dismissed card the host
+ *  decided can no longer be re-opened (e.g. the agent proceeded, or it went stale).
+ *  `at` is optional ISO-8601 provenance (data only; never rendered). Additive —
+ *  does not bump the contract version. */
 export type CardResolution =
   | { kind: 'action'; action: string; payload?: unknown; at?: string }
-  | { kind: 'submit'; data: unknown; at?: string };
+  | { kind: 'submit'; data: unknown; at?: string }
+  | { kind: 'dismissed'; at?: string }
+  | { kind: 'expired'; reason?: string; at?: string };
 
 /** What every card is handed (via native context or the iframe bridge). */
 export interface CardHost {
@@ -65,6 +71,9 @@ export interface CardPolicy {
   onOpen?: (url: string, target: 'tab' | 'artifact') => void;
   onState?: (cardId: string, patch: unknown) => void;
   onDismiss?: (cardId: string) => void;
+  /** A dismissed card asked to be re-opened. The host decides whether it can come
+   *  back (clear the resolution → live again) or has expired (stamp `expired`). */
+  onReopen?: (cardId: string) => void;
   onError?: (cardId: string, message: string) => void;
   /** Cap on send-prompt: 'compose' (default) forbids silent sends. 'send' to allow. */
   maxSendPromptMode?: 'compose' | 'send';

package/src/primitives/card-recovery.ts

@@ -0,0 +1,149 @@
+// src/primitives/card-recovery.ts
+// Recovery glue for the card dismiss/reopen flow. `dismissRecovery` builds the
+// `{ onDismiss, onReopen }` half of a CardPolicy for a host that keeps its cards in
+// some store: it writes a `dismissed` resolution onto the matching envelope (a NEW
+// array reference, never an in-place mutation, so a Solid/React host re-renders),
+// optionally shows an injected "Dismissed · Undo" toast (Undo restores the prior
+// resolution), and on reopen decides — via `isReopenable` — whether the card comes
+// back live (resolution cleared) or `expired`.
+//
+// The toast is an INJECTED ADAPTER, never an import — cards (and this helper) stay
+// decoupled from the toast module. The re-appear rule is the host's: "the agent
+// already proceeded" is a host fact, surfaced through `isReopenable`.
+import type { CardEnvelope, CardPolicy, CardResolution } from './card-contract';
+
+/** The minimal toast surface this helper needs. Inject a real adapter (e.g. one
+ *  backed by `kai-toast-region`) — this module never imports the toast itself. */
+export interface RecoveryToast {
+  show(opts: {
+    message: string;
+    action?: { label: string; onClick: () => void };
+    durationMs?: number;
+  }): { dismiss(): void };
+}
+
+/** Context handed to a custom `isReopenable` predicate. */
+export interface ReopenEnv {
+  cardId: string;
+  /** The card's current resolution at reopen time (should be `dismissed`). */
+  resolution: CardResolution | undefined;
+  /** `Date.now()` at reopen time (injected for testability). */
+  now: number;
+}
+
+export interface DismissRecoveryOptions {
+  /** Read the current cards array. */
+  get: () => CardEnvelope[];
+  /** Write the next cards array (a NEW reference). */
+  set: (next: CardEnvelope[]) => void;
+  /** Optional injected toast adapter for the "Dismissed · Undo" affordance. */
+  toast?: RecoveryToast;
+  /** Override the default re-openable rule. Return false to expire instead. */
+  isReopenable?: (env: ReopenEnv) => boolean;
+  /** A dismissed card older than this (ms since `dismissed.at`) is no longer
+   *  re-openable (→ expired). Omit/Infinity = never stale. */
+  staleAfterMs?: number;
+  /** Auto-dismiss the Undo toast after this long. Default 6000ms. */
+  undoMs?: number;
+  /** Injected clock (defaults to Date.now); keeps the helper testable. */
+  now?: () => number;
+}
+
+/** The terminal resolution kinds that block a reopen (a finished card can't come back). */
+const TERMINAL_KINDS = new Set<CardResolution['kind']>(['action', 'submit', 'expired']);
+
+/** Default re-openable rule: a card can come back unless it carries a terminal
+ *  resolution OR it has gone stale (`staleAfterMs` elapsed since `dismissed.at`).
+ *  A `dismissed` card with no/invalid `at` is always re-openable. */
+export function defaultIsReopenable(env: ReopenEnv, staleAfterMs?: number): boolean {
+  const r = env.resolution;
+  if (r && TERMINAL_KINDS.has(r.kind)) return false;
+  if (
+    staleAfterMs !== undefined &&
+    Number.isFinite(staleAfterMs) &&
+    r?.kind === 'dismissed' &&
+    typeof r.at === 'string'
+  ) {
+    const at = Date.parse(r.at);
+    if (!Number.isNaN(at) && env.now - at >= staleAfterMs) return false;
+  }
+  return true;
+}
+
+/** Return a new cards array with `cardId`'s envelope stamped with `resolution`
+ *  (or cleared when `resolution` is undefined). Same reference if nothing changed. */
+function withResolution(
+  cards: CardEnvelope[],
+  cardId: string,
+  resolution: CardResolution | undefined,
+): CardEnvelope[] {
+  let changed = false;
+  const next = cards.map((c) => {
+    if (c.id !== cardId) return c;
+    changed = true;
+    if (resolution === undefined) {
+      if (c.resolution === undefined) return c;
+      const { resolution: _drop, ...rest } = c;
+      return rest;
+    }
+    return { ...c, resolution };
+  });
+  return changed ? next : cards;
+}
+
+/** The current resolution on `cardId`, if any. */
+function resolutionOf(cards: CardEnvelope[], cardId: string): CardResolution | undefined {
+  return cards.find((c) => c.id === cardId)?.resolution;
+}
+
+/**
+ * Build the `{ onDismiss, onReopen }` policy handlers for the card dismiss/recovery
+ * flow over a host store (`get`/`set`).
+ *
+ * - `onDismiss(cardId)` — stamps `{ kind:'dismissed', at }` immutably and, when a
+ *   `toast` is injected, shows "Dismissed" with an Undo that restores the card's
+ *   prior resolution (live again when there was none).
+ * - `onReopen(cardId)` — clears the resolution (live) when `isReopenable`, else
+ *   stamps `{ kind:'expired', at }`.
+ */
+export function dismissRecovery(
+  opts: DismissRecoveryOptions,
+): Pick<CardPolicy, 'onDismiss' | 'onReopen'> {
+  const now = opts.now ?? (() => Date.now());
+  const reopenable = opts.isReopenable ?? ((env: ReopenEnv) => defaultIsReopenable(env, opts.staleAfterMs));
+  const undoMs = opts.undoMs ?? 6000;
+
+  const onDismiss = (cardId: string): void => {
+    const before = opts.get();
+    const prior = resolutionOf(before, cardId);
+    const dismissed: CardResolution = { kind: 'dismissed', at: new Date(now()).toISOString() };
+    opts.set(withResolution(before, cardId, dismissed));
+
+    opts.toast?.show({
+      message: 'Dismissed',
+      durationMs: undoMs,
+      action: {
+        label: 'Undo',
+        onClick: () => {
+          // Restore the prior resolution (undefined → live again). Read fresh in
+          // case the store moved on; only touch this card.
+          opts.set(withResolution(opts.get(), cardId, prior));
+        },
+      },
+    });
+  };
+
+  const onReopen = (cardId: string): void => {
+    const before = opts.get();
+    const current = resolutionOf(before, cardId);
+    const env: ReopenEnv = { cardId, resolution: current, now: now() };
+    if (reopenable(env)) {
+      opts.set(withResolution(before, cardId, undefined));
+    } else {
+      const expired: CardResolution = { kind: 'expired', at: new Date(now()).toISOString() };
+      opts.set(withResolution(before, cardId, expired));
+    }
+  };
+
+  return { onDismiss, onReopen };
+}

package/src/primitives/card-routing.ts

@@ -59,6 +59,9 @@ export function routeCardEvent(policy: CardPolicy | undefined, event: CardEvent)
     case 'dismiss':
       p.onDismiss ? p.onDismiss(event.cardId) : warnNoHandler('dismiss');
       break;
+    case 'reopen':
+      p.onReopen ? p.onReopen(event.cardId) : warnNoHandler('reopen');
+      break;
     case 'error':
       p.onError ? p.onError(event.cardId, event.message) : warnNoHandler('error');
       break;

package/src/primitives/card-schemas/choice.schema.json

@@ -65,6 +65,11 @@
     "allowOther": {
       "description": "Optional free-text escape ('none of these / specify'). `true` appends a final 'Other…' option; an object customizes its `label`/`placeholder`. Selecting it reveals a text input; the shared Submit button then emits `{ kind:'action', action:'__other__', payload:{ text } }`.",
       "x-kai-control": "allow-other"
+    },
+    "dismissible": {
+      "type": "boolean",
+      "default": false,
+      "description": "Show a close affordance that emits the `dismiss` verb. The card collapses to a re-openable 'dismissed' stub; the host decides via `onReopen` whether it comes back live or `expired`."
     }
   }
 }

package/src/primitives/card-schemas/tasks.schema.json

@@ -8,9 +8,9 @@
   "properties": {
     "mode": {
       "type": "string",
-      "enum": ["select"],
+      "enum": ["select", "progress"],
       "default": "select",
-      "description": "v1 supports only 'select' (toggle + confirm). 'progress' (live AG-UI status) is a future enum value; restricting it now keeps the wire forward-compatible.",
+      "description": "'select' (default) = toggle + a confirm button that emits `submit`. 'progress' = an onboarding-checklist look (header `done / total` count, circular indicators, per-item title/description, no confirm button, where checking a row IS the action). Both share the selection model.",
       "x-kai-mode": true
     },
     "heading": {
@@ -73,6 +73,11 @@
       "minimum": 1,
       "description": "Optional maximum selectable; further toggles are blocked once reached.",
       "x-kai-select-max": true
+    },
+    "dismissible": {
+      "type": "boolean",
+      "default": false,
+      "description": "Show a close affordance that emits the `dismiss` verb. The card collapses to a re-openable 'dismissed' stub; the host decides via `onReopen` whether it comes back live or `expired`."
     }
   }
 }

package/src/primitives/composer-model.ts

@@ -0,0 +1,49 @@
+export interface EntityRef {
+  kind: string;
+  id: string;
+  label: string;
+  icon?: string;
+  promptText?: string;
+  data?: Record<string, unknown>;
+}
+export type Segment =
+  | { type: 'text'; text: string }
+  | { type: 'entity'; entity: EntityRef };
+export type ComposerDoc = Segment[];
+
+export function normalizeValue(value: string | ComposerDoc | null | undefined): ComposerDoc {
+  if (value == null) return [];
+  if (typeof value === 'string') return value.length ? [{ type: 'text', text: value }] : [];
+  const out: ComposerDoc = [];
+  for (const seg of value) {
+    if (seg.type === 'text') {
+      if (!seg.text) continue;
+      const last = out[out.length - 1];
+      // Replace (don't mutate) the prior segment so every object in the returned
+      // doc is freshly built and never an aliased/held reference.
+      if (last && last.type === 'text') out[out.length - 1] = { type: 'text', text: last.text + seg.text };
+      else out.push({ type: 'text', text: seg.text });
+    } else {
+      out.push({ type: 'entity', entity: seg.entity });
+    }
+  }
+  return out;
+}
+
+export function serializeToText(
+  doc: ComposerDoc,
+  opts?: { entity?: (e: EntityRef) => string },
+): string {
+  let out = '';
+  for (const seg of doc) {
+    if (seg.type === 'text') out += seg.text;
+    else out += opts?.entity ? opts.entity(seg.entity) : (seg.entity.promptText ?? seg.entity.label);
+  }
+  return out;
+}
+export function entitiesOf(doc: ComposerDoc): EntityRef[] {
+  return doc.filter((s): s is Extract<Segment, { type: 'entity' }> => s.type === 'entity').map((s) => s.entity);
+}
+export function docIsEmpty(doc: ComposerDoc): boolean {
+  return doc.every((s) => s.type === 'text' && s.text.length === 0);
+}

package/src/primitives/composer-triggers.ts

@@ -0,0 +1,35 @@
+export interface ActiveTrigger { char: string; query: string; start: number; }
+
+export function detectTrigger(text: string, caret: number, chars: string[]): ActiveTrigger | null {
+  // Caret is a position within `text` (0..text.length). Out-of-range = no trigger.
+  if (caret < 0 || caret > text.length) return null;
+  for (let i = caret - 1; i >= 0; i--) {
+    const c = text[i];
+    if (/\s/.test(c)) return null; // hit whitespace before any trigger char
+    if (chars.includes(c)) {
+      const boundaryOk = i === 0 || /\s/.test(text[i - 1]);
+      if (!boundaryOk) return null;
+      return { char: c, query: text.slice(i + 1, caret), start: i };
+    }
+  }
+  return null;
+}
+
+/**
+ * Wraps detectTrigger with a list of trigger definitions.
+ * Returns { def, query, start } when a trigger is active, else null.
+ * Accepts generic defs so it does not import from composer.tsx (no cycle).
+ */
+export function activeTriggerFor<T extends { char: string; kind: string }>(
+  text: string,
+  caret: number,
+  defs: T[],
+): { def: T; query: string; start: number } | null {
+  if (!defs.length) return null;
+  const chars = defs.map((d) => d.char);
+  const hit = detectTrigger(text, caret, chars);
+  if (!hit) return null;
+  const def = defs.find((d) => d.char === hit.char);
+  if (!def) return null;
+  return { def, query: hit.query, start: hit.start };
+}

package/src/primitives/create-kai-chat.ts

@@ -0,0 +1,66 @@
+// src/primitives/create-kai-chat.ts
+import { createSignal } from 'solid-js';
+import type { ChatMessage } from '../elements/chat-types';
+import type { AttachmentData } from '../components/attachments';
+import {
+  appendMessage, updateMessage, removeMessage, addSuggestion, removeSuggestion,
+  createAssistantStream, onStreamSettled, type AssistantStream, type SetMessages,
+} from '../state';
+
+export interface CreateKaiChatOptions {
+  /** Seed messages, read once at creation and copied. Later changes are ignored — drive updates through the returned ops. */
+  initialMessages?: ChatMessage[];
+  /** Seed suggestions, read once at creation and copied. Later changes are ignored. */
+  initialSuggestions?: string[];
+  onSubmit?: (detail: { value: string; attachments: AttachmentData[] }) => void | Promise<void>;
+}
+
+/** Solid store: consumer-owned chat state + the same ergonomic ops as `useKaiChat`. */
+export interface KaiChatStore {
+  messages: () => ChatMessage[];
+  setMessages: SetMessages;
+  suggestions: () => string[];
+  loading: () => boolean;
+  append: (msg: ChatMessage) => void;
+  update: (id: string, patch: Partial<ChatMessage> | ((m: ChatMessage) => ChatMessage)) => void;
+  remove: (id: string) => void;
+  addSuggestion: (s: string) => void;
+  removeSuggestion: (s: string) => void;
+  clearSuggestions: () => void;
+  streamAssistant: (init?: Partial<ChatMessage>) => AssistantStream;
+  handleSubmit: (event: CustomEvent<{ value: string; attachments: AttachmentData[] }>) => void;
+  /** Spread onto `<kai-chat {...chat.bind} />` (reactive getters). Wire submit via `on:kai-submit={chat.handleSubmit}`. */
+  bind: { readonly messages: ChatMessage[]; readonly loading: boolean; readonly suggestions: string[] };
+}
+
+export function createKaiChat(options: CreateKaiChatOptions = {}): KaiChatStore {
+  // Copy the seed arrays so a caller mutating the array it passed in can't reach our state.
+  const [messages, setMessagesSignal] = createSignal<ChatMessage[]>([...(options.initialMessages ?? [])]);
+  const [suggestions, setSuggestions] = createSignal<string[]>([...(options.initialSuggestions ?? [])]);
+  const [loading, setLoading] = createSignal(false);
+
+  const setMessages: SetMessages = (updater) => setMessagesSignal((prev) => updater(prev));
+
+  return {
+    messages,
+    setMessages,
+    suggestions,
+    loading,
+    append: (msg) => setMessages((prev) => appendMessage(prev, msg)),
+    update: (id, patch) => setMessages((prev) => updateMessage(prev, id, patch)),
+    remove: (id) => setMessages((prev) => removeMessage(prev, id)),
+    addSuggestion: (s) => setSuggestions((prev) => addSuggestion(prev, s)),
+    removeSuggestion: (s) => setSuggestions((prev) => removeSuggestion(prev, s)),
+    clearSuggestions: () => setSuggestions([]),
+    streamAssistant: (init) => {
+      setLoading(true);
+      return onStreamSettled(createAssistantStream(setMessages, init), () => setLoading(false));
+    },
+    handleSubmit: (event) => { void options.onSubmit?.(event.detail); },
+    bind: {
+      get messages() { return messages(); },
+      get loading() { return loading(); },
+      get suggestions() { return suggestions(); },
+    },
+  };
+}