@bendyline/squisq 1.5.1 → 2.0.0

package/src/narration/script.ts

@@ -0,0 +1,239 @@
+/**
+ * Teleprompter script model: a Doc flattened into an ordered word-token
+ * stream with per-block ranges.
+ *
+ * `sourceText` is the canonical narration text — it is stored verbatim
+ * in the timing sidecar, and every token/block `charOffset` indexes into
+ * it. Determinism matters: the same Doc always builds a byte-identical
+ * script, because sidecar↔doc matching later compares slices of this
+ * exact string.
+ */
+
+import type { Block, Doc } from '../schemas/Doc.js';
+import { flattenRenderableBlocks, getBlockBodyText } from '../doc/markdownToDoc.js';
+import { estimateSpokenWordCount } from '../timing/narrationTiming.js';
+import { estimateSyllables } from './syllables.js';
+import type { NarrationScript, ScriptBlockRange, ScriptToken, WordTiming } from './types.js';
+
+export interface BuildScriptOptions {
+  /** Include block headings as spoken text (readers usually speak them). Default true. */
+  includeTitles?: boolean;
+  /** Separator joining block texts inside `sourceText`. Default '\n\n'. */
+  blockSeparator?: string;
+}
+
+/** Spoken text of one block: optional title line + body plain text. */
+function blockSpokenText(block: Block, includeTitles: boolean): string {
+  const title = includeTitles && block.title ? block.title.trim() : '';
+  const body = getBlockBodyText(block);
+  if (title && body) return `${title}\n${body}`;
+  return title || body;
+}
+
+/**
+ * Build the narration script for a doc. Blocks with no spoken text
+ * (pure-media sections, container-template children) contribute no
+ * tokens and no block range.
+ */
+export function buildNarrationScript(doc: Doc, options?: BuildScriptOptions): NarrationScript {
+  const includeTitles = options?.includeTitles ?? true;
+  const separator = options?.blockSeparator ?? '\n\n';
+
+  const pieces: Array<{ blockId: string; heading?: string; text: string }> = [];
+  for (const block of flattenRenderableBlocks(doc.blocks)) {
+    const text = blockSpokenText(block, includeTitles);
+    if (!text) continue;
+    pieces.push({
+      blockId: block.id,
+      heading: block.title || undefined,
+      text,
+    });
+  }
+
+  let sourceText = '';
+  const blocks: ScriptBlockRange[] = [];
+  for (let i = 0; i < pieces.length; i++) {
+    if (i > 0) sourceText += separator;
+    const charStart = sourceText.length;
+    sourceText += pieces[i].text;
+    blocks.push({
+      blockId: pieces[i].blockId,
+      ...(pieces[i].heading !== undefined ? { heading: pieces[i].heading } : {}),
+      tokenStart: 0,
+      tokenEnd: 0,
+      charStart,
+      charEnd: sourceText.length,
+    });
+  }
+
+  // Tokenize with a single left-to-right scan so charOffsets are exact.
+  const tokens: ScriptToken[] = [];
+  const tokenRe = /\S+/g;
+  let blockIndex = 0;
+  let match: RegExpExecArray | null;
+  while ((match = tokenRe.exec(sourceText)) !== null) {
+    const charOffset = match.index;
+    const charEnd = charOffset + match[0].length;
+    while (blockIndex < blocks.length - 1 && charOffset >= blocks[blockIndex].charEnd) {
+      blockIndex++;
+    }
+    // A token with no letters or digits (a standalone em-dash, bullet, …)
+    // is punctuation, not a word: it displays but is never spoken.
+    const spoken = hasSpokenContent(match[0]);
+    tokens.push({
+      text: match[0],
+      charOffset,
+      charEnd,
+      blockId: blocks[blockIndex]?.blockId ?? '',
+      blockIndex,
+      syllables: spoken ? estimateSyllables(match[0]) : 0,
+      spokenWordEquiv: spoken ? estimateSpokenWordCount(stripBoundaryPunct(match[0])) : 0,
+      pauseAfter: 0,
+      spoken,
+    });
+  }
+
+  // Token ranges per block.
+  for (const range of blocks) {
+    range.tokenStart = tokens.length;
+    range.tokenEnd = 0;
+  }
+  for (let i = 0; i < tokens.length; i++) {
+    const range = blocks[tokens[i].blockIndex];
+    if (range) {
+      if (i < range.tokenStart) range.tokenStart = i;
+      range.tokenEnd = i + 1;
+    }
+  }
+  for (const range of blocks) {
+    if (range.tokenStart > range.tokenEnd) {
+      // No tokens landed in this range (cannot happen for non-empty text,
+      // but keep the invariant tokenStart ≤ tokenEnd).
+      range.tokenStart = range.tokenEnd;
+    }
+  }
+
+  // Pause classes: block boundary > paragraph break > clause punctuation.
+  for (let i = 0; i < tokens.length; i++) {
+    const token = tokens[i];
+    const next = tokens[i + 1];
+    if (!next || next.blockIndex !== token.blockIndex) {
+      token.pauseAfter = 3;
+    } else if (sourceText.slice(token.charEnd, next.charOffset).includes('\n')) {
+      // getBlockBodyText joins paragraphs/list items with a single '\n',
+      // so ANY newline in the inter-token gap is a paragraph-class pause.
+      token.pauseAfter = 2;
+    } else if (endsWithClausePunctuation(token.text)) {
+      token.pauseAfter = 1;
+    }
+  }
+
+  const cumulativeSyllables = new Array<number>(tokens.length + 1);
+  cumulativeSyllables[0] = 0;
+  for (let i = 0; i < tokens.length; i++) {
+    cumulativeSyllables[i + 1] = cumulativeSyllables[i] + tokens[i].syllables;
+  }
+
+  return {
+    sourceText,
+    tokens,
+    blocks,
+    totalSyllables: cumulativeSyllables[tokens.length],
+    cumulativeSyllables,
+  };
+}
+
+const TRAILING_CLOSERS = /["')\]}»”’]+$/;
+
+/** True when a token carries at least one letter or digit (i.e. is spoken). */
+function hasSpokenContent(token: string): boolean {
+  return /[\p{L}\p{N}]/u.test(token);
+}
+
+function stripBoundaryPunct(token: string): string {
+  return token.replace(/^[.,!?;:'"()[\]{}]+|[.,!?;:'"()[\]{}]+$/g, '');
+}
+
+/** Clause/sentence punctuation at the token's end (closing quotes/brackets tolerated). */
+function endsWithClausePunctuation(token: string): boolean {
+  const bare = token.replace(TRAILING_CLOSERS, '');
+  const last = bare.charAt(bare.length - 1);
+  if (!last) return false;
+  if (last === ',') {
+    // Digit-grouping commas never end a token (a trailing comma has no
+    // following digit), so any terminal comma is a real pause.
+    return true;
+  }
+  return last === '.' || last === ';' || last === ':' || last === '!' || last === '?';
+}
+
+/** Clamp helper shared by the query functions. */
+function clamp(value: number, min: number, max: number): number {
+  return value < min ? min : value > max ? max : value;
+}
+
+/**
+ * Expected cumulative syllables at a (fractional) word position —
+ * linear interpolation over the prefix sums.
+ */
+export function expectedSyllablesAt(script: NarrationScript, wordPos: number): number {
+  const n = script.tokens.length;
+  if (n === 0) return 0;
+  const pos = clamp(wordPos, 0, n);
+  const idx = Math.floor(pos);
+  if (idx >= n) return script.totalSyllables;
+  return script.cumulativeSyllables[idx] + (pos - idx) * script.tokens[idx].syllables;
+}
+
+/**
+ * Inverse of {@link expectedSyllablesAt}: the fractional word position at
+ * which the script reaches `syllables` cumulative syllables. Used by the
+ * pacing controller's hard resync.
+ */
+export function wordPosAtExpectedSyllables(script: NarrationScript, syllables: number): number {
+  const n = script.tokens.length;
+  if (n === 0) return 0;
+  const target = clamp(syllables, 0, script.totalSyllables);
+  // Binary search: last index with cumulativeSyllables[idx] <= target.
+  let lo = 0;
+  let hi = n;
+  while (lo < hi) {
+    const mid = (lo + hi + 1) >> 1;
+    if (script.cumulativeSyllables[mid] <= target) lo = mid;
+    else hi = mid - 1;
+  }
+  if (lo >= n) return n;
+  const within = target - script.cumulativeSyllables[lo];
+  const sylls = script.tokens[lo].syllables;
+  return lo + (sylls > 0 ? within / sylls : 0);
+}
+
+/** Index of the token containing (or following) a char offset into sourceText. */
+export function wordIndexAtChar(script: NarrationScript, charOffset: number): number {
+  const tokens = script.tokens;
+  if (tokens.length === 0) return 0;
+  let lo = 0;
+  let hi = tokens.length - 1;
+  while (lo < hi) {
+    const mid = (lo + hi) >> 1;
+    if (tokens[mid].charEnd <= charOffset) lo = mid + 1;
+    else hi = mid;
+  }
+  return lo;
+}
+
+/**
+ * Index of the active word at a playback time, given aligned word
+ * timings — the last word whose `tSec` ≤ `tSec` (or 0 before the first).
+ */
+export function wordIndexAtTime(words: WordTiming[], tSec: number): number {
+  if (words.length === 0) return 0;
+  let lo = 0;
+  let hi = words.length - 1;
+  while (lo < hi) {
+    const mid = (lo + hi + 1) >> 1;
+    if (words[mid].tSec <= tSec) lo = mid;
+    else hi = mid - 1;
+  }
+  return words[lo].tSec <= tSec ? lo : 0;
+}

package/src/narration/session.ts

@@ -0,0 +1,100 @@
+/**
+ * Live-session composition: one pure call per PCM hop runs feature
+ * extraction → VAD → nuclei → pacing. This is the only surface the
+ * editor's mic loop needs — feed it worklet batches, read
+ * `state.pacing.wordPos` / `state.vad.speaking` / `state.lastFrame`.
+ */
+
+import { createFeatureState, featureStep, type FeatureState } from './features.js';
+import { createNucleiState, nucleiStep, type NucleiState } from './nuclei.js';
+import { createPacingState, pacingStep, reanchorPacing, type PacingState } from './pacing.js';
+import { createVadState, vadStep, type VadState } from './vad.js';
+import type {
+  FeatureConfig,
+  FrameFeatures,
+  NarrationScript,
+  NucleiConfig,
+  PacingConfig,
+  VadConfig,
+} from './types.js';
+
+export interface NarrationSessionConfig {
+  feature?: Partial<FeatureConfig>;
+  vad?: Partial<VadConfig>;
+  nuclei?: Partial<NucleiConfig>;
+  pacing?: Partial<PacingConfig>;
+}
+
+export interface NarrationSessionState {
+  script: NarrationScript;
+  config: NarrationSessionConfig;
+  features: FeatureState;
+  vad: VadState;
+  nuclei: NucleiState;
+  pacing: PacingState;
+  /** Most recent analysis frame — drives the UI level meter. */
+  lastFrame: FrameFeatures | null;
+  /** Seconds of PCM consumed so far. */
+  tSec: number;
+}
+
+export function createNarrationSession(
+  sampleRate: number,
+  script: NarrationScript,
+  config?: NarrationSessionConfig,
+): NarrationSessionState {
+  const merged = config ?? {};
+  return {
+    script,
+    config: merged,
+    features: createFeatureState(sampleRate, merged.feature),
+    vad: createVadState(merged.vad),
+    nuclei: createNucleiState(merged.nuclei),
+    pacing: createPacingState(0),
+    lastFrame: null,
+    tSec: 0,
+  };
+}
+
+/** Feed one hop of mono PCM; every completed frame advances VAD/nuclei/pacing. */
+export function narrationSessionStep(
+  state: NarrationSessionState,
+  hop: Float32Array,
+): NarrationSessionState {
+  const { state: features, frames } = featureStep(state.features, hop);
+  let vad = state.vad;
+  let nuclei = state.nuclei;
+  let pacing = state.pacing;
+  let lastFrame = state.lastFrame;
+
+  for (const frame of frames) {
+    vad = vadStep(vad, frame, state.config.vad);
+    const nucleiResult = nucleiStep(nuclei, frame, vad.speaking, state.config.nuclei);
+    nuclei = nucleiResult.state;
+    pacing = pacingStep(
+      pacing,
+      { tSec: frame.tSec, speaking: vad.speaking, onsets: nucleiResult.onset !== null ? 1 : 0 },
+      state.script,
+      state.config.pacing,
+    );
+    lastFrame = frame;
+  }
+
+  return {
+    ...state,
+    features,
+    vad,
+    nuclei,
+    pacing,
+    lastFrame,
+    tSec: state.tSec + hop.length / state.features.sampleRate,
+  };
+}
+
+/** Manual nudge/scroll: re-anchor the pacing controller at a word position. */
+export function reanchorSession(
+  state: NarrationSessionState,
+  wordPos: number,
+): NarrationSessionState {
+  return { ...state, pacing: reanchorPacing(state.pacing, wordPos, state.script) };
+}

package/src/narration/sidecar.ts

@@ -0,0 +1,187 @@
+/**
+ * Narration timing sidecar v3 — the extended `<audio>.timing.json`.
+ *
+ * v1 (the recorder's original shape) is `{ sourceText, duration,
+ * bookmarks }` with bookmarks always empty. v3 fills the bookmarks with
+ * real per-word timings from the aligner and adds contiguous per-block
+ * ranges. `version: 2` is already taken by the consolidated root
+ * `timing.json` (`{ version: 2, sections }`), hence v3.
+ *
+ * Compatibility contract (tested in both directions): v3 is a strict
+ * superset of v1, so the legacy `parseTimingJson` gate (requires
+ * `sourceText` + `duration`, ignores unknown keys) keeps accepting v3
+ * files; {@link parseNarrationTimingJson} accepts v1 files and returns
+ * them with empty `blocks`.
+ */
+
+import type { AudioBookmark } from '../schemas/Doc.js';
+import type { NarrationAlignment, NarrationScript } from './types.js';
+
+/** Narration time range of one doc block at record time. */
+export interface NarrationTimingBlock {
+  /** Doc block id at record time (primary match key; ids can drift on heading edits). */
+  blockId?: string;
+  /** Block heading at record time (human-readable + fuzzy match key). */
+  heading?: string;
+  /** Index in renderable-block order at record time. */
+  blockIndex: number;
+  /** Char range into `sourceText` — the durable content key. */
+  charStart: number;
+  charEnd: number;
+  startSec: number;
+  /** Contiguous with the next block's startSec (aligner invariant). */
+  endSec: number;
+}
+
+export interface NarrationTimingJsonV3 {
+  version: 3;
+  /** EXACTLY the NarrationScript.sourceText of the take. */
+  sourceText: string;
+  /** Take length in seconds (decoded-PCM length, not the recorder clock). */
+  duration: number;
+  /** Per-word timings: { id: `word-${i}`, time, charOffset, textFragment }. */
+  bookmarks: AudioBookmark[];
+  blocks: NarrationTimingBlock[];
+  /** Start skew of the companion camera recording, when one exists. */
+  cameraOffsetSec?: number;
+  /** Provenance of the timing data. */
+  generator?: { name: string; method: 'dsp-align'; baseWpm?: number };
+}
+
+export interface BuildNarrationTimingOptions {
+  cameraOffsetSec?: number;
+  baseWpm?: number;
+}
+
+/** Build the v3 sidecar payload from a script + its alignment. Pure. */
+export function buildNarrationTimingJson(
+  script: NarrationScript,
+  alignment: NarrationAlignment,
+  durationSec: number,
+  options?: BuildNarrationTimingOptions,
+): NarrationTimingJsonV3 {
+  const bookmarks: AudioBookmark[] = alignment.words.map((word) => {
+    const token = script.tokens[word.tokenIndex];
+    return {
+      id: `word-${word.tokenIndex}`,
+      time: word.tSec,
+      charOffset: token?.charOffset ?? 0,
+      textFragment: token?.text ?? '',
+    };
+  });
+  const blocks: NarrationTimingBlock[] = alignment.blocks.map((range) => ({
+    ...(range.blockId ? { blockId: range.blockId } : {}),
+    ...(range.heading !== undefined ? { heading: range.heading } : {}),
+    blockIndex: range.blockIndex,
+    charStart: range.charStart,
+    charEnd: range.charEnd,
+    startSec: range.startSec,
+    endSec: range.endSec,
+  }));
+  return {
+    version: 3,
+    sourceText: script.sourceText,
+    duration: Number.isFinite(durationSec) && durationSec >= 0 ? durationSec : 0,
+    bookmarks,
+    blocks,
+    ...(options?.cameraOffsetSec !== undefined ? { cameraOffsetSec: options.cameraOffsetSec } : {}),
+    generator: {
+      name: 'squisq-teleprompter',
+      method: 'dsp-align',
+      ...(options?.baseWpm !== undefined ? { baseWpm: options.baseWpm } : {}),
+    },
+  };
+}
+
+function finiteNonNegative(value: unknown): value is number {
+  return typeof value === 'number' && Number.isFinite(value) && value >= 0;
+}
+
+/**
+ * Tolerant parse: accepts v3, and v1 (`{ sourceText, duration,
+ * bookmarks? }`) which comes back with empty `blocks`. Returns null for
+ * malformed payloads. Blocks are sorted and clamped monotonic
+ * defensively (hand-edited sidecars).
+ */
+export function parseNarrationTimingJson(
+  data: ArrayBuffer | Uint8Array | string,
+): NarrationTimingJsonV3 | null {
+  try {
+    const text =
+      typeof data === 'string'
+        ? data
+        : new TextDecoder().decode(data instanceof Uint8Array ? data : new Uint8Array(data));
+    const parsed: unknown = JSON.parse(text);
+    if (typeof parsed !== 'object' || parsed === null) return null;
+    const raw = parsed as Record<string, unknown>;
+    if (typeof raw.sourceText !== 'string' || !finiteNonNegative(raw.duration)) return null;
+
+    const bookmarks: AudioBookmark[] = Array.isArray(raw.bookmarks)
+      ? (raw.bookmarks as unknown[]).flatMap((b): AudioBookmark[] => {
+          if (typeof b !== 'object' || b === null) return [];
+          const bookmark = b as Record<string, unknown>;
+          if (!finiteNonNegative(bookmark.time) || !finiteNonNegative(bookmark.charOffset)) {
+            return [];
+          }
+          return [
+            {
+              id: typeof bookmark.id === 'string' ? bookmark.id : `bookmark-${bookmark.charOffset}`,
+              time: bookmark.time,
+              charOffset: bookmark.charOffset,
+              ...(typeof bookmark.textFragment === 'string'
+                ? { textFragment: bookmark.textFragment }
+                : {}),
+            },
+          ];
+        })
+      : [];
+
+    let blocks: NarrationTimingBlock[] = Array.isArray(raw.blocks)
+      ? (raw.blocks as unknown[]).flatMap((b): NarrationTimingBlock[] => {
+          if (typeof b !== 'object' || b === null) return [];
+          const block = b as Record<string, unknown>;
+          if (
+            !finiteNonNegative(block.startSec) ||
+            !finiteNonNegative(block.endSec) ||
+            !finiteNonNegative(block.charStart) ||
+            !finiteNonNegative(block.charEnd)
+          ) {
+            return [];
+          }
+          return [
+            {
+              ...(typeof block.blockId === 'string' ? { blockId: block.blockId } : {}),
+              ...(typeof block.heading === 'string' ? { heading: block.heading } : {}),
+              blockIndex: finiteNonNegative(block.blockIndex) ? block.blockIndex : 0,
+              charStart: block.charStart,
+              charEnd: block.charEnd,
+              startSec: block.startSec,
+              endSec: Math.max(block.startSec, block.endSec),
+            },
+          ];
+        })
+      : [];
+
+    blocks = blocks.sort((a, b) => a.startSec - b.startSec);
+    let cursor = 0;
+    for (const block of blocks) {
+      if (block.startSec < cursor) block.startSec = cursor;
+      if (block.endSec < block.startSec) block.endSec = block.startSec;
+      cursor = block.startSec;
+    }
+
+    return {
+      version: 3,
+      sourceText: raw.sourceText,
+      duration: raw.duration,
+      bookmarks,
+      blocks,
+      ...(finiteNonNegative(raw.cameraOffsetSec) ? { cameraOffsetSec: raw.cameraOffsetSec } : {}),
+      ...(typeof raw.generator === 'object' && raw.generator !== null
+        ? { generator: raw.generator as NarrationTimingJsonV3['generator'] }
+        : {}),
+    };
+  } catch {
+    return null;
+  }
+}

package/src/narration/syllables.ts

@@ -0,0 +1,85 @@
+/**
+ * Deterministic English-oriented syllable estimation.
+ *
+ * Approximation limits (accepted by design): ±1 on roughly 15% of
+ * English words; systematically wrong on loanwords ("cafe", "naive"),
+ * some vowel-hiatus words ("create", "quiet"), and non-English text.
+ * Every consumer tolerates per-word error — the pacing controller
+ * smooths rates and anchors on cumulative sums, and the aligner pays
+ * symmetric insert/delete costs — so the estimator only needs to be
+ * unbiased on average. Exact outputs are part of the deterministic
+ * contract (tests pin a corpus table).
+ */
+
+import { estimateSpokenWordCount } from '../timing/narrationTiming.js';
+
+/** Same boundary-punctuation strip as `countSpokenWords`. */
+const BOUNDARY_PUNCT = /^[.,!?;:'"()[\]{}]+|[.,!?;:'"()[\]{}]+$/g;
+
+/** Average syllables per spoken word-equivalent when expanding numbers. */
+const SYLLABLES_PER_SPOKEN_WORD = 1.4;
+
+/**
+ * Estimate the syllable count of a single whitespace-delimited token.
+ * Always ≥ 1 for non-empty tokens.
+ */
+export function estimateSyllables(token: string): number {
+  const stripped = token.replace(BOUNDARY_PUNCT, '');
+  if (!stripped) return 1;
+
+  // Numeric tokens: expand via the spoken-word estimator ("1910" →
+  // "nineteen ten" ≈ 2 spoken words × 1.3 × 1.4 ≈ 4 syllables).
+  if (/^[-+]?[\d.,]+$/.test(stripped)) {
+    const num = parseFloat(stripped.replace(/,/g, ''));
+    if (!Number.isNaN(num) && Number.isFinite(num)) {
+      return Math.max(1, Math.round(estimateSpokenWordCount(stripped) * SYLLABLES_PER_SPOKEN_WORD));
+    }
+  }
+
+  // Vowel-less all-caps runs read as initialisms letter by letter
+  // ("HTML" → aitch-tee-em-el ≈ 4). "NASA" has vowels and falls through.
+  if (/^[A-Z]{2,5}$/.test(stripped) && !/[AEIOUY]/.test(stripped)) {
+    return stripped.length;
+  }
+
+  // Hyphenated/slashed compounds: sum the parts ("beam-splitter" → 3).
+  const parts = stripped
+    .toLowerCase()
+    .split(/[^a-z']+/)
+    .filter((p) => p.length > 0);
+  if (parts.length === 0) return 1;
+  let total = 0;
+  for (const part of parts) {
+    total += countAlphaSyllables(part.replace(/'/g, ''));
+  }
+  return Math.max(1, total);
+}
+
+/** Vowel-group heuristic over a lowercase alphabetic word. */
+function countAlphaSyllables(word: string): number {
+  if (!word) return 0;
+  const groups = word.match(/[aeiouy]+/g);
+  let count = groups ? groups.length : 0;
+  if (count === 0) return 1;
+
+  if (count > 1 && /[^aeiouy]e$/.test(word)) {
+    // Terminal silent e: "table", "whale", "give".
+    count -= 1;
+  }
+  if (count > 1 && /[^aeiouy]ed$/.test(word) && !/[td]ed$/.test(word)) {
+    // Past-tense -ed is silent after most consonants ("walked"),
+    // syllabic after t/d ("wanted", "loaded").
+    count -= 1;
+  }
+  if (count > 1 && /[^aeiouy]es$/.test(word) && !/(?:[sxz]|[cs]h)es$/.test(word)) {
+    // Plural -es is silent after most consonants ("makes"), syllabic
+    // after sibilants ("boxes", "riches").
+    count -= 1;
+  }
+  if (/[^aeiouy]le$/.test(word)) {
+    // Syllabic -le after a consonant: "table", "little" — restores the
+    // syllable the silent-e rule removed. Vowel + "le" ("whale") skips.
+    count += 1;
+  }
+  return Math.max(1, count);
+}

package/src/narration/trace.ts

@@ -0,0 +1,50 @@
+/**
+ * Live prompter trace: sparse `{ tMs, wordPos }` samples the UI records
+ * while the reader records a take (~4 Hz plus one on every re-anchor).
+ * The offline aligner uses it as a prior — a Sakoe-Chiba band around
+ * the trace keeps the DTW honest and cheap.
+ */
+
+export interface TraceSample {
+  tMs: number;
+  wordPos: number;
+}
+
+export interface NarrationTrace {
+  samples: TraceSample[];
+}
+
+/** Clamped linear interpolation of the trace at a time. */
+export function traceWordPosAt(trace: NarrationTrace, tSec: number): number {
+  const samples = trace.samples;
+  if (samples.length === 0) return 0;
+  const tMs = tSec * 1000;
+  if (tMs <= samples[0].tMs) return samples[0].wordPos;
+  const last = samples[samples.length - 1];
+  if (tMs >= last.tMs) return last.wordPos;
+  // Binary search: last sample with tMs <= target.
+  let lo = 0;
+  let hi = samples.length - 1;
+  while (lo < hi) {
+    const mid = (lo + hi + 1) >> 1;
+    if (samples[mid].tMs <= tMs) lo = mid;
+    else hi = mid - 1;
+  }
+  const a = samples[lo];
+  const b = samples[lo + 1];
+  const span = b.tMs - a.tMs;
+  if (span <= 0) return a.wordPos;
+  return a.wordPos + ((tMs - a.tMs) / span) * (b.wordPos - a.wordPos);
+}
+
+/** Downsample to at most `maxSamples`, always keeping both endpoints. */
+export function downsampleTrace(trace: NarrationTrace, maxSamples: number): NarrationTrace {
+  const samples = trace.samples;
+  if (maxSamples < 2 || samples.length <= maxSamples) return { samples: samples.slice() };
+  const out: TraceSample[] = [];
+  const stride = (samples.length - 1) / (maxSamples - 1);
+  for (let i = 0; i < maxSamples; i++) {
+    out.push(samples[Math.round(i * stride)]);
+  }
+  return { samples: out };
+}