videoclaw 3.0.0-alpha.1

package/src/video/motion-overlay/flow-pack.ts

@@ -0,0 +1,223 @@
+/**
+ * Flow hand-off pack + restitch — the productised "manual Omni" loop.
+ *
+ * The source skill's real pipeline is: *write prompts → upload each take + paste
+ * its prompt into Google Flow (Omni) by hand → download → stitch*. The Omni step
+ * was never automated (the skill marks it "under construction") and Flow's current
+ * web UI does not accept video uploads through the API or the Agent editor — so the
+ * hand-off stays manual. This module turns that manual loop into first-class
+ * artifacts instead of throwaway shell scripts:
+ *
+ *  - `emitFlowPack(plan, outDir)` — write a drop-in folder: each take's clip + a
+ *    clean, ready-to-paste prompt `.txt` (the prompt body extracted from the
+ *    `prompts/take-NN.md` the planner already wrote) + a README of the workflow.
+ *  - `restitchFlowOutputs(plan, flowOutDir, outputPath)` — once the operator drops
+ *    the animated takes back, re-mux each with its ORIGINAL audio (CRITICAL RULE 1)
+ *    and concatenate into the finished reel.
+ *
+ * Pure builders (prompt extraction, README, output pairing, concat args) are
+ * unit-tested; the fs copy + ffmpeg runs are injectable seams, so the whole module
+ * is exercised offline with no ffmpeg.
+ */
+import { mkdir, copyFile as fsCopyFile, writeFile as fsWriteFile, readFile as fsReadFile, readdir } from 'node:fs/promises';
+import { basename, join } from 'node:path';
+import { buildAudioRestoreArgs } from './execute.js';
+import type { MotionOverlayPlan, MotionTake } from './types.js';
+
+/** Pure: pull the prompt body out of a `prompts/take-NN.md` — the text between the
+ * first pair of ``` fences (the ready-to-paste Omni prompt). Falls back to the
+ * whole doc if no fence is present. */
+export function extractPromptBlock(md: string): string {
+  const m = md.match(/```[^\n]*\n([\s\S]*?)\n```/);
+  return (m ? m[1] : md).trim();
+}
+
+/** One pack entry: a take's clip + its prompt file (basenames, inside the pack). */
+export interface FlowPackEntry {
+  index: number;
+  clip: string;
+  prompt: string;
+  span: string;
+}
+
+/** Pure: the README walking the operator through the Flow web hand-off. */
+export function flowPackReadme(args: { entries: FlowPackEntry[]; style: string; layout: string }): string {
+  const rows = args.entries
+    .map((e) => `| \`${e.clip}\` | \`${e.prompt}\` | ${e.span} |`)
+    .join('\n');
+  return `# Flow hand-off pack
+
+Google Flow's API blocks the V2V "add overlays to my video" edit, and its web
+editor won't accept a video upload — so the Omni step is **manual** (exactly how the
+source skill's author does it). The prompts are already written; you upload + paste.
+
+Style: **${args.style}** · Layout: **${args.layout}**
+
+## Takes (one prompt per ≤10s clip)
+
+| Clip to upload | Prompt to paste | Span |
+|---|---|---|
+${rows}
+
+## Steps (per take)
+1. Open Google Flow and **upload** \`take-NN.mp4\`.
+2. **Paste** the entire contents of \`take-NN.txt\` as the prompt.
+3. Generate → **download** the result into a \`done/\` folder here, keeping the
+   take order (e.g. \`done/take-01_out.mp4\`).
+
+The prompt preserves your original audio and renders only the quoted on-screen text.
+
+## Then restitch
+\`\`\`
+vclaw video motion-overlay --output-dir <this work dir> --restitch <path to done/>
+\`\`\`
+That re-muxes each animated take with its **original audio** and concatenates the
+finished reel (\`motion-overlay-reel.mp4\`).
+`;
+}
+
+/** Injectable fs seam for the pack writer (tests pass fakes). */
+export interface EmitFlowPackDeps {
+  copyFile?: (src: string, dst: string) => Promise<void>;
+  readFile?: (p: string) => Promise<string>;
+  writeFile?: (p: string, data: string) => Promise<void>;
+}
+
+export interface FlowPackResult {
+  packDir: string;
+  entries: FlowPackEntry[];
+}
+
+/**
+ * Emit the hand-off pack into `outDir`: copy each take clip, write its prompt as a
+ * clean `.txt`, and a README. Reads the take + prompt files the planner already
+ * wrote under `plan.workdir`. Pure control flow over injectable fs.
+ */
+export async function emitFlowPack(
+  plan: MotionOverlayPlan,
+  outDir: string,
+  deps: EmitFlowPackDeps = {},
+): Promise<FlowPackResult> {
+  const copyFile = deps.copyFile ?? fsCopyFile;
+  const readFile = deps.readFile ?? ((p: string) => fsReadFile(p, 'utf-8'));
+  const writeFile = deps.writeFile ?? ((p: string, d: string) => fsWriteFile(p, d, 'utf-8'));
+  await mkdir(outDir, { recursive: true });
+
+  const ordered = [...plan.takes].sort((a, b) => a.index - b.index);
+  const entries: FlowPackEntry[] = [];
+  for (const take of ordered) {
+    const clipName = basename(take.file);
+    const stem = clipName.replace(/\.mp4$/i, '');
+    const promptName = `${stem}.txt`;
+    await copyFile(join(plan.workdir, take.file), join(outDir, clipName));
+    const md = await readFile(join(plan.workdir, take.promptFile));
+    await writeFile(join(outDir, promptName), extractPromptBlock(md));
+    entries.push({ index: take.index, clip: clipName, prompt: promptName, span: `${fmtT(take.start)}–${fmtT(take.end)}s` });
+  }
+  await writeFile(join(outDir, 'README.md'), flowPackReadme({ entries, style: plan.style, layout: plan.layout }));
+  return { packDir: outDir, entries };
+}
+
+function fmtT(s: number): string {
+  return Number.isInteger(s) ? String(s) : s.toFixed(1);
+}
+
+/**
+ * Pure: pair each take (in order) with its returned animated clip. Prefers a file
+ * whose name contains the take's `take-0N` token; otherwise falls back to sorted
+ * positional order. Returns `null` for a take with no matching output.
+ */
+export function pairFlowOutputs(takes: MotionTake[], files: string[]): Array<{ take: MotionTake; file: string | null }> {
+  const ordered = [...takes].sort((a, b) => a.index - b.index);
+  const sortedFiles = [...files].sort();
+  const used = new Set<string>();
+  const result = ordered.map((take) => {
+    const token = `take-${String(take.index + 1).padStart(2, '0')}`;
+    const hit = sortedFiles.find((f) => !used.has(f) && basename(f).toLowerCase().includes(token));
+    if (hit) used.add(hit);
+    return { take, file: hit ?? null };
+  });
+  // Second pass: fill any unmatched take from the remaining files in sorted order.
+  const remaining = sortedFiles.filter((f) => !used.has(f));
+  let r = 0;
+  for (const entry of result) {
+    if (!entry.file && r < remaining.length) {
+      entry.file = remaining[r++];
+    }
+  }
+  return result;
+}
+
+/**
+ * Pure: ffmpeg concat-filter args joining N restored clips into one reel (re-encode;
+ * robust across heterogeneous inputs). `-y` is prepended by the runner.
+ */
+export function buildConcatArgs(clips: string[], outputPath: string): string[] {
+  const inputs = clips.flatMap((c) => ['-i', c]);
+  const refs = clips.map((_, i) => `[${i}:v][${i}:a]`).join('');
+  const filter = `${refs}concat=n=${clips.length}:v=1:a=1[v][a]`;
+  return [
+    ...inputs,
+    '-filter_complex',
+    filter,
+    '-map',
+    '[v]',
+    '-map',
+    '[a]',
+    '-c:v',
+    'libx264',
+    '-crf',
+    '18',
+    '-preset',
+    'fast',
+    '-pix_fmt',
+    'yuv420p',
+    '-c:a',
+    'aac',
+    '-b:a',
+    '192k',
+    '-movflags',
+    '+faststart',
+    outputPath,
+  ];
+}
+
+/** Injectable ffmpeg seam for restitch. */
+export type FfmpegRunner = (args: string[]) => Promise<void>;
+
+export interface RestitchResult {
+  outputPath: string;
+  takeCount: number;
+  restored: string[];
+}
+
+/**
+ * Restitch: for each take, re-mux the operator's downloaded animated clip with the
+ * take's ORIGINAL audio (`buildAudioRestoreArgs`), then concat into the final reel.
+ * Throws if a take has no matching animated output.
+ */
+export async function restitchFlowOutputs(
+  plan: MotionOverlayPlan,
+  flowOutDir: string,
+  outputPath: string,
+  deps: { ffmpeg: FfmpegRunner; listDir?: (d: string) => Promise<string[]> },
+): Promise<RestitchResult> {
+  const listDir = deps.listDir ?? (async (d: string) => (await readdir(d)).filter((n) => n.endsWith('.mp4')).map((n) => join(d, n)));
+  const files = await listDir(flowOutDir);
+  const pairs = pairFlowOutputs(plan.takes, files);
+  const missing = pairs.filter((p) => !p.file).map((p) => p.take.index + 1);
+  if (missing.length) {
+    throw new Error(`restitch: no animated output found for take(s) ${missing.join(', ')} in ${flowOutDir}`);
+  }
+  const restoredDir = join(plan.workdir, 'restored');
+  await mkdir(restoredDir, { recursive: true });
+  const restored: string[] = [];
+  for (const { take, file } of pairs) {
+    const out = join(restoredDir, basename(take.file));
+    await deps.ffmpeg(buildAudioRestoreArgs(file as string, join(plan.workdir, take.file), out));
+    restored.push(out);
+  }
+  await mkdir(join(outputPath, '..'), { recursive: true }).catch(() => {});
+  await deps.ffmpeg(buildConcatArgs(restored, outputPath));
+  return { outputPath, takeCount: restored.length, restored };
+}

package/src/video/motion-overlay/ingest.ts

@@ -0,0 +1,210 @@
+/**
+ * FFmpeg ingest for motion-overlay.
+ *
+ * Thin side-effecting helpers over ffmpeg/ffprobe that the plan/execute layers
+ * call to break an input video into the pieces the composer needs:
+ *  - `probeVideo`        — duration (s) + width/height + derived aspect label.
+ *  - `extractAudio`      — pull the audio track to a standalone file.
+ *  - `cutTake`           — frame-accurate `-ss/-to` cut, re-encoded CRF18.
+ *  - `extractFrames`     — sample reference frames for `readFrameObservations`.
+ *  - `readFrameObservations` — heuristic + notes stub from the sampled frames.
+ *
+ * Every ffmpeg/ffprobe call routes through an injectable `IngestDeps` so tests
+ * run fully offline (no ffmpeg required) by supplying fakes. The defaults wrap
+ * the proven `assemble/ffmpeg.ts` spawn primitives + a small ffprobe shell-out.
+ */
+
+import { spawn } from 'node:child_process';
+import { ffprobeDuration, resolveFfprobeBin, runFfmpeg } from '../assemble/ffmpeg.js';
+import type { FrameObservations } from './types.js';
+
+export interface VideoProbe {
+  durationSeconds: number;
+  width: number;
+  height: number;
+  /** "16:9" | "9:16" | "1:1" | "<w>:<h>" reduced label. */
+  aspect: string;
+}
+
+/** Run an ffmpeg arg array. Mirrors `runFfmpeg`'s shape (returns a command). */
+export type RunFfmpegFn = (args: string[]) => Promise<{ command: string }>;
+/** Probe a video → duration/width/height. */
+export type ProbeFn = (path: string) => Promise<{ durationSeconds: number; width: number; height: number }>;
+
+export interface IngestDeps {
+  /** Real ffmpeg by default; injected fake in tests. */
+  runFfmpeg?: RunFfmpegFn;
+  /** Real ffprobe by default; injected fake in tests. */
+  probe?: ProbeFn;
+}
+
+/** Reduce a width:height pair to a tidy aspect label. */
+export function aspectLabel(width: number, height: number): string {
+  if (width <= 0 || height <= 0) return `${width}:${height}`;
+  const g = gcd(width, height);
+  const w = width / g;
+  const h = height / g;
+  // Snap the common 16:9 / 9:16 / 1:1 families even when the source is slightly
+  // off (e.g. 1080x1920 reduces cleanly, but 1080x1916 should still read 9:16).
+  const ratio = width / height;
+  if (Math.abs(ratio - 16 / 9) < 0.02) return '16:9';
+  if (Math.abs(ratio - 9 / 16) < 0.02) return '9:16';
+  if (Math.abs(ratio - 1) < 0.02) return '1:1';
+  return `${w}:${h}`;
+}
+
+function gcd(a: number, b: number): number {
+  let x = Math.abs(a);
+  let y = Math.abs(b);
+  while (y) {
+    [x, y] = [y, x % y];
+  }
+  return x || 1;
+}
+
+/** Default ffprobe-backed probe: duration (s) + the first video stream's w/h. */
+const defaultProbe: ProbeFn = async (path: string) => {
+  const durationMs = await ffprobeDuration(path);
+  const { width, height } = await probeDimensions(path);
+  return { durationSeconds: durationMs / 1000, width, height };
+};
+
+/** Default ffmpeg runner: the real spawn path from assemble/ffmpeg.ts. */
+const defaultRunFfmpeg: RunFfmpegFn = async (args: string[]) => {
+  const { command } = await runFfmpeg(args);
+  return { command };
+};
+
+/** ffprobe the first video stream's pixel dimensions. */
+function probeDimensions(path: string): Promise<{ width: number; height: number }> {
+  const bin = resolveFfprobeBin();
+  const args = [
+    '-v',
+    'error',
+    '-select_streams',
+    'v:0',
+    '-show_entries',
+    'stream=width,height',
+    '-of',
+    'csv=s=x:p=0',
+    path,
+  ];
+  return new Promise((resolve, reject) => {
+    const child = spawn(bin, args, { stdio: ['ignore', 'pipe', 'pipe'] });
+    let stdout = '';
+    let stderr = '';
+    child.stdout?.on('data', (c: Buffer) => {
+      stdout += c.toString();
+    });
+    child.stderr?.on('data', (c: Buffer) => {
+      stderr += c.toString();
+    });
+    child.on('error', (err) => reject(new Error(`Failed to spawn ffprobe: ${err.message}`)));
+    child.on('close', (code) => {
+      if (code !== 0) {
+        reject(new Error(`ffprobe exited ${code}: ${stderr.trim().slice(0, 300)}`));
+        return;
+      }
+      const match = stdout.trim().split('\n')[0]?.match(/^(\d+)x(\d+)$/);
+      if (!match) {
+        reject(new Error(`ffprobe returned unparseable dimensions: ${JSON.stringify(stdout.trim())}`));
+        return;
+      }
+      resolve({ width: Number(match[1]), height: Number(match[2]) });
+    });
+  });
+}
+
+/** Probe a video for duration + dimensions + aspect label. */
+export async function probeVideo(path: string, deps: IngestDeps = {}): Promise<VideoProbe> {
+  const probe = deps.probe ?? defaultProbe;
+  const { durationSeconds, width, height } = await probe(path);
+  return { durationSeconds, width, height, aspect: aspectLabel(width, height) };
+}
+
+/** Extract the input's audio track to `outPath` (copy codec, no re-encode). */
+export async function extractAudio(inputPath: string, outPath: string, deps: IngestDeps = {}): Promise<{ command: string }> {
+  const run = deps.runFfmpeg ?? defaultRunFfmpeg;
+  // -vn drops video; copy the audio stream as-is for fidelity (CRITICAL RULE 1).
+  return run(['-i', inputPath, '-vn', '-c:a', 'copy', outPath]);
+}
+
+/**
+ * Cut a take frame-accurately from `inputPath` between `start` and `end`
+ * (absolute seconds), re-encoding so the cut is exact (not keyframe-snapped).
+ * Matches the design spec: `-ss/-to -c:v libx264 -crf 18 -preset fast -c:a aac`.
+ */
+export async function cutTake(
+  inputPath: string,
+  start: number,
+  end: number,
+  outPath: string,
+  deps: IngestDeps = {},
+): Promise<{ command: string }> {
+  const run = deps.runFfmpeg ?? defaultRunFfmpeg;
+  return run([
+    '-i',
+    inputPath,
+    '-ss',
+    String(start),
+    '-to',
+    String(end),
+    '-c:v',
+    'libx264',
+    '-crf',
+    '18',
+    '-preset',
+    'fast',
+    '-c:a',
+    'aac',
+    outPath,
+  ]);
+}
+
+/**
+ * Sample `count` reference frames evenly across `[0, durationSeconds)` to
+ * `<outDir>/frame_%02d.jpg`. Returns the relative-ish filenames produced (the
+ * caller owns the dir). One ffmpeg call using the `fps` filter.
+ */
+export async function extractFrames(
+  inputPath: string,
+  outDir: string,
+  durationSeconds: number,
+  count: number,
+  deps: IngestDeps = {},
+): Promise<string[]> {
+  const run = deps.runFfmpeg ?? defaultRunFfmpeg;
+  const n = Math.max(1, Math.floor(count));
+  // Sample at count/duration fps so we land ~n frames across the clip.
+  const fps = durationSeconds > 0 ? n / durationSeconds : 1;
+  const pattern = `${outDir}/frame_%02d.jpg`;
+  await run(['-i', inputPath, '-vf', `fps=${fps.toFixed(6)}`, '-frames:v', String(n), pattern]);
+  const names: string[] = [];
+  for (let i = 1; i <= n; i++) {
+    names.push(`frame_${String(i).padStart(2, '0')}.jpg`);
+  }
+  return names;
+}
+
+/**
+ * Derive `FrameObservations` from the sampled frames + the probe aspect.
+ *
+ * v1 is a deterministic heuristic stub: a portrait (9:16) talking-head is
+ * assumed centred; a landscape source is assumed to have the speaker on one
+ * side. It records a note about the untouchable region so the composer's GLOBAL
+ * RULES carry it through. Pure given its inputs — no image decoding (that is a
+ * later enhancement) — so it stays offline-testable.
+ */
+export function readFrameObservations(probe: { aspect: string }, frameFiles: string[]): FrameObservations {
+  const notes: string[] = [];
+  notes.push(`Reference frames sampled: ${frameFiles.length}.`);
+  let speakerSide: FrameObservations['speakerSide'];
+  if (probe.aspect === '9:16' || probe.aspect === '1:1') {
+    speakerSide = 'center';
+    notes.push('Vertical/square source: assume the speaker is centred; keep the central region untouched.');
+  } else {
+    speakerSide = 'left';
+    notes.push('Landscape source: assume the speaker occupies one side; keep that region untouched.');
+  }
+  return { speakerSide, notes };
+}

package/src/video/motion-overlay/motifs.ts

@@ -0,0 +1,223 @@
+/**
+ * Concept → visual motif layer (the source skill's "visualize what's being said").
+ *
+ * Scans the transcript and, at the moment a concept is spoken, surfaces a matching
+ * **hairline icon** (money → `$`, team → people, launch → rocket, …) or an
+ * **infographic stat callout** (a number/percentage with a ring gauge). These are
+ * full-frame SVG overlays composited in the upper area by the local renderer, the
+ * same way the giant anchor headlines are — free, no provider, no moderation.
+ *
+ * Everything here is pure + deterministic and unit-tested. Icons are simple stroked
+ * geometry (no portraits, no bitmaps) so `sharp`/resvg renders them reliably.
+ */
+
+/** A detected motif and the window it pulses on. */
+export interface MotifMoment {
+  kind: 'icon' | 'stat';
+  /** icon id (kind === 'icon'). */
+  iconId?: string;
+  /** display number, e.g. "40" or "3" (kind === 'stat'). */
+  value?: string;
+  /** unit suffix, e.g. "%" (kind === 'stat'). */
+  unit?: string;
+  /** ring-gauge fill 0..1 (percentages; kind === 'stat'). */
+  gauge?: number;
+  /** small caption under the motif (a short concept tag). */
+  label?: string;
+  start: number;
+  end: number;
+}
+
+/** Spelled-number → value (covers the common reel vocabulary). */
+const NUMBER_WORDS: Record<string, number> = {
+  one: 1, two: 2, three: 3, four: 4, five: 5, six: 6, seven: 7, eight: 8, nine: 9, ten: 10,
+  eleven: 11, twelve: 12, thirteen: 13, fourteen: 14, fifteen: 15, sixteen: 16, seventeen: 17,
+  eighteen: 18, nineteen: 19, twenty: 20, thirty: 30, forty: 40, fifty: 50, sixty: 60,
+  seventy: 70, eighty: 80, ninety: 90, hundred: 100, thousand: 1000, million: 1000000,
+};
+
+/**
+ * Concept keyword → icon. Ordered by priority (first match wins per segment). Each
+ * entry: [matcher, iconId, short tag label]. Stems are matched word-wise.
+ */
+const CONCEPT_ICONS: Array<{ re: RegExp; icon: string; label: string }> = [
+  { re: /\b(revenue|sales?|profit|money|dollars?|earn(ed|ings)?|paid|pricing|price|income)\b/i, icon: 'dollar', label: 'REVENUE' },
+  { re: /\b(budget|cost|costs|spend|spent|cheap|expensive|free)\b/i, icon: 'wallet', label: 'COST' },
+  { re: /\b(grow(th|s|n)?|grew|jump(ed)?|rise|rising|rose|increase[ds]?|scal(e|ing|ed)|surg(e|ed)|boom(ed)?)\b/i, icon: 'trend', label: 'GROWTH' },
+  { re: /\b(team|teams|people|audience|users?|customers?|community|everyone|hire[ds]?|crew)\b/i, icon: 'people', label: 'PEOPLE' },
+  { re: /\b(ai|a\.i\.|agents?|bots?|robots?|model(s)?|intelligence|neural|automation|automate[ds]?)\b/i, icon: 'nodes', label: 'AI' },
+  { re: /\b(build|built|building|ship(ped|s)?|launch(ed|es)?|create[ds]?|made|make|produc(e|ed|tion))\b/i, icon: 'rocket', label: 'BUILD' },
+  { re: /\b(time|days?|weeks?|months?|years?|hours?|minutes?|fast|quick(ly)?|now|today|instant(ly)?)\b/i, icon: 'clock', label: 'TIME' },
+  { re: /\b(world|global(ly)?|everywhere|planet|earth|international|worldwide)\b/i, icon: 'globe', label: 'GLOBAL' },
+  { re: /\b(video|videos|watch(ing|ed)?|reel|reels|content|stream(ing)?|clip)\b/i, icon: 'play', label: 'VIDEO' },
+  { re: /\b(energy|power(ful)?|force|impact|strong|surge|boost|electric)\b/i, icon: 'bolt', label: 'POWER' },
+  { re: /\b(idea|ideas|think(ing)?|learn(ing|ed)?|knowledge|insight|smart|discover(y|ed)?)\b/i, icon: 'bulb', label: 'IDEA' },
+  { re: /\b(goal|goals|target|campaign|mission|aim|focus|win(ning)?)\b/i, icon: 'target', label: 'GOAL' },
+  { re: /\b(data|stats?|metrics?|numbers?|chart|analytics|results?|performance)\b/i, icon: 'bars', label: 'DATA' },
+  { re: /\b(secret|hidden|unknown|reveal(ed|s)?|behind|beneath|surface)\b/i, icon: 'eye', label: 'REVEAL' },
+  { re: /\b(ocean|sea|water|wave|waves|tide|deep)\b/i, icon: 'wave', label: 'OCEAN' },
+];
+
+/** Parse a number value from a token (digit or spelled word). Pure. */
+function numberFromToken(tok: string): number | undefined {
+  const bare = tok.toLowerCase().replace(/[^a-z0-9]/g, '');
+  if (/^\d+$/.test(bare)) return Number(bare);
+  if (bare in NUMBER_WORDS) return NUMBER_WORDS[bare];
+  return undefined;
+}
+
+/**
+ * Detect the strongest motif per segment — a numeric **stat** (preferred when a
+ * number is present) or a concept **icon**. Returns at most `max` moments (one per
+ * segment), each pulsed on a short window at the spoken moment, so the reel doesn't
+ * clutter. Pure & deterministic.
+ */
+export function detectMotifs(
+  segments: Array<{ start: number; end: number; text: string }>,
+  max = 5,
+): MotifMoment[] {
+  const out: MotifMoment[] = [];
+  for (const seg of segments) {
+    if (out.length >= max) break;
+    const tokens = seg.text.split(/\s+/);
+    let motif: MotifMoment | undefined;
+
+    // 1. Stat: the first number token (+ a trailing percent/unit).
+    for (let i = 0; i < tokens.length; i++) {
+      const n = numberFromToken(tokens[i]);
+      if (n === undefined) continue;
+      const next = (tokens[i + 1] ?? '').toLowerCase().replace(/[^a-z%]/g, '');
+      const isPct = next === 'percent' || tokens[i].includes('%');
+      motif = {
+        kind: 'stat',
+        value: String(n),
+        ...(isPct ? { unit: '%', gauge: Math.max(0, Math.min(1, n / 100)) } : {}),
+        start: seg.start + 0.15,
+        end: Math.min(seg.end, seg.start + 1.8),
+      };
+      break;
+    }
+
+    // 2. Else a concept icon.
+    if (!motif) {
+      const hit = CONCEPT_ICONS.find((c) => c.re.test(seg.text));
+      if (hit) {
+        motif = {
+          kind: 'icon',
+          iconId: hit.icon,
+          label: hit.label,
+          start: seg.start + 0.15,
+          end: Math.min(seg.end, seg.start + 1.8),
+        };
+      }
+    }
+    if (motif) out.push(motif);
+  }
+  return out;
+}
+
+/** Inner stroked geometry for each icon, drawn in a 0..100 box. Pure. */
+function iconGeometry(iconId: string, color: string): string {
+  const s = `stroke="${color}" stroke-width="6" fill="none" stroke-linecap="round" stroke-linejoin="round"`;
+  switch (iconId) {
+    case 'trend':
+      return `<polyline points="8,72 38,46 58,60 92,22" ${s}/><polyline points="74,22 92,22 92,40" ${s}/>`;
+    case 'bars':
+      return `<rect x="14" y="58" width="16" height="30" ${s}/><rect x="42" y="40" width="16" height="48" ${s}/><rect x="70" y="22" width="16" height="66" ${s}/>`;
+    case 'dollar':
+      return `<circle cx="50" cy="50" r="40" ${s}/><path d="M62 34 C62 28 56 24 50 24 C42 24 38 30 38 36 C38 50 64 46 64 62 C64 70 58 76 50 76 C42 76 36 72 36 64" ${s}/><line x1="50" y1="18" x2="50" y2="82" ${s}/>`;
+    case 'wallet':
+      return `<rect x="14" y="28" width="72" height="48" rx="8" ${s}/><path d="M64 46 h26 v12 h-26 a6 6 0 0 1 0-12 z" ${s}/>`;
+    case 'people':
+      return `<circle cx="36" cy="34" r="14" ${s}/><path d="M14 80 C14 62 26 54 36 54 C46 54 58 62 58 80" ${s}/><circle cx="70" cy="40" r="11" ${s}/><path d="M62 56 C72 56 86 62 86 80" ${s}/>`;
+    case 'nodes':
+      return `<circle cx="24" cy="30" r="9" ${s}/><circle cx="78" cy="26" r="9" ${s}/><circle cx="50" cy="68" r="9" ${s}/><circle cx="20" cy="74" r="8" ${s}/><line x1="31" y1="34" x2="71" y2="29" ${s}/><line x1="29" y1="36" x2="46" y2="61" ${s}/><line x1="74" y1="33" x2="55" y2="61" ${s}/><line x1="27" y1="71" x2="43" y2="69" ${s}/>`;
+    case 'rocket':
+      return `<path d="M50 12 C66 24 70 44 64 66 H36 C30 44 34 24 50 12 z" ${s}/><circle cx="50" cy="40" r="8" ${s}/><path d="M36 60 L22 74 L34 70 M64 60 L78 74 L66 70" ${s}/><path d="M44 66 L44 82 M56 66 L56 82" ${s}/>`;
+    case 'clock':
+      return `<circle cx="50" cy="50" r="40" ${s}/><line x1="50" y1="50" x2="50" y2="26" ${s}/><line x1="50" y1="50" x2="68" y2="58" ${s}/>`;
+    case 'globe':
+      return `<circle cx="50" cy="50" r="40" ${s}/><ellipse cx="50" cy="50" rx="18" ry="40" ${s}/><line x1="10" y1="50" x2="90" y2="50" ${s}/><line x1="16" y1="30" x2="84" y2="30" ${s}/><line x1="16" y1="70" x2="84" y2="70" ${s}/>`;
+    case 'play':
+      return `<rect x="14" y="22" width="72" height="56" rx="12" ${s}/><path d="M44 40 L62 50 L44 60 z" stroke="${color}" stroke-width="6" fill="${color}" stroke-linejoin="round"/>`;
+    case 'bolt':
+      return `<path d="M56 10 L26 56 H48 L42 90 L76 40 H52 z" stroke="${color}" stroke-width="6" fill="none" stroke-linejoin="round"/>`;
+    case 'bulb':
+      return `<path d="M50 16 C66 16 78 28 78 44 C78 56 70 62 64 70 H36 C30 62 22 56 22 44 C22 28 34 16 50 16 z" ${s}/><line x1="38" y1="80" x2="62" y2="80" ${s}/><line x1="42" y1="90" x2="58" y2="90" ${s}/>`;
+    case 'target':
+      return `<circle cx="50" cy="50" r="38" ${s}/><circle cx="50" cy="50" r="22" ${s}/><circle cx="50" cy="50" r="6" stroke="${color}" stroke-width="6" fill="${color}"/>`;
+    case 'eye':
+      return `<path d="M10 50 C26 26 74 26 90 50 C74 74 26 74 10 50 z" ${s}/><circle cx="50" cy="50" r="14" ${s}/>`;
+    case 'wave':
+      return `<path d="M8 44 C20 30 28 30 40 44 C52 58 60 58 72 44 C80 35 86 35 92 40" ${s}/><path d="M8 64 C20 50 28 50 40 64 C52 78 60 78 72 64 C80 55 86 55 92 60" ${s}/>`;
+    default:
+      return `<circle cx="50" cy="50" r="38" ${s}/>`;
+  }
+}
+
+/**
+ * Full-frame SVG for an **icon motif** — a hairline concept icon in the accent
+ * colour, centred in the upper third, with a small uppercase concept tag beneath.
+ * Pure & deterministic.
+ */
+export function iconMotifSvg(
+  motif: MotifMoment,
+  dims: { width: number; height: number },
+  opts: { accent: string; labelFamily: string },
+): string {
+  const { width: W, height: H } = dims;
+  const box = Math.round(Math.min(W, H) * 0.14);
+  // Upper-right "stat bug" position — clears a centred talking-head / avatar face.
+  const cx = Math.round(W * 0.82);
+  const cy = Math.round(H * 0.22);
+  const x0 = cx - box / 2;
+  const y0 = cy - box / 2;
+  const label = (motif.label ?? '').toUpperCase();
+  const labelSvg = label
+    ? `<text x="${cx}" y="${cy + box / 2 + 40}" text-anchor="middle" font-family="${opts.labelFamily}" font-size="26" fill="${opts.accent}" letter-spacing="3">${esc(label)}</text>`
+    : '';
+  return `<svg xmlns="http://www.w3.org/2000/svg" width="${W}" height="${H}">
+  <g transform="translate(${x0},${y0}) scale(${box / 100})">${iconGeometry(motif.iconId ?? '', opts.accent)}</g>
+  ${labelSvg}
+</svg>`;
+}
+
+/**
+ * Full-frame SVG for a **stat callout** — a big accent number (+ optional unit) with
+ * a ring gauge for percentages, centred in the upper third. Pure & deterministic.
+ */
+export function statMotifSvg(
+  motif: MotifMoment,
+  dims: { width: number; height: number },
+  opts: { accent: string; numberFamily: string },
+): string {
+  const { width: W, height: H } = dims;
+  // Upper-right "stat bug" position — clears a centred talking-head / avatar face.
+  const cx = Math.round(W * 0.82);
+  const cy = Math.round(H * 0.22);
+  const hasGauge = motif.gauge !== undefined;
+  const r = Math.round(Math.min(W, H) * 0.095);
+  const value = `${motif.value ?? ''}${motif.unit ?? ''}`;
+  // Plain numbers read bigger (no ring competing); percentages sit inside the ring.
+  const fontSize = hasGauge ? Math.round(r * 0.86) : Math.round(Math.min(W, H) * 0.1);
+  let deco = '';
+  if (hasGauge) {
+    const circ = 2 * Math.PI * r;
+    const fill = circ * Math.max(0, Math.min(1, motif.gauge as number));
+    deco = `<circle cx="${cx}" cy="${cy}" r="${r}" fill="none" stroke="rgba(255,255,255,0.18)" stroke-width="10"/>
+  <circle cx="${cx}" cy="${cy}" r="${r}" fill="none" stroke="${opts.accent}" stroke-width="10" stroke-linecap="round" stroke-dasharray="${fill.toFixed(1)} ${circ.toFixed(1)}" transform="rotate(-90 ${cx} ${cy})"/>`;
+  } else {
+    // A thin accent underline turns a lone number into an infographic beat.
+    const half = Math.round(fontSize * 0.42);
+    deco = `<rect x="${cx - half}" y="${cy + fontSize * 0.34}" width="${half * 2}" height="6" rx="3" fill="${opts.accent}"/>`;
+  }
+  return `<svg xmlns="http://www.w3.org/2000/svg" width="${W}" height="${H}">
+  ${deco}
+  <text x="${cx}" y="${cy + fontSize / 3}" text-anchor="middle" font-family="${opts.numberFamily}" font-size="${fontSize}" font-weight="800" fill="${opts.accent}">${esc(value)}</text>
+</svg>`;
+}
+
+/** Local XML escaper (kept independent of render-local to avoid a cycle). */
+function esc(t: string): string {
+  return t.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;').replace(/'/g, '&apos;');
+}