@alexkroman1/aai-ui 0.12.3 → 0.14.0

package/dist/default-client/assets/playback-processor-CjDbc9iH.js

@@ -0,0 +1,314 @@
+import{r as e}from"./index-DPfmSFmc.js";import{t}from"./_module-url-BX0RuRU2.js";var n=`
+class PlaybackProcessor extends AudioWorkletProcessor {
+  constructor(options) {
+    super();
+    const opts = options.processorOptions || {};
+    // The node's context IS the playback context (audio/voice-io.ts asserts its rate),
+    // so the worklet-global sampleRate is authoritative; the option exists
+    // for the node-less test harness.
+    const rate = opts.sampleRate ?? sampleRate;
+    // Kept, because every derived quantity below reads it and \`bufferedMs\` in
+    // process() is the one that used to read the worklet global instead. Those
+    // agree in production (the option is unset, so \`rate\` IS \`sampleRate\`) and
+    // diverge only in the node-less harness — which is the one place a spec
+    // could ever assert on the reported backlog, so the divergence made the
+    // number untestable rather than wrong.
+    this.rate = rate;
+    // The one fill target — for the start of a turn and for recovery after an
+    // underrun alike. If 'done' arrives first (short utterance), start
+    // immediately instead of waiting for audio that is never coming.
+    this.fillSamples = Math.floor((rate * (opts.fillMs ?? 200)) / 1000);
+    // Concealment source: a ring of the most recently played samples, looped
+    // under a decaying gain to cover a gap. Sized to the fade window, with a
+    // per-sample decay that reaches the floor exactly at its end.
+    this.concealCapacity = Math.max(1, Math.floor((rate * 40) / 1000));
+    this.concealBuf = new Float32Array(this.concealCapacity);
+    this.concealDecay = Math.exp(Math.log(${e}) / this.concealCapacity);
+    // Float32 ring buffer — PLAYBACK_BUFFER_SECONDS at the context sample
+    // rate. Allocated once for the node's lifetime; per-turn state resets via
+    // resetTurn(). writePos and readPos are absolute (monotonic) sample
+    // counts; the buffer is indexed modulo capacity so a longer reply keeps
+    // playing instead of writing past the end and going silent.
+    this.capacity = rate * 60;
+    this.samples = new Float32Array(this.capacity);
+    // Cadence for the 'progress' report in process(), counted in samples so
+    // the hot path never reads a clock. Survives resetTurn(): the host clamps
+    // upward only, so a stale count costs at most one extra report.
+    this.reportIntervalSamples = Math.floor((rate * 500) / 1000);
+    this.sinceReportSamples = 0;
+    // Platform endianness probe: the wire format is PCM16 little-endian, so
+    // the Int16Array fast path in ingestBytes is only valid on LE hosts
+    // (every shipping browser target; the DataView path is the fallback).
+    this.littleEndian = new Uint8Array(new Uint16Array([1]).buffer)[0] === 1;
+    this.resetTurn();
+
+    this.port.onmessage = (e) => {
+      const d = e.data;
+      if (d.event === 'write') {
+        this.ingestBytes(d.buffer);
+      } else if (d.event === 'interrupt') {
+        // Applied eagerly, not deferred to the next process(): onmessage and
+        // process() never interleave (one audio thread), and a deferred
+        // interrupt would let 'write'/'done' frames for the NEXT turn
+        // coalesce in ahead of it and be wiped by the reset along with the
+        // cancelled turn's audio.
+        this.stopTurn('interrupt');
+      } else if (d.event === 'done') {
+        this.isDone = true;
+        // Echoed back on this turn's 'stop' so the host can tell WHICH turn
+        // drained: a stop already in flight when a barge-in lands would
+        // otherwise settle the next turn's done() the moment it arrives.
+        this.doneTurn = d.turn ?? null;
+      }
+    };
+  }
+
+  // Reset per-turn state so the node is reusable across replies without
+  // reallocating the sample buffer or re-instantiating the worklet.
+  resetTurn() {
+    this.isDone = false;
+    // Host turn id carried by this turn's 'done' (null until one arrives).
+    this.doneTurn = null;
+    this.playing = false;
+    // Whether any real audio has been rendered this turn. Separates a turn's
+    // pre-roll (nothing to extrapolate from, and not a defect) from a
+    // mid-turn underrun.
+    this.hasPlayed = false;
+    // Carry-over byte for split samples across chunks
+    this.carry = null;
+    this.writePos = 0;
+    this.readPos = 0;
+    // Concealment ring state and the current fade position.
+    this.concealLen = 0;
+    this.concealWrite = 0;
+    this.concealPos = 0;
+    this.concealGain = 1;
+    // Episode flags, so a multi-quantum gap counts as one event.
+    this.concealing = false;
+    this.concealedSilence = false;
+    // Reported to the host on 'stop'. A fresh object per turn: the one just
+    // posted must not be mutated by the next turn.
+    this.stats = {
+      concealedSamples: 0,
+      silentConcealedSamples: 0,
+      concealmentEvents: 0,
+      silentConcealmentEvents: 0,
+    };
+  }
+
+  // End the current turn: notify the host and rearm for the next reply.
+  // Must NOT return false from process() — a processor that stops is dead
+  // for good, forcing a new node (and buffer) per reply.
+  // \`reason\` ('interrupt' | 'done') tells the host which turn boundary this
+  // stop belongs to — interrupt-stops are dropped host-side, flush() having
+  // already settled that turn — and \`turn\` names WHICH turn drained (the id
+  // this turn's 'done' carried), so a drain-stop still in flight when a
+  // barge-in lands cannot settle the next turn's done() early.
+  stopTurn(reason) {
+    this.port.postMessage({ event: 'stop', reason, turn: this.doneTurn, stats: this.stats });
+    this.resetTurn();
+  }
+
+  // Cover a quantum (from \`start\`) where real audio should have been.
+  //
+  // Before the turn's first samples there is nothing to extrapolate from, so
+  // the gap is plain silence and counted as nothing — WebRTC likewise only
+  // counts concealment once playout has begun. After that, loop the retained
+  // tail under a decaying gain: a hard zero-fill is a discontinuity mid-word,
+  // which is the click that makes a brief stall sound like breakage.
+  coverGap(out, start) {
+    if (!this.hasPlayed) {
+      out.fill(0, start);
+      return;
+    }
+    if (!this.concealing) {
+      this.concealing = true;
+      this.concealedSilence = false;
+      this.stats.concealmentEvents++;
+    }
+    const total = out.length - start;
+    const len = this.concealLen;
+    let silent = 0;
+    // Second condition: once the fade has decayed to the floor, every sample
+    // the loop would emit is 0 anyway — bulk-fill instead of running 128
+    // branchy iterations per quantum for the whole tail of a long stall.
+    if (len === 0 || this.concealGain < ${e}) {
+      out.fill(0, start);
+      silent = total;
+    } else {
+      let g = this.concealGain;
+      for (let i = start; i < out.length; i++) {
+        if (g < ${e}) {
+          // The fade has run out: keep counting the gap, but stop looping a
+          // fragment that is now inaudible anyway.
+          out[i] = 0;
+          silent++;
+          continue;
+        }
+        out[i] = this.concealBuf[this.concealPos] * g;
+        this.concealPos = this.concealPos + 1 === len ? 0 : this.concealPos + 1;
+        g *= this.concealDecay;
+      }
+      this.concealGain = g;
+    }
+    this.stats.concealedSamples += total;
+    if (silent > 0) {
+      this.stats.silentConcealedSamples += silent;
+      if (!this.concealedSilence) {
+        this.concealedSilence = true;
+        this.stats.silentConcealmentEvents++;
+      }
+    }
+  }
+
+  // Retain the tail of a rendered quantum as the next gap's concealment
+  // source, and close any episode the real audio just ended.
+  rememberTail(out, n) {
+    const cap = this.concealCapacity;
+    const take = Math.min(n, cap);
+    // Bulk copies (this runs on every cleanly rendered quantum): the tail is
+    // one contiguous source run, landing in at most two ring runs.
+    const tail = out.subarray(n - take, n);
+    const first = Math.min(take, cap - this.concealWrite);
+    this.concealBuf.set(tail.subarray(0, first), this.concealWrite);
+    if (take > first) this.concealBuf.set(tail.subarray(first), 0);
+    this.concealWrite = (this.concealWrite + take) % cap;
+    this.concealLen = Math.min(cap, this.concealLen + take);
+    // Read the loop oldest-first; once the ring is full the write cursor is
+    // the oldest retained sample.
+    this.concealPos = this.concealLen === cap ? this.concealWrite : 0;
+    this.concealing = false;
+    this.concealGain = 1;
+  }
+
+  ingestBytes(uint8) {
+    let bytes = uint8;
+
+    if (this.carry !== null) {
+      const merged = new Uint8Array(1 + bytes.length);
+      merged[0] = this.carry;
+      merged.set(bytes, 1);
+      bytes = merged;
+      this.carry = null;
+    }
+
+    if (bytes.length % 2 !== 0) {
+      this.carry = bytes[bytes.length - 1];
+      bytes = bytes.subarray(0, bytes.length - 1);
+    }
+
+    if (bytes.length === 0) return;
+    const numSamples = bytes.length / 2;
+    const cap = this.capacity;
+    const samples = this.samples;
+    if (this.littleEndian && (bytes.byteOffset & 1) === 0) {
+      // Fast path: 2-byte-aligned LE bytes wrap directly as an Int16Array;
+      // copy wrap-aware in at most two runs with no per-sample DataView call
+      // or modulo. This runs on the realtime audio thread.
+      const int16 = new Int16Array(bytes.buffer, bytes.byteOffset, numSamples);
+      let src = 0;
+      let dst = this.writePos % cap;
+      while (src < numSamples) {
+        const run = Math.min(numSamples - src, cap - dst);
+        for (let j = 0; j < run; j++) {
+          samples[dst + j] = int16[src + j] / 0x8000;
+        }
+        src += run;
+        dst = 0;
+      }
+    } else {
+      // Odd byte offset (or big-endian host): fall back to per-sample reads.
+      const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.length);
+      let dst = this.writePos % cap;
+      for (let i = 0; i < numSamples; i++) {
+        samples[dst] = view.getInt16(i * 2, true) / 0x8000;
+        dst++;
+        if (dst === cap) dst = 0;
+      }
+    }
+    this.writePos += numSamples;
+    // If the producer outran the consumer by more than the buffer holds, drop
+    // the oldest unplayed audio rather than reading samples we've overwritten.
+    if (this.writePos - this.readPos > this.capacity) {
+      this.readPos = this.writePos - this.capacity;
+    }
+  }
+
+  process(inputs, outputs) {
+    // No output wired up yet — nothing to render this quantum. Throwing here
+    // would permanently kill the processor (the node is persistent per
+    // session), so guard like the capture processor does.
+    if (!outputs[0] || !outputs[0][0]) return true;
+    const out = outputs[0][0];
+    const avail = this.writePos - this.readPos;
+
+    // Report the unplayed backlog to the host (\`playback_progress\`). This IS
+    // the closed-loop signal: the host otherwise models playback open-loop —
+    // every forwarded chunk assumed to start playing on arrival at exactly
+    // 1.0x — and cannot see a buffer that has run ahead of the wall clock.
+    // Measured against a client draining at 0.6x, the host declared the line
+    // silent while it still held seconds of the reply, and then opened the
+    // speaking-edge gate over speech the caller had not heard.
+    //
+    // Sent from process() rather than a timer because this is the only place
+    // that sees the buffer on the audio thread; the counter is in QUANTA, so
+    // it costs an integer compare per render and no clock read. Silence is not
+    // reported: an empty buffer is what the host already assumes.
+    this.sinceReportSamples += out.length;
+    if (this.sinceReportSamples >= this.reportIntervalSamples) {
+      this.sinceReportSamples = 0;
+      if (avail > 0) {
+        this.port.postMessage({ event: 'progress', bufferedMs: (avail / this.rate) * 1000 });
+      }
+    }
+
+    // Filling: wait for the target. 'done' short-circuits it — what is
+    // buffered is all there will be, so there is nothing left to wait for.
+    if (!this.playing) {
+      if (avail >= this.fillSamples || this.isDone) {
+        this.playing = true;
+      } else {
+        this.coverGap(out, 0);
+        return true;
+      }
+    }
+
+    // Underrun: this quantum cannot be filled and more audio is still coming.
+    // Go back to filling and cover the gap, leaving
+    // readPos untouched — the fragment stays buffered and plays intact once
+    // the buffer recovers, instead of being dribbled out a few samples at a
+    // time for the rest of the turn.
+    if (avail < out.length && !this.isDone) {
+      this.playing = false;
+      this.coverGap(out, 0);
+      return true;
+    }
+
+    if (avail > 0) {
+      const n = Math.min(avail, out.length);
+      // Copy from the ring buffer, splitting across the wrap boundary.
+      const start = this.readPos % this.capacity;
+      const first = Math.min(n, this.capacity - start);
+      out.set(this.samples.subarray(start, start + first), 0);
+      if (n > first) out.set(this.samples.subarray(0, n - first), first);
+      this.readPos += n;
+      // Only reachable with n < out.length on the turn's final partial
+      // quantum (the underrun branch above catches every other case).
+      out.fill(0, n);
+      this.hasPlayed = true;
+      this.rememberTail(out, n);
+      return true;
+    }
+
+    // Drained and done: end the turn. Not reachable mid-turn — an empty
+    // buffer with audio still coming is the underrun branch above.
+    out.fill(0);
+    if (this.isDone) {
+      this.stopTurn('done');
+    }
+    return true;
+  }
+}
+
+registerProcessor('playback-processor', PlaybackProcessor);
+`,r=t(n);export{r as default};

package/dist/default-client/index.html

@@ -0,0 +1,15 @@
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0, viewport-fit=cover" />
+    <title>aai</title>
+    <link rel="icon" href="./favicon.ico" />
+    <style>html,body{background:#fbf8f2;margin:0}</style>
+    <script type="module" crossorigin src="./assets/index-DPfmSFmc.js"></script>
+    <link rel="stylesheet" crossorigin href="./assets/index-8ihb1Urm.css">
+  </head>
+  <body>
+    <main id="app"></main>
+  </body>
+</html>

package/dist/default-client-entry.d.ts

@@ -0,0 +1,6 @@
+/**
+ * The prebuilt default client's bundle entry (`index.html` loads it): the
+ * stylesheet plus one call. The choice of page lives in `default-client.tsx`,
+ * where a spec can drive it without importing a side effect.
+ */
+import "../styles.css";

package/dist/default-client.d.ts

@@ -0,0 +1,19 @@
+/** The two mounts the default client chooses between, injectable for a spec. */
+export type DefaultClientMounts = {
+    mountClient: (config: {
+        name?: string;
+    }) => unknown;
+    mountPage: (config: {
+        name?: string;
+    }) => unknown;
+};
+/**
+ * Look up the agent's front door and mount the matching shell.
+ *
+ * A function rather than the module's own side effect so the CHOICE can be
+ * driven with fake mounts; `default-client-entry.tsx` is the bundle entry that
+ * calls it. The lookup already degrades to "the agent declared nothing" on
+ * every failure path — which resolves to `page: "voice"`, the front door this
+ * can always mount.
+ */
+export declare function bootDefaultClient(mounts?: DefaultClientMounts): Promise<void>;

package/dist/define-client.d.ts

@@ -1,57 +1,200 @@
-import type { ComponentType } from "preact";
-import { type ClientTheme } from "./client-context.ts";
-import { type VoiceSession, type WebSocketConstructor } from "./session.ts";
-import { type SessionSignals } from "./signals.ts";
+/** @jsxImportSource react */
+import { type ComponentType, type ReactNode } from "react";
+import { type ToolDisplayConfig } from "./components/tool-config-context.ts";
+import type { BrowserSession } from "./session/index.ts";
+import { createBrowserSession } from "./session/index.ts";
+import type { ClientTheme, VoiceSessionOptions } from "./types.ts";
 /**
- * Options for {@link defineClient}.
+ * Configuration passed to {@link mountClient}.
+ *
+ * The session-forwarded fields are picked from {@link VoiceSessionOptions}
+ * (one source of truth for types and docs) rather than re-declared — a
+ * re-declared copy is exactly how doc comments drift. It is NOT the session's
+ * own options type: that is {@link VoiceSessionOptions}, which
+ * `createBrowserSession` takes and which three of these fields come from.
+ *
+ * @remarks
+ * **One flat type, not a union of tiers.** `component` is what decides which
+ * shell renders — absent, the default one (StartScreen + ChatView, optional
+ * sidebar); present, the caller's own component inside the same providers —
+ * and that decision is made at runtime, where every field can be honoured. It
+ * used to be a union whose two arms banned each other's fields with `?: never`,
+ * and the failure that shape produces is recorded twice in this file's history:
+ * `mountClient({ name, component })` and `mountClient({ component, tools })` were both
+ * the natural thing to write, both were refused with *"Type 'string' is not
+ * assignable to type 'undefined'"*, and both cost a build round each time
+ * before the ban was lifted. What was left banned was `sidebar` beside a
+ * `component`, which invited the identical failure for a combination
+ * {@link mountClient} can simply render.
  *
  * @public
  */
-export type ClientOptions = {
+export type ClientConfig = Pick<VoiceSessionOptions, "onSessionId" | "resumeSessionId" | "location" | "phone" | "client" | "token" | "WebSocket"> & {
     /** CSS selector or DOM element to render into. Defaults to `"#app"`. */
     target?: string | HTMLElement;
     /** Base URL of the AAI platform server. Derived from `location.href` by default. */
     platformUrl?: string;
-    /** Agent title shown in the header and start screen. */
-    title?: string;
     /** Theme color overrides. */
     theme?: ClientTheme;
-    /** Called when the server sends a session ID. Store it for reconnection. */
-    onSessionId?: ((sessionId: string) => void) | undefined;
-    /** Session ID from a previous connection for resuming persisted state. */
-    resumeSessionId?: string | undefined;
-    /** WebSocket constructor override. Passed through to VoiceSessionOptions. */
-    WebSocket?: WebSocketConstructor | undefined;
+    /**
+     * Full custom component to render instead of the default shell.
+     *
+     * It is rendered inside the same providers the default shell gets, so every
+     * session hook, `useTheme` and the tool display config work in it unchanged.
+     */
+    component?: ComponentType;
+    /**
+     * Agent name shown in the header and start screen — and, with a `component`,
+     * the page title, there being no shell header to put it in. Left out, the
+     * default shell asks the agent for its own declared name.
+     */
+    name?: string;
+    /**
+     * Optional sidebar component rendered alongside the main pane.
+     *
+     * Beside a `component` it is the custom component that becomes the main pane,
+     * in the same {@link SidebarLayout} the default shell uses.
+     */
+    sidebar?: ComponentType;
+    /** CSS width of the sidebar. Defaults to `"18rem"`. */
+    sidebarWidth?: string;
+    /**
+     * Which side the sidebar sits on. Defaults to `"left"`.
+     *
+     * Routed through the same {@link SidebarLayout} whether the main pane is the
+     * default shell or a `component`, for the reason `sidebar` itself is: the two
+     * branches build the same layout and a field honoured by only one of them is
+     * the shape this config used to have.
+     */
+    sidebarPosition?: "left" | "right";
+    /**
+     * Element rendered in place of the AAI logo — on the start card, and in the
+     * shell header once the session begins.
+     *
+     * Both, because they are one mark: an agent whose start screen shows a slice
+     * of pizza and whose header shows our logo reads as two products.
+     */
+    icon?: ReactNode;
+    /** A line under the title on the start card. */
+    subtitle?: string;
+    /** Label of the start CTA. Defaults to `"Start Conversation"`. */
+    buttonText?: string;
+    /**
+     * Tool display config: icon and label overrides keyed by tool name.
+     *
+     * Honoured with a custom `component` too: {@link mountClient} installs it into
+     * `ToolConfigContext`, and the consumer is `ToolCallBlock` — which a custom
+     * component renders as soon as it uses `MessageList` or `ChatView`, the usual
+     * way to build one.
+     */
+    tools?: ToolDisplayConfig;
 };
 /**
- * Handle returned by {@link defineClient} for cleanup.
+ * Handle returned by {@link mountClient} for cleanup.
  *
  * Implements `Disposable` so it can be used with `using`.
  *
  * @public
  */
 export type ClientHandle = {
-    /** The underlying voice session. */
-    session: VoiceSession;
-    /** Reactive session controls for the mounted UI. */
-    signals: SessionSignals;
-    /** Unmount the UI, remove injected styles, and disconnect the session. */
+    /** The underlying session core. */
+    session: BrowserSession;
+    /** Unmount the UI and disconnect the session. */
+    dispose(): void;
+    /** Alias for `dispose` for use with `using`. */
+    [Symbol.dispose](): void;
+};
+/**
+ * The element a mount renders into.
+ *
+ * Exported so `mountPage()` resolves its target the same way `mountClient()` does — the
+ * default selector and the "element not found" sentence are part of what an
+ * author has learned, and a second copy is how the two mounts come to disagree
+ * about which one they were given.
+ *
+ * @internal
+ */
+export declare function resolveContainer(target?: string | HTMLElement): HTMLElement;
+/**
+ * What a mount hands back: unmount, and `using` support.
+ *
+ * @internal
+ */
+export type MountedRoot = {
+    /** Unmount the React tree (and, for `mountClient()`, dispose the session). */
     dispose(): void;
     /** Alias for `dispose` for use with `using`. */
     [Symbol.dispose](): void;
 };
+/**
+ * Render `node` into `container` and hand back its teardown.
+ *
+ * Shared by {@link mountClient} and `mountPage()` because the plumbing is identical and
+ * the two decisions in it are not obvious enough to be re-derived: the root is
+ * created here rather than by the caller so nothing else can hold one, and the
+ * render is `flushSync` so the mount is observable to the caller's NEXT
+ * STATEMENT (and to a test) rather than scheduled — `mountClient()` returns a handle
+ * whose session is expected to be live, and `mountPage()` returns one a caller may
+ * dispose immediately.
+ *
+ * `onDispose` runs after the unmount, which is the order `mountClient()` needs: the
+ * tree comes down before the session under it goes away.
+ *
+ * @internal
+ */
+export declare function mountRoot(container: HTMLElement, node: ReactNode, onDispose?: () => void): MountedRoot;
 /**
  * Define and mount a client UI for a voice agent.
  *
- * Creates a {@link VoiceSession}, wraps it in
- * {@link SessionSignals}, and renders the component
- * inside a {@link SessionProvider}.
+ * **Config only:** leave `component` out and the default shell renders
+ * (StartScreen + ChatView, optional sidebar).
+ *
+ * **A custom component:** pass `component` and it is rendered inside the same
+ * providers instead of the default shell — beside a `sidebar` if one is given,
+ * in the same {@link SidebarLayout}. A provided `name` then also sets
+ * `document.title`, there being no shell header to show it in.
+ *
+ * Mounts into `target` — a CSS selector or DOM element, defaulting to
+ * `"#app"` — and throws `Element not found: <target>` when the selector
+ * matches nothing.
+ *
+ * @example The default shell
+ * ```tsx
+ * import { mountClient } from "@alexkroman1/aai-ui";
+ *
+ * function OrderPanel() {
+ *   return <div>Cart</div>;
+ * }
+ *
+ * mountClient({
+ *   name: "Pizza Ordering",
+ *   theme: { bg: "#1a1a1a", primary: "#e55" },
+ *   sidebar: OrderPanel,
+ *   tools: { add_pizza: { icon: "🍕", label: "Adding pizza" } },
+ * });
+ * ```
+ *
+ * @example A custom component
+ * ```tsx
+ * import { mountClient, useSession } from "@alexkroman1/aai-ui";
+ *
+ * function MyCustomApp() {
+ *   const session = useSession();
+ *   return <div>{session.state}</div>;
+ * }
+ *
+ * mountClient({ component: MyCustomApp });
+ * ```
  *
- * @param Component - The Preact component to render.
- * @param options - Client options (target element, platform URL, theme).
  * @returns A {@link ClientHandle} for cleanup.
  * @throws If the target element is not found in the DOM.
  *
  * @public
  */
-export declare function defineClient(Component: ComponentType<any>, options?: ClientOptions): ClientHandle;
+export declare function mountClient(config: ClientConfig): ClientHandle;
+/**
+ * {@link mountClient} with the session factory handed in. Not on the barrel:
+ * it is the seam a spec drives with a fake core rather than replacing the
+ * session module.
+ */
+export declare function mountClientWith(config: ClientConfig, createSession: typeof createBrowserSession): ClientHandle;