@kitn.ai/ui 0.17.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';
@@ -204,8 +206,6 @@ 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';
@@ -281,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-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": {

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(); },
+    },
+  };
+}

package/src/primitives/toast-store.ts

@@ -16,12 +16,20 @@ import { createRoot, createSignal } from 'solid-js';
 import { createStore, produce } from 'solid-js/store';
 import type { ToastPosition } from '../components/toast';
 
-export type ToastVariant = 'neutral' | 'success';
+export type ToastVariant = 'neutral' | 'success' | 'warning' | 'error' | 'info';
+/** Visual treatment: `'pill'` (default, compact single-line) or `'card'` (richer
+ *  rounded card with an optional description line). */
+export type ToastAppearance = 'pill' | 'card';
 
 export interface ToastConfig {
   stack?: 'expanded' | 'collapsed';
   position?: ToastPosition;
   max?: number;
+  /** Default appearance for imperatively-raised toasts. Defaults to `'pill'`. */
+  appearance?: ToastAppearance;
+  /** Default high-contrast inverse treatment for imperatively-raised toasts.
+   *  Defaults to `false`. */
+  inverse?: boolean;
 }
 
 // Module-level config the imperative singleton regions inherit. Defaults match
@@ -33,6 +41,11 @@ function applyConfig(el: HTMLElement): void {
   if (toastConfig.stack) el.setAttribute('stack', toastConfig.stack);
   if (toastConfig.position) el.setAttribute('position', toastConfig.position);
   if (toastConfig.max !== undefined) el.setAttribute('max', String(toastConfig.max));
+  if (toastConfig.appearance) el.setAttribute('appearance', toastConfig.appearance);
+  if (toastConfig.inverse !== undefined) {
+    if (toastConfig.inverse) el.setAttribute('inverse', '');
+    else el.removeAttribute('inverse');
+  }
 }
 
 /**
@@ -59,6 +72,15 @@ export interface ToastItem {
   id: string;
   message: string;
   variant?: ToastVariant;
+  /** Visual treatment: `'pill'` (default, compact single-line) or `'card'` (richer
+   *  rounded card with an optional description line). */
+  appearance?: ToastAppearance;
+  /** High-contrast inverse surface — works on either appearance, popping in light
+   *  AND dark. Defaults to `false`. */
+  inverse?: boolean;
+  /** Secondary line shown below the message in the `'card'` appearance. The
+   *  `'pill'` appearance ignores it. */
+  description?: string;
   action?: ToastAction;
   /** Auto-dismiss delay in ms. `0` = sticky (never auto-dismisses). When an
    *  `action` is present the effective floor is 4000ms so it stays long enough
@@ -77,6 +99,13 @@ export interface ToastItem {
 export interface ToastOptions {
   id?: string;
   variant?: ToastVariant;
+  /** Visual treatment: `'pill'` (default) or `'card'`. Falls back to the value set
+   *  via `configureToasts`, then `'pill'`. */
+  appearance?: ToastAppearance;
+  /** High-contrast inverse surface. Falls back to `configureToasts`, then `false`. */
+  inverse?: boolean;
+  /** Secondary line shown below the message in the `'card'` appearance. */
+  description?: string;
   action?: ToastAction;
   duration?: number;
   dismissible?: boolean;
@@ -193,6 +222,9 @@ function raise(message: string, opts: ToastOptions | undefined, variant: ToastVa
     id,
     message,
     variant: opts?.variant ?? variant,
+    appearance: opts?.appearance ?? toastConfig.appearance ?? 'pill',
+    inverse: opts?.inverse ?? toastConfig.inverse ?? false,
+    description: opts?.description,
     action: opts?.action,
     duration: opts?.duration,
     dismissible: opts?.dismissible,
@@ -204,8 +236,14 @@ function raise(message: string, opts: ToastOptions | undefined, variant: ToastVa
 
 export interface ToastFn {
   (message: string, opts?: ToastOptions): ToastHandle;
-  /** Raise a success (emerald check) toast. */
+  /** Raise a success (green check) toast. */
   success: (message: string, opts?: ToastOptions) => ToastHandle;
+  /** Raise a warning (amber) toast — e.g. an agent needs your input. */
+  warning: (message: string, opts?: ToastOptions) => ToastHandle;
+  /** Raise an error (destructive/red) toast — e.g. an agent failed. */
+  error: (message: string, opts?: ToastOptions) => ToastHandle;
+  /** Raise an info (blue) toast. */
+  info: (message: string, opts?: ToastOptions) => ToastHandle;
   /** Dismiss a toast by id. */
   dismiss: (id: string) => void;
   /** Dismiss every active toast. */
@@ -226,6 +264,9 @@ export const toast: ToastFn = Object.assign(
   (message: string, opts?: ToastOptions) => raise(message, opts, 'neutral'),
   {
     success: (message: string, opts?: ToastOptions) => raise(message, opts, 'success'),
+    warning: (message: string, opts?: ToastOptions) => raise(message, opts, 'warning'),
+    error: (message: string, opts?: ToastOptions) => raise(message, opts, 'error'),
+    info: (message: string, opts?: ToastOptions) => raise(message, opts, 'info'),
     dismiss,
     clear: () => setToasts([]),
   },

package/src/primitives/use-speech-recognition.ts

@@ -0,0 +1,135 @@
+import { createSignal, onCleanup } from 'solid-js';
+
+// Minimal Web Speech API surface. The DOM lib doesn't ship these types reliably
+// across TS versions, so we declare only what we touch. `webkitSpeechRecognition`
+// is the Chrome/Safari-prefixed constructor; the unprefixed one is rare.
+interface SpeechRecognitionAlternative {
+  transcript: string;
+}
+interface SpeechRecognitionResult {
+  readonly isFinal: boolean;
+  readonly length: number;
+  [index: number]: SpeechRecognitionAlternative;
+}
+interface SpeechRecognitionResultList {
+  readonly length: number;
+  [index: number]: SpeechRecognitionResult;
+}
+interface SpeechRecognitionEventLike {
+  readonly resultIndex: number;
+  readonly results: SpeechRecognitionResultList;
+}
+interface SpeechRecognitionLike {
+  lang: string;
+  continuous: boolean;
+  interimResults: boolean;
+  start(): void;
+  stop(): void;
+  abort(): void;
+  onresult: ((event: SpeechRecognitionEventLike) => void) | null;
+  onerror: ((event: { error?: string }) => void) | null;
+  onend: (() => void) | null;
+}
+type SpeechRecognitionCtor = new () => SpeechRecognitionLike;
+
+function getCtor(): SpeechRecognitionCtor | undefined {
+  if (typeof window === 'undefined') return undefined;
+  const w = window as unknown as {
+    SpeechRecognition?: SpeechRecognitionCtor;
+    webkitSpeechRecognition?: SpeechRecognitionCtor;
+  };
+  return w.SpeechRecognition ?? w.webkitSpeechRecognition;
+}
+
+export interface UseSpeechRecognitionOptions {
+  /** Emit live, non-final partials via the `onInterim` callback passed to start(). */
+  interim?: boolean;
+}
+
+export interface SpeechRecognitionStartOptions {
+  /** BCP-47 language tag, e.g. `en-US`. */
+  lang?: string;
+  /** Called with each interim (non-final) transcript when `interim` is enabled. */
+  onInterim?: (text: string) => void;
+}
+
+/**
+ * Wrap the browser's Web Speech `SpeechRecognition` (Chrome/Safari; no Firefox).
+ * Mirrors `useVoiceRecorder`'s shape: an `isListening` signal, an `error` signal,
+ * and `start`/`stop` controls. `start()` resolves with the final transcript when
+ * recognition ends; `stop()` ends the in-progress session (resolving start()).
+ *
+ * Caveat (documented at the element): in Chrome this is cloud-based — audio is
+ * sent to Google — so it is "native to the browser," not on-device/private.
+ */
+export function useSpeechRecognition(options: UseSpeechRecognitionOptions = {}) {
+  const [isListening, setIsListening] = createSignal(false);
+  const [error, setError] = createSignal<string | null>(null);
+
+  const isSupported = getCtor() !== undefined;
+
+  let recognition: SpeechRecognitionLike | undefined;
+  let resolveText: ((text: string) => void) | undefined;
+  let finalText = '';
+
+  function start(opts: SpeechRecognitionStartOptions = {}): Promise<string> {
+    setError(null);
+    finalText = '';
+    const Ctor = getCtor();
+    if (!Ctor) {
+      const message = 'SpeechRecognition is not supported in this browser';
+      setError(message);
+      return Promise.reject(new Error(message));
+    }
+    try {
+      recognition = new Ctor();
+      if (opts.lang) recognition.lang = opts.lang;
+      recognition.interimResults = options.interim === true;
+      recognition.continuous = false;
+
+      recognition.onresult = (event) => {
+        let interim = '';
+        for (let i = event.resultIndex; i < event.results.length; i++) {
+          const result = event.results[i];
+          const transcript = result[0]?.transcript ?? '';
+          if (result.isFinal) {
+            finalText += transcript;
+          } else {
+            interim += transcript;
+          }
+        }
+        if (interim && opts.onInterim) opts.onInterim(interim);
+      };
+
+      recognition.onerror = (event) => {
+        setError(event.error ?? 'Speech recognition error');
+      };
+
+      recognition.onend = () => {
+        setIsListening(false);
+        resolveText?.(finalText);
+        recognition = undefined;
+      };
+
+      recognition.start();
+      setIsListening(true);
+      return new Promise<string>((resolve) => { resolveText = resolve; });
+    } catch (err) {
+      setError(err instanceof Error ? err.message : 'Speech recognition failed to start');
+      setIsListening(false);
+      throw err;
+    }
+  }
+
+  function stop() {
+    if (recognition && isListening()) {
+      recognition.stop();
+    }
+  }
+
+  onCleanup(() => {
+    if (recognition) recognition.abort();
+  });
+
+  return { isSupported, isListening, error, start, stop };
+}

package/src/state/index.ts

@@ -0,0 +1,6 @@
+// Framework-neutral state core for @kitn.ai/ui. Pure functions over ChatMessage[]
+// + a typed streaming handle. No React/Solid runtime — drives a consumer setter.
+export { appendMessage, upsertMessage, updateMessage, removeMessage, appendContent } from './messages';
+export { addSuggestion, removeSuggestion } from './suggestions';
+export { createAssistantStream, onStreamSettled } from './stream';
+export type { SetMessages, AssistantStream } from './stream';

package/src/state/messages.ts

@@ -0,0 +1,36 @@
+import type { ChatMessage } from '../elements/chat-types';
+
+/** Append a message; returns a new array. */
+export function appendMessage(messages: ChatMessage[], msg: ChatMessage): ChatMessage[] {
+  return [...messages, msg];
+}
+
+/** Replace a same-id message, or append when absent. */
+export function upsertMessage(messages: ChatMessage[], msg: ChatMessage): ChatMessage[] {
+  const i = messages.findIndex((x) => x.id === msg.id);
+  if (i === -1) return [...messages, msg];
+  const next = messages.slice();
+  next[i] = msg;
+  return next;
+}
+
+/** Patch the matched message (object patch or updater). Untouched items keep their reference. */
+export function updateMessage(
+  messages: ChatMessage[],
+  id: string,
+  patch: Partial<ChatMessage> | ((m: ChatMessage) => ChatMessage),
+): ChatMessage[] {
+  return messages.map((x) =>
+    x.id === id ? (typeof patch === 'function' ? patch(x) : { ...x, ...patch }) : x,
+  );
+}
+
+/** Remove the matched message. */
+export function removeMessage(messages: ChatMessage[], id: string): ChatMessage[] {
+  return messages.filter((x) => x.id !== id);
+}
+
+/** Streaming primitive: concatenate `delta` onto the matched message's content. */
+export function appendContent(messages: ChatMessage[], id: string, delta: string): ChatMessage[] {
+  return messages.map((x) => (x.id === id ? { ...x, content: x.content + delta } : x));
+}