paper-motion 0.0.0-stage → 0.2.0

package/lib/server.mjs

@@ -0,0 +1,89 @@
+// Static server for scenes. Injects an import map so scenes can
+// `import { scene } from 'paper-motion'` with no bundler, and live-reloads
+// previews when files change.
+import http from 'node:http';
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { moduleDir } from './modules.mjs';
+
+const ENGINE = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+
+const MIME = {
+  '.html': 'text/html; charset=utf-8', '.js': 'text/javascript; charset=utf-8', '.mjs': 'text/javascript; charset=utf-8',
+  '.css': 'text/css; charset=utf-8', '.json': 'application/json', '.svg': 'image/svg+xml', '.png': 'image/png',
+  '.jpg': 'image/jpeg', '.jpeg': 'image/jpeg', '.webp': 'image/webp', '.gif': 'image/gif', '.avif': 'image/avif',
+  '.woff': 'font/woff', '.woff2': 'font/woff2', '.ttf': 'font/ttf', '.otf': 'font/otf',
+  '.mp4': 'video/mp4', '.webm': 'video/webm', '.mov': 'video/quicktime', '.mp3': 'audio/mpeg', '.wav': 'audio/wav', '.map': 'application/json',
+};
+
+const IMPORT_MAP = {
+  imports: {
+    'paper-motion': '/__pm/runtime/index.js',
+    'paper-motion/moves': '/__pm/runtime/moves.js',
+    'paper-motion/kit': '/__pm/runtime/kit.js',
+    'paper-motion/brand': '/__pm/runtime/brand.js',
+    '@paper-design/shaders': '/__pm/node_modules/@paper-design/shaders/dist/index.js',
+    '@paper-design/shaders-react': '/__pm/node_modules/@paper-design/shaders-react/dist/index.js',
+    react: '/__pm/runtime/react-shim.js',
+    'react/jsx-runtime': '/__pm/runtime/jsx-shim.js',
+  },
+};
+
+const RELOAD_CLIENT = `<script>(()=>{if(location.search.includes('render'))return;
+const es=new EventSource('/__pm/events');es.onmessage=()=>location.reload();})();</script>`;
+
+export function startServer({ root, port = 0, watch = false }) {
+  const clients = new Set();
+  const server = http.createServer((req, res) => {
+    const url = new URL(req.url, 'http://x');
+    let p = decodeURIComponent(url.pathname);
+    if (p === '/__pm/events') {
+      res.writeHead(200, { 'content-type': 'text/event-stream', 'cache-control': 'no-cache', connection: 'keep-alive' });
+      res.write(': ok\n\n');
+      clients.add(res);
+      req.on('close', () => clients.delete(res));
+      return;
+    }
+    if (p === '/favicon.ico') { res.writeHead(204).end(); return; }
+    let file;
+    if (p.startsWith('/__pm/runtime/')) file = path.join(ENGINE, 'runtime', p.slice('/__pm/runtime/'.length));
+    let base = p.startsWith('/__pm/') ? ENGINE : root;
+    if (p.startsWith('/__pm/node_modules/')) {
+      // '/__pm/node_modules/@scope/pkg/dist/x.js' → wherever npm put @scope/pkg
+      const rest = p.slice('/__pm/node_modules/'.length).split('/'), n = rest[0].startsWith('@') ? 2 : 1;
+      base = moduleDir(rest.slice(0, n).join('/')) ?? path.join(ENGINE, 'node_modules', ...rest.slice(0, n));
+      file = path.join(base, ...rest.slice(n));
+    } else if (!file) file = path.join(root, p);
+    if (!path.resolve(file).startsWith(path.resolve(base))) { res.writeHead(403).end(); return; }
+    fs.stat(file, (err, st) => {
+      if (!err && st.isDirectory()) { file = path.join(file, 'index.html'); }
+      fs.readFile(file, (e, buf) => {
+        if (e) { res.writeHead(404, { 'content-type': 'text/plain' }).end(`not found: ${p}`); return; }
+        const ext = path.extname(file).toLowerCase();
+        const headers = { 'content-type': MIME[ext] ?? 'application/octet-stream', 'cache-control': 'no-store', 'access-control-allow-origin': '*' };
+        if (ext === '.html') {
+          let html = buf.toString('utf8');
+          const inject = `<script type="importmap">${JSON.stringify(IMPORT_MAP)}</script>${watch ? RELOAD_CLIENT : ''}`;
+          html = /<head[^>]*>/i.test(html) ? html.replace(/<head[^>]*>/i, (m) => m + inject) : inject + html;
+          res.writeHead(200, headers).end(html);
+        } else res.writeHead(200, headers).end(buf);
+      });
+    });
+  });
+
+  if (watch) {
+    let timer;
+    try {
+      fs.watch(root, { recursive: true }, (_e, f) => {
+        if (!f || /(^|[\\/])(node_modules|renders|stills|\.git)([\\/]|$)/.test(f) || /\.(mp4|mov|webm|gif)$/.test(f)) return;
+        clearTimeout(timer);
+        timer = setTimeout(() => { for (const c of clients) c.write('data: reload\n\n'); }, 120);
+      });
+    } catch { /* recursive watch unsupported: no live reload */ }
+  }
+
+  return new Promise((resolve) => {
+    server.listen(port, '127.0.0.1', () => resolve({ server, port: server.address().port, close: () => new Promise((r) => { for (const c of clients) c.end(); server.close(r); }) }));
+  });
+}

package/lib/sfx.mjs

@@ -0,0 +1,287 @@
+// Deterministic sound-effects synthesizer. Scenes declare cues with
+// s.sfx(t, type, opts); the renderer synthesizes them into a WAV and muxes it.
+// Everything is generated from code (no samples) and seeded, so the same scene
+// always produces the same audio.
+import fs from 'node:fs';
+import { loadBank } from './keys.mjs';
+
+const SR = 48000;
+
+function mulberry32(seed) {
+  let a = seed >>> 0;
+  return () => {
+    a |= 0; a = (a + 0x6d2b79f5) | 0;
+    let t = Math.imul(a ^ (a >>> 15), 1 | a);
+    t = (t + Math.imul(t ^ (t >>> 7), 61 | t)) ^ t;
+    return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+  };
+}
+
+// RBJ biquad
+class Biquad {
+  constructor(type, freq, q = 0.707, gainDb = 0) {
+    const w = (2 * Math.PI * Math.min(freq, SR * 0.45)) / SR, cos = Math.cos(w), alpha = Math.sin(w) / (2 * q);
+    const A = 10 ** (gainDb / 40);
+    let b0, b1, b2, a0, a1, a2;
+    a0 = 1 + alpha; a1 = -2 * cos; a2 = 1 - alpha;
+    if (type === 'lowpass') { b0 = (1 - cos) / 2; b1 = 1 - cos; b2 = b0; }
+    else if (type === 'highpass') { b0 = (1 + cos) / 2; b1 = -(1 + cos); b2 = b0; }
+    else if (type === 'peak') { b0 = 1 + alpha * A; b1 = -2 * cos; b2 = 1 - alpha * A; a0 = 1 + alpha / A; a2 = 1 - alpha / A; }
+    else if (type === 'highshelf') {
+      const sq = 2 * Math.sqrt(A) * alpha;
+      b0 = A * ((A + 1) + (A - 1) * cos + sq); b1 = -2 * A * ((A - 1) + (A + 1) * cos); b2 = A * ((A + 1) + (A - 1) * cos - sq);
+      a0 = (A + 1) - (A - 1) * cos + sq; a1 = 2 * ((A - 1) - (A + 1) * cos); a2 = (A + 1) - (A - 1) * cos - sq;
+    }
+    else { b0 = alpha; b1 = 0; b2 = -alpha; } // bandpass, 0 dB peak
+    this.b = [b0 / a0, b1 / a0, b2 / a0]; this.a = [a1 / a0, a2 / a0];
+    this.x1 = this.x2 = this.y1 = this.y2 = 0;
+  }
+  process(x) {
+    const y = this.b[0] * x + this.b[1] * this.x1 + this.b[2] * this.x2 - this.a[0] * this.y1 - this.a[1] * this.y2;
+    this.x2 = this.x1; this.x1 = x; this.y2 = this.y1; this.y1 = y;
+    return y;
+  }
+}
+
+const TAU = Math.PI * 2;
+const smooth = (x) => (x <= 0 ? 0 : x >= 1 ? 1 : x * x * (3 - 2 * x));
+
+/**
+ * Voices. Each returns { len (s), fn(i, sr) -> sample } — mono; panning is applied by the mixer.
+ * All of them are dark by design; the master low-pass (default 2 kHz) guarantees no harsh highs.
+ */
+const VOICES = {
+  // Continuous low bed. { dur, freq=55, gain=0.05, attack=3, release=4 }
+  drone({ dur = 10, freq = 55, gain = 0.05, attack = 3, release = 4 }, rnd) {
+    const lp = new Biquad('lowpass', 260), ph = [rnd(), rnd(), rnd(), rnd()].map((p) => p * TAU);
+    return { len: dur, fn: (i) => {
+      const t = i / SR;
+      const env = smooth(t / attack) * smooth((dur - t) / release);
+      const am = 1 + 0.18 * Math.sin(TAU * 0.07 * t + ph[0]);
+      const tone = Math.sin(TAU * freq * t + ph[1]) + 0.5 * Math.sin(TAU * freq * 1.5 * t + ph[2]) + 0.3 * Math.sin(TAU * freq * 2 * t + ph[3]);
+      const air = lp.process(rnd() * 2 - 1) * 0.9;
+      return gain * env * (tone * 0.6 * am + air);
+    } };
+  },
+  // Slow chord pad: root, fifth, octave. { dur=4, freq=73.4, gain=0.1 }
+  swell({ dur = 4, freq = 73.4, gain = 0.1 }) {
+    const parts = [[1, 1], [1.5, 0.55], [2, 0.4], [1.003, 0.6], [1.497, 0.3]];
+    return { len: dur, fn: (i) => {
+      const t = i / SR, p = t / dur;
+      const env = p < 0.45 ? Math.sin((p / 0.45) * Math.PI / 2) ** 2 : Math.cos(((p - 0.45) / 0.55) * Math.PI / 2) ** 2;
+      let s = 0; for (const [r, a] of parts) s += a * Math.sin(TAU * freq * r * t);
+      return gain * env * s * 0.35;
+    } };
+  },
+  // Pen / pencil writing on paper: band-limited noise with stroke rhythm. { dur=1, gain=0.12, rate=7 }
+  pen({ dur = 1, gain = 0.12, rate = 7, tone = 520 }, rnd) {
+    const bp = new Biquad('bandpass', tone, 0.7), lp = new Biquad('lowpass', 1100);
+    const r = rate * (0.85 + 0.3 * rnd()), ph = rnd() * TAU;
+    return { len: dur, fn: (i) => {
+      const t = i / SR;
+      const env = smooth(t / 0.025) * smooth((dur - t) / 0.05);
+      const stroke = 0.35 + 0.65 * Math.abs(Math.sin(TAU * r * t + ph + 0.6 * Math.sin(TAU * 1.3 * t))) ** 1.6;
+      return gain * env * stroke * lp.process(bp.process(rnd() * 2 - 1)) * 2.2;
+    } };
+  },
+  // Paper movement / whoosh. { dur=0.8, gain=0.14 }
+  paper({ dur = 0.8, gain = 0.14 }, rnd) {
+    const lp = new Biquad('lowpass', 650), hp = new Biquad('highpass', 90), lp2 = new Biquad('lowpass', 900);
+    return { len: dur, fn: (i) => {
+      const t = i / SR, p = t / dur;
+      const env = Math.sin(Math.PI * Math.min(1, p)) ** 2;
+      const crackle = rnd() < 0.002 ? (rnd() * 2 - 1) * 3 : 0;
+      return gain * (env * hp.process(lp.process(rnd() * 2 - 1)) * 1.8 + env * lp2.process(crackle) * 0.6);
+    } };
+  },
+  // Soft low stamp / body hit. { freq=62, gain=0.5, decay=0.45 }
+  thud({ freq = 62, gain = 0.5, decay = 0.45 }, rnd) {
+    const lp = new Biquad('lowpass', 320);
+    let phase = 0;
+    return { len: decay * 5, fn: (i) => {
+      const t = i / SR;
+      const f = freq * (1 + 0.8 * Math.exp(-t / 0.035));
+      phase += (TAU * f) / SR;
+      const env = smooth(t / 0.004) * Math.exp(-t / decay);
+      const click = lp.process((rnd() * 2 - 1) * Math.exp(-t / 0.012));
+      return gain * (env * Math.sin(phase) + click * 0.5);
+    } };
+  },
+  // Wooden knock, low. { freq=140, gain=0.3, decay=0.16 }
+  knock({ freq = 140, gain = 0.3, decay = 0.16 }, rnd) {
+    const lp = new Biquad('lowpass', 520);
+    return { len: decay * 6, fn: (i) => {
+      const t = i / SR;
+      const a = smooth(t / 0.002);
+      const body = Math.sin(TAU * freq * t) * Math.exp(-t / decay) + 0.35 * Math.sin(TAU * freq * 2.31 * t) * Math.exp(-t / (decay * 0.4));
+      const n = lp.process((rnd() * 2 - 1) * Math.exp(-t / 0.008));
+      return gain * a * (body + n * 0.6);
+    } };
+  },
+  // Tiny low tick (UI-ish but dull). { freq=200, gain=0.1, decay=0.05 }
+  tick({ freq = 200, gain = 0.1, decay = 0.05 }) {
+    return { len: decay * 6, fn: (i) => { const t = i / SR; return gain * smooth(t / 0.0015) * Math.exp(-t / decay) * Math.sin(TAU * freq * t); } };
+  },
+  // A keystroke, modeled like a real one: the bottom-out impact excites a few inharmonic keycap/plate
+  // resonances plus a low case "thock"; a softer, higher upstroke follows; a hint of room around it.
+  // { gain=0.3, kind='letter'|'space'|'enter', vel=1, style='creamy'|'thock'|'clack' }. Seeded variation.
+  key({ gain = 0.3, kind = 'letter', vel = 1, style = 'creamy', bank }, rnd) {
+    if (bank) {
+      // Real keystrokes: pick a hit from the bank, vary level and pitch slightly so no two repeat exactly.
+      const pool = (kind === 'space' || kind === 'enter') ? bank.heavy : bank.letter;
+      const src = pool[Math.floor(rnd() * pool.length) % pool.length];
+      const rate = 0.98 + 0.04 * rnd(), g = gain * vel * (0.82 + 0.3 * rnd()) * (kind === 'enter' ? 1.15 : 1);
+      const len = src.length / rate / SR;
+      return { len, bright: true, fn: (i) => {
+        const p = i * rate, j = Math.floor(p), x = p - j;
+        const y0 = src[j - 1] ?? 0, y1 = src[j] ?? 0, y2 = src[j + 1] ?? 0, y3 = src[j + 2] ?? 0;
+        const soft = Math.min(1, i / (0.0035 * SR)); // a 3.5 ms rise rounds off the hardest edge of the click
+        return g * soft * (y1 + 0.5 * x * (y2 - y0 + x * (2 * y0 - 5 * y1 + 4 * y2 - y3 + x * (3 * (y1 - y2) + y3 - y0))));
+      } };
+    }
+    const S = {
+      thock:  { modes: [[620, 0.016, 1], [1040, 0.011, 0.7], [1580, 0.008, 0.45], [2350, 0.006, 0.25]], body: [170, 0.026, 1.1], burst: 0.0009, up: 0.32 },
+      creamy: { modes: [[780, 0.013, 1], [1290, 0.010, 0.75], [1960, 0.007, 0.5], [2900, 0.005, 0.3]], body: [210, 0.020, 0.8], burst: 0.0007, up: 0.4 },
+      clack:  { modes: [[1150, 0.010, 0.8], [1850, 0.008, 1], [2750, 0.006, 0.7], [3900, 0.004, 0.4]], body: [260, 0.014, 0.5], burst: 0.0005, up: 0.5 },
+    }[style] ?? null;
+    if (!S) throw new Error(`key style "${style}": use creamy, thock or clack`);
+    const heavy = kind === 'space' || kind === 'enter';
+    const pitch = (heavy ? (kind === 'space' ? 0.72 : 0.84) : 1) * (0.93 + 0.14 * rnd());
+    const len = 0.26, N = Math.ceil(len * SR), buf = new Float32Array(N);
+    // one strike: noise burst + click into a bank of ringing band-passes (Q from the decay time)
+    const strike = (at, amp, fMul) => {
+      const bank = S.modes.map(([f, tau, g]) => {
+        const fr = f * pitch * fMul * (0.96 + 0.08 * rnd());
+        return { bq: new Biquad('bandpass', fr, Math.max(2, Math.PI * fr * tau * (heavy ? 1.3 : 1))), g: g * (0.8 + 0.4 * rnd()) };
+      });
+      const [bf, btau, bg] = S.body;
+      const body = new Biquad('bandpass', bf * pitch * (0.95 + 0.1 * rnd()), Math.PI * bf * btau * (heavy ? 1.5 : 1));
+      const hp = new Biquad('highpass', 400);
+      const i0 = Math.round(at * SR), burst = S.burst * (heavy ? 1.6 : 1);
+      for (let i = i0; i < N; i++) {
+        const t = (i - i0) / SR;
+        const ex = t < burst * 6 ? (rnd() * 2 - 1) * Math.exp(-t / burst) + (i === i0 ? 3 : 0) : 0;
+        let y = 0;
+        for (const m of bank) y += m.bq.process(ex) * m.g;
+        y += body.process(ex) * bg * 1.6;
+        y += hp.process(ex) * 0.12; // the contact "tick" itself
+        buf[i] += amp * y;
+      }
+    };
+    const pre = 0.004 + 0.008 * rnd();                // finger meets the cap
+    strike(0, 0.08, 1.35);
+    strike(pre, 1, 1);                                 // bottom-out
+    if (kind === 'space') strike(pre + 0.007 + 0.005 * rnd(), 0.35, 1.25); // stabilizer rattle
+    strike(pre + (heavy ? 0.11 : 0.075) + 0.035 * rnd(), S.up * (0.8 + 0.4 * rnd()), 1.18); // upstroke
+    // a little room: two early reflections
+    for (const [d, k] of [[0.0071, 0.16], [0.0133, 0.09]]) { const o = Math.round(d * SR); for (let i = N - 1; i >= o; i--) buf[i] += buf[i - o] * k; }
+    let peak = 1e-9; for (let i = 0; i < N; i++) peak = Math.max(peak, Math.abs(buf[i]));
+    const g = (gain * vel * (0.8 + 0.3 * rnd()) * (heavy ? 1.2 : 1)) / peak;
+    return { len, bright: true, fn: (i) => buf[i] * g };
+  },
+  // Air moving past: a pass-by whoosh. The band sweeps from→to→back while the level peaks at `peak`.
+  // { dur=0.7, gain=0.2, from=320, to=1200, peak=0.6, body=0 (low weight under it, 0..1) }
+  whoosh({ dur = 0.7, gain = 0.2, from = 320, to = 1200, peak = 0.6, body = 0 }, rnd) {
+    // state-variable filters so the centre frequency can move every sample
+    const svf = () => { let low = 0, band = 0; return (x, fc, q) => { const f = 2 * Math.sin(Math.PI * Math.min(fc, SR / 6) / SR); low += f * band; const high = x - low - q * band; band += f * high; return band; }; };
+    const A = svf(), B = svf();
+    let pink = 0, flut = 0;
+    const ph = rnd() * TAU, bf = 52 + 14 * rnd();
+    return { len: dur, fn: (i) => {
+      const t = i / SR, p = t / dur;
+      const env = p < peak ? smooth(p / peak) ** 1.6 : Math.cos(((p - peak) / (1 - peak)) * Math.PI / 2) ** 2;
+      const fc = p < peak ? from * (to / from) ** smooth(p / peak) : to * ((from * 0.8) / to) ** ((p - peak) / (1 - peak));
+      const w = rnd() * 2 - 1;
+      pink = 0.8 * pink + 0.2 * w; // gentle tilt, still airy
+      flut = 0.9995 * flut + 0.0005 * (rnd() * 2 - 1);
+      const n = pink * 1.6;
+      const air = A(n, fc, 0.9) + 0.5 * B(n, fc * 1.6, 1.1);
+      const low = body * Math.sin(TAU * bf * t + ph) * env * 0.5;
+      return gain * env * (air * (1 + flut * 60) * 1.4 + low);
+    } };
+  },
+  // A small card/paper flick (something light landing). { gain=0.12 }
+  flick({ gain = 0.12 }, rnd) {
+    const bp = new Biquad('bandpass', 700 + 500 * rnd(), 0.9), lp = new Biquad('lowpass', 1600);
+    const f = 160 + 80 * rnd();
+    return { len: 0.12, fn: (i) => {
+      const t = i / SR;
+      const n = lp.process(bp.process(rnd() * 2 - 1)) * Math.exp(-t / 0.012) * 2.4;
+      const k = Math.sin(TAU * f * t) * Math.exp(-t / 0.02) * smooth(t / 0.001) * 0.5;
+      return gain * (0.75 + 0.5 * rnd()) * (n + k);
+    } };
+  },
+  // Pitch glide. { dur=0.6, from=160, to=80, gain=0.08 }
+  sweep({ dur = 0.6, from = 160, to = 80, gain = 0.08 }) {
+    let phase = 0;
+    return { len: dur, fn: (i) => {
+      const t = i / SR, p = t / dur;
+      phase += (TAU * (from + (to - from) * p)) / SR;
+      return gain * Math.sin(Math.PI * p) ** 2 * Math.sin(phase);
+    } };
+  },
+};
+
+export const SFX_TYPES = Object.keys(VOICES);
+
+/**
+ * @param cues     [{ t, type, pan?, seed?, ...voiceOpts }]
+ * @param options  { duration, lowpass=2000, highpass=30, gain=1, peak=0.8, normalize=true }
+ *                  normalize: true scales the mix up or down to `peak`; false keeps the cues' own gains and only
+ *                  limits overs (used when the scene brings its own audio, so effects sit where their gains put them)
+ * @returns { left: Float32Array, right: Float32Array, sampleRate }
+ */
+export function synthesize(cues, { duration, lowpass = 2000, highpass = 30, gain = 1, peak = 0.8, normalize = true } = {}) {
+  const n = Math.ceil(duration * SR);
+  const L = new Float32Array(n), R = new Float32Array(n);
+  // Voices marked `bright` (keys) go through their own, gentler low-pass: a keystroke's click lives at 1–4 kHz.
+  const BL = new Float32Array(n), BR = new Float32Array(n);
+  cues.forEach((c, k) => {
+    const voice = VOICES[c.type];
+    if (!voice) throw new Error(`Unknown sfx type "${c.type}". Use: ${SFX_TYPES.join(', ')}`);
+    const rnd = mulberry32((c.seed ?? k * 7919 + 13) >>> 0);
+    const v = voice(typeof c.bank === 'string' ? { ...c, bank: loadBank(c.bank) } : c, rnd);
+    const start = Math.round(c.t * SR), len = Math.ceil(v.len * SR);
+    const pan = Math.max(-1, Math.min(1, c.pan ?? 0)), gl = Math.cos(((pan + 1) * Math.PI) / 4), gr = Math.sin(((pan + 1) * Math.PI) / 4);
+    for (let i = 0; i < len; i++) {
+      const j = start + i;
+      if (j < 0) continue; if (j >= n) break;
+      const s = v.fn(i);
+      if (v.bright) { BL[j] += s * gl; BR[j] += s * gr; } else { L[j] += s * gl; R[j] += s * gr; }
+    }
+  });
+  // Master: 24 dB/oct low-pass (no harsh highs), high-pass rumble, normalize, soft clip.
+  for (const ch of [L, R]) {
+    const f = [new Biquad('lowpass', lowpass), new Biquad('lowpass', lowpass), new Biquad('highpass', highpass)];
+    for (let i = 0; i < n; i++) ch[i] = f[2].process(f[1].process(f[0].process(ch[i])));
+  }
+  // Keys bus: open on top (no low-pass), a little less box (~450 Hz), more presence and air above 4 kHz.
+  [[BL, L], [BR, R]].forEach(([b, ch]) => {
+    const f = [new Biquad('highpass', 110), new Biquad('peak', 450, 1.0, -3.5), new Biquad('highshelf', 4200, 0.7, 3.5)];
+    for (let i = 0; i < n; i++) ch[i] += f[2].process(f[1].process(f[0].process(b[i])));
+  });
+  let max = 1e-9;
+  for (let i = 0; i < n; i++) max = Math.max(max, Math.abs(L[i]), Math.abs(R[i]));
+  const k = (normalize ? peak / max : Math.min(1, peak / max)) * gain;
+  const fadeOut = Math.min(n, Math.round(0.05 * SR));
+  for (let i = 0; i < n; i++) {
+    const f = i > n - fadeOut ? (n - i) / fadeOut : 1;
+    L[i] = Math.tanh(L[i] * k * 1.1) * f; R[i] = Math.tanh(R[i] * k * 1.1) * f;
+  }
+  return { left: L, right: R, sampleRate: SR };
+}
+
+export function writeWav(file, { left, right, sampleRate }) {
+  const n = left.length, buf = Buffer.alloc(44 + n * 4);
+  buf.write('RIFF', 0); buf.writeUInt32LE(36 + n * 4, 4); buf.write('WAVE', 8);
+  buf.write('fmt ', 12); buf.writeUInt32LE(16, 16); buf.writeUInt16LE(1, 20); buf.writeUInt16LE(2, 22);
+  buf.writeUInt32LE(sampleRate, 24); buf.writeUInt32LE(sampleRate * 4, 28); buf.writeUInt16LE(4, 32); buf.writeUInt16LE(16, 34);
+  buf.write('data', 36); buf.writeUInt32LE(n * 4, 40);
+  const rnd = mulberry32(1);
+  for (let i = 0; i < n; i++) {
+    const d = (rnd() - rnd()) / 32768; // TPDF dither
+    buf.writeInt16LE(Math.max(-32768, Math.min(32767, Math.round((left[i] + d) * 32767))), 44 + i * 4);
+    buf.writeInt16LE(Math.max(-32768, Math.min(32767, Math.round((right[i] + d) * 32767))), 46 + i * 4);
+  }
+  fs.writeFileSync(file, buf);
+}

package/lib/shaderset.mjs

@@ -0,0 +1,65 @@
+// A brand's shader set: entries in brand/shader-set/set.json, one format for all.
+// build → one scene per entry (shots/) and review boards (boards/), from the template's shot.js.
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const ENGINE = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+
+export function readSet(dir) {
+  const file = path.join(dir, 'set.json');
+  if (!fs.existsSync(file)) throw new Error(`No ${file}`);
+  const raw = JSON.parse(fs.readFileSync(file, 'utf8'));
+  // older sets were a plain list of { id, video }
+  const set = Array.isArray(raw) ? { format: { width: 1920, height: 1080, duration: 6, fps: 30 }, entries: raw } : raw;
+  set.format = { width: 1920, height: 1080, duration: 6, fps: 30, ...(set.format ?? {}) };
+  return set;
+}
+
+export function writeSet(dir, set) {
+  fs.writeFileSync(path.join(dir, 'set.json'), JSON.stringify(set, null, 1) + '\n');
+}
+
+const page = (title, call) => `<!doctype html>
+<html>
+<head>
+<meta charset="utf-8">
+<title>${title}</title>
+<style>#stage { overflow: hidden; }</style>
+</head>
+<body>
+<main id="stage"></main>
+<script type="module">
+import { mount } from '../shot.js';
+${call}
+</script>
+</body>
+</html>
+`;
+
+export const shotName = (e, i) => `${String(i + 1).padStart(2, '0')}-${e.id}`;
+
+/** Writes shot.js, shots/<nn>-<id>.html and boards/board-<k>.html (12 per board). Entries without a shader or file are skipped. */
+export function buildSet(dir) {
+  const set = readSet(dir);
+  fs.copyFileSync(path.join(ENGINE, 'templates', 'shader-set', 'shot.js'), path.join(dir, 'shot.js'));
+  for (const sub of ['shots', 'boards']) { fs.rmSync(path.join(dir, sub), { recursive: true, force: true }); fs.mkdirSync(path.join(dir, sub), { recursive: true }); }
+  // shaders that only filter an image need one; say which entry instead of failing inside a render
+  const NEEDS_IMAGE = ['ImageDithering', 'HalftoneDots', 'HalftoneCmyk', 'FlutedGlass', 'LensDistortion', 'LiquidMetal', 'GemSmoke', 'Heatmap'];
+  const skipped = [];
+  const live = set.entries.map((e, i) => ({ e, i })).filter(({ e, i }) => {
+    if (!e.shader && !e.file) { skipped.push(`${i + 1} · ${e.id}: no shader or file`); return false; }
+    if (NEEDS_IMAGE.includes(e.shader) && !e.image) { skipped.push(`${i + 1} · ${e.id}: ${e.shader} filters an image; give it "image" (wordmark, wordmark-dark or a path in brand/)`); return false; }
+    return true;
+  });
+  const F = JSON.stringify(set.format);
+  for (const { e, i } of live) fs.writeFileSync(path.join(dir, 'shots', `${shotName(e, i)}.html`), page(`shader set · ${e.id}`, `await mount([${JSON.stringify(e)}], ${F});`));
+  const boards = [];
+  for (let k = 0; k * 12 < live.length; k++) {
+    const chunk = live.slice(k * 12, k * 12 + 12);
+    const f = path.join(dir, 'boards', `board-${k + 1}.html`);
+    fs.writeFileSync(f, page(`shader set · board ${k + 1}`, `await mount(${JSON.stringify(chunk.map((c) => c.e))}, ${F}, { board: true, numbers: ${JSON.stringify(chunk.map((c) => c.i + 1))} });`));
+    boards.push(f);
+  }
+  return { set, skipped, shots: live.map(({ e, i }) => ({ entry: e, index: i, file: path.join(dir, 'shots', `${shotName(e, i)}.html`) })), boards };
+}

package/lib/wordmark.mjs

@@ -0,0 +1,64 @@
+// Wordmarks: a brand name set in its typeface, rendered to a transparent PNG cropped to the ink
+// (for scenes, logo shaders such as LiquidMetal, and the brand folder).
+import fs from 'node:fs';
+import path from 'node:path';
+import { launch } from './browser.mjs';
+
+const esc = (s) => String(s).replace(/[&<>"]/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;' }[c]));
+
+/**
+ * @param {object} o
+ * @param {string} o.text      the name, already cased as the brand writes it
+ * @param {string} o.family    font family name
+ * @param {string} [o.css]     stylesheet URL that provides the family (e.g. Google Fonts css2)
+ * @param {string} [o.file]    local font file (woff2/ttf/otf), used instead of css
+ * @param {number} [o.weight]  font weight (default 400)
+ * @param {string} [o.tracking] letter-spacing in em, e.g. "-0.02em"
+ * @param {string} [o.color]   fill color (default #ffffff)
+ * @param {number} [o.size]    font size in px (default 400)
+ * @param {number} [o.pad]     transparent margin around the ink, as a fraction of the size (default 0)
+ * @param {string} o.out       output .png path
+ */
+export async function renderWordmark({ text, family, css, file, weight = 400, tracking = '0em', color = '#ffffff', size = 400, pad = 0, out }) {
+  const face = file
+    ? `@font-face { font-family: 'WM'; src: url(data:font/${path.extname(file).slice(1)};base64,${fs.readFileSync(file).toString('base64')}); font-weight: ${weight}; }`
+    : '';
+  const fam = file ? 'WM' : family;
+  const html = `<!doctype html><html><head>${css ? `<link rel="stylesheet" href="${esc(css)}">` : ''}<style>${face}
+    html,body{margin:0;background:transparent}</style></head><body><span style="font-family:'${esc(fam)}';font-weight:${weight}">${esc(text)}</span></body></html>`;
+  const browser = await launch();
+  try {
+    const page = await browser.newPage();
+    await page.setContent(html, { waitUntil: 'networkidle' });
+    const r = await page.evaluate(async ({ fam, weight, size, text, tracking, color, pad }) => {
+      const font = `${weight} ${size}px '${fam}'`;
+      await document.fonts.load(font).catch(() => {});
+      await document.fonts.ready;
+      // fonts.check() is true when no face matches at all, so look for a loaded face of this family instead.
+      if (![...document.fonts].some((f) => f.family.replace(/['"]/g, '') === fam && f.status === 'loaded')) return { error: 'font' };
+      const em = parseFloat(tracking) || 0;
+      // Draw generously, then crop to the exact ink so clear space is a brand rule, not a file accident.
+      const big = document.createElement('canvas');
+      const g = big.getContext('2d');
+      g.font = font; g.letterSpacing = `${em * size}px`;
+      const m = g.measureText(text);
+      big.width = Math.ceil(m.width + size * 2); big.height = Math.ceil(size * 2.4);
+      g.font = font; g.letterSpacing = `${em * size}px`; g.fillStyle = color; g.textBaseline = 'alphabetic';
+      g.fillText(text, size, size * 1.6);
+      const { data, width: W, height: H } = g.getImageData(0, 0, big.width, big.height);
+      let x0 = W, y0 = H, x1 = -1, y1 = -1;
+      for (let y = 0; y < H; y++) for (let x = 0; x < W; x++) if (data[(y * W + x) * 4 + 3] > 0) { if (x < x0) x0 = x; if (x > x1) x1 = x; if (y < y0) y0 = y; if (y > y1) y1 = y; }
+      if (x1 < 0) return { error: 'empty' };
+      const p = Math.round(size * pad);
+      const c = document.createElement('canvas');
+      c.width = x1 - x0 + 1 + p * 2; c.height = y1 - y0 + 1 + p * 2;
+      c.getContext('2d').drawImage(big, x0, y0, x1 - x0 + 1, y1 - y0 + 1, p, p, x1 - x0 + 1, y1 - y0 + 1);
+      return { url: c.toDataURL('image/png'), width: c.width, height: c.height };
+    }, { fam, weight, size, text: String(text), tracking, color, pad });
+    if (r.error === 'font') throw new Error(`wordmark: font "${family}" (${weight}) did not load; check --css / --file`);
+    if (r.error) throw new Error('wordmark: nothing was drawn');
+    fs.mkdirSync(path.dirname(path.resolve(out)), { recursive: true });
+    fs.writeFileSync(out, Buffer.from(r.url.split(',')[1], 'base64'));
+    return { out, width: r.width, height: r.height };
+  } finally { await browser.close(); }
+}

package/package.json

@@ -1,6 +1,48 @@
 {
   "name": "paper-motion",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "description": "Frame-exact video renderer for HTML scenes built with Paper Shaders: the engine behind the paper-motion agent skills.",
+  "keywords": [
+    "video",
+    "motion-graphics",
+    "paper-shaders",
+    "shaders",
+    "render",
+    "ffmpeg",
+    "agent-skills",
+    "claude-code"
+  ],
+  "homepage": "https://github.com/solanodz/paper-motion#readme",
+  "bugs": {
+    "url": "https://github.com/solanodz/paper-motion/issues"
+  },
+  "license": "MIT",
+  "author": "Solano de Zuasnabar",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/solanodz/paper-motion.git",
+    "directory": "packages/engine"
+  },
+  "type": "module",
+  "bin": {
+    "pamo": "bin/pamo.mjs",
+    "paper-motion": "bin/pamo.mjs"
+  },
+  "files": [
+    "bin/",
+    "lib/",
+    "runtime/",
+    "templates/",
+    "examples/",
+    "!examples/**/renders/",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18.17"
+  },
+  "dependencies": {
+    "@paper-design/shaders": "0.0.82",
+    "@paper-design/shaders-react": "0.0.82",
+    "playwright-core": "^1.49.0"
+  }
+}

package/runtime/brand.js

@@ -0,0 +1,71 @@
+// paper-motion/brand: the brand folder inside a scene, so a piece takes its look, motion, sound and
+// material from brand/ instead of re-deciding them.
+//   import { loadBrand } from 'paper-motion/brand';
+//   const B = await loadBrand();                       // reads /brand/* (serve from the project root)
+//   const s = scene({ ..., background: B.color('ground') });
+//   B.style(title, 'display'); B.shader(s, '#bg', 'mesh-ground'); B.cue(s, 'transition', 2.4); B.sound(s);
+import { PACE } from './moves.js';
+
+const get = (p, json) => fetch(p).then((r) => (r.ok ? (json ? r.json() : r.text()) : null)).catch(() => null);
+const sections = (md) => Object.fromEntries((md ?? '').split(/^## /m).slice(1).map((b) => { const i = b.indexOf('\n'); return [b.slice(0, i).trim(), b.slice(i + 1).trim()]; }));
+
+export async function loadBrand(root = '/brand') {
+  const [tokens, identityMd, motion, sound, setRaw] = await Promise.all([
+    get(`${root}/tokens.json`, true), get(`${root}/IDENTITY.md`), get(`${root}/motion.json`, true), get(`${root}/sound.json`, true), get(`${root}/shader-set/set.json`, true),
+  ]);
+  const identity = sections(identityMd);
+  const set = Array.isArray(setRaw) ? { entries: setRaw } : setRaw ?? { entries: [] };
+
+  // fonts: stylesheets and files, all loaded before the first frame
+  const fonts = Object.values(tokens?.fonts ?? {}).filter(Boolean);
+  await Promise.all(fonts.filter((f) => f.css).map((f) => new Promise((res) => document.head.append(Object.assign(document.createElement('link'), { rel: 'stylesheet', href: f.css, onload: res, onerror: res })))));
+  for (const f of fonts) if (f.file) document.head.append(Object.assign(document.createElement('style'), { textContent: `@font-face { font-family: '${f.family}'; src: url('${root}/${f.file}'); font-weight: 100 900; }` }));
+  await Promise.all(fonts.flatMap((f) => (f.weights ?? [400]).map((w) => document.fonts.load(`${w} 40px '${f.family}'`).catch(() => {}))));
+
+  const C = tokens?.colors ?? {};
+  const T = tokens?.type ?? {};
+  const fam = (key) => (tokens?.fonts?.[key]?.family ? `'${tokens.fonts[key].family}', system-ui, sans-serif` : 'system-ui, sans-serif');
+  const wm = tokens?.wordmark ?? {};
+  const pal = sound?.cues ?? {};
+
+  const B = {
+    tokens, identity, motion, sound, set,
+    name: wm.text ?? tokens?.brand ?? 'brand',
+    /** A color by role (ground, figure, muted, surface, accent…), with a fallback. */
+    color: (role, fallback = '#888888') => C[role]?.hex ?? fallback,
+    ramp: tokens?.ramp ?? [C.ground?.hex, C.surface?.hex, C.accent?.hex].filter(Boolean),
+    /** CSS font-family for a font key (display, text, mono). */
+    font: fam,
+    /** The type role's numbers (display, title, body, caption), scaled for a short side of `short` px. */
+    type: (role, short = 1080) => { const r = T[role] ?? {}; const k = short / (T.reference ?? 1080); return { family: fam(r.font ?? 'text'), weight: r.weight ?? 400, size: (r.size ?? 32) * k, lineHeight: r.lineHeight ?? 1.2, tracking: r.tracking ?? '0em' }; },
+    /** Apply a type role to an element. */
+    style: (el, role, { short = 1080, color = 'figure' } = {}) => {
+      const t = B.type(role, short);
+      Object.assign(el.style, { fontFamily: t.family, fontWeight: t.weight, fontSize: `${t.size}px`, lineHeight: t.lineHeight, letterSpacing: t.tracking, color: B.color(color) });
+      return el;
+    },
+    wordmark: { text: wm.text ?? tokens?.brand, onLight: wm.files?.onLight && `${root}/${wm.files.onLight}`, onDark: wm.files?.onDark && `${root}/${wm.files.onDark}` },
+    /** Timing for the brand's pace: { enter, hold, stagger } in seconds. */
+    pace: { ...PACE[motion?.pace ?? 'medium'], ...(motion?.timing ?? {}) },
+    /** Mount a shader-set entry by id on an element (or selector). Returns the layer. */
+    shader: (s, el, id, options = {}) => {
+      const e = set.entries.find((x) => x.id === id);
+      if (!e?.shader) throw new Error(`paper-motion/brand: no shader entry "${id}" in brand/shader-set/set.json`);
+      const props = { ...e.props };
+      if (e.image) props.image = e.image === 'wordmark' ? B.wordmark.onDark ?? B.wordmark.onLight : e.image === 'wordmark-dark' ? B.wordmark.onLight ?? B.wordmark.onDark : `${root}/${e.image}`;
+      const layer = s.shader(el, e.shader, props, { ...(e.loop ? { loop: e.loop } : {}), ...options });
+      // the entry's periodic motion, as in its rendered loop (static shaders stay alive)
+      if (e.motion) { const D = set.format?.duration ?? s.duration, { param, from, to, cycles = 1 } = e.motion; s.update((t) => layer.set({ [param]: from + (to - from) * (0.5 - 0.5 * Math.cos((2 * Math.PI * cycles * t) / D)) })); }
+      return layer;
+    },
+    /** Schedule the brand's sound for a gesture (transition, land, text) at time t. */
+    cue: (s, gesture, t, extra = {}) => { const c = pal[gesture]; if (c) s.sfx(t, c.type, { ...c, ...extra }); },
+    /** The brand's keystroke options for keySounds(): { bank, style, gain }. */
+    keys: { ...(sound?.keys?.bank ? { bank: sound.keys.bank } : {}), ...(sound?.keys?.style ? { style: sound.keys.style } : {}), gain: sound?.keys?.gain ?? 0.16 },
+    /** Apply the brand's master sound settings (and its bed, if any) to a scene. */
+    sound: (s) => { if (pal.bed) s.sfx(0, pal.bed.type, { dur: s.duration, ...pal.bed }); s.sound({ lowpass: sound?.lowpass ?? 2000, gain: 1 }); },
+    /** The loudness to render at (LUFS). */
+    loudness: sound?.loudness ?? -16,
+  };
+  return B;
+}