@mevdragon/vidfarm-devcli 0.18.1 → 0.19.1

package/dist/src/services/hyperframes.js

@@ -7,6 +7,7 @@ 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";
@@ -21,6 +22,24 @@ import { applyMarkupUsd } from "./billing-pricing.js";
 // 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;
@@ -81,57 +100,12 @@ export class HyperframesService {
         if (shouldRenderLocally()) {
             return this.renderLocal({ ...input, compositionHtml });
         }
-        const metadata = extractCompositionMetadata(compositionHtml, input);
-        const stack = await resolveHyperframesStack();
-        devLog("hyperframes.render.staging", {
-            composition_id: metadata.compositionId,
-            width: metadata.width,
-            height: metadata.height,
-            fps: metadata.fps,
-            stack_name: stack.stackName,
-            region: stack.region
-        });
-        const projectDir = await stageProject({
-            compositionHtml,
-            compositionId: metadata.compositionId,
-            projectFiles: input.projectFiles,
-            copyPaths: input.copyPaths
-        });
-        const timestamp = Date.now().toString(36);
-        const renderId = input.executionName || `vf-${metadata.compositionId.slice(0, 40)}-${timestamp}-${randomUUID().slice(0, 8)}`;
-        const outputKey = input.outputKey || `renders/vidfarm/${metadata.compositionId}/${renderId}/output.mp4`;
-        devLog("hyperframes.render.dispatch", {
-            composition_id: metadata.compositionId,
-            render_id: renderId,
-            output_key: outputKey,
-            chunk_size: input.chunkSize ?? 240,
-            max_parallel_chunks: input.maxParallelChunks ?? 8,
-            wait: input.wait !== false
-        });
-        const { renderToLambda, getRenderProgress } = await import("@hyperframes/aws-lambda/sdk");
-        const handle = await renderToLambda({
-            projectDir,
-            bucketName: stack.bucketName,
-            stateMachineArn: stack.stateMachineArn,
-            region: stack.region,
-            executionName: renderId,
-            outputKey,
-            config: {
-                fps: normalizeRenderFps(metadata.fps),
-                width: metadata.width,
-                height: metadata.height,
-                format: input.format || "mp4",
-                codec: "h264",
-                quality: "standard",
-                chunkSize: input.chunkSize ?? 240,
-                maxParallelChunks: input.maxParallelChunks ?? 8,
-                runtimeCap: "lambda"
-            }
-        });
+        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: metadata.compositionId,
-                render_id: renderId,
+                composition_id: prep.metadata.compositionId,
+                render_id: prep.renderId,
                 execution_arn: handle.executionArn
             });
             return {
@@ -142,11 +116,12 @@ export class HyperframesService {
                 metadata: {
                     mode: "hyperframes_lambda",
                     status: "RUNNING",
-                    stack,
-                    composition: metadata
+                    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;
@@ -155,14 +130,14 @@ export class HyperframesService {
         for (;;) {
             const progress = await getRenderProgress({
                 executionArn: handle.executionArn,
-                region: stack.region,
-                defaultMemorySizeMb: stack.lambdaMemoryMb
+                region: prep.stack.region,
+                defaultMemorySizeMb: prep.stack.lambdaMemoryMb
             });
             pollCount += 1;
             if (progress.status !== lastLoggedStatus) {
                 devLog("hyperframes.render.progress", {
-                    composition_id: metadata.compositionId,
-                    render_id: renderId,
+                    composition_id: prep.metadata.compositionId,
+                    render_id: prep.renderId,
                     status: progress.status,
                     poll_count: pollCount,
                     elapsed_ms: Date.now() - startedAtMs,
@@ -172,42 +147,22 @@ export class HyperframesService {
                 lastLoggedStatus = progress.status;
             }
             if (progress.status === "SUCCEEDED") {
-                const outputS3Uri = progress.outputFile?.s3Uri || handle.outputS3Uri;
                 devLog("hyperframes.render.succeeded", {
-                    composition_id: metadata.compositionId,
-                    render_id: renderId,
+                    composition_id: prep.metadata.compositionId,
+                    render_id: prep.renderId,
                     duration_ms: Date.now() - startedAtMs,
-                    output_s3_uri: outputS3Uri,
+                    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 {
-                    ...handle,
-                    outputS3Uri,
-                    outputUrl: await signedS3Url(outputS3Uri, stack.region),
-                    endedAt: progress.endedAt,
-                    metadata: {
-                        mode: "hyperframes_lambda",
-                        status: progress.status,
-                        stack,
-                        composition: metadata,
-                        progress,
-                        costs: progress.costs,
-                        estimatedCostUsd: progress.costs.accruedSoFarUsd,
-                        chargeUsd: applyMarkupUsd(progress.costs.accruedSoFarUsd),
-                        costDisplay: progress.costs.displayCost,
-                        lambdasInvoked: progress.lambdasInvoked,
-                        framesRendered: progress.framesRendered,
-                        totalFrames: progress.totalFrames
-                    }
-                };
+                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: metadata.compositionId,
-                    render_id: renderId,
+                    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
@@ -216,8 +171,8 @@ export class HyperframesService {
             }
             if (Date.now() - startedAtMs > timeoutMs) {
                 devLog("hyperframes.render.timeout", {
-                    composition_id: metadata.compositionId,
-                    render_id: renderId,
+                    composition_id: prep.metadata.compositionId,
+                    render_id: prep.renderId,
                     timeout_ms: timeoutMs,
                     last_status: progress.status
                 }, "error");
@@ -226,6 +181,182 @@ export class HyperframesService {
             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
@@ -1628,6 +1759,197 @@ function normalizeViralDna(value) {
         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: "" },
+    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(" | ");
+    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}${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"
+  },
+  "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.
+- 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 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)
+        },
+        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
+    });
+    const attempt = await callVisionWithFallback({ prompt, frames: input.frames, keys: input.keys });
+    return normalizeEditorHarness(attempt.result);
+}
 function shortElementId() {
     return `element_${randomUUID().slice(0, 8)}`;
 }
@@ -2025,7 +2347,7 @@ export async function smartDecomposeVideo(input) {
         // non-fatal. The placement call is DELIBERATELY a separate request from the
         // caption/scene vision call so it can never dilute timeline-layer quality —
         // it just reuses the same already-sampled sparse frames (no extra ffmpeg).
-        const [attempt, ocrFrames, transcript, placementSurfaces] = await Promise.all([
+        const [attempt, ocrFrames, transcript, placementSurfaces, editorHarness] = await Promise.all([
             callVisionWithFallback({
                 prompt,
                 frames,
@@ -2049,6 +2371,18 @@ export async function smartDecomposeVideo(input) {
             }).catch((err) => {
                 console.error("smart decompose placement pass failed", err instanceof Error ? err.message : err);
                 return [];
+            }),
+            // Editor harness — technical editing direction. Isolated call in the same
+            // burst (reuses these frames + the detected cuts); non-fatal.
+            runEditorHarnessPass({
+                frames,
+                keys: input.keys,
+                durationSeconds: meta.durationSeconds,
+                sceneCuts,
+                userPrompt: input.userPrompt ?? null
+            }).catch((err) => {
+                console.error("smart decompose editor-harness pass failed", err instanceof Error ? err.message : err);
+                return DEFAULT_EDITOR_HARNESS;
             })
         ]);
         devLog("hyperframes.smart_decompose.ocr_completed", {
@@ -2147,12 +2481,15 @@ export async function smartDecomposeVideo(input) {
             caption_count: finalCaptions.length,
             captions_snapped: snapped.snappedCount,
             scenes_snapped: snappedScenes.snappedCount,
-            placement_surface_count: finalPlacementSurfaces.length
+            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,
@@ -2228,6 +2565,7 @@ export function buildSmartDecomposedHtml(input) {
     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>
@@ -2241,7 +2579,7 @@ export function buildSmartDecomposedHtml(input) {
   </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}">
+  <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}
@@ -2250,6 +2588,79 @@ export function buildSmartDecomposedHtml(input) {
 </body>
 </html>`;
 }
+// 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()
@@ -2625,6 +3036,44 @@ export function normalizePublishHtml(html) {
     }
     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);