@amg555/frameforge-mcp 2.7.3 → 2.7.7

package/plugins/faceless-shorts/styles/inside-out/example/src/shots.js

@@ -0,0 +1,195 @@
+// WHAT IF YOU SWALLOW GUM?: the shot list (the only file that changes per video, with script.json).
+// A shot: { id, at, cam: [cx, cy], zoom, note, draw(lt, d, t) }  · lt = time in shot, d = shot length, t = film time.
+// It runs until the next shot's `at`; the last one ends at T.dur. Cut = L(i) - 0.08 (picture changes just before the line).
+// Sound: cue(t, type, { gain, dur }): types tools/mix.py knows are listed in STYLE.md.
+import { ctx, C, W, H, clamp, lerp, seg, eo, eio, eob, rnd, bigText } from './core/lib.js';
+import { L, Le, Wd, T } from './core/timing.js';
+import * as K from './core/kit.js';
+
+export function buildShots() {
+  const S = [], CUES = [];
+  const add = (o) => (S.push(o), o);
+  const cue = (t, type, o = {}) => CUES.push({ t: +t.toFixed(3), type, ...o });
+  const cut = (i) => (i === 0 ? 0 : L(i) - 0.08);
+
+  // ── 1 · HOOK: he pops the gum, chews, gulps ─────────────────────────────
+  {
+    const st = cut(0), gulp = Wd('swallow', 0) - st, shock = Wd('gum', 0) - st;
+    add({ id: 'S01', at: st, cam: [540, 820], note: 'room, gum to mouth, gulp, shock',
+      draw(lt) {
+        K.room();
+        const arm = K.armPose(K.armPose(K.armPose(K.ARM.down, K.ARM.mouth, 0.55), K.ARM.mouth, eio(seg(lt, 0, 0.3))), K.ARM.down, eio(seg(lt, 0.4, 0.8)));
+        const shocked = lt > shock;
+        const shake = shocked ? Math.sin(lt * 70) * 6 * Math.max(0, 1 - (lt - shock) * 2) : 0;
+        K.man({ x: 540 + shake, y: 1180, s: 1.6, arm, holding: lt < 0.32 ? (x, y) => K.gum(x, y, 0.55, 0.3) : null,
+          mouth: shocked ? 'o' : lt < 0.32 ? 'smile' : 'chew', chew: Math.abs(Math.sin(lt * 14)), eyes: shocked ? 'wide' : 'n', brow: shocked ? 1 : 0 });
+        if (lt > gulp && lt < gulp + 0.75) bigText('GULP!', 830, 560, 92, C.white, -0.18, eob(seg(lt, gulp, gulp + 0.15)));
+        K.shockLines(540, 625, 300, shocked ? clamp((lt - shock) * 5) : 0);
+      } });
+    cue(st + 0.3, 'pop', { gain: 0.6 }); cue(st + gulp, 'gulp'); cue(st + shock, 'boing', { gain: 0.5 });
+  }
+
+  // ── 2 · X-RAY: it slides down into the stomach ──────────────────────────
+  {
+    const st = cut(1), arrive = Wd('stomach', 1) - st + 0.15;
+    add({ id: 'S02', at: st, cam: [540, 1050], zoom: 0.3, note: 'x-ray body, gum travels mouth to stomach',
+      draw(lt, d, t) {
+        K.xray(t);
+        const [gx, gy] = K.foodAt(eio(seg(lt, 0.15, arrive)));
+        const pulse = lt > arrive ? Math.max(0, Math.sin((lt - arrive) * 8)) * Math.exp(-(lt - arrive) * 1.5) : 0;
+        K.man({ x: 540, y: 1120, s: 1.5, xray: true, mouth: 'o', eyes: 'wide', brow: 1, inside: [gx, gy, lt * 2], pulse });
+      } });
+    cue(st, 'whoosh'); cue(st + 0.2, 'slide', { dur: arrive - 0.2 }); cue(st + arrive, 'plop');
+  }
+
+  // ── 3 · STOMACH: acid gets to work ──────────────────────────────────────
+  {
+    const st = cut(2), work = Wd('work', 2) - st;
+    add({ id: 'S03', at: st, cam: [540, 900], note: 'inside stomach, acid bubbles, sizzle on "work"',
+      draw(lt, d, t) {
+        K.insideStomach(t);
+        const bob = Math.sin(lt * 2.4) * 18;
+        K.gum(540, 820 + bob, 3.4, Math.sin(lt * 1.7) * 0.12);
+        if (lt > work) { ctx.save(); ctx.globalAlpha = clamp((lt - work) * 4);
+          for (let i = 0; i < 10; i++) { const an = i / 10 * Math.PI * 2 + lt, r1 = 190 + Math.sin(lt * 12 + i) * 12;
+            ctx.strokeStyle = C.yellow; ctx.lineWidth = 10; ctx.lineCap = 'round'; ctx.beginPath();
+            ctx.moveTo(540 + Math.cos(an) * r1, 820 + bob + Math.sin(an) * r1 * 0.7); ctx.lineTo(540 + Math.cos(an) * (r1 + 50), 820 + bob + Math.sin(an) * (r1 + 50) * 0.7); ctx.stroke(); }
+          ctx.restore(); }
+      } });
+    cue(st, 'whoosh'); cue(st, 'bubbles', { dur: L(3) - st }); cue(st + work, 'sizzle', { dur: 1.0 });
+  }
+
+  // ── 4 · sugar dissolves, the base stays ─────────────────────────────────
+  {
+    const st = cut(3), sugar = Wd('sugar', 3) - st, base = Wd('base', 3) - st;
+    add({ id: 'S04', at: st, cam: [540, 820], note: 'sugar specks fly off, GUM BASE tag on "base"',
+      draw(lt, d, t) {
+        K.insideStomach(t + 3);
+        const bob = Math.sin(lt * 2.4) * 14;
+        for (let i = 0; i < 26; i++) {
+          const s0 = sugar + rnd(i) * 1.0, p = seg(lt, s0, s0 + 1.1); if (p <= 0 || p >= 1) continue;
+          const an = rnd(i + 40) * Math.PI * 2, dd = 120 + eo(p) * 380;
+          ctx.save(); ctx.globalAlpha = 1 - p; ctx.translate(540 + Math.cos(an) * dd, 820 + Math.sin(an) * dd * 0.8); ctx.rotate(p * 4 + i);
+          if (i % 2) { ctx.fillStyle = C.white; ctx.fillRect(-14, -14, 28, 28); } else { ctx.beginPath(); ctx.arc(0, 0, 13, 0, 7); ctx.fillStyle = C.yellow; ctx.fill(); }
+          ctx.restore();
+        }
+        K.gum(540, 820 + bob, 3.4, Math.sin(lt * 1.7) * 0.12);
+        K.tag('GUM BASE', 540, 500, 540, 700 + bob, 66, lt > base ? eob(seg(lt, base, base + 0.3)) : 0);
+      } });
+    cue(st, 'whoosh'); cue(st + sugar, 'sparkle', { dur: 1.2 }); cue(st + base, 'pop');
+  }
+
+  // ── 5 · your body can't break it down (enzymes bounce off) ──────────────
+  {
+    const st = cut(4), end = cut(5), P = 1.05;
+    add({ id: 'S05', at: st, cam: [540, 800], note: 'enzyme chompers bounce off stretchy gum',
+      draw(lt) {
+        ctx.fillStyle = C.bg; ctx.fillRect(-300, -300, W + 600, H + 600);
+        const sx = Math.abs(Math.sin(lt * 3.2));
+        K.gum(540, 780, 4.4, 0, 1 + 0.32 * sx, 1 - 0.16 * sx);
+        K.pill('GUM BASE', 540, 430, 52, C.ink, C.white, eob(seg(lt, 0.1, 0.4)));
+        for (const sd of [-1, 1]) {
+          const cyc = lt % P, first = lt < P, contact = 540 + sd * (250 + sx * 70);
+          const x = cyc < 0.45 ? lerp(first ? 540 + sd * 720 : 540 + sd * 430, contact + sd * 85, eio(cyc / 0.45)) : lerp(contact + sd * 85, 540 + sd * 430, eo((cyc - 0.45) / 0.6));
+          K.chomper(x, 800, 92, 0.12 + 0.5 * Math.abs(Math.sin(lt * 16)), sd > 0);
+          if (cyc > 0.43 && cyc < 0.65) K.burst(contact, 790, 1, 1 - (cyc - 0.43) / 0.22);
+          if (lt > 0.5) K.redX(x, 640, 0.17, Math.min(1, clamp((cyc - 0.45) * 6) * clamp((1 - cyc) * 8)));
+        }
+      } });
+    cue(st, 'whoosh'); for (let k = 0; st + k * P + 0.45 < end; k++) cue(st + k * P + 0.45, 'boing', { gain: 0.7 });
+  }
+
+  // ── 6 · seven years? total myth (X slams on "myth") ─────────────────────
+  {
+    const st = cut(5), slam = Wd('myth', 5) - st - 0.05;
+    add({ id: 'S06', at: st, cam: [540, 800], note: 'calendar 7 YEARS drops, red X slams on "myth"',
+      draw(lt) {
+        ctx.fillStyle = C.bg; ctx.fillRect(-300, -300, W + 600, H + 600);
+        const shake = lt > slam ? Math.sin(lt * 90) * 18 * Math.max(0, 1 - (lt - slam) * 4) : 0;
+        ctx.save(); ctx.translate(shake, 0);
+        const drop = eob(seg(lt, 0, 0.45));
+        K.calendar(540, lerp(-400, 780, drop), 1, '7', 'YEARS', lerp(-0.25, -0.04, drop));
+        if (lt > slam) { const p = seg(lt, slam, slam + 0.2); K.redX(540, 780, lerp(1.9, 1, eo(p)), clamp(p * 3)); }
+        ctx.restore();
+      } });
+    cue(st, 'whoosh'); cue(st + 0.4, 'thud'); cue(st + slam + 0.1, 'slam');
+  }
+
+  // ── 7 · it moves through your gut ───────────────────────────────────────
+  {
+    const st = cut(6), gut = K.makeGut();
+    add({ id: 'S07', at: st, cam: [540, 760], note: 'gum travels the whole x-ray intestine',
+      draw(lt, d, t) {
+        K.xray(t); gut.draw();
+        const u = eio(seg(lt, 0.1, d - 0.1)), [x, y, a] = gut.at(u);
+        ctx.save(); ctx.globalAlpha = 0.35; for (let i = 1; i < 6; i++) { const q = gut.at(Math.max(0, u - i * 0.012)); ctx.beginPath(); ctx.arc(q[0], q[1], 10 - i, 0, 7); ctx.fillStyle = C.cyan; ctx.fill(); } ctx.restore();
+        K.gum(x, y, 1.25, a);
+      } });
+    cue(st, 'whoosh'); cue(st + 0.1, 'slide', { dur: L(7) - st - 0.2, gain: 0.6 });
+  }
+
+  // ── 8 · a few days, and it's out ────────────────────────────────────────
+  {
+    const st = cut(7), out = Wd('out', 7) - st - 0.1, shrink = Math.max(0.6, out - 0.45);
+    add({ id: 'S08', at: st, cam: [540, 760], note: 'stopwatch spins DAY 1-3, gum zips out on "out"',
+      draw(lt) {
+        ctx.fillStyle = C.bg; ctx.fillRect(-300, -300, W + 600, H + 600);
+        const k = eio(seg(lt, shrink, shrink + 0.35));
+        K.stopwatch(lerp(540, 250, k), lerp(720, 560, k), lerp(1, 0.55, k), lt * 14);
+        const day = Math.min(3, 1 + Math.floor(lt / (shrink / 3)));
+        K.pill('DAY ' + day, lerp(540, 250, k), lerp(1130, 820, k), lerp(70, 48, k), C.ink, C.white, lt < 0.25 ? eob(seg(lt, 0, 0.25)) : 1);
+        if (lt > out) { const p = seg(lt, out, out + 0.75), gx = lerp(380, 1300, eio(p)); K.gum(gx, 1010, 2.2, 0, 1.25, 0.85); K.speedLines(gx - 60, 1010, 1 - p * 0.6); }
+      } });
+    cue(st, 'whoosh'); for (let i = 1; i < 3; i++) cue(st + i * shrink / 3, 'tock'); cue(st + out, 'zip');
+  }
+
+  // ── 9 · swallow tons? (gums pile up) ────────────────────────────────────
+  {
+    const st = cut(8), d0 = cut(9) - st;
+    add({ id: 'S09', at: st, cam: [540, 820], note: 'many gums rain into the x-ray stomach',
+      draw(lt, d, t) {
+        K.xray(t);
+        const top = K.stomachTop(560, 780, 3.0);
+        ctx.strokeStyle = C.pink; ctx.lineWidth = 70; ctx.lineCap = 'round'; ctx.beginPath(); ctx.moveTo(top[0] + 10, -100); ctx.lineTo(top[0], top[1] + 30); ctx.stroke();
+        K.stomach(560, 780, 3.0);
+        const step = Math.min(0.08, (d0 - 0.6) / 14);
+        for (let i = 0; i < 14; i++) {
+          const p = seg(lt, i * step, i * step + 0.45); if (p <= 0) continue;
+          const tx = 470 + (rnd(i) - 0.5) * 260 + (i > 7 ? 40 : 0), ty = 990 - Math.floor(i / 5) * 55 - rnd(i + 3) * 20;
+          K.gum(lerp(470, tx, eo(p)), lerp(-80, ty, eob(p)), 1.1, rnd(i + 7) * 3 + p);
+        }
+      } });
+    const step = Math.min(0.08, (d0 - 0.6) / 14);
+    cue(st, 'whoosh'); for (let i = 0; i < 14; i += 2) cue(st + i * step + 0.4, 'plop', { gain: 0.5 });
+  }
+
+  // ── 10 · bigger problem: blockage ───────────────────────────────────────
+  {
+    const st = cut(9), warn = Wd('block', 9) - st - 0.1;
+    add({ id: 'S10', at: st, cam: [540, 820], note: 'gum clump blocks the gut, warning pulses',
+      draw(lt, d, t) {
+        K.xray(t); K.gutTube(820, t);
+        for (let i = 0; i < 14; i++) { ctx.beginPath(); ctx.arc(120 + i * 24 + Math.sin(t * 3 + i) * 4, 760 + rnd(i) * 120, 16 + rnd(i + 2) * 10, 0, 7); ctx.fillStyle = C.yellow; ctx.fill(); }
+        const pr = Math.sin(lt * 7) * 0.5 + 0.5;
+        ctx.beginPath(); ctx.arc(560, 820, 190 + pr * 30, 0, 7); ctx.strokeStyle = C.red; ctx.globalAlpha = 0.35 + 0.5 * pr; ctx.lineWidth = 18; ctx.stroke(); ctx.globalAlpha = 1;
+        for (let i = 0; i < 7; i++) { const an = i / 7 * Math.PI * 2; K.gum(560 + Math.cos(an) * 60 + Math.sin(t * 20 + i) * 3, 820 + Math.sin(an) * 50, 1.25, an); }
+        K.gum(560, 820, 1.3, 0.4);
+        K.warning(560, 450, lt > warn ? eob(seg(lt, warn, warn + 0.3)) * (1 + pr * 0.06) : 0);
+      } });
+    cue(st, 'whoosh'); cue(st + warn, 'alarm', { dur: cut(10) - st - warn });
+  }
+
+  // ── 11 · so maybe… spit it out ──────────────────────────────────────────
+  {
+    const st = cut(10), spit = Wd('spit', 10) - st;
+    add({ id: 'S11', at: st, cam: [540, 760], note: 'hero wags his finger at camera',
+      draw(lt) {
+        K.room();
+        const p = eio(seg(lt, 0, 0.5));
+        K.man({ x: 540, y: 1290, s: 2.0, arm: K.armPose(K.ARM.down, K.ARM.point, p), finger: lt > 0.35 ? Math.sin(lt * 11) * 0.35 : 0, mouth: lt > spit ? 'grin' : 'smirk', brow: 0.3, smirk: true });
+      } });
+    cue(st, 'whoosh'); cue(st + spit, 'pop', { gain: 0.6 });
+  }
+
+  return { shots: S, cues: CUES };
+}

package/plugins/faceless-shorts/styles/inside-out/example/tools/capture.mjs

@@ -0,0 +1,122 @@
+// Frame-exact capture through headless Chrome. No npm packages (Node 22+). Run from the project folder.
+//   node tools/capture.mjs check                         boot, list shots + captions, report errors
+//   node tools/capture.mjs cues                          write data/cues.json (the sound cues, for tools/mix.py)
+//   node tools/capture.mjs sheet review/all.jpg [step=0.5] [cols=9]   contact sheet, a frame every `step` s, time-stamped
+//   node tools/capture.mjs frames review/full "1.2,8.4"  full-size JPEGs of those times
+//   node tools/capture.mjs video renders/out.mp4 [start end] [--draft]   the film (30 fps) with data/mix.wav if it exists
+//   node tools/capture.mjs preview                       serve the project and print a URL to watch it in a browser
+// CHROME=/path/to/chrome overrides the browser.
+import { spawn, spawnSync } from 'node:child_process';
+import http from 'node:http';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const FPS = +(process.env.FPS || 30);
+const CHROME = [process.env.CHROME, '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome', '/Applications/Chromium.app/Contents/MacOS/Chromium',
+  '/Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge', '/usr/bin/google-chrome', '/usr/bin/google-chrome-stable', '/usr/bin/chromium',
+  '/usr/bin/chromium-browser', '/snap/bin/chromium', 'C:/Program Files/Google/Chrome/Application/chrome.exe',
+  'C:/Program Files (x86)/Google/Chrome/Application/chrome.exe'].find((p) => p && fs.existsSync(p));
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+const args = process.argv.slice(2), flags = new Set(args.filter((a) => a.startsWith('--')));
+const [mode, ...rest] = args.filter((a) => !a.startsWith('--'));
+
+const MIME = { '.html': 'text/html', '.js': 'text/javascript', '.mjs': 'text/javascript', '.json': 'application/json', '.otf': 'font/otf',
+  '.ttf': 'font/ttf', '.woff2': 'font/woff2', '.wav': 'audio/wav', '.mp3': 'audio/mpeg', '.png': 'image/png', '.jpg': 'image/jpeg' };
+function serve(port = 0) {
+  return new Promise((res) => {
+    const srv = http.createServer((req, r) => {
+      const u = decodeURIComponent(req.url.split('?')[0]), f = path.join(ROOT, u === '/' ? 'index.html' : u);
+      if (!f.startsWith(ROOT) || !fs.existsSync(f) || fs.statSync(f).isDirectory()) { r.writeHead(404); r.end(); return; }
+      r.writeHead(200, { 'Content-Type': MIME[path.extname(f)] || 'application/octet-stream', 'Cache-Control': 'no-store' });
+      fs.createReadStream(f).pipe(r);
+    });
+    srv.listen(port, '127.0.0.1', () => res(srv));
+  });
+}
+
+async function openPage(port) {
+  if (!CHROME) throw new Error('Chrome not found: install Google Chrome or set CHROME=/path/to/chrome');
+  const prof = fs.mkdtempSync(path.join(os.tmpdir(), 'fs-chrome-'));
+  const chrome = spawn(CHROME, ['--headless=new', '--remote-debugging-port=0', `--user-data-dir=${prof}`, '--no-first-run', '--no-default-browser-check',
+    '--hide-scrollbars', '--window-size=1080,1920', '--ignore-gpu-blocklist', '--enable-unsafe-swiftshader', ...(process.env.SOFTWARE_GL ? ['--use-angle=swiftshader'] : []), ...(process.getuid?.() === 0 ? ['--no-sandbox'] : []), '--disable-background-timer-throttling', '--disable-renderer-backgrounding', 'about:blank'], { stdio: 'ignore' });
+  let dbg;
+  for (let i = 0; i < 200 && !dbg; i++) { try { dbg = fs.readFileSync(path.join(prof, 'DevToolsActivePort'), 'utf8').split('\n')[0].trim(); } catch { await sleep(100); } }
+  if (!dbg) throw new Error('Chrome did not start');
+  const r = await fetch(`http://127.0.0.1:${dbg}/json/new?${encodeURIComponent(`http://127.0.0.1:${port}/index.html?capture=1${process.env.QS || ''}`)}`, { method: 'PUT' });
+  const target = await r.json();
+  const ws = new WebSocket(target.webSocketDebuggerUrl);
+  await new Promise((res, rej) => { ws.onopen = res; ws.onerror = rej; });
+  let id = 0; const pend = new Map(), logs = [];
+  ws.onmessage = (e) => {
+    const m = JSON.parse(e.data);
+    if (m.id && pend.has(m.id)) { const p = pend.get(m.id); pend.delete(m.id); m.error ? p.rej(new Error(m.error.message)) : p.res(m.result); }
+    else if (m.method === 'Runtime.exceptionThrown') logs.push('EXCEPTION ' + (m.params.exceptionDetails.exception?.description || m.params.exceptionDetails.text));
+    else if (m.method === 'Runtime.consoleAPICalled' && m.params.type === 'error') logs.push('ERROR ' + m.params.args.map((a) => a.value ?? a.description).join(' '));
+  };
+  const send = (method, params = {}) => new Promise((res, rej) => { const i = ++id; pend.set(i, { res, rej }); ws.send(JSON.stringify({ id: i, method, params })); });
+  const ev = async (expr) => { const x = await send('Runtime.evaluate', { expression: expr, returnByValue: true, awaitPromise: true }); if (x.exceptionDetails) throw new Error(x.exceptionDetails.exception?.description || x.exceptionDetails.text); return x.result.value; };
+  await send('Runtime.enable');
+  for (let i = 0; ; i++) {
+    const st = await ev('window.OP ? (OP.bootError ? "ERR:" + OP.bootError : OP.ready) : false').catch(() => false);
+    if (st === true) break;
+    if (typeof st === 'string') throw new Error('boot failed: ' + st + '\n' + logs.join('\n'));
+    if (i > 1200) throw new Error('boot timeout\n' + logs.join('\n'));
+    await sleep(100);
+  }
+  const close = () => { try { ws.close(); } catch {} chrome.kill('SIGKILL'); setTimeout(() => { try { fs.rmSync(prof, { recursive: true, force: true }); } catch {} }, 300); };
+  return { ev, logs, close };
+}
+const jpg = (d) => Buffer.from(d.slice(d.indexOf(',') + 1), 'base64');
+const FRAME = (t, q, label) => `(() => { const d = OP.frame(${t}, ${q}); ${label ? `const cv = document.getElementById('cv'), c = cv.getContext('2d'); c.setTransform(1,0,0,1,0,0); c.fillStyle = '#000'; c.fillRect(0, 0, 250, 86); c.fillStyle = '#fff'; c.font = '700 60px sans-serif'; c.textAlign = 'left'; c.textBaseline = 'alphabetic'; c.fillText('${(+t).toFixed(2)}', 14, 64); return cv.toDataURL('image/jpeg', ${q});` : 'return d;'} })()`;
+
+const srv = await serve(mode === 'preview' ? 8765 : 0), port = srv.address().port;
+if (mode === 'preview') { console.log(`open http://127.0.0.1:${port}/  (Ctrl+C to stop)`); }
+else {
+  const P = await openPage(port);
+  try {
+    const dur = await P.ev('OP.duration()');
+    if (mode === 'check') {
+      console.log(`duration ${dur.toFixed(2)} s`);
+      for (const s of await P.ev('OP.shots()')) console.log(`${s.id.padEnd(5)} ${s.at.toFixed(2).padStart(6)} → ${s.end.toFixed(2).padStart(6)}  (${(s.end - s.at).toFixed(2)} s)  ${s.note}`);
+      console.log('captions:'); for (const c of await P.ev('OP.captions()')) console.log(`  ${c.s.toFixed(2).padStart(6)}–${c.e.toFixed(2).padEnd(6)} ${c.text}`);
+      let bad = 0; for (let t = 0; t < dur; t += 0.25) { try { await P.ev(`OP.draw(${t})`); } catch (e) { bad++; console.log(`ERROR at ${t.toFixed(2)}: ${e.message.split('\n')[0]}`); } }
+      if (P.logs.length) console.log(P.logs.join('\n'));
+      console.log(bad || P.logs.length ? 'CHECK FAILED' : 'CHECK OK');
+    } else if (mode === 'cues') {
+      const cues = await P.ev('OP.cues()');
+      fs.mkdirSync(path.join(ROOT, 'data'), { recursive: true });
+      fs.writeFileSync(path.join(ROOT, 'data/cues.json'), JSON.stringify({ duration: dur, cues }, null, 1));
+      console.log(`data/cues.json: ${cues.length} cues, ${dur.toFixed(2)} s`);
+    } else if (mode === 'frames') {
+      const dir = path.resolve(ROOT, rest[0] || 'review/frames'); fs.mkdirSync(dir, { recursive: true });
+      for (const t of (rest[1] || '0').split(',').map(Number)) { fs.writeFileSync(path.join(dir, `t${t.toFixed(2)}.jpg`), jpg(await P.ev(FRAME(t, 0.92)))); }
+      console.log(dir);
+    } else if (mode === 'sheet') {
+      const out = path.resolve(ROOT, rest[0] || 'review/all.jpg'), step = +(rest[1] || 0.5), cols = +(rest[2] || 9);
+      const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'fs-sheet-')); let n = 0;
+      for (let t = step / 2; t < dur; t += step) fs.writeFileSync(path.join(tmp, `f${String(n++).padStart(4, '0')}.jpg`), jpg(await P.ev(FRAME(t, 0.8, true))));
+      const rows = Math.ceil(n / cols); fs.mkdirSync(path.dirname(out), { recursive: true });
+      const r = spawnSync('ffmpeg', ['-v', 'error', '-y', '-framerate', '1', '-i', path.join(tmp, 'f%04d.jpg'), '-vf', `scale=216:384,tile=${cols}x${rows}:padding=4:color=black`, '-frames:v', '1', '-q:v', '3', out]);
+      fs.rmSync(tmp, { recursive: true, force: true });
+      if (r.status) throw new Error('ffmpeg: ' + r.stderr); console.log(`${out} (${n} frames, every ${step} s)`);
+    } else if (mode === 'video') {
+      const out = path.resolve(ROOT, rest[0] || 'renders/video.mp4'); fs.mkdirSync(path.dirname(out), { recursive: true });
+      const mix = path.join(ROOT, 'data/mix.wav'), hasMix = fs.existsSync(mix), a0 = rest[1] ? +rest[1] : 0, a1 = rest[2] ? Math.min(+rest[2], dur) : dur, n = Math.round((a1 - a0) * FPS);
+      const ff = spawn('ffmpeg', ['-v', 'error', '-y', '-f', 'image2pipe', '-framerate', String(FPS), '-i', '-',
+        ...(hasMix ? ['-ss', String(a0), '-t', String(a1 - a0), '-i', mix] : ['-f', 'lavfi', '-i', 'anullsrc=r=48000:cl=stereo']), '-map', '0:v', '-map', '1:a',
+        '-c:v', 'libx264', '-preset', flags.has('--draft') ? 'ultrafast' : 'veryfast', '-crf', flags.has('--draft') ? '28' : '18', '-pix_fmt', 'yuv420p',
+        '-c:a', 'aac', '-b:a', '192k', '-shortest', '-movflags', '+faststart', out], { stdio: ['pipe', 'inherit', 'inherit'] });
+      const t0 = Date.now();
+      for (let i = 0; i < n; i++) {
+        const b = jpg(await P.ev(FRAME(a0 + i / FPS, flags.has('--draft') ? 0.8 : 0.93)));
+        if (!ff.stdin.write(b)) await new Promise((r) => ff.stdin.once('drain', r));
+        if (i % 150 === 0) process.stdout.write(`\r${i}/${n} frames`);
+      }
+      ff.stdin.end(); await new Promise((r) => ff.on('close', r));
+      console.log(`\r${out} (${n} frames, ${hasMix ? 'with data/mix.wav' : 'SILENT: no data/mix.wav'}, ${((Date.now() - t0) / 1000).toFixed(0)} s)`);
+    } else console.log('modes: check · cues · sheet · frames · video · preview');
+  } finally { P.close(); srv.close(); }
+}

package/plugins/faceless-shorts/styles/inside-out/example/tools/mix.py

@@ -0,0 +1,172 @@
+"""Inside Out soundtrack: narration + soft procedural sound effects + a quiet music bed, all made here with numpy.
+No samples, no AI audio, no downloads.
+
+  python3 tools/mix.py [project=.]          → data/mix.wav (48 kHz stereo)
+
+Reads data/cues.json (node tools/capture.mjs cues), data/narration.wav if it exists (voice.py or words.py --audio),
+and script.json "music": "bed" (the procedural score, default) · "none" · "audio/your-track.mp3" (your own royalty-free
+track, any format ffmpeg reads). The music ducks under the voice.
+
+Sound rules (STYLE.md): every effect is soft and rounded, nothing above ~5 kHz, no ticks / hats / glitches / beeps.
+Cue types: whoosh slide pop plop gulp boing bubbles sizzle sparkle thud slam tock zip alarm  (+ gain, dur)
+"""
+import json, subprocess, sys
+from pathlib import Path
+import numpy as np
+from scipy import signal
+from scipy.io import wavfile
+
+P = Path(sys.argv[1] if len(sys.argv) > 1 else '.')
+SR = 48000
+rng = np.random.default_rng(11)
+cj = json.loads((P / 'data/cues.json').read_text())
+script = json.loads((P / 'script.json').read_text())
+DUR = float(cj['duration'])
+N = int(DUR * SR) + SR // 10
+
+
+def lp(x, f, o=2): b, a = signal.butter(o, min(f, SR / 2 - 100) / (SR / 2), 'low'); return signal.lfilter(b, a, x)
+def hp(x, f, o=2): b, a = signal.butter(o, f / (SR / 2), 'high'); return signal.lfilter(b, a, x)
+def bp(x, f0, f1, o=2): b, a = signal.butter(o, [f0 / (SR / 2), f1 / (SR / 2)], 'band'); return signal.lfilter(b, a, x)
+def db(x): return 10 ** (x / 20)
+def tt(d): return np.arange(int(d * SR)) / SR
+def env(n, a=0.005, r=None):
+    """attack a seconds then exponential release over the rest"""
+    e = np.ones(n); na = max(1, int(a * SR)); e[:na] = np.linspace(0, 1, na)
+    rest = n - na; e[na:] = np.exp(-np.linspace(0, r or 5, rest)) if rest > 0 else 1; return e
+def sweep(f0, f1, d, shape='exp'):
+    t = tt(d); f = f0 * (f1 / f0) ** (t / d) if shape == 'exp' else f0 + (f1 - f0) * t / d
+    return np.sin(2 * np.pi * np.cumsum(f) / SR)
+def noise(d): return rng.standard_normal(int(d * SR))
+
+
+# ---------- the effects ----------
+def whoosh(d=0.38, **_):
+    n = noise(d); lo, hi = lp(n, 500), lp(n, 2200)
+    k = np.sin(np.pi * np.linspace(0, 1, len(n))); x = (lo * (1 - k) + hi * k) * k ** 1.5
+    return x / (np.abs(x).max() + 1e-9) * 0.5
+def slide(d=1.0, **_):
+    n = lp(noise(d), 700); e = np.sin(np.pi * np.linspace(0, 1, len(n))) ** 2
+    return n / (np.abs(n).max() + 1e-9) * e * 0.35 + sweep(260, 120, d) * e * 0.08
+def pop(**_): x = sweep(560, 240, 0.11) * env(int(0.11 * SR), 0.002, 6); return lp(x, 3000) * 0.7
+def plop(**_): x = sweep(700, 180, 0.14) * env(int(0.14 * SR), 0.002, 5); return lp(x, 2500) * 0.6
+def gulp(**_):
+    a = sweep(320, 140, 0.16) * env(int(0.16 * SR), 0.01, 4); b = sweep(240, 90, 0.2) * env(int(0.2 * SR), 0.01, 4)
+    x = np.concatenate([a, np.zeros(int(0.04 * SR)), b]); return lp(x, 1800) * 0.8
+def boing(**_):
+    d = 0.42; t = tt(d); f = 200 * (1 + 0.6 * t / d) * (1 + 0.08 * np.sin(2 * np.pi * 18 * t))
+    return lp(np.sin(2 * np.pi * np.cumsum(f) / SR) * env(len(t), 0.004, 4), 2000) * 0.55
+def bubbles(d=2.0, **_):
+    x = np.zeros(int(d * SR))
+    for _ in range(int(d * 7)):
+        st = rng.integers(0, max(1, len(x) - int(0.08 * SR))); f = rng.uniform(380, 900); b = sweep(f, f * 1.6, 0.06) * env(int(0.06 * SR), 0.003, 5)
+        x[st:st + len(b)] += b * rng.uniform(0.2, 0.5)
+    return lp(x, 2500) * 0.5
+def sizzle(d=1.0, **_):
+    n = bp(noise(d), 1800, 4500); crack = (rng.random(len(n)) < 0.002).astype(float); crack = lp(crack, 300) * 40
+    e = np.minimum(1, np.linspace(0, 6, len(n))) * np.linspace(1, 0.2, len(n)); return n * (0.4 + crack) * e * 0.12
+def sparkle(d=1.2, **_):
+    notes = [784, 880, 1047, 1175, 1319, 1568]; x = np.zeros(int(d * SR) + SR // 2)
+    for k, f in enumerate(notes):
+        st = int(k * d / len(notes) * SR); n = int(0.4 * SR); t = tt(0.4)
+        x[st:st + n] += (np.sin(2 * np.pi * f * t) + 0.3 * np.sin(4 * np.pi * f * t)) * env(n, 0.004, 6) * 0.22
+    return lp(x, 4500)
+def thud(**_):
+    d = 0.35; t = tt(d); x = np.sin(2 * np.pi * (70 + 40 * np.exp(-t * 30)) * t) * env(len(t), 0.002, 7)
+    return x * 0.9 + lp(noise(d), 220) * env(len(t), 0.001, 12) * 0.3
+def slam(**_):
+    d = 0.5; t = tt(d); x = np.sin(2 * np.pi * (60 + 60 * np.exp(-t * 25)) * t) * env(len(t), 0.002, 6)
+    return np.tanh(1.6 * (x + lp(noise(d), 1200) * env(len(t), 0.001, 10) * 0.6)) * 0.9
+def tock(**_): d = 0.09; t = tt(d); return (np.sin(2 * np.pi * 420 * t) + 0.3 * np.sin(2 * np.pi * 840 * t)) * env(len(t), 0.001, 9) * 0.35
+def zip_(**_):
+    d = 0.32; n = bp(noise(d), 400, 3000); k = np.linspace(0, 1, len(n))
+    return (n / (np.abs(n).max() + 1e-9) * 0.35 + sweep(300, 1100, d) * 0.12) * np.sin(np.pi * k) ** 1.2
+def alarm(d=2.0, **_):
+    x = np.zeros(int(d * SR)); one = np.sin(2 * np.pi * 150 * tt(0.22)) * env(int(0.22 * SR), 0.02, 5)
+    for st in np.arange(0, d - 0.25, 0.5): i = int(st * SR); x[i:i + len(one)] += one
+    return lp(x, 900) * 0.55
+
+def inhale(d=1.0, **_):
+    n = bp(noise(d), 300, 2600); k = np.linspace(0, 1, len(n)); e = np.sin(np.pi * np.minimum(1, k * 1.15)) ** 1.5 * (0.6 + 0.4 * k)
+    return n / (np.abs(n).max() + 1e-9) * e * 0.5
+def heartbeat(**_):
+    one = lambda d, f: np.sin(2 * np.pi * f * tt(d)) * env(int(d * SR), 0.004, 7)
+    x = np.concatenate([one(0.16, 58), np.zeros(int(0.09 * SR)), one(0.2, 52) * 0.75]); return lp(x, 300) * 1.0
+
+FX = dict(inhale=inhale, heartbeat=heartbeat, whoosh=whoosh, slide=slide, pop=pop, plop=plop, gulp=gulp, boing=boing, bubbles=bubbles, sizzle=sizzle,
+          sparkle=sparkle, thud=thud, slam=slam, tock=tock, zip=zip_, alarm=alarm)
+LEVEL = dict(inhale=-15, heartbeat=-8, whoosh=-17, slide=-19, pop=-14, plop=-15, gulp=-11, boing=-15, bubbles=-21, sizzle=-18, sparkle=-17,
+             thud=-11, slam=-9, tock=-18, zip=-14, alarm=-17)
+
+
+# ---------- the music bed: soft pad + plucked arpeggio, 100 BPM, I–vi–IV–V ----------
+def music_bed():
+    bpm = 100; beat = 60 / bpm; bar = beat * 4
+    chords = [[261.6, 329.6, 392.0], [220.0, 261.6, 329.6], [174.6, 220.0, 261.6], [196.0, 246.9, 293.7]]
+    x = np.zeros(N)
+    nb = int(np.ceil(DUR / bar)) + 1
+    for b in range(nb):
+        ch = chords[b % 4]; st = int(b * bar * SR); n = int(bar * SR)
+        if st >= N: break
+        t = tt(bar); e = np.minimum(1, t / 0.4) * np.minimum(1, (bar - t) / 0.4)
+        pad = sum(np.sin(2 * np.pi * f / 2 * t) + 0.25 * np.sin(2 * np.pi * f * t) for f in ch) * e * 0.10
+        x[st:st + n] += pad[:max(0, min(n, N - st))]
+        for k in range(8):                                                       # eighth-note pluck arpeggio
+            f = ch[[0, 1, 2, 1, 2, 0, 1, 2][k]] * (2 if k % 4 == 2 else 1); ps = st + int(k * beat / 2 * SR); pn = int(0.5 * SR)
+            if ps + pn >= N: continue
+            pt = tt(0.5); pl = (np.sin(2 * np.pi * f * pt) + 0.35 * np.sin(4 * np.pi * f * pt)) * env(pn, 0.003, 7) * 0.12
+            x[ps:ps + pn] += pl
+    x = lp(x, 3200)
+    fade = np.ones(N); fo = int(1.2 * SR); fade[-fo:] = np.linspace(1, 0, fo)
+    return x / (np.abs(x).max() + 1e-9) * fade
+
+def music_tension():
+    """low drone + slow minor pulse, for mysterious / tense explainers (script.json "music": "tension")"""
+    t = np.arange(N) / SR; x = np.zeros(N)
+    for f, g in [(55, 0.5), (82.4, 0.3), (110, 0.2), (130.8, 0.12)]: x += np.sin(2 * np.pi * f * t + np.sin(t * 0.3) * 0.5) * g
+    x *= 0.55 + 0.45 * np.sin(2 * np.pi * t / 8) ** 2
+    beat = 60 / 84; ping = lambda f: (np.sin(2 * np.pi * f * tt(1.2)) + 0.3 * np.sin(4 * np.pi * f * tt(1.2))) * env(int(1.2 * SR), 0.01, 5)
+    seq = [220.0, 261.6, 196.0, 174.6]
+    for k in range(int(DUR / (beat * 2))):
+        i = int(k * beat * 2 * SR); pg = ping(seq[(k // 2) % 4]) * 0.35
+        if i + len(pg) < N: x[i:i + len(pg)] += pg
+    x = lp(x, 2200); fade = np.ones(N); fo = int(1.5 * SR); fade[-fo:] = np.linspace(1, 0, fo); fi = int(0.8 * SR); fade[:fi] *= np.linspace(0, 1, fi)
+    return x / (np.abs(x).max() + 1e-9) * fade
+
+def load_audio(f):
+    out = subprocess.run(['ffmpeg', '-v', 'error', '-i', str(f), '-f', 'f32le', '-ac', '2', '-ar', str(SR), '-'], capture_output=True, check=True).stdout
+    a = np.frombuffer(out, dtype=np.float32).reshape(-1, 2).astype(np.float64); return a
+
+
+mix = np.zeros((N, 2))
+# voice
+vf = P / 'data/narration.wav'
+voice = None
+if vf.exists():
+    v = load_audio(vf)[:N]; voice = np.zeros((N, 2)); voice[:len(v)] = v
+    rms = np.sqrt(np.mean(voice ** 2) + 1e-12); voice *= db(-19) / rms
+    mix += voice
+# music
+mus = script.get('music', 'bed')
+if mus and mus != 'none':
+    m = music_bed() if mus == 'bed' else music_tension() if mus == 'tension' else None
+    if m is None:
+        a = load_audio(P / mus)[:N]; m = np.zeros(N); m[:len(a)] = a.mean(1); m /= np.abs(m).max() + 1e-9
+    m = np.stack([m, m], 1) * db(-24 if voice is not None else -20)
+    if voice is not None:                                                        # duck under the voice
+        lev = np.abs(voice.mean(1)); lev = signal.lfilter([1 - 0.9995], [1, -0.9995], lev); lev /= lev.max() + 1e-9
+        m *= (1 - 0.55 * np.clip(lev * 3, 0, 1))[:, None]
+    mix += m
+# effects
+for c in cj['cues']:
+    fn = FX.get(c['type'])
+    if not fn: print('unknown cue type, skipped:', c['type']); continue
+    x = fn(**({'d': c['dur']} if c.get('dur') else {}))
+    x = lp(x, 5000) * db(LEVEL[c['type']]) * c.get('gain', 1.0) / (np.abs(x).max() + 1e-9) * 0.9
+    i = int(c['t'] * SR); n = min(len(x), N - i)
+    if n > 0 and i >= 0: pan = c.get('pan', 0.0); mix[i:i + n, 0] += x[:n] * (1 - max(0, pan)); mix[i:i + n, 1] += x[:n] * (1 + min(0, pan))
+# master: gentle soft-clip, peak -1 dBFS
+mix = np.tanh(mix * 1.2) / 1.2
+mix *= db(-1) / (np.abs(mix).max() + 1e-9)
+wavfile.write(P / 'data/mix.wav', SR, (mix * 32767).astype(np.int16))
+print(f"data/mix.wav: {DUR:.2f} s · voice: {'yes' if voice is not None else 'NO (captions-only)'} · music: {mus} · {len(cj['cues'])} cues")

package/plugins/faceless-shorts/styles/night-file/STYLE.md

@@ -0,0 +1,36 @@
+# Night File 3D: unsolved mysteries and true crime, 9:16
+
+Quiet, uneasy, investigative. Dark 3D places with ONE light source, faceless people: witnesses are near-black with a
+thin red rim light, the person the story is about glows solid red. Typewriter dates and captions, evidence inserts
+(case files, tickets, polaroids, red circles), film grain, slow camera.
+Example: `example/` = **THE MAN WHO JUMPED OUT OF A PLANE** (D.B. Cooper, 1971; 36 s, 11 shots). Sheet: `style-sheet.png`.
+
+## 1. Rules
+- One light per scene; everything else falls into darkness. Lamps come with a soft visible light cone.
+- **Red means the subject.** Nothing else on screen is red except evidence marks (red circle, UNSOLVED stamp, string).
+- No faces, no gore, no weapons shown (mention them in words only if the record needs it). Real cases: facts checked
+  against primary sources (FBI, court records, major outlets) and listed in `script.json` "sources"; treat victims and
+  families with respect; never accuse a real living person.
+- Slow: 3-5 s shots, push-ins and drifts. Pauses between sentences are longer (`gap` 0.4).
+- Captions: FreeMono typewriter, sentence case, 2-5 words, cream with one red word, typed on letter by letter (y 1560).
+- Dates type on top-left: `K.dateStamp('NOV 24, 1971', 'FLIGHT 305 · PORTLAND', p, 80, 300)`.
+- Narration: low and calm, `am_onyx` x0.95. Music `"tension"`.
+
+## 2. Engine map (`example/src/`)
+The 3D core (`engine.js`, `sdf.js`, `human.js`) is shared with Deep Dive 3D (see its STYLE.md). Night File adds:
+| file | gives you |
+|---|---|
+| `core/sets3d.js` | `corridor()`, `houseNight()`, `caseWall(photoCanvases)`, `planeCabin()` (`.update(t, { door, rain, flash })`); `witnessMat()`, `subjectMat()`, `lightCone()` |
+| `core/kit.js` | 2D evidence inserts: `caseFile(x, y, s, label, stamp)`, `polaroid(x, y, s, rot, 'glow'│'dark'│'house')`, `clock`, `cassette`, `marker`, `redacted`, `redCircle(x, y, rx, ry, p)`, `dateStamp`, `captionMono`, `filmLook` |
+People: `new Human({ face: false })` then `.setAllMaterial(SETS.subjectMat())` or `witnessMat()`. Sitting: hips y 0.66,
+`hipL/hipR [88, 0, 2]`, `knL/knR 88`.
+
+## 3. Story shape
+Date + place → the person (subject glowing) → the strange event, step by step, each step an evidence insert or a slow
+3D shot → the moment it goes wrong (one hard sound) → what was found later (case wall, date) → the open question,
+UNSOLVED stamp. End on silence and the drone.
+
+## 4. QA pitfalls we've hit
+- Camera inside a light cone = flat brown frame. Seats or walls between camera and subject = blocked view.
+- Too-tight framing on a dark doorway reads as an empty frame: use a wider lens (`fov: 58`) for dark spaces.
+- Rendering speed: see Deep Dive STYLE.md section 5.