videoclaw 3.0.0-alpha.1

package/src/video/motion-overlay/render-local.ts

@@ -0,0 +1,441 @@
+/**
+ * Native local overlay renderer (no provider spend, no moderation).
+ *
+ * Renders each transcript segment as a broadcast lower-third — an SVG rasterised
+ * to PNG via `sharp` (resvg text shaping; NO system freetype / ffmpeg `drawtext`
+ * needed) — then composites the cards onto the source clip with a single ffmpeg
+ * `overlay` filtergraph (each card fades + slides up on its segment window). The
+ * original audio is preserved.
+ *
+ * This is the reliable production path for motion-graphics overlays: the Google
+ * Flow omni-flash V2V "add-overlay" edit is moderation-blocked for most inputs
+ * (FINISH_REASON_INPUT_VIDEO_EDIT), whereas this runs fully locally.
+ *
+ * The pure pieces (SVG builder, filtergraph builder, accent-word splitter) are
+ * unit-tested; the sharp rasterise + the ffmpeg run are injectable side effects.
+ */
+import sharp from 'sharp';
+import { mkdir, writeFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { iconMotifSvg, statMotifSvg, type MotifMoment } from './motifs.js';
+
+/** One caption: the spoken text and its absolute window in the source clip. */
+export interface LocalCaption {
+  text: string;
+  start: number;
+  end: number;
+}
+
+/**
+ * The three card looks, ported from the source skill's style catalog so
+ * `--render local --style X` actually changes the rendered overlay (previously
+ * only the V2V *prompt* varied by style; the local card was fixed).
+ *  - `apple-clean`    — rounded dark frosted glass, clean sans-serif sentence case.
+ *  - `editorial-dark` — squared solid-black poster panel, bold condensed UPPERCASE.
+ *  - `knowledge-tool` — soft cool-dark card, editorial serif, calm lavender accent.
+ */
+export type CardVariant = 'apple-clean' | 'editorial-dark' | 'knowledge-tool';
+
+interface VariantSpec {
+  /** Panel geometry: floating inset card · full-bleed bar · left-anchored card. */
+  layout: 'inset' | 'fullbleed' | 'left';
+  panelFill: string;
+  panelRx: number;
+  stroke: string;
+  fontFamily: string;
+  /** Font for the kicker/label row (mono for the knowledge `[[ ]]` look). */
+  labelFamily: string;
+  fontWeight: number;
+  uppercase: boolean;
+  letterSpacing: number;
+  textFill: string;
+  /** Headline (giant anchor word) font family for this variant. */
+  headlineFamily: string;
+  /** Accent treatment: a vertical bar at the panel's left, or a full-width top rule. */
+  accentRule: 'left-bar' | 'top-rule';
+  accentRuleSize: number;
+  /** Kicker style: accent dot · solid accent tag block · `[[ MONO ]]` brackets. */
+  label: 'dot' | 'tag' | 'brackets';
+}
+
+// Three structurally distinct looks faithful to the source skill's catalog:
+//  - apple-clean    — a floating inset rounded frosted card, thin left accent bar,
+//                     accent dot + uppercase kicker, sans-serif sentence case.
+//  - editorial-dark — a FULL-BLEED edge-to-edge near-black poster bar, thick accent
+//                     TOP rule, a solid accent tag block label, bold condensed CAPS.
+//  - knowledge-tool — a LEFT-anchored narrower cool-dark study card, thick lavender
+//                     left rule, a `[[ MONO ]]` bracket label, editorial serif body.
+const VARIANTS: Record<CardVariant, VariantSpec> = {
+  'apple-clean': {
+    layout: 'inset',
+    panelFill: 'rgba(14,14,18,0.86)',
+    panelRx: 22,
+    stroke: 'rgba(255,255,255,0.15)',
+    fontFamily: 'Helvetica Neue, Helvetica, Arial, sans-serif',
+    labelFamily: 'Helvetica Neue, Helvetica, Arial, sans-serif',
+    fontWeight: 600,
+    uppercase: false,
+    letterSpacing: 0,
+    textFill: '#ffffff',
+    headlineFamily: 'Helvetica Neue, Helvetica, Arial, sans-serif',
+    accentRule: 'left-bar',
+    accentRuleSize: 8,
+    label: 'dot',
+  },
+  'editorial-dark': {
+    layout: 'fullbleed',
+    panelFill: 'rgba(0,0,0,0.94)',
+    panelRx: 0,
+    stroke: '',
+    fontFamily: 'Arial Narrow, Helvetica Neue, Arial, sans-serif',
+    labelFamily: 'Arial Narrow, Helvetica, Arial, sans-serif',
+    fontWeight: 800,
+    uppercase: true,
+    letterSpacing: 1,
+    textFill: '#ffffff',
+    headlineFamily: 'Arial Narrow, Helvetica Neue, Arial, sans-serif',
+    accentRule: 'top-rule',
+    accentRuleSize: 10,
+    label: 'tag',
+  },
+  'knowledge-tool': {
+    layout: 'left',
+    panelFill: 'rgba(19,19,24,0.93)',
+    panelRx: 12,
+    stroke: 'rgba(167,139,250,0.28)',
+    fontFamily: 'Georgia, Times New Roman, serif',
+    labelFamily: 'Menlo, Consolas, monospace',
+    fontWeight: 500,
+    uppercase: false,
+    letterSpacing: 0,
+    textFill: '#e9e6f4',
+    headlineFamily: 'Georgia, Times New Roman, serif',
+    accentRule: 'left-bar',
+    accentRuleSize: 12,
+    label: 'brackets',
+  },
+};
+
+/** Resolve a variant id (defaults to apple-clean — the original card look). */
+function variantSpec(v: CardVariant | undefined): VariantSpec {
+  return VARIANTS[v ?? 'apple-clean'];
+}
+
+/** Visual config for the lower-third (accent hex + small kicker label + style). */
+export interface LocalRenderStyle {
+  accent: string;
+  /** Optional small kicker label above the caption (e.g. a brand). Omitted when blank. */
+  kicker?: string;
+  /** Lowercased words that get the accent colour (e.g. brand/anchor words). */
+  accentWords?: string[];
+  /** Which card look to render (default `apple-clean`). */
+  variant?: CardVariant;
+  /**
+   * Word-by-word reveal: only the first N words of the caption are visible; the rest
+   * render transparent (so the panel keeps its full size — no per-frame reflow). The
+   * animated renderer drives this with `revealWordCount(t)`. Omitted → all words.
+   */
+  visibleWords?: number;
+}
+
+/** Escape the five XML entities so arbitrary transcript text is SVG-safe. Pure. */
+export function xmlEscape(text: string): string {
+  return text
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&apos;');
+}
+
+/**
+ * Word-wrap `text` to at most `maxChars` per line (greedy by words). Pure — used
+ * to size the panel and lay out tspans.
+ */
+export function wrapWords(text: string, maxChars: number): string[] {
+  const words = text.trim().split(/\s+/).filter(Boolean);
+  const lines: string[] = [];
+  let line = '';
+  for (const w of words) {
+    if (line && line.length + 1 + w.length > maxChars) {
+      lines.push(line);
+      line = w;
+    } else {
+      line = line ? `${line} ${w}` : w;
+    }
+  }
+  if (line) lines.push(line);
+  return lines.length ? lines : [''];
+}
+
+/**
+ * Render a wrapped line as `<tspan>`s. Accent words render in the accent colour AND
+ * (per the source skill) get a small accent **asterisk** beat-marker after them.
+ * Pure.
+ */
+function lineTspans(
+  line: string,
+  accent: string,
+  baseFill: string,
+  accentWords: Set<string>,
+  reveal?: { counter: { n: number }; visible: number },
+): string {
+  return line
+    .split(/(\s+)/)
+    .map((tok) => {
+      if (/^\s+$/.test(tok)) return xmlEscape(tok);
+      // Word-by-word reveal: words past the visible count render transparent (they
+      // still occupy space so the panel does not reflow frame to frame).
+      let hidden = false;
+      if (reveal) {
+        reveal.counter.n += 1;
+        hidden = reveal.counter.n > reveal.visible;
+      }
+      // fill-opacity (not opacity) — resvg/sharp reliably honours it on <tspan>.
+      const op = hidden ? ' fill-opacity="0"' : '';
+      const bare = tok.toLowerCase().replace(/[^a-z0-9]/g, '');
+      if (accentWords.has(bare)) {
+        return `<tspan fill="${accent}"${op}>${xmlEscape(tok)}</tspan><tspan fill="${accent}" font-size="0.7em"${op}>*</tspan>`;
+      }
+      return `<tspan fill="${baseFill}"${op}>${xmlEscape(tok)}</tspan>`;
+    })
+    .join('');
+}
+
+/**
+ * Build the lower-third SVG for one caption. Pure & deterministic. `style.variant`
+ * selects a **structurally distinct** card per the source skill's catalog — a
+ * floating inset frosted card (apple-clean), a full-bleed near-black poster bar with
+ * an accent top rule and a solid accent tag (editorial-dark), or a left-anchored cool
+ * study card with a `[[ MONO ]]` bracket label and serif body (knowledge-tool).
+ */
+export function lowerThirdSvg(
+  caption: Pick<LocalCaption, 'text'>,
+  dims: { width: number; height: number },
+  style: LocalRenderStyle,
+): string {
+  const { width: W, height: H } = dims;
+  const spec = variantSpec(style.variant);
+  const accent = style.accent;
+  const accentWords = new Set((style.accentWords ?? []).map((w) => w.toLowerCase().replace(/[^a-z0-9]/g, '')));
+
+  // Layout geometry differs per variant — this is the main structural distinction.
+  const px = spec.layout === 'fullbleed' ? 0 : 36;
+  const panelW = spec.layout === 'fullbleed' ? W : spec.layout === 'left' ? Math.round(W * 0.62) : W - 72;
+  const padX = 44;
+  const tx = px + padX;
+  const topPad = spec.accentRule === 'top-rule' ? spec.accentRuleSize : 0;
+
+  // Smaller, less shouty lower-third text (a bit tighter than the original 46px) —
+  // the smaller font also fits more characters per line, so captions wrap less.
+  const fontSize = 38;
+  const maxChars = Math.max(12, Math.floor((panelW - padX - 56) / 20));
+  const raw = caption.text.replace(/\s+$/, '');
+  const text = spec.uppercase ? raw.toUpperCase() : raw;
+  const lines = wrapWords(text, maxChars);
+  const lineH = fontSize + 14;
+  const labelH = 42;
+  const panelH = topPad + 30 + labelH + lines.length * lineH + 22;
+  const py = H - panelH - 70;
+  const labelBaseline = py + topPad + 40;
+  const textTop = labelBaseline + 50;
+  const lsAttr = spec.letterSpacing ? ` letter-spacing="${spec.letterSpacing}"` : '';
+  // Word-by-word reveal: a shared counter walks every word across all lines.
+  const reveal = style.visibleWords !== undefined ? { counter: { n: 0 }, visible: style.visibleWords } : undefined;
+  const tspanLines = lines
+    .map((l, i) => `<tspan x="${tx}" dy="${i === 0 ? 0 : lineH}">${lineTspans(l, accent, spec.textFill, accentWords, reveal)}</tspan>`)
+    .join('');
+
+  const accentRuleSvg =
+    spec.accentRule === 'top-rule'
+      ? `<rect x="${px}" y="${py}" width="${panelW}" height="${spec.accentRuleSize}" fill="${accent}"/>`
+      : `<rect x="${px + 18}" y="${py + 20}" width="${spec.accentRuleSize}" height="${panelH - 40}" rx="${spec.panelRx ? 4 : 0}" fill="${accent}"/>`;
+
+  const kicker = (style.kicker ?? '').trim().toUpperCase();
+  let labelSvg = '';
+  if (kicker) {
+    if (spec.label === 'tag') {
+      const tagW = 24 + kicker.length * 14;
+      labelSvg = `<rect x="${tx}" y="${labelBaseline - 26}" width="${tagW}" height="34" fill="${accent}"/>
+  <text x="${tx + 12}" y="${labelBaseline - 1}" font-family="${spec.labelFamily}" font-size="22" font-weight="800" fill="#000000" letter-spacing="1.5">${xmlEscape(kicker)}</text>`;
+    } else if (spec.label === 'brackets') {
+      labelSvg = `<text x="${tx}" y="${labelBaseline}" font-family="${spec.labelFamily}" font-size="21" fill="${accent}" letter-spacing="1">${xmlEscape(`[[ ${kicker} ]]`)}</text>`;
+    } else {
+      labelSvg = `<circle cx="${tx + 7}" cy="${labelBaseline - 7}" r="7" fill="${accent}"/>
+  <text x="${tx + 24}" y="${labelBaseline}" font-family="${spec.labelFamily}" font-size="22" fill="rgba(255,255,255,0.7)" letter-spacing="1.6">${xmlEscape(kicker)}</text>`;
+    }
+  }
+
+  const strokeSvg = spec.stroke
+    ? `<rect x="${px}" y="${py}" width="${panelW}" height="${panelH}" rx="${spec.panelRx}" fill="none" stroke="${spec.stroke}" stroke-width="2"/>`
+    : '';
+
+  return `<svg xmlns="http://www.w3.org/2000/svg" width="${W}" height="${H}">
+  <rect x="${px}" y="${py}" width="${panelW}" height="${panelH}" rx="${spec.panelRx}" fill="${spec.panelFill}"/>
+  ${strokeSvg}
+  ${accentRuleSvg}
+  ${labelSvg}
+  <text y="${textTop}" font-family="${spec.fontFamily}" font-size="${fontSize}" font-weight="${spec.fontWeight}" fill="${spec.textFill}"${lsAttr}>${tspanLines}</text>
+</svg>`;
+}
+
+/**
+ * Build the giant **anchor-headline** SVG — a single dominant keyword centred in
+ * the upper-middle of the frame, with the accent asterisk beat-marker after it
+ * (the source skill's signature kinetic-typography moment). Pure & deterministic.
+ */
+export function anchorHeadlineSvg(
+  word: string,
+  dims: { width: number; height: number },
+  style: LocalRenderStyle,
+): string {
+  const { width: W, height: H } = dims;
+  const spec = variantSpec(style.variant);
+  const raw = word.trim();
+  const text = spec.uppercase || (style.variant ?? 'apple-clean') !== 'knowledge-tool' ? raw.toUpperCase() : raw;
+  // Size to fit the frame width (rough advance ~0.6em per glyph), capped.
+  const fitted = Math.floor((W * 0.92) / Math.max(1, text.length) / 0.6);
+  const fontSize = Math.max(64, Math.min(Math.floor(W * 0.2), fitted));
+  const cy = Math.floor(H * 0.42);
+  return `<svg xmlns="http://www.w3.org/2000/svg" width="${W}" height="${H}">
+  <text x="${W / 2}" y="${cy}" text-anchor="middle" font-family="${spec.headlineFamily}" font-size="${fontSize}" font-weight="${Math.max(spec.fontWeight, 700)}" fill="${spec.textFill}" letter-spacing="${spec.letterSpacing}">${xmlEscape(text)}<tspan fill="${style.accent}" font-size="${Math.floor(fontSize * 0.7)}" dy="${-Math.floor(fontSize * 0.18)}">*</tspan></text>
+</svg>`;
+}
+
+/** Rasterise a lower-third SVG to a PNG buffer via sharp. Side effect (sharp). */
+export async function rasteriseCaption(svg: string): Promise<Buffer> {
+  return sharp(Buffer.from(svg)).png().toBuffer();
+}
+
+/**
+ * Build the ffmpeg `-filter_complex` graph compositing N pre-rendered full-frame
+ * card PNGs (inputs 1..N; input 0 is the source video) onto the source — each
+ * card fades in/out and slides up 36px on entrance over its [start,end] window.
+ * Pure (string only).
+ */
+export function buildLocalFiltergraph(cards: Array<{ start: number; end: number }>): string {
+  if (cards.length === 0) return '[0:v]null[vout]';
+  const parts: string[] = [];
+  let last = '[0:v]';
+  cards.forEach((c, i) => {
+    const start = c.start;
+    const end = Math.max(c.end, start + 1.0);
+    parts.push(
+      `[${i + 1}:v]format=rgba,fade=t=in:st=${start.toFixed(2)}:d=0.30:alpha=1,` +
+        `fade=t=out:st=${(end - 0.3).toFixed(2)}:d=0.30:alpha=1[c${i}]`,
+    );
+    const out = i === cards.length - 1 ? '[vout]' : `[v${i}]`;
+    const yExpr = `'if(lt(t,${(start + 0.35).toFixed(2)}), 36*(1-(t-${start.toFixed(2)})/0.35), 0)'`;
+    parts.push(`${last}[c${i}]overlay=x=0:y=${yExpr}:enable='between(t,${start.toFixed(2)},${end.toFixed(2)})'${out}`);
+    last = `[v${i}]`;
+  });
+  return parts.join(';');
+}
+
+/**
+ * Build the ffmpeg argv for the overlay composite. Pure — the source is input 0,
+ * each card PNG is a looped image input, the graph maps [vout] + the source audio.
+ */
+export function buildLocalRenderArgs(
+  sourceVideo: string,
+  cardPngPaths: string[],
+  filtergraph: string,
+  outputPath: string,
+): string[] {
+  const args = ['-y', '-i', sourceVideo];
+  for (const p of cardPngPaths) args.push('-loop', '1', '-i', p);
+  args.push(
+    '-filter_complex',
+    filtergraph,
+    '-map',
+    '[vout]',
+    '-map',
+    '0:a?',
+    '-c:v',
+    'libx264',
+    '-crf',
+    '18',
+    '-preset',
+    'fast',
+    '-pix_fmt',
+    'yuv420p',
+    '-c:a',
+    'aac',
+    '-b:a',
+    '192k',
+    '-movflags',
+    '+faststart',
+    '-shortest',
+    outputPath,
+  );
+  return args;
+}
+
+/** Runs ffmpeg with the given argv. Injectable so the orchestrator tests offline. */
+export type FfmpegRunner = (args: string[]) => Promise<void>;
+
+export interface RenderLocalDeps {
+  ffmpeg: FfmpegRunner;
+  /** Override the rasteriser (tests). Defaults to the live sharp path. */
+  rasterise?: (svg: string) => Promise<Buffer>;
+}
+
+/** A giant anchor-headline moment: the word + the short window it pulses on. */
+export interface HeadlineMoment {
+  word: string;
+  start: number;
+  end: number;
+}
+
+export interface RenderLocalOptions {
+  sourceVideo: string;
+  captions: LocalCaption[];
+  dims: { width: number; height: number };
+  style: LocalRenderStyle;
+  /** Optional giant anchor-headline overlays, composited above the lower-thirds. */
+  headlines?: HeadlineMoment[];
+  /** Optional concept icons / stat callouts, composited in the upper third. */
+  motifs?: MotifMoment[];
+  /** Dir for the intermediate card PNGs. */
+  cardDir: string;
+  outputPath: string;
+}
+
+/** Resolve a motif into its full-frame SVG using the active style. Pure. */
+export function motifSvg(m: MotifMoment, dims: { width: number; height: number }, style: LocalRenderStyle): string {
+  const spec = variantSpec(style.variant);
+  return m.kind === 'stat'
+    ? statMotifSvg(m, dims, { accent: style.accent, numberFamily: spec.headlineFamily })
+    : iconMotifSvg(m, dims, { accent: style.accent, labelFamily: spec.labelFamily });
+}
+
+/**
+ * Render the local overlay reel: rasterise one lower-third per caption (plus any
+ * giant anchor-headline moments), then composite all elements onto the source with
+ * the fade/slide filtergraph, sorted by start time. Returns the list of card PNG
+ * paths written (for provenance / tests).
+ */
+export async function renderLocalOverlay(opts: RenderLocalOptions, deps: RenderLocalDeps): Promise<string[]> {
+  const rasterise = deps.rasterise ?? rasteriseCaption;
+  await mkdir(opts.cardDir, { recursive: true });
+  await mkdir(dirname(opts.outputPath), { recursive: true });
+
+  // Build a unified, start-sorted element list: lower-thirds + headline pulses +
+  // concept icon / stat motifs (the "visualize what's being said" layer).
+  const elements: Array<{ svg: string; start: number; end: number }> = [
+    ...opts.captions.map((c) => ({ svg: lowerThirdSvg(c, opts.dims, opts.style), start: c.start, end: c.end })),
+    ...(opts.headlines ?? []).map((h) => ({ svg: anchorHeadlineSvg(h.word, opts.dims, opts.style), start: h.start, end: h.end })),
+    ...(opts.motifs ?? []).map((m) => ({ svg: motifSvg(m, opts.dims, opts.style), start: m.start, end: m.end })),
+  ].sort((a, b) => a.start - b.start);
+
+  const cardPaths: string[] = [];
+  for (let i = 0; i < elements.length; i++) {
+    const png = await rasterise(elements[i].svg);
+    const p = join(opts.cardDir, `card-${String(i).padStart(2, '0')}.png`);
+    await writeFile(p, png);
+    cardPaths.push(p);
+  }
+  const filtergraph = buildLocalFiltergraph(elements.map((e) => ({ start: e.start, end: e.end })));
+  await deps.ffmpeg(buildLocalRenderArgs(opts.sourceVideo, cardPaths, filtergraph, opts.outputPath));
+  return cardPaths;
+}

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

@@ -0,0 +1,217 @@
+/**
+ * Motion-overlay plan orchestrator (Phase 2).
+ *
+ * `planMotionOverlay` is the dry/plan front door wired into `vclaw video
+ * motion-overlay`. It runs the full plan pipeline:
+ *   ingest.probeVideo → extractAudio → transcribe (or --transcript) → slice →
+ *   ingest.cutTake per take → extractFrames → readFrameObservations →
+ *   analyze-reel → compose-prompt per take → plan → write work folder.
+ *
+ * Every side effect (ffmpeg, ffprobe, Gemini STT) is injected via `deps`, so the
+ * whole orchestrator runs offline in tests with fakes. NO provider spend happens
+ * here — this is the plan/dry path; execution (V2V) lands in Phase 4.
+ */
+
+import { join } from 'node:path';
+import { copyFile, mkdir, writeFile } from 'node:fs/promises';
+import { analyzeTake } from './analyze-reel.js';
+import { composePrompt } from './compose-prompt.js';
+import {
+  cutTake,
+  extractAudio,
+  extractFrames,
+  probeVideo,
+  readFrameObservations,
+  type IngestDeps,
+} from './ingest.js';
+import { buildMotionOverlayPlan, takeStem } from './plan.js';
+import { resolveStyle } from './motion-style.js';
+import { planSplits } from './slice.js';
+import { loadTranscript, transcribeAudio, type TranscribeDeps } from './transcribe.js';
+import { writeMotionOverlayReview } from './preview.js';
+import { writeWorkFolder } from './write.js';
+import type { MotionLayout, MotionOverlayPlan, MotionStyleId, Transcript } from './types.js';
+
+/** Human-readable language label for the on-screen-text GLOBAL RULE. */
+const LANGUAGE_NAMES: Record<string, string> = {
+  en: 'English',
+  pt: 'Portuguese',
+  es: 'Spanish',
+  fr: 'French',
+  de: 'German',
+  it: 'Italian',
+  hi: 'Hindi',
+  ja: 'Japanese',
+  zh: 'Chinese',
+};
+
+/** Map a BCP-47 code (or "auto") to a human language label for the prompt. */
+export function languageLabel(code: string): string {
+  const key = code.trim().toLowerCase();
+  if (!key || key === 'auto') return 'the spoken language';
+  return LANGUAGE_NAMES[key] ?? code.trim();
+}
+
+export interface PlanMotionOverlayArgs {
+  /** Absolute path to the input video. */
+  input: string;
+  /** Absolute work-folder path to emit into. */
+  workdir: string;
+  layout: MotionLayout;
+  style: MotionStyleId;
+  /** Requested STT language ("auto" lets Gemini detect). */
+  lang: string;
+  /** Omni hard per-clip limit (seconds). */
+  maxTakeSeconds: number;
+  /** Optional accent override (hex or name). */
+  accent?: string;
+  /** Optional brand-derived accent (wins over --accent). */
+  brandAccent?: string;
+  /** Optional bring-your-own transcript path (skips STT). */
+  transcriptPath?: string;
+  /** Number of reference frames to sample (default 3). */
+  frameCount?: number;
+  /** Emit the `review/review.html` approval surface alongside the plan. */
+  preview?: boolean;
+  /** Deterministic timestamp for the manifest (tests). */
+  generatedAt?: string;
+}
+
+export interface PlanMotionOverlayDeps extends IngestDeps, TranscribeDeps {}
+
+export interface PlanMotionOverlayResult {
+  plan: MotionOverlayPlan;
+  manifestPath: string;
+  readmePath: string;
+  promptPaths: string[];
+  /** Path to `review/review.html` when `preview` was requested, else undefined. */
+  reviewPath?: string;
+}
+
+/**
+ * Run the full plan pipeline and emit the work folder. Returns the assembled
+ * plan + the paths written. Pure orchestration over injected side effects.
+ */
+export async function planMotionOverlay(
+  args: PlanMotionOverlayArgs,
+  deps: PlanMotionOverlayDeps = {},
+): Promise<PlanMotionOverlayResult> {
+  const ingestDeps: IngestDeps = {
+    ...(deps.runFfmpeg ? { runFfmpeg: deps.runFfmpeg } : {}),
+    ...(deps.probe ? { probe: deps.probe } : {}),
+  };
+  const transcribeDeps: TranscribeDeps = {
+    ...(deps.transcriber ? { transcriber: deps.transcriber } : {}),
+    ...(deps.fetcher ? { fetcher: deps.fetcher } : {}),
+    ...(deps.endpoint ? { endpoint: deps.endpoint } : {}),
+  };
+
+  // 0. Create the work-folder subdirs up front so ingest can write into them
+  //    (the README/manifest are emitted by writeWorkFolder at the end).
+  await Promise.all([
+    mkdir(join(args.workdir, 'source'), { recursive: true }),
+    mkdir(join(args.workdir, 'takes'), { recursive: true }),
+    mkdir(join(args.workdir, 'frames'), { recursive: true }),
+    mkdir(join(args.workdir, 'prompts'), { recursive: true }),
+  ]);
+
+  // 1. Probe the input.
+  const probe = await probeVideo(args.input, ingestDeps);
+
+  // 2. Extract audio into the work folder's source/ dir, then transcribe.
+  const audioPath = join(args.workdir, 'source', 'audio.aac');
+  await extractAudio(args.input, audioPath, ingestDeps);
+
+  let transcript: Transcript;
+  if (args.transcriptPath) {
+    transcript = await loadTranscript(args.transcriptPath);
+  } else {
+    transcript = await transcribeAudio(audioPath, args.lang, transcribeDeps);
+  }
+  // Persist the transcript alongside source/ for the operator + execute phase.
+  const transcriptOut = join(args.workdir, 'source', 'transcript.json');
+  await writeFile(transcriptOut, `${JSON.stringify(transcript, null, 2)}\n`, 'utf-8');
+
+  // 3. Slice into takes at sentence boundaries ≤ max.
+  const splits = planSplits(transcript, args.maxTakeSeconds);
+
+  // 4. Cut each take frame-accurately + sample reference frames.
+  for (const split of splits) {
+    const clipPath = join(args.workdir, 'takes', `${takeStem(split)}.mp4`);
+    await cutTake(args.input, split.start, split.end, clipPath, ingestDeps);
+  }
+  const frameFiles = await extractFrames(
+    args.input,
+    join(args.workdir, 'frames'),
+    probe.durationSeconds,
+    args.frameCount ?? 3,
+    ingestDeps,
+  );
+  const frames = readFrameObservations(probe, frameFiles);
+
+  // 5. Resolve style + analyze + compose per take.
+  const resolvedStyle = resolveStyle(args.style, {
+    ...(args.accent ? { accent: args.accent } : {}),
+    ...(args.brandAccent ? { brand: { accent: args.brandAccent } } : {}),
+  });
+  const onScreenLanguage = languageLabel(transcript.language || args.lang);
+
+  const analyses = splits.map((split) => analyzeTake(split, transcript.segments, splits.length));
+  const prompts = splits.map((split, i) =>
+    composePrompt({
+      index: split.index,
+      split,
+      segments: transcript.segments,
+      layout: args.layout,
+      style: resolvedStyle,
+      analysis: analyses[i],
+      frames,
+      language: onScreenLanguage,
+      durationSeconds: split.end - split.start,
+    }),
+  );
+
+  // 6. Assemble the manifest.
+  const plan = buildMotionOverlayPlan({
+    input: {
+      path: args.input,
+      durationSeconds: probe.durationSeconds,
+      width: probe.width,
+      height: probe.height,
+      aspect: probe.aspect,
+    },
+    layout: args.layout,
+    style: args.style,
+    accent: resolvedStyle.accent,
+    language: transcript.language || args.lang,
+    workdir: args.workdir,
+    splits,
+    analyses,
+    prompts,
+  });
+
+  // 7. Write the work folder (README + manifest + per-take prompts).
+  const written = await writeWorkFolder(args.workdir, plan, {
+    ...(args.generatedAt ? { generatedAt: args.generatedAt } : {}),
+  });
+
+  // Copy the original into source/ for provenance (best-effort; non-fatal).
+  await copyFile(args.input, join(args.workdir, 'source', 'original.mp4')).catch(() => {});
+
+  const stampedPlan: MotionOverlayPlan = { ...plan, generatedAt: args.generatedAt ?? plan.generatedAt };
+
+  // Optionally emit the review/review.html approval surface (the contract).
+  let reviewPath: string | undefined;
+  if (args.preview) {
+    const review = await writeMotionOverlayReview(args.workdir, stampedPlan);
+    reviewPath = review.reviewPath;
+  }
+
+  return {
+    plan: stampedPlan,
+    manifestPath: written.manifestPath,
+    readmePath: written.readmePath,
+    promptPaths: written.promptPaths,
+    ...(reviewPath ? { reviewPath } : {}),
+  };
+}