@mevdragon/vidfarm-devcli 0.2.13 → 0.3.0

package/dist/src/dev-serve.js

@@ -0,0 +1,169 @@
+import { createServer } from "node:http";
+import { existsSync, mkdirSync, readFileSync, watch, writeFileSync } from "node:fs";
+import path from "node:path";
+import { parseArgs } from "node:util";
+// vidfarm dev-serve — a tiny HTTP layer that lets the browser editor point at
+// a local directory of composition files instead of the deployed API. The
+// editor detects dev mode from `?dev=<url>` (or localStorage) and rewrites
+// its fork API calls to hit this server. File changes fan out via SSE so the
+// editor can reload the composition on save-from-disk (e.g. Claude Code
+// edits the file directly).
+const CORS_HEADERS = {
+    "access-control-allow-origin": "*",
+    "access-control-allow-methods": "GET,PUT,PATCH,POST,OPTIONS",
+    "access-control-allow-headers": "content-type,authorization",
+    "access-control-max-age": "600"
+};
+export async function runDevServeCommand(argv) {
+    const parsed = parseArgs({
+        args: argv,
+        options: {
+            dir: { type: "string", default: "." },
+            port: { type: "string", default: "4321" }
+        }
+    });
+    const rootDir = path.resolve(process.cwd(), parsed.values.dir);
+    const port = Number(parsed.values.port);
+    if (!existsSync(rootDir)) {
+        mkdirSync(rootDir, { recursive: true });
+    }
+    let nextClientId = 1;
+    const clients = new Set();
+    function broadcast(event, data) {
+        const payload = `event: ${event}\ndata: ${JSON.stringify(data)}\n\n`;
+        for (const client of clients) {
+            try {
+                client.res.write(payload);
+            }
+            catch {
+                clients.delete(client);
+            }
+        }
+    }
+    // fs.watch fires on any child change. Coalesce bursts so a single save
+    // doesn't spam the editor with 3 reload events.
+    let reloadTimer = null;
+    const scheduleReload = (filename) => {
+        if (reloadTimer)
+            clearTimeout(reloadTimer);
+        reloadTimer = setTimeout(() => {
+            reloadTimer = null;
+            broadcast("reload", { file: filename, at: Date.now() });
+            console.log(`[dev-serve] reload → ${filename ?? "(unknown)"}`);
+        }, 80);
+    };
+    try {
+        watch(rootDir, { recursive: true }, (_type, filename) => {
+            scheduleReload(filename ?? null);
+        });
+    }
+    catch (error) {
+        console.warn(`[dev-serve] watch failed: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    const server = createServer((req, res) => handleRequest(req, res, rootDir, clients, nextClientId++));
+    server.listen(port, () => {
+        console.log(`[dev-serve] serving ${rootDir}`);
+        console.log(`[dev-serve] listening on http://localhost:${port}`);
+        console.log(`[dev-serve] editor: open with ?dev=${encodeURIComponent(`http://localhost:${port}`)}`);
+    });
+    process.on("SIGINT", () => {
+        console.log("\n[dev-serve] shutting down");
+        server.close(() => process.exit(0));
+    });
+}
+function handleRequest(req, res, rootDir, clients, clientId) {
+    const method = (req.method ?? "GET").toUpperCase();
+    const url = new URL(req.url ?? "/", `http://localhost`);
+    const pathname = url.pathname;
+    if (method === "OPTIONS") {
+        res.writeHead(204, CORS_HEADERS);
+        res.end();
+        return;
+    }
+    if (pathname === "/_events" && method === "GET") {
+        res.writeHead(200, {
+            ...CORS_HEADERS,
+            "content-type": "text/event-stream",
+            "cache-control": "no-cache",
+            connection: "keep-alive"
+        });
+        res.write(`event: hello\ndata: ${JSON.stringify({ at: Date.now() })}\n\n`);
+        const client = { res, id: clientId };
+        clients.add(client);
+        req.on("close", () => clients.delete(client));
+        return;
+    }
+    const filePath = resolveFilePath(rootDir, pathname);
+    if (!filePath) {
+        respondJson(res, 404, { ok: false, error: `Not found: ${pathname}` });
+        return;
+    }
+    if (method === "GET") {
+        if (!existsSync(filePath)) {
+            respondJson(res, 404, { ok: false, error: `Missing ${path.basename(filePath)}` });
+            return;
+        }
+        const body = readFileSync(filePath);
+        const contentType = pathname.endsWith(".html") ? "text/html; charset=utf-8" : "application/json";
+        res.writeHead(200, { ...CORS_HEADERS, "content-type": contentType });
+        res.end(body);
+        return;
+    }
+    if (method === "PUT" && pathname.endsWith("/composition.html")) {
+        readBody(req).then((body) => {
+            const html = body.toString("utf8");
+            if (!html.includes("data-composition-id=")) {
+                respondJson(res, 400, { ok: false, error: "Composition HTML is missing data-composition-id" });
+                return;
+            }
+            mkdirSync(path.dirname(filePath), { recursive: true });
+            writeFileSync(filePath, html, "utf8");
+            respondJson(res, 200, { ok: true, bytes: html.length });
+        }).catch((error) => respondJson(res, 500, { ok: false, error: String(error) }));
+        return;
+    }
+    if (method === "PATCH" && pathname.endsWith("/composition.json")) {
+        readBody(req).then((body) => {
+            const patch = JSON.parse(body.toString("utf8") || "{}");
+            const existing = existsSync(filePath) ? JSON.parse(readFileSync(filePath, "utf8") || "{}") : {};
+            const merged = { ...existing, ...patch };
+            mkdirSync(path.dirname(filePath), { recursive: true });
+            writeFileSync(filePath, JSON.stringify(merged, null, 2), "utf8");
+            respondJson(res, 200, merged);
+        }).catch((error) => respondJson(res, 500, { ok: false, error: String(error) }));
+        return;
+    }
+    respondJson(res, 405, { ok: false, error: `Method ${method} not allowed on ${pathname}` });
+}
+// Restrict served paths to the working/version composition files. Anything
+// else 404s so this server isn't a random static host.
+function resolveFilePath(rootDir, pathname) {
+    const clean = pathname.replace(/^\/+/, "");
+    const parts = clean.split("/").filter(Boolean);
+    if (parts.length === 0)
+        return null;
+    const filename = parts[parts.length - 1];
+    const allowed = ["composition.html", "composition.json", "manifest.json"];
+    if (!allowed.includes(filename))
+        return null;
+    // Allow: `composition.html`, `versions/1/composition.html`.
+    if (parts.length === 1)
+        return path.join(rootDir, filename);
+    if (parts.length === 3 && parts[0] === "versions" && /^\d+$/.test(parts[1])) {
+        return path.join(rootDir, "versions", parts[1], filename);
+    }
+    return null;
+}
+function respondJson(res, status, body) {
+    res.writeHead(status, { ...CORS_HEADERS, "content-type": "application/json" });
+    res.end(JSON.stringify(body));
+}
+function readBody(req) {
+    return new Promise((resolve, reject) => {
+        const chunks = [];
+        req.on("data", (chunk) => chunks.push(chunk));
+        req.on("end", () => resolve(Buffer.concat(chunks)));
+        req.on("error", reject);
+    });
+}
+//# sourceMappingURL=dev-serve.js.map

package/package.json

@@ -1,37 +1,18 @@
 {
   "name": "@mevdragon/vidfarm-devcli",
-  "version": "0.2.13",
-  "description": "DEPRECATED. Built for the old REST-API Vidfarm template model. Superseded by the browser-based Trackpad Editor at https://vidfarm.cc/editor/. No longer maintained.",
-  "deprecated": "This CLI targeted the old REST-API template paradigm. Vidfarm now uses the Trackpad Editor (composition-based editing in the browser). See SKILL.platform.md.",
+  "version": "0.3.0",
+  "description": "Local bridge for the Vidfarm Trackpad Editor. Point it at a template id, edit composition.html on disk (Claude Code, Codex, etc.), preview live in the browser at https://vidfarm.cc/editor/.",
   "type": "module",
   "bin": {
     "vidfarm": "dist/src/cli.js",
     "vidfarm-devcli": "dist/src/cli.js"
   },
   "files": [
-    "dist/src",
-    "public/assets",
-    "auto-create-templates/AUTO_CREATE_TEMPLATES.md",
-    "auto-create-templates/extractor-system-prompt.md",
-    "auto-create-templates/production-graph.schema.json",
-    "auto-create-templates/runbook.md",
-    "auto-create-templates/template-plan.schema.json",
-    "auto-create-templates/template-planner-prompt.md",
-    "auto-create-hyperframe-templates/AUTO_CREATE_HYPERFRAME_TEMPLATES.md",
-    "auto-create-hyperframe-templates/extractor-system-prompt.md",
-    "auto-create-hyperframe-templates/input-manifest.schema.json",
-    "auto-create-hyperframe-templates/lambda-memory-estimator.md",
-    "auto-create-hyperframe-templates/production-graph.schema.json",
-    "auto-create-hyperframe-templates/runbook.md",
-    "auto-create-hyperframe-templates/scripts/create-hyperframe-template.mjs",
-    "auto-create-hyperframe-templates/template-plan.schema.json",
-    "auto-create-hyperframe-templates/template-planner-prompt.md",
-    "dist/templates/vidfarm_template_0000",
-    "templates/vidfarm_template_0000",
+    "dist/src/cli.js",
+    "dist/src/dev-serve.js",
     "README.md",
     "SKILL.director.md",
     "SKILL.platform.md",
-    ".env.example",
     "!readme.secret.md"
   ],
   "publishConfig": {
@@ -47,7 +28,7 @@
   "scripts": {
     "dev": "tsx --import ./src/instrument.ts watch src/index.ts",
     "dev:frontend": "node scripts/build-homepage-client.mjs --watch",
-    "dev:cli": "tsx src/cli.ts dev",
+    "dev:cli": "tsx src/cli.ts --help",
     "build:frontend": "node scripts/build-homepage-client.mjs",
     "build:hyperframes-editor": "cd demo && node scripts/build.mjs",
     "operator:template-artifact": "node scripts/platform-operator-template-artifact.mjs",

package/.env.example

@@ -1,60 +0,0 @@
-NODE_ENV="development"
-PORT="3000"
-MOCK_PROVIDER_RESPONSES="false"
-MAX_ACTIVE_JOBS_PER_CUSTOMER="30"
-PROVIDER_LEASE_INLINE_WAIT_SECONDS="5"
-PROVIDER_LEASE_STEP_WAIT_SECONDS="60"
-PROVIDER_LEASE_MAX_STEP_WAIT_SECONDS="43200"
-MAX_JOB_WALL_CLOCK_SECONDS="86400"
-
-OPENAI_API_KEY=""
-OPENROUTER_API_KEY=""
-GEMINI_API_KEY=""
-PERPLEXITY_API_KEY=""
-GHOSTCUT_KEY=""
-GHOSTCUT_SECRET=""
-
-# Optional. Production CDK wires these automatically. Browser-facing Lambda calls still callback to PUBLIC_BASE_URL for auth.
-VIDFARM_ZIP_LAMBDA_URL=""
-VIDFARM_ZIP_LAMBDA_SECRET=""
-VIDFARM_BILLING_URL=""
-VIDFARM_BILLING_SECRET=""
-VIDFARM_RATE_LIMITS_TABLE_NAME=""
-# Optional production CDK overrides. Leave empty to use deterministic per-account/per-region names.
-VIDFARM_STORAGE_S3_BUCKET_NAME=""
-
-# Optional when calling a hosted Vidfarm API directly.
-VIDFARM_USER_ID=""
-VIDFARM_API_KEY=""
-# Optional director override for production debugging. Send as x-superagency-key.
-SUPERAGENCY_KEY=""
-
-# Optional local overrides. The CLI will choose sensible local defaults.
-PUBLIC_BASE_URL="http://localhost:3310"
-# Optional public browser-facing chat endpoint. Leave empty locally unless you want the UI to hit a separate chat host directly.
-PUBLIC_EDITOR_CHAT_URL=""
-
-# Optional Sentry setup. SENTRY_DSN powers the Hono Node backend.
-# SENTRY_LAMBDA_DSN powers the CDK-managed AWS Lambdas.
-# PUBLIC_SENTRY_DSN powers the browser React bundles and may be the same DSN or a separate browser project DSN.
-SENTRY_DSN=""
-SENTRY_ENVIRONMENT="development"
-SENTRY_RELEASE=""
-SENTRY_TRACES_SAMPLE_RATE=""
-SENTRY_ENABLE_LOGS="true"
-SENTRY_SEND_DEFAULT_PII="false"
-SENTRY_DEBUG_ROUTE="false"
-SENTRY_LAMBDA_DSN=""
-SENTRY_LAMBDA_TRACES_SAMPLE_RATE="1.0"
-PUBLIC_SENTRY_DSN=""
-PUBLIC_SENTRY_TRACES_SAMPLE_RATE=""
-PUBLIC_SENTRY_REPLAYS_SESSION_SAMPLE_RATE=""
-PUBLIC_SENTRY_REPLAYS_ON_ERROR_SAMPLE_RATE=""
-PUBLIC_SENTRY_ENABLE_LOGS="true"
-PUBLIC_SENTRY_SEND_DEFAULT_PII="true"
-PUBLIC_SENTRY_TRACE_PROPAGATION_TARGETS=""
-REMOTION_MODE="local"
-
-
-GHOSTCUT_KEY="_________"
-GHOSTCUT_SECRET="_________"

package/auto-create-hyperframe-templates/AUTO_CREATE_HYPERFRAME_TEMPLATES.md

@@ -1,275 +0,0 @@
-# Auto-Create HyperFrame Templates Harness
-
-This harness turns a simple MP4, image, or PNG/JPG/WebP slideshow into an editable HyperFrames composition that can be rendered through the production AWS Lambda stack.
-
-Use this when the desired output is not a Vidfarm operation package, but a decomposed HyperFrames project:
-
-```txt
-drafts/<format_slug>/
-  source.md
-  preview/
-    source.mp4
-  composition.html
-  composition.json
-  lambda-site.json
-```
-
-The goal is to make the source editable in the HyperFrames editor while keeping publish behavior faithful. If a user deletes a source video scene, the final render must show a blank/background gap unless another timed layer covers that range. Do not rely on an always-on source video for publish output.
-
-## Start Here
-
-Give a Codex agent these two things:
-
-1. this entry file: `auto-create-hyperframe-templates/AUTO_CREATE_HYPERFRAME_TEMPLATES.md`
-2. one source media folder, preferably shaped like:
-
-```txt
-drafts/<format_slug>/
-  source.md
-  preview/
-    source.mp4
-    slide-01.png
-    slide-02.png
-```
-
-Then ask:
-
-```txt
-Use auto-create-hyperframe-templates/AUTO_CREATE_HYPERFRAME_TEMPLATES.md as the harness. Analyze drafts/<format_slug>/, create the run artifacts, generate the HyperFrames production graph and template plan, then write composition.html, composition.json, and lambda-site.json.
-```
-
-For the current local bridge, you can run:
-
-```bash
-node auto-create-hyperframe-templates/scripts/create-hyperframe-template.mjs drafts/<format_slug>/preview/source.mp4
-```
-
-For a slideshow, pass the folder containing the images:
-
-```bash
-node auto-create-hyperframe-templates/scripts/create-hyperframe-template.mjs drafts/<format_slug>/preview
-```
-
-Add `--stage-site` when you want the script to call the production HyperFrames Lambda site upload after writing the local artifacts.
-
-The source can be:
-
-- one MP4
-- a folder of PNG/JPG/WebP slides
-- a mixed folder with source video, screenshots, overlay images, audio, and notes
-
-If `source.md` is missing, create it with the source URL, adaptation goal, expected audience, and any constraints that can be inferred from the files.
-
-For programmatic runs, write an input manifest matching `input-manifest.schema.json`:
-
-```json
-{
-  "mode": "autocreate-hyperframe-template",
-  "input_path": "drafts/my-format/preview/source.mp4",
-  "output_path": "drafts/my-format",
-  "slug_id": "my-format",
-  "source_mode": "auto",
-  "render_defaults": {
-    "width": 720,
-    "height": 1280,
-    "fps": 30
-  },
-  "lambda": {
-    "stack_name": "hyperframes-vidfarm-prod",
-    "region": "us-east-1",
-    "memory_strategy": "estimate"
-  },
-  "publish": {
-    "prestage_site": false,
-    "output_url_policy": "signed_https_final_output_only"
-  }
-}
-```
-
-## Output Contract
-
-Every successful run should produce:
-
-- `composition.html`: a self-contained HyperFrames composition using deterministic HTML/CSS and timed media elements.
-- `composition.json`: the editable editor manifest: source assets, scene cuts, layers, caption geometry, viral/visual DNA, and Lambda estimate.
-- `lambda-site.json`: the production Lambda site/render metadata: stack, region, memory estimate, site id if pre-staged, and render defaults.
-- optional `frames/contact-sheet.jpg`, `source/ffprobe.json`, `transcripts/stt.json`, `ocr/frame_text.json`, and `motion/scene-cuts.json`.
-
-The `composition.json` should follow `template-plan.schema.json` after planning. The lower-level extraction artifact should follow `production-graph.schema.json`.
-
-## Core Principle
-
-HyperFrames is the editor and deterministic renderer. The harness should decompose the source into layers that remain individually editable:
-
-- source video scene clips
-- source audio
-- images or slide frames
-- deterministic captions
-- deterministic HTML overlays
-- shapes, chips, arrows, circles, masks, UI shells, and stickers
-- generated assets only when the visual cannot be rebuilt deterministically
-
-Important readable text should not be baked into generated media unless the source format is explicitly poster/artifact-native and OCR validation is part of the quality harness.
-
-## Timeline Rules
-
-Use absolute seconds in manifests and data attributes. Convert to frames only at render time.
-
-Required layer fields:
-
-- `id`
-- `kind`
-- `start`
-- `duration`
-- `track`
-- `z`
-- `mode`
-- `source_of_truth`
-- `geometry`
-- `viral_alignment`
-
-For video decomposition, split source video into scene layers:
-
-```json
-{
-  "id": "scene-2",
-  "kind": "video",
-  "start": 3.567,
-  "duration": 3.033,
-  "track": 0,
-  "z": 0,
-  "mode": "both",
-  "media": {
-    "src": "/drafts/example/source.mp4",
-    "media_start": 3.567,
-    "fit": "cover"
-  }
-}
-```
-
-For publish correctness, timed video scene layers should become real timed media layers or publish-time timeline proxies that are rewritten into real timed media. A preview-only playback source may exist for editor scrubbing, but it must be ignored or normalized out during publish.
-
-Blank gaps are valid. If no layer covers a time range, render the composition background for that range.
-
-## Slideshow Rules
-
-For an image slideshow, create one timed image layer per slide:
-
-```json
-{
-  "id": "slide-01-image",
-  "kind": "image",
-  "start": 0,
-  "duration": 3,
-  "track": 0,
-  "z": 0,
-  "mode": "both",
-  "media": {
-    "src": "/drafts/example/slide-01.png",
-    "fit": "cover"
-  }
-}
-```
-
-Caption text should be separate `caption` or `html` layers unless the source is intentionally a flattened image/poster template.
-
-## Caption And Overlay Rules
-
-Captions are deterministic layout, not an afterthought. Record:
-
-- font family and fallback
-- font weight
-- font size in px at the target composition size
-- line height
-- max width
-- x/y/width/height in percentages
-- text alignment
-- safe-area constraints
-- outline, radial halo, shadow, or inline highlight chip behavior
-- whether text can wrap and how many lines are allowed
-
-Caption positions must account for TikTok/Reels unsafe zones. For vertical 9:16 output, preserve:
-
-- top 8-12 percent for app chrome risk
-- right 12-16 percent for action buttons
-- bottom 14-20 percent for username, caption, and scrubber risk
-- center subject-safe zone when faces/products matter
-
-Use inline chips that hug measured wrapped lines when the source has caption backgrounds. Do not turn inline chips into full-width bars or large paragraph washes.
-
-For white TikTok-native captions, prefer a radial halo or outline. Avoid a single directional web drop shadow when the source uses a native black glyph halo.
-
-For multiline captions, wrap once, choose one shared font size and line height, render one block, then measure per-line chips after layout. Do not render each wrapped line as an independently trimmed text image.
-
-## Lambda Memory Estimate
-
-Each plan must include a `lambda_memory_estimate` with:
-
-- `recommended_memory_mb`
-- `confidence`
-- `complexity_scores`
-- `rationale`
-- `risk_flags`
-- `benchmark_override`
-
-Default to `3072` MB for ordinary 720x1280 or 1080x1920 social-video compositions with one active video stream and deterministic overlays. Use `2048` MB only for static/slideshow/simple 720p outputs or after local evidence that video decode is light. Use `4096` MB for 1080p video, multiple simultaneous videos, heavy DOM/caption effects, or long audio mixing. Reserve `6144+` MB for high-resolution or failure-prone compositions.
-
-Do not default to `10240` MB. Use it only after timeouts, Chromium memory failures, or a measured case that requires it.
-
-See `lambda-memory-estimator.md` for the scoring rubric.
-
-## Production Lambda Site
-
-The generated plan should be ready for the deployed production Lambda stack:
-
-- stack: `hyperframes-vidfarm-prod`
-- default region: `us-east-1`
-- default memory: `3072`
-- output policy: frontend should show only the final downloadable/signed output URL, not AWS console links that require login
-
-For repeat publishing, pre-stage the project as a Lambda site and write `lambda-site.json`:
-
-```json
-{
-  "schema": "vidfarm.hyperframe.lambda-site.v1",
-  "stack_name": "hyperframes-vidfarm-prod",
-  "region": "us-east-1",
-  "site_id": "content-addressed-site-id",
-  "project_dir": "drafts/example",
-  "composition_file": "composition.html",
-  "memory_mb": 3072,
-  "render_defaults": {
-    "width": 720,
-    "height": 1280,
-    "fps": 30
-  },
-  "output_url_policy": "signed_https_final_output_only"
-}
-```
-
-If the site has not been uploaded yet, set `site_id` to `null` and include `site_upload_command` or `site_upload_api`.
-
-## Pipeline
-
-1. Intake source media and notes.
-2. Extract `ffprobe`, contact sheet, scene cuts, OCR, transcript, and simple layout/subject regions.
-3. Generate `production_graph.json` with `extractor-system-prompt.md`.
-4. Generate `template_plan.json` with `template-planner-prompt.md`.
-5. Write `composition.html`, `composition.json`, and `lambda-site.json`.
-6. Validate locally in the editor.
-7. Stage the project with the production Lambda site flow.
-8. Publish through Lambda and verify the final output URL.
-
-## Required Validation
-
-Before publishing:
-
-- every timed layer has non-negative `start` and positive `duration`
-- no two editable layers overlap on the same track unless the track is intentionally composited
-- scene video layers use `media_start`/`playbackStart` rather than an always-on background dependency
-- deleting a scene removes that visual range from publish output
-- captions are legible at phone size
-- caption boxes avoid unsafe TikTok/Reels zones unless the source intentionally uses them
-- source audio and source video are separate layers when audio is reused continuously
-- Lambda memory estimate has a concrete rationale
-- `lambda-site.json` does not contain credentials

package/auto-create-hyperframe-templates/extractor-system-prompt.md

@@ -1,128 +0,0 @@
-# HyperFrames Production Graph Extractor Prompt
-
-You are a HyperFrames production analyst.
-
-Your job is to inspect one MP4, screenshot set, or PNG/JPG/WebP slideshow and extract the repeatable HyperFrames production process as structured JSON. Do not merely describe the media. Convert it into an editable composition graph that can become `composition.html`, `composition.json`, and a production Lambda site.
-
-Return only JSON matching `production-graph.schema.json`.
-
-## Inputs You May Receive
-
-- source notes
-- source video or slides
-- contact sheet
-- representative frames
-- ffprobe metadata
-- scene cut list
-- STT transcript with word timestamps
-- OCR text from frames
-- layout analysis with bounding boxes
-- existing `composition.html` or `composition.json`
-- desired output dimensions and fps
-
-## Extraction Rules
-
-- Treat all supplied media as one reusable HyperFrames format.
-- Separate source media, deterministic overlays, captions, audio, and generated assets.
-- Identify which visual surfaces are editable layers and which are source-media content.
-- Important readable text should default to deterministic HTML/caption layers, not baked generated media.
-- Extract exact or inferred timing for scenes, slides, captions, overlays, transitions, zooms, holds, and loop points.
-- Record source media slices with `media_start` when a layer uses a segment from a longer MP4.
-- Preserve blank gaps as intentional timeline ranges when no layer should be visible.
-- Do not depend on an always-on source video for publish correctness. Preview playback sources are allowed only as editor affordances.
-- Distinguish `mode: "both"`, `mode: "editor"`, and `mode: "publish"`.
-- Use percent geometry for layer placement: `x`, `y`, `width`, `height`.
-- Use seconds for `start`, `duration`, `media_start`, and `media_end`.
-- Track source audio separately from source video if audio should continue across scene cuts.
-- Keep one editable timeline track collision-free unless the track is explicitly marked as composited.
-- Identify caption safe areas and collisions with TikTok/Reels chrome.
-- Record Lambda memory estimate inputs: resolution, duration, active video streams, source resolution, layer count, DOM complexity, effects, audio mixing, and known risk flags.
-
-## Required Analysis Dimensions
-
-Extract:
-
-- format summary and source mode
-- output dimensions, fps, and total duration
-- source asset inventory
-- scene or slide timeline
-- layer decomposition
-- deterministic caption and text surfaces
-- HTML overlay surfaces
-- media replacement slots
-- audio plan
-- safe areas and subject bounds
-- caption positioning and wrapping rules
-- visual rules that must survive adaptation
-- editable controls
-- generated asset needs, if any
-- Lambda memory estimate
-- production Lambda site readiness
-- validation checklist
-
-## Layer Classification
-
-For every meaningful visual or audio element choose one kind:
-
-- `video`: timed video layer or scene slice
-- `image`: timed image/slide layer
-- `audio`: timed audio layer
-- `caption`: text intended as subtitle/creator caption
-- `html`: custom deterministic HTML overlay, UI card, comment, notification, or app shell
-- `shape`: non-text geometric layer
-- `effect`: deterministic transform/filter/mask/highlight
-
-For every layer choose one source of truth:
-
-- `source_media`: the original media asset is the visual/audio content
-- `deterministic_html`: HTML/CSS/text is the source of truth
-- `generated_asset`: AI/generated media is the source of truth
-- `user_asset`: caller-provided replacement asset is required
-- `computed_effect`: derived motion, mask, crop, zoom, or highlight
-
-## Caption Rules
-
-Strongly identify typography:
-
-- font family match
-- fallback font stack
-- font weight
-- case
-- color
-- outline, stroke, radial halo, shadow
-- background chip style
-- line wrapping
-- line height
-- alignment
-- safe area
-- phone-size legibility
-
-When captions have colored backgrounds, classify them as inline highlight chips unless the source clearly uses a panel. Chips must hug measured wrapped lines.
-
-When captions are white TikTok-native captions, distinguish radial black halo/outline from a web-style directional shadow.
-
-For multiline captions, require one shared font size and line height for the block. Do not recommend per-line rendered images.
-
-## Lambda Memory Estimate Rules
-
-Estimate memory from composition complexity, not vibes.
-
-Use these defaults:
-
-- `2048` MB for static/slideshow/simple image compositions with low DOM complexity.
-- `3072` MB for standard 720x1280 or 1080x1920 social video with one active video stream and deterministic overlays.
-- `4096` MB for 1080p video, multiple active videos, heavy captions, masks, filters, or long audio.
-- `6144` MB or higher only when high resolution, many simultaneous layers, or prior failures justify it.
-
-Return both a recommendation and a confidence. Include benchmark guidance only when the source sits near a threshold.
-
-## Output Bias
-
-Be concrete. A production graph should be implementable.
-
-Bad: "Add captions around the video."
-
-Good: "Render a 2-line white TikTok Sans Semibold caption block at x=8, y=42, width=84, height=14, fontSize=46, lineHeight=1.08, black radial halo, max 18 chars per line, timed 0.0-2.4s."
-
-Publish correctness bias: if a source video is split into scenes, every scene must be its own timed layer or publish proxy. Deleting scene 2 must delete scene 2 from the final render.
-