@amg555/frameforge-mcp 2.3.2 → 2.3.4

package/plugins/video-pipeline/skills/html-renderer/SKILL.md

@@ -0,0 +1,292 @@
+---
+name: html-renderer
+description: |
+  HTML-as-compositor renderer for FrameForge. Every video frame is a pure
+  function of time rendered by a headless browser (Playwright + Chromium)
+  and encoded by FFmpeg. Produces exact, pixel-perfect animation — React
+  component quality without a React runtime. Use this as an alternative to
+  FFmpeg-only zoompan when richer motion graphics are required: kinetic text,
+  morphing layouts, spring-physics, counters, progress rings, captions
+  synced to audio, and any CSS/SVG animation. Pairs with the FrameForge
+  pipeline: script JSON → HTML compositor → frame PNGs → FFmpeg encode.
+  Compatible with IBM Bob, Kiro, Cursor, Windsurf, Claude Code, and any
+  agentic IDE connected via MCP. Activate when the user asks for richer
+  animation, Remotion-style rendering, HTML-based video, or "make it look
+  like the reference repo".
+---
+
+# HTML Renderer — FrameForge Extension
+
+Renders video frames as HTML pages (one page = one frame clock) using
+Playwright for screenshot capture and FFmpeg for final encoding.
+
+Built on deterministic `seek(t)` — every style is a pure function of time `t`.
+No CSS transitions, no `setTimeout`, no frame state that depends on the
+previous frame (Playwright renders frames out of order for parallelism).
+
+---
+
+## When to use this renderer
+
+| Use FFmpeg zoompan (default)       | Use HTML renderer (this skill)       |
+|------------------------------------|--------------------------------------|
+| Batch overnight — speed matters    | Animation quality is the priority    |
+| Simple Ken-Burns + captions        | Kinetic text, counters, data charts  |
+| CI/server with no browser          | Morphing layouts, spring physics     |
+| < 5 min render time required       | Creator wants Remotion-style output  |
+| Raspberry Pi / low-RAM machine     | macOS/Linux with 4GB+ free RAM       |
+
+---
+
+## Requirements
+
+- Node.js 18+, FFmpeg, `npx playwright install chromium`
+- macOS or Linux recommended (Windows: WSL2)
+- 4 GB+ free RAM (Playwright renders up to 6 subframes per output frame in
+  parallel for motion blur)
+- `uv` (Python) for audio processing scripts: `pip install uv` or
+  `curl -LsSf https://astral.sh/uv/install.sh | sh`
+
+---
+
+## Setup
+
+```bash
+# Install Playwright chromium (one-time)
+npx playwright install chromium
+
+# Scaffold a new HTML-renderer project from a FrameForge script JSON
+node <frameforge-root>/scripts/html-renderer/new-project.mjs \
+  --script output/<productionId>-script.json \
+  --out    output/<productionId>-html/
+```
+
+The scaffold copies `index.html` (compositor), starter `edit.js`, the
+`reel/engine.js` runtime, and all render scripts into the project folder.
+
+---
+
+## Core concept: `seek(t)`
+
+```js
+// edit.js — every element style is computed from t (seconds)
+import { reel, faceAt, layer, text, at, captions } from './reel/engine.js';
+
+reel({ width: 1920, height: 1080, fps: 30, duration: 65 });
+
+// Title card: fades in at t=0, stays for 3s
+layer('hook').on(t => ({
+  opacity: t < 0.3 ? t / 0.3 : t > 2.7 ? (3 - t) / 0.3 : 1,
+}));
+
+at(0, text('Why Ancient Humans Started Cooking', {
+  font: '72px/1.2 "Archivo"', color: '#fff',
+  x: 'center', y: 200,
+}));
+
+// Caption synced to FrameForge TTS audio
+captions('audio/outline.txt');  // generated by transcribe.py
+```
+
+**Iron rule:** Every style must be a pure function of `t`. If a layer is
+active during frames 5–15 s and you `return` early for t > 15, it must
+explicitly reset every property it drove — otherwise the last frame's value
+sticks on all later frames.
+
+---
+
+## Workflow (integrates with FrameForge pipeline)
+
+### Step 1: Run FrameForge dry-run to get script JSON
+
+```bash
+npm run make -- --topic "Your Topic" --dry-run --out-dir output/my-topic
+# Produces: output/my-topic/<productionId>-script.json
+```
+
+### Step 2: Scaffold the HTML compositor project
+
+```bash
+node scripts/html-renderer/new-project.mjs \
+  --script output/my-topic/<productionId>-script.json \
+  --out    output/my-topic/html-render/
+```
+
+The scaffolder reads each scene's `narration`, `caption`,
+`visual_description`, `camera_hint`, and `music_mood` from the script JSON
+and generates a starter `edit.js` with one `layer()` per scene, timed to
+the expected narration duration (estimated at 2.5 words/second).
+
+### Step 3: Gather assets (optional)
+
+```bash
+# Stock footage
+uv run scripts/stock.py video "ancient cooking fire" --portrait
+
+# Website screenshot as b-roll
+node scripts/capture.mjs site https://example.com broll-site
+
+# X post card
+node scripts/capture.mjs tweet https://x.com/... post-card
+```
+
+### Step 4: Check visually before full render
+
+```bash
+# Contact sheet — one frame every 0.5s
+node scripts/render.mjs sheet
+
+# Specific timestamps
+node scripts/render.mjs stills 0 5.5 12 28 45 60
+```
+
+### Step 5: Mix audio
+
+```bash
+uv run scripts/mix_audio.py
+# Reads FrameForge TTS outputs, applies -14 LUFS, writes out/audio_mix.m4a
+```
+
+### Step 6: Full render + verify
+
+```bash
+node scripts/render.mjs full
+uv run scripts/verify.py
+```
+
+Output: `out/<name>.mp4` (1920x1080 or 1080x1920 for Shorts), verified
+against the same FrameForge quality gates (resolution, codec, LUFS, A/V sync).
+
+### Step 7: Re-inject into FrameForge pipeline
+
+The rendered MP4 can be injected back into FrameForge via `video_path`:
+
+```json
+{
+  "scene_id": 1,
+  "video_path": "output/my-topic/html-render/out/video.mp4"
+}
+```
+
+Or pass it directly to `publish_video` via MCP:
+
+```
+publish_video(productionId, masterPath="output/my-topic/html-render/out/video.mp4", channels=["file","webhook"])
+```
+
+---
+
+## Engine API quick reference
+
+| Function | What it does |
+|---|---|
+| `reel({ width, height, fps, duration })` | Configure the compositor |
+| `layer('name').on(t => styles)` | Declare a layer; styles recomputed every frame |
+| `at(t, element)` | Place element at time t |
+| `stagger(t, dt, elements[])` | Place elements with dt spacing |
+| `text(str, opts)` | Animated text with font/color/position |
+| `chip(str, opts)` | Pill-shaped label (tags, captions) |
+| `wallCard(lines[], opts)` | Frosted-glass card over background |
+| `imageCard(src, opts)` | Image with optional caption overlay |
+| `browserCard(url, opts)` | Screenshot-as-card |
+| `terminal(lines[], opts)` | Animated terminal output |
+| `stamp(str, opts)` | Bold diagonal stamp (VERIFIED, SOURCE, etc.) |
+| `codeCard(code, lang, opts)` | Syntax-highlighted code block |
+| `captions(outlinePath)` | Auto-sync captions from whisper outline |
+| `cuePhrase(phrase, offset)` | Word-level trigger with fail-fast transcript check |
+| `cue(sfxName, t, vol)` | Trigger sound effect at time t |
+| `faceAt(layout, t)` | Position talking-head face (FULL, SPLIT, PIP) |
+| `hash(i)` | Deterministic PRNG float [0, 1) for index i |
+| `boilSeed(key, t)` | Deterministic stepped float [0, 1) in 1/12s window |
+| `kf(t, keys, ease)` | Keyframe interpolation with easing curves |
+| `onTwos(t)` | Quantize time to 12 fps (traditional animation on twos) |
+| `seg(t, a, b)` | Clamp t into [0, 1] interval progress |
+| `pulse(t, k)` | Exponential impulse peak at t=0, decaying with rate k |
+| `shots(timeline)` | Time-ordered shot registry fn(t, lt, dur) for parallel render |
+| `on(t => ...)` | Raw per-frame compute (for custom animations) |
+
+---
+
+## Storyboard Gates, Purity Verification & Review Modes
+
+```bash
+# 1. Diagnostic & Setup checks
+node scripts/harness.mjs doctor        # Verify Chrome, GPU flags (D3D11/Metal), WebGL context
+node scripts/look.mjs                  # Pre-render linter (fonts, clipping, NaN transforms)
+
+# 2. Purity verification gate (3-point repeat, wander, cold-jump test)
+node scripts/harness.mjs verify        # Must pass a===b and a===c across 9 sampled timestamps
+
+# 3. Gate stills & review commands
+node scripts/harness.mjs storyboard    # 4 keyframes (0%, 33%, 66%, 100%) or validate STORYBOARD.md
+node scripts/harness.mjs sheet         # Contact sheet (0.5s interval)
+node scripts/harness.mjs strip 1.0 1.5 # Horizontal frame strip (motion check)
+node scripts/harness.mjs crop 9:16     # Focal-point mobile crop preview
+node scripts/harness.mjs pixels        # Blind-spot frame analysis (blank, blown, corner-confined)
+
+# 4. Master render & encode
+node scripts/harness.mjs frames        # Resumable atomic frame render (.tmp + renameSync)
+node scripts/harness.mjs encode        # BT.709 color-tagged master encode + audio mux
+node scripts/harness.mjs all           # Complete gate-checked end-to-end production
+node scripts/render.mjs mux            # Re-mux audio only (no re-render)
+node scripts/render.mjs kit            # Editor kit (Premiere/Resolve XML)
+```
+
+Full render uses 6-page parallel Playwright pool (motion blur subframes).
+Long videos render in 60s resumable chunks — re-run to continue after crash.
+
+---
+
+## Gotchas
+
+- **Pure functions of t.** No CSS transitions, `setTimeout`, or state that
+  depends on previous frames. Playwright seeks out of order.
+- **Every style must reset.** If a layer returns early after t > 15s, it
+  must explicitly set opacity/display/visibility to 0/none/hidden — or the
+  last rendered value bleeds onto all later frames.
+- **HDR iPhone footage** needs tonemapping before compositing
+  (`uv run scripts/assemble.py` does this automatically).
+- **Motion blur needs 6 subframes.** Fewer subframes show fast morphs as
+  ghost copies. Default is 6 (180° shutter), a 60s video takes ~4 min.
+- **Measure text after fonts load.** Components that need widths (strike-
+  through, underline) measure lazily on first `seek()`.
+- **Captions over the mouth.** Use `REEL.captionY` per layout to move them
+  to the seam in split-screen mode.
+
+---
+
+## IBM Bob integration
+
+This skill works inside IBM Bob as a `~/.bob/skills/html-renderer/` skill.
+
+```bash
+# Install
+cp -r plugins/video-pipeline/skills/html-renderer/ ~/.bob/skills/html-renderer/
+
+# Bob will pick it up automatically — ask:
+# "use the html-renderer skill to animate my FrameForge script"
+```
+
+The skill pairs with the existing `video-pipeline` skill: use
+`video-pipeline` for research/script/TTS/publish and `html-renderer` for
+the animation/render stage.
+
+---
+
+## Files this skill adds
+
+```
+plugins/video-pipeline/skills/html-renderer/
+  SKILL.md                    ← this file
+  references/engine-api.md    ← full engine function reference
+  references/design.md        ← layouts, safe zones, type scale, pacing
+  assets/project/             ← template copied into each render project
+    index.html                ← compositor page (loads engine.js)
+    edit.js                   ← starter edit (one layer per FrameForge scene)
+    reel/engine.js            ← springs, layouts, components, captions, seek API
+    reel/engine.css           ← default fonts + base reset
+    scripts/                  ← render.mjs, mix_audio.py, verify.py, stock.py,
+                                 capture.mjs, transcribe.py, new-project.mjs
+scripts/html-renderer/
+  new-project.mjs             ← scaffolds a render project from script JSON
+```

package/plugins/video-pipeline/skills/video-pipeline/SKILL.md

@@ -0,0 +1,308 @@
+---
+name: video-pipeline
+description: >
+  Autonomous AI video production pipeline. Given a topic, this skill
+  researches, fact-checks, writes the script, synthesises voice, renders
+  with FFmpeg, runs quality gates, and saves the output locally or POSTs
+  to any webhook — all without human intervention.
+  Works in IBM Bob, Codex, opencode, Cursor, Windsurf, Claude Code,
+  or any IDE that loads skills from ~/.claude/skills/ or .claude/skills/.
+  Trigger phrases: "make a video about", "produce a reel on", "overnight
+  batch", "queue videos", "generate video", "run the pipeline", "publish
+  video". Also activates when a user pastes a topic list and says
+  "make these" or "do the batch".
+---
+
+# Video Pipeline Skill
+
+End-to-end autonomous video production. The AI proposes every creative
+decision; deterministic systems (FFmpeg, TTS, image gen, MCP) execute them;
+a quality gate blocks bad output before delivery.
+
+## Architecture
+
+```
+IDE Agent (IBM Bob / Codex / opencode / Cursor / Windsurf / Claude Code)
+    │
+    ▼  Cloudflare Remote MCP (recommended) ─────────────────────────────
+    │  https://video-mcp.YOUR_SUBDOMAIN.workers.dev/mcp
+    │  17 tools: create_video_from_script · render_from_scenes
+    │            ingest_media · edit_scenes · render_tts · multi_voice_tts
+    │            generate_scene_image · assemble_video · publish_video
+    │            research_topic · write_script · external_platform_call
+    │            queue_full_pipeline · get_job_status
+    │            scaffold_animation_project · validate_storyboard · render_animation
+    │
+    ▼  OR — Local stdio / HTTP MCP ────────────────────────────────────
+    │  node src/mcp-server/stdio.js   (stdio)
+    │  node src/mcp-server/server.js  (HTTP :3210)
+    │
+    ▼  Execution layer
+    │  LLM provider:   PROVIDER_LLM=groq|openrouter|anthropic|gemini
+    │                              |mistral|together|cerebras|openai
+    │                              |ollama|webhook
+    │  TTS provider:   PROVIDER_TTS=edge-tts|voxforge|elevenlabs|azure|openai|webhook
+    │  Visuals:        Code-driven animations (default) + user media (video_path / image_path)
+    │
+    ▼  Optional: queue_full_pipeline
+       queue_full_pipeline MCP tool → POST job to worker API (WORKER_API_URL)
+```
+
+All secrets come from environment variables — **never** hardcoded.
+See `docs/env.template` for the full reference.
+
+---
+
+## Setup
+
+### Option A — Cloudflare Remote MCP (Recommended)
+
+Deploy once; works in every IDE with no local server process:
+
+```bash
+cd cloudflare-mcp
+npm install
+wrangler secret put WORKER_API_URL     # https://your-render-app.onrender.com
+wrangler secret put MCP_AUTH_TOKEN     # random 32-byte hex
+wrangler secret put INTERNAL_API_TOKEN # shared secret with render node
+wrangler deploy
+```
+
+Add to any IDE's MCP config:
+
+```json
+{
+  "mcpServers": {
+    "frameforge": {
+      "url": "https://video-mcp.YOUR_SUBDOMAIN.workers.dev/mcp",
+      "headers": { "Authorization": "Bearer YOUR_MCP_AUTH_TOKEN" }
+    }
+  }
+}
+```
+
+### Option B — Local stdio MCP
+
+**IBM Bob** (`~/.bob/mcp.json`):
+```json
+{
+  "mcpServers": {
+    "frameforge": {
+      "command": "node",
+      "args": ["<absolute-path>/src/mcp-server/stdio.js"],
+      "env": { "PROVIDER_LLM": "groq", "GROQ_API_KEY": "gsk_..." }
+    }
+  }
+}
+```
+
+**Codex / opencode / Cursor / Windsurf / Claude Code** (`~/.claude/mcp.json` or `.mcp.json`):
+```json
+{
+  "mcpServers": {
+    "frameforge": {
+      "command": "node",
+      "args": ["<absolute-path>/src/mcp-server/stdio.js"],
+      "env": { "PROVIDER_LLM": "groq", "GROQ_API_KEY": "${GROQ_API_KEY}" }
+    }
+  }
+}
+```
+
+### 2. Set environment variables
+
+Copy `docs/env.template` → `.env` and fill in. Minimum:
+
+```bash
+# LLM (pick one — Groq is free with no credit card)
+PROVIDER_LLM=groq
+GROQ_API_KEY=gsk_...
+
+# TTS (edge-tts is free offline)
+PROVIDER_TTS=edge-tts
+
+# Visuals are 100% code-driven (kinetic typography/motion graphics) + user media. No image key needed.
+
+# Delivery (optional — default is 'file' which copies to N8N_FILES_DIR/published/)
+# PUBLISH_WEBHOOK_URL=https://hooks.example.com/frameforge
+# REVIEW_NOTIFY_URL=https://hooks.example.com/review-gate
+```
+
+Run the interactive wizard for guided setup:
+```bash
+npm run setup
+```
+
+---
+
+## Workflow (step-by-step)
+
+### Path 1 — Agent-First (FFmpeg + AI images)
+
+**You are already running an LLM — use it.** Write the scenes yourself and hand
+them to FrameForge for rendering. No `GROQ_API_KEY` or any other LLM key needed.
+FrameForge only runs FFmpeg, TTS, and image generation:
+
+```
+create_video_from_script({
+  scenes: [
+    { narration: "WiFi sends data as radio waves...", caption: "RADIO WAVES",
+      visual_description: "router emitting waves, flat illustration" },
+    { narration: "Your device picks up the signal...", caption: "YOUR DEVICE",
+      visual_description: "laptop receiving signal, clean diagram" }
+  ],
+  title: "How WiFi Works"
+})
+```
+
+Then deliver it:
+```
+publish_video({ productionId, masterPath, channels: ["file"] })
+```
+
+> **Image generation fallback:** If the configured image provider is unavailable, FrameForge automatically falls back to a dark-background placeholder per scene — the render completes. Switch to `PROVIDER_IMAGE=falai` for a more reliable free provider.
+
+### Path 2 — Code-Driven Animated Video (Playwright + ffmpeg, no AI images)
+
+Use when: the user wants Remotion-style motion graphics, image gen is unavailable, or they ask for "animated video" or "make it look good". Every pixel is a pure function of time `t`.
+
+> **Beat sheet gate:** Reply with a beat sheet and 4 keyframe descriptions first. Stop. Wait for approval before writing any scene code.
+
+```
+// 1. Synthesise voice first — audio timing is ground truth
+multi_voice_tts({ text: "Narration.", outputPath: ".frameforge-files/voice_0.m4a" })
+
+// 2. Scaffold the compositor project (copies engine + all render scripts + briefings)
+scaffold_animation_project({
+  outDir: ".frameforge-files/my-anim/",
+  scenes: [ { narration: "...", caption: "...", visual_description: "..." } ],
+  audioPath: ".frameforge-files/voice_0.m4a"
+})
+// → returns nextSteps[] — read ANIMATION_GUIDE.md and edit STORYBOARD.md next
+
+// 3. Validate storyboard (four hard gates — must pass before scene code)
+validate_storyboard({ storyboardPath: ".frameforge-files/my-anim/STORYBOARD.md" })
+
+// 4. Write real animation in edit.js (pure functions of t — read ANIMATION_GUIDE.md)
+
+// 5. Pre-flight linter & purity verification (3-point repeat, wander, cold-jump)
+render_animation({ projectDir: ".frameforge-files/my-anim/", mode: "look" })
+render_animation({ projectDir: ".frameforge-files/my-anim/", mode: "verify" })
+
+// 6. Review stills (at least one sheet per shot, one strip per key motion)
+render_animation({ projectDir: ".frameforge-files/my-anim/", mode: "sheet" })
+render_animation({ projectDir: ".frameforge-files/my-anim/", mode: "strip",
+                   timestamps: [2.1, 2.6] })   // every frame of one motion
+render_animation({ projectDir: ".frameforge-files/my-anim/", mode: "crop",
+                   timestamps: ["9:16", 3.0] })  // mobile crop check
+
+// 7. Full render (only after stills pass)
+render_animation({ projectDir: ".frameforge-files/my-anim/", mode: "full",
+                   audioPath: ".frameforge-files/voice_0.m4a" })
+```
+
+Requires one-time: `cd <outDir> && npm install playwright && npx playwright install chromium`
+
+### Path 3 — Auto-Research (for unattended / batch runs)
+
+Use this when FrameForge runs **without** an IDE in the loop — overnight batch,
+`queue_full_pipeline`, or a standalone worker. The pipeline calls its own LLM
+for research and scripting, so `PROVIDER_LLM` + the matching API key are required:
+
+```
+1. research_topic({ topic: "...", style: "educational", format: "short-form reel" })
+2. write_script({ productionId, claims, topic, persona: "tech reviewer" })
+3. render_from_scenes({ productionId })
+4. publish_video({ productionId, masterPath, channels: ["file"] })
+```
+
+### Voice Synthesis (per call)
+
+```
+multi_voice_tts({
+  text: "Narration text here",
+  outputPath: "/path/in/files-dir/voice_0.m4a",
+  platform: "elevenlabs",
+  voice: "your_cloned_voice_id",
+  apiKey: "sk_..."
+})
+```
+
+### Overnight batch
+
+```
+I'm going to sleep. Make as many videos as you can before 9 AM.
+Topics (queue them all):
+  1. How does GPS actually work?
+  2. Why planes don't fly over the Pacific in a straight line
+  3. The engineering inside a modern CPU
+
+Rules:
+- Strong hook, double-verify every fact.
+- After each video: run the quality gate, then publish to the output directory.
+- Leave me a summary when done.
+```
+
+The skill calls MCP tools sequentially using the StateMachine to track progress.
+If a stage fails it retries with exponential backoff; if it fails terminally it
+marks that production FAILED and moves to the next topic.
+
+---
+
+## Provider reference
+
+| Role  | Provider     | Key env var               | Notes                          |
+|-------|-------------|--------------------------|-------------------------------|
+| LLM   | groq        | `GROQ_API_KEY`            | Default. Fast, free tier.      |
+| LLM   | openrouter  | `OPENROUTER_API_KEY`      | Any model via one key          |
+| LLM   | anthropic   | `ANTHROPIC_API_KEY`       | Claude Sonnet/Haiku/Opus       |
+| LLM   | gemini      | `GEMINI_API_KEY`          | Gemini 2.0 Flash / 2.5 Pro     |
+| LLM   | cerebras    | `CEREBRAS_API_KEY`        | 2000+ tok/s Llama              |
+| LLM   | openai      | `OPENAI_API_KEY`          | GPT-4o / o1                    |
+| LLM   | ollama      | _(none)_                  | Local, OLLAMA_BASE_URL         |
+| TTS   | edge-tts    | _(none)_                  | Free, offline, 300+ voices     |
+| TTS   | elevenlabs  | `ELEVENLABS_API_KEY`      | Voice cloning                  |
+| TTS   | azure       | `AZURE_SPEECH_KEY`        | Enterprise                     |
+| TTS   | openai      | `OPENAI_API_KEY`          | High quality                   |
+| Visual| code-driven | _(none)_                  | Default — kinetic cards & typography |
+| Visual| user-media  | _(none)_                  | Caller `image_path` / `video_path`   |
+
+---
+
+## Quality gates (hard — will block delivery)
+
+| Gate                | Threshold            |
+|---------------------|----------------------|
+| File size           | > 1 MB               |
+| Video stream        | present              |
+| Resolution (master) | 1920×1080            |
+| Resolution (short)  | 1080×1920            |
+| Codec               | H.264                |
+| Pixel format        | yuv420p              |
+| Frame rate          | 24–30 fps            |
+| Integrated loudness | −14 ±1.5 LUFS        |
+| True peak           | ≤ −0.5 dBTP          |
+| Black frames        | none > 0.5 s         |
+| Frozen frames       | none > 0.5 s         |
+
+---
+
+## Key files
+
+```
+src/mcp-server/server.js          MCP HTTP server (17 tools, port 3210)
+src/mcp-server/stdio.js           MCP stdio server (17 tools)
+cloudflare-mcp/src/index.js       Cloudflare Workers Remote MCP proxy
+src/pipeline/providers.js         LLM / TTS / Image abstraction (env-var-switchable providers)
+src/pipeline/state-machine.js     File + PostgreSQL production state
+src/pipeline/retry-policy.js      Exponential backoff, stage timeouts
+src/pipeline/telemetry.js         NDJSON cost tracking
+src/quality-gate/gate.js          9 hard gates
+src/audio-mixer/mixer.js          Sidechain ducking, LUFS normalisation
+src/shorts-extractor/extractor.js Silence-based 9:16 crop for Shorts
+src/fact-checker/checker.js       Claim risk classification + evidence gates
+src/video-renderer/renderer.js    Scene render + master assembly
+src/worker/server-render-free.js  Render-optimised worker API (Render free)
+src/worker/server.js              Full worker API
+docs/env.template                 Environment variable reference
+```