@alexkroman1/aai-ui 6.1.0 → 6.3.0

package/dist/use-workflow-form.d.ts

@@ -33,6 +33,7 @@
  * followed from the same id either way.
  */
 import { type WorkflowSummary } from "@alexkroman1/aai";
+import type { UploadProgress } from "@alexkroman1/aai/workflow-api";
 import type { WorkflowApi, WorkflowRun } from "./workflow-client.ts";
 /** Options for {@link useWorkflows}. */
 export type UseWorkflowsOptions = {
@@ -71,6 +72,23 @@ export type UseWorkflowsResult = {
  * @public
  */
 export declare function useWorkflows(opts?: UseWorkflowsOptions): UseWorkflowsResult;
+/**
+ * What {@link WorkflowSubmission.upload} reports while the bytes are going.
+ *
+ * The SDK's per-request {@link UploadProgress} plus WHICH file it describes,
+ * because a form is allowed more than one and a bar over "the upload" would
+ * restart at zero partway through with nothing to say why.
+ *
+ * @public
+ */
+export type UploadStatus = UploadProgress & {
+    /** The file being sent, by the name the picker gave it. */
+    name: string;
+    /** Which file of the submission this is, counting from 1. */
+    index: number;
+    /** How many files this submission sends in total. */
+    count: number;
+};
 /** What {@link useWorkflowSubmit} returns. */
 export type WorkflowSubmission<R = unknown> = {
     /**
@@ -91,6 +109,19 @@ export type WorkflowSubmission<R = unknown> = {
      * already in flight.
      */
     pending: boolean;
+    /**
+     * How far the submission's files have got, while any are still going.
+     *
+     * Undefined before the first byte and again from the moment the last one
+     * lands, so a page can render `{upload && <UploadProgressBar upload={upload} />}`
+     * and the bar exists exactly for as long as there is an upload to describe. A
+     * form with no files never sets it at all.
+     *
+     * The wait it covers is the one `run` cannot: a run does not EXIST until its
+     * input is stored, so `pending` is true and there is nothing to poll — which
+     * for a 200 MB recording is minutes of a page that looks stuck.
+     */
+    upload: UploadStatus | undefined;
     /** The submit's own failure (a rejected input), or the watch's. */
     error: string | undefined;
 };

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;

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

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

package/dist/worklets/playback-processor.js

@@ -1,4 +1,4 @@
-import { PLAYBACK_BUFFER_SECONDS, PLAYBACK_CONCEAL_FADE_MS, PLAYBACK_CONCEAL_FLOOR, PLAYBACK_JITTER_MS, PLAYBACK_PROGRESS_INTERVAL_MS, PLAYBACK_REFILL_MS } from "../types.js";
+import { PLAYBACK_BUFFER_SECONDS, PLAYBACK_CONCEAL_FADE_MS, PLAYBACK_CONCEAL_FLOOR, PLAYBACK_FILL_MS, PLAYBACK_PROGRESS_INTERVAL_MS } from "../types.js";
 import { t as workletModuleUrl } from "../_module-url-C_4gRVL0.js";
 //#region worklets/playback-processor.ts
 const PlaybackProcessorWorklet = `
@@ -17,12 +17,10 @@ class PlaybackProcessor extends AudioWorkletProcessor {
     // could ever assert on the reported backlog, so the divergence made the
     // number untestable rather than wrong.
     this.rate = rate;
-    // Fill target for the start of a turn. If 'done' arrives first (short
-    // utterance), start immediately instead of waiting for audio that is
-    // never coming.
-    this.jitterSamples = Math.floor((rate * (opts.jitterMs ?? ${PLAYBACK_JITTER_MS})) / 1000);
-    // Fill target after an underrun — see PLAYBACK_REFILL_MS.
-    this.refillSamples = Math.floor((rate * (opts.refillMs ?? ${PLAYBACK_REFILL_MS})) / 1000);
+    // 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 ?? ${PLAYBACK_FILL_MS})) / 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.
@@ -79,7 +77,6 @@ class PlaybackProcessor extends AudioWorkletProcessor {
     // pre-roll (nothing to extrapolate from, and not a defect) from a
     // mid-turn underrun.
     this.hasPlayed = false;
-    this.fillTarget = this.jitterSamples;
     // Carry-over byte for split samples across chunks
     this.carry = null;
     this.writePos = 0;
@@ -271,7 +268,7 @@ class PlaybackProcessor extends AudioWorkletProcessor {
     // 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.fillTarget || this.isDone) {
+      if (avail >= this.fillSamples || this.isDone) {
         this.playing = true;
       } else {
         this.coverGap(out, 0);
@@ -280,13 +277,12 @@ class PlaybackProcessor extends AudioWorkletProcessor {
     }
 
     // Underrun: this quantum cannot be filled and more audio is still coming.
-    // Go back to filling (at the refill target) and cover the gap, leaving
+    // 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.fillTarget = this.refillSamples;
       this.coverGap(out, 0);
       return true;
     }