@mevdragon/vidfarm-devcli 0.20.5 → 0.20.8

package/dist/src/services/hyperframes.js

@@ -1,3517 +0,0 @@
-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 { DescribeExecutionCommand, ExecutionDoesNotExist, SFNClient } from "@aws-sdk/client-sfn";
-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 { CAPTION_ANIM_CSS, CAPTION_STYLE_MARKER, KEN_BURNS_CSS, KEN_BURNS_STYLE_MARKER, LEGACY_TRANSITION_CSS_V1, TRANSITION_ADJACENCY_EPSILON, TRANSITION_CSS, TRANSITION_OUT_PRESETS, TRANSITION_PRESETS, TRANSITION_STYLE_MARKER, buildHyperframeCompositionHtml, clampTransitionDuration, transitionOutDelaySeconds } from "../hyperframes/composition.js";
-import { applyMarkupUsd } from "./billing-pricing.js";
-// The scene-annotation pass reuses the clip library's controlled vocabulary and
-// embedding-text recipe verbatim so a source scene's clip-match query is
-// symmetric with how a candidate clip was tagged/embedded. This is the ONE
-// coupling to the (parallel) clip-curation work — a plain leaf import; the
-// retrieval logic itself (search over these criteria) is merged in later.
-import { buildClipEmbeddingText, sanitizeTagValues, taxonomyForPrompt } from "./clip-curation/index.js";
-/** Thrown by the primitive render wrapper when a distributed render is still in
- *  flight. The job runner catches it and parks the job as `waiting_for_render`
- *  so Step Functions waits + re-invokes — no single Lambda holds the render open
- *  for its 15-minute lifetime. */
-export class RenderInProgressError extends Error {
-    executionArn;
-    renderId;
-    waitSeconds;
-    progressFraction;
-    constructor(input) {
-        super(`HyperFrames render ${input.renderId} still in progress`);
-        this.name = "RenderInProgressError";
-        this.executionArn = input.executionArn;
-        this.renderId = input.renderId;
-        this.waitSeconds = input.waitSeconds;
-        this.progressFraction = input.progressFraction;
-    }
-}
-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;
-}
-// The bundled producer/aws-lambda libraries embed upstream-vendor doc links in
-// some error messages (font resolution, large-variables). Those URLs surface in
-// job logs and the export modal, so rewrite them to vidfarm's docs before the
-// message leaves the render layer.
-function scrubVendorDocLinks(text) {
-    return text.replace(/https?:\/\/[a-z0-9.-]*heygen\.com[^\s"')\]]*/gi, "https://vidfarm.cc/skill/vidfarm-director");
-}
-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 prep = await this.prepareCloudRender(input, compositionHtml);
-        const handle = await this.dispatchCloudRender(prep, input);
-        if (input.wait === false) {
-            devLog("hyperframes.render.dispatched_async", {
-                composition_id: prep.metadata.compositionId,
-                render_id: prep.renderId,
-                execution_arn: handle.executionArn
-            });
-            return {
-                ...handle,
-                outputUrl: null,
-                outputS3Uri: handle.outputS3Uri,
-                endedAt: null,
-                metadata: {
-                    mode: "hyperframes_lambda",
-                    status: "RUNNING",
-                    stack: prep.stack,
-                    composition: prep.metadata
-                }
-            };
-        }
-        const { getRenderProgress } = await import("@hyperframes/aws-lambda/sdk");
-        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: prep.stack.region,
-                defaultMemorySizeMb: prep.stack.lambdaMemoryMb
-            });
-            pollCount += 1;
-            if (progress.status !== lastLoggedStatus) {
-                devLog("hyperframes.render.progress", {
-                    composition_id: prep.metadata.compositionId,
-                    render_id: prep.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") {
-                devLog("hyperframes.render.succeeded", {
-                    composition_id: prep.metadata.compositionId,
-                    render_id: prep.renderId,
-                    duration_ms: Date.now() - startedAtMs,
-                    output_s3_uri: progress.outputFile?.s3Uri || handle.outputS3Uri,
-                    frames_rendered: progress.framesRendered,
-                    total_frames: progress.totalFrames,
-                    lambdas_invoked: progress.lambdasInvoked,
-                    cost_usd: progress.costs?.accruedSoFarUsd
-                });
-                return this.buildCloudRenderResult(handle, progress, prep.metadata, prep.stack);
-            }
-            if (progress.fatalErrorEncountered || ["FAILED", "TIMED_OUT", "ABORTED"].includes(progress.status)) {
-                devLog("hyperframes.render.failed", {
-                    composition_id: prep.metadata.compositionId,
-                    render_id: prep.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: ${scrubVendorDocLinks(JSON.stringify(progress.errors))}`);
-            }
-            if (Date.now() - startedAtMs > timeoutMs) {
-                devLog("hyperframes.render.timeout", {
-                    composition_id: prep.metadata.compositionId,
-                    render_id: prep.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));
-        }
-    }
-    /**
-     * One non-blocking step of a distributed render, keyed by a stable
-     * `executionName`. The first call stages + dispatches the render to the
-     * HyperFrames render state machine and returns `running` immediately; later
-     * calls (from a re-invoked job runner) DescribeExecution the SAME execution
-     * and either keep waiting, finalize on SUCCEEDED, or report failure. This is
-     * what keeps a 40-minute render off any single Lambda's 15-minute clock.
-     */
-    async renderStep(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.");
-        }
-        // Local/dev has no Step Functions — render in-process, blocking, and finalize
-        // in one step so the devcli and local backend behave exactly as before.
-        if (shouldRenderLocally()) {
-            try {
-                const result = await this.renderLocal({ ...input, compositionHtml });
-                return { state: "succeeded", ...result };
-            }
-            catch (error) {
-                return {
-                    state: "failed",
-                    renderId: input.executionName,
-                    executionArn: null,
-                    message: error instanceof Error ? error.message : String(error)
-                };
-            }
-        }
-        const stack = await resolveHyperframesStack();
-        const executionArn = executionArnFromName(stack.stateMachineArn, input.executionName);
-        const existingStatus = await describeRenderExecutionStatus(executionArn, stack.region);
-        if (existingStatus === null) {
-            // Never dispatched — stage + kick off the render, then park.
-            const prep = await this.prepareCloudRender(input, compositionHtml, input.executionName);
-            const handle = await this.dispatchCloudRender(prep, input);
-            devLog("hyperframes.render.dispatched_async", {
-                composition_id: prep.metadata.compositionId,
-                render_id: prep.renderId,
-                execution_arn: handle.executionArn
-            });
-            return { state: "running", executionArn: handle.executionArn, renderId: handle.renderId, progressFraction: 0.1 };
-        }
-        if (existingStatus === "RUNNING" || existingStatus === "PENDING_REDRIVE") {
-            // Cheap path: DescribeExecution already told us it's still going. Avoid the
-            // heavier GetExecutionHistory pagination that getRenderProgress performs.
-            return { state: "running", executionArn, renderId: input.executionName, progressFraction: 0.5 };
-        }
-        // Terminal (SUCCEEDED / FAILED / TIMED_OUT / ABORTED) — read the full snapshot
-        // for output location, frames, and cost metadata.
-        const { getRenderProgress } = await import("@hyperframes/aws-lambda/sdk");
-        const progress = await getRenderProgress({
-            executionArn,
-            region: stack.region,
-            defaultMemorySizeMb: stack.lambdaMemoryMb
-        });
-        if (progress.status === "SUCCEEDED") {
-            const outputS3Uri = progress.outputFile?.s3Uri || null;
-            if (!outputS3Uri) {
-                return {
-                    state: "failed",
-                    renderId: input.executionName,
-                    executionArn,
-                    message: `HyperFrames render ${input.executionName} reported SUCCEEDED without an output file.`
-                };
-            }
-            const metadata = extractCompositionMetadata(compositionHtml, input);
-            const handleShape = {
-                renderId: input.executionName,
-                executionArn,
-                bucketName: stack.bucketName,
-                stateMachineArn: stack.stateMachineArn,
-                outputS3Uri,
-                // Not carried across re-invocations; unused by downstream consumers,
-                // which read outputS3Uri / outputUrl / renderId / metadata only.
-                projectS3Uri: "",
-                startedAt: progress.startedAt
-            };
-            const result = await this.buildCloudRenderResult(handleShape, progress, metadata, stack);
-            devLog("hyperframes.render.succeeded", {
-                composition_id: metadata.compositionId,
-                render_id: input.executionName,
-                output_s3_uri: outputS3Uri,
-                frames_rendered: progress.framesRendered,
-                total_frames: progress.totalFrames,
-                lambdas_invoked: progress.lambdasInvoked,
-                cost_usd: progress.costs?.accruedSoFarUsd
-            });
-            return { state: "succeeded", ...result };
-        }
-        devLog("hyperframes.render.failed", {
-            render_id: input.executionName,
-            status: progress.status,
-            errors: Array.isArray(progress.errors) ? progress.errors.slice(0, 3) : progress.errors
-        }, "error");
-        return {
-            state: "failed",
-            renderId: input.executionName,
-            executionArn,
-            message: `HyperFrames render ${input.executionName} ${progress.status}: ${scrubVendorDocLinks(JSON.stringify(progress.errors))}`
-        };
-    }
-    async prepareCloudRender(input, compositionHtml, executionName) {
-        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 = executionName || input.executionName || `vf-${metadata.compositionId.slice(0, 40)}-${timestamp}-${randomUUID().slice(0, 8)}`;
-        const outputKey = input.outputKey || `renders/vidfarm/${metadata.compositionId}/${renderId}/output.mp4`;
-        return { metadata, stack, projectDir, renderId, outputKey };
-    }
-    async dispatchCloudRender(prep, input) {
-        devLog("hyperframes.render.dispatch", {
-            composition_id: prep.metadata.compositionId,
-            render_id: prep.renderId,
-            output_key: prep.outputKey,
-            chunk_size: input.chunkSize ?? 240,
-            max_parallel_chunks: input.maxParallelChunks ?? 8
-        });
-        const { renderToLambda } = await import("@hyperframes/aws-lambda/sdk");
-        return renderToLambda({
-            projectDir: prep.projectDir,
-            bucketName: prep.stack.bucketName,
-            stateMachineArn: prep.stack.stateMachineArn,
-            region: prep.stack.region,
-            executionName: prep.renderId,
-            outputKey: prep.outputKey,
-            config: {
-                fps: normalizeRenderFps(prep.metadata.fps),
-                width: prep.metadata.width,
-                height: prep.metadata.height,
-                format: input.format || "mp4",
-                codec: "h264",
-                quality: "standard",
-                chunkSize: input.chunkSize ?? 240,
-                maxParallelChunks: input.maxParallelChunks ?? 8,
-                runtimeCap: "lambda"
-            }
-        });
-    }
-    async buildCloudRenderResult(handle, progress, metadata, stack) {
-        const outputS3Uri = progress.outputFile?.s3Uri || handle.outputS3Uri;
-        return {
-            ...handle,
-            outputS3Uri,
-            outputUrl: outputS3Uri ? await signedS3Url(outputS3Uri, stack.region) : null,
-            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
-            }
-        };
-    }
-    // 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;
-        try {
-            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;
-                }
-            });
-        }
-        catch (error) {
-            throw new Error(scrubVendorDocLinks(error instanceof Error ? error.message : String(error)), { cause: error });
-        }
-        // 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, "vidfarm-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 {
-            try {
-                await executeRenderJob(job, projectDir, framesDir);
-            }
-            catch (error) {
-                throw new Error(scrubVendorDocLinks(error instanceof Error ? error.message : String(error)), { cause: error });
-            }
-            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;
-}
-// The ARCHETYPE / production style of a source video. Detected once per
-// decompose and used two ways: (a) stamped onto the template metadata so the
-// catalog + clip matcher can filter by format, and (b) to CONDITION the
-// per-scene clip annotations, because what counts as a scene's "literal DNA"
-// differs by format — an AI fruit drama is defined by its stylized character +
-// action, a UGC trend by the creator's face/gesture/authenticity, an
-// educational series by the board/diagram/screen, live action by real-world
-// subjects + cinematography. Controlled + extendable; ambiguous videos fall back
-// to "other".
-export const CONTENT_FORMATS = [
-    "ai_fruit_drama", // AI-generated surreal food/object dramas ("fruit drama")
-    "ai_generative_skit", // other AI-generated character skits / dramas
-    "ugc_trend", // phone-shot creator-to-camera trend/challenge
-    "talking_head", // single speaker addressing camera (advice/opinion)
-    "educational_series", // explainer / how-to / lecture / listicle
-    "live_action", // real-world filmed scenes, actors, cinematography
-    "product_demo", // hands-on showcase / unboxing / review
-    "street_interview", // vox-pop / man-on-the-street
-    "reaction_commentary", // reacting to / narrating other footage
-    "cinematic_broll", // moody establishing / atmosphere / montage
-    "screen_recording", // app/screen capture, tutorials, gameplay
-    "animation_motion_graphics", // 2D/3D animation, kinetic typography
-    "other"
-];
-export const DEFAULT_CONTENT_FORMAT = {
-    format: "other",
-    label: "Unclassified",
-    confidence: 0,
-    rationale: "",
-    secondary: []
-};
-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);
-}
-// ---------------------------------------------------------------------------
-// Scene-annotation pass — clip-replacement DNA.
-//
-// A dependent vision pass (runs AFTER scenes are finalized, so annotations line
-// up 1:1 by scene slug) that (1) classifies the whole video's content FORMAT and
-// (2) for each scene emits the literal + viral DNA needed to find a REPLACEMENT
-// clip from the clip library. It reuses the sparse frames already sampled for
-// the main pass (no extra ffmpeg) and the clip library's own controlled tag
-// vocabulary + embedding recipe, so a scene's clip-match query is symmetric with
-// how a candidate clip was tagged/embedded. Non-fatal: callers wrap in .catch().
-// ---------------------------------------------------------------------------
-// Vocabulary for a scene's role in the retention arc. Constrained in the prompt,
-// clamped here; free-form-ish (unknown → "context") so it never blocks output.
-const SCENE_ROLE_VOCAB = [
-    "hook", "build", "reveal", "payoff", "transition", "cta", "proof", "context", "punchline", "loop"
-];
-function asPlainRecord(value) {
-    return value && typeof value === "object" && !Array.isArray(value) ? value : {};
-}
-function readAnnotationString(value) {
-    return typeof value === "string" ? value.trim() : "";
-}
-function readAnnotationStringList(value, max) {
-    if (!Array.isArray(value))
-        return [];
-    const out = [];
-    for (const v of value) {
-        const s = typeof v === "string" ? v.trim() : "";
-        if (s && !out.includes(s))
-            out.push(s);
-        if (out.length >= max)
-            break;
-    }
-    return out;
-}
-function humanizeContentFormat(format) {
-    return format
-        .split("_")
-        .map((w) => w.charAt(0).toUpperCase() + w.slice(1))
-        .join(" ");
-}
-function normalizeContentFormat(raw) {
-    const rec = asPlainRecord(raw);
-    const slug = normalizeSlug(readAnnotationString(rec.format));
-    const format = CONTENT_FORMATS.includes(slug)
-        ? slug
-        : "other";
-    const secondaryRaw = Array.isArray(rec.secondary) ? rec.secondary : [];
-    const secondary = Array.from(new Set(secondaryRaw
-        .map((s) => normalizeSlug(readAnnotationString(s)))
-        .filter((s) => CONTENT_FORMATS.includes(s) && s !== format))).slice(0, 3);
-    const conf = Number(rec.confidence);
-    const label = readAnnotationString(rec.label);
-    return {
-        format,
-        label: label || humanizeContentFormat(format),
-        confidence: Number.isFinite(conf) ? Math.max(0, Math.min(1, conf)) : 0,
-        rationale: readAnnotationString(rec.rationale),
-        secondary
-    };
-}
-function normalizeSceneRole(value) {
-    const slug = normalizeSlug(readAnnotationString(value));
-    return SCENE_ROLE_VOCAB.includes(slug) ? slug : "context";
-}
-function normalizeReplaceability(value) {
-    const s = readAnnotationString(value).toLowerCase();
-    return s === "high" || s === "low" ? s : "medium";
-}
-// Deterministic per-scene spoken text pulled from the transcript segments that
-// overlap the scene window — more reliable than asking the vision model to
-// re-transcribe, and keeps `tags.transcript` grounded in the audio pass.
-function transcriptForScene(transcript, scene) {
-    if (!transcript || !Array.isArray(transcript.segments))
-        return "";
-    const end = scene.start + scene.duration;
-    return transcript.segments
-        .filter((seg) => seg.end > scene.start && seg.start < end)
-        .map((seg) => seg.text.trim())
-        .filter((t) => t.length > 0)
-        .join(" ")
-        .trim();
-}
-// Compose the retrieval query text. Leads with the clip-doc recipe (description +
-// tags) so it lands near literally-similar clip embeddings, then appends the
-// viral purpose so the vector also reflects the beat's INTENT — a replacement
-// must match both axes.
-function buildSceneEmbeddingText(input) {
-    const literalDoc = buildClipEmbeddingText(input.tags, input.literal);
-    const purpose = [
-        input.scene_role ? `Role: ${input.scene_role}` : "",
-        input.narrative_purpose,
-        input.why_it_works
-    ].filter((p) => p && p.length > 0).join(". ");
-    return purpose ? `${literalDoc}\nPurpose: ${purpose}` : literalDoc;
-}
-// Turn a scene's literal tags into a ready-to-run SplicingCriteria for the clip
-// library. Tag constraints are the high-precision structured filter; the
-// duration floor lets candidates be trimmed to fit; has_subject/has_dialogue are
-// derived from the tags. semantic_text carries the embedding query for re-rank.
-function buildSceneMatchCriteria(tags, scene, semanticText) {
-    const criteria = { semantic_text: semanticText };
-    if (tags.subject.length)
-        criteria.subject = tags.subject;
-    if (tags.action.length)
-        criteria.action = tags.action;
-    if (tags.emotion.length)
-        criteria.emotion = tags.emotion;
-    if (tags.setting.length)
-        criteria.setting = tags.setting;
-    if (tags.composition.length)
-        criteria.composition = tags.composition;
-    if (tags.motion.length)
-        criteria.motion = tags.motion;
-    if (tags.audio_type.length)
-        criteria.audio_type = tags.audio_type;
-    if (tags.energy)
-        criteria.energy = [tags.energy];
-    if (Number.isFinite(scene.duration) && scene.duration > 0) {
-        criteria.min_duration_sec = Number(Math.max(0, scene.duration * 0.6).toFixed(2));
-    }
-    const hasRealSubject = tags.subject.some((s) => s !== "no_subject");
-    if (hasRealSubject)
-        criteria.has_subject = true;
-    else if (tags.subject.includes("no_subject"))
-        criteria.has_subject = false;
-    if (tags.audio_type.includes("dialogue"))
-        criteria.has_dialogue = true;
-    return criteria;
-}
-function buildSceneAnnotationPrompt(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 sceneListing = input.scenes.map((s) => (`  - scene_slug="${s.slug}" @ ${s.start.toFixed(2)}s for ${s.duration.toFixed(2)}s — ${s.label}: ${s.description || "(no description)"}${s.viral_note ? ` [viral note: ${s.viral_note}]` : ""}`)).join("\n");
-    const dna = input.viralDna;
-    const dnaBlock = `Video-level viral DNA (context for each scene's PURPOSE):\n  hook: ${dna.hook || "—"}\n  retention: ${dna.retention || "—"}\n  payoff: ${dna.payoff || "—"}\n  preserve: ${(dna.preserve || []).join("; ") || "—"}\n  avoid: ${(dna.avoid || []).join("; ") || "—"}`;
-    const userGuidance = input.userPrompt && input.userPrompt.trim().length > 0
-        ? `\nUSER GUIDANCE (highest priority):\n"""\n${input.userPrompt.trim()}\n"""\n`
-        : "";
-    return `You are Vidfarm's scene annotator. For EACH scene of this short-form vertical video, write an annotation rich enough to do TWO things: (A) find a REPLACEMENT clip from a searchable clip library — a different piece of footage that could stand in for this scene without breaking the video; and (B) let an AI agent RE-CREATE this scene from scratch with an image/video generator when no library clip fits.
-
-Both goals hang on capturing the same TWO axes:
-  1) LITERAL DNA — what is physically on screen (subject, action, setting, shot, motion, mood). A candidate or generated clip must look and feel like this.
-  2) VIRAL / NARRATIVE DNA — the ROLE this beat plays in why the video works (the hook, the reveal, the payoff, a transition...). A replacement or regeneration must serve the same purpose in the story, or the swap kills retention.
-${userGuidance}
-FIRST classify the whole video's FORMAT (its production archetype) — what counts as "literal DNA" differs by format. Pick the single best "format" and list any close seconds in "secondary". Allowed formats:
-  ${CONTENT_FORMATS.join(", ")}
-Format guidance: ai_fruit_drama / ai_generative_skit = AI-generated surreal character dramas (e.g. talking fruit); ugc_trend = phone-shot creator-to-camera trend; talking_head = single speaker giving advice; educational_series = explainer / how-to / listicle; live_action = real filmed scenes / actors; product_demo = hands-on showcase / unboxing; street_interview = man-on-the-street; reaction_commentary = reacting to other footage; cinematic_broll = moody montage / atmosphere; screen_recording = app / screen capture; animation_motion_graphics = animation / kinetic text.
-
-Video duration: ${input.durationSeconds.toFixed(2)}s. One-line summary: ${input.summary || "(none)"}.
-${dnaBlock}
-${frameListing}
-SCENES to annotate (return EXACTLY one annotation per scene_slug below, in this order):
-${sceneListing}
-
-For the LITERAL "tags", use ONLY values from this controlled vocabulary — it is the SAME vocabulary the clip library is tagged with, so your tags must line up with how a candidate clip would be tagged:
-${taxonomyForPrompt()}
-
-Return strictly valid JSON matching this schema:
-{
-  "content_format": { "format": string, "label": string, "confidence": number, "rationale": string, "secondary": [string, ...] },
-  "scenes": [{
-    "scene_slug": string,
-    "literal": string,
-    "tags": { "subject": [string], "action": [string], "emotion": [string], "setting": [string], "composition": [string], "motion": [string], "energy": "low"|"medium"|"high", "audio_type": [string], "transcript": string },
-    "scene_role": string,
-    "narrative_purpose": string,
-    "why_it_works": string,
-    "must_preserve": [string, ...],
-    "can_vary": [string, ...],
-    "replaceability": "high"|"medium"|"low",
-    "replaceability_reason": string,
-    "recreation_prompt": string,
-    "recreation_notes": [string, ...]
-  }]
-}
-
-RULES:
-- Output one scene object per scene_slug listed above, using the EXACT scene_slug strings. Do not invent, merge, split, or reorder scenes.
-- "literal": one concrete, factual sentence describing exactly what is on screen in this scene (subject + action + setting + shot). This is the primary match key — be specific and visual, not interpretive.
-- "tags": pick only vocabulary values you are confident about from the frames; omit a category (empty list) rather than guess. "energy" is a single value. "transcript" = words spoken in this scene verbatim, or "" if none.
-- "scene_role": one of ${SCENE_ROLE_VOCAB.join(", ")} — the function this beat serves in the retention arc.
-- "narrative_purpose" / "why_it_works": the viral DNA — WHY this beat exists and how it holds attention. A replacement clip must reproduce this effect, not just the look.
-- "must_preserve": 1-4 things a replacement MUST keep (e.g. "subject facing camera", "surprised reaction on the beat drop", "product clearly visible"). "can_vary": 1-4 things free to change (specific person, exact background, color grade).
-- "replaceability": how safely this scene can be swapped from generic library clips. "low" for scenes carrying unique baked-in text / a specific face / a spoken payoff; "high" for generic b-roll / cutaways / establishing shots. Explain in "replaceability_reason".
-- "recreation_prompt": a self-contained generative brief an AI agent could paste into a text-to-image/video model to REGENERATE this exact beat — describe subject, action, setting, framing, camera move, lighting, mood, art style, and pacing in one rich paragraph. Write it in the idiom of the detected format (e.g. an ai_fruit_drama prompt reads like a stylized 3D-character render brief; a live_action prompt reads like a cinematography direction). Do NOT reference "this video" or timestamps — it must stand alone.
-- "recreation_notes": 2-5 short discrete production directives that back up the recreation_prompt (e.g. "9:16 vertical", "handheld push-in", "soft key light from left", "on-screen text: 'wait for it'", "cut on the beat at ~1.2s", "dialogue VO: <verbatim line>"). Include any exact on-screen text or spoken line that must be reproduced.
-- Match your vocabulary and framing to the detected format above.`;
-}
-async function runSceneAnnotationPass(input) {
-    if (input.frames.length === 0 || input.scenes.length === 0) {
-        return { contentFormat: DEFAULT_CONTENT_FORMAT, annotations: [], provider: null, model: null };
-    }
-    const prompt = buildSceneAnnotationPrompt({
-        durationSeconds: input.durationSeconds,
-        frameTimestamps: input.frames.map((f) => f.timestamp),
-        scenes: input.scenes,
-        viralDna: input.viralDna,
-        summary: input.summary,
-        userPrompt: input.userPrompt ?? null
-    });
-    const attempt = await callVisionWithFallback({ prompt, frames: input.frames, keys: input.keys });
-    const record = asPlainRecord(attempt.result);
-    const contentFormat = normalizeContentFormat(record.content_format);
-    const rawScenes = Array.isArray(record.scenes) ? record.scenes : [];
-    const bySlug = new Map();
-    for (const r of rawScenes) {
-        const rec = asPlainRecord(r);
-        const slug = normalizeSlug(readAnnotationString(rec.scene_slug));
-        if (slug && !bySlug.has(slug))
-            bySlug.set(slug, rec);
-    }
-    // Iterate the FINALIZED scenes (not the model output) so every scene gets
-    // exactly one annotation aligned by slug, even if the model dropped, renamed,
-    // or duplicated one. Missing fields degrade to the scene's own description.
-    const annotations = input.scenes.map((scene) => {
-        const raw = bySlug.get(scene.slug) ?? {};
-        const tags = {
-            ...sanitizeTagValues(asPlainRecord(raw.tags)),
-            transcript: transcriptForScene(input.transcript, scene) || readAnnotationString(asPlainRecord(raw.tags).transcript)
-        };
-        const literal = readAnnotationString(raw.literal) || scene.description || scene.label;
-        const scene_role = normalizeSceneRole(raw.scene_role);
-        const narrative_purpose = readAnnotationString(raw.narrative_purpose) || scene.viral_note;
-        const why_it_works = readAnnotationString(raw.why_it_works);
-        const embedding_text = buildSceneEmbeddingText({ literal, tags, scene_role, narrative_purpose, why_it_works });
-        return {
-            scene_slug: scene.slug,
-            start: scene.start,
-            duration: scene.duration,
-            content_format: contentFormat.format,
-            literal,
-            tags,
-            scene_role,
-            narrative_purpose,
-            why_it_works,
-            must_preserve: readAnnotationStringList(raw.must_preserve, 4),
-            can_vary: readAnnotationStringList(raw.can_vary, 4),
-            replaceability: normalizeReplaceability(raw.replaceability),
-            replaceability_reason: readAnnotationString(raw.replaceability_reason),
-            embedding_text,
-            match_criteria: buildSceneMatchCriteria(tags, scene, embedding_text),
-            // Fall back to the literal + purpose if the model omitted a recreation
-            // brief, so an agent always has *something* to regenerate from.
-            recreation_prompt: readAnnotationString(raw.recreation_prompt)
-                || [literal, narrative_purpose].filter((p) => p.length > 0).join(" "),
-            recreation_notes: readAnnotationStringList(raw.recreation_notes, 6)
-        };
-    });
-    return { contentFormat, annotations, provider: attempt.provider, model: attempt.model };
-}
-// Standalone entry point for the ASYNC scene-annotation pass, invoked once per
-// /scene-annotations-poll. Mirrors analyzeCastMembers: it re-downloads the
-// (caption-free) source, re-samples the same sparse frames the main decompose
-// used, and runs the annotation vision call against the ALREADY-finalized scenes
-// (passed in from the persisted smart-decompose snapshot) so annotations align
-// 1:1 by slug. Kept out of the synchronous decompose so that request stays under
-// the origin timeout.
-export async function annotateScenesFromSource(input) {
-    if (input.scenes.length === 0) {
-        return { contentFormat: DEFAULT_CONTENT_FORMAT, annotations: [], provider: null, model: null, durationSeconds: 0 };
-    }
-    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.scene_annotations.start", { source_url: input.sourceUrl, scene_count: input.scenes.length });
-    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");
-        }
-        const frames = await sampleFramesAsBase64(sourcePath, meta.durationSeconds, tempDir);
-        const outcome = await runSceneAnnotationPass({
-            frames,
-            keys: input.keys,
-            durationSeconds: meta.durationSeconds,
-            scenes: input.scenes,
-            viralDna: input.viralDna,
-            summary: input.summary,
-            transcript: input.transcript,
-            userPrompt: input.userPrompt ?? null
-        });
-        devLog("hyperframes.scene_annotations.completed", {
-            provider: outcome.provider,
-            model: outcome.model,
-            duration_ms: Date.now() - startedAt,
-            content_format: outcome.contentFormat.format,
-            annotation_count: outcome.annotations.length
-        });
-        return { ...outcome, durationSeconds: meta.durationSeconds };
-    }
-    catch (error) {
-        devLog("hyperframes.scene_annotations.failed", {
-            source_url: input.sourceUrl,
-            duration_ms: Date.now() - startedAt,
-            ...devErrorFields(error)
-        }, "error");
-        throw error;
-    }
-    finally {
-        await rm(tempDir, { recursive: true, force: true });
-    }
-}
-// The frames handed to the vision passes are SILENT stills — but a short-form
-// video's emotional punch is often carried by its AUDIO (the trending sound, a
-// music-bed drop, vocal intonation, a punchline's delivery). This digest folds
-// the transcript pass into a compact block so the viral-DNA and editor-harness
-// prompts can reason about the sound, not just the pixels. Music-only clips
-// (no speech) still get a note so the model infers a trending-sound bed rather
-// than guessing there is silence.
-function buildAudioDigestForPrompt(transcript) {
-    if (!transcript) {
-        return `\nAUDIO TRACK: none detected, or transcription unavailable. Judge emotional punch from the visuals, on-screen text, and pacing alone — and do not fabricate spoken lines, music, or a trending sound you cannot infer.\n`;
-    }
-    const text = (transcript.text || "").trim();
-    const clipped = text.length > 1200 ? `${text.slice(0, 1200)} …` : text;
-    const segs = transcript.segments.slice(0, 24)
-        .map((s) => `  [${s.start.toFixed(1)}-${s.end.toFixed(1)}s] ${s.text.trim()}`)
-        .filter((line) => line.trim().length > 0)
-        .join("\n");
-    return `\nAUDIO TRANSCRIPT — the video's spoken/sung audio. The SOUND is a primary driver of emotional punch: read the words, the intonation and cadence they imply, WHERE the delivery lands (the pause before a punchline, an exclamation, a beat-synced line), and infer any music / trending-sound bed even when there are no lyrics.
-- language: ${transcript.language ?? "unknown"}
-- full text: ${clipped || "(no speech transcribed — likely a music-only or trending-sound bed; treat the audio as a music/sound-driven format and reason about the beat/drop, not dialogue)"}${segs ? `\n- timed lines:\n${segs}` : ""}
-`;
-}
-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`
-        : "";
-    const audioDigest = buildAudioDigestForPrompt(input.transcript ?? null);
-    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}${audioDigest}
-
-Return strictly valid JSON matching this schema:
-{
-  "summary": string,
-  "viral_dna": {
-    "trend_tagline": string,
-    "hook": string,
-    "retention": string,
-    "payoff": string,
-    "emotional_punch": {
-      "core_emotion": string,
-      "tone": string,
-      "arc": string,
-      "peak_moment": string,
-      "mechanism": string,
-      "contrast": string,
-      "humor": string,
-      "audio_visual_tension": string,
-      "delivery": string,
-      "preserve": [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).
-- "emotional_punch": the FEELING this format delivers and exactly what makes it land — the part remixes most often flatten. hook/retention/payoff are the mechanical structure; this is the vibe, the joke, and the intonation that make a viewer actually FEEL something. Fill EVERY sub-field:
-  - "core_emotion": the dominant feeling a viewer walks away with (e.g. "delighted surprise", "righteous validation", "warm nostalgia", "second-hand cringe", "smug satisfaction").
-  - "tone": the register / vibe in 1-3 words (comedic, deadpan, earnest, dramatic, wholesome, chaotic, satirical, hype, ...).
-  - "arc": how the feeling MOVES across the runtime (e.g. "curiosity → mounting tension → relief-laugh", "flat setup → sudden absurd turn").
-  - "peak_moment": the single beat that lands the emotional hit — the punchline, the reveal, the gut-punch, the beat-drop — and roughly when.
-  - "mechanism": WHY it lands — the technique doing the work (comedic timing, irony, subversion of expectation, escalation, deadpan intonation, relatability, a trending-sound drop synced to the visual). Weigh the AUDIO here: on TikTok/Reels the trending sound or music bed is frequently the single biggest driver of the emotional hit, so if a recognizable trending sound, a beat drop, or a music swell is doing the work, name it as the mechanism.
-  - "contrast": the specific mismatch / juxtaposition that creates the feeling. This is CRITICAL for irony- or sass-driven formats: identify the actual tension, not just the visible gesture. Examples: "hard, macho soundtrack over a dainty office-laptop scene", "overconfident delivery about a trivial preference", "luxury attitude applied to a mundane workflow". If there is no real mismatch, write "none".
-  - "humor": if it's funny, state what the JOKE actually is and why it works, concretely enough that a remixer can rebuild the same joke with new subject matter; write "none" if the format is not comedic. Focus on the underlying bit, not surface choreography.
-  - "audio_visual_tension": describe how the SOUND and VISUALS interact emotionally: whether the soundtrack / vocal cadence reinforces the visuals, undercuts them, or creates a deliberate mismatch. Name the exact pairing if that's the joke or swagger engine; write "none" only if audio contributes nothing.
-  - "delivery": the performance cues to preserve so the vibe survives — speech intonation / cadence (from the AUDIO TRANSCRIPT), the pause held before the punchline, a facial beat or reaction, and especially the SOUND: the music / trending-audio bed, where the beat drop or lyric hit lands relative to the cut, a music swell, an sfx sting, the deadpan-then-cut. This is what keeps intonation, comedic timing, and the audio-driven vibe from being lost in a remix.
-  - "preserve": 2-4 emotional beats a remix MUST keep to reproduce the same feeling (e.g. "keep the beat drop landing exactly on the reveal cut", "hold the silent beat before the reveal", "keep the flat unbothered delivery", "the payoff must undercut the buildup, not confirm it").
-  Use BOTH the frames and the AUDIO TRANSCRIPT block above. Never leave emotional_punch empty — infer the feeling from the frames, captions, and pacing even when there is no audio, and when the audio is music-only, treat the sound itself as the emotional engine. Do NOT over-index on a single gesture or hand movement if the real emotional engine is the character attitude, the soundtrack choice, the setting mismatch, or the audio-vs-visual contrast.
-- "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_EMOTIONAL_PUNCH = {
-    core_emotion: "",
-    tone: "",
-    arc: "",
-    peak_moment: "",
-    mechanism: "",
-    contrast: "",
-    humor: "",
-    audio_visual_tension: "",
-    delivery: "",
-    preserve: []
-};
-export const DEFAULT_VIRAL_DNA = {
-    trend_tagline: "", hook: "", retention: "", payoff: "", emotional_punch: { ...DEFAULT_EMOTIONAL_PUNCH }, preserve: [], avoid: [], promotions: [], keywords: []
-};
-function normalizeEmotionalPunch(value) {
-    if (!value || typeof value !== "object")
-        return { ...DEFAULT_EMOTIONAL_PUNCH };
-    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 {
-        core_emotion: asString(record.core_emotion ?? record.coreEmotion),
-        tone: asString(record.tone),
-        arc: asString(record.arc ?? record.emotional_arc),
-        peak_moment: asString(record.peak_moment ?? record.peakMoment),
-        mechanism: asString(record.mechanism),
-        contrast: asString(record.contrast),
-        humor: asString(record.humor),
-        audio_visual_tension: asString(record.audio_visual_tension ?? record.audioVisualTension),
-        delivery: asString(record.delivery),
-        preserve: asStringArray(record.preserve).slice(0, 4)
-    };
-}
-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),
-        emotional_punch: normalizeEmotionalPunch(record.emotional_punch ?? record.emotionalPunch),
-        preserve: asStringArray(record.preserve),
-        avoid: asStringArray(record.avoid),
-        promotions: asStringArray(record.promotions),
-        keywords: asStringArray(record.keywords).map((item) => item.toLowerCase())
-    };
-}
-// ---------------------------------------------------------------------------
-// Editor-harness pass — technical editing direction (the "how to edit like
-// this" companion to viral DNA's "why it works"). Isolated vision call in the
-// decompose burst (never the caption/scene call) so it can't dilute
-// timeline-layer quality; reuses the SAME sparse frames already sampled + the
-// ffmpeg cut timings for grounded pacing. Non-fatal: callers wrap in .catch().
-// ---------------------------------------------------------------------------
-export const DEFAULT_EDITOR_HARNESS = {
-    format: "other",
-    one_liner: "",
-    aspect_ratio: "",
-    pacing: { cut_rhythm: "medium", avg_scene_seconds: 0, cuts_per_10s: 0, energy_curve: "" },
-    typography: { caption_style: "", placement: "", font_character: "", emphasis: "", text_density: "none" },
-    broll: { reliance: "none", sourcing: "", shot_kinds: [], cadence: "" },
-    transitions: { default: "cut", intro: "", outro: "", usage: "" },
-    audio: { voiceover: "", music: "", sfx: "", captions_from: "" },
-    emotional: { target_feeling: "", tone: "", comedic_timing: "", intonation: "", vibe_anchors: [] },
-    scenes: [],
-    important_scenes: [],
-    editing_bias: [],
-    do: [],
-    dont: []
-};
-const HARNESS_CUT_RHYTHMS = ["fast", "medium", "slow", "varied"];
-const HARNESS_TEXT_DENSITY = ["heavy", "moderate", "minimal", "none"];
-const HARNESS_BROLL_RELIANCE = ["heavy", "moderate", "light", "none"];
-const HARNESS_SCENE_IMPORTANCE = ["critical", "high", "normal"];
-function buildEditorHarnessPrompt(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 cutListing = input.sceneCuts.length > 0
-        ? `\nDETECTED HARD CUTS (seconds, from the editing timeline — use these to ground pacing/cut_rhythm/cuts_per_10s/avg_scene_seconds): ${input.sceneCuts.map((c) => c.toFixed(2)).join(", ")}\n`
-        : "\n(No hard cuts detected — likely a single continuous take or slow crossfades. Judge pacing from the frames.)\n";
-    const promptHint = input.userPrompt && input.userPrompt.trim().length > 0
-        ? `\nUSER GOAL (bias the harness toward recreating THIS intent): ${input.userPrompt.trim()}\n`
-        : "";
-    const roleVocab = SCENE_ROLE_VOCAB.join(" | ");
-    const formatVocab = CONTENT_FORMATS.join(" | ");
-    const audioDigest = buildAudioDigestForPrompt(input.transcript ?? null);
-    const emotional = input.viralDna?.emotional_punch;
-    const emotionalSnapshot = emotional && [
-        emotional.core_emotion,
-        emotional.tone,
-        emotional.arc,
-        emotional.peak_moment,
-        emotional.mechanism,
-        emotional.contrast,
-        emotional.humor,
-        emotional.audio_visual_tension,
-        emotional.delivery
-    ].some((value) => value && value.trim().length > 0)
-        ? `\nVIRAL DNA FEELING SNAPSHOT (operationalize this in the harness; do NOT drift from it):\n- core_emotion: ${emotional.core_emotion || "—"}\n- tone: ${emotional.tone || "—"}\n- arc: ${emotional.arc || "—"}\n- peak_moment: ${emotional.peak_moment || "—"}\n- mechanism: ${emotional.mechanism || "—"}\n- contrast: ${emotional.contrast || "—"}\n- humor: ${emotional.humor || "—"}\n- audio_visual_tension: ${emotional.audio_visual_tension || "—"}\n- delivery: ${emotional.delivery || "—"}\n- preserve: ${(emotional.preserve || []).join("; ") || "—"}\n`
-        : "";
-    return `You are Vidfarm's EDITING DIRECTOR. You are studying a short-form video to write an EDITOR HARNESS — a compact, technical brief that lets another AI editor recreate this video's STYLE (not its exact content) in one clean pass on a timeline editor (scenes, captions, audio, transitions, keyframes).
-
-This is DIFFERENT from "viral DNA" (why the video works / what to preserve). The harness is HOW to edit: pace, typography, b-roll usage, transitions, audio bed, and the role each scene plays. Be concrete and directive — every field should be something an editor can act on, not vibes.
-
-Video duration: ${input.durationSeconds.toFixed(2)} seconds.
-${frameListing}${cutListing}${audioDigest}${emotionalSnapshot}${promptHint}
-Return strictly valid JSON matching this schema:
-{
-  "format": string,                 // one of: ${formatVocab}
-  "one_liner": string,              // ONE sentence: how to edit to match this style
-  "aspect_ratio": string,           // "9:16" | "1:1" | "16:9" (infer from the frames)
-  "pacing": {
-    "cut_rhythm": "fast" | "medium" | "slow" | "varied",
-    "avg_scene_seconds": number,    // typical shot length in seconds
-    "cuts_per_10s": number,         // ground on the detected cuts + duration
-    "energy_curve": string          // e.g. "front-loaded hook then steady"
-  },
-  "typography": {
-    "caption_style": string,        // karaoke | word-pop | spotlight | stack-up | neon | bounce | none | free-form label
-    "placement": string,            // e.g. "center-lower" | "top" | "full-bleed" | "none"
-    "font_character": string,       // e.g. "bold condensed all-caps sans"
-    "emphasis": string,             // e.g. "active-word highlight in yellow" | "none"
-    "text_density": "heavy" | "moderate" | "minimal" | "none"
-  },
-  "broll": {
-    "reliance": "heavy" | "moderate" | "light" | "none",
-    "sourcing": string,             // generated | stock | screen-recording | talking-head | mixed
-    "shot_kinds": [string, ...],    // e.g. b_roll, product_shot, screen_recording, reaction, establishing, text_graphic
-    "cadence": string               // e.g. "new visual ~every 2s under VO"
-  },
-  "transitions": {
-    "default": string,              // junction at most cuts: cut | crossfade | whip | slide | zoom | dissolve | ...
-    "intro": string,                // first-clip entrance
-    "outro": string,                // last-clip exit
-    "usage": string                 // one line on how transitions are used
-  },
-  "audio": {
-    "voiceover": string,            // e.g. "first-person narration" | "none"
-    "music": string,                // e.g. "upbeat lofi bed, low volume" | "none"
-    "sfx": string,                  // e.g. "whoosh on cuts" | "none"
-    "captions_from": string         // "voiceover" | "on-screen text" | "none"
-  },
-  "emotional": {
-    "target_feeling": string,       // the emotion the edit must reproduce (the vibe/joke that makes it land)
-    "tone": string,                 // register to hold: comedic | deadpan | earnest | dramatic | wholesome | hype | ...
-    "comedic_timing": string,       // where the beat/pause/cut sells the joke; "none" if not comedic
-    "intonation": string,           // vocal delivery/cadence to preserve on VO or on-cam speech; "none" if silent
-    "vibe_anchors": [string, ...]   // 2-4 concrete edit moves that carry the emotion
-  },
-  "scenes": [{
-    "role": string,                 // ${roleVocab}
-    "timestamp": string,            // human range, e.g. "0:00-0:03"
-    "start": number,                // numeric seconds where the beat begins
-    "importance": "critical" | "high" | "normal",
-    "must_keep": boolean,           // true if swapping/removing this beat kills the style
-    "note": string,                 // what happens in this beat
-    "edit_bias": string             // how to edit this beat while staying on-style
-  }],
-  "important_scenes": [string, ...],// roles or timestamps that carry the virality — protect when editing
-  "editing_bias": [string, ...],    // 3-6 top directives an editor MUST follow to stay on-style
-  "do": [string, ...],              // 2-5 concrete DOs
-  "dont": [string, ...]             // 2-5 concrete DON'Ts
-}
-
-RULES:
-- Ground pacing numbers on the detected cuts + duration when cuts are supplied; otherwise estimate from the frames. Round avg_scene_seconds and cuts_per_10s to at most 2 decimals.
-- "scenes": 3-8 entries covering the whole runtime in order, each tied to a real moment you see. Reserve importance "critical" for the 1-3 beats that actually carry the style/retention (usually the hook + payoff).
-- Prefer the caption_style / transition / shot_kind vocabulary above so the editor can map straight to presets; a free-form label is fine when nothing fits.
-- "emotional": this is HOW to edit so the FEELING survives — the vibe, the joke, the intonation, and the SOUND are the first things a remix flattens, so make these directive. Use the AUDIO TRANSCRIPT block: on TikTok/Reels the trending sound / music bed is often the biggest carrier of the feeling. "target_feeling" = the emotion the recreated edit must produce; "tone" = the register to hold; "comedic_timing" = the exact editing move that sells the joke (the beat held before a cut, the deadpan-then-punch, the sfx sting or beat-drop on the button word) or "none"; "intonation" = the vocal delivery/cadence to preserve on any VO or on-cam speech (or "none" if silent) — flag it if the speech must be re-voiced in the SAME cadence; "vibe_anchors" = 2-4 concrete edit choices that carry the emotion, and include the audio ones (e.g. "keep the trending sound and land the beat drop on the reveal cut", "swell the music on the payoff", "hold a full beat of silence before the reveal cut", "cut hard on the punch word"). When the viral-DNA snapshot above names a contrast or audio_visual_tension, convert that into actionable edit moves instead of drifting to superficial gestures. Infer the feeling from frames + pacing even without audio, and when the audio is music-only treat the sound as the emotional engine; never leave it empty.
-- Keep every string tight and directive. Never invent audio you cannot infer — say "none"/"unknown" instead.
-- Output ONLY the JSON object.`;
-}
-function normalizeEditorHarness(raw) {
-    const rec = asPlainRecord(raw);
-    const oneOf = (value, allowed, fallback) => {
-        const s = normalizeSlug(readAnnotationString(value));
-        return allowed.includes(s) ? s : fallback;
-    };
-    const num = (value) => {
-        const n = Number(value);
-        return Number.isFinite(n) && n >= 0 ? Number(n.toFixed(2)) : 0;
-    };
-    const formatSlug = normalizeSlug(readAnnotationString(rec.format));
-    const format = CONTENT_FORMATS.includes(formatSlug)
-        ? formatSlug
-        : "other";
-    const pacing = asPlainRecord(rec.pacing);
-    const typography = asPlainRecord(rec.typography);
-    const broll = asPlainRecord(rec.broll);
-    const transitions = asPlainRecord(rec.transitions);
-    const audio = asPlainRecord(rec.audio);
-    const emotional = asPlainRecord(rec.emotional);
-    const scenesRaw = Array.isArray(rec.scenes) ? rec.scenes : [];
-    const scenes = scenesRaw
-        .map((s) => {
-        const sr = asPlainRecord(s);
-        return {
-            role: normalizeSlug(readAnnotationString(sr.role)) || "context",
-            timestamp: readAnnotationString(sr.timestamp),
-            start: num(sr.start),
-            importance: oneOf(sr.importance, HARNESS_SCENE_IMPORTANCE, "normal"),
-            must_keep: sr.must_keep === true,
-            note: readAnnotationString(sr.note),
-            edit_bias: readAnnotationString(sr.edit_bias)
-        };
-    })
-        .filter((s) => s.note.length > 0 || s.edit_bias.length > 0)
-        .slice(0, 12);
-    return {
-        format,
-        one_liner: readAnnotationString(rec.one_liner),
-        aspect_ratio: readAnnotationString(rec.aspect_ratio),
-        pacing: {
-            cut_rhythm: oneOf(pacing.cut_rhythm, HARNESS_CUT_RHYTHMS, "medium"),
-            avg_scene_seconds: num(pacing.avg_scene_seconds),
-            cuts_per_10s: num(pacing.cuts_per_10s),
-            energy_curve: readAnnotationString(pacing.energy_curve)
-        },
-        typography: {
-            caption_style: readAnnotationString(typography.caption_style),
-            placement: readAnnotationString(typography.placement),
-            font_character: readAnnotationString(typography.font_character),
-            emphasis: readAnnotationString(typography.emphasis),
-            text_density: oneOf(typography.text_density, HARNESS_TEXT_DENSITY, "none")
-        },
-        broll: {
-            reliance: oneOf(broll.reliance, HARNESS_BROLL_RELIANCE, "none"),
-            sourcing: readAnnotationString(broll.sourcing),
-            shot_kinds: readAnnotationStringList(broll.shot_kinds, 8),
-            cadence: readAnnotationString(broll.cadence)
-        },
-        transitions: {
-            default: readAnnotationString(transitions.default) || "cut",
-            intro: readAnnotationString(transitions.intro),
-            outro: readAnnotationString(transitions.outro),
-            usage: readAnnotationString(transitions.usage)
-        },
-        audio: {
-            voiceover: readAnnotationString(audio.voiceover),
-            music: readAnnotationString(audio.music),
-            sfx: readAnnotationString(audio.sfx),
-            captions_from: readAnnotationString(audio.captions_from)
-        },
-        emotional: {
-            target_feeling: readAnnotationString(emotional.target_feeling),
-            tone: readAnnotationString(emotional.tone),
-            comedic_timing: readAnnotationString(emotional.comedic_timing),
-            intonation: readAnnotationString(emotional.intonation),
-            vibe_anchors: readAnnotationStringList(emotional.vibe_anchors, 4)
-        },
-        scenes,
-        important_scenes: readAnnotationStringList(rec.important_scenes, 8),
-        editing_bias: readAnnotationStringList(rec.editing_bias, 8),
-        do: readAnnotationStringList(rec.do, 6),
-        dont: readAnnotationStringList(rec.dont, 6)
-    };
-}
-async function runEditorHarnessPass(input) {
-    if (input.frames.length === 0)
-        return DEFAULT_EDITOR_HARNESS;
-    const prompt = buildEditorHarnessPrompt({
-        durationSeconds: input.durationSeconds,
-        frameTimestamps: input.frames.map((f) => f.timestamp),
-        sceneCuts: input.sceneCuts,
-        userPrompt: input.userPrompt ?? null,
-        transcript: input.transcript ?? null,
-        viralDna: input.viralDna ?? null
-    });
-    const attempt = await callVisionWithFallback({ prompt, frames: input.frames, keys: input.keys });
-    return normalizeEditorHarness(attempt.result);
-}
-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}` }
-        });
-    }
-    // OpenRouter proxies many models and still accepts the classic Chat
-    // Completions params. Native OpenAI's current models (gpt-5.x / o-series)
-    // rejected `max_tokens` (they require `max_completion_tokens`) and only allow
-    // the default temperature, so sending `max_tokens`/`temperature:0.15` 400s
-    // every call. Branch the body by endpoint.
-    const isOpenRouter = Boolean(input.endpoint && input.endpoint.includes("openrouter"));
-    // Give the JSON response room to breathe so a video with 12+ text overlays
-    // doesn't get truncated (same rationale as Gemini's maxOutputTokens).
-    const OUTPUT_TOKEN_BUDGET = 16384;
-    const body = {
-        model: input.model,
-        response_format: { type: "json_object" },
-        messages: [{ role: "user", content }]
-    };
-    if (isOpenRouter) {
-        body.temperature = 0.15;
-        body.max_tokens = OUTPUT_TOKEN_BUDGET;
-    }
-    else {
-        body.max_completion_tokens = OUTPUT_TOKEN_BUDGET;
-    }
-    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(body)
-    });
-    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).
-        // Phase 1 — deterministic ffmpeg/whisper work up front. Transcription is
-        // pulled INTO this phase (chained off the audio extract) so the transcript
-        // is ready BEFORE the vision + harness passes run: emotional punch on
-        // short-form video is frequently carried by the AUDIO (a trending sound, a
-        // beat drop, vocal intonation), and the silent frames alone can't capture
-        // it. The transcript overlaps with frame-sampling/OCR/cut-detection here
-        // instead of with the vision call, so this stays roughly latency-neutral.
-        const [frames, ocrRawFrames, transcript, sceneCuts] = await Promise.all([
-            sampleFramesAsBase64(sourcePath, meta.durationSeconds, tempDir),
-            extractDenseOcrFrames(sourcePath, meta.durationSeconds, tempDir),
-            extractAudioAsWav(sourcePath, tempDir)
-                .then((audioPath) => audioPath
-                ? transcribeAudioWithFallback({ audioPath, durationSeconds: meta.durationSeconds, keys: input.keys })
-                : null)
-                .catch((err) => {
-                console.error("smart decompose audio extract/transcription 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(transcript),
-            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,
-            transcript
-        });
-        // Phase 2 — vision, OCR, and product-placement run concurrently, all now
-        // transcript-aware. OCR and placement failures are non-fatal. The
-        // placement call is DELIBERATELY separate from the caption/scene vision
-        // call so it can never dilute timeline-layer quality — it reuses the same
-        // sparse frames (no extra ffmpeg) plus the transcript from phase 1.
-        const [attempt, ocrFrames, 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 [];
-            }),
-            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();
-        }
-        // Editor harness — technical editing direction. Run AFTER viral DNA is
-        // normalized so the harness can operationalize the exact emotional punch
-        // instead of guessing independently and drifting from the decompose result.
-        const editorHarness = await runEditorHarnessPass({
-            frames,
-            keys: input.keys,
-            durationSeconds: meta.durationSeconds,
-            sceneCuts,
-            userPrompt: input.userPrompt ?? null,
-            transcript,
-            viralDna
-        }).catch((err) => {
-            console.error("smart decompose editor-harness pass failed", err instanceof Error ? err.message : err);
-            return DEFAULT_EDITOR_HARNESS;
-        });
-        // NOTE: the per-scene clip-annotation + content-format pass is deliberately
-        // NOT run here — it is a separate vision call that would risk the ~60s origin
-        // timeout on longer videos. /auto-decompose seeds scene-annotations.json
-        // "pending" and /scene-annotations-poll drives annotateScenesFromSource
-        // against these finalized scenes (persisted in smart-decompose.json).
-        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,
-            editor_harness_format: editorHarness.format,
-            editor_harness_scene_count: editorHarness.scenes.length
-        });
-        return {
-            summary: typeof record.summary === "string" ? record.summary : "",
-            viralDna,
-            placementSurfaces: finalPlacementSurfaces,
-            editorHarness,
-            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));
-    const editorHarnessJson = escapeAttr(JSON.stringify(result.editorHarness ?? DEFAULT_EDITOR_HARNESS));
-    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}" data-editor-harness="${editorHarnessJson}">
-    <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>`;
-}
-export function buildSmartDecomposedData(input) {
-    const { sourceUrl, result } = input;
-    const durationSeconds = Number(result.durationSeconds.toFixed(3));
-    return {
-        summary: result.summary,
-        scenes: result.scenes.map((scene) => ({
-            slug: scene.slug,
-            start: scene.start,
-            duration: scene.duration,
-            label: scene.label,
-            description: scene.description,
-            viral_note: scene.viral_note
-        })),
-        captions: result.captions.map((caption) => ({
-            slug: caption.slug,
-            text: caption.text,
-            start: caption.start,
-            duration: caption.duration,
-            x: caption.x,
-            y: caption.y,
-            width: caption.width,
-            height: caption.height,
-            color: caption.color,
-            background: caption.background,
-            background_style: caption.background_style,
-            font_family: caption.font_family,
-            font_size: caption.font_size,
-            font_weight: caption.font_weight,
-            viral_note: caption.viral_note
-        })),
-        viralDna: result.viralDna,
-        width: result.width,
-        height: result.height,
-        durationSeconds,
-        source_assets: [{
-                type: "video",
-                url: sourceUrl,
-                width: result.width,
-                height: result.height,
-                duration: durationSeconds
-            }]
-    };
-}
-// The public placeholder tile every blank scene starts on — a gray diagonal-
-// striped 720×1280 image with a dashed text box (uploaded once by
-// scripts/upload-scene-placeholder.ts). Hardcoded to the prod bucket URL (a
-// public object that resolves from any stage) so the blank composition renders
-// identically everywhere. Mirrors SCENE_PLACEHOLDER_IMAGE_URL in the SPA editor.
-export const SCENE_PLACEHOLDER_IMAGE_URL = "https://vidfarmprodstack-vidfarmbucket335ee12f-0vsvtd5earqy.s3.us-east-1.amazonaws.com/primitives/placeholders/scene-placeholder.png";
-const BLANK_PROJECT_SCENE_COUNT = 3;
-const BLANK_PROJECT_SCENE_DURATION = 4;
-// The canonical, reusable "new blank project" composition. This is the single
-// composition.html every fresh /editor/original/fork/new opens on, and the base
-// every blank project forks from (POST /api/v1/compositions seeds a new fork by
-// copying this). It mirrors blankProjectSemanticLayers() in the SPA editor: a
-// continuous placeholder image track (3 butt-cut 4s scenes on track 0) plus a
-// "Scene 1/2/3" caption on track 3, giving the user an editable 12s scaffold
-// instead of an empty canvas. Like the other builders it emits clips only — the
-// runtime is injected on serve by rewriteHyperframesDraftCompositionHtml, and z
-// is normalized to track index on the way out.
-export function buildBlankCompositionHtml(compositionId) {
-    const totalDuration = BLANK_PROJECT_SCENE_COUNT * BLANK_PROJECT_SCENE_DURATION;
-    const sceneEls = [];
-    const captionEls = [];
-    for (let index = 0; index < BLANK_PROJECT_SCENE_COUNT; index += 1) {
-        const sceneNumber = index + 1;
-        const start = index * BLANK_PROJECT_SCENE_DURATION;
-        const end = start + BLANK_PROJECT_SCENE_DURATION;
-        // Placeholder image scene — full canvas, track 0. Together the three form
-        // one continuous 12s media track the user replaces with real footage.
-        const imageId = `scene-${sceneNumber}-image`;
-        sceneEls.push(`<img class="clip" id="${imageId}" data-hf-id="${imageId}" data-hf-slug="scene_${sceneNumber}" data-layer-mode="both" data-layer-kind="image" data-viral-note="Placeholder scene backdrop — replace with your own media." data-start="${start}" data-duration="${BLANK_PROJECT_SCENE_DURATION}" data-end="${end}" data-track-index="0" data-label="Scene ${sceneNumber}" src="${escapeAttr(SCENE_PLACEHOLDER_IMAGE_URL)}" alt="" style="position:absolute;left:0%;top:0%;width:100%;height:100%;z-index:0;opacity:1;border-radius:0px;overflow:hidden;object-fit:cover;" />`);
-        // "Scene N" label sitting in the tile's blank text box — white on a solid
-        // black highlight so it reads over both the placeholder and swapped-in media.
-        const caption = {
-            slug: `scene_${sceneNumber}_label`,
-            text: `Scene ${sceneNumber}`,
-            start,
-            duration: BLANK_PROJECT_SCENE_DURATION,
-            x: 13.5,
-            y: 44,
-            width: 73,
-            height: 12,
-            font_size: 34,
-            color: "#ffffff",
-            background: "#000000",
-            background_style: "highlight-solid",
-            font_family: "TikTok Sans",
-            font_weight: 700,
-            viral_note: "Placeholder scene label — edit or delete once you add real media."
-        };
-        const captionId = `scene-${sceneNumber}-caption`;
-        const innerStyle = captionInlineTextStyle(caption);
-        captionEls.push(`<div class="clip" id="${captionId}" data-hf-id="${captionId}" data-hf-slug="${escapeAttr(caption.slug)}" data-layer-mode="publish" data-layer-kind="caption" data-viral-note="${escapeAttr(caption.viral_note ?? "")}" data-start="${start}" data-duration="${BLANK_PROJECT_SCENE_DURATION}" data-end="${end}" data-track-index="3" data-label="${escapeAttr(caption.text)}" 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:${caption.x}%;top:${caption.y}%;width:${caption.width}%;height:${caption.height}%;z-index:3;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}">${escapeHtml(caption.text)}</span></span></div>`);
-    }
-    // data-vf-origin="raw": a brand-new project, so the editor never auto-prompts
-    // the Decompose modal (there is no source video to decompose).
-    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; }
-  </style>
-</head>
-<body>
-  <div data-composition-id="${escapeAttr(compositionId)}" data-vf-origin="raw" data-width="720" data-height="1280" data-duration="${totalDuration}" data-source-title="Untitled project">
-    ${sceneEls.join("\n    ")}
-    ${captionEls.join("\n    ")}
-  </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;
-}
-// Scene transitions: the INCOMING clip carries data-transition and its vf-tr-*
-// animation plays over the clip's first data-transition-duration seconds — the
-// render engine's CSS adapter scrubs that on its own. What the render engine
-// canNOT do is keep the OUTGOING clip on screen beneath it (visibility is
-// derived strictly from data-start/data-duration), so materialize the overlap
-// here: extend the previous same-track butt-cut clip's data-duration by the
-// transition length. The granted extension is recorded in data-transition-hold
-// so the pass is idempotent and self-healing — every run first restores each
-// clip's nominal duration (duration - hold), then re-grants from the current
-// set of [data-transition] clips (so removed/retimed transitions shrink their
-// neighbor back). Stored drafts stay butt-cut; only publish/render output
-// carries the overlap. The preview runtime applies the same window live.
-function materializeTransitionOverlaps(document) {
-    const upsertStyleVar = (el, name, value) => {
-        const styleValue = el.getAttribute("style") || "";
-        const decl = `${name}:${value}`;
-        const pattern = new RegExp(`(^|;)\\s*${name.replace(/[.*+?^${}()|[\]\\-]/g, "\\$&")}\\s*:[^;]*`, "i");
-        const nextStyle = pattern.test(styleValue)
-            ? styleValue.replace(pattern, (_match, lead) => `${lead}${decl}`)
-            : styleValue.length === 0 || styleValue.endsWith(";")
-                ? `${styleValue}${decl}`
-                : `${styleValue};${decl}`;
-        if (nextStyle !== styleValue)
-            el.setAttribute("style", nextStyle);
-    };
-    const clips = [];
-    for (const el of Array.from(document.querySelectorAll("[data-start]"))) {
-        if (el.hasAttribute("data-composition-id"))
-            continue;
-        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)
-            continue;
-        const priorHold = Number.parseFloat(el.getAttribute("data-transition-hold") || "");
-        const hold = Number.isFinite(priorHold) && priorHold > 0 ? Math.min(priorHold, duration) : 0;
-        clips.push({
-            el,
-            track: Number.parseInt(el.getAttribute("data-track-index") || "0", 10) || 0,
-            start,
-            nominal: duration - hold,
-            hold: 0
-        });
-    }
-    if (!clips.length)
-        return;
-    for (const clip of clips) {
-        const transitionEl = clip.el;
-        const tagName = transitionEl.tagName?.toLowerCase?.() ?? "";
-        // Exit transitions: validate/clamp here; the tail-positioning delay var is
-        // re-derived in the final loop below once holds are known (the animation
-        // must end at the clip's rendered end, nominal + hold).
-        const outPreset = transitionEl.getAttribute("data-transition-out");
-        if (outPreset) {
-            if (!TRANSITION_OUT_PRESETS.includes(outPreset) || tagName === "audio") {
-                transitionEl.removeAttribute("data-transition-out");
-                transitionEl.removeAttribute("data-transition-out-duration");
-            }
-            else {
-                const outDuration = Math.min(clampTransitionDuration(transitionEl.getAttribute("data-transition-out-duration")), clip.nominal);
-                const outDurationValue = Number(outDuration.toFixed(3));
-                transitionEl.setAttribute("data-transition-out-duration", String(outDurationValue));
-                upsertStyleVar(transitionEl, "--vf-tr-out-dur", `${outDurationValue}s`);
-            }
-        }
-        const preset = transitionEl.getAttribute("data-transition");
-        if (!preset)
-            continue;
-        if (!TRANSITION_PRESETS.includes(preset)) {
-            // Unknown preset would render as a permanently-paused animation with no
-            // keyframes — harmless — but drop it so agents get clean state back.
-            transitionEl.removeAttribute("data-transition");
-            transitionEl.removeAttribute("data-transition-duration");
-            continue;
-        }
-        if (tagName === "audio") {
-            transitionEl.removeAttribute("data-transition");
-            transitionEl.removeAttribute("data-transition-duration");
-            continue;
-        }
-        // The animation cannot outlast its own clip.
-        const duration = Math.min(clampTransitionDuration(transitionEl.getAttribute("data-transition-duration")), clip.nominal);
-        const durationValue = Number(duration.toFixed(3));
-        transitionEl.setAttribute("data-transition-duration", String(durationValue));
-        // Keep the inline var (which drives animation-duration) in lockstep, same
-        // as the --vf-kb-dur re-derivation above.
-        upsertStyleVar(transitionEl, "--vf-tr-dur", `${durationValue}s`);
-        // Grant the hold to the clip this one cuts away from: same track, nominal
-        // end at (within epsilon of) this clip's start.
-        for (const candidate of clips) {
-            if (candidate === clip || candidate.track !== clip.track)
-                continue;
-            if (Math.abs(candidate.start + candidate.nominal - clip.start) > TRANSITION_ADJACENCY_EPSILON)
-                continue;
-            const candidateTag = candidate.el.tagName?.toLowerCase?.() ?? "";
-            if (candidateTag === "audio")
-                continue;
-            candidate.hold = Math.max(candidate.hold, duration);
-        }
-    }
-    for (const clip of clips) {
-        const nextDuration = Number((clip.nominal + clip.hold).toFixed(3));
-        const currentDuration = Number.parseFloat(clip.el.getAttribute("data-duration") || "");
-        if (currentDuration !== nextDuration) {
-            clip.el.setAttribute("data-duration", String(nextDuration));
-        }
-        if (clip.el.hasAttribute("data-end")) {
-            clip.el.setAttribute("data-end", String(Number((clip.start + nextDuration).toFixed(3))));
-        }
-        if (clip.hold > 0) {
-            clip.el.setAttribute("data-transition-hold", String(Number(clip.hold.toFixed(3))));
-        }
-        else {
-            clip.el.removeAttribute("data-transition-hold");
-        }
-        // Position the exit animation at the clip's rendered tail. Timeline edits
-        // touch data-duration only, so this re-derivation (like --vf-kb-dur) is
-        // what keeps stored delays honest after retimes.
-        if (clip.el.getAttribute("data-transition-out")) {
-            const outDuration = clampTransitionDuration(clip.el.getAttribute("data-transition-out-duration"));
-            upsertStyleVar(clip.el, "--vf-tr-out-delay", `${transitionOutDelaySeconds(nextDuration, outDuration)}s`);
-        }
-    }
-}
-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);
-    }
-    // HyperFrames contract: visible timed elements (div/img) carry class="clip" —
-    // the upstream runtime keeps clip-less timed elements visible for the whole
-    // composition. video/audio deliberately stay bare (framework-managed), so the
-    // class is STRIPPED there (the editor's add-layer paths set it universally).
-    // Only promote layers with a valid timing window: a clip-less element with a
-    // missing/invalid data-duration historically stayed visible full-length, and
-    // promoting it would silently hide it on re-renders of older compositions.
-    for (const el of Array.from(document.querySelectorAll("[data-start]"))) {
-        if (el.hasAttribute("data-composition-id"))
-            continue;
-        const tag = el.tagName.toLowerCase();
-        if (tag === "video" || tag === "audio") {
-            el.classList.remove("clip");
-            if (!el.getAttribute("class"))
-                el.removeAttribute("class");
-            continue;
-        }
-        const start = Number.parseFloat(el.getAttribute("data-start") || "");
-        const clipDuration = Number.parseFloat(el.getAttribute("data-duration") || "");
-        if (!Number.isFinite(start) || start < 0 || !Number.isFinite(clipDuration) || clipDuration <= 0)
-            continue;
-        if (!el.classList.contains("clip")) {
-            el.classList.add("clip");
-        }
-    }
-    // Ken Burns motion must span exactly the clip: timeline edits touch
-    // data-duration only, so re-derive the inline --vf-kb-dur (which drives
-    // animation-duration) from data-duration on every [data-kenburns] layer.
-    // Also make sure the shared keyframes stylesheet travels with compositions
-    // stored before the builder started embedding it.
-    const kenBurnsLayers = Array.from(document.querySelectorAll("[data-kenburns]"));
-    for (const el of kenBurnsLayers) {
-        const duration = Number.parseFloat(el.getAttribute("data-duration") || "");
-        if (!Number.isFinite(duration) || duration <= 0)
-            continue;
-        const styleValue = el.getAttribute("style") || "";
-        const durDecl = `--vf-kb-dur:${Number(duration.toFixed(3))}s`;
-        const nextStyle = /(^|;)\s*--vf-kb-dur\s*:[^;]*/i.test(styleValue)
-            ? styleValue.replace(/(^|;)\s*--vf-kb-dur\s*:[^;]*/i, (_match, lead) => `${lead}${durDecl}`)
-            : styleValue.length === 0 || styleValue.endsWith(";")
-                ? `${styleValue}${durDecl}`
-                : `${styleValue};${durDecl}`;
-        if (nextStyle !== styleValue)
-            el.setAttribute("style", nextStyle);
-    }
-    if (kenBurnsLayers.length > 0 && !html.includes(KEN_BURNS_STYLE_MARKER)) {
-        const styleEl = document.createElement("style");
-        styleEl.textContent = KEN_BURNS_CSS;
-        (document.head ?? document.documentElement)?.appendChild(styleEl);
-    }
-    // Animated captions: word windows are stored relative to the layer start
-    // (inline animation-delay/duration on each [data-cap-word]), so retimes need
-    // no re-derivation — but the shared vf-cap-* keyframes stylesheet must
-    // travel with compositions stored before the builder embedded it, or every
-    // word renders in its resting state.
-    if (document.querySelector("[data-caption-animation]") && !html.includes(CAPTION_STYLE_MARKER)) {
-        const styleEl = document.createElement("style");
-        styleEl.textContent = CAPTION_ANIM_CSS;
-        (document.head ?? document.documentElement)?.appendChild(styleEl);
-    }
-    materializeTransitionOverlaps(document);
-    if (document.querySelector("[data-transition], [data-transition-out]") && !html.includes(TRANSITION_STYLE_MARKER)) {
-        // Compositions stored before V2 carry the V1 block inline: upgrade it in
-        // place (exact string swap) instead of stacking a second stylesheet. If the
-        // legacy block drifted, append after it — later source order wins the
-        // equal-specificity animation-name battle, so V2 still takes effect.
-        let upgradedLegacy = false;
-        if (html.includes("__VF_TRANSITIONS_V1__")) {
-            for (const styleEl of Array.from(document.querySelectorAll("style"))) {
-                const text = styleEl.textContent || "";
-                if (!text.includes("__VF_TRANSITIONS_V1__"))
-                    continue;
-                styleEl.textContent = text.includes(LEGACY_TRANSITION_CSS_V1)
-                    ? text.split(LEGACY_TRANSITION_CSS_V1).join(TRANSITION_CSS)
-                    : `${text}\n${TRANSITION_CSS}`;
-                upgradedLegacy = true;
-            }
-        }
-        if (!upgradedLegacy) {
-            const styleEl = document.createElement("style");
-            styleEl.textContent = TRANSITION_CSS;
-            (document.head ?? document.documentElement)?.appendChild(styleEl);
-        }
-    }
-    // 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}`;
-}
-/**
- * Reconstruct a Step Functions execution ARN from the render state machine ARN
- * plus a deterministic execution name, so a re-invoked job runner can poll the
- * SAME render without persisting the ARN handed back at dispatch time.
- *   arn:...:stateMachine:NAME  ->  arn:...:execution:NAME:EXEC_NAME
- */
-function executionArnFromName(stateMachineArn, executionName) {
-    const marker = ":stateMachine:";
-    const idx = stateMachineArn.indexOf(marker);
-    if (idx === -1) {
-        throw new Error(`Unexpected HyperFrames render state machine ARN: ${stateMachineArn}`);
-    }
-    const prefix = stateMachineArn.slice(0, idx);
-    const machineName = stateMachineArn.slice(idx + marker.length);
-    return `${prefix}:execution:${machineName}:${executionName}`;
-}
-/**
- * DescribeExecution for a render execution. Returns the Step Functions status,
- * or `null` when the execution does not exist yet (never dispatched) — the
- * signal renderStep() uses to decide between dispatch and resume.
- */
-async function describeRenderExecutionStatus(executionArn, region) {
-    const client = new SFNClient({ region });
-    try {
-        const response = await client.send(new DescribeExecutionCommand({ executionArn }));
-        return response.status ?? "RUNNING";
-    }
-    catch (error) {
-        if (error instanceof ExecutionDoesNotExist) {
-            return null;
-        }
-        const name = error instanceof Error ? error.name : "";
-        if (name === "ExecutionDoesNotExist") {
-            return null;
-        }
-        throw error;
-    }
-}
-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, "vidfarm-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 || rootTagAttribute(html, "data-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}`;
-    });
-}
-// Reads an attribute from the SAME opening tag that carries
-// data-composition-id (the composition root). htmlAttribute matches the first
-// occurrence anywhere in the document, which nested sub-compositions or
-// embedded snippets could hijack — fps must come from the root only.
-function rootTagAttribute(html, name) {
-    const rootTag = html.match(/<[a-zA-Z][^>]*\bdata-composition-id\s*=[^>]*>/);
-    if (!rootTag) {
-        return "";
-    }
-    const value = rootTag[0].match(new RegExp(`\\b${name}\\s*=\\s*["']([^"']*)["']`, "i"));
-    return value ? value[1] : "";
-}
-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