@bendyline/squisq 2.1.0 → 2.2.0

package/src/narration/types.ts

@@ -1,299 +0,0 @@
-/**
- * Shared types + tuning configs for the narration engine.
- *
- * The engine is pure TypeScript with zero dependencies and no DOM/Node
- * APIs: audio arrives as mono `Float32Array` PCM (the editor decodes
- * WebM/MP4 on its side), and every stage is a deterministic step
- * function `(state, input, config) → state` so the whole pipeline is
- * unit-testable in Node with synthetic signals. No `Date.now`, no
- * `Math.random`, no timers anywhere in this module.
- */
-
-/** One word of the teleprompter script, positioned inside {@link NarrationScript.sourceText}. */
-export interface ScriptToken {
-  /** The word as displayed (no surrounding whitespace). */
-  text: string;
-  /** Start offset into {@link NarrationScript.sourceText}. */
-  charOffset: number;
-  /** Exclusive end offset into {@link NarrationScript.sourceText}. */
-  charEnd: number;
-  /** Id of the doc block this word belongs to. */
-  blockId: string;
-  /** Index into {@link NarrationScript.blocks}. */
-  blockIndex: number;
-  /** Estimated syllable count (≥ 1 for spoken tokens; 0 when `spoken` is false). */
-  syllables: number;
-  /** Spoken-word equivalents (numbers count as several words; 0 when not spoken). */
-  spokenWordEquiv: number;
-  /**
-   * Pause class after this token:
-   * 0 none · 1 clause/sentence punctuation · 2 paragraph break · 3 block boundary.
-   */
-  pauseAfter: 0 | 1 | 2 | 3;
-  /**
-   * Whether this token is actually spoken. Standalone punctuation runs —
-   * an em-dash, a lone bullet, `···` — tokenize on whitespace like words
-   * but carry no letters or digits: they DISPLAY in the prompter yet must
-   * never be the highlighted active word, are never paused on, and add no
-   * syllables to the pacing/alignment model.
-   */
-  spoken: boolean;
-}
-
-/** The token/char span of one doc block inside the script. */
-export interface ScriptBlockRange {
-  blockId: string;
-  /** The block's heading text, when present. */
-  heading?: string;
-  /** Inclusive index into {@link NarrationScript.tokens}. */
-  tokenStart: number;
-  /** Exclusive index into {@link NarrationScript.tokens}. */
-  tokenEnd: number;
-  /** Start offset into {@link NarrationScript.sourceText} (includes the spoken title). */
-  charStart: number;
-  /** Exclusive end offset into {@link NarrationScript.sourceText}. */
-  charEnd: number;
-}
-
-/**
- * The teleprompter script derived from a Doc. `sourceText` is canonical:
- * it is stored verbatim in the timing sidecar, and every `charOffset`
- * indexes into it. Building is deterministic — the same Doc always
- * yields a byte-identical script.
- */
-export interface NarrationScript {
-  sourceText: string;
-  tokens: ScriptToken[];
-  blocks: ScriptBlockRange[];
-  totalSyllables: number;
-  /**
-   * Prefix sums: `cumulativeSyllables[i]` = syllables of `tokens[0..i-1]`.
-   * Length is `tokens.length + 1`.
-   */
-  cumulativeSyllables: number[];
-}
-
-/** Per-frame acoustic features extracted from PCM. */
-export interface FrameFeatures {
-  /** Frame CENTER time in seconds from the start of the signal. */
-  tSec: number;
-  /** Full-band root-mean-square of the frame. */
-  rms: number;
-  /** Mean square of the 250–3000 Hz bandpassed frame (speech band energy). */
-  bandEnergy: number;
-  /** Zero crossings / (frameLength − 1), in [0, 1]. */
-  zcr: number;
-}
-
-// ── Configs ──────────────────────────────────────────────────────────
-
-export interface FeatureConfig {
-  /** Analysis frame length in samples (~21 ms @ 48 kHz). */
-  frameSize: number;
-  /** Hop between frame starts in seconds (live 0.02; the aligner uses 0.01). */
-  hopSec: number;
-  /** Bandpass high-pass corner (Hz). */
-  bandLowHz: number;
-  /** Bandpass low-pass corner (Hz). */
-  bandHighHz: number;
-}
-
-export const DEFAULT_FEATURE_CONFIG: FeatureConfig = Object.freeze({
-  frameSize: 1024,
-  hopSec: 0.02,
-  bandLowHz: 250,
-  bandHighHz: 3000,
-});
-
-export interface VadConfig {
-  /** Floor-seeding period before any speech decision (ms). */
-  warmupMs: number;
-  /** Floor attack toward minima (per-frame EMA alpha when energy < floor). */
-  alphaDown: number;
-  /** Floor release (per-frame EMA alpha when energy ≥ floor; frozen while speaking). */
-  alphaUp: number;
-  /** Enter speech when energy > floor × enterRatio for enterFrames frames. */
-  enterRatio: number;
-  /**
-   * Exit hysteresis: sub-exit frames only count once energy < floor ×
-   * exitRatio. The floor is a LOW-percentile tracker, so steady room
-   * noise runs ~1.8–2.3× above it — exitRatio must sit above that band
-   * (and below enterRatio) or silence never registers.
-   */
-  exitRatio: number;
-  /** Consecutive supra-enter frames required to enter speech. */
-  enterFrames: number;
-  /** Sub-exit dwell required to leave speech (ms). */
-  hangoverMs: number;
-  /**
-   * Dip-starved rebaseline: real speech dips below enterRatio × floor
-   * between syllables; a "speech" that stays strongly above the floor
-   * for this long with zero dips is a shifted noise floor — adopt it
-   * and exit. Guards against a step change in room noise wedging the
-   * VAD open forever (the floor is otherwise frozen while speaking).
-   */
-  noiseRebaselineSec: number;
-  /** Absolute floor clamp guarding digital silence. */
-  floorMin: number;
-}
-
-export const DEFAULT_VAD_CONFIG: VadConfig = Object.freeze({
-  warmupMs: 200,
-  alphaDown: 0.3,
-  alphaUp: 0.005,
-  enterRatio: 3.0,
-  exitRatio: 2.5,
-  enterFrames: 2,
-  hangoverMs: 300,
-  noiseRebaselineSec: 1.5,
-  floorMin: 1e-9,
-});
-
-export interface NucleiConfig {
-  /** One-pole low-pass cutoff for the amplitude envelope (Hz). */
-  envelopeHz: number;
-  /** Minimum spacing between accepted syllable onsets (ms) — caps ~8.3 syl/s. */
-  minInterOnsetMs: number;
-  /** Peak must exceed valley-since-last-peak × this ratio. */
-  prominenceRatio: number;
-  /** Peak must exceed the decaying loudness reference × this fraction. */
-  minRelPeak: number;
-  /** Decay time constant of the loudness reference (s). */
-  peakRefTauSec: number;
-}
-
-export const DEFAULT_NUCLEI_CONFIG: NucleiConfig = Object.freeze({
-  // Continuous reading blurs adjacent syllables together: a 10 Hz envelope
-  // over-smooths 5–7 Hz syllable structure and a 1.6× prominence gate
-  // rejects the shallow dips between connected syllables — both cause the
-  // detector to UNDER-count, which makes the prompter lag. A higher
-  // envelope cutoff preserves per-syllable peaks and a gentler prominence
-  // gate accepts them; the min-spacing gate still rejects true doublets.
-  envelopeHz: 16,
-  minInterOnsetMs: 110,
-  prominenceRatio: 1.3,
-  minRelPeak: 0.1,
-  peakRefTauSec: 3.0,
-});
-
-export interface PacingConfig {
-  /** The user's base speaking rate (words per minute). */
-  baseWpm: number;
-  /**
-   * How strongly the detected voice rate steers the cruise velocity vs.
-   * the user's set pace, in [0, 1]. The speaking-cruise velocity is
-   * `voiceBlend·voiceRate + (1 − voiceBlend)·baseRate`, so the WPM slider
-   * is ALWAYS felt (it never fully cancels) and an under-counting detector
-   * can't drag the prompter to a crawl. 1 = pure voice-follow (the old
-   * behavior, where WPM only mattered at the clamps); 0 = ignore the voice.
-   */
-  voiceBlend: number;
-  /** Clamp on the cruise velocity as a fraction of the set pace. */
-  minRateMult: number;
-  maxRateMult: number;
-  /** EMA time constant for the detected syllable rate (s). */
-  rateEmaTauSec: number;
-  /** Velocity slew time constant while speaking (s). */
-  velSlewTauSec: number;
-  /** Velocity decay time constant in silence (s) — halted within ~250 ms. */
-  haltTauSec: number;
-  /** Proportional gain of the forward-only catch-up boost (per syllable behind). */
-  kP: number;
-  /** Integral gain of the forward-only boost (per syllable·second behind). */
-  kI: number;
-  /** Anti-windup clamp on the (≤ 0) behind-error integral (syllable·seconds). */
-  intClamp: number;
-  /** Max fraction the catch-up boost may ADD to the cruise velocity. */
-  maxCorrection: number;
-  /** Window (words ahead) used for the local expected syllables-per-word. */
-  sylWindowWords: number;
-  /** Reader-ahead error beyond this hard-resyncs the prompter FORWARD. */
-  resyncSyllables: number;
-}
-
-export const DEFAULT_PACING_CONFIG: PacingConfig = Object.freeze({
-  baseWpm: 150,
-  voiceBlend: 0.6,
-  minRateMult: 0.5,
-  maxRateMult: 3.0,
-  rateEmaTauSec: 0.7,
-  velSlewTauSec: 0.15,
-  haltTauSec: 0.085,
-  kP: 0.14,
-  kI: 0.02,
-  intClamp: 4,
-  maxCorrection: 0.6,
-  sylWindowWords: 8,
-  resyncSyllables: 8,
-});
-
-export interface AlignConfig {
-  /** Fine analysis hop for the offline pass (s). */
-  hopSec: number;
-  /** Non-speech runs at least this long become GAP events (s). */
-  gapMinSec: number;
-  /** Sakoe-Chiba band half-width around the live-trace prior (s). */
-  bandRadiusSec: number;
-  /** Band half-width when no trace exists (s); also floored at 10% of take length. */
-  bandRadiusNoTraceSec: number;
-  /** Cost weight for |Δt| on syllable↔syllable matches (normalized by band radius). */
-  matchTimeWeight: number;
-  /** Cost of matching an expected pause slot to a detected syllable (reader didn't pause). */
-  pauseToSylCost: number;
-  /** Cost of matching an expected syllable slot to a detected gap (mid-sentence hesitation). */
-  sylToGapCost: number;
-  /** Cost of skipping an expected slot (merged/unspoken syllable). */
-  deleteCost: number;
-  /** Cost of skipping a detected event (filler word, breath, click). */
-  insertCost: number;
-  /** Snap a block start to a silence-gap end within this window before it (s). */
-  blockSnapWindowSec: number;
-  /** Padding after the last speech for the final block's end (s). */
-  tailPadSec: number;
-}
-
-export const DEFAULT_ALIGN_CONFIG: AlignConfig = Object.freeze({
-  hopSec: 0.01,
-  gapMinSec: 0.35,
-  bandRadiusSec: 1.5,
-  bandRadiusNoTraceSec: 3,
-  matchTimeWeight: 1.0,
-  pauseToSylCost: 2.0,
-  sylToGapCost: 1.5,
-  deleteCost: 0.8,
-  insertCost: 0.8,
-  blockSnapWindowSec: 0.8,
-  tailPadSec: 0.4,
-});
-
-// ── Alignment outputs ────────────────────────────────────────────────
-
-/** Refined timestamp of one script token. */
-export interface WordTiming {
-  tokenIndex: number;
-  /** Seconds into the take when the word begins. Monotonically non-decreasing. */
-  tSec: number;
-  /** True when this word had no matched syllable and was interpolated. */
-  interpolated: boolean;
-}
-
-/** Narration time range of one doc block. Ranges are CONTIGUOUS: endSec === next.startSec. */
-export interface NarrationBlockRange {
-  blockId: string;
-  heading?: string;
-  blockIndex: number;
-  charStart: number;
-  charEnd: number;
-  startSec: number;
-  endSec: number;
-}
-
-export interface NarrationAlignment {
-  /** One entry per script token, monotonic in time. */
-  words: WordTiming[];
-  blocks: NarrationBlockRange[];
-  /** Total syllable onsets detected in the take (diagnostics). */
-  detectedSyllables: number;
-  /** Total DTW path cost (diagnostics/QA). */
-  cost: number;
-}

package/src/narration/vad.ts

@@ -1,131 +0,0 @@
-/**
- * Adaptive voice-activity detection over frame features.
- *
- * The noise floor is an asymmetric EMA of band energy that hugs minima
- * (≈ a 5th-percentile tracker): fast attack toward quieter frames, slow
- * release upward, and FROZEN upward while speaking so long speech can't
- * inflate it. Speech enters via a ratio threshold with a
- * consecutive-frame debounce and exits after a continuous sub-exit
- * dwell (hangover) — the hangover also bridges trailing fricatives and
- * inter-word dips. A dip-starved rebaseline escape keeps a step change
- * in room noise from wedging the detector open: real speech dips below
- * the enter threshold between syllables, steady noise never does.
- */
-
-import type { FrameFeatures, VadConfig } from './types.js';
-import { DEFAULT_VAD_CONFIG } from './types.js';
-
-export interface VadState {
-  /** Adaptive noise-floor estimate (band-energy units). */
-  noiseFloor: number;
-  /** The VAD decision — the stage's output. */
-  speaking: boolean;
-  /** Consecutive supra-enter frames observed while silent. */
-  enterStreak: number;
-  /** tSec when the current sub-exit dwell began (while speaking), else null. */
-  subExitSince: number | null;
-  /** tSec when the current zero-dip run began (while speaking), else null. */
-  noDipSince: number | null;
-  /** No speech decisions before this time (floor seeding). */
-  warmupUntilSec: number;
-  /** False until the first frame seeds the floor. */
-  seeded: boolean;
-  lastTSec: number;
-}
-
-export function createVadState(config?: Partial<VadConfig>): VadState {
-  const merged = { ...DEFAULT_VAD_CONFIG, ...config };
-  return {
-    noiseFloor: merged.floorMin,
-    speaking: false,
-    enterStreak: 0,
-    subExitSince: null,
-    noDipSince: null,
-    warmupUntilSec: merged.warmupMs / 1000,
-    seeded: false,
-    lastTSec: 0,
-  };
-}
-
-/** Pure per-frame step. `state.speaking` on the returned state is the decision for this frame. */
-export function vadStep(
-  state: VadState,
-  frame: FrameFeatures,
-  config?: Partial<VadConfig>,
-): VadState {
-  const c = { ...DEFAULT_VAD_CONFIG, ...config };
-  const energy = Math.max(0, frame.bandEnergy);
-
-  let floor = state.seeded ? state.noiseFloor : Math.max(energy, c.floorMin);
-  if (state.seeded) {
-    if (!state.speaking) {
-      const alpha = energy < floor ? c.alphaDown : c.alphaUp;
-      floor += (energy - floor) * alpha;
-    } else if (energy < floor) {
-      // Downward adaptation stays safe while speaking; only upward is frozen.
-      floor += (energy - floor) * c.alphaDown;
-    }
-  }
-  if (floor < c.floorMin) floor = c.floorMin;
-
-  let speaking = state.speaking;
-  let enterStreak = state.enterStreak;
-  let subExitSince = state.subExitSince;
-  let noDipSince = state.noDipSince;
-
-  if (frame.tSec < state.warmupUntilSec) {
-    speaking = false;
-    enterStreak = 0;
-    subExitSince = null;
-    noDipSince = null;
-  } else if (!speaking) {
-    noDipSince = null;
-    if (energy > floor * c.enterRatio) {
-      enterStreak += 1;
-      if (enterStreak >= c.enterFrames) {
-        speaking = true;
-        subExitSince = null;
-        noDipSince = frame.tSec;
-      }
-    } else {
-      enterStreak = 0;
-    }
-  } else {
-    // Hangover: leave speech only after a continuous sub-exit dwell.
-    if (energy >= floor * c.exitRatio) {
-      subExitSince = null;
-    } else {
-      if (subExitSince === null) subExitSince = frame.tSec;
-      if (frame.tSec - subExitSince >= c.hangoverMs / 1000) {
-        speaking = false;
-        subExitSince = null;
-        noDipSince = null;
-        enterStreak = 0;
-      }
-    }
-    // Dip-starved rebaseline: a signal that never dips near the floor
-    // is a new noise floor, not speech.
-    if (speaking) {
-      if (energy <= floor * c.enterRatio) {
-        noDipSince = frame.tSec;
-      } else if (noDipSince !== null && frame.tSec - noDipSince >= c.noiseRebaselineSec) {
-        floor = Math.max(energy, c.floorMin);
-        speaking = false;
-        subExitSince = null;
-        noDipSince = null;
-        enterStreak = 0;
-      }
-    }
-  }
-
-  return {
-    noiseFloor: floor,
-    speaking,
-    enterStreak,
-    subExitSince,
-    noDipSince,
-    warmupUntilSec: state.warmupUntilSec,
-    seeded: true,
-    lastTSec: frame.tSec,
-  };
-}

package/src/ngeohash.d.ts

@@ -1,11 +0,0 @@
-declare module 'ngeohash' {
-  export function encode(latitude: number, longitude: number, precision?: number): string;
-  export function decode(hashstring: string): {
-    latitude: number;
-    longitude: number;
-    error: { latitude: number; longitude: number };
-  };
-  export function neighbors(hashstring: string): string[];
-  export function decode_bbox(hashstring: string): [number, number, number, number];
-  export default { encode, decode, neighbors, decode_bbox };
-}

package/src/random/SeededRandom.ts

@@ -1,127 +0,0 @@
-/**
- * Seeded pseudo-random number generator (Mulberry32 algorithm).
- *
- * Provides deterministic, reproducible randomness from an integer seed.
- * Useful for consistent slideshow generation, shuffling, and selection.
- *
- * ```ts
- * const rng = new SeededRandom(42);
- * rng.next();            // 0.0–1.0
- * rng.nextInt(10);       // 0–9
- * rng.pick(['a', 'b']);  // 'a' or 'b'
- * ```
- */
-export class SeededRandom {
-  private state: number;
-
-  constructor(seed: number) {
-    this.state = seed >>> 0;
-    if (this.state === 0) {
-      this.state = 0xdeadbeef;
-    }
-  }
-
-  /** Random float in [0, 1). */
-  next(): number {
-    let t = (this.state += 0x6d2b79f5);
-    t = Math.imul(t ^ (t >>> 15), t | 1);
-    t ^= t + Math.imul(t ^ (t >>> 7), t | 61);
-    return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
-  }
-
-  /** Random integer in [0, max). */
-  nextInt(max: number): number {
-    return Math.floor(this.next() * max);
-  }
-
-  /** Random integer in [min, max). */
-  nextIntRange(min: number, max: number): number {
-    return min + Math.floor(this.next() * (max - min));
-  }
-
-  /** Random boolean with given probability of `true` (default 0.5). */
-  nextBool(probability: number = 0.5): boolean {
-    return this.next() < probability;
-  }
-
-  /** Pick a random element, or `undefined` if array is empty. */
-  pick<T>(array: T[]): T | undefined {
-    if (array.length === 0) return undefined;
-    return array[this.nextInt(array.length)];
-  }
-
-  /** Pick a random element; throws if empty. */
-  pickRequired<T>(array: T[]): T {
-    if (array.length === 0) {
-      throw new Error('Cannot pick from empty array');
-    }
-    return array[this.nextInt(array.length)];
-  }
-
-  /** Pick `count` unique random elements (fewer if array is smaller). */
-  pickMultiple<T>(array: T[], count: number): T[] {
-    if (count >= array.length) {
-      return this.shuffle([...array]);
-    }
-    const result: T[] = [];
-    const available = [...array];
-    for (let i = 0; i < count && available.length > 0; i++) {
-      const index = this.nextInt(available.length);
-      result.push(available[index]);
-      available.splice(index, 1);
-    }
-    return result;
-  }
-
-  /** Fisher-Yates shuffle **in place**. Returns the same array. */
-  shuffle<T>(array: T[]): T[] {
-    for (let i = array.length - 1; i > 0; i--) {
-      const j = this.nextInt(i + 1);
-      [array[i], array[j]] = [array[j], array[i]];
-    }
-    return array;
-  }
-
-  /** Return a **new** shuffled copy. */
-  shuffled<T>(array: readonly T[]): T[] {
-    return this.shuffle([...array]);
-  }
-
-  /** Weighted random selection. Returns `undefined` if items is empty. */
-  pickWeighted<T>(items: { item: T; weight: number }[]): T | undefined {
-    if (items.length === 0) return undefined;
-
-    const totalWeight = items.reduce((sum, { weight }) => sum + weight, 0);
-    if (totalWeight <= 0) return items[0]?.item;
-
-    let random = this.next() * totalWeight;
-    for (const { item, weight } of items) {
-      random -= weight;
-      if (random <= 0) return item;
-    }
-    return items[items.length - 1]?.item;
-  }
-
-  /** Current internal state (for debugging / serialization). */
-  getState(): number {
-    return this.state;
-  }
-
-  /** Create an independent sub-stream keyed by a modifier. */
-  derive(modifier: string | number): SeededRandom {
-    const hash = typeof modifier === 'string' ? hashString(modifier) : modifier >>> 0;
-    return new SeededRandom(this.state ^ hash);
-  }
-}
-
-/**
- * Simple string → 32-bit hash (djb2 algorithm).
- * Useful for turning a document ID into a numeric seed.
- */
-export function hashString(str: string): number {
-  let hash = 5381;
-  for (let i = 0; i < str.length; i++) {
-    hash = ((hash << 5) + hash) ^ str.charCodeAt(i);
-  }
-  return hash >>> 0;
-}

package/src/random/index.ts

@@ -1 +0,0 @@
-export { SeededRandom, hashString } from './SeededRandom.js';

package/src/recommend/index.ts

@@ -1,16 +0,0 @@
-/**
- * Template recommendations for the editor's block template picker.
- *
- * @example
- * ```ts
- * import { parseMarkdown } from '@bendyline/squisq/markdown';
- * import { profileBlockContents, recommendTemplatesForBlock } from '@bendyline/squisq/recommend';
- *
- * const doc = parseMarkdown(blockBodySource);
- * const profile = profileBlockContents(doc.children);
- * const { recommended, rest } = recommendTemplatesForBlock(profile, ALL_TEMPLATE_NAMES);
- * ```
- */
-
-export type { BlockContentProfile, RecommendationResult } from './templates.js';
-export { profileBlockContents, recommendTemplatesForBlock } from './templates.js';

package/src/recommend/numberHighlight.ts

@@ -1,25 +0,0 @@
-/**
- * Matches a prominent number suitable for a Stat Highlight block. Qualifies
- * on currency prefixes, common unit suffixes, and standalone large numbers.
- * Plain small numbers (`42`) intentionally do not qualify.
- */
-const NUMBER_HIGHLIGHT_RE =
-  /(?:[$€£¥]\s?\d+(?:[.,]\d+)*(?:\s?(?:[MBK]|million|billion|thousand))?|\d+(?:[.,]\d+)*\s?(?:%|‰|x|×|[MBK]|million|billion|thousand|percent|years?|days?|hours?)|\d{3,}(?:[.,]\d+)*)/i;
-
-/** A prominent number found inside a short stat-like string. */
-export interface NumberHighlightMatch {
-  value: string;
-  index: number;
-  end: number;
-}
-
-/** Find the prominent number phrase inside a string, if one exists. */
-export function matchNumberHighlight(text: string): NumberHighlightMatch | null {
-  const match = NUMBER_HIGHLIGHT_RE.exec(text);
-  if (!match || match.index === undefined) return null;
-  return {
-    value: match[0],
-    index: match.index,
-    end: match.index + match[0].length,
-  };
-}