primocode 10.17.1 → 10.19.0

package/vendor/motioncraft/scripts/doctor.sh

@@ -0,0 +1,23 @@
+#!/bin/sh
+# motioncraft bootstrap check (Mac/Linux). Works without Node. Detects only - never installs.
+say() { printf '%s\n' "$*"; }
+ok() { printf '  \342\234\224 %-10s %s\n' "$1" "$2"; }
+miss() { printf '  \342\234\226 %-10s missing  ->  %s\n' "$1" "$2"; }
+OS=$(uname -s); PM=""
+if [ "$OS" = "Darwin" ]; then command -v brew >/dev/null 2>&1 && PM=brew; else
+  for p in apt-get dnf pacman; do command -v $p >/dev/null 2>&1 && PM=$p && break; done; fi
+inst() { case "$PM:$1" in
+  brew:node) echo "brew install node";; brew:ffmpeg) echo "brew install ffmpeg";;
+  apt-get:node) echo "see https://nodejs.org (or: sudo apt-get install -y nodejs npm)";; apt-get:ffmpeg) echo "sudo apt-get install -y ffmpeg";;
+  dnf:node) echo "sudo dnf install nodejs";; dnf:ffmpeg) echo "sudo dnf install ffmpeg";;
+  pacman:node) echo "sudo pacman -S nodejs npm";; pacman:ffmpeg) echo "sudo pacman -S ffmpeg";;
+  *) [ "$1" = node ] && echo "https://nodejs.org (LTS)" || echo "https://ffmpeg.org/download.html";; esac; }
+say "motioncraft bootstrap ($OS, package manager: ${PM:-none})"
+if command -v node >/dev/null 2>&1; then
+  V=$(node -v); MAJ=$(echo "$V" | sed 's/v\([0-9]*\).*/\1/')
+  if [ "$MAJ" -ge 18 ]; then ok node "$V"; else miss node "$(inst node) (found $V, need 18+)"; fi
+else miss node "$(inst node)"; fi
+command -v ffmpeg >/dev/null 2>&1 && ok ffmpeg "$(ffmpeg -version | head -1 | cut -c1-40)" || miss ffmpeg "$(inst ffmpeg)  (optional: Remotion ships its own)"
+say ""
+say "Nothing was installed. Ask the user before running any install command above."
+if command -v node >/dev/null 2>&1; then say "Full check: node \"$(dirname "$0")/motioncraft.mjs\" doctor"; fi

package/vendor/motioncraft/scripts/lib/audio.mjs

@@ -0,0 +1,58 @@
+// Pure-JS audio analysis: loudness, true peak, BPM + beat grid, onsets, key, drop, silences.
+import fs from 'node:fs';
+import * as D from './dsp.mjs';
+
+function fft(re, im) { // in-place radix-2
+  const n = re.length; for (let i = 1, j = 0; i < n; i++) { let b = n >> 1; for (; j & b; b >>= 1) j ^= b; j ^= b; if (i < j) { [re[i], re[j]] = [re[j], re[i]]; [im[i], im[j]] = [im[j], im[i]]; } }
+  for (let len = 2; len <= n; len <<= 1) { const a = -2 * Math.PI / len, wr = Math.cos(a), wi = Math.sin(a);
+    for (let i = 0; i < n; i += len) { let cr = 1, ci = 0; for (let k = 0; k < len / 2; k++) { const ur = re[i + k], ui = im[i + k], vr = re[i + k + len / 2] * cr - im[i + k + len / 2] * ci, vi = re[i + k + len / 2] * ci + im[i + k + len / 2] * cr;
+      re[i + k] = ur + vr; im[i + k] = ui + vi; re[i + k + len / 2] = ur - vr; im[i + k + len / 2] = ui - vi; const t = cr * wr - ci * wi; ci = cr * wi + ci * wr; cr = t; } } }
+}
+function spectrogram(mono, sr, N = 2048, hop = 512) {
+  const win = new Float32Array(N).map((_, i) => 0.5 - 0.5 * Math.cos(2 * Math.PI * i / N)); const frames = [];
+  for (let s = 0; s + N <= mono.length; s += hop) { const re = new Float64Array(N), im = new Float64Array(N); for (let i = 0; i < N; i++) re[i] = mono[s + i] * win[i]; fft(re, im);
+    const mag = new Float32Array(N / 2); for (let k = 0; k < N / 2; k++) mag[k] = Math.hypot(re[k], im[k]); frames.push(mag); }
+  return { frames, hop, N, sr };
+}
+function onsetEnvelope(sp) { // spectral flux on log magnitude
+  const env = new Float32Array(sp.frames.length); let prev = null;
+  sp.frames.forEach((m, i) => { const lm = m.map((v) => Math.log1p(v * 10)); if (prev) { let s = 0; for (let k = 1; k < lm.length; k++) { const d = lm[k] - prev[k]; if (d > 0) s += d; } env[i] = s; } prev = lm; });
+  const mx = Math.max(...env) || 1; return env.map((v) => v / mx);
+}
+function tempo(env, fr) { // autocorrelation over 60-180 bpm, weighted toward 90-120
+  let best = 0, bestBpm = 100; const scores = [];
+  for (let bpm = 60; bpm <= 180; bpm += 0.25) { const lag = 60 * fr / bpm; let s = 0; for (let i = Math.ceil(lag); i < env.length; i++) { const j = i - lag, k = Math.floor(j), f = j - k; s += env[i] * (env[k] * (1 - f) + env[k + 1] * f); }
+    const w = Math.exp(-0.5 * Math.pow(Math.log2(bpm / 105) / 0.6, 2)); scores.push([bpm, s * w]); if (s * w > best) { best = s * w; bestBpm = bpm; } }
+  return bestBpm;
+}
+function beatPhase(env, fr, bpm) { const period = 60 * fr / bpm; let best = 0, bp = 0; for (let ph = 0; ph < period; ph += 0.5) { let s = 0; for (let t = ph; t < env.length; t += period) s += env[Math.round(t)] || 0; if (s > best) { best = s; bp = ph; } } return bp / fr; }
+function pickOnsets(env, fr) { const out = []; const w = 3; for (let i = w; i < env.length - w; i++) { let mean = 0; for (let k = i - 8; k <= i + 8; k++) mean += env[Math.max(0, Math.min(env.length - 1, k))]; mean /= 17; let isMax = true; for (let k = i - w; k <= i + w; k++) if (env[k] > env[i]) isMax = false; if (isMax && env[i] > mean + 0.08 && env[i] > 0.12) out.push(+(i / fr).toFixed(3)); } return out; }
+const MAJ = [6.35, 2.23, 3.48, 2.33, 4.38, 4.09, 2.52, 5.19, 2.39, 3.66, 2.29, 2.88], MIN = [6.33, 2.68, 3.52, 5.38, 2.6, 3.53, 2.54, 4.75, 3.98, 2.69, 3.34, 3.17];
+const NAMES = ['C', 'C#', 'D', 'Eb', 'E', 'F', 'F#', 'G', 'Ab', 'A', 'Bb', 'B'];
+function key(sp) { // Krumhansl-Schmuckler on a chroma average
+  const ch = new Float64Array(12); const bin = sp.sr / sp.N;
+  for (const m of sp.frames) for (let k = 3; k < m.length; k++) { const f = k * bin; if (f < 60 || f > 2000) continue; const pc = ((Math.round(12 * Math.log2(f / 440)) % 12) + 12 + 9) % 12; ch[pc] += m[k]; }
+  const corr = (p, r) => { const x = [...Array(12)].map((_, i) => ch[(i + r) % 12]); const mx = x.reduce((a, b) => a + b) / 12, mp = p.reduce((a, b) => a + b) / 12; let n = 0, dx = 0, dp = 0; for (let i = 0; i < 12; i++) { n += (x[i] - mx) * (p[i] - mp); dx += (x[i] - mx) ** 2; dp += (p[i] - mp) ** 2; } return n / Math.sqrt(dx * dp + 1e-12); };
+  let best = { c: -2 }; for (let r = 0; r < 12; r++) { const a = corr(MAJ, r), b = corr(MIN, r); if (a > best.c) best = { c: a, key: NAMES[r] + ' major' }; if (b > best.c) best = { c: b, key: NAMES[r] + ' minor' }; }
+  return { key: best.key, confidence: +best.c.toFixed(2) };
+}
+function rmsCurve(mono, sr, win = 0.5) { const n = Math.round(win * sr), out = []; for (let s = 0; s + n <= mono.length; s += n) { let e = 0; for (let i = s; i < s + n; i++) e += mono[i] * mono[i]; out.push(D.toDb(Math.sqrt(e / n))); } return out; }
+export function silences(mono, sr, thrDb = -38, minDur = 0.25) { const hop = Math.round(0.01 * sr), out = []; let st = null;
+  for (let s = 0; s + hop <= mono.length; s += hop) { let e = 0; for (let i = s; i < s + hop; i++) e += mono[i] * mono[i]; const dbv = D.toDb(Math.sqrt(e / hop)); const t = s / sr;
+    if (dbv < thrDb) { if (st == null) st = t; } else if (st != null) { if (t - st >= minDur) out.push([+st.toFixed(3), +t.toFixed(3)]); st = null; } }
+  if (st != null && mono.length / sr - st >= minDur) out.push([+st.toFixed(3), +(mono.length / sr).toFixed(3)]); return out; }
+
+export function analyze(wavPath, { withKey = true } = {}) {
+  const { buf, sr } = D.readWav(wavPath, fs); const n = buf.L.length; const mono = new Float32Array(n); for (let i = 0; i < n; i++) mono[i] = (buf.L[i] + buf.R[i]) / 2;
+  const dur = n / sr; const lufs = sr === 48000 ? D.lufs(buf) : null; const tp = D.truePeakDb(buf);
+  // downsample to ~22 kHz for rhythm/key work
+  const step = Math.max(1, Math.round(sr / 22050)); const ds = new Float32Array(Math.floor(n / step)); for (let i = 0; i < ds.length; i++) ds[i] = mono[i * step]; const dsr = sr / step;
+  const sp = spectrogram(ds, dsr); const fr = dsr / sp.hop; const env = onsetEnvelope(sp);
+  const bpm = +tempo(env, fr).toFixed(2); const phase = beatPhase(env, fr, bpm); const beat = 60 / bpm; const beats = []; for (let t = phase; t < dur; t += beat) beats.push(+t.toFixed(3));
+  const onsets = pickOnsets(env, fr); const rms = rmsCurve(mono, sr);
+  let drop = null, bestJump = 0; for (let i = 4; i < rms.length - 2; i++) { const before = (rms[i - 4] + rms[i - 3] + rms[i - 2] + rms[i - 1]) / 4, after = (rms[i] + rms[i + 1]) / 2; if (after - before > bestJump) { bestJump = after - before; drop = i * 0.5; } }
+  const res = { file: wavPath, duration: +dur.toFixed(3), sampleRate: sr, lufs: lufs == null ? null : +lufs.toFixed(2), truePeakDb: +tp.toFixed(2), bpm, beatSeconds: +beat.toFixed(4), firstBeat: +phase.toFixed(3),
+    beats, bars: beats.filter((_, i) => i % 4 === 0), onsets, drop: drop == null ? null : { t: +drop.toFixed(2), jumpDb: +bestJump.toFixed(1) }, silences: silences(mono, sr), energyDbPerHalfSecond: rms.map((v) => +v.toFixed(1)) };
+  if (withKey) Object.assign(res, key(sp));
+  return res;
+}

package/vendor/motioncraft/scripts/lib/check-update.mjs

@@ -0,0 +1,66 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import https from 'node:https';
+import {SKILL_DIR} from './util.mjs';
+
+const API = 'https://api.github.com/repos/ahmdd4vd/MotionCraft';
+const RELEASES = 'https://github.com/ahmdd4vd/MotionCraft/releases';
+export function installedVersion(skillDir = SKILL_DIR) {
+  const file = fs.readFileSync(path.join(skillDir, 'SKILL.md'), 'utf8');
+  const match = file.match(/^metadata:\s*\n(?:^[ \t]+.*\n)*?^[ \t]+version:\s*["']?([^\s"']+)/m);
+  if (!match) throw Error('Installed SKILL.md has no metadata.version; cannot compare versions');
+  return match[1];
+}
+export function parseVersion(value) {
+  const m = /^v?(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?$/.exec(value);
+  if (!m) throw Error(`Unsupported version: ${value}`);
+  return {parts: m.slice(1,4).map(Number), pre: m[4] || null};
+}
+export function compareVersions(a,b) {
+  const x=parseVersion(a),y=parseVersion(b);
+  for(let i=0;i<3;i++) if(x.parts[i]!==y.parts[i]) return Math.sign(x.parts[i]-y.parts[i]);
+  if(x.pre===y.pre)return 0;
+  if(!x.pre)return 1;if(!y.pre)return -1;
+  const xa=x.pre.split('.'),ya=y.pre.split('.');
+  for(let i=0;i<Math.max(xa.length,ya.length);i++){
+    if(xa[i]===undefined)return -1;if(ya[i]===undefined)return 1;
+    if(xa[i]===ya[i])continue;
+    const xn=/^\d+$/.test(xa[i]),yn=/^\d+$/.test(ya[i]);
+    if(xn&&yn)return Math.sign(Number(xa[i])-Number(ya[i]));
+    if(xn!==yn)return xn?-1:1;
+    return xa[i]<ya[i]?-1:1;
+  }
+  return 0;
+}
+export function getJson(url) {
+  return new Promise((resolve,reject)=>{
+    const req=https.get(url,{headers:{'User-Agent':'MotionCraft-update-check','Accept':'application/vnd.github+json'},timeout:8000},res=>{
+      let data='';res.setEncoding('utf8');
+      res.on('data',part=>{data+=part;if(data.length>1024*1024)res.destroy(Error('GitHub response too large'));});
+      res.on('end',()=>{
+        if(res.statusCode!==200)return reject(Error(`GitHub API returned HTTP ${res.statusCode}`));
+        try{resolve(JSON.parse(data));}catch{reject(Error('Invalid GitHub response'));}
+      });
+    });req.on('timeout',()=>req.destroy(Error('GitHub request timed out')));req.on('error',reject);
+  });
+}
+export async function checkUpdate({skillDir=SKILL_DIR,fetchJson=getJson}={}){
+  const installed=installedVersion(skillDir);
+  parseVersion(installed);
+  let tag,source;
+  try {
+    const release=await fetchJson(`${API}/releases/latest`);
+    if(!release.tag_name||release.draft||release.prerelease)throw Error('No stable release');
+    tag=release.tag_name;source='release';
+  } catch(err){
+    if(!/HTTP 404|No stable release/.test(err.message))throw err;
+    // No published release: use the newest stable semantic tag, not API creation order.
+    const tags=await fetchJson(`${API}/tags?per_page=100`);
+    const stable=tags.map(t=>t.name).filter(t=>/^v?\d+\.\d+\.\d+$/.test(t));
+    if(!stable.length)throw Error('No stable release or tag found');
+    stable.sort(compareVersions);tag=stable.at(-1);source='tag';
+  }
+  parseVersion(tag);
+  const updateAvailable=compareVersions(installed,tag)<0;
+  return {installed,latest:tag,source,updateAvailable,latestUrl:`${RELEASES}/tag/${encodeURIComponent(tag)}`,instruction:updateAvailable?'From your agent environment, run: npx skills add ahmdd4vd/motioncraft (then re-run check-update).':'Already up to date. The version in SKILL.md is the installed version; unreleased changes on main are not counted.'};
+}

package/vendor/motioncraft/scripts/lib/commands.mjs

@@ -0,0 +1,147 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import * as D from './dsp.mjs';
+import { renderMusic, varietyCheck, validateSpec, resolveSpec, PRESETS, PROGRESSIONS } from './music.mjs';
+import { renderSfx, SFX_TYPES, PACKS } from './sfx.mjs';
+import { analyze, silences } from './audio.mjs';
+import { ff, probe, toWav48, has, run, die, log, readJson, writeJson, mkdirp, workDir, stateDir, SKILL_DIR, ffmpeg } from './util.mjs';
+
+import {geometry, FORMATS} from '../../assets/template/src/lib/format.mjs';
+
+// ---------------- project
+export function cmdNew(a) {
+  const dest = path.resolve(a._[0] || 'my-video'); if (fs.existsSync(dest) && fs.readdirSync(dest).length) die(`${dest} is not empty`);
+  fs.cpSync(path.join(SKILL_DIR, 'assets', 'template'), dest, { recursive: true });
+  const style = a.style || 'pi-v2'; const sp = path.join(SKILL_DIR, 'styles', style, 'tokens.json'); if (!fs.existsSync(sp)) die(`unknown style ${style}`, `choose one of: ${fs.readdirSync(path.join(SKILL_DIR, 'styles')).join(', ')}`);
+  fs.copyFileSync(sp, path.join(dest, 'src', 'style.json'));
+  const format=a.format || (a.vertical?'9:16':'16:9');const g=geometry(format,a.platform);
+  { const j=readJson(path.join(dest,'src','style.json'));j.canvas={...j.canvas,width:g.width,height:g.height};writeJson(path.join(dest,'src','style.json'),j); }
+  { const t = readJson(path.join(dest, 'src', 'style.json')); const mod = (n) => n.replace(/[^A-Za-z0-9]/g, ''); // load the style's Google Fonts
+    const wts = [...new Set(Object.values(t.font.weights || {}).map(String).concat(['400', '500']))].sort();
+    fs.writeFileSync(path.join(dest, 'src', 'lib', 'fonts.ts'), `// Generated by motioncraft new from style.json. To change fonts: import another family from @remotion/google-fonts
+// (or use @remotion/fonts with a local file in public/fonts) AND update style.json font.display / font.mono.
+import {loadFont as loadDisplay} from '@remotion/google-fonts/${mod(t.font.display)}';
+import {loadFont as loadMono} from '@remotion/google-fonts/${mod(t.font.mono)}';
+loadDisplay('normal', {weights: ${JSON.stringify(wts)}, subsets: ['latin']});
+loadMono('normal', {weights: ['400', '500'], subsets: ['latin']});
+`); }
+  writeJson(path.join(dest, 'mc.config.json'), { title: a.title || path.basename(dest), style, handle: a.handle || '@yourhandle', format, platform:g.platform, fps: 30 });
+  return { created: dest, style, next: [`cd ${dest}`, 'ASK the user, then: npm install', 'npm run studio  (preview)'] };
+}
+
+// ---------------- music / sfx / mix
+export function cmdMusic(a) {
+  const sub = a._[0];
+  if (sub === 'presets') return { presets: PRESETS, progressions: Object.fromEntries(Object.entries(PROGRESSIONS).map(([k, v]) => [k, v.mood])) };
+  const spec = a.spec ? readJson(path.resolve(a.spec)) : {}; if (a.preset) spec.preset = a.preset;
+  for (const k of ['bpm', 'duration', 'drop', 'swing', 'seed']) if (a[k] != null) spec[k] = +a[k];
+  for (const k of ['key', 'lead', 'comp', 'drums', 'progression']) if (a[k] != null) spec[k] = a[k];
+  const s = resolveSpec(spec); const issues = validateSpec(s); if (issues.length) die('music spec rejected:\n  - ' + issues.join('\n  - '), 'fix the values or pick a preset: node scripts/motioncraft.mjs music presets');
+  const hist = path.join(os.homedir(), '.motioncraft', 'music-history.json'); const H = readJson(hist, []);
+  const v = varietyCheck(s, H[H.length - 1]); if (!v.ok && !a.force) die(`too similar to the last track (${v.why.join(', ')}). Change at least 2 of key / bpm (>=6) / progression / lead.`, 'or pass --force if the user explicitly wants the same vibe');
+  const outDir = path.resolve(a.out || 'audio'); mkdirp(outDir);
+  if (sub === 'audition') { // 3 short variations
+    const res = []; const keys = ['C', 'D', 'F', 'G', 'A', 'Bb']; const progs = Object.keys(PROGRESSIONS);
+    for (let i = 0; i < 3; i++) { const vs = { ...spec, duration: 16, drop: 5, key: keys[(keys.indexOf(s.key) + 1 + i * 2) % keys.length], progression: progs[(progs.indexOf(s.progression) + 1 + i) % progs.length], bpm: s.bpm + [-4, 0, 5][i], chords: undefined, seed: 7 + i };
+      const r = renderMusic(vs); const m = D.master(r.mix); const f = path.join(outDir, `audition_${i + 1}.wav`); D.writeWav(f, m.buf, 16, fs); res.push({ file: f, key: r.spec.key, bpm: r.spec.bpm, progression: r.spec.progression }); }
+    return { auditions: res, next: 'let the user pick one, then run `music make` with those values' };
+  }
+  const r = renderMusic(s); const m = D.master(r.mix, a.lufs ? +a.lufs : -14, -1);
+  D.writeWav(path.join(outDir, 'music.wav'), m.buf, 24, fs);
+  if (a.stems) for (const [k, b] of Object.entries(r.stems)) D.writeWav(path.join(outDir, `stem_${k}.wav`), b, 16, fs);
+  const grid = { bpm: r.spec.bpm, beatSeconds: 60 / r.spec.bpm, beats: r.beats, sections: r.markers, duration: r.dur };
+  writeJson(path.join(outDir, 'beatgrid.json'), grid);
+  mkdirp(path.dirname(hist)); H.push({ key: s.key, bpm: s.bpm, chords: s.chords, lead: s.lead, at: new Date().toISOString() }); writeJson(hist, H.slice(-20));
+  return { music: path.join(outDir, 'music.wav'), beatgrid: path.join(outDir, 'beatgrid.json'), lufs: +m.lufs.toFixed(2), truePeak: +m.truePeak.toFixed(2), duration: +r.dur.toFixed(2), sections: r.markers, spec: { preset: s.preset, bpm: s.bpm, key: s.key, progression: s.progression, lead: s.lead } };
+}
+export function cmdSfx(a) {
+  if (a._[0] === 'list') return { types: SFX_TYPES, packs: Object.keys(PACKS) };
+  const cuesFile = a.cues || (a.timeline ? null : 'sfx.json'); let cues = [], dur = +a.duration || 0, bpm = a.bpm ? +a.bpm : null;
+  if (a.timeline) { const tl = readJson(path.resolve(a.timeline)); cues = tl.sfx || []; dur = dur || tl.duration; bpm = bpm || tl.bpm; }
+  else { const j = readJson(path.resolve(cuesFile)); if (!j) die(`cannot read ${cuesFile}`, 'pass --cues file.json ([{type,t}]) or --timeline timeline.json'); cues = Array.isArray(j) ? j : j.cues; dur = dur || j.duration || Math.max(...cues.map((c) => c.t)) + 3; }
+  const r = renderSfx(cues, dur, { bpm, pack: a.pack || 'soft-pop', density: a.density ? +a.density : 1 });
+  const o = path.resolve(a.out || 'audio/sfx.wav'); mkdirp(path.dirname(o)); D.writeWav(o, r.buf, 24, fs);
+  return { sfx: o, cues: cues.length, perMinute: Math.round(cues.length / (dur / 60)), warnings: r.warnings };
+}
+export function cmdMix(a) {
+  const load = (p) => p ? D.readWav(toWav48(path.resolve(p), path.basename(p) + '.wav'), fs).buf : null;
+  const vo = load(a.vo), music = load(a.music), sfx = load(a.sfx); if (!vo && !music) die('need at least --vo or --music');
+  const n = Math.max(...[vo, music, sfx].filter(Boolean).map((b) => b.L.length)); const mix = D.stereo(n);
+  let voP = null; if (vo) { voP = D.compress(D.filt(vo, 'hp', 80), -20, 3, 5, 120); D.mixInto(mix, voP); }
+  if (music) { let m = D.gain(D.clone(music), D.db(a.musicDb ? +a.musicDb : -6));
+    if (voP) { // duck music under VO + dip 1-4 kHz so words stay clear
+      const env = new Float32Array(n); const at = Math.exp(-1 / (0.01 * D.SR)), rt = Math.exp(-1 / (0.35 * D.SR)); let e = 0;
+      for (let i = 0; i < n; i++) { const l = i < voP.L.length ? Math.abs(voP.L[i]) + Math.abs(voP.R[i]) : 0; e = l > e ? at * e + (1 - at) * l : rt * e + (1 - rt) * l; env[i] = e; }
+      const dip = D.filt(m, 'peak', 2500, 0.8, -3);
+      for (let i = 0; i < m.L.length; i++) { const k = Math.min(1, env[i] * 12); const g = 1 - k * (1 - D.db(-7)); m.L[i] = (m.L[i] * (1 - k) + dip.L[i] * k) * g; m.R[i] = (m.R[i] * (1 - k) + dip.R[i] * k) * g; } }
+    D.mixInto(mix, m); }
+  if (sfx) D.mixInto(mix, sfx, D.db(a.sfxDb ? +a.sfxDb : -4));
+  let finalMix=mix;
+  if (a.duration != null) { const seconds=Number(a.duration); if(!Number.isFinite(seconds)||seconds<=0)die('--duration needs positive seconds');
+    const samples=Math.round(seconds*D.SR);if(mix.L.length<samples)die(`mix sources too short for ${seconds}s (${(mix.L.length/D.SR).toFixed(2)}s); extend music/VO before mixing`);
+    finalMix=D.stereo(samples);finalMix.L.set(mix.L.subarray(0,samples));finalMix.R.set(mix.R.subarray(0,samples));
+    const fade=Math.min(samples,Math.round(0.35*D.SR));for(let i=0;i<fade;i++){const g=(fade-i-1)/fade;finalMix.L[samples-fade+i]*=g;finalMix.R[samples-fade+i]*=g;}
+  }
+  const M = D.master(finalMix, a.lufs ? +a.lufs : -14, -1.5); const o = path.resolve(a.out || 'audio/final.wav'); mkdirp(path.dirname(o)); D.writeWav(o, M.buf, 24, fs);
+  return { final: o, lufs: +M.lufs.toFixed(2), truePeak: +M.truePeak.toFixed(2), duration: +(finalMix.L.length / D.SR).toFixed(2) };
+}
+
+// ---------------- analysis
+export function cmdAudio(a) { const f = a._[1] || a._[0]; if (!f) die('usage: audio analyze <file>'); const w = toWav48(path.resolve(f)); const r = analyze(w); if (a.out) writeJson(path.resolve(a.out), r); return a.full ? r : { ...r, beats: `${r.beats.length} beats`, onsets: `${r.onsets.length} onsets`, energyDbPerHalfSecond: undefined, note: 'use --full or --out file.json for all beat/onset times; key is an estimate (see confidence)' }; }
+export function cmdBeat(a) {
+  const sub = a._[0];
+  if (sub === 'grid') { const bpm = +a.bpm, dur = +a.dur, off = +(a.offset || 0), fps = +(a.fps || 30); if (!bpm || !dur) die('usage: beat grid --bpm 93 --dur 52.6 [--offset 0] [--fps 30]'); const beats = []; for (let t = off; t < dur; t += 60 / bpm) beats.push(+t.toFixed(4)); return { bpm, beats, bars: beats.filter((_, i) => i % 4 === 0), frames: beats.map((t) => Math.round(t * fps)) }; }
+  if (sub === 'snap') { const cues = readJson(path.resolve(a._[1])); const grid = readJson(path.resolve(a.grid || 'audio/beatgrid.json')); const max = (+a.maxMs || 80) / 1000;
+    const snapped = cues.map((c) => { let best = grid.beats[0]; for (const b of grid.beats) if (Math.abs(b - c.t) < Math.abs(best - c.t)) best = b; return Math.abs(best - c.t) <= max ? { ...c, t: best, snapped: true } : c; });
+    if (a.out) writeJson(path.resolve(a.out), snapped); return { snapped: snapped.filter((c) => c.snapped).length, total: cues.length, cues: snapped }; }
+  die('usage: beat grid|snap');
+}
+export function cmdVo(a) {
+  const sub = a._[0]; const f = path.resolve(a._[1] || 'audio/vo.wav');
+  if (sub === 'clean') { const o = path.resolve(a.out || f.replace(/\.\w+$/, '_clean.wav')); ff(['-i', f, '-af', 'highpass=f=80,afftdn=nf=-25,loudnorm=I=-16:TP=-1.5:LRA=7', '-ar', '48000', o]); return { cleaned: o }; }
+  if (sub === 'align') { // word timings via Whisper if present, else phrase timings from silences
+    const o = path.resolve(a.out || 'audio/words.json'); const py = has('python3') ? 'python3' : has('python') ? 'python' : null;
+    if (py && run(py, ['-c', 'import faster_whisper']).status === 0) {
+      const r = run(py, [path.join(SKILL_DIR, 'scripts', 'py', 'whisper_words.py'), f, o, a.lang || 'auto', a.model || 'small']); if (r.status !== 0) die('whisper failed: ' + r.stderr.slice(-400));
+      const j = readJson(o); return { words: j.words.length, text: j.text, file: o, mode: 'word', check: 'Compare `text` with the script. Names are often misheard; if a segment looks wrong, cut it with ffmpeg and transcribe that piece alone.' };
+    }
+    const w = D.readWav(toWav48(f), fs); const mono = w.buf.L; const sil = silences(mono, 48000, -40, 0.18); const dur = mono.length / 48000; const phrases = []; let st = 0;
+    for (const [s0, s1] of sil) { if (s0 - st > 0.2) phrases.push({ start: +st.toFixed(3), end: +s0.toFixed(3) }); st = s1; } if (dur - st > 0.2) phrases.push({ start: +st.toFixed(3), end: +dur.toFixed(3) });
+    const script = a.script ? fs.readFileSync(path.resolve(a.script), 'utf8').split(/(?<=[.!?])\s+|\n+/).map((x) => x.trim()).filter(Boolean) : [];
+    writeJson(o, { mode: 'phrase', phrases: phrases.map((p, i) => ({ ...p, text: script[i] || null })), words: [] });
+    return { file: o, mode: 'phrase', phrases: phrases.length, scriptSentences: script.length, warning: script.length && script.length !== phrases.length ? 'phrase count differs from script sentences: check the pauses by ear or adjust --script line breaks' : undefined, note: 'Whisper not found: word-level sync unavailable. Words are spread evenly inside each phrase by `timeline build`.' };
+  }
+  die('usage: vo clean|align <file>');
+}
+export function cmdTimeline(a) {
+  const words = readJson(path.resolve(a.words || 'audio/words.json'), { words: [], phrases: [] }); const grid = readJson(path.resolve(a.grid || 'audio/beatgrid.json'), { beats: [] });
+  let W = words.words || [];
+  if (!W.length && words.phrases?.length) for (const p of words.phrases) { const ws = (p.text || '').split(/\s+/).filter(Boolean); ws.forEach((w, i) => W.push({ w, start: +(p.start + (p.end - p.start) * i / ws.length).toFixed(3), end: +(p.start + (p.end - p.start) * (i + 1) / ws.length).toFixed(3) })); }
+  const dur = +(a.duration || Math.max(grid.duration || 0, W.length ? W[W.length - 1].end + 2.5 : 0));
+  const tl = { duration: +dur.toFixed(3), bpm: grid.bpm || null, words: W, beats: grid.beats || [], sections: grid.sections || [], scenes: [], events: [] };
+  const o = path.resolve(a.out || 'public/timeline.json'); writeJson(o, tl); return { timeline: o, words: W.length, beats: tl.beats.length, duration: tl.duration };
+}
+
+// ---------------- reference breakdown
+export function cmdRef(a) {
+  const sub = a._[0]; const dir = path.resolve(a.dir || 'ref'); mkdirp(dir); const vid = path.join(dir, 'ref.mp4');
+  if (sub === 'get') { const src = a._[1]; if (!src) die('usage: ref get <url|file>');
+    if (/^https?:/.test(src)) { if (!has('yt-dlp')) die('yt-dlp not installed', 'ask the user to install it (see doctor) or to download the video and run `ref get <file>`'); const r = run('yt-dlp', ['-f', 'bv*[height<=1080]+ba/b', '--merge-output-format', 'mp4', '-o', vid, src], { stdio: 'inherit' }); if (r.status !== 0) die('download failed'); }
+    else ff(['-i', path.resolve(src), '-c:v', 'libx264', '-crf', '18', '-c:a', 'aac', vid]);
+    const p = probe(vid); const v = p.streams.find((s) => s.codec_type === 'video'); return { file: vid, duration: +(+p.format.duration).toFixed(2), size: `${v.width}x${v.height}`, fps: v.r_frame_rate }; }
+  if (!fs.existsSync(vid)) die(`${vid} not found`, 'run `ref get <url|file>` first');
+  if (sub === 'scenes') { const r = ff(['-i', vid, '-vf', `select='gt(scene,${a.threshold || 0.3})',showinfo`, '-f', 'null', '-']); const cuts = [...r.stderr.matchAll(/pts_time:([\d.]+)/g)].map((m) => +(+m[1]).toFixed(2)); writeJson(path.join(dir, 'scenes.json'), cuts); return { cuts, count: cuts.length, file: path.join(dir, 'scenes.json') }; }
+  if (sub === 'frames') { const fd = path.join(dir, 'frames'); mkdirp(fd); const every = +(a.every || 0.5); ff(['-i', vid, '-vf', `fps=1/${every},scale=640:-2`, '-q:v', '3', path.join(fd, 'f_%04d.jpg')]); const n = fs.readdirSync(fd).length; return { dir: fd, frames: n, every }; }
+  if (sub === 'sheet') { const fd = path.join(dir, 'frames'); if (!fs.existsSync(fd)) die('run `ref frames` first'); const files = fs.readdirSync(fd).filter((f) => f.endsWith('.jpg')).sort(); const every = +(a.every || 0.5); const per = 20; const sheets = [];
+    for (let s = 0; s * per < files.length; s++) { const o = path.join(dir, `sheet_${s + 1}.jpg`); ff(['-start_number', String(s * per + 1), '-i', path.join(fd, 'f_%04d.jpg'), '-frames:v', '1', '-vf', `drawtext=text='%{eif\\:(n+${s * per})*${every}\\:d}s':x=8:y=8:fontsize=22:fontcolor=white:box=1:boxcolor=black@0.5,tile=5x4:padding=6:margin=6`, o]); sheets.push(o); }
+    return { sheets, note: 'Open each sheet image and describe: layout, type sizes, color, motion between frames, where cuts land.' }; }
+  if (sub === 'motion') { const r = ff(['-i', vid, '-vf', 'scale=320:-2,tblend=all_mode=difference,signalstats,metadata=print:key=lavfi.signalstats.YAVG', '-f', 'null', '-']); const v = [...r.stderr.matchAll(/YAVG=([\d.]+)/g)].map((m) => +m[1]); const fps = 30; const perSec = []; for (let i = 0; i < v.length; i += fps) perSec.push(+(v.slice(i, i + fps).reduce((x, y) => x + y, 0) / Math.min(fps, v.length - i)).toFixed(2)); return { motionPerSecond: perSec, note: 'higher = more movement; flat low = holds; spikes = transitions' }; }
+  if (sub === 'colors') { const o = path.join(dir, 'palette.png'); ff(['-i', vid, '-vf', 'fps=1,scale=160:-2,palettegen=max_colors=12:stats_mode=full', o]); return { palette: o, note: 'open the image; the swatches are the dominant colors' }; }
+  if (sub === 'audio') { const w = toWav48(vid, 'ref.wav'); const r = analyze(w); writeJson(path.join(dir, 'audio.json'), r); return { ...r, beats: `${r.beats.length} beats`, onsets: `${r.onsets.length}`, energyDbPerHalfSecond: undefined, file: path.join(dir, 'audio.json') }; }
+  if (sub === 'text') { if (!has('tesseract')) die('tesseract not installed', 'optional: skip OCR, read text from the sheets instead'); const fd = path.join(dir, 'frames'); const res = []; for (const f of fs.readdirSync(fd).filter((x) => x.endsWith('.jpg')).sort().filter((_, i) => i % 2 === 0)) { const r = run('tesseract', [path.join(fd, f), '-', '--psm', '11']); const t = (r.stdout || '').replace(/\s+/g, ' ').trim(); if (t) res.push({ frame: f, text: t }); } writeJson(path.join(dir, 'text.json'), res); return { found: res.length, file: path.join(dir, 'text.json') }; }
+  if (sub === 'report') { const out = []; for (const s of ['scenes', 'frames', 'sheet', 'motion', 'colors', 'audio']) { try { out.push([s, cmdRef({ ...a, _: [s] })]); } catch (e) { out.push([s, { error: String(e) }]); } }
+    const R = Object.fromEntries(out); const md = [`# Reference report`, '', `Video: ${vid}`, '', `## Cuts (${R.scenes.count})`, R.scenes.cuts.join(', '), '', `## Music`, `BPM ${R.audio.bpm}, key ${R.audio.key} (conf ${R.audio.confidence}), LUFS ${R.audio.lufs}, drop ${JSON.stringify(R.audio.drop)}`, '', `## Motion per second`, R.motion.motionPerSecond.join(' '), '', `## Contact sheets`, ...R.sheet.sheets.map((s) => `- ${s}`), '', `Palette: ${R.colors.palette}`, '', '## TODO for the agent', '- open every sheet and fill: typography (font feel, sizes, weights), layout, color use, motion vocabulary, transitions, how text syncs to VO, how cuts sit on the beat', '- write findings into styles/<new>/style.md and tokens.json (see references/customization.md)'].join('\n');
+    fs.writeFileSync(path.join(dir, 'ref_report.md'), md); return { report: path.join(dir, 'ref_report.md') }; }
+  die('usage: ref get|scenes|frames|sheet|motion|colors|audio|text|report');
+}

package/vendor/motioncraft/scripts/lib/doctor.mjs

@@ -0,0 +1,67 @@
+// Environment preflight. Detects, reports, and suggests - it NEVER installs anything.
+import os from 'node:os';
+import fs from 'node:fs';
+import path from 'node:path';
+import { has, run, writeJson, stateDir, SKILL_DIR, readJson } from './util.mjs';
+
+const OS = process.platform === 'darwin' ? 'mac' : process.platform === 'win32' ? 'windows' : 'linux';
+const pm = OS === 'mac' ? (has('brew') ? 'brew' : null) : OS === 'windows' ? (has('winget', ['--version']) ? 'winget' : has('choco') ? 'choco' : null) : (has('apt-get', ['--version']) ? 'apt' : has('dnf') ? 'dnf' : has('pacman', ['--version']) ? 'pacman' : null);
+const INSTALL = {
+  node: { brew: 'brew install node', winget: 'winget install OpenJS.NodeJS.LTS', choco: 'choco install nodejs-lts', apt: 'curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash - && sudo apt-get install -y nodejs', dnf: 'sudo dnf install nodejs', pacman: 'sudo pacman -S nodejs npm', any: 'https://nodejs.org (LTS)' },
+  ffmpeg: { brew: 'brew install ffmpeg', winget: 'winget install Gyan.FFmpeg', choco: 'choco install ffmpeg', apt: 'sudo apt-get install -y ffmpeg', dnf: 'sudo dnf install ffmpeg', pacman: 'sudo pacman -S ffmpeg', any: 'https://ffmpeg.org/download.html' },
+  python: { brew: 'brew install python', winget: 'winget install Python.Python.3.12', choco: 'choco install python', apt: 'sudo apt-get install -y python3 python3-pip', dnf: 'sudo dnf install python3', pacman: 'sudo pacman -S python', any: 'https://python.org' },
+  pylibs: { any: 'python3 -m pip install --user numpy scipy librosa soundfile pyloudnorm' },
+  ytdlp: { brew: 'brew install yt-dlp', winget: 'winget install yt-dlp.yt-dlp', choco: 'choco install yt-dlp', apt: 'python3 -m pip install --user yt-dlp', dnf: 'python3 -m pip install --user yt-dlp', pacman: 'sudo pacman -S yt-dlp', any: 'python3 -m pip install --user yt-dlp' },
+  whisper: { any: 'python3 -m pip install --user faster-whisper   (or build whisper.cpp: https://github.com/ggml-org/whisper.cpp)' },
+  tesseract: { brew: 'brew install tesseract', winget: 'winget install UB-Mannheim.TesseractOCR', apt: 'sudo apt-get install -y tesseract-ocr', dnf: 'sudo dnf install tesseract', pacman: 'sudo pacman -S tesseract', any: 'https://github.com/tesseract-ocr/tesseract' },
+  remotion: { any: 'node scripts/motioncraft.mjs new <folder>   (copies the template, then asks before running npm install)' },
+};
+const cmdFor = (k) => INSTALL[k][pm] || INSTALL[k].any;
+
+export function doctor(a) {
+  const quick = a.quick; const cacheP = path.join(stateDir(a), 'env.json');
+  if (quick) { const c = readJson(cacheP); if (c && Date.now() - c.checkedAt < 7 * 864e5) return c; }
+  const items = []; const add = (id, tier, ok, detail, fix, fallback) => items.push({ id, tier, ok: !!ok, detail: detail || '', fix: ok ? null : fix, fallback: ok ? null : fallback || null });
+  const nodeV = process.versions.node; const major = +nodeV.split('.')[0];
+  add('node', 'required', major >= 18, `v${nodeV}`, cmdFor('node'), 'none - Node 18+ is required');
+  const npm = has('npm', ['--version']); add('npm', 'required', npm, npm ? `v${npm}` : 'missing', 'comes with Node.js', null);
+  const proj = findProject(a.dir || process.cwd());
+  let remV = null; if (proj) { try { remV = JSON.parse(fs.readFileSync(path.join(proj, 'node_modules', 'remotion', 'package.json'), 'utf8')).version; } catch {} }
+  add('remotion', 'required', remV, remV ? `v${remV} in ${proj}` : proj ? `project at ${proj} but dependencies not installed` : 'no Remotion project here yet', proj ? `cd ${proj} && npm install` : cmdFor('remotion'), null);
+  const ffv = has('ffmpeg', ['-version']); const ffBundled = !ffv && proj && remV && has('npx', ['--no-install', 'remotion', 'ffmpeg', '-version']);
+  add('ffmpeg', 'recommended', ffv || ffBundled, ffv ? ffv.split('\n')[0] : ffBundled ? 'using Remotion bundled ffmpeg (H.264/H.265/VP8/VP9/ProRes only)' : 'missing', cmdFor('ffmpeg'), 'Remotion bundled ffmpeg (npx remotion ffmpeg) once the project is installed');
+  const py = has('python3') || has('python'); add('python', 'optional', py, py || 'missing', cmdFor('python'), 'pure-Node analyzers (slightly less accurate BPM/key)');
+  let libs = null; if (py) { const r = run(has('python3') ? 'python3' : 'python', ['-c', 'import numpy,scipy,librosa,soundfile,pyloudnorm;print("ok")']); libs = r.status === 0; }
+  add('python-libs', 'optional', libs, libs ? 'numpy scipy librosa soundfile pyloudnorm' : 'missing', cmdFor('pylibs'), 'pure-Node analyzers');
+  const yt = has('yt-dlp'); add('yt-dlp', 'recommended', yt, yt ? `v${yt}` : 'missing', cmdFor('ytdlp'), 'ask the user to download the reference video and pass the file');
+  let wh = null; if (py) { const r = run(has('python3') ? 'python3' : 'python', ['-c', 'import faster_whisper;print("ok")']); if (r.status === 0) wh = 'faster-whisper'; }
+  if (!wh && (has('whisper-cli', ['-h']) || has('whisper-cpp', ['-h']))) wh = 'whisper.cpp';
+  if (!wh && has('whisper', ['--help'])) wh = 'openai-whisper';
+  add('whisper', 'recommended', wh, wh || 'missing', cmdFor('whisper'), 'sentence-level sync from silence detection (less precise than word-level)');
+  const tess = has('tesseract'); add('tesseract', 'optional', tess, tess ? tess.split('\n')[0] : 'missing', cmdFor('tesseract'), 'skip on-screen text OCR in reference analysis');
+  const gpu = detectGpu(); add('gpu', 'optional', gpu.ok, gpu.detail, 'no action needed', 'render 3D with --gl=swangle (software, slower) or pre-render 3D to PNG');
+  const disk = freeDiskGb(a.dir || process.cwd()); add('disk', 'recommended', disk == null || disk > 5, disk == null ? 'unknown' : `${disk.toFixed(1)} GB free`, 'free up space (renders need ~2-5 GB)', null);
+  const res = { checkedAt: Date.now(), os: OS, arch: process.arch, cpus: os.cpus().length, ramGb: +(os.totalmem() / 1073741824).toFixed(1), packageManager: pm, project: proj, items,
+    mode: { audioAnalysis: libs ? 'python' : 'node', sync: wh ? 'word' : 'sentence', ffmpeg: ffv ? 'system' : ffBundled ? 'remotion' : 'none', gl: gpu.ok ? 'angle' : 'swangle', reference: yt ? 'download' : 'manual' } };
+  writeJson(cacheP, res); return res;
+}
+function findProject(dir) { let d = path.resolve(dir); for (let i = 0; i < 4; i++) { const p = path.join(d, 'package.json'); if (fs.existsSync(p)) { const j = JSON.parse(fs.readFileSync(p, 'utf8')); if ((j.dependencies || {}).remotion) return d; } const up = path.dirname(d); if (up === d) break; d = up; } return null; }
+function detectGpu() {
+  if (process.platform === 'darwin') return { ok: true, detail: 'macOS (Metal via ANGLE)' };
+  if (process.platform === 'win32') return { ok: true, detail: 'Windows (ANGLE/D3D)' };
+  if (has('nvidia-smi', ['-L'])) return { ok: true, detail: 'NVIDIA GPU' };
+  if (fs.existsSync('/dev/dri')) return { ok: true, detail: '/dev/dri present' };
+  return { ok: false, detail: 'no GPU detected (server/container)' };
+}
+function freeDiskGb(dir) { try { const s = fs.statfsSync(dir); return s.bavail * s.bsize / 1073741824; } catch { return null; } }
+
+export function printDoctor(r) {
+  const icon = (it) => it.ok ? '✔' : it.tier === 'required' ? '✖' : '•';
+  const lines = [`motioncraft doctor  -  ${r.os}/${r.arch}, ${r.cpus} CPU, ${r.ramGb} GB RAM, package manager: ${r.packageManager || 'none found'}`, ''];
+  for (const tier of ['required', 'recommended', 'optional']) { lines.push(tier.toUpperCase());
+    for (const it of r.items.filter((x) => x.tier === tier)) { lines.push(`  ${icon(it)} ${it.id.padEnd(12)} ${it.detail}`); if (!it.ok) { lines.push(`      install : ${it.fix}`); if (it.fallback) lines.push(`      fallback: ${it.fallback}`); } } lines.push(''); }
+  const missing = r.items.filter((x) => !x.ok && x.tier !== 'optional');
+  lines.push(missing.length ? 'AGENT: show this list to the user and ASK before installing anything. If they skip, use the fallback.' : 'All required and recommended tools are present.');
+  lines.push(`modes: ${JSON.stringify(r.mode)}`);
+  return lines.join('\n');
+}

package/vendor/motioncraft/scripts/lib/dsp.mjs

@@ -0,0 +1,178 @@
+// motioncraft DSP core - pure Node, no dependencies.
+// Stereo buffers are {L: Float32Array, R: Float32Array}.
+export const SR = 48000;
+
+let seed = 7;
+export function setSeed(s) { seed = s >>> 0 || 7; }
+export function rand() { // mulberry32
+  seed |= 0; seed = (seed + 0x6D2B79F5) | 0;
+  let t = Math.imul(seed ^ (seed >>> 15), 1 | seed);
+  t = (t + Math.imul(t ^ (t >>> 7), 61 | t)) ^ t;
+  return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+}
+export const randn = () => { let u = 0, v = 0; while (!u) u = rand(); v = rand(); return Math.sqrt(-2 * Math.log(u)) * Math.cos(2 * Math.PI * v); };
+export const db = (x) => Math.pow(10, x / 20);
+export const toDb = (x) => 20 * Math.log10(Math.max(1e-12, x));
+export const midiHz = (m) => 440 * Math.pow(2, (m - 69) / 12);
+export const NOTE = { C: 0, 'C#': 1, Db: 1, D: 2, 'D#': 3, Eb: 3, E: 4, F: 5, 'F#': 6, Gb: 6, G: 7, 'G#': 8, Ab: 8, A: 9, 'A#': 10, Bb: 10, B: 11 };
+
+export function stereo(n) { return { L: new Float32Array(n), R: new Float32Array(n) }; }
+export function fromMono(x) { return { L: x, R: Float32Array.from(x) }; }
+export function len(b) { return b.L.length; }
+export function clone(b) { return { L: Float32Array.from(b.L), R: Float32Array.from(b.R) }; }
+
+export function place(buf, x, t, g = 1, panPos = 0) {
+  const i0 = Math.round(t * SR); const n = len(buf);
+  if (i0 >= n) return;
+  const l = Math.cos((panPos + 1) * Math.PI / 4) * Math.SQRT2, r = Math.sin((panPos + 1) * Math.PI / 4) * Math.SQRT2;
+  const xl = x.L || x, xr = x.R || x;
+  for (let k = Math.max(0, -i0); k < xl.length && i0 + k < n; k++) {
+    buf.L[i0 + k] += xl[k] * g * l; buf.R[i0 + k] += xr[k] * g * r;
+  }
+}
+export function mixInto(dst, src, g = 1) { const n = Math.min(len(dst), len(src)); for (let i = 0; i < n; i++) { dst.L[i] += src.L[i] * g; dst.R[i] += src.R[i] * g; } }
+export function gain(b, g) { for (let i = 0; i < len(b); i++) { b.L[i] *= g; b.R[i] *= g; } return b; }
+export function peak(b) { let p = 0; for (let i = 0; i < len(b); i++) { p = Math.max(p, Math.abs(b.L[i]), Math.abs(b.R[i])); } return p; }
+
+export function adsr(n, a, d, s, r, hold = null) {
+  const A = Math.max(1, Math.round(a * SR)), D = Math.max(1, Math.round(d * SR)), Rl = Math.max(1, Math.round(r * SR));
+  let H = hold == null ? n - A - D - Rl : Math.round(hold * SR); H = Math.max(0, H);
+  const e = new Float32Array(n); let i = 0;
+  for (let k = 0; k < A && i < n; k++) e[i++] = k / A;
+  for (let k = 0; k < D && i < n; k++) e[i++] = 1 + (s - 1) * k / D;
+  for (let k = 0; k < H && i < n; k++) e[i++] = s;
+  for (let k = 0; k < Rl && i < n; k++) e[i++] = s * (1 - k / Rl);
+  return e;
+}
+
+// ---------- biquad (RBJ cookbook)
+export function biquadCoefs(type, f, q = 0.707, gainDb = 0) {
+  f = Math.min(f, SR / 2.2);
+  const w = 2 * Math.PI * f / SR, c = Math.cos(w), s = Math.sin(w), al = s / (2 * q), A = Math.pow(10, gainDb / 40);
+  let b0, b1, b2, a0, a1, a2;
+  switch (type) {
+    case 'lp': b0 = (1 - c) / 2; b1 = 1 - c; b2 = (1 - c) / 2; a0 = 1 + al; a1 = -2 * c; a2 = 1 - al; break;
+    case 'hp': b0 = (1 + c) / 2; b1 = -(1 + c); b2 = (1 + c) / 2; a0 = 1 + al; a1 = -2 * c; a2 = 1 - al; break;
+    case 'bp': b0 = al; b1 = 0; b2 = -al; a0 = 1 + al; a1 = -2 * c; a2 = 1 - al; break;
+    case 'peak': b0 = 1 + al * A; b1 = -2 * c; b2 = 1 - al * A; a0 = 1 + al / A; a1 = -2 * c; a2 = 1 - al / A; break;
+    case 'lowshelf': { const sq = 2 * Math.sqrt(A) * al;
+      b0 = A * ((A + 1) - (A - 1) * c + sq); b1 = 2 * A * ((A - 1) - (A + 1) * c); b2 = A * ((A + 1) - (A - 1) * c - sq);
+      a0 = (A + 1) + (A - 1) * c + sq; a1 = -2 * ((A - 1) + (A + 1) * c); a2 = (A + 1) + (A - 1) * c - sq; break; }
+    case 'highshelf': { const sq = 2 * Math.sqrt(A) * al;
+      b0 = A * ((A + 1) + (A - 1) * c + sq); b1 = -2 * A * ((A - 1) + (A + 1) * c); b2 = A * ((A + 1) + (A - 1) * c - sq);
+      a0 = (A + 1) - (A - 1) * c + sq; a1 = 2 * ((A - 1) - (A + 1) * c); a2 = (A + 1) - (A - 1) * c - sq; break; }
+    default: throw new Error('biquad type ' + type);
+  }
+  return [b0 / a0, b1 / a0, b2 / a0, a1 / a0, a2 / a0];
+}
+export function biquadMono(x, co) {
+  const [b0, b1, b2, a1, a2] = co; let x1 = 0, x2 = 0, y1 = 0, y2 = 0; const y = new Float32Array(x.length);
+  for (let i = 0; i < x.length; i++) { const v = b0 * x[i] + b1 * x1 + b2 * x2 - a1 * y1 - a2 * y2; x2 = x1; x1 = x[i]; y2 = y1; y1 = v; y[i] = v; }
+  return y;
+}
+export function filt(b, type, f, q, g) { const co = biquadCoefs(type, f, q, g); return { L: biquadMono(b.L, co), R: biquadMono(b.R, co) }; }
+
+// ---------- compressor (feed-forward, peak detector, stereo linked)
+export function compress(b, thrDb = -18, ratio = 3, attMs = 5, relMs = 100, makeupDb = 0) {
+  const at = Math.exp(-1 / (attMs * SR / 1000)), rt = Math.exp(-1 / (relMs * SR / 1000));
+  let env = 0; const out = clone(b); const mk = db(makeupDb);
+  for (let i = 0; i < len(b); i++) {
+    const lv = Math.max(Math.abs(b.L[i]), Math.abs(b.R[i]));
+    env = lv > env ? at * env + (1 - at) * lv : rt * env + (1 - rt) * lv;
+    const e = toDb(env); const over = e - thrDb; const gr = over > 0 ? over * (1 - 1 / ratio) : 0;
+    const g = db(-gr) * mk; out.L[i] *= g; out.R[i] *= g;
+  }
+  return out;
+}
+
+// ---------- Freeverb-style reverb (wet only)
+const CombT = [1116, 1188, 1277, 1356, 1422, 1491, 1557, 1617], APT = [556, 441, 341, 225];
+export function reverb(b, room = 0.5, damp = 0.5, wet = 0.25, width = 1) {
+  const n = len(b), scale = SR / 44100, fb = 0.7 + room * 0.28, out = stereo(n);
+  for (const [ch, spread] of [['L', 0], ['R', 23]]) {
+    const input = ch === 'L' ? b.L : b.R; const acc = new Float32Array(n);
+    for (const ct of CombT) {
+      const L = Math.round((ct + spread) * scale); const buf = new Float32Array(L); let idx = 0, store = 0;
+      for (let i = 0; i < n; i++) { const o = buf[idx]; store = o * (1 - damp) + store * damp; buf[idx] = input[i] * 0.015 + store * fb; acc[i] += o; idx = (idx + 1) % L; }
+    }
+    for (const at of APT) {
+      const L = Math.round((at + spread) * scale); const buf = new Float32Array(L); let idx = 0;
+      for (let i = 0; i < n; i++) { const bo = buf[idx]; const o = -acc[i] + bo; buf[idx] = acc[i] + bo * 0.5; acc[i] = o; idx = (idx + 1) % L; }
+    }
+    out[ch] = acc;
+  }
+  const w1 = wet * (width / 2 + 0.5), w2 = wet * ((1 - width) / 2);
+  const res = stereo(n);
+  for (let i = 0; i < n; i++) { res.L[i] = out.L[i] * w1 + out.R[i] * w2; res.R[i] = out.R[i] * w1 + out.L[i] * w2; }
+  return res;
+}
+export function withReverb(b, room, damp, wet, dry = 1) { const w = reverb(b, room, damp, wet); const o = clone(b); gain(o, dry); mixInto(o, w); return o; }
+
+export function delay(b, timeS, fbk = 0.3, mix = 0.2) {
+  const d = Math.round(timeS * SR), n = len(b), o = clone(b);
+  for (const ch of ['L', 'R']) { const y = new Float32Array(n); for (let i = 0; i < n; i++) { y[i] = b[ch][i] + (i >= d ? y[i - d] * fbk : 0); } for (let i = 0; i < n; i++) o[ch][i] += (i >= d ? y[i - d] : 0) * mix; }
+  return o;
+}
+export function chorus(b, rate = 0.9, depthMs = 3, mix = 0.35) {
+  const n = len(b), o = clone(b), base = 0.012 * SR, dep = depthMs / 1000 * SR;
+  for (const [ch, ph] of [['L', 0], ['R', Math.PI / 2]]) {
+    const x = b[ch];
+    for (let i = 0; i < n; i++) { const d = base + dep * Math.sin(2 * Math.PI * rate * i / SR + ph); const p = i - d; const k = Math.floor(p); const fr = p - k; const v = k >= 1 ? x[k] * (1 - fr) + x[k + 1] * fr : 0; o[ch][i] = x[i] * (1 - mix) + v * mix; }
+  }
+  return o;
+}
+
+// ---------- loudness (ITU-R BS.1770-4, gated integrated LUFS)
+export function lufs(b) {
+  const pre = biquadCoefsRaw([1.53512485958697, -2.69169618940638, 1.19839281085285], [1, -1.69065929318241, 0.73248077421585]);
+  const rlb = biquadCoefsRaw([1, -2, 1], [1, -1.99004745483398, 0.99007225036621]);
+  const kw = (x) => biquadMono(biquadMono(resampleTo48(x), pre), rlb);
+  const l = kw(b.L), r = kw(b.R); const blk = Math.round(0.4 * SR), hop = Math.round(0.1 * SR); const zs = [];
+  for (let s = 0; s + blk <= l.length; s += hop) { let z = 0; for (let i = s; i < s + blk; i++) z += l[i] * l[i] + r[i] * r[i]; zs.push(z / blk); }
+  if (!zs.length) return -70;
+  const L = (z) => -0.691 + 10 * Math.log10(Math.max(z, 1e-12));
+  let g = zs.filter((z) => L(z) > -70); if (!g.length) return -70;
+  const rel = L(g.reduce((a, c) => a + c, 0) / g.length) - 10; g = g.filter((z) => L(z) > rel);
+  return L(g.reduce((a, c) => a + c, 0) / g.length);
+}
+function biquadCoefsRaw(bb, aa) { return [bb[0], bb[1], bb[2], aa[1], aa[2]]; }
+function resampleTo48(x) { return x; } // engine always runs at 48 kHz
+export function truePeakDb(b) { // 4x linear-interp oversample estimate
+  let p = 0; for (const ch of ['L', 'R']) { const x = b[ch]; for (let i = 0; i < x.length - 1; i++) { for (let k = 0; k < 4; k++) { const v = Math.abs(x[i] + (x[i + 1] - x[i]) * k / 4); if (v > p) p = v; } } }
+  return toDb(p);
+}
+export function master(b, target = -14, tp = -1) {
+  let x = compress(filt(b, 'hp', 30), -16, 2, 20, 200);
+  for (let it = 0; it < 5; it++) {
+    gain(x, db(target - lufs(x)));
+    if (truePeakDb(x) <= tp) break;
+    const c = db(tp - 0.3), k = c * 0.7, w = c * 0.3;
+    for (const ch of ['L', 'R']) { const y = x[ch]; for (let i = 0; i < y.length; i++) { const a = Math.abs(y[i]); if (a > k) y[i] = Math.sign(y[i]) * (k + w * Math.tanh((a - k) / w)); } }
+  }
+  const pk = truePeakDb(x); if (pk > tp) gain(x, db(tp - pk));
+  return { buf: x, lufs: lufs(x), truePeak: truePeakDb(x) };
+}
+export function fadeOut(b, sec) { const n = len(b), f = Math.min(n, Math.round(sec * SR)); for (let i = 0; i < f; i++) { const g = 1 - i / f; b.L[n - f + i] *= g; b.R[n - f + i] *= g; } }
+
+// ---------- WAV io
+export function writeWav(path, b, bits = 24, fs) {
+  const { writeFileSync } = fs; const n = len(b), bps = bits / 8, data = n * 2 * bps; const buf = Buffer.alloc(44 + data);
+  buf.write('RIFF', 0); buf.writeUInt32LE(36 + data, 4); buf.write('WAVE', 8); buf.write('fmt ', 12); buf.writeUInt32LE(16, 16);
+  buf.writeUInt16LE(1, 20); buf.writeUInt16LE(2, 22); buf.writeUInt32LE(SR, 24); buf.writeUInt32LE(SR * 2 * bps, 28); buf.writeUInt16LE(2 * bps, 32); buf.writeUInt16LE(bits, 34);
+  buf.write('data', 36); buf.writeUInt32LE(data, 40); let o = 44; const mx = bits === 24 ? 8388607 : 32767;
+  for (let i = 0; i < n; i++) for (const v of [b.L[i], b.R[i]]) { const s = Math.max(-1, Math.min(1, v)); const q = Math.round(s * mx); if (bits === 24) buf.writeIntLE(q, o, 3); else buf.writeInt16LE(q, o); o += bps; }
+  writeFileSync(path, buf);
+}
+export function readWav(path, fs) {
+  const buf = fs.readFileSync(path); let p = 12, fmt = null, dataOff = 0, dataLen = 0;
+  while (p + 8 <= buf.length) { const id = buf.toString('ascii', p, p + 4), sz = buf.readUInt32LE(p + 4);
+    if (id === 'fmt ') fmt = { fmt: buf.readUInt16LE(p + 8), ch: buf.readUInt16LE(p + 10), sr: buf.readUInt32LE(p + 12), bits: buf.readUInt16LE(p + 22) };
+    if (id === 'data') { dataOff = p + 8; dataLen = Math.min(sz, buf.length - dataOff); break; } p += 8 + sz + (sz & 1); }
+  if (!fmt) throw new Error('not a WAV file: ' + path);
+  const bps = fmt.bits / 8, fr = Math.floor(dataLen / (bps * fmt.ch)); const L = new Float32Array(fr), R = new Float32Array(fr);
+  for (let i = 0; i < fr; i++) for (let c = 0; c < Math.min(2, fmt.ch); c++) { const o = dataOff + (i * fmt.ch + c) * bps; let v;
+    if (fmt.fmt === 3) v = buf.readFloatLE(o); else if (fmt.bits === 16) v = buf.readInt16LE(o) / 32768; else if (fmt.bits === 24) v = buf.readIntLE(o, 3) / 8388608; else if (fmt.bits === 32) v = buf.readInt32LE(o) / 2147483648; else v = (buf[o] - 128) / 128;
+    (c === 0 ? L : R)[i] = v; }
+  if (fmt.ch === 1) R.set(L);
+  return { buf: { L, R }, sr: fmt.sr };
+}