reel-studio 0.0.0-stage → 0.2.0

package/core/lib/runtime.js

@@ -0,0 +1,126 @@
+/* Composition runtime: one clock for every engine.
+ *
+ * A composition is an HTML page that:
+ *   1. loads /core/node_modules/gsap/dist/gsap.min.js, /core/lib/base.css and this file
+ *   2. calls Studio.setup({ width, height, fps, duration })
+ *   3. builds its motion on Studio.tl (a paused GSAP timeline), in seconds
+ *   4. registers anything else that moves with Studio.onSeek(fn): fn(t) draws
+ *      that layer at time t (it may return a promise). Engine adapters in
+ *      /engines/ do this for you (Lottie, Three.js, Pixi, <video>).
+ *   5. registers anything that must load first with Studio.wait(promise)
+ *
+ * The renderer calls window.__seek(t) for every frame and screenshots it, so
+ * every frame is deterministic. Avoid CSS animations/transitions, setTimeout,
+ * requestAnimationFrame loops and Math.random() (use Studio.random(seed)).
+ *
+ * Preview in a browser (served from the repo root):
+ *   .../composition/index.html          plays live, loops
+ *   .../composition/index.html?t=2.5    freezes at 2.5 s
+ *   .../composition/index.html?safe=1   shows the safe-zone overlay
+ */
+(function () {
+  const params = new URLSearchParams(location.search);
+  const hooks = [];
+  const pending = [];
+
+  const Studio = {
+    meta: null,
+    tl: null,
+    params,
+
+    setup({ width = 1080, height = 1920, fps = 30, duration }) {
+      if (!duration) throw new Error("Studio.setup needs a duration (seconds)");
+      this.meta = { width, height, fps, duration };
+      const stage = document.getElementById("stage");
+      stage.style.width = width + "px";
+      stage.style.height = height + "px";
+      this.tl = gsap.timeline({ paused: true });
+      // Make sure the timeline is exactly `duration` long.
+      this.tl.set({}, {}, duration);
+      if (params.get("safe") === "1") document.documentElement.classList.add("show-safe");
+      return this.tl;
+    },
+
+    /** Draw a layer at time t on every seek. Hooks run in registration order. */
+    onSeek(fn) { hooks.push(fn); return fn; },
+
+    /** Hold the first frame until this promise settles (assets, engine init). */
+    wait(promise) { pending.push(promise); return promise; },
+
+    /** Seeded PRNG (mulberry32): same seed, same numbers, every render. */
+    random(seed = 1) {
+      let a = seed >>> 0;
+      return () => {
+        a = (a + 0x6d2b79f5) >>> 0;
+        let t = a;
+        t = Math.imul(t ^ (t >>> 15), t | 1);
+        t ^= t + Math.imul(t ^ (t >>> 7), t | 61);
+        return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+      };
+    },
+
+    /** Register a Lottie animation (needs lottie.min.js). `start` = second it begins. */
+    lottie(el, path, { start = 0, loop = false, speed = 1 } = {}) {
+      const anim = lottie.loadAnimation({ container: el, renderer: "svg", loop: false, autoplay: false, path });
+      this.wait(new Promise((res) => anim.addEventListener("DOMLoaded", res)));
+      this.onSeek((t) => {
+        const total = anim.totalFrames;
+        let f = Math.max(0, (t - start) * anim.frameRate * speed);
+        f = loop ? f % total : Math.min(f, total - 1);
+        anim.goToAndStop(f, true);
+      });
+      return anim;
+    },
+
+    /** Register a <video> element (a pre-rendered plate: Blender, a capture, footage). */
+    video(el, { start = 0 } = {}) {
+      el.muted = true; el.preload = "auto"; el.pause();
+      this.wait(new Promise((res, rej) => {
+        // A missing or broken plate fails the render instead of hanging it (the error may have fired already)
+        const fail = () => rej(new Error(`Video plate failed to load: ${el.currentSrc || el.src}`));
+        if (el.readyState >= 2) return res();
+        if (el.error || el.networkState === HTMLMediaElement.NETWORK_NO_SOURCE) return fail();
+        el.addEventListener("loadeddata", res, { once: true });
+        el.addEventListener("error", fail, { once: true });
+      }));
+      this.onSeek((t) => new Promise((res) => {
+        const target = Math.max(0, Math.min(t - start, (el.duration || 0) - 0.001));
+        if (Math.abs(el.currentTime - target) < 0.0005) return res();
+        el.addEventListener("seeked", res, { once: true });
+        el.currentTime = target;
+      }));
+      return el;
+    },
+  };
+
+  async function seek(t) {
+    Studio.tl.seek(t, false);
+    for (const fn of hooks) await fn(t);
+  }
+
+  window.Studio = Studio;
+  window.__seek = seek;
+  window.__meta = () => Studio.meta;
+  window.__ready = (async () => {
+    await new Promise((r) => (document.readyState === "complete" ? r() : addEventListener("load", r)));
+    await document.fonts.ready;
+    // Module scripts may register more work while earlier work loads: wait until it settles.
+    for (let n = 0; n < pending.length; n = pending.length) await Promise.all(pending.slice(n));
+    await Promise.all([...document.images].map((img) => (img.complete ? null : new Promise((r) => (img.onload = img.onerror = r)))));
+    if (!Studio.meta) throw new Error("Composition never called Studio.setup()");
+    return true;
+  })();
+
+  // Browser preview: freeze at ?t=, otherwise play in a loop. The renderer passes ?render=1.
+  window.__ready.then(() => {
+    if (params.get("render") === "1") return;
+    if (params.has("t")) return seek(parseFloat(params.get("t")));
+    const t0 = performance.now();
+    let busy = false;
+    const loop = async () => {
+      if (!busy) { busy = true; await seek(((performance.now() - t0) / 1000) % Studio.meta.duration); busy = false; }
+      requestAnimationFrame(loop);
+    };
+    loop();
+  });
+})();

package/core/package-lock.json

@@ -0,0 +1,148 @@
+{
+  "name": "reel-studio-core",
+  "lockfileVersion": 3,
+  "requires": true,
+  "packages": {
+    "": {
+      "name": "reel-studio-core",
+      "dependencies": {
+        "gsap": "^3.12.5",
+        "lottie-web": "^5.12.2",
+        "pixi.js": "^8.6.0",
+        "playwright-core": "1.49.1",
+        "three": "^0.170.0"
+      }
+    },
+    "node_modules/@pixi/colord": {
+      "version": "2.9.6",
+      "resolved": "https://registry.npmjs.org/@pixi/colord/-/colord-2.9.6.tgz",
+      "integrity": "sha512-nezytU2pw587fQstUu1AsJZDVEynjskwOL+kibwcdxsMBFqPsFFNA7xl0ii/gXuDi6M0xj3mfRJj8pBSc2jCfA==",
+      "license": "MIT"
+    },
+    "node_modules/@types/earcut": {
+      "version": "3.0.0",
+      "resolved": "https://registry.npmjs.org/@types/earcut/-/earcut-3.0.0.tgz",
+      "integrity": "sha512-k/9fOUGO39yd2sCjrbAJvGDEQvRwRnQIZlBz43roGwUZo5SHAmyVvSFyaVVZkicRVCaDXPKlbxrUcBuJoSWunQ==",
+      "license": "MIT"
+    },
+    "node_modules/@webgpu/types": {
+      "version": "0.1.74",
+      "resolved": "https://registry.npmjs.org/@webgpu/types/-/types-0.1.74.tgz",
+      "integrity": "sha512-lgiI4hbuLcI9unnm2cL/tvCaQU45dp0xcLWJh5uB/9MBGvIA4F8XIk7nSiBeg+K4xWGYwgZKn80LmERI5CxoTA==",
+      "license": "BSD-3-Clause"
+    },
+    "node_modules/@xmldom/xmldom": {
+      "version": "0.8.15",
+      "resolved": "https://registry.npmjs.org/@xmldom/xmldom/-/xmldom-0.8.15.tgz",
+      "integrity": "sha512-/5NV/vDALVFDXgLmfsy9TRCBlKwO2LNBFzpzvb9iIj+jR+eSc6DLYYvVOdivT/jm7MtU6TebYuRmzEOI7w40UA==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=10.0.0"
+      }
+    },
+    "node_modules/earcut": {
+      "version": "3.2.4",
+      "resolved": "https://registry.npmjs.org/earcut/-/earcut-3.2.4.tgz",
+      "integrity": "sha512-FHc6yNpnTORB0tM5kmZ03iD2mDuNakDE2lvf4Hw1XkfxtEHIGVi01B/GqUSwx+NcC1WGjidAfpTXzeALtPtfpg==",
+      "license": "ISC"
+    },
+    "node_modules/eventemitter3": {
+      "version": "5.0.4",
+      "resolved": "https://registry.npmjs.org/eventemitter3/-/eventemitter3-5.0.4.tgz",
+      "integrity": "sha512-mlsTRyGaPBjPedk6Bvw+aqbsXDtoAyAzm5MO7JgU+yVRyMQ5O8bD4Kcci7BS85f93veegeCPkL8R4GLClnjLFw==",
+      "license": "MIT"
+    },
+    "node_modules/gifuct-js": {
+      "version": "2.1.2",
+      "resolved": "https://registry.npmjs.org/gifuct-js/-/gifuct-js-2.1.2.tgz",
+      "integrity": "sha512-rI2asw77u0mGgwhV3qA+OEgYqaDn5UNqgs+Bx0FGwSpuqfYn+Ir6RQY5ENNQ8SbIiG/m5gVa7CD5RriO4f4Lsg==",
+      "license": "MIT",
+      "dependencies": {
+        "js-binary-schema-parser": "^2.0.3"
+      }
+    },
+    "node_modules/gsap": {
+      "version": "3.15.0",
+      "resolved": "https://registry.npmjs.org/gsap/-/gsap-3.15.0.tgz",
+      "integrity": "sha512-dMW4CWBTUK1AEEDeZc1g4xpPGIrSf9fJF960qbTZmN/QwZIWY5wgliS6JWl9/25fpTGJrMRtSjGtOmPnfjZB+A==",
+      "license": "Standard 'no charge' license: https://gsap.com/standard-license."
+    },
+    "node_modules/ismobilejs": {
+      "version": "1.1.1",
+      "resolved": "https://registry.npmjs.org/ismobilejs/-/ismobilejs-1.1.1.tgz",
+      "integrity": "sha512-VaFW53yt8QO61k2WJui0dHf4SlL8lxBofUuUmwBo0ljPk0Drz2TiuDW4jo3wDcv41qy/SxrJ+VAzJ/qYqsmzRw==",
+      "license": "MIT"
+    },
+    "node_modules/js-binary-schema-parser": {
+      "version": "2.0.3",
+      "resolved": "https://registry.npmjs.org/js-binary-schema-parser/-/js-binary-schema-parser-2.0.3.tgz",
+      "integrity": "sha512-xezGJmOb4lk/M1ZZLTR/jaBHQ4gG/lqQnJqdIv4721DMggsa1bDVlHXNeHYogaIEHD9vCRv0fcL4hMA+Coarkg==",
+      "license": "MIT"
+    },
+    "node_modules/lottie-web": {
+      "version": "5.13.0",
+      "resolved": "https://registry.npmjs.org/lottie-web/-/lottie-web-5.13.0.tgz",
+      "integrity": "sha512-+gfBXl6sxXMPe8tKQm7qzLnUy5DUPJPKIyRHwtpCpyUEYjHYRJC/5gjUvdkuO2c3JllrPtHXH5UJJK8LRYl5yQ==",
+      "license": "MIT"
+    },
+    "node_modules/parse-svg-path": {
+      "version": "0.2.0",
+      "resolved": "https://registry.npmjs.org/parse-svg-path/-/parse-svg-path-0.2.0.tgz",
+      "integrity": "sha512-Tf7FFIrguPKQwzD4pWnYkR2VOv3raoHeKED80Bm+BYHI3KxC8KsgsGC5+fSMzAGDA6UEk4bHvmi+RsjmL3khpg==",
+      "license": "MIT"
+    },
+    "node_modules/pixi.js": {
+      "version": "8.22.0",
+      "resolved": "https://registry.npmjs.org/pixi.js/-/pixi.js-8.22.0.tgz",
+      "integrity": "sha512-QbTANHMZ751MIjLiLSUSM8a7LNMWwMIf0KbRCqlW+SPS9hNLfSVS+cl1O2SEp9g1K/wyLzj/OJHv+1TUfiPr/w==",
+      "license": "MIT",
+      "workspaces": [
+        "examples",
+        "playground"
+      ],
+      "dependencies": {
+        "@pixi/colord": "^2.9.6",
+        "@types/earcut": "^3.0.0",
+        "@webgpu/types": "^0.1.69",
+        "@xmldom/xmldom": "^0.8.15",
+        "earcut": "^3.0.2",
+        "eventemitter3": "^5.0.1",
+        "gifuct-js": "^2.1.2",
+        "ismobilejs": "^1.1.1",
+        "parse-svg-path": "^0.2.0",
+        "tiny-lru": "^11.4.7"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/pixijs"
+      }
+    },
+    "node_modules/playwright-core": {
+      "version": "1.49.1",
+      "resolved": "https://registry.npmjs.org/playwright-core/-/playwright-core-1.49.1.tgz",
+      "integrity": "sha512-BzmpVcs4kE2CH15rWfzpjzVGhWERJfmnXmniSyKeRZUs9Ws65m+RGIi7mjJK/euCegfn3i7jvqWeWyHe9y3Vgg==",
+      "license": "Apache-2.0",
+      "bin": {
+        "playwright-core": "cli.js"
+      },
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/three": {
+      "version": "0.170.0",
+      "resolved": "https://registry.npmjs.org/three/-/three-0.170.0.tgz",
+      "integrity": "sha512-FQK+LEpYc0fBD+J8g6oSEyyNzjp+Q7Ks1C568WWaoMRLW+TkNNWmenWeGgJjV105Gd+p/2ql1ZcjYvNiPZBhuQ==",
+      "license": "MIT"
+    },
+    "node_modules/tiny-lru": {
+      "version": "11.4.7",
+      "resolved": "https://registry.npmjs.org/tiny-lru/-/tiny-lru-11.4.7.tgz",
+      "integrity": "sha512-w/Te7uMUVeH0CR8vZIjr+XiN41V+30lkDdK+NRIDCUYKKuL9VcmaUEmaPISuwGhLlrTGh5yu18lENtR9axSxYw==",
+      "license": "BSD-3-Clause",
+      "engines": {
+        "node": ">=12"
+      }
+    }
+  }
+}

package/core/package.json

@@ -0,0 +1,16 @@
+{
+  "name": "reel-studio-core",
+  "private": true,
+  "type": "module",
+  "description": "Deterministic renderer: HTML + GSAP / Lottie / Three.js / Pixi → MP4 / PNG",
+  "scripts": {
+    "render": "node render.mjs"
+  },
+  "dependencies": {
+    "gsap": "^3.12.5",
+    "lottie-web": "^5.12.2",
+    "pixi.js": "^8.6.0",
+    "playwright-core": "1.49.1",
+    "three": "^0.170.0"
+  }
+}

package/core/render.mjs

@@ -0,0 +1,163 @@
+#!/usr/bin/env node
+/* Deterministic renderer for compositions (HTML + GSAP, plus any engine in
+ * engines/ that registers with Studio.onSeek: Lottie, Three.js, Pixi, video).
+ *
+ *   node core/render.mjs video  <composition.html> <out.mp4> [--audio mix.wav] [--safe] [--frames <dir>]
+ *   node core/render.mjs still  <composition.html> <out.png> [--t 1.5] [--safe]
+ *   node core/render.mjs stills <composition.html> <out_dir> [--every 0.5 | --at 0,1.2,3] [--safe]
+ *
+ * Paths are relative to the repo root (reel-studio/). The page is served from
+ * the repo root over a local HTTP server so assets load with absolute paths
+ * like /brands/<name>/assets/..., /core/lib/... and /engines/...
+ *
+ * Size, fps and duration come from the composition's Studio.setup().
+ */
+import { existsSync } from "node:fs";
+import { createServer } from "node:http";
+import { readFile, mkdir, stat } from "node:fs/promises";
+import { spawn } from "node:child_process";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { chromium } from "playwright-core";
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+// Google Chrome: CHROME_PATH wins, else the usual install paths on macOS and Linux
+const CHROME = process.env.CHROME_PATH || [
+  "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome",
+  "/usr/bin/google-chrome", "/usr/bin/google-chrome-stable", "/usr/bin/chromium", "/usr/bin/chromium-browser",
+].find((p) => existsSync(p)) || "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome";
+const TYPES = {
+  ".html": "text/html", ".js": "text/javascript", ".mjs": "text/javascript", ".css": "text/css",
+  ".json": "application/json", ".svg": "image/svg+xml", ".png": "image/png", ".jpg": "image/jpeg",
+  ".jpeg": "image/jpeg", ".webp": "image/webp", ".ttf": "font/ttf", ".otf": "font/otf", ".woff2": "font/woff2",
+  ".mp4": "video/mp4", ".webm": "video/webm", ".mov": "video/quicktime", ".mp3": "audio/mpeg", ".wav": "audio/wav",
+};
+
+function args(argv) {
+  const [mode, input, output, ...rest] = argv;
+  const opts = {};
+  for (let i = 0; i < rest.length; i++) {
+    const k = rest[i].replace(/^--/, "");
+    const next = rest[i + 1];
+    if (next === undefined || next.startsWith("--")) opts[k] = true;
+    else { opts[k] = next; i++; }
+  }
+  if (!mode || !input || !output) {
+    console.error("usage: render.mjs <video|still|stills> <composition.html> <out> [options]");
+    process.exit(2);
+  }
+  return { mode, input, output, opts };
+}
+
+function serve() {
+  const server = createServer(async (req, res) => {
+    try {
+      const url = decodeURIComponent(new URL(req.url, "http://x").pathname);
+      const file = path.join(ROOT, url);
+      if (!file.startsWith(ROOT)) throw new Error("outside root");
+      const s = await stat(file);
+      const data = await readFile(s.isDirectory() ? path.join(file, "index.html") : file);
+      const type = TYPES[path.extname(file).toLowerCase()] || "application/octet-stream";
+      // Range requests: Chrome needs them to seek inside larger <video> files.
+      const range = /^bytes=(\d*)-(\d*)$/.exec(req.headers.range || "");
+      if (range) {
+        const start = range[1] ? +range[1] : data.length - +range[2];
+        const end = range[1] && range[2] ? Math.min(+range[2], data.length - 1) : data.length - 1;
+        res.writeHead(206, { "content-type": type, "accept-ranges": "bytes", "content-range": `bytes ${start}-${end}/${data.length}`, "content-length": end - start + 1 });
+        return res.end(data.subarray(start, end + 1));
+      }
+      res.writeHead(200, { "content-type": type, "accept-ranges": "bytes" });
+      res.end(data);
+    } catch {
+      res.writeHead(404); res.end("not found");
+    }
+  });
+  return new Promise((resolve) => server.listen(0, "127.0.0.1", () => resolve(server)));
+}
+
+// WebGL (Three.js, Pixi) on the GPU, but compositing in software: with GPU compositing Chrome
+// draws <video> plates ~10 levels brighter than ffmpeg decodes them (measured 2026-11-02).
+// playwright-core is pinned (1.49.1) because 1.64 shifted plate colours the same way.
+const CHROME_ARGS = ["--force-color-profile=srgb", "--hide-scrollbars",
+  "--enable-gpu", "--use-angle=metal", "--ignore-gpu-blocklist", "--disable-gpu-compositing"];
+
+async function openPage(input, safe) {
+  const server = await serve();
+  const { port } = server.address();
+  const rel = path.relative(ROOT, path.resolve(input)).split(path.sep).join("/");
+  const browser = await chromium.launch({ executablePath: CHROME, args: CHROME_ARGS });
+  const page = await browser.newPage({ viewport: { width: 1080, height: 1920 }, deviceScaleFactor: 1 });
+  const errors = [];
+  page.on("pageerror", (e) => errors.push(String(e)));
+  page.on("console", (m) => m.type() === "error" && !m.text().startsWith("Failed to load resource") && errors.push(m.text()));
+  page.on("response", (r) => r.status() >= 400 && !r.url().endsWith("/favicon.ico") && errors.push(`${r.status()} ${r.url()}`));
+  await page.goto(`http://127.0.0.1:${port}/${rel}?render=1${safe ? "&safe=1" : ""}`);
+  await page.evaluate(() => window.__ready);
+  const meta = await page.evaluate(() => window.__meta());
+  await page.setViewportSize({ width: meta.width, height: meta.height });
+  const stage = page.locator("#stage");
+  const shot = async (t, file) => {
+    await page.evaluate((tt) => window.__seek(tt), t);
+    return stage.screenshot({ path: file, type: "png", animations: "disabled" });
+  };
+  const close = async () => { await browser.close(); server.close(); };
+  return { page, meta, shot, close, errors };
+}
+
+function ffmpeg(argv) {
+  const p = spawn("ffmpeg", ["-hide_banner", "-loglevel", "error", "-y", ...argv], { stdio: ["pipe", "inherit", "inherit"] });
+  const done = new Promise((res, rej) => p.on("close", (c) => (c === 0 ? res() : rej(new Error("ffmpeg exited " + c)))));
+  return { stdin: p.stdin, done };
+}
+
+const { mode, input, output, opts } = args(process.argv.slice(2));
+const { meta, shot, close, errors } = await openPage(input, !!opts.safe);
+const t0 = Date.now();
+
+try {
+  if (mode === "still") {
+    await mkdir(path.dirname(path.resolve(output)), { recursive: true });
+    await shot(parseFloat(opts.t ?? 0), output);
+    console.log(`${output}  (${meta.width}x${meta.height} @ t=${opts.t ?? 0}s)`);
+  } else if (mode === "stills") {
+    await mkdir(output, { recursive: true });
+    const times = opts.at
+      ? String(opts.at).split(",").map(Number)
+      : Array.from({ length: Math.floor(meta.duration / parseFloat(opts.every ?? 0.5)) + 1 }, (_, i) => +(i * parseFloat(opts.every ?? 0.5)).toFixed(3));
+    for (const t of times) {
+      const name = path.join(output, `t_${t.toFixed(2).padStart(6, "0")}.png`);
+      await shot(Math.min(t, meta.duration - 1 / meta.fps), name);
+    }
+    console.log(`${times.length} stills → ${output}`);
+  } else if (mode === "video") {
+    const frames = Math.round(meta.duration * meta.fps);
+    const enc = [
+      "-f", "image2pipe", "-framerate", String(meta.fps), "-c:v", "png", "-i", "-",
+      ...(opts.audio ? ["-i", opts.audio] : []),
+      // aq-mode=3 + light deblock keeps smooth brand gradients from banding/shifting between frames.
+      "-c:v", "libx264", "-profile:v", "high", "-preset", "slow", "-crf", "16",
+      "-x264-params", "aq-mode=3:aq-strength=0.9:deblock=-1,-1", "-g", String(meta.fps * 2),
+      "-pix_fmt", "yuv420p", "-r", String(meta.fps), "-fps_mode", "cfr",
+      "-color_primaries", "bt709", "-color_trc", "bt709", "-colorspace", "bt709",
+      ...(opts.audio ? ["-c:a", "aac", "-b:a", "192k", "-ar", "48000", "-af", "apad", "-shortest"] : []),
+      "-movflags", "+faststart", output,
+    ];
+    await mkdir(path.dirname(path.resolve(output)), { recursive: true });
+    if (opts.frames) await mkdir(opts.frames, { recursive: true });
+    const { stdin, done } = ffmpeg(enc);
+    for (let i = 0; i < frames; i++) {
+      const file = opts.frames ? path.join(opts.frames, `f_${String(i).padStart(5, "0")}.png`) : undefined;
+      const buf = await shot(i / meta.fps, file);
+      if (!stdin.write(buf)) await new Promise((r) => stdin.once("drain", r));
+      if (i % meta.fps === 0) process.stdout.write(`\rframe ${i}/${frames}`);
+    }
+    stdin.end();
+    await done;
+    console.log(`\r${output}  (${meta.width}x${meta.height}, ${meta.fps} fps, ${frames} frames, ${meta.duration}s) in ${((Date.now() - t0) / 1000).toFixed(1)}s`);
+  } else {
+    throw new Error("unknown mode " + mode);
+  }
+  if (errors.length) { console.error("Page errors:\n  " + errors.join("\n  ")); process.exitCode = 1; }
+} finally {
+  await close();
+}

package/engines/README.md

@@ -0,0 +1,46 @@
+# Engines
+
+Every engine plugs into one clock. The renderer asks the page for time `t`, and every layer draws itself at `t`.
+That is what makes every frame deterministic and checkable, whatever drew it.
+
+## Which engine for which look
+
+| Look | Engine | File | Status |
+|---|---|---|---|
+| Moving text, app UI demos, ad layouts, end cards | **HTML/CSS + GSAP** | built into `core/lib/runtime.js` (`Studio.tl`) | ✅ tested |
+| Flat 2D cartoon character drawn in code | **SVG rig + GSAP** | `svg-rig.js` (`idle`, `blink`, `talk`, `wave`, `hop`) | ✅ tested |
+| 2D animation from a designer (After Effects) | **Lottie** | `Studio.lottie(el, path)` in the runtime | ✅ ported from the Yuppo renderer |
+| 2D character with states, from Rive | **Rive** | — | 🔜 planned: needs a `.riv` file to build and test against |
+| Particles, confetti, many sprites, 2D game-like motion | **Pixi.js v8** | `pixi.js` (`pixiLayer`) | ✅ tested |
+| 3D product, CAD, camera moves, 3D cartoon (toon + outline) | **Three.js** | `three.js` (`threeLayer`, `toon`, `outline`) | ✅ tested |
+| High-end 3D cartoon, real lighting, physics, simulations | **Blender** (headless, Python) | `blender/render.sh` + a scene script → MP4 plate | ✅ tested (Blender 5.2, Eevee) |
+| A live website or web app you own (its own 3D scene, UI) | **Page capture** | `capture.mjs` → PNG sequence → MP4 plate | ✅ used for the Bike Logger reel |
+| Real-looking footage | AI video generation or stock, as a plate | `Studio.video(el)` | Footage only. Never shows product facts; check the brand's compliance |
+
+**Rule of thumb:** start with GSAP. Add one engine for the hero visual. More than two engines in one piece usually means the idea is unclear.
+
+## Two kinds of engine
+
+- **Live layers** run in the composition page and are drawn on every seek: GSAP, SVG rig, Lottie, Pixi, Three.js.
+  They can be stacked freely (`<div class="layer">` per engine) and all share the GSAP timeline for cuts and fades.
+- **Plates** are rendered first, then played as a `<video>` layer with `Studio.video(el, { start })`: Blender,
+  page capture, footage. Encode plates with `-g 1` (every frame a keyframe) so seeking is frame-exact.
+
+## Determinism rules (all engines)
+
+1. **Pose from `t` only.** `update(t)` sets every position, rotation and colour from `t`. No `+= delta`, no state carried between frames. The renderer can ask for any frame in any order.
+2. **No hidden clocks.** No `requestAnimationFrame` loops, `setTimeout`, CSS animations or transitions, `Date.now()`, or video autoplay.
+3. **No unseeded randomness.** Use `Studio.random(seed)`.
+4. **Physics:** simulate at a fixed step ahead of time (or in Blender), store the result, look it up by `t`.
+5. **Wait for loading.** Anything async goes through `Studio.wait(promise)` so frame 0 is never half-loaded.
+6. **WebGL needs `preserveDrawingBuffer: true`** (the adapters set it) so screenshots see the canvas.
+7. **Don't change the Chrome flags or the pinned playwright-core casually.** GPU compositing or a newer Playwright
+   made `<video>` plates ~10 levels too bright (see `CHROME_ARGS` in `core/render.mjs` and *Learnings* in `STATUS.md`).
+
+Check with: `node core/render.mjs still <comp> a.png --t 3` twice, then `md5 -q a.png b.png`. They must match.
+
+## Adding an engine
+
+Write `engines/<name>.js` that creates its canvas or DOM inside a layer element, registers loading with
+`Studio.wait`, and draws with `Studio.onSeek((t) => …)`. Add a scene to `examples/engines-demo/`, render stills,
+check two renders match, then add a row to the table above.

package/engines/blender/example_scene.py

@@ -0,0 +1,47 @@
+"""Example Blender scene: a cel-shaded blob hops on a coloured floor.
+
+    engines/blender/render.sh engines/blender/example_scene.py /tmp/blob.mp4 --size 540x960 --duration 2
+"""
+import math
+
+import bpy
+
+
+def build(ctx):
+    scene, toon, key = ctx["scene"], ctx["toon"], ctx["key"]
+    d = ctx["duration"]
+
+    # Backdrop colour seen by the camera only; it must not light the scene, or it flattens the toon bands.
+    world = bpy.data.worlds.new("bg")
+    world.use_nodes = True
+    nt = world.node_tree
+    bg = nt.nodes["Background"]
+    bg.inputs[0].default_value = (1.0, 0.86, 0.72, 1)
+    path, black, mix = nt.nodes.new("ShaderNodeLightPath"), nt.nodes.new("ShaderNodeBackground"), nt.nodes.new("ShaderNodeMixShader")
+    black.inputs[0].default_value = (0, 0, 0, 1)
+    nt.links.new(path.outputs["Is Camera Ray"], mix.inputs[0])
+    nt.links.new(black.outputs[0], mix.inputs[1])
+    nt.links.new(bg.outputs[0], mix.inputs[2])
+    nt.links.new(mix.outputs[0], nt.nodes["World Output"].inputs[0])
+    scene.world = world
+
+    bpy.ops.mesh.primitive_plane_add(size=40)
+    bpy.context.object.data.materials.append(toon((1.0, 0.72, 0.5)))
+
+    bpy.ops.mesh.primitive_uv_sphere_add(radius=1, segments=48, ring_count=24, location=(0, 0, 1))
+    blob = bpy.context.object
+    bpy.ops.object.shade_smooth()
+    blob.data.materials.append(toon((0.93, 0.42, 0.09)))
+
+    # Hop: squash, rise, fall, squash, settle (same beats as SvgRig.hop).
+    for t, z, sx, sz in [(0, 1, 1, 1), (0.1 * d, 0.85, 1.1, 0.85), (0.35 * d, 2.6, 0.92, 1.1),
+                         (0.6 * d, 1, 1, 1), (0.67 * d, 0.88, 1.08, 0.88), (0.8 * d, 1, 1, 1), (d, 1, 1, 1)]:
+        key(blob, "location", t, (0, 0, z))
+        key(blob, "scale", t, (sx, sx, sz))
+
+    bpy.ops.object.light_add(type="SUN", rotation=(math.radians(50), 0, math.radians(30)))
+    bpy.context.object.data.energy = 4
+
+    bpy.ops.object.camera_add(location=(0, -11, 3.2), rotation=(math.radians(82), 0, 0))
+    scene.camera = bpy.context.object
+    scene.camera.data.lens = 40

package/engines/blender/render.sh

@@ -0,0 +1,21 @@
+#!/usr/bin/env bash
+# Render a Blender scene script to an MP4 plate the composition plays with Studio.video().
+#
+#   engines/blender/render.sh <scene.py> <out.mp4> [--size 1080x1920] [--fps 30] [--duration 4] [--engine EEVEE|CYCLES|WORKBENCH]
+#
+# <scene.py> builds the scene with bpy and defines build(ctx); see example_scene.py.
+# Frames go to a temp folder, then ffmpeg encodes with every frame a keyframe
+# so the browser can seek it frame-exactly. Alpha is not kept: render the
+# background in Blender, or put the plate behind transparent HTML layers.
+set -euo pipefail
+BLENDER="${BLENDER:-/Applications/Blender.app/Contents/MacOS/Blender}"
+here="$(cd "$(dirname "$0")" && pwd)"
+scene="$1"; out="$2"; shift 2
+frames="$(mktemp -d)/f_"
+"$BLENDER" -b --factory-startup -noaudio --python "$here/run.py" -- "$scene" "$frames" "$@" >"${frames%f_}blender.log" 2>&1 \
+  || { tail -30 "${frames%f_}blender.log"; exit 1; }
+fps=$(awk '/^FPS /{print $2}' "${frames%f_}blender.log")
+mkdir -p "$(dirname "$out")"
+ffmpeg -hide_banner -loglevel error -y -framerate "$fps" -i "${frames}%05d.png" \
+  -c:v libx264 -preset slow -crf 12 -pix_fmt yuv420p -g 1 -movflags +faststart "$out"
+echo "$out  ($(ls "${frames%f_}" | grep -c png) frames @ ${fps} fps)"