@mevdragon/vidfarm-devcli 0.5.3 → 0.6.0

package/dist/src/services/hyperframes.js

@@ -0,0 +1,2307 @@
+import { spawn } from "node:child_process";
+import { randomUUID } from "node:crypto";
+import { createWriteStream } from "node:fs";
+import { cp, mkdir, mkdtemp, readFile, readdir, rm, stat, writeFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { pipeline } from "node:stream/promises";
+import { CloudFormationClient, DescribeStacksCommand } from "@aws-sdk/client-cloudformation";
+import { GetObjectCommand, S3Client } from "@aws-sdk/client-s3";
+import { getSignedUrl } from "@aws-sdk/s3-request-presigner";
+import ffmpegStatic from "ffmpeg-static";
+import ffprobeStatic from "ffprobe-static";
+import { parseHTML } from "linkedom";
+import { config } from "../config.js";
+import { devErrorFields, devLog } from "../lib/dev-log.js";
+import { buildHyperframeCompositionHtml } from "../hyperframes/composition.js";
+import { applyMarkupUsd } from "./billing-pricing.js";
+let stackCache = null;
+const SMART_DECOMPOSE_TEMP_PREFIX = "vidfarm-smart-decompose-";
+const SMART_DECOMPOSE_TEMP_MAX_AGE_MS = 24 * 60 * 60 * 1000;
+async function sweepStaleSmartDecomposeTempDirs() {
+    const tmpRoot = os.tmpdir();
+    let entries;
+    try {
+        entries = await readdir(tmpRoot);
+    }
+    catch {
+        return;
+    }
+    const now = Date.now();
+    await Promise.all(entries.map(async (name) => {
+        if (!name.startsWith(SMART_DECOMPOSE_TEMP_PREFIX))
+            return;
+        const full = path.join(tmpRoot, name);
+        try {
+            const info = await stat(full);
+            if (!info.isDirectory())
+                return;
+            if (now - info.mtimeMs < SMART_DECOMPOSE_TEMP_MAX_AGE_MS)
+                return;
+            await rm(full, { recursive: true, force: true });
+        }
+        catch {
+            /* ignore */
+        }
+    }));
+}
+sweepStaleSmartDecomposeTempDirs().catch((err) => {
+    console.error("smart decompose temp sweep failed", err);
+});
+// True when no cloud HyperFrames render stack is wired (env or explicit
+// CloudFormation outputs). On a `vidfarm serve` box this is the normal state,
+// so render should run in-process rather than fail. `VIDFARM_LOCAL_RENDER`
+// forces local even when a cloud stack IS configured (useful for offline dev).
+function shouldRenderLocally() {
+    if (config.VIDFARM_LOCAL_RENDER)
+        return true;
+    const hasCloudStack = Boolean((config.HYPERFRAMES_RENDER_STATE_MACHINE_ARN || config.HYPERFRAMES_STATE_MACHINE_ARN) &&
+        (config.HYPERFRAMES_RENDER_BUCKET_NAME || config.HYPERFRAMES_LAMBDA_BUCKET_NAME));
+    return !hasCloudStack;
+}
+export class HyperframesService {
+    async render(input) {
+        const compositionHtml = normalizePublishHtml(input.compositionHtml || (input.composition ? buildHyperframeCompositionHtml(input.composition) : ""));
+        if (!compositionHtml.includes("data-composition-id=")) {
+            throw new Error("HyperFrames render requires composition HTML with data-composition-id.");
+        }
+        if (shouldRenderLocally()) {
+            return this.renderLocal({ ...input, compositionHtml });
+        }
+        const metadata = extractCompositionMetadata(compositionHtml, input);
+        const stack = await resolveHyperframesStack();
+        devLog("hyperframes.render.staging", {
+            composition_id: metadata.compositionId,
+            width: metadata.width,
+            height: metadata.height,
+            fps: metadata.fps,
+            stack_name: stack.stackName,
+            region: stack.region
+        });
+        const projectDir = await stageProject({
+            compositionHtml,
+            compositionId: metadata.compositionId,
+            projectFiles: input.projectFiles,
+            copyPaths: input.copyPaths
+        });
+        const timestamp = Date.now().toString(36);
+        const renderId = input.executionName || `vf-${metadata.compositionId.slice(0, 40)}-${timestamp}-${randomUUID().slice(0, 8)}`;
+        const outputKey = input.outputKey || `renders/vidfarm/${metadata.compositionId}/${renderId}/output.mp4`;
+        devLog("hyperframes.render.dispatch", {
+            composition_id: metadata.compositionId,
+            render_id: renderId,
+            output_key: outputKey,
+            chunk_size: input.chunkSize ?? 240,
+            max_parallel_chunks: input.maxParallelChunks ?? 8,
+            wait: input.wait !== false
+        });
+        const { renderToLambda, getRenderProgress } = await import("@hyperframes/aws-lambda/sdk");
+        const handle = await renderToLambda({
+            projectDir,
+            bucketName: stack.bucketName,
+            stateMachineArn: stack.stateMachineArn,
+            region: stack.region,
+            executionName: renderId,
+            outputKey,
+            config: {
+                fps: normalizeRenderFps(metadata.fps),
+                width: metadata.width,
+                height: metadata.height,
+                format: input.format || "mp4",
+                codec: "h264",
+                quality: "standard",
+                chunkSize: input.chunkSize ?? 240,
+                maxParallelChunks: input.maxParallelChunks ?? 8,
+                runtimeCap: "lambda"
+            }
+        });
+        if (input.wait === false) {
+            devLog("hyperframes.render.dispatched_async", {
+                composition_id: metadata.compositionId,
+                render_id: renderId,
+                execution_arn: handle.executionArn
+            });
+            return {
+                ...handle,
+                outputUrl: null,
+                outputS3Uri: handle.outputS3Uri,
+                endedAt: null,
+                metadata: {
+                    mode: "hyperframes_lambda",
+                    status: "RUNNING",
+                    stack,
+                    composition: metadata
+                }
+            };
+        }
+        const startedAtMs = Date.now();
+        const timeoutMs = input.timeoutMs ?? 12 * 60 * 1000;
+        const pollIntervalMs = input.pollIntervalMs ?? 5000;
+        let pollCount = 0;
+        let lastLoggedStatus = null;
+        for (;;) {
+            const progress = await getRenderProgress({
+                executionArn: handle.executionArn,
+                region: stack.region,
+                defaultMemorySizeMb: stack.lambdaMemoryMb
+            });
+            pollCount += 1;
+            if (progress.status !== lastLoggedStatus) {
+                devLog("hyperframes.render.progress", {
+                    composition_id: metadata.compositionId,
+                    render_id: renderId,
+                    status: progress.status,
+                    poll_count: pollCount,
+                    elapsed_ms: Date.now() - startedAtMs,
+                    frames_rendered: progress.framesRendered,
+                    total_frames: progress.totalFrames
+                });
+                lastLoggedStatus = progress.status;
+            }
+            if (progress.status === "SUCCEEDED") {
+                const outputS3Uri = progress.outputFile?.s3Uri || handle.outputS3Uri;
+                devLog("hyperframes.render.succeeded", {
+                    composition_id: metadata.compositionId,
+                    render_id: renderId,
+                    duration_ms: Date.now() - startedAtMs,
+                    output_s3_uri: outputS3Uri,
+                    frames_rendered: progress.framesRendered,
+                    total_frames: progress.totalFrames,
+                    lambdas_invoked: progress.lambdasInvoked,
+                    cost_usd: progress.costs?.accruedSoFarUsd
+                });
+                return {
+                    ...handle,
+                    outputS3Uri,
+                    outputUrl: await signedS3Url(outputS3Uri, stack.region),
+                    endedAt: progress.endedAt,
+                    metadata: {
+                        mode: "hyperframes_lambda",
+                        status: progress.status,
+                        stack,
+                        composition: metadata,
+                        progress,
+                        costs: progress.costs,
+                        estimatedCostUsd: progress.costs.accruedSoFarUsd,
+                        chargeUsd: applyMarkupUsd(progress.costs.accruedSoFarUsd),
+                        costDisplay: progress.costs.displayCost,
+                        lambdasInvoked: progress.lambdasInvoked,
+                        framesRendered: progress.framesRendered,
+                        totalFrames: progress.totalFrames
+                    }
+                };
+            }
+            if (progress.fatalErrorEncountered || ["FAILED", "TIMED_OUT", "ABORTED"].includes(progress.status)) {
+                devLog("hyperframes.render.failed", {
+                    composition_id: metadata.compositionId,
+                    render_id: renderId,
+                    status: progress.status,
+                    duration_ms: Date.now() - startedAtMs,
+                    errors: Array.isArray(progress.errors) ? progress.errors.slice(0, 3) : progress.errors
+                }, "error");
+                throw new Error(`HyperFrames render ${handle.renderId} failed: ${JSON.stringify(progress.errors)}`);
+            }
+            if (Date.now() - startedAtMs > timeoutMs) {
+                devLog("hyperframes.render.timeout", {
+                    composition_id: metadata.compositionId,
+                    render_id: renderId,
+                    timeout_ms: timeoutMs,
+                    last_status: progress.status
+                }, "error");
+                throw new Error(`Timed out waiting for HyperFrames render ${handle.renderId}.`);
+            }
+            await new Promise((resolve) => setTimeout(resolve, pollIntervalMs));
+        }
+    }
+    // In-process render: stage the project, then drive HyperFrames' single-machine
+    // orchestrator (headless Chromium → per-frame capture → ffmpeg encode) to write
+    // the MP4 straight to local disk storage. No AWS, no Lambda fan-out. The result
+    // is shaped like the cloud render result so the `hyperframes_render` primitive
+    // and the publish/polling flow consume it unchanged.
+    async renderLocal(input) {
+        const rawHtml = normalizePublishHtml(input.compositionHtml || (input.composition ? buildHyperframeCompositionHtml(input.composition) : ""));
+        if (!rawHtml.includes("data-composition-id=")) {
+            throw new Error("HyperFrames render requires composition HTML with data-composition-id.");
+        }
+        // libx264 (yuv420p) requires even width/height. The in-process renderer sizes
+        // the canvas from the composition's data-width/data-height, so round any odd
+        // dimension down to even here — the cloud path sidesteps this by rendering at
+        // explicit even asset dimensions.
+        const compositionHtml = forceEvenCompositionDimensions(rawHtml);
+        const metadata = extractCompositionMetadata(compositionHtml, input);
+        const projectDir = await stageProject({
+            compositionHtml,
+            compositionId: metadata.compositionId,
+            projectFiles: input.projectFiles,
+            copyPaths: input.copyPaths
+        });
+        const timestamp = Date.now().toString(36);
+        const renderId = input.executionName || `vf-${metadata.compositionId.slice(0, 40)}-${timestamp}-${randomUUID().slice(0, 8)}`;
+        const outputKey = input.outputKey || `renders/vidfarm/${metadata.compositionId}/${renderId}/output.mp4`;
+        const outputLocation = path.join(config.VIDFARM_DATA_DIR, "storage", outputKey);
+        await mkdir(path.dirname(outputLocation), { recursive: true });
+        const startedAt = new Date().toISOString();
+        const startedAtMs = Date.now();
+        devLog("hyperframes.render_local.start", {
+            composition_id: metadata.compositionId,
+            render_id: renderId,
+            width: metadata.width,
+            height: metadata.height,
+            fps: metadata.fps,
+            output_key: outputKey
+        });
+        const { createRenderJob, executeRenderJob } = await import("@hyperframes/producer");
+        const job = createRenderJob({
+            fps: normalizeRenderFps(metadata.fps),
+            quality: "standard",
+            format: input.format || "mp4"
+        });
+        let lastStatus = null;
+        await executeRenderJob(job, projectDir, outputLocation, (progressJob, message) => {
+            if (progressJob.status !== lastStatus) {
+                devLog("hyperframes.render_local.progress", {
+                    render_id: renderId,
+                    status: progressJob.status,
+                    message
+                });
+                lastStatus = progressJob.status;
+            }
+        });
+        // Single-segment encoded key — matches the `/storage/:key` route which
+        // decodeURIComponent's one param (slashes ride through as %2F).
+        const outputUrl = `${config.PUBLIC_BASE_URL}/storage/${encodeURIComponent(outputKey)}`;
+        const durationMs = Date.now() - startedAtMs;
+        devLog("hyperframes.render_local.succeeded", {
+            composition_id: metadata.compositionId,
+            render_id: renderId,
+            duration_ms: durationMs,
+            output_location: outputLocation,
+            output_url: outputUrl
+        });
+        return {
+            renderId,
+            outputUrl,
+            outputS3Uri: null,
+            executionArn: `local:${renderId}`,
+            bucketName: "",
+            stateMachineArn: "",
+            projectS3Uri: `file://${projectDir}`,
+            siteId: null,
+            startedAt,
+            endedAt: new Date().toISOString(),
+            metadata: {
+                mode: "hyperframes_local",
+                status: "SUCCEEDED",
+                composition: metadata,
+                outputLocation,
+                durationMs,
+                // Local render burns the operator's own CPU — no per-frame Lambda cost.
+                chargeUsd: 0,
+                estimatedCostUsd: 0,
+                costDisplay: "$0.00 (local render)"
+            }
+        };
+    }
+    // In-process STILL render: render one frame of a composition to a PNG/JPEG/WEBP
+    // image on local disk. Uses the same headless-Chromium capture as renderLocal
+    // via HyperFrames' png-sequence format, then transcodes to the requested still
+    // format with ffmpeg. Replaces the Remotion `renderStill` path.
+    async renderStill(input) {
+        const compositionHtml = forceEvenCompositionDimensions(normalizePublishHtml(input.compositionHtml));
+        if (!compositionHtml.includes("data-composition-id=")) {
+            throw new Error("HyperFrames still render requires composition HTML with data-composition-id.");
+        }
+        const metadata = extractCompositionMetadata(compositionHtml, { compositionId: input.compositionId });
+        const projectDir = await stageProject({
+            compositionHtml,
+            compositionId: metadata.compositionId,
+            projectFiles: input.projectFiles,
+            copyPaths: input.copyPaths
+        });
+        const timestamp = Date.now().toString(36);
+        const renderId = `vfimg-${metadata.compositionId.slice(0, 40)}-${timestamp}-${randomUUID().slice(0, 8)}`;
+        const framesDir = path.join(config.VIDFARM_DATA_DIR, "hyperframes-projects", `${renderId}-frames`);
+        await mkdir(framesDir, { recursive: true });
+        devLog("hyperframes.render_still.start", {
+            composition_id: metadata.compositionId,
+            render_id: renderId,
+            width: metadata.width,
+            height: metadata.height
+        });
+        const { createRenderJob, executeRenderJob } = await import("@hyperframes/producer");
+        // png-sequence writes outputPath as a DIRECTORY of frame_000001.png … files.
+        const job = createRenderJob({ fps: 30, quality: "high", format: "png-sequence" });
+        try {
+            await executeRenderJob(job, projectDir, framesDir);
+            const frameFiles = (await readdir(framesDir))
+                .filter((name) => name.toLowerCase().endsWith(".png"))
+                .sort();
+            if (!frameFiles.length) {
+                throw new Error("HyperFrames still render produced no frames.");
+            }
+            const firstFramePath = path.join(framesDir, frameFiles[0]);
+            const format = input.imageFormat ?? "png";
+            const extension = format === "jpeg" ? "jpg" : format;
+            const outputKey = input.outputKey
+                || `renders/vidfarm/stills/${metadata.compositionId}/${renderId}/output.${extension}`;
+            const outputLocation = path.join(config.VIDFARM_DATA_DIR, "storage", outputKey);
+            await mkdir(path.dirname(outputLocation), { recursive: true });
+            if (format === "png") {
+                await cp(firstFramePath, outputLocation, { force: true });
+            }
+            else {
+                // Transcode the captured PNG frame to the requested still format.
+                await runBinary(ffmpegBin, [
+                    "-y",
+                    "-i",
+                    firstFramePath,
+                    ...(format === "jpeg" ? ["-q:v", "3"] : []),
+                    outputLocation
+                ]);
+            }
+            const outputUrl = `${config.PUBLIC_BASE_URL}/storage/${encodeURIComponent(outputKey)}`;
+            devLog("hyperframes.render_still.succeeded", {
+                composition_id: metadata.compositionId,
+                render_id: renderId,
+                image_format: format,
+                output_location: outputLocation
+            });
+            return {
+                renderId,
+                outputUrl,
+                outputLocation,
+                metadata: {
+                    mode: "hyperframes_local_still",
+                    compositionId: metadata.compositionId,
+                    width: metadata.width,
+                    height: metadata.height,
+                    imageFormat: format,
+                    outputKey
+                }
+            };
+        }
+        finally {
+            await rm(framesDir, { recursive: true, force: true });
+        }
+    }
+    async readRenderOutput(outputS3Uri, region) {
+        const parsed = parseS3Uri(outputS3Uri);
+        if (!parsed) {
+            throw new Error(`Invalid HyperFrames output S3 URI: ${outputS3Uri}`);
+        }
+        const s3 = new S3Client({ region: region || config.HYPERFRAMES_RENDER_REGION || config.AWS_REGION });
+        const response = await s3.send(new GetObjectCommand({ Bucket: parsed.bucket, Key: parsed.key }));
+        if (!response.Body) {
+            throw new Error(`HyperFrames output is empty: ${outputS3Uri}`);
+        }
+        return {
+            bytes: Buffer.from(await response.Body.transformToByteArray()),
+            contentType: response.ContentType || "video/mp4"
+        };
+    }
+}
+// Convert a "raw" composition (source video only, no timeline scenes) into a
+// scene-scoped composition by chopping the source video into ~target-second
+// chunks and inserting timeline-proxy divs the editor can drag. This is a
+// deterministic time-based split; smarter AI-frame-based decomposition can
+// replace it later without changing the shape of the produced HTML.
+export function decomposeUndecomposedComposition(html, options) {
+    const { document } = parseHTML(html);
+    const root = document.querySelector("[data-composition-id]");
+    if (!root)
+        return { ok: false, error: "Composition root not found." };
+    const existingProxies = document.querySelectorAll('[data-vf-timeline-proxy="video"]');
+    if (existingProxies.length > 0) {
+        return { ok: false, error: "Composition already has timeline scenes." };
+    }
+    const backingVideo = document.querySelector("[data-vf-playback-source]") ?? document.querySelector("video");
+    const sourceUrl = (backingVideo?.getAttribute("data-src") || backingVideo?.getAttribute("src") || root.getAttribute("data-source-video") || "").trim();
+    if (!sourceUrl)
+        return { ok: false, error: "No source video URL found on the composition." };
+    const durationSeconds = Number.parseFloat(root.getAttribute("data-duration") ?? "");
+    if (!Number.isFinite(durationSeconds) || durationSeconds <= 0) {
+        return { ok: false, error: "Composition data-duration is missing — cannot compute scenes." };
+    }
+    const targetSeconds = options.targetSceneSeconds;
+    const preferredCount = options.requestedScenes ?? Math.max(1, Math.round(durationSeconds / targetSeconds));
+    const sceneCount = Math.min(24, Math.max(1, preferredCount));
+    const rawScene = durationSeconds / sceneCount;
+    for (let index = 0; index < sceneCount; index += 1) {
+        const start = index === 0 ? 0 : Number((index * rawScene).toFixed(3));
+        const end = index === sceneCount - 1 ? durationSeconds : Number(((index + 1) * rawScene).toFixed(3));
+        const duration = Number(Math.max(0.1, end - start).toFixed(3));
+        const proxy = document.createElement("div");
+        const proxyId = shortElementId();
+        proxy.id = proxyId;
+        proxy.setAttribute("data-hf-id", proxyId);
+        proxy.setAttribute("data-layer-mode", "both");
+        proxy.setAttribute("data-layer-kind", "video");
+        proxy.setAttribute("data-viral-note", `Auto-decomposed scene ${index + 1} of ${sceneCount}.`);
+        proxy.setAttribute("data-start", String(start));
+        proxy.setAttribute("data-duration", String(duration));
+        proxy.setAttribute("data-end", String(Number((start + duration).toFixed(3))));
+        proxy.setAttribute("data-track-index", "0");
+        proxy.setAttribute("data-label", `Scene ${index + 1}`);
+        proxy.setAttribute("data-media-start", String(start));
+        proxy.setAttribute("data-playback-start", String(start));
+        proxy.setAttribute("data-vf-timeline-proxy", "video");
+        proxy.setAttribute("data-src", sourceUrl);
+        proxy.setAttribute("style", "position:absolute;left:0%;top:0%;width:1%;height:1%;z-index:0;display:none;pointer-events:none;");
+        proxy.className = "clip";
+        root.append(proxy);
+    }
+    return {
+        ok: true,
+        html: `<!doctype html>\n${document.documentElement.outerHTML}`,
+        sceneCount,
+        durationSeconds
+    };
+}
+// ==========================================================================
+// Smart video decomposition — samples frames from the source, ships them
+// to Gemini vision alongside a strict JSON schema request, and returns the
+// scene bounds + text captions found in the footage.
+// ==========================================================================
+const ffmpegBin = typeof ffmpegStatic === "string" ? ffmpegStatic : ffmpegStatic.path;
+const ffprobeBin = typeof ffprobeStatic.path === "string"
+    ? ffprobeStatic.path
+    : ffprobeStatic;
+// The in-process HyperFrames producer (renderLocal / renderStill) shells out to
+// ffmpeg + ffprobe, resolving them from HYPERFRAMES_FFMPEG_PATH / HYPERFRAMES_FFPROBE_PATH,
+// then bare `ffmpeg`/`ffprobe` on PATH. The api Lambda image ships no ffmpeg on PATH, so
+// point the producer at the bundled ffmpeg-static / ffprobe-static binaries (already
+// resolved above) — otherwise render fails with "ffprobe not found. Please install FFmpeg."
+if (ffmpegBin && !process.env.HYPERFRAMES_FFMPEG_PATH?.trim()) {
+    process.env.HYPERFRAMES_FFMPEG_PATH = ffmpegBin;
+}
+if (ffprobeBin && !process.env.HYPERFRAMES_FFPROBE_PATH?.trim()) {
+    process.env.HYPERFRAMES_FFPROBE_PATH = ffprobeBin;
+}
+const RUN_BINARY_MAX_BUFFER_BYTES = 10 * 1024 * 1024;
+function runBinary(bin, args) {
+    return new Promise((resolve, reject) => {
+        const proc = spawn(bin, args, { stdio: ["ignore", "pipe", "pipe"] });
+        let stdout = "";
+        let stderr = "";
+        let stdoutBytes = 0;
+        let stderrBytes = 0;
+        let settled = false;
+        let killedForOverflow = null;
+        const settle = (fn) => {
+            if (settled)
+                return;
+            settled = true;
+            fn();
+        };
+        const killForOverflow = (stream) => {
+            if (killedForOverflow || settled)
+                return;
+            killedForOverflow = stream;
+            try {
+                proc.kill("SIGKILL");
+            }
+            catch { /* ignore */ }
+            settle(() => reject(new Error(`${path.basename(bin)} ${stream} exceeded ${RUN_BINARY_MAX_BUFFER_BYTES} bytes; killed with SIGKILL.`)));
+        };
+        proc.stdout.on("data", (chunk) => {
+            stdoutBytes += chunk.length;
+            if (stdoutBytes > RUN_BINARY_MAX_BUFFER_BYTES) {
+                killForOverflow("stdout");
+                return;
+            }
+            stdout += chunk.toString();
+        });
+        proc.stderr.on("data", (chunk) => {
+            stderrBytes += chunk.length;
+            if (stderrBytes > RUN_BINARY_MAX_BUFFER_BYTES) {
+                killForOverflow("stderr");
+                return;
+            }
+            stderr += chunk.toString();
+        });
+        proc.on("error", (err) => {
+            settle(() => reject(err));
+        });
+        proc.on("close", (code) => {
+            if (killedForOverflow)
+                return;
+            settle(() => {
+                if (code === 0)
+                    resolve(stdout);
+                else
+                    reject(new Error(`${path.basename(bin)} exited ${code}: ${stderr || stdout}`));
+            });
+        });
+    });
+}
+async function downloadVideoTo(url, dest) {
+    const response = await fetch(url);
+    if (!response.ok || !response.body)
+        throw new Error(`Failed to download ${url}: HTTP ${response.status}`);
+    await pipeline(response.body, createWriteStream(dest));
+}
+async function ffprobeVideo(filePath) {
+    const output = await runBinary(ffprobeBin, [
+        "-v", "error",
+        "-show_entries", "format=duration:stream=width,height",
+        "-of", "json",
+        filePath
+    ]);
+    const parsed = JSON.parse(output || "{}");
+    const stream = (parsed.streams || []).find((s) => s.width && s.height) || {};
+    return {
+        width: Number(stream.width || 0),
+        height: Number(stream.height || 0),
+        durationSeconds: Number(parsed.format?.duration || 0)
+    };
+}
+// Detect hard scene cuts deterministically with ffmpeg's frame-difference
+// scene score, so scene-layer boundaries are grounded in real pixel-level cuts
+// instead of the vision model eyeballing sparse frames and guessing. This is
+// the scene-layer analogue of the OCR pass that grounds caption timing.
+//
+// We run `select='gt(scene,THRESH)'` (score 0..1; higher = bigger visual jump)
+// and dump the selected frames' metadata to a temp file via `metadata=print`.
+// `-f null -` discards the decoded video so stdout stays tiny. Tunable via
+// SCENE_CUT_THRESHOLD (default 0.30). Never throws — cuts are an optional hint,
+// so any failure returns [] and decompose falls back to model-only boundaries.
+async function detectSceneCuts(videoPath, durationSeconds, tempDir) {
+    const thresholdRaw = Number(process.env.SCENE_CUT_THRESHOLD ?? "0.30");
+    const threshold = Number.isFinite(thresholdRaw) && thresholdRaw > 0 && thresholdRaw < 1 ? thresholdRaw : 0.30;
+    const metaPath = path.join(tempDir, "scene-cuts.txt");
+    try {
+        await runBinary(ffmpegBin, [
+            "-y",
+            "-i", videoPath,
+            "-vf", `select='gt(scene,${threshold})',metadata=print:file=${metaPath}`,
+            "-an",
+            "-f", "null",
+            "-"
+        ]);
+    }
+    catch (err) {
+        console.error("scene-cut detection ffmpeg failed", err instanceof Error ? err.message : err);
+        return [];
+    }
+    let raw;
+    try {
+        raw = await readFile(metaPath, "utf8");
+    }
+    catch {
+        // No selected frames (e.g. single continuous take) → file may be absent.
+        return [];
+    }
+    const safeDuration = Number.isFinite(durationSeconds) && durationSeconds > 0 ? durationSeconds : Infinity;
+    const cuts = [];
+    const re = /pts_time:([0-9]+\.?[0-9]*)/g;
+    let match;
+    while ((match = re.exec(raw)) !== null) {
+        const t = Number(match[1]);
+        // Ignore a cut at t≈0 (that's just the first frame, not a boundary) and
+        // anything past the probed duration. Collapse cuts within 0.4s of an
+        // already-recorded one so micro-flicker doesn't over-segment the timeline.
+        if (!Number.isFinite(t) || t < 0.4 || t >= safeDuration - 0.1)
+            continue;
+        if (cuts.length > 0 && t - cuts[cuts.length - 1] < 0.4)
+            continue;
+        cuts.push(Number(t.toFixed(3)));
+    }
+    return cuts;
+}
+// Sample frames for the vision pass. Vision no longer owns caption timing —
+// that's handled deterministically by the dense OCR pass (extractOcrFrames +
+// snapCaptionTimingsToOcr). Vision only needs enough coverage to identify
+// which captions exist, their text, style, and rough scene boundaries. Keep
+// the cadence around 1 fps with a low ceiling to control token cost. Frames
+// stay at 960px wide so small overlay text is legible for the LLM.
+//
+// Uses a single ffmpeg invocation with `-vf fps=…` — the previous per-frame
+// spawn loop occasionally left individual output files unwritten when the
+// seek raced a demux edge case, producing ENOENT reads. Batched extraction
+// is also ~10× faster.
+async function sampleFramesAsBase64(videoPath, durationSeconds, tempDir) {
+    const safeDuration = Number.isFinite(durationSeconds) && durationSeconds > 0 ? durationSeconds : 5;
+    const MIN_FRAMES = 8;
+    // Denser + sharper than before (was 14 / 960px / q3 / 1.0fps). More frames
+    // catch more scene transitions and short-lived captions; higher resolution +
+    // lower JPEG quantization keep thin overlay glyphs legible for the model.
+    const MAX_FRAMES = 18;
+    const targetPerSecond = 1.2;
+    const desired = Math.round(safeDuration * targetPerSecond);
+    const frameCount = Math.min(MAX_FRAMES, Math.max(MIN_FRAMES, desired));
+    if (frameCount <= 0)
+        return [];
+    const effectiveInterval = safeDuration / frameCount;
+    const outDir = path.join(tempDir, "vision-frames");
+    await mkdir(outDir, { recursive: true });
+    const outPattern = path.join(outDir, "frame-%04d.jpg");
+    const fps = 1 / effectiveInterval;
+    await runBinary(ffmpegBin, [
+        "-y",
+        "-i", videoPath,
+        "-vf", `fps=${fps.toFixed(6)},scale=1120:-2`,
+        "-q:v", "2",
+        "-vframes", String(frameCount),
+        outPattern
+    ]);
+    const results = [];
+    for (let i = 0; i < frameCount; i += 1) {
+        const framePath = path.join(outDir, `frame-${String(i + 1).padStart(4, "0")}.jpg`);
+        let buf;
+        try {
+            buf = await readFile(framePath);
+        }
+        catch {
+            // ffmpeg may emit fewer frames than requested for very short/edge-case
+            // videos; skip missing frames instead of throwing so the vision pass
+            // still runs with whatever we got.
+            continue;
+        }
+        const timestamp = Math.min(safeDuration - 0.01, Math.max(0.01, i * effectiveInterval + effectiveInterval / 2));
+        results.push({ timestamp: Number(timestamp.toFixed(3)), data: buf.toString("base64") });
+    }
+    return results;
+}
+// Extract frames at a dense fixed interval for OCR — this is what actually
+// grounds caption start/end timing. Interval defaults to 0.5s; tunable via
+// OCR_FRAME_INTERVAL_SECONDS. Cap total frames so a 5-minute video doesn't
+// fan out into hundreds of OCR calls.
+//
+// IMPORTANT: uses a SINGLE ffmpeg invocation with `-vf fps=…` to write all
+// frames in one pass. The previous per-frame ffmpeg spawn loop was ~1s per
+// frame and pushed 30s videos past the 60s CloudFront timeout on their own.
+async function extractDenseOcrFrames(videoPath, durationSeconds, tempDir) {
+    const intervalRaw = Number(process.env.OCR_FRAME_INTERVAL_SECONDS ?? "0.5");
+    const interval = Number.isFinite(intervalRaw) && intervalRaw > 0 ? Math.max(0.1, intervalRaw) : 0.5;
+    const maxFramesRaw = Number(process.env.OCR_MAX_FRAMES ?? "60");
+    const maxFrames = Number.isFinite(maxFramesRaw) && maxFramesRaw > 0 ? Math.floor(maxFramesRaw) : 60;
+    const safeDuration = Number.isFinite(durationSeconds) && durationSeconds > 0 ? durationSeconds : 5;
+    const totalDesired = Math.max(1, Math.floor(safeDuration / interval));
+    const totalFrames = Math.min(maxFrames, totalDesired);
+    if (totalFrames <= 0)
+        return [];
+    const effectiveInterval = safeDuration / totalFrames;
+    const outDir = path.join(tempDir, "ocr-frames");
+    await mkdir(outDir, { recursive: true });
+    const outPattern = path.join(outDir, "ocr-%04d.jpg");
+    const fps = 1 / effectiveInterval;
+    await runBinary(ffmpegBin, [
+        "-y",
+        "-i", videoPath,
+        // fps filter samples at the target rate; scale keeps the frame small
+        // enough that token cost stays down while text stays readable.
+        "-vf", `fps=${fps.toFixed(6)},scale=640:-2`,
+        "-q:v", "5",
+        "-vframes", String(totalFrames),
+        outPattern
+    ]);
+    const results = [];
+    for (let i = 0; i < totalFrames; i += 1) {
+        const framePath = path.join(outDir, `ocr-${String(i + 1).padStart(4, "0")}.jpg`);
+        let buf;
+        try {
+            buf = await readFile(framePath);
+        }
+        catch {
+            // ffmpeg may emit fewer frames than requested for very short videos
+            // (rounding). Stop cleanly instead of throwing.
+            break;
+        }
+        // Frame N (1-indexed) captures roughly at the midpoint of its interval.
+        const timestamp = Math.min(safeDuration - 0.01, Math.max(0.01, i * effectiveInterval + effectiveInterval / 2));
+        results.push({ timestamp: Number(timestamp.toFixed(3)), data: buf.toString("base64") });
+    }
+    return results;
+}
+// Prompt the vision model to return ONLY the overlay text visible in each
+// frame, verbatim, no interpretation. This is intentionally narrow so the
+// model behaves as an OCR engine rather than doing scene analysis (which
+// the sparse vision pass already handles).
+function buildOcrBatchPrompt(frames) {
+    const frameList = frames
+        .map((f, i) => `  ${i + 1}. frame @ ${f.timestamp.toFixed(2)}s`)
+        .join("\n");
+    return `You are an OCR engine. For each of the following ${frames.length} video frames, return every piece of overlay/caption text that appears in the image. Ignore any text that is part of the background scenery (signs, packaging, phone UIs, watermarks). Only report captions/subtitles/CTAs that were added on top of the video.
+
+Return ONLY strictly valid JSON with this schema:
+{
+  "frames": [
+    { "index": 1, "timestamp": <seconds>, "texts": ["exact text line 1", "exact text line 2"] },
+    ...
+  ]
+}
+
+Rules:
+- One entry per frame, in the same order given below.
+- "texts" is an array of text lines exactly as they appear (preserve case, punctuation, emoji). Split multi-line captions into one string per visible line.
+- If a frame has no overlay text, "texts" MUST be [].
+- Do NOT paraphrase, translate, or "clean up" text. Verbatim only.
+- Do NOT hallucinate text that isn't clearly visible.
+
+FRAMES (in order):
+${frameList}`;
+}
+// Run the dense frames through the same vision fallback chain that
+// smartDecomposeVideo uses. Batches ~8 frames per call to bound token cost
+// per request while keeping request count low. Any batch that fails is
+// dropped — downstream code falls back to vision-provided timing for
+// captions that don't get an OCR match, so partial OCR is still useful.
+async function runOcrPass(input) {
+    // Larger batches + higher concurrency keep the total OCR wall-time under
+    // the 60s CloudFront read timeout for typical 28s vertical videos (56
+    // dense frames). Gemini handles 12 image inputs per call fine and the
+    // extra parallelism means 56 frames finish in ~1 round of 5 concurrent
+    // batches instead of 2 rounds of 3.
+    const BATCH_SIZE = 12;
+    const CONCURRENCY = 5;
+    const batches = [];
+    for (let i = 0; i < input.frames.length; i += BATCH_SIZE) {
+        batches.push(input.frames.slice(i, i + BATCH_SIZE));
+    }
+    const results = [];
+    for (let i = 0; i < batches.length; i += CONCURRENCY) {
+        const slice = batches.slice(i, i + CONCURRENCY);
+        const settled = await Promise.allSettled(slice.map(async (batch) => {
+            const prompt = buildOcrBatchPrompt(batch);
+            const attempt = await callVisionWithFallback({ prompt, frames: batch, keys: input.keys });
+            const record = (attempt.result && typeof attempt.result === "object") ? attempt.result : {};
+            const framesRaw = Array.isArray(record.frames) ? record.frames : [];
+            const parsed = [];
+            for (let idx = 0; idx < batch.length; idx += 1) {
+                const entry = framesRaw[idx];
+                const timestamp = batch[idx].timestamp;
+                const textsRaw = entry && Array.isArray(entry.texts) ? entry.texts : [];
+                const texts = textsRaw
+                    .map((t) => (typeof t === "string" ? t : ""))
+                    .filter((t) => t.trim().length > 0);
+                parsed.push({ timestamp, texts });
+            }
+            return parsed;
+        }));
+        for (const s of settled) {
+            if (s.status === "fulfilled") {
+                results.push(...s.value);
+            }
+            else {
+                console.error("smart decompose OCR batch failed", s.reason instanceof Error ? s.reason.message : s.reason);
+            }
+        }
+    }
+    results.sort((a, b) => a.timestamp - b.timestamp);
+    return results;
+}
+function normalizeForOcrMatch(text) {
+    return text
+        .toLowerCase()
+        .replace(/[\u2018\u2019\u201C\u201D]/g, "'")
+        .replace(/[^\p{Letter}\p{Number}\s]/gu, " ")
+        .replace(/\s+/g, " ")
+        .trim();
+}
+// Overlap ratio: what fraction of the caption's significant words appear in
+// the frame's concatenated OCR text? Stopwords-free would be nicer but for
+// short-form video captions ("single", "have kids", "buy my course") the
+// full word list is fine and simpler.
+function captionOverlapWithFrame(captionText, frame) {
+    const captionWords = normalizeForOcrMatch(captionText).split(" ").filter((w) => w.length >= 2);
+    if (captionWords.length === 0)
+        return 0;
+    const frameText = " " + normalizeForOcrMatch(frame.texts.join(" ")) + " ";
+    if (frameText.trim().length === 0)
+        return 0;
+    let hits = 0;
+    for (const word of captionWords) {
+        if (frameText.includes(" " + word + " "))
+            hits += 1;
+    }
+    return hits / captionWords.length;
+}
+// For each vision-detected caption, find the contiguous run of OCR frames
+// where the caption's text is present, and snap start/duration to that run.
+// If no OCR match is confident enough, keep the vision-provided timing
+// (graceful degradation).
+function snapCaptionTimingsToOcr(input) {
+    if (input.ocrFrames.length === 0) {
+        return { captions: input.captions, snappedCount: 0 };
+    }
+    const MATCH_THRESHOLD = 0.6;
+    // Half the median inter-frame gap — used to extend duration past the last
+    // matching frame since the caption presumably stayed on-screen partway
+    // into the next (non-matching) frame.
+    const gaps = [];
+    for (let i = 1; i < input.ocrFrames.length; i += 1) {
+        gaps.push(input.ocrFrames[i].timestamp - input.ocrFrames[i - 1].timestamp);
+    }
+    const sortedGaps = gaps.slice().sort((a, b) => a - b);
+    const medianGap = sortedGaps.length > 0 ? sortedGaps[Math.floor(sortedGaps.length / 2)] : 0.5;
+    const halfGap = Math.max(0.05, medianGap / 2);
+    let snappedCount = 0;
+    const snapped = input.captions.map((caption) => {
+        const scores = input.ocrFrames.map((frame) => captionOverlapWithFrame(caption.text, frame));
+        const matchIndexes = scores
+            .map((s, i) => ({ s, i }))
+            .filter((x) => x.s >= MATCH_THRESHOLD)
+            .map((x) => x.i);
+        if (matchIndexes.length === 0) {
+            return caption;
+        }
+        // Pick the contiguous run whose midpoint is closest to the vision-
+        // provided midpoint. This handles the case of a repeated caption
+        // (same text shown twice with a gap in between) by choosing the
+        // occurrence the vision pass was pointing at.
+        const runs = [];
+        let runStart = matchIndexes[0];
+        let prev = matchIndexes[0];
+        for (let i = 1; i < matchIndexes.length; i += 1) {
+            const idx = matchIndexes[i];
+            if (idx - prev <= 2) {
+                prev = idx;
+            }
+            else {
+                runs.push({ start: runStart, end: prev });
+                runStart = idx;
+                prev = idx;
+            }
+        }
+        runs.push({ start: runStart, end: prev });
+        const visionMid = caption.start + caption.duration / 2;
+        const bestRun = runs.reduce((best, r) => {
+            const runMid = (input.ocrFrames[r.start].timestamp + input.ocrFrames[r.end].timestamp) / 2;
+            const bestMid = (input.ocrFrames[best.start].timestamp + input.ocrFrames[best.end].timestamp) / 2;
+            return Math.abs(runMid - visionMid) < Math.abs(bestMid - visionMid) ? r : best;
+        }, runs[0]);
+        const firstTs = input.ocrFrames[bestRun.start].timestamp;
+        const lastTs = input.ocrFrames[bestRun.end].timestamp;
+        const newStart = Math.max(0, firstTs - halfGap);
+        const newEnd = Math.min(input.durationSeconds, lastTs + halfGap);
+        const newDuration = Math.max(0.1, newEnd - newStart);
+        snappedCount += 1;
+        return {
+            ...caption,
+            start: Number(newStart.toFixed(3)),
+            duration: Number(newDuration.toFixed(3))
+        };
+    });
+    return { captions: snapped, snappedCount };
+}
+// Snap vision-provided scene boundaries onto ffmpeg-detected hard cuts, the
+// scene-layer analogue of snapCaptionTimingsToOcr. Each scene "start" that
+// falls within TOLERANCE of a detected cut is pulled exactly onto that cut;
+// durations are then recomputed so scenes stay contiguous and still cover the
+// full duration (start[0] forced to 0, last scene extended to the end). If no
+// cuts were detected the scenes are returned unchanged.
+function snapScenesToCuts(input) {
+    if (input.cuts.length === 0 || input.scenes.length === 0) {
+        return { scenes: input.scenes, snappedCount: 0 };
+    }
+    const TOLERANCE = 0.6;
+    const sorted = [...input.scenes].sort((a, b) => a.start - b.start);
+    let snappedCount = 0;
+    const snappedStarts = sorted.map((scene, index) => {
+        if (index === 0)
+            return 0; // first scene always starts at 0
+        let nearest = scene.start;
+        let bestDelta = TOLERANCE;
+        for (const cut of input.cuts) {
+            const delta = Math.abs(cut - scene.start);
+            if (delta < bestDelta) {
+                bestDelta = delta;
+                nearest = cut;
+            }
+        }
+        if (nearest !== scene.start)
+            snappedCount += 1;
+        return nearest;
+    });
+    const rebuilt = sorted.map((scene, index) => {
+        const start = Number(snappedStarts[index].toFixed(3));
+        const nextStart = index + 1 < snappedStarts.length ? snappedStarts[index + 1] : input.durationSeconds;
+        const duration = Math.max(0.1, Number((nextStart - start).toFixed(3)));
+        return { ...scene, start, duration };
+    }).filter((s) => s.duration > 0.05);
+    return { scenes: rebuilt, snappedCount };
+}
+// Product-AGNOSTIC placement-surface prompt. Deliberately does NOT know the
+// user's product — it enumerates reusable slots where any product could later
+// be inserted. The product-SPECIFIC pitch stays the on-demand
+// brainstorm_product_placement primitive, which these surfaces can seed.
+function buildPlacementSurfacePrompt(input) {
+    const frameListing = input.frameTimestamps.length > 0
+        ? `\nFRAMES SUPPLIED (in order, each captioned with its capture timestamp):\n${input.frameTimestamps.map((t, i) => `  frame ${i + 1} @ ${t.toFixed(2)}s`).join("\n")}\n`
+        : "";
+    const sceneSlugList = input.sceneSlugs.length > 0
+        ? `\nSCENE SLUGS (link each surface to the closest one via "scene_slug"): ${input.sceneSlugs.join(", ")}\n`
+        : "";
+    return `You are Vidfarm's native-advertising product-placement scout. You are studying a short-form vertical video (TikTok/Reel) to find natural PLACEMENT SURFACES — moments and spots where a product could later be inserted so it feels native, not bolted on.
+
+CRITICAL: You do NOT know the product yet. Do NOT invent a specific product. Describe the SLOT itself (what is physically/attention-wise available), and list the KINDS of products that would fit. Think of this as reusable metadata that a later, product-specific pass will draw from.
+
+Video duration: ${input.durationSeconds.toFixed(2)} seconds.
+${frameListing}${sceneSlugList}
+Return strictly valid JSON matching this schema:
+{
+  "surfaces": [{
+    "slug": string,
+    "timestamp": string,
+    "start": number,
+    "scene_slug": string,
+    "surface_type": string,
+    "surface_note": string,
+    "best_for": [string, ...],
+    "why_it_works": string
+  }]
+}
+
+RULES:
+- Identify 3-8 distinct surfaces, ordered strongest to weakest. Each must reference a real moment you actually see in the frames.
+- "slug": short snake_case role label, e.g. "desk_prop_slot", "phone_screen_swap", "hand_held_reveal", "b_roll_cutaway", "end_card_cta". Unique.
+- "timestamp": human range like "0:04" or "0:12-0:18". "start": the numeric seconds (float) where the surface begins — use it for editor targeting.
+- "scene_slug": the closest scene slug from the list above (or "" if none given).
+- "surface_type": one of prop | set_dressing | screen_ui | verbal_mention | caption_overlay | sticker_lower_third | b_roll_cutaway | apparel | before_after_demo | end_card.
+- "surface_note": describe the SLOT product-agnostically — what is physically there and how long it holds (e.g. "empty desk surface faces camera, unobstructed for ~2s", "subject holds phone screen toward camera", "blank wall behind subject at chest height").
+- "best_for": 2-4 product/offer CATEGORIES that would fit this slot naturally (e.g. "beverage/snack brand", "SaaS dashboard", "skincare bottle", "mobile app UI"). Categories, never a specific brand.
+- "why_it_works": the attention/emotion/story logic that makes a placement here land.
+- Bias toward surfaces that ride existing attention or story beats. If the video genuinely has no natural surface, return "surfaces": []. Never fabricate.`;
+}
+function normalizePlacementSurfaces(raw) {
+    const record = (raw && typeof raw === "object") ? raw : {};
+    const surfacesRaw = Array.isArray(record.surfaces) ? record.surfaces : [];
+    const usedSlugs = new Set();
+    return surfacesRaw
+        .map((s, index) => {
+        const slug = dedupeSlug(normalizeSlug(typeof s.slug === "string" ? s.slug : `surface_${index + 1}`) || `surface_${index + 1}`, usedSlugs);
+        const bestForRaw = Array.isArray(s.best_for) ? s.best_for : [];
+        const best_for = bestForRaw
+            .map((b) => (typeof b === "string" ? b.trim() : ""))
+            .filter((b) => b.length > 0)
+            .slice(0, 6);
+        return {
+            slug,
+            timestamp: typeof s.timestamp === "string" ? s.timestamp : "",
+            start: Number.isFinite(Number(s.start)) ? Number(Number(s.start).toFixed(3)) : 0,
+            scene_slug: typeof s.scene_slug === "string" ? normalizeSlug(s.scene_slug) : "",
+            surface_type: typeof s.surface_type === "string" ? s.surface_type : "prop",
+            surface_note: typeof s.surface_note === "string" ? s.surface_note : "",
+            best_for,
+            why_it_works: typeof s.why_it_works === "string" ? s.why_it_works : ""
+        };
+    })
+        .filter((s) => s.surface_note.trim().length > 0);
+}
+// Isolated placement-surface vision call. Reuses the SAME sparse frames already
+// sampled for the main pass — no extra ffmpeg — and runs as its own request so
+// it can never dilute the caption/scene call's attention budget. Non-fatal:
+// callers wrap in .catch(() => []).
+async function runPlacementSurfacePass(input) {
+    if (input.frames.length === 0)
+        return [];
+    const prompt = buildPlacementSurfacePrompt({
+        durationSeconds: input.durationSeconds,
+        frameTimestamps: input.frames.map((f) => f.timestamp),
+        sceneSlugs: input.sceneSlugs
+    });
+    const attempt = await callVisionWithFallback({ prompt, frames: input.frames, keys: input.keys });
+    return normalizePlacementSurfaces(attempt.result);
+}
+function buildSmartDecomposePrompt(input) {
+    const sceneCutHint = input.sceneCuts && input.sceneCuts.length > 0
+        ? `\nDETECTED SCENE CUTS (authoritative — ffmpeg measured hard visual cuts at these timestamps, in seconds):\n${input.sceneCuts.map((t) => `  cut @ ${t.toFixed(2)}s`).join("\n")}\n\nThese are ground truth for where the video visually changes. Align scene boundaries to these cuts: each detected cut should begin a new scene (a scene "start" should equal a detected cut time, within ~0.15s), and do NOT place a scene boundary where there is no detected cut unless the frames clearly show a change the detector missed. If two adjacent cuts are very close and belong to the same beat, you may merge them into one scene, but never exceed 6 scenes.\n`
+        : "";
+    const userGuidance = input.userPrompt && input.userPrompt.trim().length > 0
+        ? `\nUSER GUIDANCE (highest priority — pay special attention to this when deciding scenes, captions, and viral_dna):\n"""\n${input.userPrompt.trim()}\n"""\n`
+        : "";
+    const trendTaglineHint = input.trendTaglineHint && input.trendTaglineHint.trim().length > 0
+        ? `\nTREND TAGLINE (caller-supplied, use verbatim as viral_dna.trend_tagline — do NOT rephrase):\n"""\n${input.trendTaglineHint.trim()}\n"""\n`
+        : "";
+    const frameListing = input.frameTimestamps.length > 0
+        ? `\nFRAMES SUPPLIED (in order — each image is captioned with its capture timestamp):\n${input.frameTimestamps.map((t, i) => `  frame ${i + 1} @ ${t.toFixed(2)}s`).join("\n")}\n\nUse the frame timestamps to determine caption "start" and "duration". Cross-reference consecutive frames: a caption whose text is identical across frames N and M was on-screen from at least the timestamp of frame N through the timestamp of frame M (extend "duration" accordingly). A caption present in only one frame is short-lived — set duration to roughly (next_frame_timestamp - this_frame_timestamp) or 0.8s, whichever is smaller.\n`
+        : "";
+    return `You are decomposing a short-form vertical video (TikTok/Reel) into editable HyperFrames timeline layers.
+${userGuidance}${trendTaglineHint}
+Video metadata:
+- duration: ${input.durationSeconds.toFixed(3)} seconds
+- dimensions: ${input.width} x ${input.height} (9:16 vertical, canvas is 100% x 100%)
+${frameListing}${sceneCutHint}
+
+Return strictly valid JSON matching this schema:
+{
+  "summary": string,
+  "viral_dna": {
+    "trend_tagline": string,
+    "hook": string,
+    "retention": string,
+    "payoff": string,
+    "preserve": [string, ...],
+    "avoid": [string, ...],
+    "promotions": [string, ...],
+    "keywords": [string, ...]
+  },
+  "scenes": [{
+    "slug": string,
+    "start": number,
+    "duration": number,
+    "label": string,
+    "description": string,
+    "viral_note": string
+  }],
+  "captions": [{
+    "slug": string,
+    "text": string,
+    "start": number,
+    "duration": number,
+    "x": number,
+    "y": number,
+    "width": number,
+    "height": number,
+    "font_size_percent": number,
+    "font_size": number,
+    "color": string,
+    "background": string,
+    "background_style": "plain" | "outline" | "highlight-solid" | "highlight-translucent",
+    "font_family": string,
+    "font_weight": number,
+    "viral_note": string
+  }]
+}
+
+VIRAL_DNA RULES:
+- "trend_tagline": a short (3-8 word) semantic identifier for the underlying trend/format itself, NOT this specific video's topic. Think of it as the label a scroller would use to categorize the format (e.g., "green-screen news debunk", "day-in-the-life sped-up montage", "best-at-what-cost destination reveal", "pinned-comment dance dare"). If the caller pre-supplied a trend_tagline (see USER GUIDANCE), preserve it verbatim; otherwise generate one.
+- "hook": the 1-sentence tactic used in the first 1-2 seconds to stop the scroll (e.g., "Pinned comment screenshot dares the viewer to keep watching").
+- "retention": how the middle of the video keeps attention (visual cuts, pattern loops, escalating stakes).
+- "payoff": what the viewer earns at the end (reveal, punchline, transformation).
+- "preserve": 3-5 concrete elements a remixer MUST keep to preserve the format (e.g., "Pinned comment stays on-screen the whole video", "Wedding dance payoff shot").
+- "avoid": 3-5 things that would break the format if changed (e.g., "Do not remove the on-screen text overlay", "Do not slow the cuts below 1.5s").
+- "promotions": 3-5 categories of product / service / offer this exact format could be reused to promote, WITHOUT changing the beat structure or hook mechanic. Each item is a concrete pitchable use-case, not a genre. Examples: "SaaS free-trial signup (before/after workflow)", "Fitness challenge (7-day transformation)", "Local restaurant grand-opening (line-out-the-door proof)", "Ebook / course launch (result-first payoff)", "Real-estate open-house (walk-through reveal)". Anchor each promotion to the same viral tactic captured in "hook" — do not invent unrelated verticals.
+- "keywords": 6-12 lowercase search terms that make this format discoverable when a marketer describes their product/offer in their own words. Include the niches, target audiences, product categories, outcomes, and emotions this format naturally sells to — plus obvious synonyms a user might type. Think about what a customer would search: e.g. for a before/after fitness format include "weight loss", "fitness", "gym", "transformation", "before after", "health app", "diet", "body goals", "wellness". Single words or 2-3 word phrases, no punctuation, no duplicates. These are for matching only, so bias toward the words a customer would use, not jargon.
+- Use short imperative fragments in preserve/avoid arrays. Never leave empty — infer from the frames if unstated.
+
+SCENE RULES:
+- 2 to 6 scenes covering the FULL duration; contiguous (scene[i].start = scene[i-1].start + scene[i-1].duration); first scene starts at 0.0; last scene ends at ${input.durationSeconds.toFixed(3)}.
+- Every scene MUST include a "description": 1-3 plain sentences literally describing what is happening on screen during that scene — setting, subjects, their actions, camera movement/framing, and any notable visual changes (cuts, zooms, transitions, product shots). Describe only what a viewer literally sees in the frames; do NOT repeat viral_note commentary, marketing analysis, or audio content here.
+
+SLUG RULES:
+- Every scene AND every caption MUST have a "slug": short snake_case (2-4 words) describing its ROLE in the viral structure. Unique within scenes; unique within captions. Examples: "hook_reveal", "problem_setup", "payoff_context", "cta_follow", "caption_hook_dare".
+
+CAPTION RULES (CRITICAL — this is the primary use of vision on this task):
+- Inspect EVERY supplied frame. Enumerate EVERY distinct visible text overlay across all frames — hooks, dialog subtitles, hashtags, usernames, handles, brand tags, CTAs, sticker text, arrow labels, price tags, meme text, comment-screenshot text, product names — anything rendered as text on the pixels.
+- One caption = one visually distinct text block. If two lines share the same visual treatment and appear together as one overlay, keep them as ONE caption with "\\n" between the lines. If two blocks look different (different font, color, position, or independent timing), they are SEPARATE captions.
+- Preserve text VERBATIM. Copy spelling, punctuation, casing, emojis, and line breaks exactly as they appear. Do NOT paraphrase, normalize casing, translate, or "clean up" spacing. If a caption contains a typo, keep the typo.
+- The SAME text overlay that persists across multiple sampled frames is ONE caption with a longer duration — do NOT emit one caption per frame. Merge by (identical text + roughly same on-screen position + same visual style).
+- If a caption changes text mid-clip (e.g. rolling subtitle updates), emit each version as a separate caption with its own tight start/duration.
+- Position numbers (x, y, width, height) must reflect where the text ACTUALLY sits in the frame — measure the bounding box, don't guess. Vertical (9:16) captions almost never span x=0..100; hooks near y=8-18, dialog near y=60-72, CTAs near y=80-88.
+- If no visible text overlays exist across ANY frame, return "captions": []. NEVER invent text. NEVER hallucinate captions from audio or context.
+- Prioritize completeness. Missing an on-screen caption is a worse failure than emitting an extra minor one.
+
+FONT_FAMILY (choose ONE, match visual appearance):
+- "TikTok Sans" — clean sans-serif (DEFAULT if unsure). Rounded, modern.
+- "Montserrat" — geometric bold sans. Common on IG/TikTok bold captions.
+- "Source Code Pro" — monospaced. For code/terminal aesthetic.
+- "Yesteryear" — cursive script. For quotes / romantic vibes.
+- "Georgia" — serif. For editorial / news look.
+- "Abel" — condensed sans. Newsletter/headline vibe.
+- Return exactly one of the above six strings. If unsure, return "TikTok Sans".
+
+FONT_WEIGHT (integer):
+- 400 for normal weight
+- 600 for semibold (typical TikTok caption look)
+- 700 for bold (heavy captions)
+- 800 or 900 for ultra-black display text
+
+FONT_SIZE — return TWO numbers, both required. The renderer uses font_size_percent to survive canvas resizes.
+- "font_size_percent" (float 1.0–15.0): the caption glyph height as a percent of canvas height (${input.height || 1280}px). This is the SOURCE OF TRUTH. Measure a single-line uppercase-height letter (like an "M" or "H") in the actual frame and divide by canvas height, times 100.
+  - Tiny UI / hashtag row: 1.2–2.0
+  - Standard TikTok caption (dialog line): 2.0–3.2
+  - Standard hook caption (readable but not screaming): 3.2–5.0
+  - Bold hook overlay filling a wide band: 5.0–8.0
+  - Giant kinetic display / meme text: 8.0–12.0
+- "font_size" (integer pixels): compute as round(font_size_percent / 100 * ${input.height || 1280}). Include it for redundancy.
+- Do NOT default to 24. Measure the actual on-screen glyph height. When unsure between two ranges, pick the one closest to what you actually measure — do not over-inflate.
+- Give the SAME caption the SAME font_size — do not vary between instances.
+
+COLOR (hex "#rrggbb"):
+- Pure white: "#ffffff" (most common TikTok captions)
+- Pure black: "#000000"
+- Bright yellow (highlight text): "#ffe600"
+- Match the actual on-screen color as closely as you can. Never return names like "white"; always hex.
+
+BACKGROUND_STYLE (choose ONE):
+- "plain" — no visible pill/outline. Just letters over the video. (Most common.)
+- "outline" — thin dark outline around each glyph (for legibility over busy video).
+- "highlight-solid" — a solid colored pill / block behind the text (typical TikTok white-on-black caption card).
+- "highlight-translucent" — semi-transparent pill.
+- BACKGROUND ("#rrggbb") is the pill / outline color. For "plain" this is unused but still return a valid hex like "#000000".
+
+POSITION (percent 0-100, floats OK):
+- x, y = top-left corner of the caption's bounding box relative to the canvas.
+- width, height = its bounding box size.
+- TikTok baked captions are usually centered horizontally: x ≈ 5-10, width ≈ 80-90.
+- Vertical placement: hook captions near top (y ≈ 8-18); dialog/subtitle mid-lower (y ≈ 60-72); brand tag / cta bottom (y ≈ 80-88).
+- Height should roughly match font_size and line count.
+
+TIMING RULES:
+- start, duration are seconds (floats). start >= 0. start + duration <= ${input.durationSeconds.toFixed(3)}.
+
+OUTPUT: pure JSON, no prose, no markdown fences.`;
+}
+const ALLOWED_FONTS = [
+    "TikTok Sans", "Montserrat", "Source Code Pro", "Yesteryear", "Georgia", "Abel"
+];
+const ALLOWED_BG_STYLES = [
+    "plain", "outline", "highlight-solid", "highlight-translucent"
+];
+function normalizeFontFamily(value) {
+    if (typeof value !== "string")
+        return "TikTok Sans";
+    const trimmed = value.trim();
+    const match = ALLOWED_FONTS.find((font) => font.toLowerCase() === trimmed.toLowerCase());
+    return match ?? "TikTok Sans";
+}
+function normalizeHexColor(value, fallback) {
+    if (typeof value !== "string")
+        return fallback;
+    const trimmed = value.trim();
+    if (/^#[0-9a-fA-F]{6}$/.test(trimmed))
+        return trimmed.toLowerCase();
+    if (/^#[0-9a-fA-F]{3}$/.test(trimmed)) {
+        const [, r, g, b] = /^#([0-9a-fA-F])([0-9a-fA-F])([0-9a-fA-F])$/.exec(trimmed) ?? [];
+        return `#${r}${r}${g}${g}${b}${b}`.toLowerCase();
+    }
+    return fallback;
+}
+function normalizeBackgroundStyle(value) {
+    if (typeof value !== "string")
+        return "plain";
+    const lowered = value.trim().toLowerCase();
+    const match = ALLOWED_BG_STYLES.find((style) => style === lowered);
+    return match ?? "plain";
+}
+// Convert a #rrggbb hex to an rgba(...) string with the given alpha. Falls back
+// to a solid dark backing if the hex is malformed so the caption still stays
+// legible.
+function hexToRgba(hex, alpha) {
+    const match = /^#([0-9a-f]{6})$/i.exec(String(hex ?? "").trim());
+    if (!match)
+        return `rgba(0,0,0,${alpha})`;
+    const value = match[1];
+    const r = parseInt(value.slice(0, 2), 16);
+    const g = parseInt(value.slice(2, 4), 16);
+    const b = parseInt(value.slice(4, 6), 16);
+    return `rgba(${r},${g},${b},${alpha})`;
+}
+// Builds the inline-span CSS for a caption based on its background_style so
+// captions actually render with the visual treatment the vision LLM extracted
+// ("outline" gets a real text stroke; "highlight-*" gets a colored pill).
+// Without this the span just had `color:#fff` and everything looked washed
+// out over the video.
+function captionInlineTextStyle(caption) {
+    const parts = [`color:${caption.color}`];
+    const strokeColor = caption.background && /^#[0-9a-f]{6}$/i.test(caption.background)
+        ? caption.background
+        : "#000000";
+    // Outline width scales with font size so small captions still get a
+    // visible edge. Clamp so it never disappears (1px) and never eats the
+    // glyph interior (5px).
+    const strokePx = Math.max(1, Math.min(5, Math.round(caption.font_size * 0.06)));
+    switch (caption.background_style) {
+        case "outline":
+            parts.push(`-webkit-text-stroke:${strokePx}px ${strokeColor}`, `paint-order:stroke fill`, 
+            // text-shadow fallback for renderers that ignore paint-order.
+            `text-shadow:0 0 ${strokePx}px ${strokeColor}, ${strokePx}px ${strokePx}px 0 ${strokeColor}, -${strokePx}px ${strokePx}px 0 ${strokeColor}, ${strokePx}px -${strokePx}px 0 ${strokeColor}, -${strokePx}px -${strokePx}px 0 ${strokeColor}`);
+            break;
+        case "highlight-solid":
+            parts.push(`background:${strokeColor}`, `padding:0.18em 0.5em`, `border-radius:0.35em`, `box-decoration-break:clone`, `-webkit-box-decoration-break:clone`);
+            break;
+        case "highlight-translucent":
+            parts.push(`background:${hexToRgba(strokeColor, 0.55)}`, `padding:0.18em 0.5em`, `border-radius:0.35em`, `box-decoration-break:clone`, `-webkit-box-decoration-break:clone`);
+            break;
+        case "plain":
+        default:
+            // Even "plain" captions need SOME shadow over busy TikTok footage or
+            // white-on-white becomes invisible. Use a subtle drop shadow that
+            // doesn't read as an intentional outline.
+            parts.push(`text-shadow:0 1px 2px rgba(0,0,0,0.55), 0 0 3px rgba(0,0,0,0.35)`);
+            break;
+    }
+    return parts.join(";");
+}
+function normalizeFontWeight(value) {
+    const parsed = Number(value);
+    if (!Number.isFinite(parsed))
+        return 600;
+    const clamped = Math.max(100, Math.min(900, Math.round(parsed / 100) * 100));
+    return clamped;
+}
+function normalizeFontSize(value, canvasHeight) {
+    const parsed = Number(value);
+    const heightRef = canvasHeight > 0 ? canvasHeight : 1280;
+    if (!Number.isFinite(parsed) || parsed <= 0)
+        return Math.round(heightRef * 0.028);
+    return Math.max(10, Math.min(160, Math.round(parsed)));
+}
+function resolveFontSize(input) {
+    const heightRef = input.canvasHeight > 0 ? input.canvasHeight : 1280;
+    const percent = Number(input.fontSizePercent);
+    if (Number.isFinite(percent) && percent > 0) {
+        const clampedPct = Math.max(0.8, Math.min(15, percent));
+        return Math.max(10, Math.min(160, Math.round((clampedPct / 100) * heightRef)));
+    }
+    return normalizeFontSize(input.fontSize, input.canvasHeight);
+}
+const DEFAULT_VIRAL_DNA = {
+    trend_tagline: "", hook: "", retention: "", payoff: "", preserve: [], avoid: [], promotions: [], keywords: []
+};
+function normalizeViralDna(value) {
+    if (!value || typeof value !== "object")
+        return DEFAULT_VIRAL_DNA;
+    const record = value;
+    const asString = (v) => typeof v === "string" ? v.trim() : "";
+    const asStringArray = (v) => Array.isArray(v)
+        ? v.map((item) => (typeof item === "string" ? item.trim() : "")).filter((item) => item.length > 0)
+        : [];
+    return {
+        trend_tagline: asString(record.trend_tagline ?? record.trendTagline),
+        hook: asString(record.hook),
+        retention: asString(record.retention),
+        payoff: asString(record.payoff),
+        preserve: asStringArray(record.preserve),
+        avoid: asStringArray(record.avoid),
+        promotions: asStringArray(record.promotions),
+        keywords: asStringArray(record.keywords).map((item) => item.toLowerCase())
+    };
+}
+function shortElementId() {
+    return `element_${randomUUID().slice(0, 8)}`;
+}
+function extractJson(text) {
+    const trimmed = text.trim();
+    const fenced = /```(?:json)?\s*([\s\S]*?)```/.exec(trimmed);
+    const candidate = fenced?.[1] ?? trimmed;
+    try {
+        return JSON.parse(candidate);
+    }
+    catch {
+        const objectMatch = /\{[\s\S]*\}/.exec(candidate);
+        if (objectMatch)
+            return JSON.parse(objectMatch[0]);
+        throw new Error("Gemini did not return valid JSON");
+    }
+}
+async function callGeminiVision(input) {
+    const parts = [{ text: input.prompt }];
+    for (const frame of input.frames) {
+        parts.push({ text: `Frame captured at ${frame.timestamp.toFixed(2)}s` });
+        parts.push({ inlineData: { mimeType: "image/jpeg", data: frame.data } });
+    }
+    const response = await fetch(`https://generativelanguage.googleapis.com/v1beta/models/${encodeURIComponent(input.model)}:generateContent?key=${encodeURIComponent(input.apiKey)}`, {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({
+            contents: [{ role: "user", parts }],
+            generationConfig: {
+                responseMimeType: "application/json",
+                temperature: 0.15,
+                // Bumped from Gemini's 8k default so long caption arrays (10+ text
+                // overlays × per-caption position/style metadata) don't truncate
+                // mid-JSON and blow up the parser.
+                maxOutputTokens: 16384
+            }
+        })
+    });
+    const raw = await response.text();
+    if (!response.ok) {
+        let message = raw;
+        try {
+            message = JSON.parse(raw).error?.message ?? raw;
+        }
+        catch { }
+        throw new Error(`Gemini responded ${response.status}: ${message}`);
+    }
+    const parsed = JSON.parse(raw);
+    const text = parsed.candidates?.[0]?.content?.parts?.map((p) => p.text ?? "").join("") ?? "";
+    return extractJson(text);
+}
+async function callOpenAIVision(input) {
+    const content = [{ type: "text", text: input.prompt }];
+    for (const frame of input.frames) {
+        content.push({ type: "text", text: `Frame captured at ${frame.timestamp.toFixed(2)}s` });
+        content.push({
+            type: "image_url",
+            image_url: { url: `data:image/jpeg;base64,${frame.data}` }
+        });
+    }
+    const response = await fetch(input.endpoint ?? "https://api.openai.com/v1/chat/completions", {
+        method: "POST",
+        headers: {
+            "content-type": "application/json",
+            "authorization": `Bearer ${input.apiKey}`,
+            ...(input.extraHeaders ?? {})
+        },
+        body: JSON.stringify({
+            model: input.model,
+            temperature: 0.15,
+            // Same rationale as Gemini's maxOutputTokens: give the JSON response room
+            // to breathe so a video with 12+ text overlays doesn't get truncated.
+            max_tokens: 16384,
+            response_format: { type: "json_object" },
+            messages: [{ role: "user", content }]
+        })
+    });
+    const raw = await response.text();
+    if (!response.ok) {
+        let message = raw;
+        try {
+            message = JSON.parse(raw).error?.message ?? raw;
+        }
+        catch { }
+        throw new Error(`${input.endpoint?.includes("openrouter") ? "OpenRouter" : "OpenAI"} responded ${response.status}: ${message}`);
+    }
+    const parsed = JSON.parse(raw);
+    const text = parsed.choices?.[0]?.message?.content ?? "";
+    return extractJson(text);
+}
+async function callVisionWithFallback(input) {
+    const attempts = [];
+    if (input.keys.gemini) {
+        const model = process.env.GEMINI_MODEL ?? "gemini-3.5-flash";
+        attempts.push({
+            provider: "gemini",
+            model,
+            run: () => callGeminiVision({ apiKey: input.keys.gemini, model, prompt: input.prompt, frames: input.frames })
+        });
+    }
+    if (input.keys.openai) {
+        const model = process.env.OPENAI_VISION_MODEL ?? "gpt-5.5-2026-04-23";
+        attempts.push({
+            provider: "openai",
+            model,
+            run: () => callOpenAIVision({ apiKey: input.keys.openai, model, prompt: input.prompt, frames: input.frames })
+        });
+    }
+    if (input.keys.openrouter) {
+        const model = process.env.OPENROUTER_VISION_MODEL ?? "google/gemini-3.5-flash";
+        attempts.push({
+            provider: "openrouter",
+            model,
+            run: () => callOpenAIVision({
+                apiKey: input.keys.openrouter,
+                model,
+                prompt: input.prompt,
+                frames: input.frames,
+                endpoint: "https://openrouter.ai/api/v1/chat/completions",
+                extraHeaders: {
+                    "HTTP-Referer": "https://staging.vidfarm.cc",
+                    "X-Title": "Vidfarm smart decompose"
+                }
+            })
+        });
+    }
+    if (attempts.length === 0) {
+        throw new Error("No vision provider key available (GEMINI_API_KEY, OPENAI_API_KEY, or OPENROUTER_API_KEY).");
+    }
+    const errors = [];
+    for (const attempt of attempts) {
+        try {
+            const result = await attempt.run();
+            return { result, provider: attempt.provider, model: attempt.model };
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            errors.push(`${attempt.provider}(${attempt.model}): ${message}`);
+            console.error(`smart decompose ${attempt.provider} failed`, message);
+        }
+    }
+    throw new Error(`All vision providers failed. ${errors.join(" | ")}`);
+}
+// ==========================================================================
+// Audio transcript pass — demux the source's audio track to mono 16kHz WAV
+// (codec-free, accepted by every STT provider) and transcribe it verbatim
+// with timestamped segments. Runs concurrently with the vision + OCR passes
+// and is non-fatal: a video with no audio track, or a transcription failure,
+// yields transcript: null instead of failing the decompose.
+// ==========================================================================
+async function extractAudioAsWav(videoPath, tempDir) {
+    const probeOutput = await runBinary(ffprobeBin, [
+        "-v", "error",
+        "-select_streams", "a",
+        "-show_entries", "stream=codec_type",
+        "-of", "json",
+        videoPath
+    ]);
+    const parsed = JSON.parse(probeOutput || "{}");
+    if (!Array.isArray(parsed.streams) || parsed.streams.length === 0)
+        return null;
+    const audioPath = path.join(tempDir, "audio.wav");
+    await runBinary(ffmpegBin, [
+        "-y",
+        "-i", videoPath,
+        "-vn",
+        "-ac", "1",
+        "-ar", "16000",
+        "-c:a", "pcm_s16le",
+        audioPath
+    ]);
+    return audioPath;
+}
+function buildTranscriptionPrompt(durationSeconds) {
+    return `Transcribe the spoken audio in this ${durationSeconds.toFixed(1)}-second clip VERBATIM.
+
+Return strictly valid JSON matching this schema:
+{
+  "language": string,
+  "segments": [{ "start": number, "end": number, "text": string }]
+}
+
+RULES:
+- Transcribe every spoken word exactly as heard — keep filler words, slang, and repetitions. Do not paraphrase, translate, or clean up grammar.
+- "language" is the BCP-47 code of the dominant spoken language (e.g. "en", "es").
+- Split into short segments at natural phrase boundaries; "start"/"end" are seconds within the clip (start >= 0, end <= ${durationSeconds.toFixed(3)}, end > start).
+- Only transcribe speech and sung lyrics. Ignore background music without lyrics and sound effects.
+- If there is no speech at all, return { "language": null, "segments": [] }.
+
+OUTPUT: pure JSON, no prose, no markdown fences.`;
+}
+function normalizeTranscriptSegments(raw, durationSeconds) {
+    if (!Array.isArray(raw))
+        return [];
+    return raw
+        .map((entry) => {
+        const record = (entry && typeof entry === "object") ? entry : {};
+        const start = Number(record.start ?? NaN);
+        const end = Number(record.end ?? NaN);
+        const text = typeof record.text === "string" ? record.text.trim() : "";
+        return { start, end, text };
+    })
+        .filter((s) => s.text.length > 0 && Number.isFinite(s.start) && Number.isFinite(s.end) && s.end > s.start)
+        .map((s) => ({
+        start: Number(Math.max(0, s.start).toFixed(3)),
+        end: Number(Math.min(durationSeconds > 0 ? durationSeconds : s.end, s.end).toFixed(3)),
+        text: s.text
+    }))
+        .sort((a, b) => a.start - b.start);
+}
+async function callGeminiTranscription(input) {
+    const response = await fetch(`https://generativelanguage.googleapis.com/v1beta/models/${encodeURIComponent(input.model)}:generateContent?key=${encodeURIComponent(input.apiKey)}`, {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({
+            contents: [{
+                    role: "user",
+                    parts: [
+                        { text: buildTranscriptionPrompt(input.durationSeconds) },
+                        { inlineData: { mimeType: "audio/wav", data: input.audioBase64 } }
+                    ]
+                }],
+            generationConfig: {
+                responseMimeType: "application/json",
+                temperature: 0,
+                maxOutputTokens: 16384
+            }
+        })
+    });
+    const raw = await response.text();
+    if (!response.ok) {
+        let message = raw;
+        try {
+            message = JSON.parse(raw).error?.message ?? raw;
+        }
+        catch { }
+        throw new Error(`Gemini responded ${response.status}: ${message}`);
+    }
+    const parsed = JSON.parse(raw);
+    const text = parsed.candidates?.[0]?.content?.parts?.map((p) => p.text ?? "").join("") ?? "";
+    const record = (extractJson(text) ?? {});
+    return {
+        language: typeof record.language === "string" && record.language.trim() ? record.language.trim() : null,
+        segments: normalizeTranscriptSegments(record.segments, input.durationSeconds)
+    };
+}
+async function callOpenAITranscription(input) {
+    const audioBuffer = await readFile(input.audioPath);
+    // Only whisper-1 supports verbose_json (per-segment timestamps). Newer
+    // gpt-4o-*-transcribe models return plain json; collapse to one segment.
+    const wantsSegments = input.model === "whisper-1";
+    const form = new FormData();
+    form.append("file", new Blob([new Uint8Array(audioBuffer)], { type: "audio/wav" }), "audio.wav");
+    form.append("model", input.model);
+    form.append("response_format", wantsSegments ? "verbose_json" : "json");
+    const response = await fetch("https://api.openai.com/v1/audio/transcriptions", {
+        method: "POST",
+        headers: { "authorization": `Bearer ${input.apiKey}` },
+        body: form
+    });
+    const raw = await response.text();
+    if (!response.ok) {
+        let message = raw;
+        try {
+            message = JSON.parse(raw).error?.message ?? raw;
+        }
+        catch { }
+        throw new Error(`OpenAI responded ${response.status}: ${message}`);
+    }
+    const parsed = JSON.parse(raw);
+    const segments = wantsSegments && Array.isArray(parsed.segments)
+        ? normalizeTranscriptSegments(parsed.segments, input.durationSeconds)
+        : [];
+    if (segments.length === 0 && typeof parsed.text === "string" && parsed.text.trim().length > 0) {
+        segments.push({ start: 0, end: Number(input.durationSeconds.toFixed(3)), text: parsed.text.trim() });
+    }
+    return {
+        language: typeof parsed.language === "string" && parsed.language.trim() ? parsed.language.trim() : null,
+        segments
+    };
+}
+async function transcribeAudioWithFallback(input) {
+    const attempts = [];
+    if (input.keys.gemini) {
+        const model = process.env.GEMINI_TRANSCRIBE_MODEL ?? process.env.GEMINI_MODEL ?? "gemini-3.5-flash";
+        attempts.push({
+            provider: "gemini",
+            model,
+            run: async () => {
+                const audioBase64 = (await readFile(input.audioPath)).toString("base64");
+                return callGeminiTranscription({ apiKey: input.keys.gemini, model, audioBase64, durationSeconds: input.durationSeconds });
+            }
+        });
+    }
+    if (input.keys.openai) {
+        const model = process.env.OPENAI_TRANSCRIBE_MODEL ?? "whisper-1";
+        attempts.push({
+            provider: "openai",
+            model,
+            run: () => callOpenAITranscription({ apiKey: input.keys.openai, model, audioPath: input.audioPath, durationSeconds: input.durationSeconds })
+        });
+    }
+    if (attempts.length === 0)
+        return null;
+    const errors = [];
+    for (const attempt of attempts) {
+        try {
+            const result = await attempt.run();
+            return {
+                text: result.segments.map((s) => s.text).join(" ").trim(),
+                language: result.language,
+                segments: result.segments,
+                provider: attempt.provider,
+                model: attempt.model
+            };
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            errors.push(`${attempt.provider}(${attempt.model}): ${message}`);
+            console.error(`smart decompose transcription ${attempt.provider} failed`, message);
+        }
+    }
+    throw new Error(`All transcription providers failed. ${errors.join(" | ")}`);
+}
+export async function smartDecomposeVideo(input) {
+    const tempDir = await mkdtemp(path.join(os.tmpdir(), SMART_DECOMPOSE_TEMP_PREFIX));
+    const sourcePath = path.join(tempDir, "source.mp4");
+    const startedAt = Date.now();
+    devLog("hyperframes.smart_decompose.start", {
+        source_url: input.sourceUrl,
+        has_user_prompt: Boolean(input.userPrompt),
+        providers_available: {
+            gemini: Boolean(input.keys.gemini),
+            openai: Boolean(input.keys.openai),
+            openrouter: Boolean(input.keys.openrouter)
+        }
+    });
+    try {
+        await downloadVideoTo(input.sourceUrl, sourcePath);
+        const meta = await ffprobeVideo(sourcePath);
+        if (!Number.isFinite(meta.durationSeconds) || meta.durationSeconds <= 0) {
+            throw new Error("Could not read video duration");
+        }
+        devLog("hyperframes.smart_decompose.probed", {
+            duration_seconds: meta.durationSeconds,
+            width: meta.width,
+            height: meta.height
+        });
+        // Sparse frames for the vision pass (scenes, captions, style, viral_dna)
+        // and dense frames for the OCR pass (deterministic caption timing).
+        // Extract both up front so the OCR API calls can run in parallel with
+        // the main vision call.
+        const [frames, ocrRawFrames, audioPath, sceneCuts] = await Promise.all([
+            sampleFramesAsBase64(sourcePath, meta.durationSeconds, tempDir),
+            extractDenseOcrFrames(sourcePath, meta.durationSeconds, tempDir),
+            extractAudioAsWav(sourcePath, tempDir).catch((err) => {
+                console.error("smart decompose audio extract failed", err instanceof Error ? err.message : err);
+                return null;
+            }),
+            detectSceneCuts(sourcePath, meta.durationSeconds, tempDir).catch((err) => {
+                console.error("smart decompose scene-cut detection failed", err instanceof Error ? err.message : err);
+                return [];
+            })
+        ]);
+        devLog("hyperframes.smart_decompose.frames_sampled", {
+            frame_count: frames.length,
+            ocr_frame_count: ocrRawFrames.length,
+            has_audio_track: Boolean(audioPath),
+            scene_cut_count: sceneCuts.length
+        });
+        const prompt = buildSmartDecomposePrompt({
+            durationSeconds: meta.durationSeconds,
+            width: meta.width,
+            height: meta.height,
+            userPrompt: input.userPrompt ?? null,
+            trendTaglineHint: input.trendTaglineHint ?? null,
+            frameTimestamps: frames.map((f) => f.timestamp),
+            sceneCuts
+        });
+        // Vision, OCR, transcription, and the product-placement scout run
+        // concurrently. OCR, transcription, and placement failures are all
+        // non-fatal. The placement call is DELIBERATELY a separate request from the
+        // caption/scene vision call so it can never dilute timeline-layer quality —
+        // it just reuses the same already-sampled sparse frames (no extra ffmpeg).
+        const [attempt, ocrFrames, transcript, placementSurfaces] = await Promise.all([
+            callVisionWithFallback({
+                prompt,
+                frames,
+                keys: input.keys
+            }),
+            runOcrPass({ frames: ocrRawFrames, keys: input.keys }).catch((err) => {
+                console.error("smart decompose OCR pass failed", err instanceof Error ? err.message : err);
+                return [];
+            }),
+            audioPath
+                ? transcribeAudioWithFallback({ audioPath, durationSeconds: meta.durationSeconds, keys: input.keys }).catch((err) => {
+                    console.error("smart decompose transcription failed", err instanceof Error ? err.message : err);
+                    return null;
+                })
+                : Promise.resolve(null),
+            runPlacementSurfacePass({
+                frames,
+                keys: input.keys,
+                durationSeconds: meta.durationSeconds,
+                sceneSlugs: []
+            }).catch((err) => {
+                console.error("smart decompose placement pass failed", err instanceof Error ? err.message : err);
+                return [];
+            })
+        ]);
+        devLog("hyperframes.smart_decompose.ocr_completed", {
+            frames_with_text: ocrFrames.filter((f) => f.texts.length > 0).length,
+            total_ocr_frames: ocrFrames.length
+        });
+        devLog("hyperframes.smart_decompose.transcript_completed", {
+            has_transcript: Boolean(transcript),
+            segment_count: transcript?.segments.length ?? 0,
+            language: transcript?.language ?? null,
+            provider: transcript?.provider ?? null
+        });
+        const raw = attempt.result;
+        const record = (raw && typeof raw === "object") ? raw : {};
+        const scenesRaw = Array.isArray(record.scenes) ? record.scenes : [];
+        const captionsRaw = Array.isArray(record.captions) ? record.captions : [];
+        const usedSceneSlugs = new Set();
+        const scenes = scenesRaw
+            .map((scene, index) => {
+            const slug = dedupeSlug(normalizeSlug(typeof scene.slug === "string" ? scene.slug : `scene_${index + 1}`) || `scene_${index + 1}`, usedSceneSlugs);
+            return {
+                slug,
+                start: Number(scene.start ?? 0),
+                duration: Number(scene.duration ?? 0),
+                label: typeof scene.label === "string" ? scene.label : `Scene ${index + 1}`,
+                description: typeof scene.description === "string" ? scene.description : "",
+                viral_note: typeof scene.viral_note === "string" ? scene.viral_note : ""
+            };
+        })
+            .filter((s) => Number.isFinite(s.start) && Number.isFinite(s.duration) && s.duration > 0);
+        const usedCaptionSlugs = new Set();
+        const captions = captionsRaw
+            .map((c, index) => {
+            const slug = dedupeSlug(normalizeSlug(typeof c.slug === "string" ? c.slug : `caption_${index + 1}`) || `caption_${index + 1}`, usedCaptionSlugs);
+            return {
+                id: `caption_${index + 1}`,
+                slug,
+                text: typeof c.text === "string" ? c.text : "",
+                start: Number(c.start ?? 0),
+                duration: Number(c.duration ?? 0),
+                x: Number(c.x ?? 8),
+                y: Number(c.y ?? 68),
+                width: Number(c.width ?? 84),
+                height: Number(c.height ?? 12),
+                font_size: resolveFontSize({ fontSize: c.font_size, fontSizePercent: c.font_size_percent, canvasHeight: meta.height }),
+                color: normalizeHexColor(c.color, "#ffffff"),
+                background: normalizeHexColor(c.background, "#000000"),
+                background_style: normalizeBackgroundStyle(c.background_style),
+                font_family: normalizeFontFamily(c.font_family),
+                font_weight: normalizeFontWeight(c.font_weight),
+                viral_note: typeof c.viral_note === "string" ? c.viral_note : undefined
+            };
+        })
+            .filter((c) => c.text.trim().length > 0 && Number.isFinite(c.start) && Number.isFinite(c.duration) && c.duration > 0);
+        const snapped = snapCaptionTimingsToOcr({
+            captions,
+            ocrFrames,
+            durationSeconds: meta.durationSeconds
+        });
+        const finalCaptions = snapped.captions;
+        devLog("hyperframes.smart_decompose.captions_snapped", {
+            total_captions: captions.length,
+            snapped_count: snapped.snappedCount
+        });
+        // Ground scene boundaries on the ffmpeg-detected hard cuts (no-op if none).
+        const snappedScenes = snapScenesToCuts({ scenes, cuts: sceneCuts, durationSeconds: meta.durationSeconds });
+        const finalScenes = snappedScenes.scenes;
+        devLog("hyperframes.smart_decompose.scenes_snapped", {
+            total_scenes: scenes.length,
+            snapped_count: snappedScenes.snappedCount,
+            scene_cut_count: sceneCuts.length
+        });
+        // Link each product-placement surface to the scene its start falls within,
+        // deterministically from the finalized scene ranges (the placement call ran
+        // before scenes existed, so it couldn't know the slugs).
+        const finalPlacementSurfaces = placementSurfaces.map((surface) => {
+            const owning = finalScenes.find((s) => surface.start >= s.start && surface.start < s.start + s.duration);
+            return owning ? { ...surface, scene_slug: owning.slug } : surface;
+        });
+        const viralDna = normalizeViralDna(record.viral_dna);
+        // Caller-supplied trend_tagline always wins over whatever the LLM emits so
+        // the user's chosen tagline round-trips even if the model tries to rephrase.
+        if (input.trendTaglineHint && input.trendTaglineHint.trim().length > 0) {
+            viralDna.trend_tagline = input.trendTaglineHint.trim();
+        }
+        devLog("hyperframes.smart_decompose.completed", {
+            provider: attempt.provider,
+            model: attempt.model,
+            duration_ms: Date.now() - startedAt,
+            scene_count: finalScenes.length,
+            caption_count: finalCaptions.length,
+            captions_snapped: snapped.snappedCount,
+            scenes_snapped: snappedScenes.snappedCount,
+            placement_surface_count: finalPlacementSurfaces.length
+        });
+        return {
+            summary: typeof record.summary === "string" ? record.summary : "",
+            viralDna,
+            placementSurfaces: finalPlacementSurfaces,
+            transcript,
+            durationSeconds: meta.durationSeconds,
+            width: meta.width,
+            height: meta.height,
+            scenes: finalScenes,
+            captions: finalCaptions,
+            provider: attempt.provider,
+            model: attempt.model
+        };
+    }
+    catch (error) {
+        devLog("hyperframes.smart_decompose.failed", {
+            source_url: input.sourceUrl,
+            duration_ms: Date.now() - startedAt,
+            ...devErrorFields(error)
+        }, "error");
+        throw error;
+    }
+    finally {
+        await rm(tempDir, { recursive: true, force: true });
+    }
+}
+export function buildSmartDecomposedHtml(input) {
+    const { compositionId, sourceUrl, title, result } = input;
+    const totalDuration = Number(result.durationSeconds.toFixed(3));
+    const scenes = result.scenes.length > 0
+        ? result.scenes
+        : [{ slug: "scene_1", start: 0, duration: totalDuration, label: "Scene 1", description: "", viral_note: "" }];
+    // Assign each caption to the lowest track index (starting at 2 — track 0
+    // is video, track 1 is audio) where it doesn't temporally overlap any
+    // caption already on that track. Enforces the "no two clips on the same
+    // track can overlap in time" rule. Multiple stacked labels (like a
+    // staircase of "single/talking/dating/marriage/have kids" all shown for
+    // the full duration) end up on tracks 2,3,4,5,6 respectively.
+    const CAPTION_TRACK_START = 2;
+    const captionTrackClipRanges = [];
+    const assignCaptionTrackIndex = (start, end) => {
+        for (let i = 0; i < captionTrackClipRanges.length; i += 1) {
+            if (!captionTrackClipRanges[i].some((r) => start < r.end && r.start < end)) {
+                captionTrackClipRanges[i].push({ start, end });
+                return CAPTION_TRACK_START + i;
+            }
+        }
+        captionTrackClipRanges.push([{ start, end }]);
+        return CAPTION_TRACK_START + captionTrackClipRanges.length - 1;
+    };
+    const sceneEls = scenes.map((scene, index) => {
+        const start = Math.max(0, Math.min(totalDuration - 0.1, Number(scene.start.toFixed(3))));
+        const duration = Math.max(0.1, Number(scene.duration.toFixed(3)));
+        const end = Math.min(totalDuration, start + duration);
+        const id = shortElementId();
+        const sceneSlug = scene.slug || `scene_${index + 1}`;
+        return `<div class="clip" id="${id}" data-hf-id="${id}" data-hf-slug="${escapeAttr(sceneSlug)}" data-layer-mode="both" data-layer-kind="video" data-viral-note="${escapeAttr(scene.viral_note ?? "")}" data-start="${start}" data-duration="${Number(duration.toFixed(3))}" data-end="${Number(end.toFixed(3))}" data-track-index="0" data-label="${escapeAttr(scene.label)}" data-media-start="${start}" data-playback-start="${start}" data-vf-timeline-proxy="video" data-src="${escapeAttr(sourceUrl)}" style="position:absolute;left:0%;top:0%;width:1%;height:1%;z-index:0;display:none;pointer-events:none;"></div>`;
+    }).join("\n    ");
+    // Sort captions by start time so the track-assignment greedy fills lower
+    // tracks first with earlier captions.
+    const sortedCaptions = [...result.captions].sort((a, b) => (a.start - b.start) || (a.duration - b.duration));
+    const captionEls = sortedCaptions.map((caption, index) => {
+        const start = Math.max(0, Math.min(totalDuration - 0.1, Number(caption.start.toFixed(3))));
+        const duration = Math.max(0.1, Math.min(totalDuration - start, Number(caption.duration.toFixed(3))));
+        const end = start + duration;
+        const trackIndex = assignCaptionTrackIndex(start, end);
+        const id = shortElementId();
+        const captionSlug = caption.slug || `caption_${index + 1}`;
+        const clampedX = clampPercent(caption.x, 0, 95);
+        const clampedY = clampPercent(caption.y, 0, 95);
+        const clampedW = clampPercent(caption.width, 5, 100 - clampedX);
+        const clampedH = clampPercent(caption.height, 3, 100 - clampedY);
+        const escapedText = escapeHtml(caption.text);
+        const innerStyle = captionInlineTextStyle(caption);
+        return `<div class="clip" id="${id}" data-hf-id="${id}" data-hf-slug="${escapeAttr(captionSlug)}" data-layer-mode="publish" data-layer-kind="caption" data-viral-note="${escapeAttr(caption.viral_note ?? "")}" data-start="${start}" data-duration="${Number(duration.toFixed(3))}" data-end="${Number(end.toFixed(3))}" data-track-index="${trackIndex}" data-label="${escapeAttr(caption.text.slice(0, 40))}" data-text-background-style="${caption.background_style}" data-text-background-color="${escapeAttr(caption.background)}" data-font-family="${escapeAttr(caption.font_family)}" style="position:absolute;left:${clampedX}%;top:${clampedY}%;width:${clampedW}%;height:${clampedH}%;z-index:${trackIndex};display:flex;align-items:center;justify-content:center;padding:3px;box-sizing:border-box;text-align:center;color:${caption.color};background:transparent;font-family:'${caption.font_family}', 'TikTok Sans', sans-serif;font-weight:${caption.font_weight};font-size:${caption.font_size}px;line-height:1.2;overflow:visible;"><span data-vf-text-lines="true"><span data-vf-text-inline="true" style="${innerStyle}">${escapedText}</span></span></div>`;
+    }).join("\n    ");
+    const audioId = shortElementId();
+    const audioEl = `<audio class="clip" id="${audioId}" data-hf-id="${audioId}" data-hf-slug="source_audio" data-layer-mode="both" data-layer-kind="audio" data-viral-note="Original TikTok audio track." data-start="0" data-duration="${totalDuration}" data-end="${totalDuration}" data-track-index="1" data-label="Original audio" data-media-start="0" data-playback-start="0" data-timeline-role="music" data-volume="1" src="${escapeAttr(sourceUrl)}" preload="metadata"></audio>`;
+    const viralDnaJson = escapeAttr(JSON.stringify(result.viralDna ?? DEFAULT_VIRAL_DNA));
+    return `<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+  <style>
+    @import url("https://fonts.googleapis.com/css2?family=Abel&family=Montserrat:wght@600;700&family=Source+Code+Pro:wght@700&family=TikTok+Sans:wght@400;600;700;800;900&family=Yesteryear&display=swap");
+    html, body { width:100%; height:100%; margin:0; overflow:hidden; background:#050604; }
+    [data-composition-id] { position:relative; width:100vw; height:100vh; overflow:hidden; background:#050604; }
+    audio { display:none; }
+  </style>
+</head>
+<body>
+  <div data-composition-id="${escapeAttr(compositionId)}" data-source-video="${escapeAttr(sourceUrl)}" data-width="${result.width || 720}" data-height="${result.height || 1280}" data-duration="${totalDuration}" data-source-title="${escapeAttr(title)}" data-viral-dna="${viralDnaJson}">
+    <video data-vf-playback-source="true" src="${escapeAttr(sourceUrl)}" muted playsinline preload="auto" style="position:absolute;left:0%;top:0%;width:100%;height:100%;z-index:0;object-fit:cover;background:#050604"></video>
+    ${sceneEls}
+    ${audioEl}
+    ${captionEls}
+  </div>
+</body>
+</html>`;
+}
+function normalizeSlug(value) {
+    return String(value ?? "")
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "_")
+        .replace(/^_+|_+$/g, "")
+        .slice(0, 64);
+}
+function dedupeSlug(base, used) {
+    const seed = base || "element";
+    if (!used.has(seed)) {
+        used.add(seed);
+        return seed;
+    }
+    for (let index = 2; index < 999; index += 1) {
+        const candidate = `${seed}_${index}`;
+        if (!used.has(candidate)) {
+            used.add(candidate);
+            return candidate;
+        }
+    }
+    const fallback = `${seed}_${Date.now().toString(36)}`;
+    used.add(fallback);
+    return fallback;
+}
+function escapeAttr(value) {
+    return String(value ?? "").replace(/&/g, "&amp;").replace(/"/g, "&quot;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+}
+function escapeHtml(value) {
+    return String(value ?? "").replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+}
+function clampPercent(value, min, max) {
+    if (!Number.isFinite(value))
+        return min;
+    return Math.max(min, Math.min(max, value));
+}
+export function stampCompositionIdentity(html, input) {
+    if (!input.forkId)
+        return html;
+    const composed = `${input.forkId}_v${input.version}`;
+    const { document } = parseHTML(html);
+    const root = document.querySelector("[data-composition-id]");
+    if (!root)
+        return html;
+    root.setAttribute("data-composition-id", composed);
+    root.setAttribute("data-fork-id", input.forkId);
+    root.setAttribute("data-fork-version", String(input.version));
+    return `<!doctype html>\n${document.documentElement.outerHTML}`;
+}
+// True when the union of canvas-filling intervals leaves any hole ≥ minGap within
+// [0, total] — a leading gap, a hole between clips, or a trailing gap. Mirrors the
+// editor-side computeCompositionGaps intent (see src/devcli/composition-edit.ts).
+function compositionHasCoverageGap(intervals, total, minGap = 0.2) {
+    if (!Number.isFinite(total) || total <= 0)
+        return false;
+    const sorted = intervals.filter(([start, end]) => end > start).sort((a, b) => a[0] - b[0]);
+    let cursor = 0;
+    for (const [start, end] of sorted) {
+        if (start > cursor + minGap)
+            return true;
+        cursor = Math.max(cursor, end);
+    }
+    return cursor < total - minGap;
+}
+export function normalizePublishHtml(html) {
+    const { document } = parseHTML(html);
+    // Coverage gaps: any interval of the timeline with no active canvas-filling
+    // layer renders as the page background (#050604 — near-black), which the user
+    // experiences as the video "going black" mid-composition (e.g. a scene that
+    // was shortened/deleted or a replacement clip shorter than its slot). The
+    // full-length backing source video (data-vf-playback-source) is the natural
+    // fallback — every scene proxy is cut from that same source — but it is
+    // normally dropped at publish. When a gap exists we instead retain it as a
+    // timed bottom base layer so uncovered intervals show the original footage
+    // rather than black; with no gap we drop it (avoids decoding a redundant
+    // full-length video on every render).
+    const compositionRoot = document.querySelector("[data-composition-id]");
+    const totalDuration = compositionRoot
+        ? Number.parseFloat(compositionRoot.getAttribute("data-duration") || "")
+        : NaN;
+    const coverageIntervals = [];
+    for (const el of Array.from(document.querySelectorAll('[data-vf-timeline-proxy="video"], video[data-start], img[data-start]'))) {
+        const start = Number.parseFloat(el.getAttribute("data-start") || "");
+        const duration = Number.parseFloat(el.getAttribute("data-duration") || "");
+        if (Number.isFinite(start) && Number.isFinite(duration) && duration > 0) {
+            coverageIntervals.push([start, start + duration]);
+        }
+    }
+    const retainBackingVideo = Number.isFinite(totalDuration) &&
+        totalDuration > 0 &&
+        compositionHasCoverageGap(coverageIntervals, totalDuration);
+    for (const backingVideo of Array.from(document.querySelectorAll("[data-vf-playback-source]"))) {
+        if (!retainBackingVideo) {
+            backingVideo.remove();
+            continue;
+        }
+        // Retime the backing video into a full-timeline base layer the render engine
+        // seeks per frame (video[data-start]), pinned below every proxy (z-index:-1).
+        backingVideo.removeAttribute("data-vf-playback-source");
+        backingVideo.setAttribute("data-start", "0");
+        backingVideo.setAttribute("data-duration", String(totalDuration));
+        backingVideo.setAttribute("data-media-start", "0");
+        backingVideo.setAttribute("muted", "");
+        backingVideo.setAttribute("playsinline", "");
+        backingVideo.setAttribute("preload", "auto");
+        backingVideo.setAttribute("style", [
+            "position:absolute",
+            "left:0%",
+            "top:0%",
+            "width:100%",
+            "height:100%",
+            "z-index:-1",
+            "object-fit:cover",
+            "background:#050604"
+        ].join(";"));
+    }
+    for (const proxy of Array.from(document.querySelectorAll('[data-vf-timeline-proxy="video"]'))) {
+        const video = document.createElement("video");
+        const source = proxy.getAttribute("data-src") || proxy.getAttribute("src") || "";
+        for (const attr of Array.from(proxy.attributes)) {
+            if (attr.name === "data-vf-timeline-proxy" || attr.name === "data-src")
+                continue;
+            video.setAttribute(attr.name, attr.value);
+        }
+        video.setAttribute("src", source);
+        video.setAttribute("muted", "");
+        video.setAttribute("playsinline", "");
+        video.setAttribute("preload", "auto");
+        const trackIndex = Number.parseInt(proxy.getAttribute("data-track-index") ?? "0", 10) || 0;
+        video.setAttribute("style", [
+            "position:absolute",
+            "left:0%",
+            "top:0%",
+            "width:100%",
+            "height:100%",
+            `z-index:${trackIndex}`,
+            "object-fit:cover",
+            "background:#050604"
+        ].join(";"));
+        proxy.replaceWith(video);
+    }
+    // Enforce z-index = data-track-index for every timed layer so visual stacking
+    // strictly follows the timeline layer index. No arbitrary inline z-index survives.
+    for (const el of Array.from(document.querySelectorAll("[data-track-index]"))) {
+        const trackAttr = el.getAttribute("data-track-index");
+        if (!trackAttr)
+            continue;
+        const trackIndex = Number.parseInt(trackAttr, 10);
+        if (!Number.isFinite(trackIndex))
+            continue;
+        const html = el;
+        if (typeof html.style === "undefined")
+            continue;
+        html.style.zIndex = String(trackIndex);
+    }
+    // Editor sessions occasionally leave inline style attributes with double
+    // quotes inside CSS values (font-family: "TikTok Sans"). When serialized into
+    // an HTML attribute, those quotes become &quot; entities. The render lambda
+    // resolves font-family with a regex over raw HTML and misreads &quot; as a
+    // literal font name, exploding with FontFetchError. Normalize to single
+    // quotes so serialization stays entity-free.
+    for (const el of Array.from(document.querySelectorAll("[style]"))) {
+        const styleValue = el.getAttribute("style");
+        if (!styleValue || styleValue.indexOf('"') === -1)
+            continue;
+        el.setAttribute("style", styleValue.replace(/"/g, "'"));
+    }
+    return `<!doctype html>\n${document.documentElement.outerHTML}`;
+}
+async function resolveHyperframesStack() {
+    const region = config.HYPERFRAMES_RENDER_REGION || config.AWS_REGION || "us-east-1";
+    const lambdaMemoryMb = positiveInteger(config.HYPERFRAMES_RENDER_MEMORY_MB, 3072);
+    const envStack = {
+        stackName: config.HYPERFRAMES_LAMBDA_STACK_NAME || "hyperframes-vidfarm-prod",
+        bucketName: config.HYPERFRAMES_RENDER_BUCKET_NAME || config.HYPERFRAMES_LAMBDA_BUCKET_NAME || "",
+        stateMachineArn: config.HYPERFRAMES_RENDER_STATE_MACHINE_ARN || config.HYPERFRAMES_STATE_MACHINE_ARN || "",
+        region,
+        lambdaMemoryMb
+    };
+    if (envStack.bucketName && envStack.stateMachineArn) {
+        return envStack;
+    }
+    if (stackCache && stackCache.expiresAt > Date.now()) {
+        return stackCache.value;
+    }
+    const stackName = envStack.stackName;
+    const cloudFormation = new CloudFormationClient({ region });
+    const result = await cloudFormation.send(new DescribeStacksCommand({ StackName: stackName }));
+    const stack = result.Stacks?.[0];
+    if (!stack) {
+        throw new Error(`HyperFrames Lambda stack not found: ${stackName}`);
+    }
+    const outputs = stack.Outputs || [];
+    const value = {
+        stackName,
+        bucketName: stackOutput(outputs, "RenderBucketName"),
+        stateMachineArn: stackOutput(outputs, "RenderStateMachineArn"),
+        functionArn: stackOutput(outputs, "RenderFunctionArn"),
+        region: stackOutput(outputs, "RenderRegion") || region,
+        lambdaMemoryMb: positiveInteger(stackOutput(outputs, "RenderMemoryMb"), lambdaMemoryMb)
+    };
+    if (!value.bucketName || !value.stateMachineArn) {
+        throw new Error(`HyperFrames Lambda stack ${stackName} is missing render outputs.`);
+    }
+    stackCache = { value, expiresAt: Date.now() + 60_000 };
+    return value;
+}
+async function stageProject(input) {
+    const root = path.join(config.VIDFARM_DATA_DIR, "hyperframes-projects");
+    const projectDir = path.join(root, `${Date.now().toString(36)}-${safeIdentifier(input.compositionId)}-${randomUUID().slice(0, 8)}`);
+    await rm(projectDir, { recursive: true, force: true });
+    await mkdir(projectDir, { recursive: true });
+    await writeFile(path.join(projectDir, "index.html"), input.compositionHtml, "utf8");
+    for (const file of input.projectFiles || []) {
+        const target = safeProjectPath(projectDir, file.path);
+        await mkdir(path.dirname(target), { recursive: true });
+        await writeFile(target, file.contents);
+    }
+    for (const copyPath of input.copyPaths || []) {
+        const target = safeProjectPath(projectDir, copyPath.to);
+        await mkdir(path.dirname(target), { recursive: true });
+        await cp(copyPath.from, target, { recursive: true, force: true });
+    }
+    return projectDir;
+}
+function extractCompositionMetadata(html, input) {
+    const compositionId = safeIdentifier(input.compositionId || htmlAttribute(html, "data-composition-id") || input.composition?.compositionId || "composition");
+    const width = positiveInteger(input.width || htmlAttribute(html, "data-width") || input.composition?.width, 720);
+    const height = positiveInteger(input.height || htmlAttribute(html, "data-height") || input.composition?.height, 1280);
+    const fps = positiveInteger(input.fps || 30, 30);
+    const duration = Number.parseFloat(htmlAttribute(html, "data-duration") || String(input.composition?.duration || ""));
+    return {
+        compositionId,
+        title: input.title || htmlAttribute(html, "data-source-video") || compositionId,
+        width,
+        height,
+        fps,
+        duration: Number.isFinite(duration) && duration > 0 ? duration : null
+    };
+}
+function safeProjectPath(root, relativePath) {
+    const target = path.resolve(root, relativePath);
+    const resolvedRoot = path.resolve(root);
+    if (target !== resolvedRoot && !target.startsWith(`${resolvedRoot}${path.sep}`)) {
+        throw new Error(`Invalid HyperFrames project path: ${relativePath}`);
+    }
+    return target;
+}
+// Round the composition's data-width / data-height down to the nearest even
+// integer so libx264 (yuv420p) accepts the frame size. Only rewrites values
+// that are actually odd, leaving well-formed even compositions untouched.
+function forceEvenCompositionDimensions(html) {
+    return html.replace(/\bdata-(width|height)=(["'])(\d+)\2/gi, (match, dim, quote, value) => {
+        const n = Number.parseInt(value, 10);
+        if (!Number.isFinite(n) || n % 2 === 0)
+            return match;
+        return `data-${dim}=${quote}${n - 1}${quote}`;
+    });
+}
+function htmlAttribute(html, name) {
+    const escaped = name.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    const match = html.match(new RegExp(`${escaped}=(["'])(.*?)\\1`, "i"));
+    return match?.[2] || "";
+}
+function stackOutput(outputs, key) {
+    return outputs.find((output) => output.OutputKey === key)?.OutputValue
+        || outputs.find((output) => String(output.OutputKey || "").endsWith(key))?.OutputValue
+        || "";
+}
+function parseS3Uri(uri) {
+    const match = String(uri || "").match(/^s3:\/\/([^/]+)\/(.+)$/);
+    return match ? { bucket: match[1], key: match[2] } : null;
+}
+async function signedS3Url(s3Uri, region) {
+    const parsed = parseS3Uri(s3Uri);
+    if (!parsed)
+        return null;
+    const client = new S3Client({ region });
+    return getSignedUrl(client, new GetObjectCommand({ Bucket: parsed.bucket, Key: parsed.key }), { expiresIn: 3600 });
+}
+function safeIdentifier(value) {
+    return String(value || "composition")
+        .toLowerCase()
+        .replace(/[^a-z0-9_-]+/g, "-")
+        .replace(/^-+|-+$/g, "")
+        .slice(0, 64) || "composition";
+}
+function positiveInteger(value, fallback) {
+    const next = Math.round(Number(value));
+    return Number.isFinite(next) && next > 0 ? next : fallback;
+}
+function normalizeRenderFps(value) {
+    if (value <= 24)
+        return 24;
+    if (value > 45)
+        return 60;
+    return 30;
+}
+function buildCastAnalysisPrompt(input) {
+    const summaryBlock = input.summary && input.summary.trim()
+        ? `\nVIDEO SUMMARY (from the first decompose pass):\n"""\n${input.summary.trim()}\n"""\n`
+        : "";
+    const sceneBlock = input.scenes && input.scenes.length > 0
+        ? `\nSCENES (slug — description, from the first pass; use these exact slugs in "appears_in"):\n${input.scenes
+            .map((s) => `  ${s.slug}: ${(s.description ?? "").slice(0, 240)}`)
+            .join("\n")}\n`
+        : "";
+    const frameBlock = input.frameTimestamps.length > 0
+        ? `\nFRAMES SUPPLIED (in order, each captioned with its capture timestamp): ${input.frameTimestamps
+            .map((t) => `${t.toFixed(2)}s`)
+            .join(", ")}\nPick "best_frame_seconds" from one of these exact timestamps — the frame where that person is largest, most frontal, and least occluded (ideally alone).\n`
+        : "";
+    return `You are identifying the recurring CAST (the people/characters) of a short-form vertical video so they can be reused and regenerated consistently in later edits.
+${summaryBlock}${sceneBlock}
+Video metadata:
+- duration: ${input.durationSeconds.toFixed(3)} seconds
+- dimensions: ${input.width} x ${input.height} (canvas is 100% x 100%)
+${frameBlock}
+Identify each DISTINCT person who appears. Merge the same person across scenes into ONE entry — do not create a new entry per scene. Ignore incidental crowd/background extras who never recur unless they are visually significant. If the video has no people (product-only, screen-recording, etc.), return an empty "cast" array.
+
+For each person, describe them in enough concrete detail (face, hair, skin tone, build, age range, distinguishing features, wardrobe) that an image model could regenerate the SAME person from the description alone. Give a stable snake_case "slug" (e.g. "hero_girl", "male_narrator"), a short "name"/label, a "role" of "main" | "secondary" | "background", the list of scene slugs they "appears_in", the single "best_frame_seconds" timestamp where they're cleanest, a normalized bounding box "bbox" {x,y,width,height} in 0..1 coordinates locating that person within that frame (null if you cannot localize), and "is_primary": true for the single most central recurring subject (false for the rest).
+
+Return strictly valid JSON:
+{
+  "cast": [{
+    "slug": string,
+    "name": string,
+    "role": "main" | "secondary" | "background",
+    "description": string,
+    "wardrobe": string,
+    "appears_in": [string, ...],
+    "best_frame_seconds": number,
+    "bbox": { "x": number, "y": number, "width": number, "height": number } | null,
+    "is_primary": boolean
+  }]
+}`;
+}
+function clamp01(value) {
+    const n = Number(value);
+    if (!Number.isFinite(n))
+        return 0;
+    return Math.min(1, Math.max(0, n));
+}
+function normalizeCastMembers(raw, durationSeconds) {
+    const root = raw && typeof raw === "object" ? raw : {};
+    const list = Array.isArray(root.cast)
+        ? root.cast
+        : Array.isArray(root.members)
+            ? root.members
+            : [];
+    const usedSlugs = new Set();
+    const members = [];
+    for (const entry of list) {
+        if (!entry || typeof entry !== "object")
+            continue;
+        const e = entry;
+        const description = typeof e.description === "string" ? e.description.trim() : "";
+        if (!description)
+            continue;
+        let slug = safeIdentifier(typeof e.slug === "string" && e.slug.trim() ? e.slug : (typeof e.name === "string" ? e.name : `cast-${members.length + 1}`));
+        while (usedSlugs.has(slug))
+            slug = `${slug}-${members.length + 1}`;
+        usedSlugs.add(slug);
+        const bboxRaw = e.bbox && typeof e.bbox === "object" ? e.bbox : null;
+        const bbox = bboxRaw
+            ? {
+                x: clamp01(bboxRaw.x),
+                y: clamp01(bboxRaw.y),
+                width: clamp01(bboxRaw.width ?? bboxRaw.w),
+                height: clamp01(bboxRaw.height ?? bboxRaw.h)
+            }
+            : null;
+        const best = Number(e.best_frame_seconds ?? e.best_frame ?? 0);
+        members.push({
+            slug,
+            name: typeof e.name === "string" && e.name.trim() ? e.name.trim().slice(0, 120) : slug,
+            role: typeof e.role === "string" && e.role.trim() ? e.role.trim().toLowerCase().slice(0, 40) : "secondary",
+            description: description.slice(0, 2000),
+            wardrobe: typeof e.wardrobe === "string" ? e.wardrobe.trim().slice(0, 600) : "",
+            appears_in: Array.isArray(e.appears_in)
+                ? e.appears_in.map((s) => (typeof s === "string" ? s.trim() : "")).filter(Boolean).slice(0, 40)
+                : [],
+            best_frame_seconds: Number.isFinite(best) && best > 0
+                ? Math.min(Math.max(0, best), Math.max(0, durationSeconds - 0.05))
+                : 0,
+            bbox: bbox && (bbox.width > 0 || bbox.height > 0) ? bbox : null,
+            is_primary: e.is_primary === true
+        });
+    }
+    // Guarantee exactly one primary when there's at least one member.
+    if (members.length > 0 && !members.some((m) => m.is_primary)) {
+        members[0].is_primary = true;
+    }
+    return members;
+}
+export async function analyzeCastMembers(input) {
+    const tempDir = await mkdtemp(path.join(os.tmpdir(), SMART_DECOMPOSE_TEMP_PREFIX));
+    const sourcePath = path.join(tempDir, "source.mp4");
+    try {
+        await downloadVideoTo(input.sourceUrl, sourcePath);
+        const meta = await ffprobeVideo(sourcePath);
+        if (!Number.isFinite(meta.durationSeconds) || meta.durationSeconds <= 0) {
+            throw new Error("Could not read video duration for cast analysis");
+        }
+        const frames = await sampleFramesAsBase64(sourcePath, meta.durationSeconds, tempDir);
+        const prompt = buildCastAnalysisPrompt({
+            durationSeconds: meta.durationSeconds,
+            width: meta.width,
+            height: meta.height,
+            summary: input.summary ?? null,
+            scenes: input.scenes ?? [],
+            frameTimestamps: frames.map((f) => f.timestamp)
+        });
+        const attempt = await callVisionWithFallback({ prompt, frames, keys: input.keys });
+        devLog("hyperframes.cast_analyze.done", {
+            source_url: input.sourceUrl,
+            provider: attempt.provider,
+            model: attempt.model
+        });
+        return {
+            members: normalizeCastMembers(attempt.result, meta.durationSeconds),
+            provider: attempt.provider,
+            model: attempt.model,
+            durationSeconds: meta.durationSeconds,
+            width: meta.width,
+            height: meta.height
+        };
+    }
+    finally {
+        await rm(tempDir, { recursive: true, force: true }).catch(() => { });
+    }
+}
+//# sourceMappingURL=hyperframes.js.map