@alexkroman1/aai-ui 5.14.0 → 6.2.0

package/dist/workflow-client.d.ts

@@ -0,0 +1,97 @@
+/**
+ * Browser client for the workflow HTTP API (`aai/host/workflow-api.ts`).
+ *
+ * This is the whole client half of a WORKFLOW APP: an agent whose front door is
+ * a form rather than a microphone (`workflowApp()`) starts runs
+ * here and watches them for the answer. It deliberately does NOT go through
+ * `SessionCore` — there is no socket, no audio graph, and no session to resume.
+ *
+ * **The requests themselves are the SDK's now**
+ * (`createWorkflowApiClient`, `@alexkroman1/aai/workflow-api`), and what is left
+ * here is the one thing that is genuinely a BROWSER's: the default base URL.
+ * Every route, every query, the 404-is-an-answer rule and the `wait` clamp were
+ * written three times over — here, in the studio's Workflows card, and in
+ * `aai workflow` — and the parts the copies disagreed on were exactly the ones a
+ * reader cannot check by eye. The SDK module's doc carries that argument; this
+ * file must not grow a second implementation of any of it.
+ *
+ * The one thing worth knowing before using it: **a run outlives the page.**
+ * Starting one resolves as soon as the run is created, so `runId` is the only
+ * handle that matters and it stays valid across a reload, a different device, or
+ * `curl` — which is what makes `useWorkflowRun` a watch rather than a
+ * subscription to something the page owns.
+ *
+ * The loop that keeps asking lives in `use-workflow-run.ts`, and the streaming
+ * fast path under it in `workflow-events.ts`.
+ */
+import type { WorkflowRunSnapshot } from "@alexkroman1/aai";
+import { type WorkflowApi } from "@alexkroman1/aai/workflow-api";
+/**
+ * A run's observable state.
+ *
+ * Aliased from the SDK rather than restated. `import type` is erased entirely,
+ * so a second definition of the fields and the five-member status union would
+ * buy nothing and cost the one thing that matters — nothing would assert the two
+ * agree, so a status added to the SDK would never reach the browser type.
+ *
+ * `WorkflowRun` keeps the shorter name because it is what a page's own code
+ * writes; nothing in a browser needs the word "snapshot" to know a read returns
+ * one.
+ *
+ * It is GENERIC on the run's output, and a page supplies it — see
+ * {@link useWorkflowRun}. It does NOT have to restate that type: a page can name
+ * its own workflow and derive the rest with `WorkflowOutputOf`, pulling no
+ * server graph into the bundle.
+ *
+ * @public
+ */
+export type WorkflowRun<R = unknown> = WorkflowRunSnapshot<R>;
+/**
+ * A workflow's own output type, and the shape `GET /workflows` lists — both
+ * re-exported so a page needs ONE import to type its runs and render its form.
+ */
+export type { WorkflowOutputOf, WorkflowSummary } from "@alexkroman1/aai";
+/**
+ * A run status nothing will change again.
+ *
+ * Re-exported from the SDK rather than defined here. A second implementation
+ * listing two of the three terminal statuses would leave a cancelled run polled
+ * forever by a page while the agent considered it finished — the kind of drift a
+ * status predicate beside the status union cannot have.
+ */
+export { isTerminal } from "@alexkroman1/aai";
+/**
+ * The call set {@link createWorkflowApi} returns.
+ *
+ * Re-exported from the SDK rather than declared here: it IS the SDK's client,
+ * and a structural restatement would be a second thing to keep in step with the
+ * routes for no gain.
+ */
+export type { WorkflowApi } from "@alexkroman1/aai/workflow-api";
+export type WorkflowApiOptions = {
+    /**
+     * Base URL of the agent. Defaults to the page's own origin + path, which is
+     * right for a page the agent itself serves — the only case that exists today,
+     * and the reason this wrapper exists at all: the SDK client requires a base
+     * URL, because `location` does not exist in that half of the SDK.
+     */
+    baseUrl?: string;
+    /**
+     * Bearer for an agent whose operator set `AAI_WORKFLOW_API_TOKEN`. A page
+     * served to the public has nothing to put here (and should not — it would be
+     * readable in the bundle); this exists for a programmatic caller written
+     * against the same client.
+     */
+    token?: string;
+};
+/**
+ * Create a workflow API client aimed at the agent serving this page.
+ *
+ * Hoist it out of the component that uses it. `useWorkflowRun` holds the client
+ * in a ref precisely so a fresh object per render does not restart its watch,
+ * but a client built in render is still a new `fetch` closure every time and
+ * reads as though it were free.
+ *
+ * @public
+ */
+export declare function createWorkflowApi(opts?: WorkflowApiOptions): WorkflowApi;

package/dist/workflow-events.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Watching a run over server-sent events — the PUSH half of `useWorkflowRun`.
+ *
+ * Its own module because the seam is clean: everything in `workflow-client.ts`
+ * is request/response shaping plus the poll, and this is one long-lived stream
+ * and the SSE parser it needs.
+ *
+ * @internal
+ */
+import type { WorkflowApi, WorkflowRun } from "./workflow-client.ts";
+/**
+ * The slice of the client this needs: one method.
+ *
+ * Narrowed rather than taking the whole `WorkflowApi`, and the narrowing is the
+ * honest statement — nothing here reads a run, starts one, or cancels one, it
+ * opens ONE stream. It also makes a test double a plain object rather than a
+ * six-method stub cast into shape. A real client satisfies it structurally.
+ */
+export type RunWatcher = Pick<WorkflowApi, "watch">;
+/**
+ * Watch a run over SSE, falling back to the caller's poll on any failure.
+ *
+ * The poll stays the fallback rather than being replaced, and that is the whole
+ * shape of this: a stream is an optimisation over a mechanism that already
+ * works, so every way it can fail — an older agent with no `/events` route, a
+ * proxy that buffers, a network that drops it — has to degrade to the thing that
+ * does. What it buys is real, though: on the platform every polled read BROKERS,
+ * so N open tabs at `DEFAULT_WORKFLOW_POLL_MS` is N/2 brokered requests a
+ * second, each able to boot a sandbox. One stream per tab replaces all of it.
+ *
+ * `EventSource` is not used, for two reasons that both matter here: it cannot
+ * send an `Authorization` header (an agent with `AAI_WORKFLOW_API_TOKEN` set
+ * would be unreachable), and it reconnects on its own schedule, which would
+ * fight the caller's. A `fetch` stream gives both back.
+ *
+ * Returns a stop function. `onFallback` is called at most once, when this stream
+ * cannot be relied on and the poll should take over.
+ */
+export declare function watchRunEvents<R>(getClient: () => RunWatcher, runId: string, onRun: (run: WorkflowRun<R>) => void, onSettled: () => void, onFallback: () => void): () => void;

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 the aai-ui guide 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.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;