@kitn.ai/ui 0.16.0 → 0.18.0

package/src/primitives/message-feedback.ts

@@ -0,0 +1,123 @@
+// Message action-row feedback state — copy + like/dislike — owned ABOVE the
+// per-message `<For>` so a streaming re-render (a fresh `messages` array ref per
+// chunk) never wipes the user's optimistic vote or the transient "copied" check.
+//
+// Both facades (`ChatThread` and the `<kai-message>` element) create one of
+// these and route their action-bar clicks through `handleAction`. Keeping the
+// logic here (not inside the un-unit-testable `defineWebComponent` body) makes
+// the toggle/toast/clipboard behavior directly testable.
+
+import { createSignal, onCleanup } from 'solid-js';
+import type { ChatMessage, FeedbackVote } from '../elements/chat-types';
+import { toast } from './toast-store';
+
+/** Detail shape emitted by the action row. `state` is present only for the
+ *  toggleable feedback votes: `'on'` when a vote is set, `'off'` when cleared.
+ *  Copy / regenerate / edit / custom actions omit it. */
+export interface MessageActionDetail {
+  messageId: string;
+  action: string;
+  state?: 'on' | 'off';
+}
+
+export interface MessageFeedbackOptions {
+  /** Emit the `kai-message-action` detail (facade maps this to `dispatch` /
+   *  `onMessageAction`). */
+  emit: (detail: MessageActionDetail) => void;
+  /** How long the copy check stays before auto-clearing. Defaults to 2000ms. */
+  copiedDuration?: number;
+  /** Container the copy/feedback toasts should be scoped to (the chat, by
+   *  default) so they appear in-chat rather than at the page top. */
+  target?: () => HTMLElement | undefined;
+}
+
+export interface MessageFeedback {
+  /** Resolve the active vote for a message: a controlled `m.feedback` wins,
+   *  else the facade's own optimistic map. */
+  resolveFeedback: (m: Pick<ChatMessage, 'id' | 'feedback'>) => FeedbackVote | undefined;
+  /** Whether a message's copy button should currently show its check. */
+  isCopied: (id: string) => boolean;
+  /** Route a clicked action through copy / vote / passthrough handling. */
+  handleAction: (m: Pick<ChatMessage, 'id' | 'content' | 'feedback'>, action: string) => void;
+}
+
+const DEFAULT_COPIED_DURATION = 2000;
+
+/**
+ * Create the action-row feedback controller for one message list (or one
+ * standalone message). Owns the optimistic `feedbackMap` + transient
+ * `copiedIds`, resolves the controlled-wins vote, and turns clicks into
+ * clipboard writes, toasts, and `kai-message-action` emissions.
+ */
+export function createMessageFeedback(opts: MessageFeedbackOptions): MessageFeedback {
+  const [feedbackMap, setFeedbackMap] = createSignal<Record<string, FeedbackVote>>({});
+  const [copiedIds, setCopiedIds] = createSignal<Set<string>>(new Set());
+  const copiedDuration = opts.copiedDuration ?? DEFAULT_COPIED_DURATION;
+  const timers = new Map<string, ReturnType<typeof setTimeout>>();
+
+  onCleanup(() => {
+    timers.forEach((t) => clearTimeout(t));
+    timers.clear();
+  });
+
+  const resolveFeedback: MessageFeedback['resolveFeedback'] = (m) =>
+    m.feedback ?? feedbackMap()[m.id];
+
+  const isCopied: MessageFeedback['isCopied'] = (id) => copiedIds().has(id);
+
+  const markCopied = (id: string) => {
+    setCopiedIds((prev) => {
+      const next = new Set(prev);
+      next.add(id);
+      return next;
+    });
+    const existing = timers.get(id);
+    if (existing) clearTimeout(existing);
+    timers.set(id, setTimeout(() => {
+      timers.delete(id);
+      setCopiedIds((prev) => {
+        if (!prev.has(id)) return prev;
+        const next = new Set(prev);
+        next.delete(id);
+        return next;
+      });
+    }, copiedDuration));
+  };
+
+  const setVote = (id: string, vote: FeedbackVote | undefined) => {
+    setFeedbackMap((prev) => {
+      const next = { ...prev };
+      if (vote === undefined) delete next[id];
+      else next[id] = vote;
+      return next;
+    });
+  };
+
+  const handleAction: MessageFeedback['handleAction'] = (m, action) => {
+    if (action === 'copy') {
+      // Clipboard may be unavailable (insecure context / jsdom); fail soft.
+      try { navigator.clipboard?.writeText(m.content); } catch { /* ignore */ }
+      markCopied(m.id);
+      toast('Copied to clipboard', { target: opts.target?.() });
+      opts.emit({ messageId: m.id, action });
+      return;
+    }
+    if (action === 'like' || action === 'dislike') {
+      const current = resolveFeedback(m);
+      if (current === action) {
+        // Re-tap clears the vote — no toast on un-vote.
+        setVote(m.id, undefined);
+        opts.emit({ messageId: m.id, action, state: 'off' });
+      } else {
+        setVote(m.id, action);
+        toast('Thanks for your feedback', { target: opts.target?.() });
+        opts.emit({ messageId: m.id, action, state: 'on' });
+      }
+      return;
+    }
+    // regenerate / edit / custom — passthrough, no state.
+    opts.emit({ messageId: m.id, action });
+  };
+
+  return { resolveFeedback, isCopied, handleAction };
+}

package/src/primitives/toast-store.ts

@@ -0,0 +1,276 @@
+// Module-level toast store + the imperative `toast()` API.
+//
+// This is the PRIMARY way consumers raise a toast: `toast('Saved')`,
+// `toast.success('Copied')`, `toast.dismiss(id)`. The store is a single
+// reactive list held in a long-lived `createRoot` (so its reactivity survives
+// outside any component), and `ensureMounted()` lazily creates exactly ONE
+// `<kai-toast-region>` on `document.body` the first time a toast is raised,
+// binding the list to its `toasts` property. The region is a real `kai-*`
+// element, so it carries its own shadow root + the shared kit stylesheet — it's
+// viewport-positioned AND fully kit-styled, never a raw div.
+//
+// SSR-safe: every DOM touch is guarded by `typeof document`. On the server,
+// raising a toast is an inert no-op (the store updates, nothing mounts).
+
+import { createRoot, createSignal } from 'solid-js';
+import { createStore, produce } from 'solid-js/store';
+import type { ToastPosition } from '../components/toast';
+
+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
+// the element's own defaults, so an un-configured app behaves exactly as before.
+let toastConfig: ToastConfig = {};
+
+/** Apply the current config to a region element (attributes for scalars). */
+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');
+  }
+}
+
+/**
+ * Configure the imperative `toast()` singleton — call once at app start.
+ * `toast.success('…')` has no element to set a prop on, so this is how you opt
+ * the auto-mounted region into collapsed stacking / a position / a max. Updates
+ * any already-mounted regions too, so call order doesn't matter.
+ */
+export function configureToasts(config: ToastConfig): void {
+  toastConfig = { ...toastConfig, ...config };
+  if (typeof document === 'undefined') return;
+  document.querySelectorAll('kai-toast-region').forEach((el) => applyConfig(el as HTMLElement));
+}
+
+/** An action button rendered inside the toast. Returning `false` from
+ *  `onAction` keeps the toast open (e.g. to show a follow-up); any other
+ *  return value dismisses it. */
+export interface ToastAction {
+  label: string;
+  onAction: () => void | false;
+}
+
+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
+   *  to act on. Defaults to 2000ms. */
+  duration?: number;
+  /** Whether the × close affordance is shown. Defaults to `true`. */
+  dismissible?: boolean;
+  /** Container to scope this toast WITHIN — it floats anchored to that element's
+   *  bounds instead of the viewport. Omit for a global, viewport-anchored toast.
+   *  The chat targets itself by default so its copy/feedback toasts stay in-chat. */
+  target?: HTMLElement;
+}
+
+/** Options accepted by `toast()` — everything but the message. Pass `id` to
+ *  update an existing toast in place. */
+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;
+  /** Scope this toast to a container's bounds (e.g. a chat) instead of the
+   *  viewport. Omit for a global, viewport-anchored toast. */
+  target?: HTMLElement;
+}
+
+/** Handle returned from `toast()` for imperative control. */
+export interface ToastHandle {
+  id: string;
+  dismiss: () => void;
+  update: (patch: Partial<Omit<ToastItem, 'id'>>) => void;
+}
+
+/** Default auto-dismiss delay. Long enough to read + reach before it leaves. */
+export const DEFAULT_TOAST_DURATION = 5000;
+/** Minimum auto-dismiss delay when the toast carries an action (e.g. Undo) — it
+ *  has to stay up long enough to actually act on. */
+export const ACTION_TOAST_FLOOR = 7000;
+
+// ── The reactive store ──────────────────────────────────────────────────────
+// Held in a never-disposed root so the signal/store graph stays live for the
+// lifetime of the page, independent of any component.
+const { toasts, setToasts, mounted, setMounted } = createRoot(() => {
+  const [list, setList] = createStore<ToastItem[]>([]);
+  const [isMounted, setIsMounted] = createSignal(false);
+  return { toasts: list, setToasts: setList, mounted: isMounted, setMounted: setIsMounted };
+});
+
+/** The live toast list (reactive). The region facade binds to this. */
+export function getToasts(): ToastItem[] {
+  return toasts;
+}
+
+let counter = 0;
+function nextId(): string {
+  counter += 1;
+  return `toast-${counter}`;
+}
+
+/** Resolve the effective duration, applying the action floor. */
+function resolveDuration(item: Pick<ToastItem, 'duration' | 'action'>): number {
+  const base = item.duration ?? DEFAULT_TOAST_DURATION;
+  if (base === 0) return 0; // explicit sticky wins
+  if (item.action) return Math.max(base, ACTION_TOAST_FLOOR);
+  return base;
+}
+
+/**
+ * Lazily create the single `<kai-toast-region>` host on `document.body` and
+ * bind the store to its `toasts` property. Idempotent + SSR-safe. The element
+ * upgrade (its `defineWebComponent` registration) happens when the elements
+ * bundle loads; setting the property before/after upgrade both work because
+ * `customElement` reflects late-set properties.
+ */
+// One region per distinct target (the `null` key = the global / viewport region).
+// Every region binds the SAME store proxy and filters to its own target, so a
+// toast routes to the region for its `target`.
+const regions = new Map<HTMLElement | null, HTMLElement>();
+
+export function ensureMounted(target: HTMLElement | null = null): HTMLElement | undefined {
+  if (typeof document === 'undefined') return undefined;
+  const cached = regions.get(target);
+  if (cached && cached.isConnected) return cached;
+  const el = document.createElement('kai-toast-region') as HTMLElement;
+  // Append FIRST so the element upgrades, THEN bind. Setting a property before
+  // upgrade loses it: component-register resets every prop in the constructor on
+  // upgrade (the same pre-upgrade clobber that bites <kai-chat>), so a pre-append
+  // `el.toasts = …` is wiped and the first toast never renders.
+  document.body.appendChild(el);
+  (el as unknown as { toasts: ToastItem[] }).toasts = toasts as ToastItem[];
+  if (target) (el as unknown as { target: HTMLElement }).target = target;
+  applyConfig(el); // inherit stack/position/max from configureToasts()
+  regions.set(target, el);
+  setMounted(true);
+  return el;
+}
+
+/** Test-only: whether `ensureMounted` has run. */
+export function isToastRegionMounted(): boolean {
+  return mounted();
+}
+
+function upsert(item: ToastItem): void {
+  const idx = toasts.findIndex((t) => t.id === item.id);
+  if (idx >= 0) {
+    setToasts(idx, item);
+  } else {
+    setToasts(produce((list) => { list.push(item); }));
+  }
+}
+
+function dismiss(id: string): void {
+  setToasts((list) => list.filter((t) => t.id !== id));
+}
+
+function makeHandle(id: string): ToastHandle {
+  return {
+    id,
+    dismiss: () => dismiss(id),
+    update: (patch) => {
+      const idx = toasts.findIndex((t) => t.id === id);
+      if (idx >= 0) setToasts(idx, (prev) => ({ ...prev, ...patch }));
+    },
+  };
+}
+
+/** Internal: raise/refresh a toast of a given variant. */
+function raise(message: string, opts: ToastOptions | undefined, variant: ToastVariant): ToastHandle {
+  ensureMounted(opts?.target ?? null);
+  const id = opts?.id ?? nextId();
+  const item: ToastItem = {
+    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,
+    target: opts?.target,
+  };
+  upsert(item);
+  return makeHandle(id);
+}
+
+export interface ToastFn {
+  (message: string, opts?: ToastOptions): ToastHandle;
+  /** 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. */
+  clear: () => void;
+}
+
+/**
+ * Raise a transient toast. Returns a `{ id, dismiss, update }` handle.
+ *
+ * ```ts
+ * toast('Copied to clipboard');
+ * toast.success('Saved');
+ * const t = toast('Working…', { duration: 0 });
+ * t.update({ message: 'Done', variant: 'success', duration: 2000 });
+ * ```
+ */
+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([]),
+  },
+);
+
+// Re-export for the region facade so the effective-duration rule lives in one place.
+export { resolveDuration };

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

package/src/state/stream.ts

@@ -0,0 +1,92 @@
+// src/state/stream.ts
+import type { ChatMessage } from '../elements/chat-types';
+import type { ToolPart } from '../components/tool-types';
+
+/** The one universal contract: a functional-updater setter (React setState shape). */
+export type SetMessages = (updater: (prev: ChatMessage[]) => ChatMessage[]) => void;
+
+/** A fluent builder for one in-flight assistant message. Owns no state. */
+export interface AssistantStream {
+  readonly id: string;
+  appendText(delta: string): AssistantStream;
+  setText(content: string): AssistantStream;
+  appendReasoning(delta: string, label?: string): AssistantStream;
+  setReasoning(text: string, label?: string): AssistantStream;
+  upsertTool(tool: ToolPart): AssistantStream;
+  updateTool(toolCallId: string, patch: Partial<ToolPart>): AssistantStream;
+  patch(patch: Partial<ChatMessage>): AssistantStream;
+  done(final?: Partial<ChatMessage>): void;
+  abort(reason?: string): void;
+}
+
+function newId(): string {
+  if (typeof crypto !== 'undefined' && typeof crypto.randomUUID === 'function') return crypto.randomUUID();
+  return 'kai-' + Math.random().toString(36).slice(2);
+}
+
+/** Start an assistant message and drive it through `set`. New refs on every mutation. */
+export function createAssistantStream(set: SetMessages, init: Partial<ChatMessage> = {}): AssistantStream {
+  const id = init.id ?? newId();
+  const seed: ChatMessage = { id, role: 'assistant', content: '', ...init };
+  set((prev) => [...prev, seed]);
+
+  const mutate = (fn: (m: ChatMessage) => ChatMessage) =>
+    set((prev) => prev.map((m) => (m.id === id ? fn(m) : m)));
+
+  const stream: AssistantStream = {
+    id,
+    appendText(delta) { mutate((m) => ({ ...m, content: m.content + delta })); return stream; },
+    setText(content) { mutate((m) => ({ ...m, content })); return stream; },
+    appendReasoning(delta, label) {
+      mutate((m) => ({ ...m, reasoning: { text: (m.reasoning?.text ?? '') + delta, label: label ?? m.reasoning?.label } }));
+      return stream;
+    },
+    setReasoning(text, label) {
+      mutate((m) => ({ ...m, reasoning: { text, label: label ?? m.reasoning?.label } }));
+      return stream;
+    },
+    upsertTool(tool) {
+      mutate((m) => {
+        const tools = m.tools ? m.tools.slice() : [];
+        const i = tool.toolCallId != null
+          ? tools.findIndex((t) => t.toolCallId === tool.toolCallId)
+          : tools.findIndex((t) => t.type === tool.type);
+        if (i === -1) tools.push(tool); else tools[i] = tool;
+        return { ...m, tools };
+      });
+      return stream;
+    },
+    updateTool(toolCallId, patch) {
+      mutate((m) => ({ ...m, tools: (m.tools ?? []).map((t) => (t.toolCallId === toolCallId ? { ...t, ...patch } : t)) }));
+      return stream;
+    },
+    patch(patch) { mutate((m) => ({ ...m, ...patch })); return stream; },
+    done(final) { if (final) mutate((m) => ({ ...m, ...final })); },
+    abort(reason) {
+      if (reason) {
+        mutate((m) => ({ ...m, tools: (m.tools ?? []).map((t) => ({ ...t, state: 'output-error' as const, errorText: reason })) }));
+      } else {
+        set((prev) => prev.filter((m) => m.id !== id));
+      }
+    },
+  };
+  return stream;
+}
+
+/** Wrap a stream so `onSettle` fires on done/abort (used to toggle a `loading` flag).
+ *  Preserves the fluent chain by returning the wrapper from every mutator. */
+export function onStreamSettled(inner: AssistantStream, onSettle: () => void): AssistantStream {
+  const wrapper: AssistantStream = {
+    id: inner.id,
+    appendText(d) { inner.appendText(d); return wrapper; },
+    setText(c) { inner.setText(c); return wrapper; },
+    appendReasoning(d, l) { inner.appendReasoning(d, l); return wrapper; },
+    setReasoning(t, l) { inner.setReasoning(t, l); return wrapper; },
+    upsertTool(t) { inner.upsertTool(t); return wrapper; },
+    updateTool(tcId, p) { inner.updateTool(tcId, p); return wrapper; },
+    patch(p) { inner.patch(p); return wrapper; },
+    done(final) { inner.done(final); onSettle(); },
+    abort(reason) { inner.abort(reason); onSettle(); },
+  };
+  return wrapper;
+}

package/src/state/suggestions.ts

@@ -0,0 +1,9 @@
+/** Append a suggestion; no-op when already present. Returns a new array. */
+export function addSuggestion(suggestions: string[], s: string): string[] {
+  return suggestions.includes(s) ? suggestions.slice() : [...suggestions, s];
+}
+
+/** Remove a suggestion by value. */
+export function removeSuggestion(suggestions: string[], s: string): string[] {
+  return suggestions.filter((x) => x !== s);
+}