@kitn.ai/ui 0.28.0 → 0.30.0

package/src/elements/thread.tsx

@@ -1,139 +0,0 @@
-import { createSignal, onMount, onCleanup } from 'solid-js';
-import { defineWebComponent } from './define';
-import { readSlots, THREAD_SLOTS } from './slots';
-import { Thread, type ThreadController } from '../components/thread';
-import { cardComponentsFromTags } from './message';
-import { createMessagesGuard } from './validate-messages';
-import type { ChatMessage } from './chat-types';
-import type { ProseSize } from '../primitives/chat-config';
-
-interface Props extends Record<string, unknown> {
-  /** The full message thread to render, newest last. Each entry carries its role,
-   *  ordered `parts`, and optional actions/avatar/feedback. Set as a JS
-   *  property (`el.messages = [...]`); a NEW array reference per streaming chunk
-   *  re-renders (mutating in place does not). */
-  messages?: ChatMessage[];
-  /** Show a typing indicator on the pending assistant turn. Set it while
-   *  awaiting the assistant's reply. */
-  loading?: boolean;
-  /** Body/prose font scale for rendered markdown (`'xs' | 'sm' | 'base' | 'lg'`).
-   *  Defaults to `'sm'`. */
-  proseSize?: ProseSize;
-  /** Shiki theme name for syntax-highlighted code blocks (e.g.
-   *  `'github-dark-dimmed'`). */
-  codeTheme?: string;
-  /** Enable Shiki syntax highlighting in code blocks. Turn off to render plain
-   *  `<pre>` blocks (lighter, no highlighter load). Default true. */
-  codeHighlight?: boolean;
-  /** Whether each message's action bar is always visible (`'always'`, default) or
-   *  only revealed on hover of that message row (`'hover'`). */
-  actionsReveal?: 'always' | 'hover';
-  /** Show the scroll-to-bottom button inside the scroll area. Default true. */
-  scrollButton?: boolean;
-  /** Extra classes applied to the thread's inner root. */
-  class?: string;
-  /** Optional card type -> custom-element tag overrides/additions for `card`
-   *  parts (merged over the built-ins). Property: `el.cardTypes`. Typed as a
-   *  plain string map (not the `CardTagMap` alias) so the generated React
-   *  wrapper inlines it instead of emitting an unresolved named type. */
-  cardTypes?: Record<string, string>;
-  /** JSON Schemas for the card types this app renders, keyed by envelope type. The
-   *  companion of `cardTypes`, which says what DRAWS a card while this says what a
-   *  VALID one looks like. An OBJECT, so it is a JS property only: `el.cardSchemas
-   *  = { 'pricing-table': pricingSchema }`, never an attribute.
-   *  `createCardRegistry(...).validationSchemas` is exactly this shape.
-   *
-   *  Without it the kit validates its own seven built-ins and leaves your own card
-   *  type, the one your app actually cares about, as the only unchecked thing on
-   *  screen. A schema here WINS over a built-in of the same name.
-   *
-   *  Typed `Record<string, object>` rather than `Record<string, JsonSchema>`
-   *  deliberately: an imported `.json` schema widens `"type"` to `string`, and an
-   *  authored one carries `$schema`/`title`/`description`/`additionalProperties`,
-   *  so the tighter type would reject both of the normal ways to supply one. */
-  cardSchemas?: Record<string, object>;
-}
-
-/** Events fired by `<kai-thread>`. */
-interface Events extends Record<string, unknown> {
-  /** A message's action button was clicked. `action` is the built-in name (`copy`
-   *  / `like` / `dislike` / `regenerate` / `edit`) or a custom id. `state` is
-   *  present only for the toggleable feedback votes: `'on'` when a like/dislike is
-   *  set, `'off'` when re-tapped to clear. */
-  'kai-message-action': { messageId: string; action: string; state?: 'on' | 'off' };
-}
-
-/**
- * `<kai-thread>` — the scrolling message list of a chat, as a standalone
- * composable element: one message row per `messages` entry with markdown / code
- * highlight / reasoning + tool panels / avatars / action row, stick-to-bottom
- * scroll with a scroll-to-bottom button, an optional typing indicator, and an
- * `empty` slot. It fills the height its parent gives it and scrolls internally
- * (`:host { display:block; height:100% }`). No composer, header, suggestions, or
- * sidebar — pair it with `<kai-prompt-input>` and your own layout, or reach for
- * the batteries-included `<kai-chat>`. Emits `kai-message-action`; exposes
- * `scrollToBottom()`.
- */
-defineWebComponent<Props, Events>('kai-thread', {
-  messages: undefined,
-  loading: false,
-  proseSize: 'sm',
-  codeTheme: 'github-dark-dimmed',
-  codeHighlight: true,
-  actionsReveal: 'always',
-  scrollButton: true,
-  class: undefined,
-  cardTypes: undefined,
-  cardSchemas: undefined,
-}, (props, { element, dispatch, flag, expose }) => {
-  let controller: ThreadController | undefined;
-
-  // `messages` is an untyped boundary: a consumer can hand it anything at
-  // runtime (a pre-0.20.0 `{ id, role, content }` array, in particular). Skip
-  // the invalid entries rather than let `groupMessageParts` throw deep inside a
-  // render pass, which would blank the whole element instead of one message.
-  const validMessages = createMessagesGuard('kai-thread');
-
-  // Detect whether the consumer projected `slot="empty"` content, so the built-in
-  // default only renders when they did NOT.
-  const [slots, setSlots] = createSignal<Record<string, boolean>>({});
-  onMount(() => {
-    const read = () => setSlots(readSlots(element, THREAD_SLOTS));
-    read();
-    const observer = new MutationObserver(read);
-    observer.observe(element, { childList: true });
-    onCleanup(() => observer.disconnect());
-  });
-
-  // Imperative method API — forward the thread's scroll control onto the host.
-  expose({
-    /** Scroll the message list to the bottom (default `'smooth'`). */
-    scrollToBottom: (behavior?: ScrollBehavior) => controller?.scrollToBottom(behavior),
-  });
-
-  return (
-    <>
-      {/* Fill the height the parent gives us and scroll internally, like
-          <kai-resizable>. Consumers only need to give a parent (or the element) a
-          height. */}
-      <style>{':host{display:block;height:100%}'}</style>
-      <Thread
-        class={props.class as string | undefined}
-        messages={validMessages(props.messages)}
-        loading={flag('loading')}
-        proseSize={props.proseSize as ProseSize}
-        codeTheme={props.codeTheme as string}
-        codeHighlight={flag('codeHighlight')}
-        actionsReveal={props.actionsReveal as 'always' | 'hover'}
-        scrollButton={props.scrollButton !== false}
-        cardTypes={cardComponentsFromTags(props.cardTypes as Record<string, string> | undefined, (props as { theme?: string }).theme)}
-        cardSchemas={props.cardSchemas as Record<string, object> | undefined}
-        /* F-26: card parts emit off THIS element as the bubbling `kai-card` event. */
-        cardHostElement={element}
-        empty={slots()['empty'] ? <slot name="empty" /> : undefined}
-        onMessageAction={(detail) => dispatch('kai-message-action', detail)}
-        controllerRef={(c) => (controller = c)}
-      />
-    </>
-  );
-});

package/src/elements/toast.tsx

@@ -1,106 +0,0 @@
-import { defineWebComponent } from './define';
-import { ToastRegion, type ToastDismissReason, type ToastPosition, type ToastAppearance } from '../components/toast';
-import { toast as toastStore, type ToastItem } from '../primitives/toast-store';
-
-interface Props extends Record<string, unknown> {
-  /** The toasts to render. Newest is shown on top. Set as a JS property (array);
-   *  pass a new array reference to update. Omit for an empty region, which is
-   *  the normal resting state and how the imperative `toast()` API starts.
-   *  Note the handover: the first `toast()` call ADOPTS a region you placed in
-   *  markup (no second region mounts) and binds the imperative store to this
-   *  property, replacing any array you set. Drive a region as data OR via
-   *  `toast()`, not both at once. */
-  toasts?: ToastItem[];
-  /** Stack anchor: `'top-center'` (default), `'top-right'`, `'bottom-center'`, … */
-  position?: ToastPosition;
-  /** Max simultaneously-visible toasts; the rest queue. Defaults to `3`. */
-  max?: number;
-  /** Stacking: 'expanded' (default, full column) | 'collapsed' (Sonner-style
-   *  pile that expands on hover/focus). Attribute: stack. */
-  stack?: 'expanded' | 'collapsed';
-  /** Default appearance for this region's toasts: `'pill'` (default, compact) |
-   *  `'card'` (richer, with a description line). A per-toast `appearance` wins.
-   *  Attribute: `appearance`. */
-  appearance?: ToastAppearance;
-  /** Default high-contrast inverse treatment for this region's toasts. A per-toast
-   *  `inverse` wins. Off by default. Attribute: `inverse`. */
-  inverse?: boolean;
-  /** Container element to anchor this region to (JS property). Set by the store
-   *  for a scoped region; unset = the global viewport region. */
-  target?: HTMLElement;
-}
-
-interface Events {
-  /** A toast left the stack. `reason` is `'timeout' | 'close' | 'action'`. */
-  'kai-dismiss': { id: string; reason: ToastDismissReason };
-  /** A toast's action button was pressed. */
-  'kai-action': { id: string; label: string };
-}
-
-/**
- * `<kai-toast-region>` — the viewport overlay that renders the toast stack.
- *
- * It is the substrate behind the imperative `toast()` API: the store lazily
- * mounts ONE of these on `document.body` and binds the list to `toasts`. It is
- * also usable declaratively — set `el.toasts = [...]` (a JS property, never an
- * attribute) and listen for `kai-dismiss` / `kai-action`.
- *
- * The two modes meet gracefully: `toast()` ADOPTS the first connected
- * `<kai-toast-region>` already in the document instead of mounting a second
- * one, and creates its own on `document.body` only when none exists. Adoption
- * keeps your authored attributes (position/stack/appearance) but binds the
- * imperative store to `toasts`, replacing an array you were driving as data —
- * so within one app, either own the array or call `toast()`, not both. With
- * two or more regions placed, the first in document order is adopted and a
- * one-time console.warn flags the ambiguity.
- *
- * Because it is a real `kai-*` element it carries its own shadow root + the
- * shared kit stylesheet, so it is viewport-positioned AND kit-styled.
- *
- * Stack-level defaults are also declarative: `<kai-toast-region appearance="card"
- * inverse>` makes every toast that doesn't set its own `appearance`/`inverse`
- * render as an inverted card. A per-toast value always wins.
- *
- * Your app chrome must stay below the toast layer; set `--kai-toast-z`
- * (default 100) on the host to move the layer.
- */
-defineWebComponent<Props, Events>('kai-toast-region', {
-  toasts: [],
-  position: 'top-center',
-  max: 3,
-  stack: 'expanded',
-  appearance: 'pill',
-  inverse: false,
-  target: undefined,
-}, (props, { dispatch, flag }) => {
-  // `max` may arrive as a string attribute (`<kai-toast-region max="2">`).
-  const max = () => {
-    const raw = props.max as unknown;
-    const n = typeof raw === 'string' ? parseInt(raw, 10) : raw;
-    return typeof n === 'number' && !Number.isNaN(n) ? n : 3;
-  };
-
-  const remove = (id: string) => {
-    // Drop from the shared store (imperative path). For purely-declarative
-    // consumers the store simply won't contain the id — the dispatched event
-    // is the signal for them to update their own `toasts` array.
-    toastStore.dismiss(id);
-  };
-
-  return (
-    <ToastRegion
-      toasts={props.toasts ?? []}
-      position={props.position}
-      max={max()}
-      stack={props.stack as 'expanded' | 'collapsed' | undefined}
-      appearance={props.appearance as ToastAppearance | undefined}
-      inverse={flag('inverse')}
-      target={props.target as HTMLElement | undefined}
-      onDismiss={(id, reason) => {
-        remove(id);
-        dispatch('kai-dismiss', { id, reason });
-      }}
-      onAction={(id, label) => dispatch('kai-action', { id, label })}
-    />
-  );
-});

package/src/elements/tool.tsx

@@ -1,78 +0,0 @@
-import { createSignal, Show } from 'solid-js';
-import { defineWebComponent } from './define';
-import { Tool, type ToolPart } from '../components/tool';
-import { wireDisclosure } from './disclosure';
-import type { CollapsibleController } from '../ui/collapsible';
-
-interface Props extends Record<string, unknown> {
-  /** The tool-call to display. Set as a JS property. */
-  tool?: ToolPart;
-  /** Drive/observe open state (Shoelace-style: settable + reflected to the `open`
-   *  attribute; the element still self-manages on trigger click). Set
-   *  `el.open = true`, or `<kai-tool open>`; listen for `kai-open-change`. */
-  open?: boolean;
-  /** Initial open state on mount (uncontrolled seed). */
-  defaultOpen?: boolean;
-  /** Gate the disclosure trigger: programmatic `show()/hide()/toggle()` still
-   *  work, but the trigger click no longer toggles. */
-  disabled?: boolean;
-}
-
-/** Events fired by `<kai-tool>`. */
-interface Events {
-  /** The panel expanded or collapsed (by trigger click or a method). */
-  'kai-open-change': { open: boolean };
-}
-
-/**
- * `<kai-tool>` — a collapsible tool-call panel (input/output inspection with a
- * state badge). Data via the `tool` property. Open state is the standard overlay
- * surface: settable+reflecting `open`, `kai-open-change`, and
- * `show()`/`hide()`/`toggle()` (gated by `disabled`); seed with `defaultOpen`.
- */
-defineWebComponent<Props, Events>('kai-tool', {
-  tool: undefined,
-  open: undefined,
-  defaultOpen: undefined,
-  disabled: undefined,
-}, (props, ctx) => {
-  const { flag, reflectFlag } = ctx;
-
-  // A SIGNAL, not a `let`. This facade gates its whole subtree on `<Show when={props.tool}>`,
-  // and `tool` is an object prop, so the only sequence a consumer of the HTML spelling
-  // has is markup-then-assign: the element connects with no tool, renders nothing, and
-  // the Collapsible — and therefore the controller — arrives a tick later.
-  //
-  // With a plain `let`, wireDisclosure's effects ran once against `undefined` and never
-  // again, because the getter they were handed was not reactive and a bare `open`
-  // attribute never changes `props.open` to re-trigger them. Net result: `<kai-tool open>`
-  // silently stayed shut while `el.open` read back `true` — the property and the
-  // rendering disagreed. Making the controller reactive is the whole fix: the effects
-  // re-run the moment it lands. `Tool` already tracks its own copy this way internally.
-  // Pinned by the ordering rows in tests/elements/tool.test.tsx.
-  const [api, setApi] = createSignal<CollapsibleController>();
-
-  // The standard disclosure surface: settable+reflecting `open`, kai-open-change,
-  // show/hide/toggle, disabled-gating. See ./disclosure. This is the SOLE emitter
-  // of kai-open-change — the Tool/Collapsible no longer wires its own.
-  wireDisclosure(ctx, api, () => props.open);
-
-  // `disabled` reflects too, following kai-dock. Without it the prop is write-only in
-  // the read direction AND deaf in the write one: `el.setAttribute('disabled', '')`
-  // after mount is parsed by component-register to `undefined`, so the prop never
-  // changes and nothing re-renders. reflectFlag's coercing setter resolves that
-  // `undefined` back through the same `flag()` policy, which is what makes the plain
-  // HTML gesture work at runtime and not only at parse time (findings G-05).
-  reflectFlag('disabled');
-
-  return (
-    <Show when={props.tool}>
-      <Tool
-        toolPart={props.tool!}
-        defaultOpen={flag('defaultOpen')}
-        disabled={flag('disabled')}
-        controllerRef={(a) => setApi(a)}
-      />
-    </Show>
-  );
-});

package/src/elements/tooltip.tsx

@@ -1,85 +0,0 @@
-import { type Placement } from '@floating-ui/dom';
-import { Tooltip, type TooltipController } from '../ui/tooltip';
-import { defineWebComponent } from './define';
-import { wireDisclosure } from './disclosure';
-
-interface Props extends Record<string, unknown> {
-  /** The hint text shown on hover/focus of the slotted trigger. */
-  content?: string;
-  /** Delay (ms) before the tooltip appears on hover. Defaults to 600. Focus
-   *  shows it immediately regardless. */
-  openDelay?: number;
-  /** Delay (ms) before it hides after the pointer leaves. Defaults to 0 (hides
-   *  immediately). */
-  closeDelay?: number;
-  /** Preferred placement: `'top' | 'bottom' | 'left' | 'right'` (+ optional
-   *  `-start`/`-end`). Defaults to `'top'`; flips to stay in view. */
-  placement?: string;
-  /** Drive/observe open state (Shoelace-style: settable + reflected to the `open`
-   *  attribute, the element still self-manages on hover/focus). Set `el.open = true`,
-   *  or `<kai-tooltip open>`; listen for `kai-open-change`. */
-  open?: boolean;
-  /** Initial open state on mount (uncontrolled seed). */
-  defaultOpen?: boolean;
-  /** Turn the tooltip off while keeping the trigger mounted (hover/focus and
-   *  `show()` no longer open it). */
-  disabled?: boolean;
-}
-
-/** Events fired by `<kai-tooltip>`. */
-interface Events {
-  /** The tooltip opened or closed (by hover/focus, outside-click, or a method). */
-  'kai-open-change': { open: boolean };
-}
-
-/**
- * `<kai-tooltip>` — wraps a trigger and shows a hint on hover/focus. Put the
- * trigger as light-DOM content; set the text via `content`. Positions itself and
- * dismisses on Escape/outside-click; the content is portaled inside the shadow
- * root so it isn't clipped.
- *
- * ```html
- * <kai-tooltip content="Voice input">
- *   <kai-button variant="subtle" size="icon" icon="mic" label="Voice input"></kai-button>
- * </kai-tooltip>
- * ```
- */
-defineWebComponent<Props, Events>('kai-tooltip', {
-  content: '',
-  openDelay: undefined,
-  closeDelay: undefined,
-  placement: undefined,
-  open: undefined,
-  defaultOpen: undefined,
-  disabled: undefined,
-}, (props, ctx) => {
-  const { flag } = ctx;
-  let api: TooltipController | undefined;
-
-  // The standard overlay surface: settable+reflecting `open`, kai-open-change,
-  // show/hide/toggle, disabled-gating. See ./disclosure.
-  wireDisclosure(ctx, () => api, () => props.open);
-
-  return (
-    <>
-      {/* The shared element base sets `:host{display:block}` (styles.css). A block
-          host wraps the inline-flex trigger in a line box, so the font-descender
-          strut makes the host taller than the control and pins the control to the
-          top, so it reads off-center beside non-tooltipped siblings in a
-          flex-items-center row. inline-flex (like kai-button) drops the line box so
-          the host hugs the trigger and their centers line up. */}
-      <style>{':host{display:inline-flex}'}</style>
-      <Tooltip
-        content={props.content ?? ''}
-        openDelay={props.openDelay != null ? Number(props.openDelay) : undefined}
-        closeDelay={props.closeDelay != null ? Number(props.closeDelay) : undefined}
-        placement={(props.placement as Placement | undefined) ?? undefined}
-        defaultOpen={flag('defaultOpen')}
-        disabled={flag('disabled')}
-        controllerRef={(a) => (api = a)}
-      >
-        <slot />
-      </Tooltip>
-    </>
-  );
-});

package/src/elements/validate-messages.ts

@@ -1,76 +0,0 @@
-import type { ChatMessage } from './chat-types';
-
-/**
- * Boundary validation for the untyped `message` / `messages` properties.
- *
- * A web component's properties are an untyped boundary: nothing stops a consumer
- * from assigning the pre-0.20.0 `{ id, role, content }` shape, and TypeScript is
- * not there at runtime to catch it. `parts` is REQUIRED internally, so a message
- * without one throws inside a Solid render pass (`groupMessageParts` iterating
- * `undefined`), and an uncaught exception there blanks the WHOLE element, not
- * just the offending message. Validating here turns that into a skipped message
- * plus one clear console error naming the element and the expected shape.
- */
-
-/** True when `m` carries the required `parts` array. */
-export function hasParts(m: unknown): m is ChatMessage {
-  return !!m && typeof m === 'object' && Array.isArray((m as { parts?: unknown }).parts);
-}
-
-/** Shared tail of every diagnostic, so all facades say the same thing. */
-const EXPECTED =
-  "each entry needs a 'parts' array (e.g. parts: [{ type: 'text', text: 'Hi' }]). " +
-  "The 'content' string field was removed in 0.20.0.";
-
-const EMPTY: ChatMessage[] = [];
-
-/**
- * Creates a per-element-instance validator for a `messages` array. Returns the
- * INPUT array unchanged when every entry is valid (no allocation, so streaming
- * identity checks upstream still hold), a filtered copy when some are not, and
- * `[]` when the property itself is not an array.
- *
- * Logs at most one `console.error` per validation pass, and never re-logs for a
- * message object it has already reported, so an unrelated re-render during
- * streaming does not spam the console.
- */
-export function createMessagesGuard(tag: string): (messages: unknown) => ChatMessage[] {
-  const warned = new WeakSet<object>();
-  // WeakSet only holds objects, so primitive entries (a stray string/null in the
-  // array) get one shared latch instead.
-  let warnedPrimitive = false;
-  let warnedNonArray = false;
-
-  return (messages: unknown): ChatMessage[] => {
-    if (!Array.isArray(messages)) {
-      if (messages != null && !warnedNonArray) {
-        warnedNonArray = true;
-        console.error(`<${tag}>: 'messages' must be an array. Ignoring it.`);
-      }
-      return EMPTY;
-    }
-    // Fast path: nothing to report, hand back the same reference.
-    if (messages.every(hasParts)) return messages as ChatMessage[];
-
-    let invalid = 0;
-    let unreported = 0;
-    for (const m of messages) {
-      if (hasParts(m)) continue;
-      invalid++;
-      if (m !== null && typeof m === 'object') {
-        if (warned.has(m as object)) continue;
-        warned.add(m as object);
-      } else {
-        if (warnedPrimitive) continue;
-        warnedPrimitive = true;
-      }
-      unreported++;
-    }
-    if (unreported > 0) {
-      console.error(
-        `<${tag}>: skipped ${invalid} of ${messages.length} messages: ${EXPECTED}`,
-      );
-    }
-    return messages.filter(hasParts);
-  };
-}

package/src/elements/voice-input.tsx

@@ -1,100 +0,0 @@
-import { defineWebComponent } from './define';
-import { VoiceInput, type VoiceInputController } from '../components/voice-input';
-
-interface Props extends Record<string, unknown> {
-  /**
-   * Transcriber the host supplies: records audio, returns the text. This is a
-   * **function-valued property** (`el.transcribe = async blob => '...'`) because
-   * a value-returning callback can't be modelled as a fire-and-forget event.
-   */
-  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. Also the
-   *  unsupported-fallback signal: no `transcribe`, no SpeechRecognition, so only
-   *  the blob is produced (no text). */
-  'kai-audio-captured': { blob: Blob };
-  /** 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 };
-  /** A voice session failed, so no failure is ever silent. `detail.source` names
-   *  the failing side (`recognition` on `<kai-voice-input>`, `synthesis` on
-   *  `<kai-voice-output>`), `detail.error` carries the platform error code, the
-   *  thrown exception's name, or `no-result` when recognition ended with no error
-   *  and no text (the user said nothing), and `detail.message` is human-readable.
-   *  Deliberate cancellation does not fire. */
-  'kai-voice-error': { source: 'recognition'; error: string; message: string };
-}
-
-/**
- * `<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), `kai-voice-error`
- * (a failed or empty session) and, with `interim`, `kai-transcript-interim`
- * (live partials).
- */
-defineWebComponent<Props, Events>('kai-voice-input', {
-  transcribe: undefined,
-  disabled: false,
-  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 })}
-      onError={(detail) => dispatch('kai-voice-error', detail)}
-      controllerRef={(c) => (controller = c)}
-    />
-  );
-});

package/src/elements/voice-output.tsx

@@ -1,82 +0,0 @@
-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. `speaking: true`
-   *  fires when audio actually starts (utterance.onstart natively; audio playback
-   *  beginning on the `synthesize` path), not when speak() is called; earlier
-   *  releases fired it optimistically inside speak() itself. 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 };
-  /** A voice session failed, so no failure is ever silent. `detail.source` names
-   *  the failing side (`recognition` on `<kai-voice-input>`, `synthesis` on
-   *  `<kai-voice-output>`), `detail.error` carries the platform error code, the
-   *  thrown exception's name, or `no-result` when recognition ended with no error
-   *  and no text (the user said nothing), and `detail.message` is human-readable.
-   *  Deliberate cancellation does not fire. */
-  'kai-voice-error': { source: 'synthesis'; error: string; message: string };
-}
-
-/**
- * `<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`, `kai-voice-error` (a failed synthesis) 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 })}
-      onError={(detail) => dispatch('kai-voice-error', detail)}
-      controllerRef={(c) => (controller = c)}
-    />
-  );
-});