@bendyline/squisq 1.5.2 → 2.0.0

package/src/__tests__/narrationSidecar.test.ts

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

package/src/__tests__/narrationSyllables.test.ts

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

package/src/__tests__/narrationTestSignals.ts

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

package/src/__tests__/narrationVad.test.ts

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

package/src/__tests__/resolveDocTheme.test.ts

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

package/src/__tests__/rootExports.test.ts

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

package/src/__tests__/scopedContentContainer.test.ts

@@ -73,6 +73,26 @@ describe('ScopedContentContainer', () => {
     expect(() => scopeContainer(parent, '/')).toThrow();
     expect(() => scopeContainer(parent, 'a/../b')).toThrow();
     expect(() => scopeContainer(parent, './a')).toThrow();
+    expect(() => scopeContainer(parent, 'a\\b')).toThrow(/forward slashes/);
+  });
+
+  it('rejects traversal, dot segments, and backslashes on every file operation', async () => {
+    const scoped = scopeContainer(parent, 'sidecar');
+    for (const badPath of ['../escape.txt', 'a/../../escape.txt', './same.txt', 'a\\b.txt']) {
+      expect(() => scoped.readFile(badPath)).toThrow();
+      expect(() => scoped.writeFile(badPath, enc('x'))).toThrow();
+      expect(() => scoped.removeFile(badPath)).toThrow();
+      expect(() => scoped.exists(badPath)).toThrow();
+      await expect(scoped.listFiles(badPath)).rejects.toThrow();
+    }
+    expect(await parent.listFiles()).toEqual([]);
+  });
+
+  it('normalizes repeated and leading slashes without changing scope', async () => {
+    const scoped = scopeContainer(parent, '//sidecar//nested//');
+    expect(scoped.prefix).toBe('sidecar/nested');
+    await scoped.writeFile('//assets//x.txt', enc('x'));
+    expect(dec(await parent.readFile('sidecar/nested/assets/x.txt'))).toBe('x');
   });
 
   it('getDocumentPath / readDocument always return null', async () => {

package/src/__tests__/shapeGeometry.test.ts

@@ -69,9 +69,21 @@ describe('connectorPath', () => {
     expect(connectorPath('orthogonal', a, b)).toBe('M 0 0 L 50 0 L 50 50 L 100 50');
   });
 
+  it('orthogonal routing approaches top/bottom ports vertically', () => {
+    expect(
+      connectorPath('orthogonal', { port: 'bottom', x: 80, y: 60 }, { port: 'top', x: 20, y: 140 }),
+    ).toBe('M 80 60 L 80 100 L 20 100 L 20 140');
+  });
+
   it('curved is a cubic bezier', () => {
     expect(connectorPath('curved', a, b).startsWith('M 0 0 C')).toBe(true);
   });
+
+  it('curved routing follows the endpoint port directions', () => {
+    expect(
+      connectorPath('curved', { port: 'bottom', x: 80, y: 60 }, { port: 'top', x: 20, y: 140 }),
+    ).toBe('M 80 60 C 80 110, 20 90, 20 140');
+  });
 });
 
 describe('clipEndpoints', () => {

package/src/__tests__/templateAnnotationParse.test.ts

@@ -11,6 +11,16 @@ function getHeading(md: string) {
 }
 
 describe('Template annotation in Heading parse path', () => {
+  it('extracts and round-trips an empty annotation without leaving literal heading text', () => {
+    const source = '## Getting Started {[]}';
+    const heading = getHeading(source);
+
+    expect(heading.templateAnnotation).toEqual({});
+    expect(heading.children).toHaveLength(1);
+    expect(heading.children[0]).toMatchObject({ type: 'text', value: 'Getting Started' });
+    expect(stringifyMarkdown(parseMarkdown(source)).trim()).toBe(source);
+  });
+
   it('parseMarkdown extracts {[template]} from a heading', () => {
     const md = '## Getting Started {[comparisonBar]}';
     const doc = parseMarkdown(md);

package/src/__tests__/templateInputs.test.ts

@@ -0,0 +1,69 @@
+import { describe, expect, it } from 'vitest';
+import { parseMarkdown } from '../markdown/parse.js';
+import { deriveTemplateInputs } from '../doc/templateInputs.js';
+
+function statInputs(heading: string, body: string): Record<string, unknown> | null {
+  return deriveTemplateInputs('statHighlight', heading, parseMarkdown(body).children);
+}
+
+describe('statHighlight template input derivation', () => {
+  it('uses a leading bold metric as the hero stat', () => {
+    expect(
+      statInputs('The Big Number', '**42%** of teams prefer visual blocks over raw slides.'),
+    ).toEqual({
+      stat: '42%',
+      description: 'of teams prefer visual blocks over raw slides.',
+    });
+  });
+
+  it('accepts an explicitly bold small integer', () => {
+    expect(statInputs('Answer Count', '**42** answers were submitted')).toEqual({
+      stat: '42',
+      description: 'answers were submitted',
+    });
+  });
+
+  it('promotes only the metric when the bold run contains a longer phrase', () => {
+    expect(statInputs('Revenue', '**Revenue grew 42%** year over year')).toEqual({
+      stat: '42%',
+      description: 'Revenue grew year over year',
+    });
+  });
+
+  it('drops an inline separator between the metric and description', () => {
+    expect(
+      statInputs('The Big Number', '**42%** — The percentage of developers who prefer it.'),
+    ).toEqual({
+      stat: '42%',
+      description: 'The percentage of developers who prefer it.',
+    });
+  });
+
+  it('preserves a stat-looking heading for existing documents', () => {
+    expect(statInputs('89%', 'of customers recommend it')).toEqual({
+      stat: '89%',
+      description: 'of customers recommend it',
+    });
+  });
+
+  it('extracts an unformatted body metric for automatic templates', () => {
+    expect(statInputs('Funding', '$2.3M raised')).toEqual({
+      stat: '$2.3M',
+      description: 'raised',
+    });
+  });
+
+  it('does not let a year in a structural heading eclipse the body metric', () => {
+    expect(statInputs('2024 Results', '42% of teams reached their goal')).toEqual({
+      stat: '42%',
+      description: 'of teams reached their goal',
+    });
+  });
+
+  it('retains the historical fallback when no metric can be found', () => {
+    expect(statInputs('A Result', 'Supporting context')).toEqual({
+      stat: 'A Result',
+      description: 'Supporting context',
+    });
+  });
+});

package/src/__tests__/templateMetadata.test.ts

@@ -1,5 +1,6 @@
 import { describe, it, expect } from 'vitest';
-import { templateRegistry, TEMPLATE_METADATA, TEMPLATE_ALIASES } from '../doc/templates/index';
+import { templateRegistry, TEMPLATE_METADATA } from '../doc/templates/index';
+import { TEMPLATE_ALIASES } from '../doc/templates/templateNames';
 
 describe('TEMPLATE_METADATA', () => {
   it('stays exactly 1:1 with templateRegistry (same ids)', () => {