videoclaw 3.0.0-alpha.1

package/dist/video/motion-overlay/avatar-host.js

@@ -0,0 +1,131 @@
+/**
+ * Avatar-host layout (Layout D) — per-take host base clip generation.
+ *
+ * The `avatar-host` layout replaces the original speaker with an identity-locked
+ * character host that SPEAKS each take's line. For each take we generate a fresh
+ * host clip with **omni-flash R2V + native voice**:
+ *
+ *   character reference image (R2V `ingredients:`) + the take's line + a voice
+ *      → omni-flash generates the audio AND the lip-synced video together
+ *
+ * Because Omni produces the speech and the mouth movement jointly, the avatar is
+ * genuinely lip-synced (no separate TTS / no muxing / no lip-sync model). The
+ * host clips are then stitched into the avatar reel and captioned via the local
+ * renderer. Unlike the V2V "add-overlay" edit, R2V generation is NOT
+ * moderation-blocked.
+ *
+ * Each step carries the take's spoken `text`; the voice + character reference are
+ * supplied by the generator (see `avatar-host-transport.ts`).
+ *
+ * Credit safety is structural: every side effect (the go-bananas character
+ * generation + the Veo I2V render) is delegated to an injectable
+ * {@link MotionOverlayHostGenerator}. The CLI supplies a generator that shells the
+ * real go-bananas + Veo I2V path; tests inject a fake, so the orchestrator runs
+ * offline with NO real generation and NO spend.
+ *
+ * Dry vs execute mirrors {@link runMotionOverlay}: default (`confirmSpend` falsey)
+ * enumerates the host clips that WOULD be generated without invoking the
+ * generator; only `confirmSpend: true` actually drives it.
+ */
+import { join } from 'node:path';
+import { takeStem } from './plan.js';
+export class MotionOverlayAvatarError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = 'MotionOverlayAvatarError';
+    }
+}
+/** The subdir under the work folder where generated host base clips land. */
+export const HOST_DIRNAME = 'host';
+/**
+ * Parse a `--gb-character` flag value of the form `Name:ID` (e.g. `Clawbot:291`).
+ * The name may contain spaces; only the FINAL `:` separates name from id so names
+ * like `Dr. Vox:97` parse correctly. Pure.
+ *
+ * @throws {@link MotionOverlayAvatarError} (`gb_character_malformed`) on a missing
+ * separator, an empty name, or a non-numeric / non-positive id.
+ */
+export function parseGbCharacter(raw) {
+    const value = raw.trim();
+    const sep = value.lastIndexOf(':');
+    if (sep <= 0 || sep === value.length - 1) {
+        throw new MotionOverlayAvatarError('gb_character_malformed', `--gb-character must be of the form Name:ID (e.g. Clawbot:291), got: ${JSON.stringify(raw)}`);
+    }
+    const name = value.slice(0, sep).trim();
+    const idRaw = value.slice(sep + 1).trim();
+    const id = Number(idRaw);
+    if (!name) {
+        throw new MotionOverlayAvatarError('gb_character_malformed', `--gb-character is missing a character name before ':', got: ${JSON.stringify(raw)}`);
+    }
+    if (!Number.isInteger(id) || id <= 0) {
+        throw new MotionOverlayAvatarError('gb_character_malformed', `--gb-character id must be a positive integer, got: ${JSON.stringify(idRaw)}`);
+    }
+    return { name, id };
+}
+/**
+ * Reconstruct a take's stem (e.g. `take-01_0s-10s`) from its manifest fields so
+ * the host clip sits in `host/` with a matching name. Same {@link takeStem} the
+ * planner used.
+ */
+function takeStemOf(take) {
+    const split = { index: take.index, start: take.start, end: take.end, segmentIndices: [] };
+    return takeStem(split);
+}
+/** Absolute path the host base clip for a take is written to. */
+export function hostClipPath(workdir, take) {
+    return join(workdir, HOST_DIRNAME, `${takeStemOf(take)}.mp4`);
+}
+/**
+ * Generate (or dry-plan) the per-take host base clips for the avatar-host layout.
+ *
+ * Takes are processed strictly IN ORDER. Pure control flow — all generation I/O is
+ * delegated to `opts.generator`. Never mutates the input plan. The returned
+ * `hostBaseByIndex` map feeds {@link runMotionOverlay} so each take's V2V base is
+ * the generated host clip instead of the source take.
+ *
+ * @throws {@link MotionOverlayAvatarError} (`motion_overlay_avatar_layout`) if the
+ * plan's layout is not `avatar-host`, or (`motion_overlay_no_takes`) if there are
+ * no takes.
+ */
+export async function runAvatarHostGeneration(plan, character, opts) {
+    if (plan.layout !== 'avatar-host') {
+        throw new MotionOverlayAvatarError('motion_overlay_avatar_layout', `runAvatarHostGeneration: plan layout must be 'avatar-host', got: ${plan.layout}.`);
+    }
+    if (plan.takes.length === 0) {
+        throw new MotionOverlayAvatarError('motion_overlay_no_takes', 'motion-overlay avatar-host: the plan has no takes to generate hosts for.');
+    }
+    const confirmSpend = opts.confirmSpend === true;
+    const orderedTakes = [...plan.takes].sort((a, b) => a.index - b.index);
+    const hosts = [];
+    const hostBaseByIndex = {};
+    for (const take of orderedTakes) {
+        const hostClip = hostClipPath(plan.workdir, take);
+        if (confirmSpend) {
+            await opts.generator.generateHostClip({
+                index: take.index,
+                character,
+                text: opts.textByIndex?.[take.index] ?? '',
+                anatomy: take.anatomy,
+                durationSeconds: take.durationSeconds,
+                outputPath: hostClip,
+            });
+        }
+        hosts.push({
+            index: take.index,
+            anatomy: take.anatomy,
+            hostClip,
+            status: confirmSpend ? 'generated' : 'planned',
+        });
+        hostBaseByIndex[take.index] = hostClip;
+    }
+    return {
+        schemaVersion: 1,
+        generated: confirmSpend,
+        character,
+        hosts,
+        hostBaseByIndex,
+    };
+}
+//# sourceMappingURL=avatar-host.js.map

package/dist/video/motion-overlay/avatar-host.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"avatar-host.js","sourceRoot":"","sources":["../../../src/video/motion-overlay/avatar-host.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AAGrC,MAAM,OAAO,wBAAyB,SAAQ,KAAK;IAE/B;IADlB,YACkB,IAAY,EAC5B,OAAe;QAEf,KAAK,CAAC,OAAO,CAAC,CAAC;QAHC,SAAI,GAAJ,IAAI,CAAQ;QAI5B,IAAI,CAAC,IAAI,GAAG,0BAA0B,CAAC;IACzC,CAAC;CACF;AAED,6EAA6E;AAC7E,MAAM,CAAC,MAAM,YAAY,GAAG,MAAM,CAAC;AAYnC;;;;;;;GAOG;AACH,MAAM,UAAU,gBAAgB,CAAC,GAAW;IAC1C,MAAM,KAAK,GAAG,GAAG,CAAC,IAAI,EAAE,CAAC;IACzB,MAAM,GAAG,GAAG,KAAK,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC;IACnC,IAAI,GAAG,IAAI,CAAC,IAAI,GAAG,KAAK,KAAK,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACzC,MAAM,IAAI,wBAAwB,CAChC,wBAAwB,EACxB,uEAAuE,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,EAAE,CAC7F,CAAC;IACJ,CAAC;IACD,MAAM,IAAI,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC;IACxC,MAAM,KAAK,GAAG,KAAK,CAAC,KAAK,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;IAC1C,MAAM,EAAE,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC;IACzB,IAAI,CAAC,IAAI,EAAE,CAAC;QACV,MAAM,IAAI,wBAAwB,CAChC,wBAAwB,EACxB,+DAA+D,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,EAAE,CACrF,CAAC;IACJ,CAAC;IACD,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,EAAE,CAAC,IAAI,EAAE,IAAI,CAAC,EAAE,CAAC;QACrC,MAAM,IAAI,wBAAwB,CAChC,wBAAwB,EACxB,sDAAsD,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,EAAE,CAC9E,CAAC;IACJ,CAAC;IACD,OAAO,EAAE,IAAI,EAAE,EAAE,EAAE,CAAC;AACtB,CAAC;AAoED;;;;GAIG;AACH,SAAS,UAAU,CAAC,IAAgB;IAClC,MAAM,KAAK,GAAc,EAAE,KAAK,EAAE,IAAI,CAAC,KAAK,EAAE,KAAK,EAAE,IAAI,CAAC,KAAK,EAAE,GAAG,EAAE,IAAI,CAAC,GAAG,EAAE,cAAc,EAAE,EAAE,EAAE,CAAC;IACrG,OAAO,QAAQ,CAAC,KAAK,CAAC,CAAC;AACzB,CAAC;AAED,iEAAiE;AACjE,MAAM,UAAU,YAAY,CAAC,OAAe,EAAE,IAAgB;IAC5D,OAAO,IAAI,CAAC,OAAO,EAAE,YAAY,EAAE,GAAG,UAAU,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;AAChE,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,KAAK,UAAU,uBAAuB,CAC3C,IAAuB,EACvB,SAAsB,EACtB,IAA0B;IAE1B,IAAI,IAAI,CAAC,MAAM,KAAK,aAAa,EAAE,CAAC;QAClC,MAAM,IAAI,wBAAwB,CAChC,8BAA8B,EAC9B,oEAAoE,IAAI,CAAC,MAAM,GAAG,CACnF,CAAC;IACJ,CAAC;IACD,IAAI,IAAI,CAAC,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC5B,MAAM,IAAI,wBAAwB,CAChC,yBAAyB,EACzB,0EAA0E,CAC3E,CAAC;IACJ,CAAC;IAED,MAAM,YAAY,GAAG,IAAI,CAAC,YAAY,KAAK,IAAI,CAAC;IAChD,MAAM,YAAY,GAAG,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC;IAEvE,MAAM,KAAK,GAA8B,EAAE,CAAC;IAC5C,MAAM,eAAe,GAA2B,EAAE,CAAC;IAEnD,KAAK,MAAM,IAAI,IAAI,YAAY,EAAE,CAAC;QAChC,MAAM,QAAQ,GAAG,YAAY,CAAC,IAAI,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC;QAClD,IAAI,YAAY,EAAE,CAAC;YACjB,MAAM,IAAI,CAAC,SAAS,CAAC,gBAAgB,CAAC;gBACpC,KAAK,EAAE,IAAI,CAAC,KAAK;gBACjB,SAAS;gBACT,IAAI,EAAE,IAAI,CAAC,WAAW,EAAE,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE;gBAC1C,OAAO,EAAE,IAAI,CAAC,OAAO;gBACrB,eAAe,EAAE,IAAI,CAAC,eAAe;gBACrC,UAAU,EAAE,QAAQ;aACrB,CAAC,CAAC;QACL,CAAC;QACD,KAAK,CAAC,IAAI,CAAC;YACT,KAAK,EAAE,IAAI,CAAC,KAAK;YACjB,OAAO,EAAE,IAAI,CAAC,OAAO;YACrB,QAAQ;YACR,MAAM,EAAE,YAAY,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,SAAS;SAC/C,CAAC,CAAC;QACH,eAAe,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,QAAQ,CAAC;IACzC,CAAC;IAED,OAAO;QACL,aAAa,EAAE,CAAC;QAChB,SAAS,EAAE,YAAY;QACvB,SAAS;QACT,KAAK;QACL,eAAe;KAChB,CAAC;AACJ,CAAC"}

package/dist/video/motion-overlay/compose-prompt.d.ts

@@ -0,0 +1,48 @@
+/**
+ * compose-prompt — THE IP.
+ *
+ * Pure function that assembles the full Omni prompt for a single take from:
+ *   take/split + take-relative segments + layout + resolved style + analysis +
+ *   frame observations + language + duration.
+ *
+ * Structure (ported from the source skill's SKELETON):
+ *   CRITICAL RULE 1/2/3  (from prompt-rules)
+ *   TASK + LAYOUT block  (per layout: split / overlay / motion-only / avatar-host)
+ *   VISUAL block         (from resolved style)
+ *   MOTION block         (from resolved style)
+ *   SHOTS                (one shot per take-relative segment; only quoted text renders)
+ *   GLOBAL RULES         (layout-specific untouchable zones + language + audio)
+ *
+ * INVARIANTS (tested):
+ *  - Timecodes are rebased to the clip's 0:00 (absolute − take.start).
+ *  - The output contains NO leaked styling metadata: no `\d+px`, no `\d+ms`, no
+ *    hex colour, no easing-curve name, no font-family name. The accent is
+ *    rendered as a HUMAN COLOUR NAME, never a hex string.
+ *
+ * Pure: no I/O. Deterministic.
+ */
+import type { FrameObservations, MotionLayout, ResolvedStyle, TakeAnalysis, TakeSplit, TranscriptSegment } from './types.js';
+export interface ComposePromptArgs {
+    /** Take index (0-based). */
+    index: number;
+    /** The take's span + which segments it covers. */
+    split: TakeSplit;
+    /** Full transcript segments (absolute timing); rebased here. */
+    segments: TranscriptSegment[];
+    layout: MotionLayout;
+    style: ResolvedStyle;
+    analysis: TakeAnalysis;
+    frames?: FrameObservations;
+    /** On-screen text language (human-readable, e.g. "Portuguese"). */
+    language: string;
+    /** Take duration in seconds (for the TASK line). */
+    durationSeconds: number;
+}
+/** Map a hex accent to a human colour NAME so no hex leaks into the prompt. */
+export declare function accentColourName(hex: string): string;
+/**
+ * Compose the full Omni prompt for one take. Pure. Output is guaranteed free of
+ * leaked styling metadata (see module-level invariants + the compose test).
+ */
+export declare function composePrompt(args: ComposePromptArgs): string;
+//# sourceMappingURL=compose-prompt.d.ts.map

package/dist/video/motion-overlay/compose-prompt.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"compose-prompt.d.ts","sourceRoot":"","sources":["../../../src/video/motion-overlay/compose-prompt.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,KAAK,EACV,iBAAiB,EACjB,YAAY,EACZ,aAAa,EACb,YAAY,EACZ,SAAS,EACT,iBAAiB,EAClB,MAAM,YAAY,CAAC;AAGpB,MAAM,WAAW,iBAAiB;IAChC,4BAA4B;IAC5B,KAAK,EAAE,MAAM,CAAC;IACd,kDAAkD;IAClD,KAAK,EAAE,SAAS,CAAC;IACjB,gEAAgE;IAChE,QAAQ,EAAE,iBAAiB,EAAE,CAAC;IAC9B,MAAM,EAAE,YAAY,CAAC;IACrB,KAAK,EAAE,aAAa,CAAC;IACrB,QAAQ,EAAE,YAAY,CAAC;IACvB,MAAM,CAAC,EAAE,iBAAiB,CAAC;IAC3B,mEAAmE;IACnE,QAAQ,EAAE,MAAM,CAAC;IACjB,oDAAoD;IACpD,eAAe,EAAE,MAAM,CAAC;CACzB;AAED,+EAA+E;AAC/E,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAUpD;AA+ID;;;GAGG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,iBAAiB,GAAG,MAAM,CAqC7D"}

package/dist/video/motion-overlay/compose-prompt.js

@@ -0,0 +1,217 @@
+/**
+ * compose-prompt — THE IP.
+ *
+ * Pure function that assembles the full Omni prompt for a single take from:
+ *   take/split + take-relative segments + layout + resolved style + analysis +
+ *   frame observations + language + duration.
+ *
+ * Structure (ported from the source skill's SKELETON):
+ *   CRITICAL RULE 1/2/3  (from prompt-rules)
+ *   TASK + LAYOUT block  (per layout: split / overlay / motion-only / avatar-host)
+ *   VISUAL block         (from resolved style)
+ *   MOTION block         (from resolved style)
+ *   SHOTS                (one shot per take-relative segment; only quoted text renders)
+ *   GLOBAL RULES         (layout-specific untouchable zones + language + audio)
+ *
+ * INVARIANTS (tested):
+ *  - Timecodes are rebased to the clip's 0:00 (absolute − take.start).
+ *  - The output contains NO leaked styling metadata: no `\d+px`, no `\d+ms`, no
+ *    hex colour, no easing-curve name, no font-family name. The accent is
+ *    rendered as a HUMAN COLOUR NAME, never a hex string.
+ *
+ * Pure: no I/O. Deterministic.
+ */
+import { motionOverlayCriticalRules } from '../prompt-rules.js';
+/** Map a hex accent to a human colour NAME so no hex leaks into the prompt. */
+export function accentColourName(hex) {
+    const h = hex.trim().replace(/^#/, '').toLowerCase();
+    if (!/^[0-9a-f]{6}$/.test(h)) {
+        // Already a name (or malformed) — pass through trimmed, never a hex token.
+        return hex.trim().replace(/^#/, '') || 'the accent colour';
+    }
+    const r = parseInt(h.slice(0, 2), 16);
+    const g = parseInt(h.slice(2, 4), 16);
+    const b = parseInt(h.slice(4, 6), 16);
+    return rgbToName(r, g, b);
+}
+function rgbToName(r, g, b) {
+    const max = Math.max(r, g, b);
+    const min = Math.min(r, g, b);
+    if (max - min < 24) {
+        if (max > 210)
+            return 'soft white';
+        if (max < 48)
+            return 'near-black';
+        return 'neutral grey';
+    }
+    // Hue in degrees.
+    const rf = r / 255;
+    const gf = g / 255;
+    const bf = b / 255;
+    const mx = Math.max(rf, gf, bf);
+    const mn = Math.min(rf, gf, bf);
+    const d = mx - mn;
+    let hue = 0;
+    if (mx === rf)
+        hue = ((gf - bf) / d) % 6;
+    else if (mx === gf)
+        hue = (bf - rf) / d + 2;
+    else
+        hue = (rf - gf) / d + 4;
+    hue = Math.round(hue * 60);
+    if (hue < 0)
+        hue += 360;
+    if (hue < 15 || hue >= 345)
+        return 'vivid red';
+    if (hue < 45)
+        return 'vivid orange';
+    if (hue < 70)
+        return 'warm yellow';
+    if (hue < 160)
+        return 'fresh green';
+    if (hue < 200)
+        return 'cyan teal';
+    if (hue < 255)
+        return 'electric blue';
+    if (hue < 290)
+        return 'soft lavender';
+    if (hue < 345)
+        return 'magenta pink';
+    return 'the accent colour';
+}
+function fmtTime(seconds) {
+    const clamped = Math.max(0, Math.round(seconds * 10) / 10);
+    return `${clamped.toFixed(1)}s`;
+}
+/** Build the layout-specific TASK + LAYOUT block (genericized 9:16/aspect-neutral). */
+function taskLayoutBlock(layout, durationSeconds, frames) {
+    const dur = Math.round(durationSeconds);
+    const side = frames?.speakerSide ?? 'one side';
+    switch (layout) {
+        case 'split':
+            return [
+                `TASK: Add motion graphics to the UPPER HALF of this ${dur}-second vertical clip. The footage already has a solid black upper half and the speaker composited in the lower half. ALL motion graphics live in the upper black half only. The lower half — the speaker, their clothing, the background, and any visible elements — must remain completely untouched.`,
+                'LAYOUT:',
+                '- Top half of frame: motion stage. All overlays live here.',
+                '- Bottom half of frame: speaker untouched, passed through as-is.',
+            ].join('\n');
+        case 'overlay':
+            return [
+                `TASK: Add motion graphics composited OVER this ${dur}-second clip. The speaker is in the frame and visible — overlays sit ON TOP of the footage without ever covering the speaker's face, hands, or gestures.`,
+                'LAYOUT:',
+                `- The speaker is positioned at the ${side} of the frame.`,
+                '- Motion stage: the opposite side and any plain background area. Headlines occupy the upper portion when the speaker is lower, or the side opposite the speaker.',
+                '- Keep the top and bottom UI safe areas clear of critical text.',
+            ].join('\n');
+        case 'motion-only':
+            return [
+                `TASK: The speaker does NOT appear visually in the output of this ${dur}-second clip — only their voice is preserved (CRITICAL RULE 1). Replace the entire frame with full-frame motion graphics that tell the story visually from the spoken script, like a premium keynote slide or a product launch reveal.`,
+                'LAYOUT:',
+                '- Full frame: motion stage. Use the entire canvas.',
+                '- No speaker, no source footage visible. The original video is discarded as the visual base; only its audio is retained.',
+                '- Hero shots, fullscreen headline anchors, and cinematic editorial transitions are encouraged.',
+                '- Density should be HIGHER than the split layout, since the whole frame is yours to compose.',
+            ].join('\n');
+        case 'avatar-host':
+            return [
+                `TASK: This ${dur}-second clip is fronted by an identity-locked host character delivering the lines (generated separately as the base layer). Add full-frame motion-graphics overlays ON TOP of the host, synced to the speech, without covering the host's face.`,
+                'LAYOUT:',
+                '- Host base layer: the locked character, untouched.',
+                '- Motion stage: the frame around and above the host — headlines and cards sit in the plainest areas, never over the face.',
+                '- Do NOT draw any additional human figures, silhouettes, or portraits; the host is the only person and is supplied as the base layer.',
+            ].join('\n');
+        default:
+            return `TASK: Add motion graphics to this ${dur}-second clip.`;
+    }
+}
+/** Layout-specific GLOBAL RULES additions. */
+function globalRuleAdditions(layout) {
+    switch (layout) {
+        case 'split':
+            return ['Do not place anything in the lower half of the frame; the speaker stays pristine.'];
+        case 'overlay':
+            return [
+                'Never cover the speaker\'s face, hands, or visible gestures.',
+                'Overlays primarily sit in the plainest background areas (wall, sky, blurred space).',
+            ];
+        case 'motion-only':
+            return [
+                'The speaker does not appear visually at any point.',
+                'Treat each take as a slide in a premium keynote: one dominant element at a time, with cinematic transitions.',
+            ];
+        case 'avatar-host':
+            return [
+                'The host character is the only person on screen and is supplied as the base layer — never draw another figure.',
+                'Never cover the host\'s face.',
+            ];
+        default:
+            return [];
+    }
+}
+/** Compose the SHOTS section from take-relative segments (only quoted text renders). */
+function shotsBlock(args) {
+    const lines = [
+        'SHOTS — render only the text shown in quotation marks below. Times are relative to this clip\'s 0:00.',
+    ];
+    const { split, segments, analysis } = args;
+    // Anchor words keyed by the segment they fall in (by relative time) drive the
+    // "giant headline" cue; here we surface them per shot when their time lands in
+    // the segment's relative window.
+    split.segmentIndices.forEach((segIndex, ordinal) => {
+        const seg = segments[segIndex];
+        if (!seg) {
+            return;
+        }
+        const relStart = Math.max(0, seg.start - split.start);
+        const relEnd = Math.max(relStart, seg.end - split.start);
+        const text = seg.text.trim();
+        const anchorsHere = analysis.anchorWords.filter((a) => a.relativeTime >= relStart - 0.01 && a.relativeTime <= relEnd + 0.01);
+        const anchorCue = anchorsHere.length > 0
+            ? ` Emphasize the anchor ${anchorsHere.map((a) => `"${a.word}"`).join(', ')} as a giant headline synced to the voice.`
+            : '';
+        lines.push(`SHOT ${ordinal + 1} — ${fmtTime(relStart)} to ${fmtTime(relEnd)}` +
+            `\n  Animate the meaning of this line in the chosen style, holding the frame still during any pause.${anchorCue}` +
+            `\n  Render on screen: "${text}"`);
+        // Held-pause cue immediately after this segment, if one starts at relEnd.
+        const pause = analysis.pauses.find((p) => Math.abs(p.start - relEnd) < 0.05);
+        if (pause) {
+            lines.push(`  (Pause ${fmtTime(pause.start)} to ${fmtTime(pause.end)}: hold the current state silent and still — no new animation.)`);
+        }
+    });
+    return lines.join('\n');
+}
+/**
+ * Compose the full Omni prompt for one take. Pure. Output is guaranteed free of
+ * leaked styling metadata (see module-level invariants + the compose test).
+ */
+export function composePrompt(args) {
+    const { layout, style, analysis, language, durationSeconds, frames } = args;
+    const accentName = accentColourName(style.accent);
+    const parts = [];
+    // CRITICAL RULES (verbatim, from prompt-rules).
+    parts.push(motionOverlayCriticalRules().join('\n\n'));
+    // TASK + LAYOUT.
+    parts.push(taskLayoutBlock(layout, durationSeconds, frames));
+    // Anatomy hint — calibrates visual load.
+    parts.push(`REEL POSITION: this take is the "${analysis.anatomy}" beat of the reel — calibrate visual load accordingly.`);
+    // VISUAL + MOTION from style, with the accent expressed as a human colour name.
+    parts.push(style.visualBlock.replace(/the configured accent/g, `a ${accentName} accent`));
+    parts.push(style.motionBlock);
+    // SHOTS.
+    parts.push(shotsBlock(args));
+    // GLOBAL RULES.
+    const globals = [
+        ...globalRuleAdditions(layout),
+        `On-screen text language: ${language}, exactly as written inside the quotation marks.`,
+        'Audio: do not modify — the original voiceover passes through unchanged.',
+        `Output: a single video, original as base layer (or fully replaced for the motion-only layout), overlays composited per the LAYOUT rules.`,
+    ];
+    if (frames?.notes && frames.notes.length > 0) {
+        for (const note of frames.notes) {
+            globals.push(note);
+        }
+    }
+    parts.push(['GLOBAL RULES:', ...globals.map((g) => `- ${g}`)].join('\n'));
+    return parts.join('\n\n');
+}
+//# sourceMappingURL=compose-prompt.js.map

package/dist/video/motion-overlay/compose-prompt.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"compose-prompt.js","sourceRoot":"","sources":["../../../src/video/motion-overlay/compose-prompt.ts"],"names":[],"mappings":"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"}

package/dist/video/motion-overlay/execute.d.ts

@@ -0,0 +1,190 @@
+/**
+ * Motion-overlay execution (Phase 4) — V2V + audio-restore + stitch.
+ *
+ * `runMotionOverlay` drives the render half of `vclaw video motion-overlay
+ * --execute`. The PLAN (a `MotionOverlayPlan` from `run.ts`) stays the source of
+ * truth: this module renders each of its takes IN ORDER through three steps and
+ * stitches the results into the final reel. It re-derives no slicing, prompting,
+ * or routing — the plan already fixed those.
+ *
+ * Per take:
+ *   1. Omni Flash V2V — feed the take's base footage (`takes/…mp4`) + the take's
+ *      composed prompt to the Google Flow omni-flash video-to-video transport.
+ *      Flow paints the kinetic typography / icon / metaphor overlay while keeping
+ *      the spoken content, but it RE-ENCODES the audio.
+ *   2. Audio-restore — `ffmpeg -i <v2v> -i <take> -map 0:v -map 1:a -c:v copy
+ *      -c:a aac <out>`: take the annotated VIDEO from the V2V output and the
+ *      ORIGINAL AUDIO from the source take, so the reel honors CRITICAL RULE 1
+ *      (pass the original voiceover through) as closely as the transport allows.
+ *   3. Collect the audio-restored take.
+ * Then the collected takes are clip-stitched (in take order) into the final reel.
+ *
+ * Credit safety is structural: every side effect (V2V submit/poll, the
+ * audio-restore ffmpeg mux, and the stitch) is delegated to an injectable
+ * {@link MotionOverlayStepRunner}. The CLI supplies a runner that shells the real
+ * `vclaw video` V2V path + ffmpeg + the assemble clip-stitch; tests inject a fake
+ * runner, so the whole orchestrator runs offline with NO provider spend.
+ *
+ * Dry vs execute: default (`confirmSpend` falsey) is a dry plan — the runner is
+ * NOT invoked at all and the report enumerates the steps that WOULD run. Only
+ * `confirmSpend: true` actually drives the runner. This mirrors `studio/execute.ts`.
+ */
+import type { MotionOverlayPlan, MotionTake } from './types.js';
+export declare class MotionOverlayExecuteError extends Error {
+    readonly code: string;
+    constructor(code: string, message: string);
+}
+/** Inputs for a single take's V2V render. */
+export interface MotionOverlayV2VStep {
+    index: number;
+    /** Absolute path to the take's base footage (the frame-accurate cut). */
+    baseFootage: string;
+    /** The full composed prompt for this take. */
+    prompt: string;
+    /** Absolute path the annotated (audio re-encoded) take should be written to. */
+    outputPath: string;
+}
+/** Inputs for a single take's audio-restore mux. */
+export interface MotionOverlayAudioRestoreStep {
+    index: number;
+    /** Absolute path to the V2V output (annotated video, re-encoded audio). */
+    v2vVideo: string;
+    /** Absolute path to the original take (the source of the audio to restore). */
+    originalTake: string;
+    /** Absolute path the audio-restored take should be written to. */
+    outputPath: string;
+}
+/** Inputs for the final clip-stitch over the audio-restored takes. */
+export interface MotionOverlayStitchStep {
+    /** Ordered absolute paths of the audio-restored takes (take order). */
+    takeClips: string[];
+    /** Absolute path the final reel should be written to. */
+    outputPath: string;
+}
+/**
+ * Injectable step runner — the single seam through which ALL side effects flow.
+ * The CLI supplies a runner that shells the real `vclaw video` omni-flash V2V
+ * path, the audio-restore ffmpeg mux, and the assemble clip-stitch. Tests inject
+ * a fake so the orchestrator runs offline with no spend.
+ */
+export interface MotionOverlayStepRunner {
+    /** Render one take through omni-flash V2V. Resolves once the annotated take exists. */
+    runV2V(step: MotionOverlayV2VStep): Promise<void>;
+    /**
+     * Restore the original take audio onto the V2V output via the ffmpeg mux
+     * `-map 0:v -map 1:a -c:v copy -c:a aac`. Resolves once the muxed take exists.
+     */
+    restoreAudio(step: MotionOverlayAudioRestoreStep): Promise<void>;
+    /** Clip-stitch the audio-restored takes (in order) into the final reel. */
+    stitch(step: MotionOverlayStitchStep): Promise<void>;
+}
+export interface RunMotionOverlayOptions {
+    /** The injectable step runner (CLI shells real path; tests inject a fake). */
+    runner: MotionOverlayStepRunner;
+    /**
+     * Permit the credit-spending V2V + ffmpeg + stitch steps to RUN. Default false
+     * → dry plan (the runner is never invoked); the report enumerates the steps.
+     */
+    confirmSpend?: boolean;
+    /**
+     * Avatar-host layout only: a per-take map (take index → absolute host base clip
+     * path) produced by `avatar-host.runAvatarHostGeneration`. When present for a
+     * take, the V2V step uses the HOST clip as its base footage instead of the
+     * source take — but the audio-restore step still pulls the ORIGINAL take's
+     * audio (the host visual is a stand-in; the real voiceover is preserved). Absent
+     * (or no entry for a take) → the source take is the V2V base, as for every other
+     * layout.
+     */
+    hostBaseByIndex?: Record<number, string>;
+}
+/** What happened (or would happen) to one take during execution. */
+export interface MotionOverlayTakeResult {
+    index: number;
+    anatomy: MotionTake['anatomy'];
+    /**
+     * Absolute path to the V2V base footage. The source take for every layout
+     * EXCEPT avatar-host, where it is the generated host base clip.
+     */
+    baseFootage: string;
+    /**
+     * Absolute path to the take whose audio is restored onto the V2V output. Always
+     * the ORIGINAL source take (the real voiceover), even on avatar-host.
+     */
+    audioSource: string;
+    /** Absolute path to the V2V (annotated) output. */
+    v2vVideo: string;
+    /** Absolute path to the audio-restored take (what feeds the stitch). */
+    restoredTake: string;
+    /** ran = the runner was invoked; planned = dry (not invoked). */
+    status: 'ran' | 'planned';
+}
+export type MotionOverlayExecuteMode = 'dry' | 'execute';
+export interface MotionOverlayExecuteReport {
+    schemaVersion: 1;
+    mode: MotionOverlayExecuteMode;
+    /** True only when the runner actually rendered (confirmSpend). */
+    executed: boolean;
+    takes: MotionOverlayTakeResult[];
+    /** Absolute path to the final stitched reel. */
+    reelPath: string;
+    /** Set in dry mode: how to render for real. */
+    hint?: string;
+}
+/** The subdir under the work folder where V2V outputs land. */
+export declare const V2V_DIRNAME = "v2v";
+/** The subdir under the work folder where audio-restored takes land. */
+export declare const RESTORED_DIRNAME = "restored";
+/** The final reel filename written into the work folder. */
+export declare const REEL_FILENAME = "motion-overlay-reel.mp4";
+/**
+ * Execute (or dry-plan) a motion-overlay reel from its plan.
+ *
+ * Takes are processed strictly IN ORDER; the final reel stitches the
+ * audio-restored takes in that same order. Pure control flow — all I/O is
+ * delegated to `opts.runner`. Never mutates the input plan.
+ *
+ * Throws {@link MotionOverlayExecuteError} (`motion_overlay_no_takes`) if the
+ * plan has zero takes (nothing to render or stitch).
+ */
+export declare function runMotionOverlay(plan: MotionOverlayPlan, opts: RunMotionOverlayOptions): Promise<MotionOverlayExecuteReport>;
+/**
+ * Build the audio-restore ffmpeg args (PURE). Takes the annotated VIDEO from the
+ * V2V output and the ORIGINAL AUDIO from the source take, re-muxing them so the
+ * reel keeps the untouched voiceover (CRITICAL RULE 1).
+ *
+ *   -i <v2v_video> -i <original_take>
+ *   -map 0:v -map 1:a   (video from input 0, audio from input 1)
+ *   -c:v copy           (don't re-encode the annotated video)
+ *   -c:a aac            (re-encode the restored audio to AAC for mp4 compat)
+ *   -shortest           (cap to the shorter stream so a length mismatch can't
+ *                        leave a trailing black/silent tail)
+ *   <output>
+ *
+ * (`-y` is prepended by `runFfmpeg`, so it is NOT included here.)
+ */
+export declare function buildAudioRestoreArgs(v2vVideo: string, originalTake: string, outputPath: string): string[];
+/**
+ * The per-take omni-flash V2V transport. The CLI supplies the real one (a thin
+ * wrapper over the native Flow V2V path: it submits the take's base footage as
+ * the V2V edit reference with the composed prompt, polls to completion, and
+ * writes the annotated take to `step.outputPath`). It is its OWN injectable seam
+ * so the audio-restore + stitch halves of the default runner can be unit-tested
+ * without a live provider.
+ */
+export type MotionOverlayV2VTransport = (step: MotionOverlayV2VStep) => Promise<void>;
+export interface DefaultMotionOverlayRunnerOptions {
+    /** The real V2V transport (CLI-supplied). Required — there is no offline default. */
+    v2v: MotionOverlayV2VTransport;
+    /** Override the ffmpeg binary for the audio-restore mux. */
+    ffmpegBin?: string;
+}
+/**
+ * Build the default {@link MotionOverlayStepRunner} that shells the REAL render
+ * path: `v2v` for each take's omni-flash render, `runFfmpeg` for the audio-restore
+ * mux ({@link buildAudioRestoreArgs}), and the assemble {@link stitch} clip-stitch
+ * for the final reel. The V2V transport is injected so the audio + stitch wiring
+ * stays independently testable; the whole runner is ONLY used under
+ * `--execute --confirm-spend`, so tests never reach it (they inject a fake runner).
+ */
+export declare function createDefaultMotionOverlayRunner(opts: DefaultMotionOverlayRunnerOptions): MotionOverlayStepRunner;
+//# sourceMappingURL=execute.d.ts.map

package/dist/video/motion-overlay/execute.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"execute.d.ts","sourceRoot":"","sources":["../../../src/video/motion-overlay/execute.ts"],"names":[],"mappings":"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"}