@bendyline/squisq 2.1.0 → 2.2.0

package/src/narration/script.ts

@@ -1,239 +0,0 @@
-/**
- * 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

@@ -1,100 +0,0 @@
-/**
- * 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

@@ -1,187 +0,0 @@
-/**
- * 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

@@ -1,85 +0,0 @@
-/**
- * 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

@@ -1,50 +0,0 @@
-/**
- * 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 };
-}