@bendyline/squisq 1.5.2 → 2.0.1

package/src/__tests__/narrationScript.test.ts

@@ -0,0 +1,149 @@
+import { describe, it, expect } from 'vitest';
+import { parseMarkdown } from '../markdown/parse';
+import { markdownToDoc } from '../doc/markdownToDoc';
+import {
+  buildNarrationScript,
+  expectedSyllablesAt,
+  wordPosAtExpectedSyllables,
+  wordIndexAtChar,
+  wordIndexAtTime,
+} from '../narration/script';
+import type { WordTiming } from '../narration/types';
+
+const MD = `# Morning Routine
+
+Every day starts the same way. Coffee first, then a walk.
+
+The second paragraph has more words in it, honestly.
+
+## The Walk
+
+We head down to the river and watch the boats go by.
+`;
+
+function build() {
+  return buildNarrationScript(markdownToDoc(parseMarkdown(MD)));
+}
+
+describe('buildNarrationScript', () => {
+  it('charOffsets index sourceText exactly', () => {
+    const script = build();
+    expect(script.tokens.length).toBeGreaterThan(10);
+    for (const token of script.tokens) {
+      expect(script.sourceText.slice(token.charOffset, token.charEnd)).toBe(token.text);
+    }
+  });
+
+  it('block ranges cover all tokens contiguously', () => {
+    const script = build();
+    expect(script.blocks.length).toBeGreaterThanOrEqual(2);
+    let cursor = 0;
+    for (let b = 0; b < script.blocks.length; b++) {
+      const range = script.blocks[b];
+      expect(range.tokenStart).toBe(cursor);
+      expect(range.tokenEnd).toBeGreaterThan(range.tokenStart);
+      for (let i = range.tokenStart; i < range.tokenEnd; i++) {
+        expect(script.tokens[i].blockIndex).toBe(b);
+        expect(script.tokens[i].blockId).toBe(range.blockId);
+      }
+      cursor = range.tokenEnd;
+    }
+    expect(cursor).toBe(script.tokens.length);
+  });
+
+  it('assigns pause classes: sentence, paragraph, block boundary', () => {
+    const script = build();
+    const tokenByText = (text: string) => script.tokens.find((t) => t.text === text)!;
+
+    // "way." ends a sentence mid-paragraph → 1
+    expect(tokenByText('way.').pauseAfter).toBe(1);
+    // "walk." ends the paragraph (blank line follows within the block) → 2
+    expect(tokenByText('walk.').pauseAfter).toBe(2);
+    // Last token of each block → 3
+    for (const range of script.blocks) {
+      expect(script.tokens[range.tokenEnd - 1].pauseAfter).toBe(3);
+    }
+    // Plain word mid-sentence → 0
+    expect(tokenByText('starts').pauseAfter).toBe(0);
+  });
+
+  it('includes headings as spoken text and honors includeTitles=false', () => {
+    const doc = markdownToDoc(parseMarkdown(MD));
+    const withTitles = buildNarrationScript(doc);
+    const withoutTitles = buildNarrationScript(doc, { includeTitles: false });
+    expect(withTitles.sourceText).toContain('Morning Routine');
+    expect(withoutTitles.sourceText).not.toContain('Morning Routine');
+    expect(withoutTitles.tokens.length).toBeLessThan(withTitles.tokens.length);
+  });
+
+  it('is deterministic', () => {
+    const a = build();
+    const b = build();
+    expect(a).toEqual(b);
+  });
+
+  it('marks standalone punctuation as non-spoken with zero syllables', () => {
+    const script = buildNarrationScript(
+      markdownToDoc(parseMarkdown('# Intro\n\nSquisq — short — turns plain Markdown into slides.')),
+    );
+    const dashes = script.tokens.filter((t) => t.text === '—');
+    expect(dashes.length).toBe(2);
+    for (const dash of dashes) {
+      expect(dash.spoken).toBe(false);
+      expect(dash.syllables).toBe(0);
+      expect(dash.spokenWordEquiv).toBe(0);
+    }
+    // Real words stay spoken; the em-dashes add nothing to the syllable total.
+    for (const word of script.tokens.filter((t) => /[a-z]/i.test(t.text))) {
+      expect(word.spoken).toBe(true);
+      expect(word.syllables).toBeGreaterThanOrEqual(1);
+    }
+    const spokenSyllables = script.tokens
+      .filter((t) => t.spoken)
+      .reduce((sum, t) => sum + t.syllables, 0);
+    expect(script.totalSyllables).toBe(spokenSyllables);
+  });
+
+  it('cumulative syllables are consistent prefix sums', () => {
+    const script = build();
+    expect(script.cumulativeSyllables.length).toBe(script.tokens.length + 1);
+    expect(script.cumulativeSyllables[0]).toBe(0);
+    for (let i = 0; i < script.tokens.length; i++) {
+      expect(script.cumulativeSyllables[i + 1] - script.cumulativeSyllables[i]).toBe(
+        script.tokens[i].syllables,
+      );
+    }
+    expect(script.totalSyllables).toBe(script.cumulativeSyllables[script.tokens.length]);
+  });
+});
+
+describe('script query helpers', () => {
+  it('expectedSyllablesAt interpolates and inverts', () => {
+    const script = build();
+    expect(expectedSyllablesAt(script, 0)).toBe(0);
+    expect(expectedSyllablesAt(script, script.tokens.length)).toBe(script.totalSyllables);
+    const mid = script.tokens.length / 2;
+    const syl = expectedSyllablesAt(script, mid);
+    expect(wordPosAtExpectedSyllables(script, syl)).toBeCloseTo(mid, 5);
+  });
+
+  it('wordIndexAtChar finds the containing token', () => {
+    const script = build();
+    for (const i of [0, 3, script.tokens.length - 1]) {
+      const token = script.tokens[i];
+      expect(wordIndexAtChar(script, token.charOffset)).toBe(i);
+      expect(wordIndexAtChar(script, token.charEnd - 1)).toBe(i);
+    }
+  });
+
+  it('wordIndexAtTime picks the last started word', () => {
+    const words: WordTiming[] = [
+      { tokenIndex: 0, tSec: 0.5, interpolated: false },
+      { tokenIndex: 1, tSec: 1.0, interpolated: false },
+      { tokenIndex: 2, tSec: 2.0, interpolated: false },
+    ];
+    expect(wordIndexAtTime(words, 0)).toBe(0);
+    expect(wordIndexAtTime(words, 1.2)).toBe(1);
+    expect(wordIndexAtTime(words, 5)).toBe(2);
+  });
+});

package/src/__tests__/narrationSessionRepro.test.ts

@@ -0,0 +1,62 @@
+import { describe, it, expect } from 'vitest';
+import { createNarrationSession, narrationSessionStep } from '../narration/session';
+import { createFeatureState, featureStep } from '../narration/features';
+import { scriptFromMarkdown } from './narrationTestSignals';
+
+/**
+ * Repro of the browser flow: 1024-sample worklet hops (exactly one
+ * frameSize) fed one at a time into a live session. Guards the carry /
+ * aliasing path that only this hop pattern exercises.
+ */
+describe('narration session with worklet-sized hops', () => {
+  it('featureStep reports real RMS for steady 1024-sample hops', () => {
+    let state = createFeatureState(48000);
+    let lastRms = -1;
+    for (let k = 0; k < 30; k++) {
+      const hop = new Float32Array(1024);
+      for (let i = 0; i < 1024; i++) {
+        hop[i] = 0.6 * Math.sin(((k * 1024 + i) * 2 * Math.PI * 700) / 48000);
+      }
+      const step = featureStep(state, hop);
+      state = step.state;
+      for (const frame of step.frames) lastRms = frame.rms;
+    }
+    expect(lastRms).toBeGreaterThan(0.3);
+  });
+
+  it('survives callers that recycle hop buffers after each step', () => {
+    // Chrome invalidates buffers transferred out of an AudioWorklet once
+    // the message handler returns. The carry must OWN its memory (slice,
+    // not subarray) or later frames silently read zeros.
+    let state = createFeatureState(48000);
+    let lastRms = -1;
+    for (let k = 0; k < 30; k++) {
+      const hop = new Float32Array(1024);
+      for (let i = 0; i < 1024; i++) {
+        hop[i] = 0.6 * Math.sin(((k * 1024 + i) * 2 * Math.PI * 700) / 48000);
+      }
+      const step = featureStep(state, hop);
+      state = step.state;
+      hop.fill(0); // simulate the buffer being recycled
+      for (const frame of step.frames) lastRms = frame.rms;
+    }
+    expect(lastRms).toBeGreaterThan(0.3);
+  });
+
+  it('narrationSessionStep exposes real lastFrame rms for the same hops', () => {
+    const script = scriptFromMarkdown('# One\n\nalpha beta gamma delta epsilon zeta eta theta.');
+    let session = createNarrationSession(48000, script, {
+      vad: { enterRatio: 3, exitRatio: 2.5 },
+      pacing: { baseWpm: 150 },
+    });
+    for (let k = 0; k < 30; k++) {
+      const hop = new Float32Array(1024);
+      for (let i = 0; i < 1024; i++) {
+        hop[i] = 0.6 * Math.sin(((k * 1024 + i) * 2 * Math.PI * 700) / 48000);
+      }
+      session = narrationSessionStep(session, hop);
+    }
+    expect(session.lastFrame).not.toBeNull();
+    expect(session.lastFrame!.rms).toBeGreaterThan(0.3);
+  });
+});

package/src/__tests__/narrationSidecar.test.ts

@@ -0,0 +1,88 @@
+import { describe, it, expect } from 'vitest';
+import { buildNarrationTimingJson, parseNarrationTimingJson } from '../narration/sidecar';
+import { alignNarration } from '../narration/align';
+import { scriptFromMarkdown, takeFromScript } from './narrationTestSignals';
+
+const script = scriptFromMarkdown('# One\n\nAlpha beta gamma.\n\n# Two\n\nDelta epsilon zeta.');
+
+/** The legacy v1 gate from audioMapping.parseTimingJson. */
+function passesLegacyGate(payload: unknown): boolean {
+  const p = payload as { sourceText?: unknown; duration?: unknown };
+  return typeof p.sourceText === 'string' && typeof p.duration === 'number';
+}
+
+describe('narration sidecar v3', () => {
+  const take = takeFromScript(script, 150, 48000, 31);
+  const alignment = alignNarration({ pcm: take.pcm, sampleRate: 48000, script });
+  const sidecar = buildNarrationTimingJson(script, alignment, take.durationSec, { baseWpm: 150 });
+
+  it('build → parse round-trips', () => {
+    const parsed = parseNarrationTimingJson(JSON.stringify(sidecar));
+    expect(parsed).not.toBeNull();
+    expect(parsed!.version).toBe(3);
+    expect(parsed!.sourceText).toBe(script.sourceText);
+    expect(parsed!.bookmarks.length).toBe(script.tokens.length);
+    expect(parsed!.blocks.length).toBe(script.blocks.length);
+    expect(parsed!.generator?.method).toBe('dsp-align');
+  });
+
+  it('fills bookmarks with real char offsets and monotonic times', () => {
+    for (let i = 0; i < sidecar.bookmarks.length; i++) {
+      const bookmark = sidecar.bookmarks[i];
+      expect(bookmark.charOffset).toBe(script.tokens[i].charOffset);
+      expect(bookmark.textFragment).toBe(script.tokens[i].text);
+      if (i > 0) expect(bookmark.time).toBeGreaterThanOrEqual(sidecar.bookmarks[i - 1].time);
+    }
+  });
+
+  it('v3 payloads still pass the legacy v1 parser gate (superset contract)', () => {
+    expect(passesLegacyGate(JSON.parse(JSON.stringify(sidecar)))).toBe(true);
+  });
+
+  it('parses v1 payloads with empty blocks', () => {
+    const v1 = { sourceText: 'hello world', duration: 12.5, bookmarks: [] };
+    const parsed = parseNarrationTimingJson(JSON.stringify(v1));
+    expect(parsed).not.toBeNull();
+    expect(parsed!.version).toBe(3);
+    expect(parsed!.blocks).toEqual([]);
+    expect(parsed!.duration).toBe(12.5);
+  });
+
+  it('rejects malformed payloads', () => {
+    expect(parseNarrationTimingJson('not json')).toBeNull();
+    expect(parseNarrationTimingJson('{"duration": 3}')).toBeNull();
+    expect(parseNarrationTimingJson('{"sourceText": "x", "duration": "3"}')).toBeNull();
+    expect(parseNarrationTimingJson('null')).toBeNull();
+  });
+
+  it('sorts and clamps hand-edited block ranges defensively', () => {
+    const messy = {
+      sourceText: 'a b c',
+      duration: 10,
+      blocks: [
+        { blockIndex: 1, charStart: 2, charEnd: 4, startSec: 6, endSec: 5 },
+        { blockIndex: 0, charStart: 0, charEnd: 2, startSec: 2, endSec: 4 },
+        { blockIndex: 2, charStart: 4, charEnd: 5, startSec: 'bad', endSec: 9 },
+      ],
+    };
+    const parsed = parseNarrationTimingJson(JSON.stringify(messy));
+    expect(parsed).not.toBeNull();
+    expect(parsed!.blocks.length).toBe(2); // the malformed one is dropped
+    expect(parsed!.blocks[0].startSec).toBe(2);
+    expect(parsed!.blocks[1].startSec).toBe(6);
+    expect(parsed!.blocks[1].endSec).toBe(6); // endSec clamped to startSec
+  });
+
+  it('drops non-finite bookmark entries instead of failing the file', () => {
+    const payload = {
+      sourceText: 'a b',
+      duration: 5,
+      bookmarks: [
+        { id: 'w0', time: 0.5, charOffset: 0 },
+        { id: 'bad', time: Number.NaN, charOffset: 2 },
+      ],
+    };
+    const parsed = parseNarrationTimingJson(JSON.stringify(payload));
+    expect(parsed!.bookmarks.length).toBe(1);
+  });
+});

package/src/__tests__/narrationSyllables.test.ts

@@ -0,0 +1,65 @@
+import { describe, it, expect } from 'vitest';
+import { estimateSyllables } from '../narration/syllables';
+
+describe('estimateSyllables', () => {
+  // Pinned corpus: exact values are part of the deterministic contract.
+  // ±1 misses on unusual words are acceptable and documented; these
+  // pins catch unintended drift, not linguistic perfection.
+  const corpus: Array<[string, number]> = [
+    ['a', 1],
+    ['the', 1],
+    ['word', 1],
+    ['hello', 2],
+    ['reading', 2],
+    ['syllable', 3],
+    ['teleprompter', 4],
+    ['narration', 3],
+    ['deterministic', 5],
+    ['table', 2],
+    ['little', 2],
+    ['whale', 1],
+    ['give', 1],
+    ['make', 1],
+    ['makes', 1],
+    ['boxes', 2],
+    ['riches', 2],
+    ['walked', 1],
+    ['wanted', 2],
+    ['loaded', 2],
+    ['agreed', 2],
+    ['squisq', 1],
+    ['beam-splitter', 3],
+    ["don't", 1],
+    ['yellow', 2],
+    ['rhythm', 1],
+    ['HTML', 4],
+    ['NASA', 2],
+    ['USA', 2], // vowel-bearing caps fall through to vowel groups (u + a)
+    ['Hello,', 2],
+    ['"quoted"', 2],
+    ['end.', 1],
+  ];
+
+  it.each(corpus)('%s → %d', (word, expected) => {
+    expect(estimateSyllables(word)).toBe(expected);
+  });
+
+  it('expands numbers via spoken-word equivalents', () => {
+    // "1910" → "nineteen ten" ≈ 2 words × 1.3 × 1.4 ≈ 4
+    expect(estimateSyllables('1910')).toBeGreaterThanOrEqual(3);
+    expect(estimateSyllables('1910')).toBeLessThanOrEqual(5);
+    // "175,000" is many spoken words
+    expect(estimateSyllables('175,000')).toBeGreaterThanOrEqual(5);
+    expect(estimateSyllables('7')).toBeGreaterThanOrEqual(1);
+  });
+
+  it('never returns less than 1 for non-empty tokens', () => {
+    for (const t of ['x', '—', '...', '?!', 'b2b', 'C-3PO']) {
+      expect(estimateSyllables(t)).toBeGreaterThanOrEqual(1);
+    }
+  });
+
+  it('is deterministic', () => {
+    expect(estimateSyllables('deterministic')).toBe(estimateSyllables('deterministic'));
+  });
+});

package/src/__tests__/narrationTestSignals.ts

@@ -0,0 +1,167 @@
+/**
+ * Synthetic PCM builders for narration-engine tests (test-only, not
+ * exported from the package). Everything is seeded via SeededRandom —
+ * the same arguments always produce the same samples.
+ */
+
+import { SeededRandom } from '../random/SeededRandom.js';
+import { parseMarkdown } from '../markdown/index.js';
+import { markdownToDoc } from '../doc/markdownToDoc.js';
+import { buildNarrationScript } from '../narration/script.js';
+import type { NarrationScript } from '../narration/types.js';
+
+export function silence(sec: number, sampleRate: number): Float32Array {
+  return new Float32Array(Math.max(0, Math.round(sec * sampleRate)));
+}
+
+/** Seeded white noise at a target RMS (uniform noise: rms = amp/√3). */
+export function noise(sec: number, sampleRate: number, rms: number, seed: number): Float32Array {
+  const rng = new SeededRandom(seed);
+  const out = new Float32Array(Math.max(0, Math.round(sec * sampleRate)));
+  const amp = rms * Math.sqrt(3);
+  for (let i = 0; i < out.length; i++) {
+    out[i] = (rng.next() * 2 - 1) * amp;
+  }
+  return out;
+}
+
+/** Pure tone (for band-response tests). */
+export function tone(freqHz: number, sec: number, sampleRate: number, amp = 0.5): Float32Array {
+  const out = new Float32Array(Math.round(sec * sampleRate));
+  const w = (2 * Math.PI * freqHz) / sampleRate;
+  for (let i = 0; i < out.length; i++) {
+    out[i] = amp * Math.sin(w * i);
+  }
+  return out;
+}
+
+/**
+ * A voiced burst: harmonics at 220/700/1400/2200 Hz under a Hann
+ * envelope plus 10% seeded noise — enough speech-band energy to trip
+ * the VAD and produce one envelope peak (one syllable nucleus).
+ */
+export function speechBurst(
+  sec: number,
+  sampleRate: number,
+  seed: number,
+  amp = 0.35,
+): Float32Array {
+  const rng = new SeededRandom(seed);
+  const n = Math.round(sec * sampleRate);
+  const out = new Float32Array(n);
+  const freqs = [220, 700, 1400, 2200];
+  const gains = [0.5, 1, 0.6, 0.3];
+  for (let i = 0; i < n; i++) {
+    const env = 0.5 * (1 - Math.cos((2 * Math.PI * i) / Math.max(1, n - 1)));
+    let s = 0;
+    for (let f = 0; f < freqs.length; f++) {
+      s += gains[f] * Math.sin((2 * Math.PI * freqs[f] * i) / sampleRate);
+    }
+    out[i] = amp * env * (s / 2.4 + 0.1 * (rng.next() * 2 - 1));
+  }
+  return out;
+}
+
+/** Overlay `piece` onto `target` starting at `atSec` (adds samples). */
+export function overlay(
+  target: Float32Array,
+  piece: Float32Array,
+  atSec: number,
+  sampleRate: number,
+): void {
+  const start = Math.round(atSec * sampleRate);
+  for (let i = 0; i < piece.length && start + i < target.length; i++) {
+    target[start + i] += piece[i];
+  }
+}
+
+export interface SyllableTrainOptions {
+  burstSec?: number;
+  noiseRms?: number;
+  totalSec?: number;
+  seed?: number;
+}
+
+/** Bursts at each onset time over a quiet noise floor (≈ −50 dB). */
+export function syllableTrain(
+  onsetsSec: number[],
+  sampleRate: number,
+  options?: SyllableTrainOptions,
+): Float32Array {
+  const burstSec = options?.burstSec ?? 0.16;
+  const noiseRms = options?.noiseRms ?? 0.003;
+  const seed = options?.seed ?? 1;
+  const last = onsetsSec.length > 0 ? Math.max(...onsetsSec) : 0;
+  const totalSec = options?.totalSec ?? last + burstSec + 0.5;
+  const pcm = noise(totalSec, sampleRate, noiseRms, seed);
+  onsetsSec.forEach((t, i) => {
+    overlay(pcm, speechBurst(burstSec, sampleRate, seed + 100 + i), t, sampleRate);
+  });
+  return pcm;
+}
+
+/** Build a real NarrationScript through the production pipeline. */
+export function scriptFromMarkdown(markdown: string): NarrationScript {
+  return buildNarrationScript(markdownToDoc(parseMarkdown(markdown)));
+}
+
+export interface SyntheticTake {
+  pcm: Float32Array;
+  /** Burst start time of each token's first syllable. */
+  trueWordTimes: number[];
+  /** True block start times (first word of each script block). */
+  trueBlockStarts: number[];
+  durationSec: number;
+}
+
+/**
+ * Synthesize a spoken take of a script: one burst per token syllable at
+ * a steady rate, with pauses matching the token pause classes.
+ */
+export function takeFromScript(
+  script: NarrationScript,
+  wpm: number,
+  sampleRate: number,
+  seed: number,
+  opts?: { leadInSec?: number; extraOnsets?: number[]; dropTokenSyllable?: number[] },
+): SyntheticTake {
+  const meanSylPerWord = Math.max(1, script.totalSyllables / Math.max(1, script.tokens.length));
+  const sylPeriod = 60 / wpm / meanSylPerWord;
+  const burstSec = Math.min(0.16, sylPeriod * 0.7);
+  const leadIn = opts?.leadInSec ?? 0.6;
+  const dropSet = new Set(opts?.dropTokenSyllable ?? []);
+
+  const onsets: number[] = [];
+  const trueWordTimes: number[] = [];
+  let cursor = leadIn;
+  for (let k = 0; k < script.tokens.length; k++) {
+    const token = script.tokens[k];
+    trueWordTimes.push(cursor);
+    for (let s = 0; s < token.syllables; s++) {
+      if (!dropSet.has(k * 1000 + s)) onsets.push(cursor);
+      cursor += sylPeriod;
+    }
+    if (token.pauseAfter === 1) cursor += 0.35;
+    else if (token.pauseAfter === 2) cursor += 0.9;
+    else if (token.pauseAfter === 3) cursor += 1.2;
+  }
+  for (const extra of opts?.extraOnsets ?? []) onsets.push(extra);
+  onsets.sort((a, b) => a - b);
+
+  const durationSec = cursor + 0.6;
+  const pcm = syllableTrain(onsets, sampleRate, { burstSec, totalSec: durationSec, seed });
+  const trueBlockStarts = script.blocks.map((b) => trueWordTimes[b.tokenStart]);
+  return { pcm, trueWordTimes, trueBlockStarts, durationSec };
+}
+
+export function concat(...segments: Float32Array[]): Float32Array {
+  let total = 0;
+  for (const s of segments) total += s.length;
+  const out = new Float32Array(total);
+  let offset = 0;
+  for (const s of segments) {
+    out.set(s, offset);
+    offset += s.length;
+  }
+  return out;
+}

package/src/__tests__/narrationVad.test.ts

@@ -0,0 +1,66 @@
+import { describe, it, expect } from 'vitest';
+import { extractFrameFeatures } from '../narration/features';
+import { createVadState, vadStep } from '../narration/vad';
+import { concat, noise, speechBurst } from './narrationTestSignals';
+
+const SR = 48000;
+
+function runVad(pcm: Float32Array) {
+  const frames = extractFrameFeatures(pcm, SR);
+  let state = createVadState();
+  const flags: boolean[] = [];
+  for (const frame of frames) {
+    state = vadStep(state, frame);
+    flags.push(state.speaking);
+  }
+  return { frames, flags };
+}
+
+describe('vadStep', () => {
+  it('enters within 100 ms of speech onset and exits within hangover + 100 ms', () => {
+    const quiet = 0.004;
+    const pcm = concat(noise(1.0, SR, quiet, 1), speechBurst(0.8, SR, 2), noise(1.2, SR, quiet, 3));
+    const { frames, flags } = runVad(pcm);
+
+    const burstStart = 1.0;
+    const burstEnd = 1.8;
+    const enterIdx = flags.findIndex((f) => f);
+    expect(enterIdx).toBeGreaterThan(-1);
+    // Hann envelope reaches useful energy ~15% in, so allow 100 ms + ramp.
+    expect(frames[enterIdx].tSec).toBeGreaterThan(burstStart);
+    expect(frames[enterIdx].tSec).toBeLessThan(burstStart + 0.25);
+
+    let lastSpeaking = -1;
+    for (let i = 0; i < flags.length; i++) if (flags[i]) lastSpeaking = i;
+    expect(lastSpeaking).toBeGreaterThan(-1);
+    // Envelope tails off before burstEnd; exit must happen within
+    // (ramp-down ~0.15) + hangover 0.3 + margin 0.1 of the burst end.
+    expect(frames[lastSpeaking].tSec).toBeLessThan(burstEnd + 0.45);
+    expect(frames[lastSpeaking].tSec).toBeGreaterThan(burstEnd - 0.45);
+  });
+
+  it('detects no speech on steady noise', () => {
+    const { flags } = runVad(noise(3, SR, 0.01, 9));
+    expect(flags.some(Boolean)).toBe(false);
+  });
+
+  it('adapts the floor to a noise step without flapping', () => {
+    // −40 dB → −30 dB noise step: the step transient may read as speech,
+    // but the dip-starved rebaseline (1.5 s of zero dips) must adopt the
+    // new floor and settle back to silence — permanently.
+    const pcm = concat(noise(2, SR, 0.01, 4), noise(4, SR, 0.0316, 5));
+    const { frames, flags } = runVad(pcm);
+    const tail = flags.filter((_, i) => frames[i].tSec > 3.8);
+    expect(tail.length).toBeGreaterThan(0);
+    expect(tail.some(Boolean)).toBe(false);
+  });
+
+  it('still detects speech over the louder floor after adapting', () => {
+    const pcm = concat(noise(2, SR, 0.0316, 6), speechBurst(0.6, SR, 7), noise(0.8, SR, 0.0316, 8));
+    const { frames, flags } = runVad(pcm);
+    const speakingTimes = frames.filter((_, i) => flags[i]).map((f) => f.tSec);
+    expect(speakingTimes.length).toBeGreaterThan(0);
+    expect(Math.min(...speakingTimes)).toBeGreaterThan(1.9);
+    expect(Math.min(...speakingTimes)).toBeLessThan(2.3);
+  });
+});

package/src/__tests__/resolveDocTheme.test.ts

@@ -2,13 +2,14 @@
  * resolveThemeForDoc — pure, doc-scoped theme resolution.
  *
  * The theme analog of buildRegistry: an inline custom theme resolves from the
- * doc's own `customThemes` list, with no global `registerTheme` call. Falls
- * back to built-ins for non-inline ids.
+ * doc's own `customThemes` list. Explicit caller registries and built-ins are
+ * fallback sources for non-inline ids.
  */
 
 import { describe, it, expect } from 'vitest';
 import { resolveThemeForDoc } from '../doc/resolveDocTheme';
 import { compileTheme } from '../schemas/themeCompile';
+import { createThemeRegistry } from '../schemas/Theme';
 import { DEFAULT_THEME } from '../schemas/themeLibrary';
 import type { Doc } from '../schemas/Doc.js';
 
@@ -52,4 +53,17 @@ describe('resolveThemeForDoc', () => {
   it('returns the default theme for a null doc', () => {
     expect(resolveThemeForDoc(null).id).toBe(DEFAULT_THEME.id);
   });
+
+  it('uses an explicit registry only after document-scoped definitions', () => {
+    const external = compileTheme({
+      id: 'external-brand',
+      name: 'External Brand',
+      seedColors: { primary: '#8844aa' },
+    });
+    const registry = createThemeRegistry([external]);
+    const doc = docWith({ themeId: 'external-brand' });
+
+    expect(resolveThemeForDoc(doc)).toBe(DEFAULT_THEME);
+    expect(resolveThemeForDoc(doc, undefined, registry)).toEqual(external);
+  });
 });

package/src/__tests__/rootExports.test.ts

@@ -1,6 +1,7 @@
 import { describe, expect, it } from 'vitest';
 import * as root from '../index';
 import * as icons from '../icons/index';
+import * as schemas from '../schemas/index';
 import * as transform from '../transform/index';
 
 const transformRuntimeExports = [
@@ -8,6 +9,7 @@ const transformRuntimeExports = [
   'resolveTransformStyle',
   'getTransformStyleIds',
   'getTransformStyleSummaries',
+  'createTransformStyleRegistry',
   'DEFAULT_TRANSFORM_STYLE_ID',
   'analyzeBlocks',
   'extractDocImages',
@@ -40,4 +42,20 @@ describe('root barrel exports', () => {
   it('re-exports icon runtime APIs', () => {
     expectReExported(root, icons, iconRuntimeExports);
   });
+
+  it('does not publish process-global registry mutators', () => {
+    for (const name of [
+      'registerTheme',
+      'unregisterTheme',
+      'getRegisteredThemes',
+      'lookupRegisteredTheme',
+    ]) {
+      expect(root).not.toHaveProperty(name);
+      expect(schemas).not.toHaveProperty(name);
+    }
+    for (const name of ['registerTransformStyle', 'unregisterTransformStyle']) {
+      expect(root).not.toHaveProperty(name);
+      expect(transform).not.toHaveProperty(name);
+    }
+  });
 });