@alexkroman1/aai-ui 0.12.2 → 0.13.0

package/dist/workflow-field-kind.d.ts

@@ -0,0 +1,95 @@
+/**
+ * Which control one property of a workflow's input schema renders as.
+ *
+ * `<WorkflowFields>` walks a workflow's `inputSchema` and picks a control per
+ * property. This is that decision with nothing rendered — ONE function, called
+ * by `SchemaField` itself, so a reader outside the component can ask the same
+ * question and get the same answer.
+ *
+ * **Why it is published.** The rule is not derivable from the schema by
+ * inspection: an upload property IS a plain `string` there, and the ORDER
+ * matters in a way no reader can see. The studio's API pane documents the
+ * form-to-JSON correspondence for every workflow app, and it was carrying a
+ * hand-kept mirror of the switch below — "a declared upload beats everything,
+ * then `enum`, then …" — with a comment admitting as much and a test pinning
+ * the order to catch the drift. A copy that drifted would name a control the
+ * reader cannot find on their own page. Nothing else could be done about it
+ * while the decision was private, and the same reasoning already settled the
+ * studio's SDK-subpath list: mirroring "would just move the drift somewhere
+ * new".
+ *
+ * So a NEW control added to `<WorkflowFields>` is a new member of
+ * {@link WorkflowFieldKind}, and every reader of the rule finds out from the
+ * type rather than from a table somebody remembered to edit.
+ */
+/**
+ * The control a schema property renders as inside `<WorkflowFields>`.
+ *
+ * `"none"` is not a control: it is the shape the generated form declines to
+ * guess at — a nested object, an array — because every choice (a JSON
+ * textarea, a repeater, a comma-separated string) is a guess about what the
+ * author meant, and a guess producing a value the schema then rejects is worse
+ * than no field. The API takes those shapes perfectly well; only the generated
+ * form has nothing honest to draw, so the field is written by hand and
+ * composes with the generated ones inside the same `<Form>`.
+ *
+ * There is deliberately no `"textarea"` member. A textarea is a string like a
+ * text field is — the same value over the wire — so it is a hand-written swap
+ * rather than a shape the schema can ask for.
+ *
+ * @public
+ */
+export type WorkflowFieldKind = "text" | "number" | "select" | "checkbox" | "file" | "none";
+/**
+ * A property's declared type, taking the first non-null member of a union.
+ *
+ * `["string", "null"]` is how an optional-and-nullable field converts; the
+ * control is the one the non-null half wants. Not exported from the package
+ * barrel — the published question is the KIND, and this is the one detail
+ * `<WorkflowFields>` needs past it (an integer's `step`).
+ */
+export declare function schemaTypeOf(schema: unknown): string | undefined;
+/**
+ * Which control `<WorkflowFields>` renders for one property of an input schema.
+ *
+ * @remarks
+ * The ORDER is the contract, and it is the half a reader cannot infer:
+ *
+ * 1. **A declared upload wins outright.** It is a plain `string` in the schema
+ *    — the id — so testing the type first would render a text box asking a
+ *    person to type an id no person has. The declaration is the workflow's
+ *    (`workflow({ uploads: [...] })`), not the schema's, precisely because a
+ *    marker inside the schema would only work for the library that carried it.
+ * 2. **Then a non-empty `enum`**, before the type switch: an enum of strings
+ *    is a `string` too, and a select is the narrower, better control.
+ * 3. **Then the type** — `boolean`, `number`/`integer`, `string`.
+ * 4. **Anything else is `"none"`** rather than a guess. See
+ *    {@link WorkflowFieldKind}.
+ *
+ * @example
+ * ```ts
+ * import { fieldKindFor, type WorkflowFieldKind } from "@alexkroman1/aai-ui";
+ * import type { WorkflowSummary } from "@alexkroman1/aai/workflow-api";
+ *
+ * function kindsOf(summary: WorkflowSummary): Record<string, WorkflowFieldKind> {
+ *   const uploads = new Set(summary.uploads ?? []);
+ *   const schema = summary.inputSchema as { properties?: Record<string, unknown> };
+ *   return Object.fromEntries(
+ *     Object.entries(schema.properties ?? {}).map(([name, property]) => [
+ *       name,
+ *       fieldKindFor(property, { upload: uploads.has(name) }),
+ *     ]),
+ *   );
+ * }
+ * ```
+ *
+ * @param schema - The property's JSON Schema, as `GET workflows` reports it.
+ *   Anything that is not an object reads as `"none"`.
+ * @param options - `upload` says the property is named in the workflow's own
+ *   `uploads` declaration, which is what step 1 above tests.
+ *
+ * @public
+ */
+export declare function fieldKindFor(schema: unknown, options?: {
+    upload?: boolean | undefined;
+}): WorkflowFieldKind;

package/dist/workflow-status-labels.d.ts

@@ -0,0 +1,35 @@
+/**
+ * One line describing where a run has got to, for each status there is.
+ *
+ * Two template pages carried a byte-identical `Record<WorkflowRun["status"],
+ * string>` with the same doc comment, differing only in the `running` label —
+ * which is the one a page really does want to write for itself ("Writing…",
+ * "Transcribing…") and the only one. The other four are the same sentence about
+ * the same five-member union everywhere.
+ *
+ * The exhaustiveness argument both copies were written for survives, and moves
+ * to the SDK boundary: this is a `Record` over {@link WorkflowRunStatus} rather
+ * than a `switch`, so a status added to the SDK is a compile error HERE — in one
+ * place that every page then inherits — instead of falling through a `default:`
+ * in each of them into whichever line was last. A page overriding one member
+ * keeps that: spreading a complete record cannot drop a key.
+ */
+import type { WorkflowRunStatus } from "@alexkroman1/aai/workflow-api";
+/**
+ * The default status line per {@link WorkflowRunStatus}.
+ *
+ * Override the ones your page has a better word for and keep the rest:
+ *
+ * ```ts
+ * import { WORKFLOW_STATUS_LABELS } from "@alexkroman1/aai-ui";
+ *
+ * const STATUS_LINE = { ...WORKFLOW_STATUS_LABELS, running: "Writing…" };
+ * ```
+ *
+ * The wording is deliberately about the RUN rather than about the work — a page
+ * knows what its workflow does and this does not, so `running` is the neutral
+ * "Working…" and every page that cares replaces exactly that key.
+ *
+ * @public
+ */
+export declare const WORKFLOW_STATUS_LABELS: Readonly<Record<WorkflowRunStatus, string>>;

package/dist/worklets/_module-url.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Blob-URL module for an inlined AudioWorklet processor source.
+ *
+ * A blob URL rather than a data URI because the agent page's CSP allows
+ * `script-src blob:` but not `data:` — a data-URI module fails `addModule`
+ * with the opaque "Unable to load a worklet's module". Every inline worklet
+ * in this package must load through this helper so that constraint lives in
+ * one place.
+ */
+export declare function workletModuleUrl(source: string): string;

package/dist/worklets/_playback-bench-harness.d.ts

@@ -0,0 +1,181 @@
+/**
+ * A bench for the playback jitter buffer: real TTS, the real worklet, a
+ * deterministic clock, and one setting changed at a time.
+ *
+ * Why this exists. `PLAYBACK_JITTER_MS` and `PLAYBACK_REFILL_MS` are the two
+ * numbers that decide whether a reply is heard as speech or as stutter, and
+ * every test that touches them supplies its own arrival pattern:
+ * `playback-processor.test.ts` hand-feeds quanta, and `audio-stress.test.ts`
+ * records in its own header that its chunk sizes outrun the render loop by an
+ * order of magnitude so the buffer "effectively never starves". Neither can
+ * answer "is 400 the right number", because neither has ever seen how audio
+ * actually arrives.
+ *
+ * So the bench replays a RECORDED reply (`_tts-trace-harness.ts`) through the
+ * chain the audio really crosses:
+ *
+ *   provider frames (recorded arrival times)
+ *     -> the server's bounded-lead pacer          <- MODELLED, see below
+ *     -> a network profile (latency, jitter, stalls)
+ *     -> the real playback worklet                <- `playbackProcessorSource`
+ *     -> rendered PCM + the worklet's own stats
+ *
+ * Everything is virtual-time: the clock advances one 128-sample render quantum
+ * per iteration, so a sweep of a hundred settings over a 30-second reply costs
+ * seconds and gives byte-identical results every run. {@link renderToWav} is
+ * the other half — the rendered output written where a human can listen to it,
+ * because a concealment counter does not tell you whether a reply sounds
+ * broken.
+ *
+ * **The pacer is a MODEL, and that is this bench's one fidelity gap.**
+ * `createAudioPacer` (`aai/host/audio-pacer.ts`) is not on any published
+ * subpath and this package may not import a sibling's internals, so
+ * {@link pacedSends} is a transcription of its algorithm rather than the
+ * algorithm. It is ~20 lines and reproduces the two properties the pacer's own
+ * doc states — free flow until the lead ceiling, then one release per
+ * `burstMs` — but a change to the real pacer will NOT fail this file. If the
+ * pacer moves, re-read it against `pacedSends`. Exporting the real one and
+ * deleting the model is the fix; it needs a non-test change.
+ */
+import { type TtsTrace } from "./_tts-trace-harness.ts";
+/** The render quantum every AudioWorkletProcessor is called with. */
+export declare const QUANTUM = 128;
+/** Sampling interval of {@link RenderResult.earMs}. */
+export declare const EAR_SAMPLE_MS = 20;
+/** One frame arriving at the client: when it lands, and what it carries. */
+export type Delivery = {
+    atMs: number;
+    bytes: Uint8Array;
+};
+/**
+ * How the server releases audio. Production values are
+ * `CLIENT_AUDIO_LEAD_MS` (1000) and `PACER_BURST_MS` (200); they are
+ * parameters here because they are half of what the bench is sweeping — the
+ * client's cushion is the server's lead, so tuning the jitter buffer without
+ * them is tuning one end of one number.
+ */
+export type PacerProfile = {
+    leadMs: number;
+    burstMs: number;
+};
+/** What the link does to a frame between the server and the ear. */
+export type NetworkProfile = {
+    name: string;
+    /** One-way latency floor, ms. */
+    latencyMs: number;
+    /** Peak extra delay added on top, ms (0 = a perfectly even link). */
+    jitterMs: number;
+    /**
+     * Freezes: `{ atMs, forMs }` pairs during which nothing is delivered, every
+     * held frame landing at the end. This is what a jitter buffer is FOR, and
+     * the only part of a profile that has to be scripted rather than sampled —
+     * a stall is an event, not a distribution.
+     */
+    stalls?: {
+        atMs: number;
+        forMs: number;
+    }[];
+    /**
+     * Throughput ceiling in bits/s, or `Infinity`. Both legs are uncompressed
+     * PCM16 (384 kbps down at 24 kHz), so a link that cannot carry the bitrate
+     * cannot be fixed by any buffer — that claim is in `src/worklets/CLAUDE.md` and this
+     * is what makes it measurable.
+     */
+    bitsPerSecond?: number;
+};
+/**
+ * The worklet's one knob. It was two — a startup target and a refill target —
+ * until this bench showed the startup one was redundant by construction; see
+ * `PLAYBACK_FILL_MS`.
+ */
+export type PlaybackSettings = {
+    fillMs: number;
+};
+/**
+ * Model the server's bounded-lead pacer over a trace's frames.
+ *
+ * A transcription of `createAudioPacer`, whose loop is: a frame is sent
+ * immediately while the lead (everything sent so far, minus now) is under the
+ * ceiling; otherwise it waits until the lead has drained `burstMs` below the
+ * ceiling and then goes out with everything else the drain releases.
+ */
+export declare function pacedSends(trace: TtsTrace, pacer: PacerProfile): Delivery[];
+/** Apply a network profile to the server's send schedule. */
+export declare function overNetwork(sends: Delivery[], net: NetworkProfile): Delivery[];
+/** Everything one render of one setting produced. */
+export type RenderResult = {
+    /** The audio the ear actually received, at the context sample rate. */
+    rendered: Float32Array;
+    sampleRate: number;
+    /** Ms from the first frame LEAVING the provider to the first audible sample. */
+    timeToFirstAudioMs: number;
+    /** The worklet's own report, as `onPlaybackStats` would receive it. */
+    stats: {
+        concealedSamples: number;
+        silentConcealedSamples: number;
+        concealmentEvents: number;
+        silentConcealmentEvents: number;
+    };
+    /** Every concealment episode's length in ms, in order. */
+    gapsMs: number[];
+    /** `bufferedMs` values the worklet reported, as `playback_progress` would. */
+    progressMs: number[];
+    /**
+     * Ground truth for the heard cursor: cumulative ms of the REPLY's own audio
+     * the ear had received, sampled every {@link EAR_SAMPLE_MS}.
+     *
+     * Concealed samples are excluded — they are fabricated, not reply audio — so
+     * this is exactly the quantity `heardMs()` in
+     * `aai/host/transports/pipeline-heard.ts` estimates, which is what makes the
+     * two comparable.
+     */
+    earMs: number[];
+    /** How long the reply took to play out, first sample to last. */
+    playedMs: number;
+};
+/**
+ * Render one delivery schedule through the real playback worklet.
+ *
+ * The clock is the render loop itself: quantum `q` happens at
+ * `q * QUANTUM / sampleRate` seconds, every delivery at or before that instant
+ * is written first, and `done` is posted once the last frame has landed. That
+ * is the ordering the audio thread really sees (`onmessage` and `process()`
+ * never interleave), and it makes the whole render a pure function of the
+ * schedule.
+ */
+export declare function renderSchedule(deliveries: Delivery[], opts: {
+    sampleRate: number;
+    settings: PlaybackSettings;
+    maxSeconds?: number;
+}): RenderResult;
+/** One end-to-end run: trace + pacer + network + settings. */
+export declare function runBench(opts: {
+    trace: TtsTrace;
+    pacer: PacerProfile;
+    net: NetworkProfile;
+    settings: PlaybackSettings;
+}): RenderResult;
+/**
+ * Score one render. Lower is better, and the WEIGHTS are the opinion in this
+ * file — everything above is measurement.
+ *
+ * The three terms are not interchangeable:
+ *
+ * - **Startup latency** is paid on every single turn, so it is the term that
+ *   compounds over a conversation.
+ * - **Silent concealment** is an audible hole. Concealment that stays under
+ *   the fade is a smear the ear largely forgives, which is why the worklet
+ *   reports the two separately, so silence is weighted an order of magnitude
+ *   higher than concealment in general.
+ * - **Episode COUNT** matters independently of total length: one 300 ms pause
+ *   reads as a network hiccup, where six 50 ms ones read as a broken codec.
+ *   That is the whole finding behind the refill re-arm, so a score that
+ *   summed milliseconds alone would rank the failure it was built to prevent
+ *   as equal to the fix.
+ */
+export declare function scoreRender(r: RenderResult): {
+    score: number;
+    parts: Record<string, number>;
+};
+/** Minimal 16-bit PCM WAV, so a render can be listened to. */
+export declare function toWav(samples: Float32Array, sampleRate: number): Buffer;

package/dist/worklets/_playback-bench-host.d.ts

@@ -0,0 +1,63 @@
+/**
+ * The bench's HOST-side half: what the server believes about the caller's
+ * playback, against what the caller actually heard.
+ *
+ * Split from `_playback-bench-harness.ts` at the seam it already had — that file
+ * models the wire and drives the worklet, and this one models
+ * `aai/host/transports/pipeline-heard.ts`'s arithmetic over the result. It went
+ * out when the file hit the 500-line cap, which is the right time rather than a
+ * line later.
+ *
+ * Everything here is a TRANSCRIPTION of host code this package may not import
+ * (`aai`'s `host/` is Node-only and internal), so it carries the same warning the
+ * pacer model does: a change to `createPlaybackClock` will not fail this file.
+ * Re-read it against these functions if that clock moves.
+ */
+import type { Delivery, RenderResult } from "./_playback-bench-harness.ts";
+/**
+ * What the HOST believes about playback, and what actually happened.
+ *
+ * The barge-in floor is `pending()` in `aai/host/transports/pipeline-heard.ts`:
+ * `now() < endsAtMs + PIPELINE_PLAYBACK_GRACE_MS`, where `endsAtMs` accumulates
+ * each forwarded chunk's duration from `max(endsAtMs, now())` — an OPEN-LOOP
+ * model that assumes playback starts the instant a chunk is forwarded and runs at
+ * exactly 1.0x. No real client beats that, so the model is a lower bound and the
+ * grace is what covers the difference.
+ *
+ * This measures the difference. `requiredGraceMs` is how long after the host's
+ * estimate the caller was still hearing audio — i.e. the smallest grace that
+ * keeps barge-in working to the end of a reply. It is a REQUIREMENT, so a grace
+ * at or above it is correct and one below it means a barge-in in the reply's tail
+ * is not recognised as arriving during playback.
+ *
+ * Two clients are modelled because the host serves both: one that wires
+ * `onPlaybackProgress` (the browser does) and one that does not (a telephony
+ * bridge, a harness). The reports clamp `endsAtMs` UPWARD only, so a reporting
+ * client shrinks the requirement and a silent one leaves the host on the
+ * open-loop estimate — which is the case the constant has to be safe for.
+ */
+export type PlayoutVsHost = {
+    /** When the host's open-loop model thinks forwarded audio finishes playing. */
+    openLoopEndMs: number;
+    /** The same, with the client's `playback_progress` reports clamped in. */
+    reportedEndMs: number;
+    /** When the caller actually stopped hearing audio. */
+    realEndMs: number;
+    /** Smallest grace that keeps `pending()` true to `realEndMs`, unreported. */
+    requiredGraceMs: number;
+    /** The same for a client that DOES report its backlog. */
+    requiredGraceReportingMs: number;
+};
+/**
+ * Replay a render against the host's own playback-clock arithmetic.
+ *
+ * `deliveries` is what the host FORWARDED (the pacer's output, before the link),
+ * because that is what `onChunk` sees — the host has no view of the wire.
+ */
+export declare function playoutVsHost(opts: {
+    forwarded: Delivery[];
+    render: RenderResult;
+    sampleRate: number;
+    /** Interval of the client's backlog reports; production is 500 ms. */
+    reportIntervalMs: number;
+}): PlayoutVsHost;

package/dist/worklets/_playback-bench-page.d.ts

@@ -0,0 +1,65 @@
+/**
+ * The browser half of the playback bench: a page that plays a recorded reply
+ * through the REAL playback worklet in a REAL `AudioContext`, so the tuning can
+ * be listened to rather than only counted.
+ *
+ * This is the part the offline renderer cannot be: `renderSchedule` drives
+ * `process()` on a synthetic sample clock with `postMessage` delivered exactly
+ * between quanta, which is the ordering the audio thread guarantees but says
+ * nothing about the browser's own render cadence, its output latency, or what
+ * a `port.postMessage` burst does to a live audio callback. If the two agree,
+ * the offline sweep is trustworthy; where they disagree, the browser is right.
+ *
+ * Two ways in, same page:
+ *
+ * - **A human opens it** and gets a slider for `fillMs`, the
+ *   network profile, and the pacer lead, with the worklet's own concealment
+ *   counters live. Audio comes out of the speakers.
+ * - **Playwright drives it** through {@link BENCH_API} on `window`, and pulls
+ *   back the samples the tap captured — the audio that actually reached the
+ *   destination — so a test can diff it against the offline render.
+ *
+ * The page is a STRING rather than a file under a bundler because it must stay
+ * test-only: aai-ui's build (`tsdown` + `build-default-client.ts`) ships
+ * `dist/default-client/`, and a second HTML entry there is a product artifact
+ * with a coverage floor and a size budget. Generated into `reports/playback/`,
+ * it is neither.
+ */
+/** The name of the object the page exposes for a driver to call. */
+export declare const BENCH_API = "__aaiPlaybackBench";
+/** Options a driver or a human can set on one run. */
+export type BenchRunOptions = {
+    fillMs: number;
+    /** Deliveries: ms since run start, and the slice of the PCM to write. */
+    schedule: {
+        atMs: number;
+        offset: number;
+        length: number;
+    }[];
+    /** Whether the reply is audible. A sweep run in a headless browser is not. */
+    muted?: boolean;
+};
+/**
+ * Build the bench page.
+ *
+ * `pcmUrl` is fetched once and sliced per delivery, so the page replays the
+ * same bytes the offline renderer does. `sampleRate` must be the trace's: the
+ * context is created at it and the page REFUSES to run if the browser grants
+ * another, exactly as `audio/voice-io.ts` does — PCM written into a context at the wrong
+ * rate plays at the wrong speed, which would look like a tuning result.
+ */
+export declare function benchPageHtml(opts: {
+    pcmUrl: string;
+    sampleRate: number;
+    /** Shown in the header, so a saved page names what it is playing. */
+    title: string;
+    /** Default schedules a human can pick between, by profile name. */
+    profiles: Record<string, {
+        atMs: number;
+        offset: number;
+        length: number;
+    }[]>;
+    defaults?: {
+        fillMs: number;
+    };
+}): string;

package/dist/worklets/_tts-trace-harness.d.ts

@@ -0,0 +1,142 @@
+/**
+ * Capture and replay of REAL TTS arrival timing.
+ *
+ * The playback worklet's tuning question — how deep should
+ * `PLAYBACK_JITTER_MS` be — is entirely a question about how unevenly audio
+ * arrives, and every existing test answers it with a generated arrival pattern.
+ * `audio-stress.test.ts` says so itself: its chunk-size arbitrary averages
+ * ~750 samples against 128 consumed per render, so writes outrun renders by an
+ * order of magnitude and the buffer effectively never starves. A jitter buffer
+ * tuned against that is tuned against nothing.
+ *
+ * So a trace is a recording of one real reply as the provider actually emitted
+ * it: PCM16 bytes plus the millisecond each frame ARRIVED, relative to the
+ * first. Replayed through the real pacer and the real worklet, that makes the
+ * tuning question measurable and repeatable — the same reply, the same
+ * arrival pattern, one setting changed.
+ *
+ * Two halves, deliberately separate:
+ *
+ * - {@link captureTtsTrace} needs a live provider and an API key. It runs once,
+ *   by hand (`AAI_CAPTURE_TTS_TRACE=1`), and commits its result.
+ * - {@link readTtsTrace} needs neither, so every test that CONSUMES a trace is
+ *   keyless and offline.
+ *
+ * The bytes live beside the JSON rather than inside it: base64 in a fixture
+ * inflates ~1 MB of PCM by a third and makes the file unreadable in a diff,
+ * where a `.pcm` sidecar is `ffplay`-able and reviewed by its length alone.
+ */
+/** One provider audio frame, with the moment it arrived. */
+export type TraceFrame = {
+    /** Arrival time in ms, relative to the first frame of the reply. */
+    tMs: number;
+    /** Byte offset of this frame's PCM16 in the sidecar. */
+    offset: number;
+    /** Byte length of this frame's PCM16. */
+    length: number;
+};
+/** A recorded reply: what the provider sent, and when. */
+export type TtsTrace = {
+    /** Sample rate of the PCM16 in the sidecar. */
+    sampleRate: number;
+    /** Provider kind and voice, so a trace names the thing it recorded. */
+    provider: string;
+    voice: string;
+    /** The reply text that was synthesized. */
+    text: string;
+    /** Ms from the first `sendText` to the first audio frame. */
+    firstAudioMs: number;
+    /** Ms from the first `sendText` to `done`. */
+    doneMs: number;
+    frames: TraceFrame[];
+    /** All frames' PCM16, concatenated in arrival order. */
+    pcm: Int16Array;
+};
+/**
+ * Total audio duration in ms. Not the same as {@link TtsTrace.doneMs}: a
+ * provider that synthesizes faster than real time produces more audio than the
+ * wall clock it took to produce it, and the RATIO of the two is the whole
+ * reason a jitter buffer can ever fill.
+ */
+export declare function traceAudioMs(trace: TtsTrace): number;
+/**
+ * The slice of the SDK's `TtsSession` a capture drives. Declared structurally
+ * so the harness needs no host-only type import: a real session satisfies it.
+ */
+export type CapturableTtsSession = {
+    sendText(text: string): void;
+    flush(): void;
+    on(event: "audio", fn: (pcm: Int16Array) => void): unknown;
+    on(event: "done", fn: () => void): unknown;
+    on(event: "error", fn: (err: {
+        message?: string;
+    }) => void): unknown;
+    close(): Promise<void>;
+};
+/**
+ * Open a real TTS session, synthesize `text`, and record every frame's arrival.
+ *
+ * The text is sent the way the PIPELINE sends it — as deltas, with a final
+ * `flush()` — because the AssemblyAI adapter segments on what it receives and
+ * `Generate` only buffers until a `Flush`. Handing it the whole reply in one
+ * call would record a different arrival pattern from the one a real turn
+ * produces (see `providers/tts/assemblyai-segment.ts`).
+ */
+export declare function captureTtsTrace(opts: {
+    text: string;
+    /**
+     * Opens the real provider session. INJECTED rather than resolved here: the
+     * resolver (`aai`'s `host/providers/resolve.ts`) is not on any published
+     * subpath, and this package may not import a sibling's internals. The caller
+     * that has one is the capture runner, which is not part of the package.
+     */
+    open: (o: {
+        sampleRate: number;
+        signal: AbortSignal;
+    }) => Promise<CapturableTtsSession>;
+    /** LLM-shaped deltas. Defaults to splitting `text` on word boundaries. */
+    deltas?: string[];
+    /** Recorded into the trace so a fixture names the voice it captured. */
+    voice?: string;
+    provider?: string;
+    sampleRate?: number;
+    /**
+     * Gap between deltas, in ms. **Set this to represent a real turn.**
+     *
+     * Sending every delta in one burst is what a capture does by default, and for
+     * the PLAYBACK question that is harmless — the pacer reshapes arrival anyway.
+     * For anything about SEGMENTATION it invalidates the measurement outright: the
+     * segmenter is handed the whole reply before it makes its first cut, so
+     * time-to-first-audio collapses to the service's own latency (~40 ms measured)
+     * and every segmentation rule scores the same. An LLM streams at ~30 ms a
+     * delta, which is what the segmenter really sees.
+     */
+    deltaIntervalMs?: number;
+    /** Hard cap, so a provider that never sends `done` cannot hang the capture. */
+    timeoutMs?: number;
+}): Promise<TtsTrace>;
+/**
+ * Split a reply into LLM-shaped deltas: a few words at a time, which is what
+ * `streamText` emits and therefore what the adapter's segmenter sees.
+ */
+export declare function splitIntoDeltas(text: string, wordsPer?: number): string[];
+/** Where a trace's two files live, given its directory and name. */
+export declare function tracePaths(dir: string, name: string): {
+    index: string;
+    pcm: string;
+};
+export declare function writeTtsTrace(dir: string, name: string, trace: TtsTrace): Promise<void>;
+/** Whether both halves of a trace are present, for a `skipIf` that announces. */
+export declare function hasTtsTrace(dir: string, name: string): boolean;
+export declare function readTtsTrace(dir: string, name: string): Promise<TtsTrace>;
+/**
+ * The same read, synchronously.
+ *
+ * A `describe` body may not `await` — vitest collects it synchronously — so a
+ * suite whose every case shares one trace has no other way to load it once.
+ * Reading it per `test` instead would decode 375 KiB of PCM ten times over for
+ * a value that is immutable.
+ */
+export declare function readTtsTraceSync(dir: string, name: string): TtsTrace;
+/** The PCM16 bytes of one frame, as the wire would carry them. */
+export declare function frameBytes(trace: TtsTrace, frame: TraceFrame): Uint8Array;

package/dist/worklets/_worklet-test-utils.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Test harness for AudioWorklet processor sources.
+ *
+ * The worklets ship as source strings (compiled to Blob URLs for the real
+ * AudioWorklet). This harness evaluates a source string with stubbed
+ * AudioWorkletGlobalScope globals so the processor's runtime behavior
+ * (batching, resampling, ring buffer) can be exercised directly in unit tests.
+ */
+export type WorkletPort = {
+    onmessage: ((e: {
+        data: unknown;
+    }) => void) | null;
+    postMessage(data: unknown, transfer?: unknown[]): void;
+};
+export type WorkletInstance = {
+    port: WorkletPort;
+    process(inputs: Float32Array[][], outputs: Float32Array[][]): boolean;
+};
+export type WorkletHarness = {
+    instance: WorkletInstance;
+    /** Messages the processor posted to the main thread, in order. */
+    posted: unknown[];
+    /** Deliver a message from the main thread to the processor. */
+    sendMessage(data: unknown): void;
+};
+/** Evaluate a worklet source string and instantiate its registered processor. */
+export declare function instantiateWorklet(source: string, processorOptions?: Record<string, unknown>, contextSampleRate?: number): WorkletHarness;

package/dist/worklets/capture-processor.d.ts

@@ -1,2 +1,4 @@
-declare const src: string;
-export default src;
+/** Raw worklet source — exported so tests can evaluate the processor directly. */
+export declare const captureProcessorSource = "\nclass CaptureProcessor extends AudioWorkletProcessor {\n  constructor(options) {\n    super();\n    this.recording = false;\n    const opts = options.processorOptions || {};\n    // The context runs at the STT rate, so this is both the input and the\n    // output rate \u2014 there is nothing to convert.\n    this.rate = opts.sampleRate || sampleRate;\n    // Int16 accumulation buffer: flushed to the main thread as one transferred\n    // ArrayBuffer once ~bufferSeconds of samples are batched. Sized 2x the\n    // flush target so a whole render quantum always fits before flushing.\n    this.targetSamples = Math.max(1, Math.round(this.rate * (opts.bufferSeconds || 0.1)));\n    this.pending = new Int16Array(this.targetSamples * 2);\n    this.pendingLen = 0;\n    // Dead-mic probe: samples left to inspect before concluding the device\n    // delivers nothing but digital silence. Only consumed while recording, so\n    // the cost disappears after the window (or after the first real sample).\n    this.probeSamplesLeft = Math.round(\n      (this.rate * (opts.silenceProbeMs ?? 1500)) / 1000,\n    );\n    this.port.onmessage = (e) => {\n      if (e.data.event === 'start') this.recording = true;\n      else if (e.data.event === 'stop') {\n        // Final flush so the tail of speech isn't dropped on close, then ack\n        // so the host knows the tail chunk (if any) has been posted and it is\n        // safe to tear the context down.\n        this.flush();\n        this.recording = false;\n        this.port.postMessage({ event: 'stopped' });\n      }\n    };\n  }\n\n  // Convert Float32 -> Int16 and append to the pending batch. Writes through\n  // an Int16Array directly (assignment truncates like DataView.setInt16).\n  accumulate(samples) {\n    let buf = this.pending;\n    if (this.pendingLen + samples.length > buf.length) {\n      // Defensive: only reachable if a render quantum outproduces the 1x\n      // headroom above the flush target (never with 128-sample quanta).\n      const grown = new Int16Array((this.pendingLen + samples.length) * 2);\n      grown.set(buf.subarray(0, this.pendingLen));\n      this.pending = grown;\n      buf = grown;\n    }\n    for (let i = 0; i < samples.length; i++) {\n      const s = Math.max(-1, Math.min(1, samples[i]));\n      buf[this.pendingLen++] = s < 0 ? s * 0x8000 : s * 0x7fff;\n    }\n  }\n\n  // Post the batched samples as one transferred ArrayBuffer and reset.\n  flush() {\n    if (this.pendingLen === 0) return;\n    const buffer = this.pending.buffer.slice(0, this.pendingLen * 2);\n    this.pendingLen = 0;\n    this.port.postMessage({ event: 'chunk', buffer }, [buffer]);\n  }\n\n  // Watch the first window of input for any nonzero sample. One is enough to\n  // prove the device is live \u2014 a real mic in a quiet room still carries a\n  // noise floor, so all-zeros means muted, wrong input, or no input at all.\n  probeForSilence(channel) {\n    for (let i = 0; i < channel.length; i++) {\n      if (channel[i] !== 0) {\n        this.probeSamplesLeft = 0;\n        return;\n      }\n    }\n    this.probeSamplesLeft -= channel.length;\n    if (this.probeSamplesLeft <= 0) {\n      this.port.postMessage({ event: 'silent' });\n    }\n  }\n\n  process(inputs) {\n    const input = inputs[0];\n    if (!input || !input[0] || !this.recording) return true;\n\n    if (this.probeSamplesLeft > 0) this.probeForSilence(input[0]);\n\n    this.accumulate(input[0]);\n    if (this.pendingLen >= this.targetSamples) this.flush();\n    return true;\n  }\n}\n\nregisterProcessor('capture-processor', CaptureProcessor);\n";
+declare const _default: string;
+export default _default;