@alexkroman1/aai-ui 1.14.0 → 2.0.0

package/dist/define-client.d.ts

@@ -21,15 +21,6 @@ type BaseOptions = {
     resumeSessionId?: string;
     /** WebSocket constructor override. Passed through to session options. */
     WebSocket?: WebSocketConstructor;
-    /**
-     * Transport the UI talks over. Unset (the default) asks the server via
-     * `GET client-config`, so `agent({ transport })` decides — an agent that
-     * declared `transport: "sync"` gets the sync shell (HTTP turns, no
-     * WebSocket) with no custom client needed. An explicit value here skips
-     * the lookup. Only the config tier branches on it; a custom `component`
-     * owns its own transport.
-     */
-    transport?: "websocket" | "sync";
 };
 /**
  * Tier 1: Config-only options. Renders the default shell (StartScreen + ChatView).

package/dist/define-client.js

@@ -1,4 +1,4 @@
-import { t as client } from "./define-client-Dx4JaWzL.js";
+import { t as client } from "./define-client-yoGybEYR.js";
 import "./context.js";
 import "./components/sidebar-layout.js";
 import "./components/start-screen.js";

package/dist/index.d.ts

@@ -5,11 +5,10 @@ export { Controls } from "./components/controls.tsx";
 export { MessageList } from "./components/message-list.tsx";
 export { SidebarLayout } from "./components/sidebar-layout.tsx";
 export { StartScreen } from "./components/start-screen.tsx";
-export { SyncChatView } from "./components/sync-chat-view.tsx";
-export { TextControls } from "./components/text-controls.tsx";
 export type { ToolDisplayConfig } from "./components/tool-config-context.ts";
 export { ToolConfigContext } from "./components/tool-config-context.ts";
 export { ApiUrlChip, SessionUrlChips, UiUrlChip } from "./components/url-chips.tsx";
+export { WorkflowView } from "./components/workflow-view.tsx";
 export type { Session } from "./context.ts";
 export { SessionProvider, ThemeProvider, useSession, useSessionSelector, useTheme, } from "./context.ts";
 export type { ClientConfig, ClientHandle, } from "./define-client.tsx";
@@ -17,7 +16,7 @@ export { client } from "./define-client.tsx";
 export { useEvent, useToolCallStart, useToolResult } from "./hooks.ts";
 export type { CustomEvent, SessionCore, SessionCoreOptions, SessionSnapshot, } from "./session-core.ts";
 export { createSessionCore } from "./session-core.ts";
-export { CAPTURE_WORKLET_MODULE_URL, createPttRecorder, DEFAULT_SYNC_MIC_SAMPLE_RATE, floatToPcm16, type PttRecorder, type SyncMicrophone, type SyncMicrophoneOptions, startSyncMicrophone, } from "./sync-mic.ts";
+export { CAPTURE_WORKLET_MODULE_URL, createPttRecorder, DEFAULT_SYNC_MIC_SAMPLE_RATE, floatToPcm16, type PttRecorder, } from "./sync-mic.ts";
 export { base64ToPcm16, createSyncSession, pcm16ToBase64, type SyncSession, type SyncSessionOptions, type SyncTurnResult, } from "./sync-session.ts";
-export { createUtteranceDetector, type UtteranceDetector, type UtteranceDetectorOptions, } from "./sync-vad.ts";
 export type { AgentState, ChatMessage, ClientTheme, SessionError, SessionErrorCode, ToolCallInfo, VoiceSessionOptions, WebSocketConstructor, } from "./types.ts";
+export { VOICE_CAPTURE_CONSTRAINTS } from "./types.ts";

package/dist/index.js

@@ -1,12 +1,13 @@
-import { a as pcm16ToBase64, c as createPttRecorder, d as createUtteranceDetector, f as buildAgentUrl, i as createSyncSession, l as floatToPcm16, n as SyncChatView, o as CAPTURE_WORKLET_MODULE_URL, p as fetchClientConfig, r as base64ToPcm16, s as DEFAULT_SYNC_MIC_SAMPLE_RATE, t as client, u as startSyncMicrophone } from "./define-client-Dx4JaWzL.js";
+import { a as pcm16ToBase64, c as createPttRecorder, d as fetchClientConfig, i as createSyncSession, l as floatToPcm16, n as WorkflowView, o as CAPTURE_WORKLET_MODULE_URL, r as base64ToPcm16, s as DEFAULT_SYNC_MIC_SAMPLE_RATE, t as client, u as buildAgentUrl } from "./define-client-yoGybEYR.js";
 import { SessionProvider, ThemeProvider, useSession, useSessionSelector, useTheme } from "./context.js";
 import { Button } from "./components/button.js";
-import { i as UiUrlChip, n as ApiUrlChip, r as SessionUrlChips, t as Controls } from "./controls-BbZcmnJf.js";
+import { t as ChatView } from "./chat-view-DKFhxMAT.js";
+import { i as UiUrlChip, n as ApiUrlChip, r as SessionUrlChips, t as Controls } from "./controls-4OJoekj6.js";
 import { n as ToolConfigContext } from "./tool-call-block-DIxpG8GM.js";
 import { MessageList } from "./components/message-list.js";
-import { r as TextControls, t as ChatView } from "./chat-view-gi6FccZq.js";
 import { SidebarLayout } from "./components/sidebar-layout.js";
 import { StartScreen } from "./components/start-screen.js";
-import { t as createSessionCore } from "./session-core-B64kau_v.js";
+import { VOICE_CAPTURE_CONSTRAINTS } from "./types.js";
+import { t as createSessionCore } from "./session-core-BLhiQ18c.js";
 import { useEvent, useToolCallStart, useToolResult } from "./hooks.js";
-export { ApiUrlChip, Button, CAPTURE_WORKLET_MODULE_URL, ChatView, Controls, DEFAULT_SYNC_MIC_SAMPLE_RATE, MessageList, SessionProvider, SessionUrlChips, SidebarLayout, StartScreen, SyncChatView, TextControls, ThemeProvider, ToolConfigContext, UiUrlChip, base64ToPcm16, buildAgentUrl, client, createPttRecorder, createSessionCore, createSyncSession, createUtteranceDetector, fetchClientConfig, floatToPcm16, pcm16ToBase64, startSyncMicrophone, useEvent, useSession, useSessionSelector, useTheme, useToolCallStart, useToolResult };
+export { ApiUrlChip, Button, CAPTURE_WORKLET_MODULE_URL, ChatView, Controls, DEFAULT_SYNC_MIC_SAMPLE_RATE, MessageList, SessionProvider, SessionUrlChips, SidebarLayout, StartScreen, ThemeProvider, ToolConfigContext, UiUrlChip, VOICE_CAPTURE_CONSTRAINTS, WorkflowView, base64ToPcm16, buildAgentUrl, client, createPttRecorder, createSessionCore, createSyncSession, fetchClientConfig, floatToPcm16, pcm16ToBase64, useEvent, useSession, useSessionSelector, useTheme, useToolCallStart, useToolResult };

package/dist/{session-core-B64kau_v.js → session-core-BLhiQ18c.js}

@@ -74,6 +74,12 @@ async function initAudioCapture(conn, msg, deps, fatal) {
 					console.debug("[aai-ui] sendAudio dropped: connection closed");
 				}
 			},
+			onPlaybackStats: (stats) => {
+				console.warn("[aai-ui] playback concealed a gap in this turn", stats);
+			},
+			onMicSilent: () => {
+				console.warn("[aai-ui] microphone is delivering only silence — check the selected input device");
+			},
 			onError: (err) => {
 				if (conn.generation !== gen) return;
 				reportAudioFailure(err.message);

package/dist/session-core.js

@@ -1,2 +1,2 @@
-import { t as createSessionCore } from "./session-core-B64kau_v.js";
+import { t as createSessionCore } from "./session-core-BLhiQ18c.js";
 export { createSessionCore };

package/dist/sync-mic.d.ts

@@ -1,23 +1,39 @@
 /**
- * WebRTC microphone capture for sync mode.
+ * WebRTC push-to-talk capture for the workflow run surface.
  *
- * Captures voice through `getUserMedia` with the WebRTC voice-processing
- * constraints (echo cancellation, noise suppression, auto gain — the
- * processing that makes the energy VAD in `sync-vad.ts` reliable), runs an
- * AudioWorklet that batches raw frames to the main thread, feeds them
- * through the utterance detector, and hands each completed utterance to
- * the sync session as one HTTP turn. No WebSocket anywhere on the path.
+ * Captures voice through `getUserMedia` under
+ * {@link VOICE_CAPTURE_CONSTRAINTS} — echo cancellation only — and runs an
+ * AudioWorklet that batches raw frames to the main thread; the caller's
+ * button is the endpointing. Each recording becomes one `POST /sync` run.
+ * No WebSocket anywhere on the path.
  *
  * The worklet module ships inline as a blob URL (same pattern as the
- * WebSocket path's worklets), so sync mode needs no separately-served
+ * WebSocket path's worklets), so this path needs no separately-served
  * processor file. 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 "Unable to load a worklet's module".
  */
-import type { SyncSession } from "./sync-session.ts";
-import { type UtteranceDetectorOptions } from "./sync-vad.ts";
 /** Default capture rate — what the STT providers expect. */
 export declare const DEFAULT_SYNC_MIC_SAMPLE_RATE = 16000;
+/** ~128 ms at 16 kHz: few messages per second, fine-enough VAD granularity. */
+export declare const CAPTURE_BATCH_SAMPLES = 2048;
+/**
+ * The capture processor: coalesces 128-sample render quanta into
+ * {@link CAPTURE_BATCH_SAMPLES} batches and posts them (transferred, so no
+ * per-batch copy). Inlined as source because it must be stringified into a
+ * blob URL.
+ *
+ * `batch` is held as a field rather than re-read from the posted view:
+ * `postMessage` with a transfer list detaches the buffer, so `out.length` is
+ * 0 by the time the next buffer is allocated. Allocating a zero-length `buf`
+ * from it made `n` 0 forever, so `read` stopped advancing and the render
+ * thread spun inside `process()` posting empty chunks — the mic went
+ * permanently deaf on its first flush.
+ *
+ * Exported for the worklet unit tests (`sync-mic-worklet.test.ts`), which
+ * evaluate this source directly; it is not part of the package surface.
+ */
+export declare const CAPTURE_PROCESSOR_SRC = "\nregisterProcessor(\"aai-sync-capture\", class extends AudioWorkletProcessor {\n  constructor(options) {\n    super();\n    const batch = (options && options.processorOptions && options.processorOptions.batchSamples) || 2048;\n    this.batch = batch;\n    this.buf = new Float32Array(batch);\n    this.len = 0;\n  }\n  process(inputs) {\n    const ch = inputs[0] && inputs[0][0];\n    if (!ch) return true;\n    let read = 0;\n    while (read < ch.length) {\n      const n = Math.min(ch.length - read, this.buf.length - this.len);\n      this.buf.set(ch.subarray(read, read + n), this.len);\n      this.len += n;\n      read += n;\n      if (this.len === this.batch) {\n        const out = this.buf;\n        // Size the next buffer from this.batch, never from `out`: the\n        // transfer below detaches out.buffer, so out.length reads 0 here.\n        this.buf = new Float32Array(this.batch);\n        this.len = 0;\n        this.port.postMessage({ event: \"chunk\", samples: out }, [out.buffer]);\n      }\n    }\n    return true;\n  }\n});\n";
 /**
  * Blob-URL module for the capture processor (no served asset). Satisfies the
  * agent page's `script-src blob:` CSP, which rejects data-URI modules.
@@ -25,28 +41,6 @@ export declare const DEFAULT_SYNC_MIC_SAMPLE_RATE = 16000;
 export declare const CAPTURE_WORKLET_MODULE_URL: string;
 /** Clamp-and-convert one Float32 capture batch to PCM16. */
 export declare function floatToPcm16(samples: Float32Array): Int16Array;
-/** Configuration for {@link startSyncMicrophone}. */
-export type SyncMicrophoneOptions = {
-    /** The session each completed utterance is sent through. */
-    session: Pick<SyncSession, "sendPcm16">;
-    /** Capture/STT sample rate. Defaults to {@link DEFAULT_SYNC_MIC_SAMPLE_RATE}. */
-    sampleRate?: number | undefined;
-    /** VAD tuning overrides (see {@link UtteranceDetectorOptions}). */
-    vad?: Omit<UtteranceDetectorOptions, "sampleRate"> | undefined;
-    /** Speech onset confirmed — a turn will follow once the user pauses. */
-    onSpeechStart?: (() => void) | undefined;
-    /** An utterance was endpointed and its turn dispatched. */
-    onSpeechEnd?: (() => void) | undefined;
-    /** Capture or turn failure (the mic keeps running unless stopped). */
-    onError?: ((err: Error) => void) | undefined;
-};
-/** Live microphone handle returned by {@link startSyncMicrophone}. */
-export type SyncMicrophone = {
-    /** True while the detector is inside an utterance. */
-    readonly speaking: boolean;
-    /** Release the mic, the AudioContext, and flush a trailing utterance. */
-    stop(): Promise<void>;
-};
 /** Hold-to-record handle returned by {@link createPttRecorder}. */
 export type PttRecorder = {
     /** Open the mic (first call) and start collecting frames. */
@@ -57,18 +51,11 @@ export type PttRecorder = {
     close(): Promise<void>;
 };
 /**
- * Push-to-talk recorder on the same WebRTC capture pipeline as
- * {@link startSyncMicrophone} — `getUserMedia` voice processing feeding the
- * capture worklet — minus the VAD: the caller's button is the endpointing.
- * Recording runs exactly between `start()` and `stop()`; the mic stays open
- * across presses until `close()`.
+ * Push-to-talk recorder: `getUserMedia` voice capture feeding the capture
+ * worklet, with the caller's button as the endpointing. Recording runs
+ * exactly between `start()` and `stop()`; the mic stays open across presses
+ * until `close()`.
  *
  * @public
  */
 export declare function createPttRecorder(sampleRate?: number): PttRecorder;
-/**
- * Open the microphone and stream endpointed utterances into a sync session.
- *
- * @throws If microphone access is denied or worklet registration fails.
- */
-export declare function startSyncMicrophone(opts: SyncMicrophoneOptions): Promise<SyncMicrophone>;

package/dist/types.d.ts

@@ -1,5 +1,28 @@
 import type { SessionErrorCode } from "@alexkroman1/aai/protocol";
-export { FILE_SEND_BACKOFF_MS, MIC_BUFFER_SECONDS, MIC_SEND_MAX_BUFFERED_BYTES, } from "@alexkroman1/aai";
+export { FILE_SEND_BACKOFF_MS, MIC_BUFFER_SECONDS, MIC_SEND_MAX_BUFFERED_BYTES, MIC_SILENCE_PROBE_MS, PLAYBACK_CONCEAL_FADE_MS, PLAYBACK_CONCEAL_FLOOR, PLAYBACK_JITTER_MS, PLAYBACK_REFILL_MS, } from "@alexkroman1/aai";
+/**
+ * `getUserMedia` audio constraints for every capture path in this package.
+ *
+ * Defined once because four copies of this object drifted apart trivially, and
+ * the flags are not cosmetic — each one rewrites the signal before STT (and
+ * before the sync path's energy VAD) ever sees it:
+ *
+ * - **`autoGainControl: false`** — AGC continuously retargets level, which
+ *   means riding the noise floor up through silence. An energy VAD calibrated
+ *   against a moving floor is calibrated against nothing.
+ * - **`noiseSuppression: false`** / **`voiceIsolation: false`** — both discard
+ *   signal to make speech sound cleaner to a human, and both can gate a quiet
+ *   room to *exact* zeros, which is also what a dead microphone looks like
+ *   (see `MIC_SILENCE_PROBE_MS`).
+ * - **`echoCancellation: true`** — this one stays on. The mic is open while
+ *   the agent speaks (barge-in needs it), so without AEC the agent hears
+ *   itself and interrupts its own reply.
+ *
+ * Cast because `voiceIsolation` is newer than TypeScript's DOM lib.
+ *
+ * @public
+ */
+export declare const VOICE_CAPTURE_CONSTRAINTS: MediaTrackConstraints;
 /**
  * Current state of the voice agent session.
  *

package/dist/types.js

@@ -1,2 +1,32 @@
-import { FILE_SEND_BACKOFF_MS, MIC_BUFFER_SECONDS, MIC_SEND_MAX_BUFFERED_BYTES } from "@alexkroman1/aai";
-export { FILE_SEND_BACKOFF_MS, MIC_BUFFER_SECONDS, MIC_SEND_MAX_BUFFERED_BYTES };
+import { FILE_SEND_BACKOFF_MS, MIC_BUFFER_SECONDS, MIC_SEND_MAX_BUFFERED_BYTES, MIC_SILENCE_PROBE_MS, PLAYBACK_CONCEAL_FADE_MS, PLAYBACK_CONCEAL_FLOOR, PLAYBACK_JITTER_MS, PLAYBACK_REFILL_MS } from "@alexkroman1/aai";
+//#region types.ts
+/**
+* `getUserMedia` audio constraints for every capture path in this package.
+*
+* Defined once because four copies of this object drifted apart trivially, and
+* the flags are not cosmetic — each one rewrites the signal before STT (and
+* before the sync path's energy VAD) ever sees it:
+*
+* - **`autoGainControl: false`** — AGC continuously retargets level, which
+*   means riding the noise floor up through silence. An energy VAD calibrated
+*   against a moving floor is calibrated against nothing.
+* - **`noiseSuppression: false`** / **`voiceIsolation: false`** — both discard
+*   signal to make speech sound cleaner to a human, and both can gate a quiet
+*   room to *exact* zeros, which is also what a dead microphone looks like
+*   (see `MIC_SILENCE_PROBE_MS`).
+* - **`echoCancellation: true`** — this one stays on. The mic is open while
+*   the agent speaks (barge-in needs it), so without AEC the agent hears
+*   itself and interrupts its own reply.
+*
+* Cast because `voiceIsolation` is newer than TypeScript's DOM lib.
+*
+* @public
+*/
+const VOICE_CAPTURE_CONSTRAINTS = {
+	echoCancellation: true,
+	noiseSuppression: false,
+	autoGainControl: false,
+	voiceIsolation: false
+};
+//#endregion
+export { FILE_SEND_BACKOFF_MS, MIC_BUFFER_SECONDS, MIC_SEND_MAX_BUFFERED_BYTES, MIC_SILENCE_PROBE_MS, PLAYBACK_CONCEAL_FADE_MS, PLAYBACK_CONCEAL_FLOOR, PLAYBACK_JITTER_MS, PLAYBACK_REFILL_MS, VOICE_CAPTURE_CONSTRAINTS };

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

@@ -1,4 +1,4 @@
 /** 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    this.fromRate = opts.contextRate || sampleRate;\n    this.toRate = opts.sttSampleRate || sampleRate;\n    this.ratio = this.fromRate / this.toRate;\n    this.needsResample = this.fromRate !== this.toRate;\n    // Streaming-resampler state carried across process() blocks so the output\n    // clock doesn't drift and there's no discontinuity at 128-sample block\n    // boundaries. `prev` is the previous block's last input sample (used to\n    // interpolate across the boundary); `pos` is the fractional read position,\n    // in input samples, relative to an extended [prev, ...input] frame. Start\n    // at 1 so the first output is input[0] (not the bogus initial prev).\n    this.prev = 0;\n    this.pos = 1;\n    // Output buffer reused across process() calls -- the render quantum is a\n    // fixed size, so allocating per call would churn the realtime audio thread.\n    this.resampleBuf = null;\n    // Int16 accumulation buffer: flushed to the main thread as one transferred\n    // ArrayBuffer once ~bufferSeconds of output samples are batched. Sized 2x\n    // the flush target so a whole render quantum always fits before flushing.\n    this.targetSamples = Math.max(1, Math.round(this.toRate * (opts.bufferSeconds || 0.1)));\n    this.pending = new Int16Array(this.targetSamples * 2);\n    this.pendingLen = 0;\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  resample(input) {\n    const ratio = this.ratio;\n    const n = input.length;\n    if (n === 0) return new Float32Array(0);\n    // At most ceil(n / ratio) + 1 outputs per block (pos starts in [0, ratio)).\n    const maxLen = Math.ceil(n / ratio) + 1;\n    if (this.resampleBuf === null || this.resampleBuf.length < maxLen) {\n      this.resampleBuf = new Float32Array(maxLen);\n    }\n    const out = this.resampleBuf;\n    // Extended frame: index 0 = prev (previous block's last sample),\n    // index k>=1 = input[k-1]. Interpolate at fractional positions stepping by\n    // ratio, carrying `pos` across calls to preserve the sample clock.\n    let count = 0;\n    let pos = this.pos;\n    while (pos < n) {\n      const idx = pos | 0;\n      const frac = pos - idx;\n      const a = idx === 0 ? this.prev : input[idx - 1];\n      const b = input[idx];\n      out[count++] = a + frac * (b - a);\n      pos += ratio;\n    }\n    // Shift the origin to this block's last sample for the next call.\n    this.prev = input[n - 1];\n    this.pos = pos - n;\n    return out.subarray(0, count);\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  process(inputs) {\n    const input = inputs[0];\n    if (!input || !input[0] || !this.recording) return true;\n\n    const samples = this.needsResample ? this.resample(input[0]) : input[0];\n    this.accumulate(samples);\n    if (this.pendingLen >= this.targetSamples) this.flush();\n    return true;\n  }\n}\n\nregisterProcessor('capture-processor', CaptureProcessor);\n";
+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 src: string;
 export default src;

package/dist/worklets/capture-processor.js

@@ -1,3 +1,4 @@
+import { MIC_SILENCE_PROBE_MS } from "../types.js";
 //#region worklets/capture-processor.ts
 const CaptureProcessorWorklet = `
 class CaptureProcessor extends AudioWorkletProcessor {
@@ -5,27 +6,21 @@ class CaptureProcessor extends AudioWorkletProcessor {
     super();
     this.recording = false;
     const opts = options.processorOptions || {};
-    this.fromRate = opts.contextRate || sampleRate;
-    this.toRate = opts.sttSampleRate || sampleRate;
-    this.ratio = this.fromRate / this.toRate;
-    this.needsResample = this.fromRate !== this.toRate;
-    // Streaming-resampler state carried across process() blocks so the output
-    // clock doesn't drift and there's no discontinuity at 128-sample block
-    // boundaries. \`prev\` is the previous block's last input sample (used to
-    // interpolate across the boundary); \`pos\` is the fractional read position,
-    // in input samples, relative to an extended [prev, ...input] frame. Start
-    // at 1 so the first output is input[0] (not the bogus initial prev).
-    this.prev = 0;
-    this.pos = 1;
-    // Output buffer reused across process() calls -- the render quantum is a
-    // fixed size, so allocating per call would churn the realtime audio thread.
-    this.resampleBuf = null;
+    // The context runs at the STT rate, so this is both the input and the
+    // output rate — there is nothing to convert.
+    this.rate = opts.sampleRate || sampleRate;
     // Int16 accumulation buffer: flushed to the main thread as one transferred
-    // ArrayBuffer once ~bufferSeconds of output samples are batched. Sized 2x
-    // the flush target so a whole render quantum always fits before flushing.
-    this.targetSamples = Math.max(1, Math.round(this.toRate * (opts.bufferSeconds || 0.1)));
+    // ArrayBuffer once ~bufferSeconds of samples are batched. Sized 2x the
+    // flush target so a whole render quantum always fits before flushing.
+    this.targetSamples = Math.max(1, Math.round(this.rate * (opts.bufferSeconds || 0.1)));
     this.pending = new Int16Array(this.targetSamples * 2);
     this.pendingLen = 0;
+    // Dead-mic probe: samples left to inspect before concluding the device
+    // delivers nothing but digital silence. Only consumed while recording, so
+    // the cost disappears after the window (or after the first real sample).
+    this.probeSamplesLeft = Math.round(
+      (this.rate * (opts.silenceProbeMs ?? ${MIC_SILENCE_PROBE_MS})) / 1000,
+    );
     this.port.onmessage = (e) => {
       if (e.data.event === 'start') this.recording = true;
       else if (e.data.event === 'stop') {
@@ -39,35 +34,6 @@ class CaptureProcessor extends AudioWorkletProcessor {
     };
   }
 
-  resample(input) {
-    const ratio = this.ratio;
-    const n = input.length;
-    if (n === 0) return new Float32Array(0);
-    // At most ceil(n / ratio) + 1 outputs per block (pos starts in [0, ratio)).
-    const maxLen = Math.ceil(n / ratio) + 1;
-    if (this.resampleBuf === null || this.resampleBuf.length < maxLen) {
-      this.resampleBuf = new Float32Array(maxLen);
-    }
-    const out = this.resampleBuf;
-    // Extended frame: index 0 = prev (previous block's last sample),
-    // index k>=1 = input[k-1]. Interpolate at fractional positions stepping by
-    // ratio, carrying \`pos\` across calls to preserve the sample clock.
-    let count = 0;
-    let pos = this.pos;
-    while (pos < n) {
-      const idx = pos | 0;
-      const frac = pos - idx;
-      const a = idx === 0 ? this.prev : input[idx - 1];
-      const b = input[idx];
-      out[count++] = a + frac * (b - a);
-      pos += ratio;
-    }
-    // Shift the origin to this block's last sample for the next call.
-    this.prev = input[n - 1];
-    this.pos = pos - n;
-    return out.subarray(0, count);
-  }
-
   // Convert Float32 -> Int16 and append to the pending batch. Writes through
   // an Int16Array directly (assignment truncates like DataView.setInt16).
   accumulate(samples) {
@@ -94,12 +60,29 @@ class CaptureProcessor extends AudioWorkletProcessor {
     this.port.postMessage({ event: 'chunk', buffer }, [buffer]);
   }
 
+  // Watch the first window of input for any nonzero sample. One is enough to
+  // prove the device is live — a real mic in a quiet room still carries a
+  // noise floor, so all-zeros means muted, wrong input, or no input at all.
+  probeForSilence(channel) {
+    for (let i = 0; i < channel.length; i++) {
+      if (channel[i] !== 0) {
+        this.probeSamplesLeft = 0;
+        return;
+      }
+    }
+    this.probeSamplesLeft -= channel.length;
+    if (this.probeSamplesLeft <= 0) {
+      this.port.postMessage({ event: 'silent' });
+    }
+  }
+
   process(inputs) {
     const input = inputs[0];
     if (!input || !input[0] || !this.recording) return true;
 
-    const samples = this.needsResample ? this.resample(input[0]) : input[0];
-    this.accumulate(samples);
+    if (this.probeSamplesLeft > 0) this.probeForSilence(input[0]);
+
+    this.accumulate(input[0]);
     if (this.pendingLen >= this.targetSamples) this.flush();
     return true;
   }

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 rate = options.processorOptions?.sampleRate ?? 24000;\n    // Wait for ~400ms of audio before starting.\n    // If 'done' arrives first (short utterance), start immediately.\n    this.jitterSamples = Math.floor(rate * 0.4);\n    // Float32 ring buffer \u2014 60s at the context sample rate. Allocated once for\n    // the node's lifetime; per-turn state resets via resetTurn(). writePos and\n    // readPos are absolute (monotonic) sample counts; the buffer is indexed\n    // modulo capacity so a reply longer than 60s keeps playing instead of\n    // writing past the end and going silent.\n    this.capacity = rate * 60;\n    this.samples = new Float32Array(this.capacity);\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        this.interrupted = true;\n      } else if (d.event === 'done') {\n        this.isDone = true;\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.interrupted = false;\n    this.isDone = false;\n    this.playing = false;\n    // Carry-over byte for split samples across chunks\n    this.carry = null;\n    this.writePos = 0;\n    this.readPos = 0;\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: interrupt-stops are dropped host-side (flush() already\n  // settled that turn), so they can never resolve a later turn's done() early.\n  stopTurn(reason) {\n    this.port.postMessage({ event: 'stop', reason });\n    this.resetTurn();\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    if (this.interrupted) {\n      out.fill(0);\n      this.stopTurn('interrupt');\n      return true;\n    }\n\n    const avail = this.writePos - this.readPos;\n\n    // Wait for jitter buffer to fill, unless done (short utterance)\n    if (!this.playing) {\n      if (avail >= this.jitterSamples || this.isDone) {\n        this.playing = true;\n      } else {\n        out.fill(0);\n        return true;\n      }\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      out.fill(0, n);\n      return true;\n    }\n\n    // No data: output silence, end the turn only when done\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    const rate = opts.sampleRate ?? 24000;\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 60s at the context sample rate. Allocated once for\n    // the node's lifetime; per-turn state resets via resetTurn(). writePos and\n    // readPos are absolute (monotonic) sample counts; the buffer is indexed\n    // modulo capacity so a reply longer than 60s keeps playing instead of\n    // writing past the end and going silent.\n    this.capacity = rate * 60;\n    this.samples = new Float32Array(this.capacity);\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        this.interrupted = true;\n      } else if (d.event === 'done') {\n        this.isDone = true;\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.interrupted = false;\n    this.isDone = false;\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: interrupt-stops are dropped host-side (flush() already\n  // settled that turn), so they can never resolve a later turn's done() early.\n  stopTurn(reason) {\n    this.port.postMessage({ event: 'stop', reason, 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    if (len === 0) {\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    for (let i = n - take; i < n; i++) {\n      this.concealBuf[this.concealWrite] = out[i];\n      this.concealWrite = this.concealWrite + 1 === cap ? 0 : this.concealWrite + 1;\n    }\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    if (this.interrupted) {\n      out.fill(0);\n      this.stopTurn('interrupt');\n      return true;\n    }\n\n    const avail = this.writePos - this.readPos;\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";
 declare const src: string;
 export default src;

package/dist/worklets/playback-processor.js

@@ -1,12 +1,23 @@
+import { PLAYBACK_CONCEAL_FADE_MS, PLAYBACK_CONCEAL_FLOOR, PLAYBACK_JITTER_MS, PLAYBACK_REFILL_MS } from "../types.js";
 //#region worklets/playback-processor.ts
 const PlaybackProcessorWorklet = `
 class PlaybackProcessor extends AudioWorkletProcessor {
   constructor(options) {
     super();
-    const rate = options.processorOptions?.sampleRate ?? 24000;
-    // Wait for ~400ms of audio before starting.
-    // If 'done' arrives first (short utterance), start immediately.
-    this.jitterSamples = Math.floor(rate * 0.4);
+    const opts = options.processorOptions || {};
+    const rate = opts.sampleRate ?? 24000;
+    // 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);
+    // Concealment source: a ring of the most recently played samples, looped
+    // under a decaying gain to cover a gap. Sized to the fade window, with a
+    // per-sample decay that reaches the floor exactly at its end.
+    this.concealCapacity = Math.max(1, Math.floor((rate * ${PLAYBACK_CONCEAL_FADE_MS}) / 1000));
+    this.concealBuf = new Float32Array(this.concealCapacity);
+    this.concealDecay = Math.exp(Math.log(${PLAYBACK_CONCEAL_FLOOR}) / this.concealCapacity);
     // Float32 ring buffer — 60s at the context sample rate. Allocated once for
     // the node's lifetime; per-turn state resets via resetTurn(). writePos and
     // readPos are absolute (monotonic) sample counts; the buffer is indexed
@@ -38,10 +49,31 @@ class PlaybackProcessor extends AudioWorkletProcessor {
     this.interrupted = false;
     this.isDone = false;
     this.playing = false;
+    // Whether any real audio has been rendered this turn. Separates a turn's
+    // pre-roll (nothing to extrapolate from, and not a defect) from a
+    // mid-turn underrun.
+    this.hasPlayed = false;
+    this.fillTarget = this.jitterSamples;
     // Carry-over byte for split samples across chunks
     this.carry = null;
     this.writePos = 0;
     this.readPos = 0;
+    // Concealment ring state and the current fade position.
+    this.concealLen = 0;
+    this.concealWrite = 0;
+    this.concealPos = 0;
+    this.concealGain = 1;
+    // Episode flags, so a multi-quantum gap counts as one event.
+    this.concealing = false;
+    this.concealedSilence = false;
+    // Reported to the host on 'stop'. A fresh object per turn: the one just
+    // posted must not be mutated by the next turn.
+    this.stats = {
+      concealedSamples: 0,
+      silentConcealedSamples: 0,
+      concealmentEvents: 0,
+      silentConcealmentEvents: 0,
+    };
   }
 
   // End the current turn: notify the host and rearm for the next reply.
@@ -51,10 +83,76 @@ class PlaybackProcessor extends AudioWorkletProcessor {
   // stop belongs to: interrupt-stops are dropped host-side (flush() already
   // settled that turn), so they can never resolve a later turn's done() early.
   stopTurn(reason) {
-    this.port.postMessage({ event: 'stop', reason });
+    this.port.postMessage({ event: 'stop', reason, stats: this.stats });
     this.resetTurn();
   }
 
+  // Cover a quantum (from \`start\`) where real audio should have been.
+  //
+  // Before the turn's first samples there is nothing to extrapolate from, so
+  // the gap is plain silence and counted as nothing — WebRTC likewise only
+  // counts concealment once playout has begun. After that, loop the retained
+  // tail under a decaying gain: a hard zero-fill is a discontinuity mid-word,
+  // which is the click that makes a brief stall sound like breakage.
+  coverGap(out, start) {
+    if (!this.hasPlayed) {
+      out.fill(0, start);
+      return;
+    }
+    if (!this.concealing) {
+      this.concealing = true;
+      this.concealedSilence = false;
+      this.stats.concealmentEvents++;
+    }
+    const total = out.length - start;
+    const len = this.concealLen;
+    let silent = 0;
+    if (len === 0) {
+      out.fill(0, start);
+      silent = total;
+    } else {
+      let g = this.concealGain;
+      for (let i = start; i < out.length; i++) {
+        if (g < ${PLAYBACK_CONCEAL_FLOOR}) {
+          // The fade has run out: keep counting the gap, but stop looping a
+          // fragment that is now inaudible anyway.
+          out[i] = 0;
+          silent++;
+          continue;
+        }
+        out[i] = this.concealBuf[this.concealPos] * g;
+        this.concealPos = this.concealPos + 1 === len ? 0 : this.concealPos + 1;
+        g *= this.concealDecay;
+      }
+      this.concealGain = g;
+    }
+    this.stats.concealedSamples += total;
+    if (silent > 0) {
+      this.stats.silentConcealedSamples += silent;
+      if (!this.concealedSilence) {
+        this.concealedSilence = true;
+        this.stats.silentConcealmentEvents++;
+      }
+    }
+  }
+
+  // Retain the tail of a rendered quantum as the next gap's concealment
+  // source, and close any episode the real audio just ended.
+  rememberTail(out, n) {
+    const cap = this.concealCapacity;
+    const take = Math.min(n, cap);
+    for (let i = n - take; i < n; i++) {
+      this.concealBuf[this.concealWrite] = out[i];
+      this.concealWrite = this.concealWrite + 1 === cap ? 0 : this.concealWrite + 1;
+    }
+    this.concealLen = Math.min(cap, this.concealLen + take);
+    // Read the loop oldest-first; once the ring is full the write cursor is
+    // the oldest retained sample.
+    this.concealPos = this.concealLen === cap ? this.concealWrite : 0;
+    this.concealing = false;
+    this.concealGain = 1;
+  }
+
   ingestBytes(uint8) {
     let bytes = uint8;
 
@@ -122,16 +220,29 @@ class PlaybackProcessor extends AudioWorkletProcessor {
 
     const avail = this.writePos - this.readPos;
 
-    // Wait for jitter buffer to fill, unless done (short utterance)
+    // 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.jitterSamples || this.isDone) {
+      if (avail >= this.fillTarget || this.isDone) {
         this.playing = true;
       } else {
-        out.fill(0);
+        this.coverGap(out, 0);
         return true;
       }
     }
 
+    // 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
+    // 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;
+    }
+
     if (avail > 0) {
       const n = Math.min(avail, out.length);
       // Copy from the ring buffer, splitting across the wrap boundary.
@@ -140,11 +251,16 @@ class PlaybackProcessor extends AudioWorkletProcessor {
       out.set(this.samples.subarray(start, start + first), 0);
       if (n > first) out.set(this.samples.subarray(0, n - first), first);
       this.readPos += n;
+      // Only reachable with n < out.length on the turn's final partial
+      // quantum (the underrun branch above catches every other case).
       out.fill(0, n);
+      this.hasPlayed = true;
+      this.rememberTail(out, n);
       return true;
     }
 
-    // No data: output silence, end the turn only when done
+    // Drained and done: end the turn. Not reachable mid-turn — an empty
+    // buffer with audio still coming is the underrun branch above.
     out.fill(0);
     if (this.isDone) {
       this.stopTurn('done');