@mevdragon/vidfarm-devcli 0.2.12 → 0.2.14

package/SKILL.platform.md

@@ -0,0 +1,312 @@
+---
+name: vidfarm-platform
+description: Vidfarm platform architecture reference. Use this for questions about how compositions, forks, versions, storage, DynamoDB records, the Trackpad Editor runtime, Remotion render Lambda, editor-chat, primitives, and billing fit together. This is not a director skill (see SKILL.director.md) and not a runbook — it explains the system.
+---
+
+# Vidfarm Platform Architecture
+
+Vidfarm is a **serverless composition studio** for short-form video. Directors fork templates, edit compositions on a timeline (the Trackpad Editor), publish MP4s via a shared Remotion Lambda, and share results.
+
+This document is the architectural reference — what runs where, what data lives where, and how the pieces connect. Use it when planning changes, debugging cross-cutting behavior, or onboarding to the platform.
+
+For customer-facing usage patterns, see `SKILL.director.md`.
+
+## Runtime shape
+
+Vidfarm runs entirely on AWS serverless:
+
+- **API** — a single Hono app deployed as a container Lambda behind an API Gateway custom domain per stage
+- **Editor Chat** — a separate Lambda + custom domain for streaming AI editor sessions
+- **Primitive Media** — a separate Lambda + custom domain for standalone media primitives (image gen, video generation, etc.)
+- **Ready Post Zip** — a separate Lambda + custom domain for scheduled/approved-post ZIP downloads
+- **Billing** — a separate Lambda + custom domain for Stripe webhooks, wallet top-ups, and idempotent charge processing
+- **Job Runner** — a Lambda invoked by the API to execute template operations
+- **Job Sweeper** — a scheduled Lambda that stalls / retries / cleans up in-flight jobs
+
+Stages:
+
+- `staging` — `staging.vidfarm.cc` (+ sibling subdomains for billing, editor-chat, primitive-media, zip)
+- `production` — `vidfarm.cc`
+
+Every stage is a separate CDK stack with fully separate DynamoDB tables, S3 buckets, Lambdas, and DNS.
+
+There is no EC2, no SQLite, no long-lived worker. Everything scales to zero at idle.
+
+## Data model
+
+### DynamoDB — single-table
+
+One main table per stage: `VidfarmMainTable`. Partitioned by `entity_type`. Records include:
+
+- `customer` — director account, wallet, provider keys reference, timestamps
+- `customer_api_key` — API key hash + salt
+- `template` — imported template registration (slug, source repo, active release pointer)
+- `template_release` — a specific artifact for a template
+- `job` — an in-flight or completed job execution
+- `job_log_event` — structured log lines per job (transient — pruned)
+- `api_call_history` — request audit trail (transient)
+- `editor_chat_message` — chat history (transient)
+- `serverless_record#composition_fork` — an editable composition fork
+- `serverless_record#fork_version` — an immutable version snapshot for a fork
+- `serverless_record#fork_permission` — a per-user grant on a fork
+- `serverless_record#fork_share_link` — a share-token URL for a fork
+- `submitted_video` — a source video uploaded by a director
+- `provider_key_lease` — short-lived AI key leases for job runners
+- `billing_event` — wallet transactions and Stripe events
+
+Query patterns use GSIs on `customerId`, `forkId`, `granteeId`, `slug`, and `status`.
+
+### S3 — composition storage
+
+Bucket per stage. Layout is **ownership-agnostic** — the customerId does not appear in the S3 key. Access control is enforced at the API layer via the DynamoDB permission records.
+
+```
+compositions/forks/<forkId>/
+├── working/
+│   ├── composition.html       # current editor state
+│   ├── composition.json       # current metadata (scenes, captions, viral DNA)
+│   └── ghostcut.json          # GhostCut subtitle-removal task state (optional)
+└── versions/<version>/
+    ├── composition.html
+    └── composition.json
+```
+
+Additional prefixes:
+
+- `renders/vidfarm/<slug>/<render-id>/output.mp4` — published MP4s
+- `submissions/<videoId>/...` — raw source video uploads
+- `template-assets/<slug>/...` — template media
+- `user-attachments/<customerId>/...` — chat panel uploads (only ownership-keyed area remaining)
+
+Old ownership-keyed composition paths (`compositions/users/<customerId>/forks/...`) were migrated away by `scripts/migrate-compositions-to-ownership-agnostic.ts`. Old `decomposition.json` was renamed to `composition.json` by `scripts/migrate-decomposition-to-composition.ts`.
+
+## Composition model
+
+A composition is a single HTML document plus a JSON sidecar.
+
+**composition.html** is a self-contained document. Top-level structure:
+
+```html
+<div data-composition-id="<forkId>@v<version>" data-viral-dna="{...}">
+  <div data-vf-timeline-proxy="video" data-src="..." data-start="0" data-duration="12" />
+  <div data-hf-id="clip_1" data-layer-kind="video"
+       data-start="0" data-duration="3.5" data-track-index="0"
+       data-playback-start="0.25" data-src="...">
+    ...
+  </div>
+  <div data-hf-id="caption_1" data-layer-kind="caption"
+       data-start="0.5" data-duration="2.0" data-track-index="1"
+       style="position:absolute;left:5%;top:60%;...">
+    HOOK LINE
+  </div>
+  <!-- more layers... -->
+  <script type="module"><!-- composition-runtime.ts injected inline --></script>
+</div>
+```
+
+**composition.json** carries the semantic metadata parsed once at auto-decompose time and used by the editor sidebar, chat context, and publish payload:
+
+```json
+{
+  "summary": "...",
+  "scenes": [{ "slug": "hook_reveal", "start": 0, "duration": 1.5, "label": "...", "viral_note": "..." }],
+  "captions": [{ "slug": "caption_1", "text": "...", "start": 0, "duration": 1.5, "x": 5, "y": 60 }],
+  "viralDna": { "hook": "...", "retention": "...", "payoff": "...", "preserve": [...], "avoid": [...] },
+  "width": 1080,
+  "height": 1920,
+  "durationSeconds": 10.5,
+  "source_assets": [{ "type": "video", "url": "...", "width": ..., "height": ..., "duration": ... }]
+}
+```
+
+Both files are treated as immutable per version. The working state is mutable.
+
+## Composition runtime
+
+`src/composition-runtime.ts` generates a browser-side script that gets injected into every composition HTML. It provides:
+
+- **Playback control** — reads all `[data-start][data-duration][data-track-index]` layers, toggles their visibility based on the current time, and syncs media element `currentTime` per clip
+- **Player adapter** — exposes `window.__player = { play(), pause(), seek(t), setTime(t), duration, playing, playbackRate, previewMuted, refreshClips() }` for the editor to control the iframe
+- **Media coordination** — respects `data-playback-start`, `data-volume`, and clip-specific mute
+- **Selection sync** — listens for `postMessage({ source: "hf-parent", ... })` from the parent editor to highlight/deselect clips
+
+The same runtime is used inside the Trackpad Editor iframe AND when a published fork is embedded elsewhere. It is agnostic to whether it's being edited or viewed.
+
+## The Trackpad Editor
+
+`demo/src/HyperframesStudioEditor.tsx` is the timeline editor. It:
+
+- Renders a `<Timeline>` and `<Player>` from `@hyperframes/studio` — a shared package with the timeline UI, drag/trim logic, and player state store (Zustand)
+- Loads `composition.html` + `composition.json` from the fork's working state
+- Renders the composition into a preview iframe using a `blob:` URL
+- Bidirectionally syncs timeline drag → HTML `data-start`/`data-duration` mutations, and inspector edits → text/style changes
+- Persists every commit back to the API as PUT `composition.html` and PATCH `composition.json`
+- Exposes an **Editor Action API** so the Chat panel can invoke 13 typed actions (`add_layer`, `remove_layer`, `set_layer_start`, `set_layer_duration`, `set_layer_style`, `group_layers`, `ungroup_layers`, `replace_composition_html`, etc.)
+- Runs the composition-runtime script inside the preview iframe to keep timeline scrub in sync with the current time
+
+The editor is a single monolithic React component (~9k lines). It builds cleanly to a static bundle deployed to CloudFront under `/editor/`.
+
+## Publishing (render pipeline)
+
+Publish flow:
+
+1. Client `POST /api/v1/compositions/:forkId/publish`
+2. API stamps `data-composition-id="<forkId>@v<N>"` into the composition HTML, PUTs the stamped HTML to working, and reads composition.json
+3. API resolves the caller's provider keys (preflight check for required models)
+4. API creates a `job` record and invokes the `hyperframes_render` primitive Lambda
+5. The primitive Lambda uploads the composition as a Remotion site, calls `renderMediaOnLambda` with the shared Remotion render Lambda ARN, waits for the MP4 to land in S3
+6. On success, the primitive returns `{ primary_file_url: "s3://.../output.mp4" }`, the API creates a `ForkVersionRecord` with `reason: "publish"`, writes the snapshot to `versions/<N>/`, and updates the fork's `latestVersion` and `currentRenderJobId`
+7. Client polls `GET /api/v1/compositions/:forkId/renders/:renderId` for `{ phase, progress, output_url, cost_usd }`
+
+The Remotion Lambda is **shared across all templates and forks** — it's an infrastructure primitive, not a per-template deployment. Its ARN is passed to the Vidfarm stack as an env var.
+
+## Auto-decompose
+
+`POST /api/v1/compositions/:forkId/auto-decompose` splits a raw source video into a Trackpad-editable composition. Two modes:
+
+- **`time-slice`** (deterministic) — `src/hyperframes/composition.ts`'s `decomposeUndecomposedComposition()` splits the source duration into N equal-length scenes, wraps each in a `<div data-vf-timeline-proxy="video">` layer with `data-start`/`data-duration`/`data-playback-start`. Instant. No AI.
+- **`smart`** (AI) — `src/services/hyperframes.ts`'s `smartDecomposeVideo()` downloads the source, samples frames, calls Gemini/OpenAI/OpenRouter vision (in priority order) using the caller's saved keys, extracts scenes with labels and viral notes, extracts on-screen captions with position, and generates viral DNA. Then it also submits an async **GhostCut** subtitle-removal task if the source has hardcoded subs. Takes 30-60s + async ghostcut poll.
+
+Both modes update the composition.html and composition.json in place, and create a fork version snapshot with `reason: "manual"`.
+
+## GhostCut integration
+
+GhostCut is an external AI subtitle-removal service. Vidfarm proxies to it via `src/services/ghostcut.ts`:
+
+- `submitSubtitleRemoval(sourceUrl)` — queue the removal task
+- `pollStatus(taskId)` — check status (`pending` | `processing` | `queued` | `done` | `failed`)
+- `mirrorGhostcutVideoToStorage()` — copy the clean output back to Vidfarm S3
+
+State is persisted per fork at `compositions/forks/<forkId>/working/ghostcut.json`. The client polls `POST /api/v1/compositions/:forkId/ghostcut-poll` every few seconds during smart decompose.
+
+Configuration: `GHOSTCUT_KEY` and `GHOSTCUT_SECRET` env vars per stage. Pass-through cost: `GHOSTCUT_USD_PER_30S` (default 0.10).
+
+## Editor Chat
+
+`infra/lambda/editor-chat.ts` is a separate Lambda that streams AI-driven edits to the Trackpad Editor. Client opens an SSE stream to `/api/v1/editor-chat`, sends the current composition snapshot + user prompt + attachments, and receives:
+
+- assistant text
+- tool calls that map to the Editor Action API (`add_layer`, `set_layer_start`, ...)
+- token usage + billing events
+
+The chat model uses the **caller's provider keys**. No Vidfarm-owned model calls happen in this path.
+
+## Primitives
+
+Primitives are hosted operations that are NOT templates — they're reusable building blocks:
+
+- `create_image`, `edit_image`, `inpaint_image` — image generation
+- `create_html_image` — Remotion HTML → PNG
+- `remove_background` — RapidAPI-backed image background removal → durable PNG/WebP
+- `download_media_video` — social/media URL → durable MP4
+- `hyperframes_render` — composition HTML → MP4 (the render primitive publishing uses)
+- `brainstorm` — LLM brainstorm route
+
+Directors call primitives when they want a one-off asset before feeding it into a template. Templates call primitives internally as workflow steps. All primitives are metered against the caller's wallet.
+
+## Billing
+
+Billing is USD wallet-based, not credits. Every metered operation writes a `billing_event` record and debits the wallet in the same DynamoDB transaction. Stripe webhooks land on the billing Lambda, which validates the signature, marks the invoice as processed idempotently, and credits the wallet.
+
+Key mechanics:
+
+- Every wallet mutation carries a `tracer` (idempotency key)
+- Provider spend is passed through at cost — no markup on AI provider calls
+- Platform infrastructure (Remotion render, GhostCut, storage) has a small safety buffer applied
+- Failed jobs are refunded automatically when the failure is on the platform side
+
+The billing Lambda has its own custom domain because Stripe webhooks require a stable URL not tied to the main API.
+
+## Template model
+
+There are two kinds of things directors can fork:
+
+1. **Draft templates** (`/hyperframes/:slug`) — pre-decomposed compositions checked into the repo under `templates/vidfarm_template_XXXX/`. Each has a `composition.html`, `composition.json`, `template.config.json`, a `SKILL.md`, and a `src/` if it needs custom Remotion.
+2. **Submitted videos** — raw uploads from directors, decomposed on demand via auto-decompose.
+
+Templates are static. Compositions/forks are the mutable working copies.
+
+## Configuration and env
+
+Per-stage config is loaded via `.env.<stage>`. Critical variables:
+
+- `AWS_REGION`, AWS credentials
+- `VIDFARM_<STAGE>_PUBLIC_BASE_URL` — the API base
+- `VIDFARM_<STAGE>_ENCRYPTION_SECRET` — DynamoDB field encryption
+- `VIDFARM_<STAGE>_API_KEY_SALT` — API key hashing
+- `VIDFARM_<STAGE>_BOOTSTRAP_*` — initial admin user
+- `VIDFARM_<STAGE>_REMOTION_*` — shared Remotion Lambda ARN + region
+- `VIDFARM_<STAGE>_RESEND_*` — email
+- `VIDFARM_<STAGE>_SENTRY_*` — Sentry DSN
+- `GHOSTCUT_KEY`, `GHOSTCUT_SECRET` — GhostCut credentials
+- `RAPIDAPI_KEY` — shared RapidAPI credential used by the `video_download` and `image_remove_background` primitives. Same key is set in both `.env.staging` and `.env.production`.
+- Provider fallback keys for platform-owned features that don't have a caller yet (bootstrap only)
+
+Never commit `.env.staging` or `.env.production` — both are gitignored.
+
+## Deployment
+
+CDK stacks are under `infra/cdk/`:
+
+- `bin/vidfarm-serverless-staging.ts` → `lib/vidfarm-serverless-staging-stack.ts`
+- `bin/vidfarm-prod.ts` → `lib/vidfarm-prod-stack.ts`
+
+Deploy commands are in `package.json`:
+
+- `npm run cdk:synth:staging-serverless`
+- `npm run cdk:deploy:staging-serverless`
+- `npm run cdk:deploy:prod`
+
+Never call bare `cdk deploy`. Always go through the npm scripts so the correct `.env.<stage>` is loaded.
+
+Deploy order: **staging first**, then production. Never skip staging.
+
+## Migration scripts
+
+One-shot scripts under `scripts/`:
+
+- `migrate-sqlite-to-dynamodb.ts` — one-time, completed on 2026-06-22. Do not re-run.
+- `migrate-compositions-to-ownership-agnostic.ts` — moves forks from `compositions/users/<customerId>/forks/<forkId>/` to `compositions/forks/<forkId>/working/`. Idempotent. Must be run against each stage where the old layout ever existed.
+- `migrate-decomposition-to-composition.ts` — renames `decomposition.json` → `composition.json` in S3 for all forks + versions. Idempotent. Supports `--delete-old` for cleanup.
+- `copy-dynamodb-prod-to-staging.ts` — copies prod DynamoDB items into staging for testing. Excludes transient rows by default.
+
+Run migrations with `--dry-run` first. Always.
+
+## Directory reference
+
+Top-level:
+
+- `src/` — API server + all backend services
+- `demo/` — Trackpad Editor React app
+- `infra/` — CDK stacks and Lambda entry points
+- `templates/` — draft template sources
+- `auto-create-hyperframe-templates/` — extractor prompts / schemas for new template creation
+- `scripts/` — one-shot ops scripts and migration scripts
+- `data/` — local dev SQLite + storage (gitignored)
+- `.env.staging`, `.env.production` — stage config (gitignored)
+
+Legacy but still active:
+
+- `auto-create-templates/` — extractor prompts for the older template creation flow. Still consumed by `src/cli.ts` (`autocreate-template` command) and `demo/scripts/dev.mjs`. Migrate the CLI before deleting.
+- `src/account-pages-legacy.ts`, `src/dev-app-legacy.ts` — HTML-string page renderers wrapped by `.tsx` React shells (`account-pages.tsx`, `dev-app.tsx`). Still active.
+
+## Common failure modes
+
+- **Fork loads 404** — check ownership-agnostic migration ran; the fork may still be at the old `compositions/users/.../forks/` path.
+- **Publish stuck in RUNNING** — check the primitive Lambda's CloudWatch logs. Remotion asset preflight failures usually mean a broken media URL in composition.html.
+- **Smart decompose falls back to time-slice** — the caller has no provider keys, or all their keys returned errors. Check `provider_key_lease` records.
+- **GhostCut task hangs** — client shows `pending` forever. Check the fork's `ghostcut.json` and the GhostCut dashboard. There is currently no cancel UI; the poll times out at 15 minutes.
+- **Editor edits don't persist** — verify `PUT /composition.html` is 200. If the composition.html doesn't include `data-composition-id`, the API rejects the PUT at publish time.
+
+## Where to look for things
+
+- Composition endpoints — `src/app.ts` under `COMPOSITIONS_PREFIX` (~line 6970+)
+- Fork CRUD & permissions — `src/services/serverless-records.ts`, `src/services/fork-access.ts`
+- Storage keys — `src/services/storage.ts`
+- Composition runtime script — `src/composition-runtime.ts`
+- Trackpad Editor — `demo/src/HyperframesStudioEditor.tsx`
+- Auto-decompose logic — `src/hyperframes/composition.ts` (time-slice), `src/services/hyperframes.ts` (smart)
+- Publish flow — `src/app.ts` `publishCompositionToRenderer()`
+- Ghostcut — `src/services/ghostcut.ts`
+- CDK stack — `infra/cdk/lib/vidfarm-serverless-staging-stack.ts`, `infra/cdk/lib/vidfarm-prod-stack.ts`
+- Lambdas — `infra/lambda/*.ts`

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

@@ -0,0 +1,275 @@
+# 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