@bendyline/squisq 1.5.2 → 2.0.1

package/src/__tests__/materializeBlockLayers.test.ts

@@ -0,0 +1,135 @@
+import { describe, expect, it, vi } from 'vitest';
+import { DEFAULT_THEME, expandDocBlocks } from '../doc/templates/index.js';
+import { materializeBlockLayers } from '../doc/materializeBlockLayers.js';
+import type { CustomTemplateDefinition } from '../schemas/CustomTemplates.js';
+import type { Block, Layer, TextLayer } from '../schemas/Doc.js';
+import type { TemplateBlock } from '../schemas/BlockTemplates.js';
+
+const titleBlock: TemplateBlock = {
+  template: 'title',
+  id: 'title-1',
+  duration: 5,
+  audioSegment: 0,
+  title: 'A canonical materializer',
+};
+
+describe('materializeBlockLayers', () => {
+  it('returns owned layers and metadata for built-in and authored blocks', () => {
+    const templated = materializeBlockLayers(titleBlock, { persistentLayers: false });
+    expect(templated.source).toBe('template');
+    expect(templated.diagnostic).toBeUndefined();
+    expect(templated.layers.length).toBeGreaterThan(0);
+
+    const authoredLayer: Layer = {
+      id: 'authored',
+      type: 'shape',
+      content: { shape: 'rect', fill: '#123456' },
+      position: { x: 0, y: 0, width: 10, height: 10 },
+    };
+    const authored: Block = {
+      id: 'raw',
+      startTime: 0,
+      duration: 5,
+      audioSegment: 0,
+      layers: [authoredLayer],
+    };
+    const materialized = materializeBlockLayers(authored, { persistentLayers: false });
+    expect(materialized.source).toBe('authored');
+    expect(materialized.layers).toEqual([authoredLayer]);
+    expect(materialized.layers[0]).not.toBe(authoredLayer);
+  });
+
+  it('resolves document-scoped custom templates in the on-demand API', () => {
+    const customTemplate: CustomTemplateDefinition = {
+      name: 'hero',
+      label: 'Hero',
+      viewport: { width: 1920, height: 1080 },
+      layers: [
+        {
+          id: 'hero-title',
+          type: 'text',
+          position: { x: '5%', y: '10%', width: '90%' },
+          content: { text: '{title}', style: { fontSize: 64, color: '#000000' } },
+        },
+      ],
+    };
+    const block = {
+      ...titleBlock,
+      template: 'hero',
+      title: 'Doc-scoped',
+    } as unknown as TemplateBlock;
+
+    const result = materializeBlockLayers(block, {
+      customTemplates: [customTemplate],
+      persistentLayers: false,
+    });
+
+    expect(result.source).toBe('template');
+    expect((result.layers[0] as TextLayer).content.text).toBe('Doc-scoped');
+  });
+
+  it('returns structured diagnostics and a visible fallback without logging', () => {
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+    const error = vi.spyOn(console, 'error').mockImplementation(() => {});
+    const unknown = { ...titleBlock, template: 'not-registered' } as unknown as TemplateBlock;
+
+    const result = materializeBlockLayers(unknown, { persistentLayers: false });
+
+    expect(result.source).toBe('fallback');
+    expect(result.diagnostic).toEqual({
+      code: 'unknown-template',
+      template: 'not-registered',
+      message: 'Unknown template "not-registered"',
+    });
+    expect(result.layers.some((layer) => layer.id === 'fallback-notice')).toBe(true);
+    expect(warn).not.toHaveBeenCalled();
+    expect(error).not.toHaveBeenCalled();
+    warn.mockRestore();
+    error.mockRestore();
+  });
+
+  it('supports an explicit empty failure policy', () => {
+    const unknown = { ...titleBlock, template: 'not-registered' } as unknown as TemplateBlock;
+    const result = materializeBlockLayers(unknown, {
+      failureMode: 'empty',
+      persistentLayers: false,
+    });
+
+    expect(result.source).toBe('empty');
+    expect(result.layers).toEqual([]);
+    expect(result.diagnostic?.code).toBe('unknown-template');
+  });
+
+  it('inherits theme persistent layers by default and has an explicit opt-out', () => {
+    const theme = {
+      ...DEFAULT_THEME,
+      persistentLayers: {
+        bottomLayers: [
+          {
+            template: 'solidBackground' as const,
+            config: { type: 'solidBackground' as const, color: '#123456' },
+          },
+        ],
+      },
+    };
+
+    const inherited = materializeBlockLayers(titleBlock, { theme });
+    const disabled = materializeBlockLayers(titleBlock, { theme, persistentLayers: false });
+
+    expect(inherited.layers[0]?.id).toContain('solid');
+    expect(disabled.layers[0]?.id).not.toContain('solid');
+  });
+
+  it('is the only materialization path used by timed expansion', () => {
+    const diagnostics: string[] = [];
+    const unknown = { ...titleBlock, template: 'not-registered' } as unknown as TemplateBlock;
+    const direct = materializeBlockLayers(unknown, { persistentLayers: false });
+    const [scheduled] = expandDocBlocks([unknown], {
+      persistentLayers: false,
+      onDiagnostic: (diagnostic) => diagnostics.push(diagnostic.code),
+    });
+
+    expect(scheduled.layers).toEqual(direct.layers);
+    expect(diagnostics).toEqual(['unknown-template']);
+  });
+});

package/src/__tests__/materializeTestUtils.ts

@@ -0,0 +1,17 @@
+import type { Layer } from '../schemas/Doc.js';
+import type { DocBlock } from '../schemas/BlockTemplates.js';
+import {
+  materializeBlockLayers,
+  type MaterializeBlockLayersOptions,
+} from '../doc/materializeBlockLayers.js';
+
+/** Materialize isolated test fixtures without inheriting theme atmosphere. */
+export function materializeLayers(
+  block: DocBlock,
+  options: MaterializeBlockLayersOptions = {},
+): Layer[] {
+  return materializeBlockLayers(block, {
+    persistentLayers: false,
+    ...options,
+  }).layers;
+}

package/src/__tests__/narrationAlign.test.ts

@@ -0,0 +1,150 @@
+import { describe, it, expect } from 'vitest';
+import { alignNarration } from '../narration/align';
+import type { NarrationAlignment, NarrationScript } from '../narration/types';
+import type { NarrationTrace } from '../narration/trace';
+import { scriptFromMarkdown, takeFromScript, type SyntheticTake } from './narrationTestSignals';
+
+const SR = 48000;
+
+const MD = `# The River Walk
+
+Every morning we follow the path along the river and count the boats heading out.
+The bakery opens early and the smell of bread carries across the water to the far bank.
+
+By noon the light changes and the whole town seems to slow down for an hour or two.
+
+## The Market
+
+Stalls line the square with fruit and flowers and a man who fixes watches while you wait.
+We always stop for coffee before carrying everything home up the long hill past the church.
+
+## Evening
+
+The lamps come on one street at a time and the river turns the color of old coins.
+`;
+
+const script = scriptFromMarkdown(MD);
+
+/** Burst onsets are at word start; envelope peaks ~half a burst later. */
+const PEAK_OFFSET = 0.08;
+
+function timingErrors(alignment: NarrationAlignment, take: SyntheticTake): number[] {
+  return alignment.words.map((w, k) => Math.abs(w.tSec - (take.trueWordTimes[k] + PEAK_OFFSET)));
+}
+
+function median(values: number[]): number {
+  const sorted = [...values].sort((a, b) => a - b);
+  return sorted[Math.floor(sorted.length / 2)];
+}
+
+function p95(values: number[]): number {
+  const sorted = [...values].sort((a, b) => a - b);
+  return sorted[Math.min(sorted.length - 1, Math.floor(sorted.length * 0.95))];
+}
+
+/** A live trace with a deterministic ±wobble, as a recorded prompter would produce. */
+function traceFromTake(
+  take: SyntheticTake,
+  scriptRef: NarrationScript,
+  wobbleSec: number,
+): NarrationTrace {
+  const samples: { tMs: number; wordPos: number }[] = [];
+  for (let t = 0; t <= take.durationSec; t += 0.25) {
+    const shifted = t + wobbleSec * Math.sin(t * 1.3);
+    // wordPos convention: floor(wordPos) is the ACTIVE token — the word
+    // currently being spoken — not the count of words started.
+    let started = 0;
+    while (started < take.trueWordTimes.length && take.trueWordTimes[started] <= shifted) started++;
+    const wordPos = Math.max(0, started - 1);
+    samples.push({ tMs: t * 1000, wordPos: Math.min(wordPos, scriptRef.tokens.length) });
+  }
+  return { samples };
+}
+
+describe('alignNarration', () => {
+  const take = takeFromScript(script, 150, SR, 21);
+
+  it('clean take without a trace: median error < 0.25 s, p95 < 1 s', () => {
+    const alignment = alignNarration({ pcm: take.pcm, sampleRate: SR, script });
+    expect(alignment.words.length).toBe(script.tokens.length);
+    const errors = timingErrors(alignment, take);
+    expect(median(errors)).toBeLessThan(0.25);
+    expect(p95(errors)).toBeLessThan(1.0);
+    expect(alignment.detectedSyllables).toBeGreaterThan(script.totalSyllables * 0.7);
+  });
+
+  it('clean take with a wobbly trace: median error < 0.15 s, p95 < 0.5 s', () => {
+    const trace = traceFromTake(take, script, 0.8);
+    const alignment = alignNarration({ pcm: take.pcm, sampleRate: SR, script, trace });
+    const errors = timingErrors(alignment, take);
+    expect(median(errors)).toBeLessThan(0.15);
+    expect(p95(errors)).toBeLessThan(0.5);
+  });
+
+  it('survives filler insertions and a dropped syllable', () => {
+    const messy = takeFromScript(script, 150, SR, 22, {
+      extraOnsets: [4.1, 12.4],
+      dropTokenSyllable: [8 * 1000 + 0],
+    });
+    const trace = traceFromTake(messy, script, 0.5);
+    const alignment = alignNarration({ pcm: messy.pcm, sampleRate: SR, script, trace });
+    const errors = timingErrors(alignment, messy);
+    expect(median(errors)).toBeLessThan(0.25);
+  });
+
+  it('block ranges are contiguous, monotonic, and near the true block starts', () => {
+    const trace = traceFromTake(take, script, 0.4);
+    const alignment = alignNarration({ pcm: take.pcm, sampleRate: SR, script, trace });
+    const blocks = alignment.blocks;
+    expect(blocks.length).toBe(script.blocks.length);
+    expect(blocks[0].startSec).toBe(0);
+    for (let b = 0; b < blocks.length - 1; b++) {
+      expect(blocks[b].endSec).toBeCloseTo(blocks[b + 1].startSec, 9);
+      expect(blocks[b].endSec).toBeGreaterThanOrEqual(blocks[b].startSec);
+    }
+    const last = blocks[blocks.length - 1];
+    expect(last.endSec).toBeGreaterThan(last.startSec);
+    expect(last.endSec).toBeLessThanOrEqual(take.durationSec + 1e-6);
+    for (let b = 1; b < blocks.length; b++) {
+      expect(Math.abs(blocks[b].startSec - take.trueBlockStarts[b])).toBeLessThan(0.7);
+    }
+  });
+
+  it('word times are monotonic', () => {
+    const alignment = alignNarration({ pcm: take.pcm, sampleRate: SR, script });
+    for (let i = 1; i < alignment.words.length; i++) {
+      expect(alignment.words[i].tSec).toBeGreaterThanOrEqual(alignment.words[i - 1].tSec);
+    }
+  });
+
+  it('falls back proportionally when nothing is detected', () => {
+    const quiet = new Float32Array(SR * 5);
+    const alignment = alignNarration({ pcm: quiet, sampleRate: SR, script });
+    expect(alignment.detectedSyllables).toBe(0);
+    expect(alignment.words.length).toBe(script.tokens.length);
+    expect(alignment.words.every((w) => w.interpolated)).toBe(true);
+    expect(alignment.blocks.length).toBe(script.blocks.length);
+  });
+
+  it('handles an empty script', () => {
+    const alignment = alignNarration({
+      pcm: new Float32Array(SR),
+      sampleRate: SR,
+      script: {
+        sourceText: '',
+        tokens: [],
+        blocks: [],
+        totalSyllables: 0,
+        cumulativeSyllables: [0],
+      },
+    });
+    expect(alignment.words).toEqual([]);
+    expect(alignment.blocks).toEqual([]);
+  });
+
+  it('is deterministic', () => {
+    const a = alignNarration({ pcm: take.pcm, sampleRate: SR, script });
+    const b = alignNarration({ pcm: take.pcm, sampleRate: SR, script });
+    expect(a).toEqual(b);
+  });
+});

package/src/__tests__/narrationFeatures.test.ts

@@ -0,0 +1,71 @@
+import { describe, it, expect } from 'vitest';
+import { createFeatureState, extractFrameFeatures, featureStep } from '../narration/features';
+import { tone, noise } from './narrationTestSignals';
+
+const RATES = [48000, 44100];
+
+describe('extractFrameFeatures', () => {
+  it.each(RATES)('band energy passes speech band and rejects hum/hiss @ %d Hz', (sr) => {
+    const inBand = extractFrameFeatures(tone(1000, 0.5, sr), sr);
+    const hum = extractFrameFeatures(tone(60, 0.5, sr), sr);
+    const hiss = extractFrameFeatures(tone(8000, 0.5, sr), sr);
+
+    // Skip filter warm-up frames; compare steady-state medians.
+    const median = (frames: { bandEnergy: number }[]) => {
+      const vals = frames
+        .slice(5)
+        .map((f) => f.bandEnergy)
+        .sort((a, b) => a - b);
+      return vals[Math.floor(vals.length / 2)];
+    };
+    expect(median(inBand)).toBeGreaterThan(median(hum) * 10);
+    expect(median(inBand)).toBeGreaterThan(median(hiss) * 10);
+  });
+
+  it.each(RATES)('zcr orders noise above tone @ %d Hz', (sr) => {
+    const noisy = extractFrameFeatures(noise(0.3, sr, 0.2, 7), sr);
+    const tonal = extractFrameFeatures(tone(300, 0.3, sr), sr);
+    expect(noisy[5].zcr).toBeGreaterThan(tonal[5].zcr);
+  });
+
+  it('rms measures a known-amplitude tone (~amp/√2)', () => {
+    const sr = 48000;
+    const frames = extractFrameFeatures(tone(440, 0.3, sr, 0.5), sr);
+    expect(frames[5].rms).toBeGreaterThan(0.3);
+    expect(frames[5].rms).toBeLessThan(0.4);
+  });
+
+  it.each(RATES)('streaming chunks produce the same frames as one batch @ %d Hz', (sr) => {
+    const pcm = noise(0.5, sr, 0.1, 42);
+    const batch = extractFrameFeatures(pcm, sr);
+
+    let state = createFeatureState(sr);
+    const streamed: ReturnType<typeof extractFrameFeatures> = [];
+    // Uneven chunk sizes exercise the carry logic.
+    const chunks = [100, 1024, 333, 4096, 57];
+    let offset = 0;
+    let pick = 0;
+    while (offset < pcm.length) {
+      const size = Math.min(chunks[pick++ % chunks.length], pcm.length - offset);
+      const step = featureStep(state, pcm.subarray(offset, offset + size));
+      state = step.state;
+      streamed.push(...step.frames);
+      offset += size;
+    }
+
+    expect(streamed.length).toBe(batch.length);
+    for (let i = 0; i < batch.length; i++) {
+      expect(streamed[i].tSec).toBeCloseTo(batch[i].tSec, 9);
+      expect(streamed[i].rms).toBeCloseTo(batch[i].rms, 9);
+      expect(streamed[i].bandEnergy).toBeCloseTo(batch[i].bandEnergy, 9);
+      expect(streamed[i].zcr).toBeCloseTo(batch[i].zcr, 9);
+    }
+  });
+
+  it('frame centers advance by the hop', () => {
+    const sr = 48000;
+    const frames = extractFrameFeatures(noise(0.3, sr, 0.1, 3), sr, { hopSec: 0.02 });
+    expect(frames.length).toBeGreaterThan(5);
+    expect(frames[1].tSec - frames[0].tSec).toBeCloseTo(0.02, 3);
+  });
+});

package/src/__tests__/narrationNuclei.test.ts

@@ -0,0 +1,45 @@
+import { describe, it, expect } from 'vitest';
+import { extractFrameFeatures } from '../narration/features';
+import { createVadState, vadStep } from '../narration/vad';
+import { detectSyllableOnsets } from '../narration/nuclei';
+import { syllableTrain } from './narrationTestSignals';
+
+const SR = 48000;
+
+function detect(pcm: Float32Array): number[] {
+  const frames = extractFrameFeatures(pcm, SR, { hopSec: 0.01 });
+  let vad = createVadState();
+  const flags = frames.map((f) => {
+    vad = vadStep(vad, f);
+    return vad.speaking;
+  });
+  return detectSyllableOnsets(frames, flags);
+}
+
+describe('detectSyllableOnsets', () => {
+  it('finds each burst in a syllable train (±1 count, ±60 ms timing)', () => {
+    const truth = [0.6, 0.9, 1.2, 1.5, 2.2, 2.5, 2.8, 3.6, 3.9, 4.2, 4.5, 4.8];
+    const onsets = detect(syllableTrain(truth, SR, { seed: 11 }));
+    expect(Math.abs(onsets.length - truth.length)).toBeLessThanOrEqual(1);
+
+    // Each detected onset lies near some true burst (peak ≈ burst center,
+    // so allow the 80 ms half-burst plus 60 ms tolerance).
+    for (const t of onsets) {
+      const nearest = Math.min(...truth.map((x) => Math.abs(t - (x + 0.08))));
+      expect(nearest).toBeLessThanOrEqual(0.06 + 0.04);
+    }
+  });
+
+  it('suppresses double-bursts closer than the minimum spacing', () => {
+    // Two bursts 60 ms apart → their envelopes merge / spacing gate fires:
+    // at most one onset in that neighborhood.
+    const onsets = detect(syllableTrain([1.0, 1.06, 2.0], SR, { seed: 12 }));
+    const nearOne = onsets.filter((t) => t > 0.8 && t < 1.5);
+    expect(nearOne.length).toBeLessThanOrEqual(1);
+  });
+
+  it('reports nothing on silence/noise', () => {
+    const onsets = detect(syllableTrain([], SR, { totalSec: 2, seed: 13 }));
+    expect(onsets.length).toBe(0);
+  });
+});

package/src/__tests__/narrationPacing.test.ts

@@ -0,0 +1,189 @@
+import { describe, it, expect } from 'vitest';
+import {
+  createPacingState,
+  pacingStep,
+  reanchorPacing,
+  type PacingState,
+  type PacingTick,
+} from '../narration/pacing';
+import { expectedSyllablesAt } from '../narration/script';
+import { DEFAULT_PACING_CONFIG, type PacingConfig } from '../narration/types';
+import { scriptFromMarkdown } from './narrationTestSignals';
+
+const MD = `# Cadence
+
+The quick brown fox jumps over the lazy dog while we keep a steady pace for this test.
+It continues with more plain words that carry roughly one or two syllables each one.
+
+Another paragraph starts after a pause and keeps going with the same easy words for a while.
+
+## Second Section
+
+More text lives here so the script is long enough that the prompter never runs off the end.
+The prompter should track the reader through all of it without drifting away from the voice.
+`;
+
+const script = scriptFromMarkdown(MD);
+const BASE_WPS = DEFAULT_PACING_CONFIG.baseWpm / 60;
+const DT = 0.02;
+
+/** Drive the controller with speaking ticks emitting onsets at `sylRate` (syl/s). */
+function drive(
+  state: PacingState,
+  fromSec: number,
+  durSec: number,
+  opts: { speaking: boolean; sylRate?: number },
+  config?: Partial<PacingConfig>,
+): PacingState {
+  let acc = 0;
+  let next = state;
+  for (let t = fromSec; t < fromSec + durSec; t += DT) {
+    let onsets = 0;
+    if (opts.speaking && opts.sylRate) {
+      acc += opts.sylRate * DT;
+      while (acc >= 1) {
+        onsets += 1;
+        acc -= 1;
+      }
+    }
+    const tick: PacingTick = { tSec: t, speaking: opts.speaking, onsets };
+    next = pacingStep(next, tick, script, config);
+  }
+  return next;
+}
+
+const meanSylPerWord = script.totalSyllables / script.tokens.length;
+
+describe('pacingStep', () => {
+  it('halts within 250 ms of silence', () => {
+    let state = drive(createPacingState(), 0, 3, {
+      speaking: true,
+      sylRate: BASE_WPS * meanSylPerWord,
+    });
+    expect(state.velocityWps).toBeGreaterThan(BASE_WPS * 0.5);
+    const velocityAtSilence = state.velocityWps;
+    state = drive(state, 3, 0.25, { speaking: false });
+    expect(state.velocityWps).toBeLessThan(velocityAtSilence * 0.05);
+    state = drive(state, 3.25, 0.3, { speaking: false });
+    expect(state.velocityWps).toBe(0);
+    expect(state.halted).toBe(true);
+  });
+
+  it('tracks the reader rate monotonically', () => {
+    // Faster reading → faster prompter is the whole point of voice pacing.
+    let prevSlope = 0;
+    for (const mult of [0.6, 1.0, 1.8]) {
+      const sylRate = mult * BASE_WPS * meanSylPerWord;
+      const state = drive(createPacingState(), 0, 8, { speaking: true, sylRate });
+      const slope = state.wordPos / 8;
+      expect(slope).toBeGreaterThan(prevSlope);
+      prevSlope = slope;
+    }
+  });
+
+  it('stays word-aligned when the reader matches the set pace', () => {
+    const sylRate = BASE_WPS * meanSylPerWord;
+    const state = drive(createPacingState(), 0, 8, { speaking: true, sylRate });
+    const drift =
+      expectedSyllablesAt(script, state.wordPos) - (state.anchorExpectedSyl + state.cumDetectedSyl);
+    expect(Math.abs(drift)).toBeLessThan(6);
+  });
+
+  it('the WPM setting is a live lever: higher baseWpm → faster cruise', () => {
+    // Same modest voice rate, different set pace. Because the set pace is a
+    // real feedforward term (not cancelled), doubling baseWpm must visibly
+    // speed the prompter up — the bug the user reported.
+    const sylRate = 0.8 * BASE_WPS * meanSylPerWord;
+    const slow = drive(createPacingState(), 0, 8, { speaking: true, sylRate });
+    const fast = drive(createPacingState(), 0, 8, { speaking: true, sylRate }, { baseWpm: 260 });
+    expect(fast.wordPos).toBeGreaterThan(slow.wordPos * 1.3);
+  });
+
+  it('never crawls below the set pace floor while speaking', () => {
+    // A detector that reports almost nothing must still cruise near the set
+    // pace (blend keeps baseWps in play) — so the prompter can't stall out
+    // when syllable detection under-counts.
+    const state = drive(createPacingState(), 0, 6, { speaking: true, sylRate: 0.05 });
+    const slope = state.wordPos / 6;
+    expect(slope).toBeGreaterThan(BASE_WPS * DEFAULT_PACING_CONFIG.minRateMult * 0.8);
+  });
+
+  it('clamps velocity at the cruise-band bounds', () => {
+    // Absurdly fast reader: velocity respects the maxRateMult × set-pace
+    // clamp (plus the bounded PI correction).
+    let state = createPacingState();
+    let acc = 0;
+    const sylRate = 6 * BASE_WPS * meanSylPerWord;
+    for (let t = 0; t < 5; t += DT) {
+      acc += sylRate * DT;
+      let onsets = 0;
+      while (acc >= 1) {
+        onsets += 1;
+        acc -= 1;
+      }
+      state = pacingStep(state, { tSec: t, speaking: true, onsets }, script);
+      expect(state.velocityWps).toBeLessThanOrEqual(
+        BASE_WPS * DEFAULT_PACING_CONFIG.maxRateMult * (1 + DEFAULT_PACING_CONFIG.maxCorrection) +
+          1e-9,
+      );
+    }
+  });
+
+  it('silence halts the prompter and never drags it backward', () => {
+    // Park mid-script ahead of the detected syllables, then go silent. An
+    // under-counting detector makes err > 0 ("prompter ahead"); the
+    // forward-only correction must NOT slow or rewind — the prompter simply
+    // holds position (velocity halts) rather than snapping back.
+    const startPos = Math.min(20, script.tokens.length - 1);
+    const anchored = reanchorPacing(createPacingState(), startPos, script);
+    const state = drive({ ...anchored, wordPos: startPos + 3 }, 0, 2.5, { speaking: false });
+    expect(state.velocityWps).toBe(0);
+    expect(state.wordPos).toBeGreaterThanOrEqual(startPos + 3 - 1e-9);
+  });
+
+  it('catches up forward when the reader is ahead of the prompter', () => {
+    // Feed a strong syllable stream while the prompter starts behind: the
+    // forward-only boost (and, past the threshold, a forward resync) must
+    // pull the highlight forward to meet the voice.
+    const state = drive(createPacingState(), 0, 6, {
+      speaking: true,
+      sylRate: 2 * BASE_WPS * meanSylPerWord,
+    });
+    const detected = state.cumDetectedSyl;
+    // The prompter should have advanced to roughly where those syllables land.
+    const expectedPos = expectedSyllablesAt(script, state.wordPos);
+    expect(expectedPos).toBeGreaterThan(detected * 0.6);
+  });
+
+  it('reanchorPacing resets error tracking but keeps the learned rate', () => {
+    const state = drive(createPacingState(), 0, 4, {
+      speaking: true,
+      sylRate: BASE_WPS * meanSylPerWord,
+    });
+    const ema = state.emaSylPerSec;
+    expect(ema).toBeGreaterThan(0);
+    const anchored = reanchorPacing(state, 5, script);
+    expect(anchored.wordPos).toBe(5);
+    expect(anchored.cumDetectedSyl).toBe(0);
+    expect(anchored.errIntegral).toBe(0);
+    expect(anchored.emaSylPerSec).toBe(ema);
+  });
+
+  it('is pure: identical tick sequences yield identical states', () => {
+    const run = () => {
+      let state = createPacingState();
+      state = drive(state, 0, 2, { speaking: true, sylRate: 4 });
+      state = drive(state, 2, 1, { speaking: false });
+      state = drive(state, 3, 2, { speaking: true, sylRate: 6 });
+      return state;
+    };
+    expect(JSON.stringify(run())).toBe(JSON.stringify(run()));
+  });
+
+  it('never leaves the script bounds', () => {
+    let state = createPacingState();
+    state = drive(state, 0, 60, { speaking: true, sylRate: 40 });
+    expect(state.wordPos).toBeLessThanOrEqual(script.tokens.length);
+    expect(state.wordPos).toBeGreaterThanOrEqual(0);
+  });
+});