@alexkroman1/aai-ui 0.12.2 → 0.13.0

package/dist/worklets/capture-processor.js

@@ -1,57 +1,97 @@
-//#region worklets/capture-processor.ts
-const script = new Blob([`
+import { MIC_BUFFER_SECONDS, MIC_SILENCE_PROBE_MS } from "../types.js";
+import { t as workletModuleUrl } from "../_module-url-C13kAJ87.js";
+//#region src/worklets/capture-processor.ts
+/** Raw worklet source — exported so tests can evaluate the processor directly. */
+const captureProcessorSource = `
 class CaptureProcessor extends AudioWorkletProcessor {
   constructor(options) {
     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;
+    // 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 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 || ${MIC_BUFFER_SECONDS})));
+    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') this.recording = false;
+      else if (e.data.event === 'stop') {
+        // Final flush so the tail of speech isn't dropped on close, then ack
+        // so the host knows the tail chunk (if any) has been posted and it is
+        // safe to tear the context down.
+        this.flush();
+        this.recording = false;
+        this.port.postMessage({ event: 'stopped' });
+      }
     };
   }
 
-  resample(input) {
-    const ratio = this.ratio;
-    const outLen = Math.ceil(input.length / ratio);
-    const out = new Float32Array(outLen);
-    for (let i = 0; i < outLen; i++) {
-      const srcIdx = i * ratio;
-      const idx = srcIdx | 0;
-      const frac = srcIdx - idx;
-      const a = input[idx];
-      const b = idx + 1 < input.length ? input[idx + 1] : a;
-      out[i] = a + frac * (b - a);
+  // Convert Float32 -> Int16 and append to the pending batch. Writes through
+  // an Int16Array directly (assignment truncates like DataView.setInt16).
+  accumulate(samples) {
+    let buf = this.pending;
+    if (this.pendingLen + samples.length > buf.length) {
+      // Defensive: only reachable if a render quantum outproduces the 1x
+      // headroom above the flush target (never with 128-sample quanta).
+      const grown = new Int16Array((this.pendingLen + samples.length) * 2);
+      grown.set(buf.subarray(0, this.pendingLen));
+      this.pending = grown;
+      buf = grown;
+    }
+    for (let i = 0; i < samples.length; i++) {
+      const s = Math.max(-1, Math.min(1, samples[i]));
+      buf[this.pendingLen++] = s < 0 ? s * 0x8000 : s * 0x7fff;
+    }
+  }
+
+  // Post the batched samples as one transferred ArrayBuffer and reset.
+  flush() {
+    if (this.pendingLen === 0) return;
+    const buffer = this.pending.buffer.slice(0, this.pendingLen * 2);
+    this.pendingLen = 0;
+    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' });
     }
-    return out;
   }
 
   process(inputs) {
     const input = inputs[0];
     if (!input || !input[0] || !this.recording) return true;
 
-    const raw = input[0];
-    const samples = this.needsResample ? this.resample(raw) : raw;
+    if (this.probeSamplesLeft > 0) this.probeForSilence(input[0]);
 
-    // Convert Float32 -> Int16
-    const buffer = new ArrayBuffer(samples.length * 2);
-    const view = new DataView(buffer);
-    for (let i = 0; i < samples.length; i++) {
-      const s = Math.max(-1, Math.min(1, samples[i]));
-      view.setInt16(i * 2, s < 0 ? s * 0x8000 : s * 0x7fff, true);
-    }
-
-    this.port.postMessage({ event: 'chunk', buffer }, [buffer]);
+    this.accumulate(input[0]);
+    if (this.pendingLen >= this.targetSamples) this.flush();
     return true;
   }
 }
 
 registerProcessor('capture-processor', CaptureProcessor);
-`], { type: "application/javascript" });
-const src = URL.createObjectURL(script);
+`;
+var capture_processor_default = workletModuleUrl(captureProcessorSource);
 //#endregion
-export { src as default };
+export { captureProcessorSource, capture_processor_default as default };

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

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

package/package.json

@@ -1,59 +1,86 @@
 {
   "name": "@alexkroman1/aai-ui",
-  "version": "0.12.2",
+  "version": "0.13.0",
   "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/alexkroman/agent.git",
+    "directory": "packages/aai-ui"
+  },
+  "engines": {
+    "node": ">=24"
+  },
+  "sideEffects": [
+    "*.css",
+    "**/*.css"
+  ],
   "files": [
     "dist",
     "styles.css"
   ],
   "exports": {
     ".": {
-      "@dev/source": "./index.ts",
+      "@dev/source": "./src/index.ts",
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
     },
+    "./client-dir": {
+      "@dev/source": "./src/client-dir.ts",
+      "types": "./dist/client-dir.d.ts",
+      "import": "./dist/client-dir.js"
+    },
+    "./internal": {
+      "@dev/source": "./src/internal.ts",
+      "types": "./dist/internal.d.ts",
+      "import": "./dist/internal.js"
+    },
     "./styles.css": "./styles.css",
-    "./session": {
-      "@dev/source": "./session.ts",
-      "types": "./dist/session.d.ts",
-      "import": "./dist/session.js"
-    }
+    "./package.json": "./package.json"
   },
   "dependencies": {
     "clsx": "^2.1.1",
-    "@alexkroman1/aai": "0.12.2"
+    "partysocket": "^1.3.0",
+    "react-markdown": "^10.1.0",
+    "remark-gfm": "^4.0.1",
+    "use-stick-to-bottom": "^1.1.6",
+    "use-sync-external-store": "^1.7.0",
+    "xstate": "^5.33.2",
+    "@alexkroman1/aai": "0.13.0"
+  },
+  "devDependencies": {
+    "@tailwindcss/vite": "^4.3.3",
+    "@testing-library/dom": "^10.4.2",
+    "@testing-library/react": "^16.3.3",
+    "@types/react": "^19.3.0",
+    "@types/react-dom": "^19.3.0",
+    "@types/use-sync-external-store": "^1.7.0",
+    "@vitejs/plugin-react": "^6.1.1",
+    "fast-check": "^4.10.2",
+    "jsdom": "~30.0.1",
+    "react": "^19.3.0",
+    "react-dom": "^19.3.0",
+    "tsdown": "^0.22.14",
+    "vite": "^8.3.1",
+    "vitest": "^5.0.1"
   },
   "peerDependencies": {
-    "@preact/signals": "^2.8.2",
-    "preact": "^10.29.0",
-    "tailwindcss": "^4.2.1"
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "tailwindcss": "^4.0.0"
   },
   "peerDependenciesMeta": {
     "tailwindcss": {
       "optional": true
     }
   },
-  "devDependencies": {
-    "@preact/signals": "^2.8.2",
-    "@testing-library/preact": "^3.2.4",
-    "jsdom": "^29.0.1",
-    "preact": "^10.29.0",
-    "tsdown": "^0.21.5",
-    "vitest": "^4.1.1"
-  },
-  "engines": {
-    "node": ">=22.6"
-  },
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/alexkroman/agent.git",
-    "directory": "packages/aai-ui"
-  },
   "scripts": {
-    "build": "tsdown && tsc -p tsconfig.build.json",
-    "typecheck": "tsc --noEmit",
-    "lint": "biome check .",
+    "build": "tsdown && tsc -p tsconfig.build.json && node src/build-default-client.ts",
+    "check:attw": "attw --pack --profile esm-only --exclude-entrypoints styles.css",
     "check:publint": "publint",
-    "check:attw": "attw --pack --profile esm-only --entrypoints . ./session"
+    "lint": "biome check .",
+    "test": "vitest run",
+    "test:coverage": "vitest run --coverage",
+    "typecheck": "tsc --noEmit"
   }
 }