@mevdragon/vidfarm-devcli 0.2.12 → 0.2.13

package/dist/src/services/hyperframes.js

@@ -0,0 +1,1014 @@
+import { spawn } from "node:child_process";
+import { randomUUID } from "node:crypto";
+import { createWriteStream } from "node:fs";
+import { cp, mkdir, mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { pipeline } from "node:stream/promises";
+import { CloudFormationClient, DescribeStacksCommand } from "@aws-sdk/client-cloudformation";
+import { GetObjectCommand, S3Client } from "@aws-sdk/client-s3";
+import { getSignedUrl } from "@aws-sdk/s3-request-presigner";
+import ffmpegStatic from "ffmpeg-static";
+import ffprobeStatic from "ffprobe-static";
+import { parseHTML } from "linkedom";
+import { config } from "../config.js";
+import { buildHyperframeCompositionHtml } from "../hyperframes/composition.js";
+let stackCache = null;
+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.");
+        }
+        const metadata = extractCompositionMetadata(compositionHtml, input);
+        const stack = await resolveHyperframesStack();
+        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 { renderToLambda, getRenderProgress } = await import("@hyperframes/aws-lambda/sdk");
+        const handle = await renderToLambda({
+            projectDir,
+            bucketName: stack.bucketName,
+            stateMachineArn: stack.stateMachineArn,
+            region: stack.region,
+            executionName: renderId,
+            outputKey,
+            config: {
+                fps: normalizeRenderFps(metadata.fps),
+                width: metadata.width,
+                height: metadata.height,
+                format: input.format || "mp4",
+                codec: "h264",
+                quality: "standard",
+                chunkSize: input.chunkSize ?? 240,
+                maxParallelChunks: input.maxParallelChunks ?? 8,
+                runtimeCap: "lambda"
+            }
+        });
+        if (input.wait === false) {
+            return {
+                ...handle,
+                outputUrl: null,
+                outputS3Uri: handle.outputS3Uri,
+                endedAt: null,
+                metadata: {
+                    mode: "hyperframes_lambda",
+                    status: "RUNNING",
+                    stack,
+                    composition: metadata
+                }
+            };
+        }
+        const startedAtMs = Date.now();
+        const timeoutMs = input.timeoutMs ?? 12 * 60 * 1000;
+        const pollIntervalMs = input.pollIntervalMs ?? 5000;
+        for (;;) {
+            const progress = await getRenderProgress({
+                executionArn: handle.executionArn,
+                region: stack.region,
+                defaultMemorySizeMb: stack.lambdaMemoryMb
+            });
+            if (progress.status === "SUCCEEDED") {
+                const outputS3Uri = progress.outputFile?.s3Uri || handle.outputS3Uri;
+                return {
+                    ...handle,
+                    outputS3Uri,
+                    outputUrl: await signedS3Url(outputS3Uri, stack.region),
+                    endedAt: progress.endedAt,
+                    metadata: {
+                        mode: "hyperframes_lambda",
+                        status: progress.status,
+                        stack,
+                        composition: metadata,
+                        progress,
+                        costs: progress.costs,
+                        estimatedCostUsd: progress.costs.accruedSoFarUsd,
+                        chargeUsd: roundUsd(progress.costs.accruedSoFarUsd * 1.2),
+                        costDisplay: progress.costs.displayCost,
+                        lambdasInvoked: progress.lambdasInvoked,
+                        framesRendered: progress.framesRendered,
+                        totalFrames: progress.totalFrames
+                    }
+                };
+            }
+            if (progress.fatalErrorEncountered || ["FAILED", "TIMED_OUT", "ABORTED"].includes(progress.status)) {
+                throw new Error(`HyperFrames render ${handle.renderId} failed: ${JSON.stringify(progress.errors)}`);
+            }
+            if (Date.now() - startedAtMs > timeoutMs) {
+                throw new Error(`Timed out waiting for HyperFrames render ${handle.renderId}.`);
+            }
+            await new Promise((resolve) => setTimeout(resolve, pollIntervalMs));
+        }
+    }
+    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;
+function runBinary(bin, args) {
+    return new Promise((resolve, reject) => {
+        const proc = spawn(bin, args, { stdio: ["ignore", "pipe", "pipe"] });
+        let stdout = "";
+        let stderr = "";
+        proc.stdout.on("data", (chunk) => { stdout += chunk.toString(); });
+        proc.stderr.on("data", (chunk) => { stderr += chunk.toString(); });
+        proc.on("error", reject);
+        proc.on("close", (code) => {
+            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)
+    };
+}
+async function sampleFramesAsBase64(videoPath, durationSeconds, tempDir) {
+    const timestamps = [
+        Math.max(0.1, durationSeconds * 0.05),
+        durationSeconds * 0.2,
+        durationSeconds * 0.35,
+        durationSeconds * 0.5,
+        durationSeconds * 0.65,
+        durationSeconds * 0.8,
+        Math.max(0.1, durationSeconds * 0.95)
+    ]
+        .filter((value, index, list) => Number.isFinite(value) && value >= 0 && list.indexOf(value) === index)
+        .slice(0, 6);
+    const results = [];
+    for (const [index, timestamp] of timestamps.entries()) {
+        const framePath = path.join(tempDir, `frame-${index}.jpg`);
+        await runBinary(ffmpegBin, [
+            "-y",
+            "-ss", String(timestamp),
+            "-i", videoPath,
+            "-frames:v", "1",
+            "-vf", "scale=576:-1",
+            framePath
+        ]);
+        const data = (await readFile(framePath)).toString("base64");
+        results.push({ timestamp, data });
+    }
+    return results;
+}
+function buildSmartDecomposePrompt(input) {
+    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`
+        : "";
+    return `You are decomposing a short-form vertical video (TikTok/Reel) into editable HyperFrames timeline layers.
+${userGuidance}
+Video metadata:
+- duration: ${input.durationSeconds.toFixed(3)} seconds
+- dimensions: ${input.width} x ${input.height} (9:16 vertical, canvas is 100% x 100%)
+
+Return strictly valid JSON matching this schema:
+{
+  "summary": string,
+  "viral_dna": {
+    "hook": string,
+    "retention": string,
+    "payoff": string,
+    "preserve": [string, ...],
+    "avoid": [string, ...],
+    "promotions": [string, ...]
+  },
+  "scenes": [{
+    "slug": string,
+    "start": number,
+    "duration": number,
+    "label": 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:
+- "hook": the 1-sentence tactic used in the first 1-2 seconds to stop the scroll (e.g., "Pinned comment screenshot dares the viewer to keep watching").
+- "retention": how the middle of the video keeps attention (visual cuts, pattern loops, escalating stakes).
+- "payoff": what the viewer earns at the end (reveal, punchline, transformation).
+- "preserve": 3-5 concrete elements a remixer MUST keep to preserve the format (e.g., "Pinned comment stays on-screen the whole video", "Wedding dance payoff shot").
+- "avoid": 3-5 things that would break the format if changed (e.g., "Do not remove the on-screen text overlay", "Do not slow the cuts below 1.5s").
+- "promotions": 3-5 categories of product / service / offer this exact format could be reused to promote, WITHOUT changing the beat structure or hook mechanic. Each item is a concrete pitchable use-case, not a genre. Examples: "SaaS free-trial signup (before/after workflow)", "Fitness challenge (7-day transformation)", "Local restaurant grand-opening (line-out-the-door proof)", "Ebook / course launch (result-first payoff)", "Real-estate open-house (walk-through reveal)". Anchor each promotion to the same viral tactic captured in "hook" — do not invent unrelated verticals.
+- 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)}.
+
+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:
+- Extract EVERY visible on-screen text overlay as its own caption. Preserve exact spelling/casing/line breaks (use \\n for line breaks).
+- If no visible text, return "captions": []. NEVER invent text.
+
+FONT_FAMILY (choose ONE, match visual appearance):
+- "TikTok Sans" — clean sans-serif (DEFAULT if unsure). Rounded, modern.
+- "Montserrat" — geometric bold sans. Common on IG/TikTok bold captions.
+- "Source Code Pro" — monospaced. For code/terminal aesthetic.
+- "Yesteryear" — cursive script. For quotes / romantic vibes.
+- "Georgia" — serif. For editorial / news look.
+- "Abel" — condensed sans. Newsletter/headline vibe.
+- Return exactly one of the above six strings. If unsure, return "TikTok Sans".
+
+FONT_WEIGHT (integer):
+- 400 for normal weight
+- 600 for semibold (typical TikTok caption look)
+- 700 for bold (heavy captions)
+- 800 or 900 for ultra-black display text
+
+FONT_SIZE — return TWO numbers, both required. The renderer uses font_size_percent to survive canvas resizes.
+- "font_size_percent" (float 1.0–15.0): the caption glyph height as a percent of canvas height (${input.height || 1280}px). This is the SOURCE OF TRUTH. Measure a single-line uppercase-height letter (like an "M" or "H") in the actual frame and divide by canvas height, times 100.
+  - Tiny UI / hashtag row: 1.2–2.0
+  - Standard TikTok caption (dialog line): 2.0–3.2
+  - Standard hook caption (readable but not screaming): 3.2–5.0
+  - Bold hook overlay filling a wide band: 5.0–8.0
+  - Giant kinetic display / meme text: 8.0–12.0
+- "font_size" (integer pixels): compute as round(font_size_percent / 100 * ${input.height || 1280}). Include it for redundancy.
+- Do NOT default to 24. Measure the actual on-screen glyph height. When unsure between two ranges, pick the one closest to what you actually measure — do not over-inflate.
+- Give the SAME caption the SAME font_size — do not vary between instances.
+
+COLOR (hex "#rrggbb"):
+- Pure white: "#ffffff" (most common TikTok captions)
+- Pure black: "#000000"
+- Bright yellow (highlight text): "#ffe600"
+- Match the actual on-screen color as closely as you can. Never return names like "white"; always hex.
+
+BACKGROUND_STYLE (choose ONE):
+- "plain" — no visible pill/outline. Just letters over the video. (Most common.)
+- "outline" — thin dark outline around each glyph (for legibility over busy video).
+- "highlight-solid" — a solid colored pill / block behind the text (typical TikTok white-on-black caption card).
+- "highlight-translucent" — semi-transparent pill.
+- BACKGROUND ("#rrggbb") is the pill / outline color. For "plain" this is unused but still return a valid hex like "#000000".
+
+POSITION (percent 0-100, floats OK):
+- x, y = top-left corner of the caption's bounding box relative to the canvas.
+- width, height = its bounding box size.
+- TikTok baked captions are usually centered horizontally: x ≈ 5-10, width ≈ 80-90.
+- Vertical placement: hook captions near top (y ≈ 8-18); dialog/subtitle mid-lower (y ≈ 60-72); brand tag / cta bottom (y ≈ 80-88).
+- Height should roughly match font_size and line count.
+
+TIMING RULES:
+- start, duration are seconds (floats). start >= 0. start + duration <= ${input.durationSeconds.toFixed(3)}.
+
+OUTPUT: pure JSON, no prose, no markdown fences.`;
+}
+const ALLOWED_FONTS = [
+    "TikTok Sans", "Montserrat", "Source Code Pro", "Yesteryear", "Georgia", "Abel"
+];
+const ALLOWED_BG_STYLES = [
+    "plain", "outline", "highlight-solid", "highlight-translucent"
+];
+function normalizeFontFamily(value) {
+    if (typeof value !== "string")
+        return "TikTok Sans";
+    const trimmed = value.trim();
+    const match = ALLOWED_FONTS.find((font) => font.toLowerCase() === trimmed.toLowerCase());
+    return match ?? "TikTok Sans";
+}
+function normalizeHexColor(value, fallback) {
+    if (typeof value !== "string")
+        return fallback;
+    const trimmed = value.trim();
+    if (/^#[0-9a-fA-F]{6}$/.test(trimmed))
+        return trimmed.toLowerCase();
+    if (/^#[0-9a-fA-F]{3}$/.test(trimmed)) {
+        const [, r, g, b] = /^#([0-9a-fA-F])([0-9a-fA-F])([0-9a-fA-F])$/.exec(trimmed) ?? [];
+        return `#${r}${r}${g}${g}${b}${b}`.toLowerCase();
+    }
+    return fallback;
+}
+function normalizeBackgroundStyle(value) {
+    if (typeof value !== "string")
+        return "plain";
+    const lowered = value.trim().toLowerCase();
+    const match = ALLOWED_BG_STYLES.find((style) => style === lowered);
+    return match ?? "plain";
+}
+// Convert a #rrggbb hex to an rgba(...) string with the given alpha. Falls back
+// to a solid dark backing if the hex is malformed so the caption still stays
+// legible.
+function hexToRgba(hex, alpha) {
+    const match = /^#([0-9a-f]{6})$/i.exec(String(hex ?? "").trim());
+    if (!match)
+        return `rgba(0,0,0,${alpha})`;
+    const value = match[1];
+    const r = parseInt(value.slice(0, 2), 16);
+    const g = parseInt(value.slice(2, 4), 16);
+    const b = parseInt(value.slice(4, 6), 16);
+    return `rgba(${r},${g},${b},${alpha})`;
+}
+// Builds the inline-span CSS for a caption based on its background_style so
+// captions actually render with the visual treatment the vision LLM extracted
+// ("outline" gets a real text stroke; "highlight-*" gets a colored pill).
+// Without this the span just had `color:#fff` and everything looked washed
+// out over the video.
+function captionInlineTextStyle(caption) {
+    const parts = [`color:${caption.color}`];
+    const strokeColor = caption.background && /^#[0-9a-f]{6}$/i.test(caption.background)
+        ? caption.background
+        : "#000000";
+    // Outline width scales with font size so small captions still get a
+    // visible edge. Clamp so it never disappears (1px) and never eats the
+    // glyph interior (5px).
+    const strokePx = Math.max(1, Math.min(5, Math.round(caption.font_size * 0.06)));
+    switch (caption.background_style) {
+        case "outline":
+            parts.push(`-webkit-text-stroke:${strokePx}px ${strokeColor}`, `paint-order:stroke fill`, 
+            // text-shadow fallback for renderers that ignore paint-order.
+            `text-shadow:0 0 ${strokePx}px ${strokeColor}, ${strokePx}px ${strokePx}px 0 ${strokeColor}, -${strokePx}px ${strokePx}px 0 ${strokeColor}, ${strokePx}px -${strokePx}px 0 ${strokeColor}, -${strokePx}px -${strokePx}px 0 ${strokeColor}`);
+            break;
+        case "highlight-solid":
+            parts.push(`background:${strokeColor}`, `padding:0.18em 0.5em`, `border-radius:0.35em`, `box-decoration-break:clone`, `-webkit-box-decoration-break:clone`);
+            break;
+        case "highlight-translucent":
+            parts.push(`background:${hexToRgba(strokeColor, 0.55)}`, `padding:0.18em 0.5em`, `border-radius:0.35em`, `box-decoration-break:clone`, `-webkit-box-decoration-break:clone`);
+            break;
+        case "plain":
+        default:
+            // Even "plain" captions need SOME shadow over busy TikTok footage or
+            // white-on-white becomes invisible. Use a subtle drop shadow that
+            // doesn't read as an intentional outline.
+            parts.push(`text-shadow:0 1px 2px rgba(0,0,0,0.55), 0 0 3px rgba(0,0,0,0.35)`);
+            break;
+    }
+    return parts.join(";");
+}
+function normalizeFontWeight(value) {
+    const parsed = Number(value);
+    if (!Number.isFinite(parsed))
+        return 600;
+    const clamped = Math.max(100, Math.min(900, Math.round(parsed / 100) * 100));
+    return clamped;
+}
+function normalizeFontSize(value, canvasHeight) {
+    const parsed = Number(value);
+    const heightRef = canvasHeight > 0 ? canvasHeight : 1280;
+    if (!Number.isFinite(parsed) || parsed <= 0)
+        return Math.round(heightRef * 0.028);
+    return Math.max(10, Math.min(160, Math.round(parsed)));
+}
+function resolveFontSize(input) {
+    const heightRef = input.canvasHeight > 0 ? input.canvasHeight : 1280;
+    const percent = Number(input.fontSizePercent);
+    if (Number.isFinite(percent) && percent > 0) {
+        const clampedPct = Math.max(0.8, Math.min(15, percent));
+        return Math.max(10, Math.min(160, Math.round((clampedPct / 100) * heightRef)));
+    }
+    return normalizeFontSize(input.fontSize, input.canvasHeight);
+}
+const DEFAULT_VIRAL_DNA = {
+    hook: "", retention: "", payoff: "", preserve: [], avoid: [], promotions: []
+};
+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 {
+        hook: asString(record.hook),
+        retention: asString(record.retention),
+        payoff: asString(record.payoff),
+        preserve: asStringArray(record.preserve),
+        avoid: asStringArray(record.avoid),
+        promotions: asStringArray(record.promotions)
+    };
+}
+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
+            }
+        })
+    });
+    const raw = await response.text();
+    if (!response.ok) {
+        let message = raw;
+        try {
+            message = JSON.parse(raw).error?.message ?? raw;
+        }
+        catch { }
+        throw new Error(`Gemini responded ${response.status}: ${message}`);
+    }
+    const parsed = JSON.parse(raw);
+    const text = parsed.candidates?.[0]?.content?.parts?.map((p) => p.text ?? "").join("") ?? "";
+    return extractJson(text);
+}
+async function callOpenAIVision(input) {
+    const content = [{ type: "text", text: input.prompt }];
+    for (const frame of input.frames) {
+        content.push({ type: "text", text: `Frame captured at ${frame.timestamp.toFixed(2)}s` });
+        content.push({
+            type: "image_url",
+            image_url: { url: `data:image/jpeg;base64,${frame.data}` }
+        });
+    }
+    const response = await fetch(input.endpoint ?? "https://api.openai.com/v1/chat/completions", {
+        method: "POST",
+        headers: {
+            "content-type": "application/json",
+            "authorization": `Bearer ${input.apiKey}`,
+            ...(input.extraHeaders ?? {})
+        },
+        body: JSON.stringify({
+            model: input.model,
+            temperature: 0.15,
+            response_format: { type: "json_object" },
+            messages: [{ role: "user", content }]
+        })
+    });
+    const raw = await response.text();
+    if (!response.ok) {
+        let message = raw;
+        try {
+            message = JSON.parse(raw).error?.message ?? raw;
+        }
+        catch { }
+        throw new Error(`${input.endpoint?.includes("openrouter") ? "OpenRouter" : "OpenAI"} responded ${response.status}: ${message}`);
+    }
+    const parsed = JSON.parse(raw);
+    const text = parsed.choices?.[0]?.message?.content ?? "";
+    return extractJson(text);
+}
+async function callVisionWithFallback(input) {
+    const attempts = [];
+    if (input.keys.gemini) {
+        const model = process.env.GEMINI_MODEL ?? "gemini-3.5-flash";
+        attempts.push({
+            provider: "gemini",
+            model,
+            run: () => callGeminiVision({ apiKey: input.keys.gemini, model, prompt: input.prompt, frames: input.frames })
+        });
+    }
+    if (input.keys.openai) {
+        const model = process.env.OPENAI_VISION_MODEL ?? "gpt-5.5-2026-04-23";
+        attempts.push({
+            provider: "openai",
+            model,
+            run: () => callOpenAIVision({ apiKey: input.keys.openai, model, prompt: input.prompt, frames: input.frames })
+        });
+    }
+    if (input.keys.openrouter) {
+        const model = process.env.OPENROUTER_VISION_MODEL ?? "google/gemini-3.5-flash";
+        attempts.push({
+            provider: "openrouter",
+            model,
+            run: () => callOpenAIVision({
+                apiKey: input.keys.openrouter,
+                model,
+                prompt: input.prompt,
+                frames: input.frames,
+                endpoint: "https://openrouter.ai/api/v1/chat/completions",
+                extraHeaders: {
+                    "HTTP-Referer": "https://staging.vidfarm.cc",
+                    "X-Title": "Vidfarm smart decompose"
+                }
+            })
+        });
+    }
+    if (attempts.length === 0) {
+        throw new Error("No vision provider key available (GEMINI_API_KEY, OPENAI_API_KEY, or OPENROUTER_API_KEY).");
+    }
+    const errors = [];
+    for (const attempt of attempts) {
+        try {
+            const result = await attempt.run();
+            return { result, provider: attempt.provider, model: attempt.model };
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            errors.push(`${attempt.provider}(${attempt.model}): ${message}`);
+            console.error(`smart decompose ${attempt.provider} failed`, message);
+        }
+    }
+    throw new Error(`All vision providers failed. ${errors.join(" | ")}`);
+}
+export async function smartDecomposeVideo(input) {
+    const tempDir = await mkdtemp(path.join(os.tmpdir(), "vidfarm-smart-decompose-"));
+    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");
+        }
+        const frames = await sampleFramesAsBase64(sourcePath, meta.durationSeconds, tempDir);
+        const prompt = buildSmartDecomposePrompt({
+            durationSeconds: meta.durationSeconds,
+            width: meta.width,
+            height: meta.height,
+            userPrompt: input.userPrompt ?? null
+        });
+        const attempt = await callVisionWithFallback({
+            prompt,
+            frames,
+            keys: input.keys
+        });
+        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}`,
+                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);
+        return {
+            summary: typeof record.summary === "string" ? record.summary : "",
+            viralDna: normalizeViralDna(record.viral_dna),
+            durationSeconds: meta.durationSeconds,
+            width: meta.width,
+            height: meta.height,
+            scenes,
+            captions,
+            provider: attempt.provider,
+            model: attempt.model
+        };
+    }
+    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", viral_note: "" }];
+    // Assign each caption to the lowest track index (starting at 2 — track 0
+    // is video, track 1 is audio) where it doesn't temporally overlap any
+    // caption already on that track. Enforces the "no two clips on the same
+    // track can overlap in time" rule. Multiple stacked labels (like a
+    // staircase of "single/talking/dating/marriage/have kids" all shown for
+    // the full duration) end up on tracks 2,3,4,5,6 respectively.
+    const CAPTION_TRACK_START = 2;
+    const captionTrackClipRanges = [];
+    const assignCaptionTrackIndex = (start, end) => {
+        for (let i = 0; i < captionTrackClipRanges.length; i += 1) {
+            if (!captionTrackClipRanges[i].some((r) => start < r.end && r.start < end)) {
+                captionTrackClipRanges[i].push({ start, end });
+                return CAPTION_TRACK_START + i;
+            }
+        }
+        captionTrackClipRanges.push([{ start, end }]);
+        return CAPTION_TRACK_START + captionTrackClipRanges.length - 1;
+    };
+    const sceneEls = scenes.map((scene, index) => {
+        const start = Math.max(0, Math.min(totalDuration - 0.1, Number(scene.start.toFixed(3))));
+        const duration = Math.max(0.1, Number(scene.duration.toFixed(3)));
+        const end = Math.min(totalDuration, start + duration);
+        const id = shortElementId();
+        const sceneSlug = scene.slug || `scene_${index + 1}`;
+        return `<div class="clip" id="${id}" data-hf-id="${id}" data-hf-slug="${escapeAttr(sceneSlug)}" data-layer-mode="both" data-layer-kind="video" data-viral-note="${escapeAttr(scene.viral_note ?? "")}" data-start="${start}" data-duration="${Number(duration.toFixed(3))}" data-end="${Number(end.toFixed(3))}" data-track-index="0" data-label="${escapeAttr(scene.label)}" data-media-start="${start}" data-playback-start="${start}" data-vf-timeline-proxy="video" data-src="${escapeAttr(sourceUrl)}" style="position:absolute;left:0%;top:0%;width:1%;height:1%;z-index:0;display:none;pointer-events:none;"></div>`;
+    }).join("\n    ");
+    // Sort captions by start time so the track-assignment greedy fills lower
+    // tracks first with earlier captions.
+    const sortedCaptions = [...result.captions].sort((a, b) => (a.start - b.start) || (a.duration - b.duration));
+    const captionEls = sortedCaptions.map((caption, index) => {
+        const start = Math.max(0, Math.min(totalDuration - 0.1, Number(caption.start.toFixed(3))));
+        const duration = Math.max(0.1, Math.min(totalDuration - start, Number(caption.duration.toFixed(3))));
+        const end = start + duration;
+        const trackIndex = assignCaptionTrackIndex(start, end);
+        const id = shortElementId();
+        const captionSlug = caption.slug || `caption_${index + 1}`;
+        const clampedX = clampPercent(caption.x, 0, 95);
+        const clampedY = clampPercent(caption.y, 0, 95);
+        const clampedW = clampPercent(caption.width, 5, 100 - clampedX);
+        const clampedH = clampPercent(caption.height, 3, 100 - clampedY);
+        const escapedText = escapeHtml(caption.text);
+        const innerStyle = captionInlineTextStyle(caption);
+        return `<div class="clip" id="${id}" data-hf-id="${id}" data-hf-slug="${escapeAttr(captionSlug)}" data-layer-mode="publish" data-layer-kind="caption" data-viral-note="${escapeAttr(caption.viral_note ?? "")}" data-start="${start}" data-duration="${Number(duration.toFixed(3))}" data-end="${Number(end.toFixed(3))}" data-track-index="${trackIndex}" data-label="${escapeAttr(caption.text.slice(0, 40))}" data-text-background-style="${caption.background_style}" data-text-background-color="${escapeAttr(caption.background)}" data-font-family="${escapeAttr(caption.font_family)}" style="position:absolute;left:${clampedX}%;top:${clampedY}%;width:${clampedW}%;height:${clampedH}%;z-index:${trackIndex};display:flex;align-items:center;justify-content:center;padding:3px;box-sizing:border-box;text-align:center;color:${caption.color};background:transparent;font-family:'${caption.font_family}', 'TikTok Sans', sans-serif;font-weight:${caption.font_weight};font-size:${caption.font_size}px;line-height:1.2;overflow:visible;"><span data-vf-text-lines="true"><span data-vf-text-inline="true" style="${innerStyle}">${escapedText}</span></span></div>`;
+    }).join("\n    ");
+    const audioId = shortElementId();
+    const audioEl = `<audio class="clip" id="${audioId}" data-hf-id="${audioId}" data-hf-slug="source_audio" data-layer-mode="both" data-layer-kind="audio" data-viral-note="Original TikTok audio track." data-start="0" data-duration="${totalDuration}" data-end="${totalDuration}" data-track-index="1" data-label="Original audio" data-media-start="0" data-playback-start="0" data-timeline-role="music" data-volume="1" src="${escapeAttr(sourceUrl)}" preload="metadata"></audio>`;
+    const viralDnaJson = escapeAttr(JSON.stringify(result.viralDna ?? DEFAULT_VIRAL_DNA));
+    return `<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+  <style>
+    @import url("https://fonts.googleapis.com/css2?family=Abel&family=Montserrat:wght@600;700&family=Source+Code+Pro:wght@700&family=TikTok+Sans:wght@400;600;700;800;900&family=Yesteryear&display=swap");
+    html, body { width:100%; height:100%; margin:0; overflow:hidden; background:#050604; }
+    [data-composition-id] { position:relative; width:100vw; height:100vh; overflow:hidden; background:#050604; }
+    audio { display:none; }
+  </style>
+</head>
+<body>
+  <div data-composition-id="${escapeAttr(compositionId)}" data-source-video="${escapeAttr(sourceUrl)}" data-width="${result.width || 720}" data-height="${result.height || 1280}" data-duration="${totalDuration}" data-source-title="${escapeAttr(title)}" data-viral-dna="${viralDnaJson}">
+    <video data-vf-playback-source="true" src="${escapeAttr(sourceUrl)}" muted playsinline preload="auto" style="position:absolute;left:0%;top:0%;width:100%;height:100%;z-index:0;object-fit:cover;background:#050604"></video>
+    ${sceneEls}
+    ${audioEl}
+    ${captionEls}
+  </div>
+</body>
+</html>`;
+}
+function normalizeSlug(value) {
+    return String(value ?? "")
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "_")
+        .replace(/^_+|_+$/g, "")
+        .slice(0, 64);
+}
+function dedupeSlug(base, used) {
+    const seed = base || "element";
+    if (!used.has(seed)) {
+        used.add(seed);
+        return seed;
+    }
+    for (let index = 2; index < 999; index += 1) {
+        const candidate = `${seed}_${index}`;
+        if (!used.has(candidate)) {
+            used.add(candidate);
+            return candidate;
+        }
+    }
+    const fallback = `${seed}_${Date.now().toString(36)}`;
+    used.add(fallback);
+    return fallback;
+}
+function escapeAttr(value) {
+    return String(value ?? "").replace(/&/g, "&amp;").replace(/"/g, "&quot;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+}
+function escapeHtml(value) {
+    return String(value ?? "").replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+}
+function clampPercent(value, min, max) {
+    if (!Number.isFinite(value))
+        return min;
+    return Math.max(min, Math.min(max, value));
+}
+export function stampCompositionIdentity(html, input) {
+    if (!input.forkId)
+        return html;
+    const composed = `${input.forkId}_v${input.version}`;
+    const { document } = parseHTML(html);
+    const root = document.querySelector("[data-composition-id]");
+    if (!root)
+        return html;
+    root.setAttribute("data-composition-id", composed);
+    root.setAttribute("data-fork-id", input.forkId);
+    root.setAttribute("data-fork-version", String(input.version));
+    return `<!doctype html>\n${document.documentElement.outerHTML}`;
+}
+export function normalizePublishHtml(html) {
+    const { document } = parseHTML(html);
+    for (const backingVideo of Array.from(document.querySelectorAll("[data-vf-playback-source]"))) {
+        backingVideo.remove();
+    }
+    for (const proxy of Array.from(document.querySelectorAll('[data-vf-timeline-proxy="video"]'))) {
+        const video = document.createElement("video");
+        const source = proxy.getAttribute("data-src") || proxy.getAttribute("src") || "";
+        for (const attr of Array.from(proxy.attributes)) {
+            if (attr.name === "data-vf-timeline-proxy" || attr.name === "data-src")
+                continue;
+            video.setAttribute(attr.name, attr.value);
+        }
+        video.setAttribute("src", source);
+        video.setAttribute("muted", "");
+        video.setAttribute("playsinline", "");
+        video.setAttribute("preload", "auto");
+        const trackIndex = Number.parseInt(proxy.getAttribute("data-track-index") ?? "0", 10) || 0;
+        video.setAttribute("style", [
+            "position:absolute",
+            "left:0%",
+            "top:0%",
+            "width:100%",
+            "height:100%",
+            `z-index:${trackIndex}`,
+            "object-fit:cover",
+            "background:#050604"
+        ].join(";"));
+        proxy.replaceWith(video);
+    }
+    // Enforce z-index = data-track-index for every timed layer so visual stacking
+    // strictly follows the timeline layer index. No arbitrary inline z-index survives.
+    for (const el of Array.from(document.querySelectorAll("[data-track-index]"))) {
+        const trackAttr = el.getAttribute("data-track-index");
+        if (!trackAttr)
+            continue;
+        const trackIndex = Number.parseInt(trackAttr, 10);
+        if (!Number.isFinite(trackIndex))
+            continue;
+        const html = el;
+        if (typeof html.style === "undefined")
+            continue;
+        html.style.zIndex = String(trackIndex);
+    }
+    // Editor sessions occasionally leave inline style attributes with double
+    // quotes inside CSS values (font-family: "TikTok Sans"). When serialized into
+    // an HTML attribute, those quotes become &quot; entities. The render lambda
+    // resolves font-family with a regex over raw HTML and misreads &quot; as a
+    // literal font name, exploding with FontFetchError. Normalize to single
+    // quotes so serialization stays entity-free.
+    for (const el of Array.from(document.querySelectorAll("[style]"))) {
+        const styleValue = el.getAttribute("style");
+        if (!styleValue || styleValue.indexOf('"') === -1)
+            continue;
+        el.setAttribute("style", styleValue.replace(/"/g, "'"));
+    }
+    return `<!doctype html>\n${document.documentElement.outerHTML}`;
+}
+async function resolveHyperframesStack() {
+    const region = config.HYPERFRAMES_RENDER_REGION || config.AWS_REGION || "us-east-1";
+    const lambdaMemoryMb = positiveInteger(config.HYPERFRAMES_RENDER_MEMORY_MB, 3072);
+    const envStack = {
+        stackName: config.HYPERFRAMES_LAMBDA_STACK_NAME || "hyperframes-vidfarm-prod",
+        bucketName: config.HYPERFRAMES_RENDER_BUCKET_NAME || config.HYPERFRAMES_LAMBDA_BUCKET_NAME || "",
+        stateMachineArn: config.HYPERFRAMES_RENDER_STATE_MACHINE_ARN || config.HYPERFRAMES_STATE_MACHINE_ARN || "",
+        region,
+        lambdaMemoryMb
+    };
+    if (envStack.bucketName && envStack.stateMachineArn) {
+        return envStack;
+    }
+    if (stackCache && stackCache.expiresAt > Date.now()) {
+        return stackCache.value;
+    }
+    const stackName = envStack.stackName;
+    const cloudFormation = new CloudFormationClient({ region });
+    const result = await cloudFormation.send(new DescribeStacksCommand({ StackName: stackName }));
+    const stack = result.Stacks?.[0];
+    if (!stack) {
+        throw new Error(`HyperFrames Lambda stack not found: ${stackName}`);
+    }
+    const outputs = stack.Outputs || [];
+    const value = {
+        stackName,
+        bucketName: stackOutput(outputs, "RenderBucketName"),
+        stateMachineArn: stackOutput(outputs, "RenderStateMachineArn"),
+        functionArn: stackOutput(outputs, "RenderFunctionArn"),
+        region: stackOutput(outputs, "RenderRegion") || region,
+        lambdaMemoryMb: positiveInteger(stackOutput(outputs, "RenderMemoryMb"), lambdaMemoryMb)
+    };
+    if (!value.bucketName || !value.stateMachineArn) {
+        throw new Error(`HyperFrames Lambda stack ${stackName} is missing render outputs.`);
+    }
+    stackCache = { value, expiresAt: Date.now() + 60_000 };
+    return value;
+}
+async function stageProject(input) {
+    const root = path.join(config.VIDFARM_DATA_DIR, "hyperframes-projects");
+    const projectDir = path.join(root, `${Date.now().toString(36)}-${safeIdentifier(input.compositionId)}-${randomUUID().slice(0, 8)}`);
+    await rm(projectDir, { recursive: true, force: true });
+    await mkdir(projectDir, { recursive: true });
+    await writeFile(path.join(projectDir, "index.html"), input.compositionHtml, "utf8");
+    for (const file of input.projectFiles || []) {
+        const target = safeProjectPath(projectDir, file.path);
+        await mkdir(path.dirname(target), { recursive: true });
+        await writeFile(target, file.contents);
+    }
+    for (const copyPath of input.copyPaths || []) {
+        const target = safeProjectPath(projectDir, copyPath.to);
+        await mkdir(path.dirname(target), { recursive: true });
+        await cp(copyPath.from, target, { recursive: true, force: true });
+    }
+    return projectDir;
+}
+function extractCompositionMetadata(html, input) {
+    const compositionId = safeIdentifier(input.compositionId || htmlAttribute(html, "data-composition-id") || input.composition?.compositionId || "composition");
+    const width = positiveInteger(input.width || htmlAttribute(html, "data-width") || input.composition?.width, 720);
+    const height = positiveInteger(input.height || htmlAttribute(html, "data-height") || input.composition?.height, 1280);
+    const fps = positiveInteger(input.fps || 30, 30);
+    const duration = Number.parseFloat(htmlAttribute(html, "data-duration") || String(input.composition?.duration || ""));
+    return {
+        compositionId,
+        title: input.title || htmlAttribute(html, "data-source-video") || compositionId,
+        width,
+        height,
+        fps,
+        duration: Number.isFinite(duration) && duration > 0 ? duration : null
+    };
+}
+function safeProjectPath(root, relativePath) {
+    const target = path.resolve(root, relativePath);
+    const resolvedRoot = path.resolve(root);
+    if (target !== resolvedRoot && !target.startsWith(`${resolvedRoot}${path.sep}`)) {
+        throw new Error(`Invalid HyperFrames project path: ${relativePath}`);
+    }
+    return target;
+}
+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 roundUsd(value) {
+    return Number(value.toFixed(4));
+}
+//# sourceMappingURL=hyperframes.js.map