pixi-effects 0.16.3 → 0.18.0

package/ai/tools/check.mjs

@@ -13,7 +13,10 @@
  * Needs: Node >= 22 (built-in WebSocket), Chrome / Chromium installed (or --chrome PATH / CHROME=PATH). No npm dependencies.
  * The page must follow ai/template.html: it exposes `window.movie` and sets `window.__ready = true` (and `window.__logs`).
  *
- * Options: --strict (text overlaps and stops where the picture is still changing fail the check; by default they are only listed for review) · --out DIR · --frames N (contact sheet tiles, default 12) · --formats mp4,webm (default mp4) · --no-export ·
+ * Options: --draft (the export is a draft: half size, low quality, no motion blur: a much smaller file; the drawing itself is not faster) · --at LIST (pictures at moments you name: 3.5, 50%, f120, title@end → frames/*.png and at.png) ·
+ *          --query "a=1&b=2" (added to the page address: for a page that reads it, such as one video of a batch) ·
+ *          --onion A:B (one picture of the movement between A and B seconds, frames overlaid: onion.png) ·
+ *          --strict (text overlaps and stops where the picture is still changing fail the check; by default they are only listed for review) · --out DIR · --frames N (contact sheet tiles, default 12) · --formats mp4,webm (default mp4) · --no-export ·
  *          --timeout SECONDS (default 240) · --root DIR (static server root; default: the nearest folder above the page with dist/) · --chrome PATH
  */
 import { spawn } from 'node:child_process';
@@ -37,7 +40,7 @@ export function findChrome(env = process.env, exists = fs.existsSync, platform =
 }
 
 export function parseArgs(argv) {
-  const o = { page: null, out: null, frames: 12, formats: ['mp4'], export: true, timeout: 240, root: null, chrome: null, strict: false };
+  const o = { page: null, out: null, frames: 12, formats: ['mp4'], export: true, timeout: 240, root: null, chrome: null, strict: false, at: null, draft: false, onion: null, query: null };
   const need = (i, name) => { if (i + 1 >= argv.length) throw new Error(`${name} needs a value`); return argv[i + 1]; };
   for (let i = 0; i < argv.length; i++) {
     const a = argv[i];
@@ -46,6 +49,14 @@ export function parseArgs(argv) {
     else if (a === '--formats') o.formats = need(i++, a).split(',').map(s => s.trim()).filter(Boolean);
     else if (a === '--no-export') o.export = false;
     else if (a === '--strict') o.strict = true;
+    else if (a === '--draft') o.draft = true;
+    else if (a === '--query') o.query = need(i++, a).replace(/^\?/, '');
+    else if (a === '--at') o.at = need(i++, a);
+    else if (a === '--onion') {
+      const m = need(i++, a).match(/^(\d+(?:\.\d+)?):(\d+(?:\.\d+)?)$/);
+      if (!m || !(Number(m[1]) < Number(m[2]))) throw new Error(`--onion must look like 1:3 (seconds, from before to), got "${argv[i]}"`);
+      o.onion = [Number(m[1]), Number(m[2])];
+    }
     else if (a === '--timeout') o.timeout = Math.max(10, Number(need(i++, a)) || 240);
     else if (a === '--root') o.root = need(i++, a);
     else if (a === '--chrome') o.chrome = need(i++, a);
@@ -56,32 +67,6 @@ export function parseArgs(argv) {
   return o;
 }
 
-/** [{ frame, issues[] }] → [{ message, count, firstFrame, lastFrame }]: issues that differ only by numbers are one. */
-export function groupIssues(perFrame) {
-  const groups = new Map();
-  for (const { frame, issues } of perFrame) {
-    for (const message of issues) {
-      const key = message.replace(/-?\d+(\.\d+)?/g, '#');
-      const g = groups.get(key);
-      if (g) { g.count++; g.lastFrame = frame; }
-      else groups.set(key, { message, count: 1, firstFrame: frame, lastFrame: frame });
-    }
-  }
-  return [...groups.values()];
-}
-
-/**
- * Layout issues → { problems, review }. Cut off by an edge, outside the canvas and "no size" are exact: problems. Text that
- * overlaps text is judged on layout boxes, not ink, so intentional designs trip it (ghost layers, a glow copy under a title,
- * per-letter boxes, a wipe between two scenes: 7 of 30 gallery pieces): those are `review` items to look at on the contact
- * sheet. `strict` makes every issue a problem.
- */
-export function splitIssues(groups, strict = false) {
-  if (strict) return { problems: groups, review: [] };
-  const overlap = g => /\boverlap\b/.test(g.message);
-  return { problems: groups.filter(g => !overlap(g)), review: groups.filter(overlap) };
-}
-
 const MIME = { '.html': 'text/html; charset=utf-8', '.js': 'text/javascript', '.mjs': 'text/javascript', '.css': 'text/css', '.json': 'application/json', '.png': 'image/png', '.jpg': 'image/jpeg', '.jpeg': 'image/jpeg', '.gif': 'image/gif', '.webp': 'image/webp', '.svg': 'image/svg+xml', '.mp3': 'audio/mpeg', '.wav': 'audio/wav', '.mp4': 'video/mp4', '.webm': 'video/webm', '.woff2': 'font/woff2', '.woff': 'font/woff', '.ttf': 'font/ttf', '.wasm': 'application/wasm', '.map': 'application/json', '.md': 'text/plain; charset=utf-8', '.txt': 'text/plain; charset=utf-8' };
 
 /** A plain static server for `root` (no redirects, so `?query` survives). Resolves { server, port }. */
@@ -94,7 +79,7 @@ export function serve(root, onRequest = null, port = 0) {
       if (!file.startsWith(root)) { res.writeHead(403).end(); return; }
       if (fs.existsSync(file) && fs.statSync(file).isDirectory()) file = path.join(file, 'index.html');
       if (!fs.existsSync(file)) { res.writeHead(404).end('not found'); return; }
-      res.writeHead(200, { 'content-type': MIME[path.extname(file).toLowerCase()] ?? 'application/octet-stream', 'cache-control': 'no-store' });
+      res.writeHead(200, { 'content-type': MIME[path.extname(file).toLowerCase()] ?? 'application/octet-stream', 'cache-control': 'no-store', 'access-control-allow-origin': '*' });   // like GitHub Pages: a page with no origin (a sandboxed iframe) may load these files
       fs.createReadStream(file).pipe(res);
     } catch { res.writeHead(500).end(); }
   });
@@ -137,10 +122,11 @@ export class Cdp {
   }
 }
 
-export async function launchChrome(chrome, userDataDir) {
+/** Start a private headless Chrome. `extraArgs`: more command-line flags (the tests use it for `--enable-features=WebMCP`). */
+export async function launchChrome(chrome, userDataDir, extraArgs = []) {
   const proc = spawn(chrome, [
     '--headless=new', '--remote-debugging-port=0', `--user-data-dir=${userDataDir}`, '--no-first-run', '--no-default-browser-check',
-    '--autoplay-policy=no-user-gesture-required', '--ignore-gpu-blocklist', '--enable-unsafe-swiftshader', '--window-size=1400,900', 'about:blank',
+    '--autoplay-policy=no-user-gesture-required', '--mute-audio', '--ignore-gpu-blocklist', '--enable-unsafe-swiftshader', '--window-size=1400,900', ...extraArgs, 'about:blank',
   ], { stdio: ['ignore', 'ignore', 'pipe'] });
   const endpoint = await new Promise((resolve, reject) => {
     let buf = '';
@@ -161,24 +147,13 @@ export async function launchChrome(chrome, userDataDir) {
 const INFO = `(() => { const m = window.movie; if (!m) return { hasMovie: false, logs: window.__logs || [] };
   const c = document.querySelector('canvas');
   return { hasMovie: true, logs: window.__logs || [], totalFrames: m.totalFrames, frameRate: m.frameRate, duration: m.duration,
-           width: m.width ?? (c && c.width), height: m.height ?? (c && c.height), hasAudio: !!m.audioBuffer }; })()`;
-
-const sweepScript = stride => `(async () => {
-  const total = movie.totalFrames, frames = new Set([0, total]);
-  for (let f = 0; f <= total; f += ${stride}) frames.add(Math.min(f, total));
-  const perFrame = [];
-  for (const f of [...frames].sort((a, b) => a - b)) {
-    const r = await movie.inspect(f, { layers: 'none' });
-    if (r.issues.length) perFrame.push({ frame: f, issues: r.issues });
-  }
-  return { checked: frames.size, perFrame };
-})()`;
+           width: m.width ?? (c && c.width), height: m.height ?? (c && c.height), hasAudio: !!m.audioBuffer, hasReview: typeof m.review === 'function' }; })()`;
 
-const exportScript = format => `(() => {
+const exportScript = (format, draft = false) => `(() => {
   window.__x = { state: 'running' };
   (async () => {
     try {
-      const blob = await movie.render({ format: ${JSON.stringify(format)} });
+      const blob = await movie.render({ format: ${JSON.stringify(format)}${draft ? ', draft: true' : ''} });
       const info = { bytes: blob.size, type: blob.type };
       const url = URL.createObjectURL(blob);
       const v = document.createElement('video'); v.muted = true; v.preload = 'metadata'; v.src = url;
@@ -206,6 +181,43 @@ const exportScript = format => `(() => {
   return 0;
 })()`;
 
+/** The mix as a picture (in the page, no dependency): loudness per window as bars, the peak as a line, scene edges and the start of every sound. */
+const waveformScript = (audio, duration) => `(() => {
+  const a = ${JSON.stringify({ windows: audio.windows, scenes: audio.scenes, cues: audio.cues })}, D = ${duration};
+  const W = 1200, H = 300, L = 44, R = 12, T = 22, B = 58;
+  const c = document.createElement('canvas'); c.width = W; c.height = H;
+  const g = c.getContext('2d');
+  g.fillStyle = '#10131c'; g.fillRect(0, 0, W, H);
+  const x = t => L + (t / D) * (W - L - R);
+  const y = db => T + (1 - (Math.max(-60, Math.min(0, db)) + 60) / 60) * (H - T - B);
+  g.font = '11px system-ui, sans-serif'; g.textBaseline = 'middle';
+  for (const db of [0, -12, -24, -36, -48, -60]) {
+    g.strokeStyle = 'rgba(255,255,255,.12)'; g.beginPath(); g.moveTo(L, y(db)); g.lineTo(W - R, y(db)); g.stroke();
+    g.fillStyle = '#9aa5c4'; g.fillText(String(db), 8, y(db));
+  }
+  const bw = Math.max(1, (W - L - R) / Math.max(1, a.windows.length));
+  g.fillStyle = '#7fb4ff';
+  for (const w of a.windows) { const top = y(w.rmsDb); g.fillRect(x(w.t), top, Math.max(1, bw - 0.5), (H - B) - top); }
+  g.strokeStyle = '#f2c14e'; g.lineWidth = 1; g.beginPath();
+  a.windows.forEach((w, i) => { const px = x(w.t) + bw / 2, py = y(w.peakDb); if (i) g.lineTo(px, py); else g.moveTo(px, py); });
+  g.stroke();
+  if (a.scenes.length > 1 && a.scenes.length <= 16) {
+    let lastLabel = -1e9;
+    a.scenes.forEach(s => {
+      g.strokeStyle = 'rgba(255,255,255,.35)'; g.beginPath(); g.moveTo(x(s.from), T - 8); g.lineTo(x(s.from), H - B); g.stroke();
+      if (x(s.from) - lastLabel < 70) return;                                    // scenes that start together share one label
+      lastLabel = x(s.from);
+      g.fillStyle = '#e8ecf8'; g.fillText(s.name.slice(0, 18), x(s.from) + 3, T - 10, Math.max(20, x(s.to) - x(s.from) - 6));
+    });
+  }
+  a.cues.forEach((q, i) => { g.fillStyle = '#ff5a3c'; g.fillRect(x(q.t) - 1, H - B + 2, 2, 8); if (a.cues.length <= 40) g.fillText(String(i + 1), x(q.t) - 3, H - B + 20); });
+  g.fillStyle = '#9aa5c4';
+  const step = D > 120 ? 30 : D > 40 ? 10 : D > 12 ? 5 : 1;
+  for (let t = 0; t <= D + 1e-9; t += step) { g.fillText(t + ' s', x(t) - 8, H - 22); }
+  g.fillText('mix level (dBFS): bars = RMS, line = peak; red ticks = when a sound starts', L, H - 7);
+  return c.toDataURL('image/png');
+})()`;
+
 // ───────────────────────────── the check ─────────────────────────────
 
 export const sleep = ms => new Promise(r => setTimeout(r, ms));
@@ -240,7 +252,7 @@ export async function runCheck(opts, log = console.log) {
     await cdp.send('Runtime.enable');
     await cdp.send('Page.enable');
     const t0 = Date.now();
-    await cdp.send('Page.navigate', { url: `http://127.0.0.1:${port}/${path.relative(root, pagePath).split(path.sep).join('/')}` });
+    await cdp.send('Page.navigate', { url: `http://127.0.0.1:${port}/${path.relative(root, pagePath).split(path.sep).join('/')}${opts.query ? `?${opts.query}` : ''}` });
 
     // wait for the movie to be ready (or the page to say it failed)
     let info = null;
@@ -266,12 +278,25 @@ export async function runCheck(opts, log = console.log) {
     Object.assign(report, { width: info.width, height: info.height, frameRate: info.frameRate, totalFrames: info.totalFrames, duration: info.duration, hasAudio: info.hasAudio });
     if (report.logs.length) report.problems.push(`${report.logs.length} console warning(s) / error(s) — each says what to change`);
 
-    // layout: inspect over the whole timeline
-    const stride = Math.max(1, Math.round(info.totalFrames / 60));
-    const sweep = await cdp.eval(sweepScript(stride));
-    const grouped = splitIssues(groupIssues(sweep.perFrame), opts.strict);
-    report.inspect = { checkedFrames: sweep.checked, issues: grouped.problems, review: grouped.review };
-    if (grouped.problems.length) report.problems.push(`${grouped.problems.length} kind(s) of layout issue from movie.inspect`);
+    // the library reviews the movie (layout over the whole timeline, fonts, sound): the same call the Playground and the WebMCP tools make
+    if (!info.hasReview) throw new Error("this page's pixi-effects is older than the check tool: use 0.18 or newer (the version in the page's import map)");
+
+    // a mistake in --at or --onion is a usage error: say so now, not after the slow work
+    let atList = null;
+    if (opts.at) {
+      // the page's error is returned as a value: thrown, it would arrive with the page's stack trace
+      const r = JSON.parse(await cdp.eval(`(() => { try { return JSON.stringify({ at: movie.resolveAt(${JSON.stringify(opts.at)}) }); } catch (e) { return JSON.stringify({ error: String(e && e.message || e) }); } })()`));
+      if (r.error) throw new Error(r.error.replace(/^pixi-effects: /, ''));
+      atList = r.at;
+    }
+    if (opts.onion && opts.onion[1] > info.duration + 1e-9) throw new Error(`--onion ${opts.onion[0]}:${opts.onion[1]} goes past the end: the movie is ${info.duration} s`);
+
+    const rv = await cdp.eval(`movie.review(${JSON.stringify({ strict: !!opts.strict })})`);
+    report.inspect = { checkedFrames: rv.frames, issues: rv.problems, review: rv.review };
+    if (rv.problems.length) report.problems.push(`${rv.problems.length} kind(s) of layout issue from movie.inspect`);
+    // fonts: a web font whose file did not load is a problem (the library lists a layer with no available font for review)
+    report.fonts = rv.fonts;
+    if (rv.fonts.failed.length) report.problems.push(`${rv.fonts.failed.length} web font(s) failed to load: ${rv.fonts.failed.join(', ')} (the layers that use them are drawn in a fallback)`);
     left();
 
     // contact sheet
@@ -280,6 +305,32 @@ export async function runCheck(opts, log = console.log) {
     fs.writeFileSync(sheetFile, Buffer.from(sheet.slice(sheet.indexOf(',') + 1), 'base64'));
     report.files.sheet = shown(sheetFile);
 
+    // --at: the pictures at moments you name (seconds, 50%, f120, title@end), one file each and one sheet
+    if (opts.at) {
+      const wanted = atList;
+      const framesDir = path.join(outDir, 'frames');
+      fs.mkdirSync(framesDir, { recursive: true });
+      for (const w of wanted) {
+        const png = await cdp.eval(`movie.snapshot(${w.frame}, { as: 'dataURL' })`);
+        fs.writeFileSync(path.join(framesDir, `${w.label}.png`), Buffer.from(png.slice(png.indexOf(',') + 1), 'base64'));
+      }
+      const atSheet = await cdp.eval(`movie.contactSheet({ frames: ${JSON.stringify(wanted.map(w => w.frame))}, as: 'dataURL' })`);
+      const atFile = path.join(outDir, 'at.png');
+      fs.writeFileSync(atFile, Buffer.from(atSheet.slice(atSheet.indexOf(',') + 1), 'base64'));
+      report.files.at = shown(atFile);
+      report.files.frames = shown(framesDir);
+      report.at = wanted;
+    }
+
+    // --onion A:B: one picture of the movement between A and B seconds (8 frames overlaid, the later the stronger)
+    if (opts.onion) {
+      const [from, to] = opts.onion;
+      const onion = await cdp.eval(`movie.onionSkin({ from: ${from}, to: ${to}, count: 8, as: 'dataURL' })`);
+      const onionFile = path.join(outDir, 'onion.png');
+      fs.writeFileSync(onionFile, Buffer.from(onion.slice(onion.indexOf(',') + 1), 'base64'));
+      report.files.onion = shown(onionFile);
+    }
+
     // a presentation (composition.stops): one picture of every stop, in order, so the pages and steps can be read at a glance
     const stops = await cdp.eval(`(() => { const s = movie.stops || []; return s.length ? { count: s.length, pages: movie.pageCount, items: s.map(x => ({ at: Math.round(x.at * 100) / 100, frame: x.frame, page: x.page, pageStart: x.pageStart, notes: !!x.notes, pdf: x.pdf })) } : null; })()`).catch(() => null);
     if (stops) {
@@ -316,7 +367,15 @@ export async function runCheck(opts, log = console.log) {
     }
 
     // audio
-    report.audio = info.hasAudio ? await cdp.eval('movie.inspectAudio()') : null;
+    report.audio = info.hasAudio ? rv.audio : null;
+    if (report.audio) {
+      const wave = await cdp.eval(waveformScript(report.audio, info.duration)).catch(() => null);
+      if (wave) {
+        const waveFile = path.join(outDir, 'waveform.png');
+        fs.writeFileSync(waveFile, Buffer.from(wave.slice(wave.indexOf(',') + 1), 'base64'));
+        report.files.waveform = shown(waveFile);
+      }
+    }
     if (report.audio?.issues?.length) report.problems.push(`${report.audio.issues.length} audio issue(s) from movie.inspectAudio`);
 
     // export, decoded again
@@ -324,7 +383,7 @@ export async function runCheck(opts, log = console.log) {
     if (opts.export) {
       for (const format of opts.formats) {
         left();
-        await cdp.eval(exportScript(format));
+        await cdp.eval(exportScript(format, opts.draft));
         let state;
         for (;;) {
           left();
@@ -332,7 +391,7 @@ export async function runCheck(opts, log = console.log) {
           state = await cdp.eval('window.__x && window.__x.state');
           if (state && state !== 'running') break;
         }
-        const ex = { format };
+        const ex = { format, draft: !!opts.draft };
         if (state === 'error') {
           ex.error = await cdp.eval('window.__x.message');
           report.problems.push(`export ${format} failed: ${ex.error}`);
@@ -382,7 +441,7 @@ function finish(report, outDir, log) {
     if (g.length > 8) L.push(`            … ${g.length - 8} more (report.json)`);
     const rv = report.inspect.review;
     if (rv.length) {
-      L.push(`  review    ${rv.length} text overlap(s) — often intentional (ghost / glow copies, per-letter boxes, a wipe); check them on the contact sheet, or use --strict to fail on them:`);
+      L.push(`  review    ${rv.length} to look at — text overlaps are often intentional (ghost / glow copies, per-letter boxes, a wipe), and a font that is not available is drawn in a fallback; check them on the contact sheet, or use --strict to fail on them:`);
       for (const i of rv.slice(0, 4)) L.push(line(i));
       if (rv.length > 4) L.push(`            … ${rv.length - 4} more (report.json)`);
     }
@@ -398,13 +457,14 @@ function finish(report, outDir, log) {
   }
   if (report.audio !== undefined) {
     const a = report.audio;
-    L.push(a ? `  audio     ${a.sources.length} source(s) · mix peak ${a.peakDb} dBFS · ${a.issues.length ? a.issues.join(' | ') : 'no issues (movie.inspectAudio)'}` : '  audio     none');
+    L.push(a ? `  audio     ${a.sources.length} source(s) · mix peak ${a.peakDb} dBFS · ${a.loudness?.integratedLufs ?? 'n/a'} LUFS · true peak ${a.loudness?.truePeakDb ?? 'n/a'} dBTP · ${a.issues.length ? a.issues.join(' | ') : 'no issues (movie.inspectAudio)'}` : '  audio     none');
+    for (const n of a?.notes ?? []) L.push(`  note      ${n}`);
   }
   for (const ex of report.exports ?? []) {
     if (ex.error) { L.push(`  export    ${ex.format}: FAILED — ${ex.error}`); continue; }
     const v = ex.video?.error ? `video: ${ex.video.error}` : `video ${ex.video.duration.toFixed(2)} s ${ex.video.width}×${ex.video.height}`;
     const au = ex.audio ? (ex.audio.error ? `audio: ${ex.audio.error}` : `audio ${ex.audio.duration} s, peak ${ex.audio.peakDb} dBFS, rms/s [${ex.audio.rmsDbPerSecond.join(' ')}]`) : 'no audio track';
-    L.push(`  export    ${ex.format} ok · ${kb(ex.bytes)} · ${v} · ${au}`);
+    L.push(`  export    ${ex.format}${ex.draft ? ' (draft)' : ''} ok · ${kb(ex.bytes)} · ${v} · ${au}`);
   }
   L.push(`  files     ${Object.values(report.files).join('  ')}`);
   L.push(report.problems.length ? `RESULT: ${report.problems.length} PROBLEM(S)\n  - ${report.problems.join('\n  - ')}` : 'RESULT: OK — nothing to fix. Look at the contact sheet before you call it done.');
@@ -419,7 +479,7 @@ if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href)
     if (typeof WebSocket === 'undefined') throw new Error('Node >= 22 is needed (built-in WebSocket)');
     const opts = parseArgs(process.argv.slice(2));
     if (!opts.page) {
-      console.error('usage: node ai/tools/check.mjs <page.html> [--out DIR] [--frames N] [--formats mp4,webm] [--no-export] [--timeout S] [--root DIR] [--chrome PATH]');
+      console.error('usage: node ai/tools/check.mjs <page.html> [--out DIR] [--frames N] [--formats mp4,webm] [--no-export] [--draft] [--at 3.5,title@end] [--onion 1:3] [--query a=1&b=2] [--timeout S] [--root DIR] [--chrome PATH]');
       process.exit(2);
     }
     const report = await runCheck(opts);

package/ai/tools/render.mjs

@@ -13,6 +13,8 @@
  *
  * Options: -o, --out FILE (default ./<page name>.<format>; the container follows the extension: mp4 webm mov mkv) ·
  *          --format mp4|webm|mov|mkv|pdf (a .pdf is the deck as pages: one picture per page of a movie with `stops`; --all-stops makes a page of every stop) · --quality very-low|low|medium|high|very-high (video and audio bitrate, default high) ·
+ *          --range A:B (only seconds A to B; 2: runs to the end, :5 starts at the beginning) · --scene NAME (the span of a top-level layer: a movie's scene) · --scale S (output size, 0 < S <= 1: smaller picture, smaller file) ·
+ *          --draft (for looking: half size, low quality, no motion blur; a --quality you give still wins) ·
  *          --motion-blur SAMPLES (2-64: each frame is drawn that many times over the shutter and averaged; overrides the page's own motionBlur) ·
  *          --shutter FRACTION (with --motion-blur: how long the shutter is open, 0-1 of a frame, default 0.5) ·
  *          --video-codec C · --audio-codec C · --query "a=1&b=2" (added to the page URL) · --fail-on-warn (exit 1 when the page
@@ -41,7 +43,7 @@ export function defaultOutput(page, format) {
 }
 
 export function parseRenderArgs(argv) {
-  const o = { page: null, out: null, format: null, quality: 'high', videoCodec: null, audioCodec: null, allStops: false, motionBlur: null, shutter: null, query: null, failOnWarn: false, quiet: false, timeout: 900, root: null, chrome: null };
+  const o = { range: null, scene: null, scale: null, draft: false, qualityGiven: false, page: null, out: null, format: null, quality: 'high', videoCodec: null, audioCodec: null, allStops: false, motionBlur: null, shutter: null, query: null, failOnWarn: false, quiet: false, timeout: 900, root: null, chrome: null };
   const need = (i, name) => { if (i + 1 >= argv.length) throw new Error(`${name} needs a value`); return argv[i + 1]; };
   for (let i = 0; i < argv.length; i++) {
     const a = argv[i];
@@ -50,6 +52,7 @@ export function parseRenderArgs(argv) {
       o.format = need(i++, a).toLowerCase();
       if (!FORMATS.includes(o.format)) throw new Error(`--format must be mp4, webm, mov, mkv or pdf (got "${o.format}")`);
     } else if (a === '--quality') {
+      o.qualityGiven = true;
       o.quality = need(i++, a);
       if (!QUALITIES.includes(o.quality)) throw new Error(`--quality must be very-low, low, medium, high or very-high (got "${o.quality}")`);
     } else if (a === '--video-codec') o.videoCodec = need(i++, a);
@@ -60,7 +63,17 @@ export function parseRenderArgs(argv) {
     } else if (a === '--shutter') {
       o.shutter = Number(need(i++, a));
       if (!(o.shutter > 0 && o.shutter <= 1)) throw new Error(`--shutter must be above 0 and at most 1 (0.5 is a 180° shutter), got "${argv[i]}"`);
-    } else if (a === '--query') o.query = need(i++, a).replace(/^\?/, '');
+    } else if (a === '--range') {
+      const m = need(i++, a).match(/^(\d+(?:\.\d+)?)?:(\d+(?:\.\d+)?)?$/);
+      if (!m || (m[1] === undefined && m[2] === undefined)) throw new Error(`--range must look like 2:5 (seconds; 2: runs to the end, :5 starts at the beginning), got "${argv[i]}"`);
+      o.range = [m[1] === undefined ? null : Number(m[1]), m[2] === undefined ? null : Number(m[2])];
+      if (o.range[0] !== null && o.range[1] !== null && !(o.range[0] < o.range[1])) throw new Error(`--range ${argv[i]}: it must start before it ends (2:5 is seconds 2 to 5)`);
+    } else if (a === '--scene') o.scene = need(i++, a);
+    else if (a === '--scale') {
+      o.scale = Number(need(i++, a));
+      if (!(o.scale > 0 && o.scale <= 1)) throw new Error(`--scale must be above 0 and at most 1 (0.5 is half size), got "${argv[i]}"`);
+    } else if (a === '--draft') o.draft = true;
+    else if (a === '--query') o.query = need(i++, a).replace(/^\?/, '');
     else if (a === '--all-stops') o.allStops = true;
     else if (a === '--fail-on-warn') o.failOnWarn = true;
     else if (a === '--quiet') o.quiet = true;
@@ -74,6 +87,8 @@ export function parseRenderArgs(argv) {
   if (o.shutter !== null && o.motionBlur === null) throw new Error('--shutter goes with --motion-blur SAMPLES');
   if (o.allStops && o.format !== 'pdf' && !(o.out && formatFromPath(o.out) === 'pdf')) throw new Error('--all-stops goes with a PDF (-o deck.pdf)');
   o.format ??= (o.out ? formatFromPath(o.out) : null) ?? 'mp4';
+  if (o.range && o.scene !== null) throw new Error('--range and --scene cannot be used together: a scene is a range');
+  if (o.format === 'pdf' && (o.range || o.scene !== null || o.scale !== null || o.draft)) throw new Error('--range, --scene, --scale and --draft are not for a PDF (a PDF is the pages of a deck)');
   return o;
 }
 
@@ -81,16 +96,16 @@ const UPLOAD = '/__pixi_effects_out';
 const kb = n => (n >= 1048576 ? `${(n / 1048576).toFixed(2)} MB` : `${Math.max(1, Math.round(n / 1024))} KB`);
 
 /** The page's side: render, and PUT the Blob to our server (so a long video never goes through base64). */
-const renderScript = (format, quality, videoCodec, audioCodec, motionBlur, shutter, allStops) => `(() => {
+const renderScript = (format, quality, videoCodec, audioCodec, motionBlur, shutter, allStops, part = {}) => `(() => {
   window.__r = { state: 'running', progress: 0 };
   movie.on('progress', e => { window.__r.progress = e.progress; });
   (async () => {
     try {
-      const video = { bitrate: ${JSON.stringify(quality)}${videoCodec ? `, codec: ${JSON.stringify(videoCodec)}` : ''} };
+      const video = { ${[part.draft && !part.qualityGiven ? null : `bitrate: ${JSON.stringify(quality)}`, videoCodec ? `codec: ${JSON.stringify(videoCodec)}` : null].filter(Boolean).join(', ')} };
       const audio = { bitrate: ${JSON.stringify(quality)}${audioCodec ? `, codec: ${JSON.stringify(audioCodec)}` : ''} };
       const blob = ${JSON.stringify(format)} === 'pdf'
         ? await movie.exportPDF({ which: ${allStops ? "'stops'" : "'pages'"}, title: document.title })
-        : await movie.render({ format: ${JSON.stringify(format)}, video, audio${motionBlur ? `, motionBlur: { samples: ${motionBlur}${shutter ? `, shutter: ${shutter}` : ''} }` : ''} });
+        : await movie.render({ format: ${JSON.stringify(format)}, video, audio${part.range ? `, range: [${part.range[0] ?? 0}, ${part.range[1] ?? 'movie.duration'}]` : ''}${part.scene ? `, range: ${JSON.stringify(part.scene)}` : ''}${part.scale ? `, scale: ${part.scale}` : ''}${part.draft ? ', draft: true' : ''}${motionBlur ? `, motionBlur: { samples: ${motionBlur}${shutter ? `, shutter: ${shutter}` : ''} }` : ''} });
       const res = await fetch(${JSON.stringify(UPLOAD)}, { method: 'PUT', body: blob });
       if (!res.ok) throw new Error('could not hand the file to the command (' + res.status + ')');
       window.__r = { state: 'done', bytes: blob.size, type: blob.type };
@@ -156,7 +171,7 @@ export async function runRender(opts, log = console.log, progress = () => {}) {
     }
     Object.assign(result, { duration: info.duration, frames: info.totalFrames, width: info.width, height: info.height, frameRate: info.frameRate });
 
-    await cdp.eval(renderScript(opts.format, opts.quality, opts.videoCodec, opts.audioCodec, opts.motionBlur, opts.shutter, opts.allStops));
+    await cdp.eval(renderScript(opts.format, opts.quality, opts.videoCodec, opts.audioCodec, opts.motionBlur, opts.shutter, opts.allStops, { range: opts.range, scene: opts.scene, scale: opts.scale, draft: opts.draft, qualityGiven: opts.qualityGiven }));
     let state;
     for (;;) {
       left();
@@ -190,7 +205,7 @@ if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href)
     if (typeof WebSocket === 'undefined') throw new Error('Node >= 22 is needed (built-in WebSocket)');
     const opts = parseRenderArgs(process.argv.slice(2));
     if (!opts.page) {
-      console.error('usage: node ai/tools/render.mjs <page.html> [-o out.mp4] [--format mp4|webm|mov|mkv|pdf] [--quality very-low|low|medium|high|very-high] [--query a=1] [--fail-on-warn] [--quiet] [--timeout S] [--root DIR] [--chrome PATH]');
+      console.error('usage: node ai/tools/render.mjs <page.html> [-o out.mp4] [--format mp4|webm|mov|mkv|pdf] [--range A:B | --scene NAME] [--scale S] [--draft] [--quality very-low|low|medium|high|very-high] [--query a=1] [--fail-on-warn] [--quiet] [--timeout S] [--root DIR] [--chrome PATH]');
       process.exit(2);
     }
     let last = -1;

package/dist/Composition-6JMXWNVV.cjs

@@ -0,0 +1,14 @@
+'use strict';
+
+var chunkJW67MDHQ_cjs = require('./chunk-JW67MDHQ.cjs');
+require('./chunk-ANO5R2E6.cjs');
+require('./chunk-UQBGW5DO.cjs');
+
+
+
+Object.defineProperty(exports, "CompositionSequence", {
+  enumerable: true,
+  get: function () { return chunkJW67MDHQ_cjs.CompositionSequence; }
+});
+//# sourceMappingURL=Composition-6JMXWNVV.cjs.map
+//# sourceMappingURL=Composition-6JMXWNVV.cjs.map

package/dist/{Composition-3WWNVRR5.cjs.map → Composition-6JMXWNVV.cjs.map}

@@ -1 +1 @@
-{"version":3,"sources":[],"names":[],"mappings":"","file":"Composition-3WWNVRR5.cjs"}
+{"version":3,"sources":[],"names":[],"mappings":"","file":"Composition-6JMXWNVV.cjs"}

package/dist/Composition-MLBHYYFF.js

@@ -0,0 +1,5 @@
+export { CompositionSequence } from './chunk-UXDR3ZDU.js';
+import './chunk-SG3Y66FN.js';
+import './chunk-DKGG7WD4.js';
+//# sourceMappingURL=Composition-MLBHYYFF.js.map
+//# sourceMappingURL=Composition-MLBHYYFF.js.map

package/dist/{Composition-VJWY2NDL.js.map → Composition-MLBHYYFF.js.map}

@@ -1 +1 @@
-{"version":3,"sources":[],"names":[],"mappings":"","file":"Composition-VJWY2NDL.js"}
+{"version":3,"sources":[],"names":[],"mappings":"","file":"Composition-MLBHYYFF.js"}

package/dist/Controller.d.cts

@@ -1,4 +1,4 @@
-import { f as Movie } from './Movie-oA0SUAyb.cjs';
+import { h as Movie } from './Movie-K2YuVAdg.cjs';
 import 'pixi.js';
 import 'gsap';
 import './types-SS51lP6O.cjs';

package/dist/Controller.d.ts

@@ -1,4 +1,4 @@
-import { f as Movie } from './Movie-DilBC348.js';
+import { h as Movie } from './Movie-DlHQ9C02.js';
 import 'pixi.js';
 import 'gsap';
 import './types-SS51lP6O.js';

package/dist/{Movie-DilBC348.d.ts → Movie-DlHQ9C02.d.ts}

@@ -5,6 +5,12 @@ import { U as Stop, e as AssetSpec, c as CompositionSpec } from './types-SS51lP6
 interface AudioInspectOptions {
     /** Width of each loudness window in seconds. Default 0.1. */
     window?: number;
+    /** The scenes to measure one by one (`movie.inspectAudio()` fills this from the movie's named top-level compositions). Default: the whole movie as one. */
+    scenes?: Array<{
+        name: string;
+        start: number;
+        end: number;
+    }>;
 }
 /** One sound measured ON ITS OWN (not mixed), so overlapping layers do not blur it. */
 interface SoundMeasure {
@@ -44,8 +50,76 @@ interface AudioReport {
         peakDb: number;
         brightnessHz: number;
     }>;
-    /** Problems worth fixing: limiting, inaudible layers, sounds cut off by the end of the movie. Read this first. */
+    /** Problems worth fixing: limiting, clipping, a true peak above 0 dBTP, inaudible layers, sounds cut off by the end of the movie. Read this first. */
     issues: string[];
+    /** The mix as a whole (ITU-R BS.1770 loudness; `integratedLufs` is null for a mix shorter than 0.4 s or with nothing above −70 LUFS). */
+    loudness: {
+        integratedLufs: number | null;
+        truePeakDb: number;
+        clippedSamples: number;
+        silences: Array<{
+            from: number;
+            to: number;
+        }>;
+    };
+    /** The same measure for each scene (`silent`: nothing above −60 dBFS). */
+    scenes: Array<{
+        name: string;
+        from: number;
+        to: number;
+        lufs: number | null;
+        peakDb: number;
+        silent: boolean;
+    }>;
+    /** When each sound starts: what a waveform marks. */
+    cues: Array<{
+        t: number;
+        name: string;
+    }>;
+    /** Advice, not faults: a mix that is quiet or loud for web video, little headroom, silent stretches. */
+    notes: string[];
+}
+
+interface FontReport {
+    /** Text layers none of whose fonts is available here: they are drawn in a fallback. */
+    missing: Array<{
+        layer: string;
+        family: string;
+    }>;
+    /** Web fonts (`@font-face`) whose file could not be loaded and that a text layer uses. */
+    failed: string[];
+    /** Web fonts whose file could not be loaded but no text layer uses (an unused face: worth a look, not a fault). */
+    failedUnused: string[];
+}
+
+/** One kind of issue, with how many frames it was seen in. Issues that differ only by numbers are one kind. */
+interface IssueGroup {
+    message: string;
+    count: number;
+    firstFrame: number;
+    lastFrame: number;
+}
+interface ReviewOptions {
+    /** Moments to resolve and report: `3.5`, `50%`, `f120`, `title@end` (comma-separated). */
+    at?: string;
+    /** Every layout issue is a problem (by default text overlaps are only listed for review). */
+    strict?: boolean;
+}
+interface ReviewReport {
+    /** How many frames were inspected. */
+    frames: number;
+    /** Text cut off by an edge, outside the canvas, or with no size (with `strict`: every issue). */
+    problems: IssueGroup[];
+    /** Text overlaps and fonts that are not available: often intentional, look at them on the contact sheet. */
+    review: IssueGroup[];
+    fonts: FontReport;
+    /** The sound as numbers (`movie.inspectAudio()`), or null for a movie with no audio. */
+    audio: AudioReport | null;
+    /** The moments of `at`, as frames with a label that is safe as a file name. */
+    at: Array<{
+        label: string;
+        frame: number;
+    }>;
 }
 
 interface Rect {
@@ -107,6 +181,8 @@ interface TimelineRow {
         start: number;
         end: number;
     }>;
+    /** With `parts`: the name of each layer the row stands for, in the same order (so `render({ range: 'pop-3' })` can find it). */
+    partNames?: string[];
     /** A short text for the tooltip (a text layer's words, an asset name). */
     detail?: string;
 }
@@ -196,6 +272,15 @@ interface RenderOptions {
         codec?: string;
         bitrate?: 'very-low' | 'low' | 'medium' | 'high' | 'very-high';
     };
+    /**
+     * Only part of the movie: `[from, to]` in seconds, or the name of a top-level layer (its start to its end). The file starts at 0
+     * and its sound is cut the same way (with a 10 ms fade on a cut edge). Past the end, backwards or an unknown name is an error.
+     */
+    range?: [number, number] | string;
+    /** Output size relative to the canvas, above 0 and at most 1. Each frame is drawn at full size and copied smaller before it is encoded: the file and the encoding get smaller, the drawing is not faster. */
+    scale?: number;
+    /** For looking, not for delivering: `scale: 0.5`, `video.bitrate: 'low'` and no motion blur. Anything you set yourself wins. */
+    draft?: boolean;
 }
 interface SnapshotOptions {
     /** Motion blur for this picture (see `MovieOptions.motionBlur`); overrides the movie's own setting, `false` turns it off. */
@@ -248,6 +333,19 @@ interface ContactSheetOptions {
     cellWidth?: number;
     as?: 'blob' | 'dataURL';
 }
+interface OnionSkinOptions {
+    /** Where the movement starts, in seconds. Default 0. */
+    from?: number;
+    /** Where it ends, in seconds. Default: the end of the movie. */
+    to?: number;
+    /** How many frames are overlaid, 1–64, spread evenly from `from` to `to`. Default 8. */
+    count?: number;
+    /** Output size relative to the canvas, above 0 and at most 4. Default 1. */
+    scale?: number;
+    /** Motion blur for these pictures (see `MovieOptions.motionBlur`); overrides the movie's own setting, `false` turns it off. */
+    motionBlur?: MotionBlurSpec;
+    as?: 'blob' | 'dataURL';
+}
 interface FrameEvent {
     frame: number;
     totalFrames: number;
@@ -419,6 +517,17 @@ declare class Movie {
         motionBlur?: MotionBlurSpec;
         onImage?: (image: StopImage) => void;
     }): Promise<Blob>;
+    /**
+     * One picture of a movement: `count` frames from `from` to `to` drawn one over the other, each later one stronger, so a thing that
+     * moves leaves a trail (its path and its easing: even steps = constant speed, bunched = slow) and what stays still stays itself.
+     * The movie is left where it was.
+     */
+    onionSkin(opts?: OnionSkinOptions & {
+        as?: 'blob';
+    }): Promise<Blob>;
+    onionSkin(opts: OnionSkinOptions & {
+        as: 'dataURL';
+    }): Promise<string>;
     /**
      * Several frames on ONE image, each labelled with its frame number and time — the cheapest way to
      * check a whole animation by eye. Restores the current frame afterwards.
@@ -447,6 +556,21 @@ declare class Movie {
      * The soundtrack, measured: when every audio layer plays, how loud the mix is over time, and `issues`
      * (limiting, inaudible layers, sounds cut off by the end). Use it to CHECK sound you cannot hear.
      */
+    /** The pictures to look at for moments such as `3.5`, `50%`, `f120`, `title@end` (comma-separated). A mistake says what could not be read. */
+    resolveAt(list: string): Array<{
+        label: string;
+        frame: number;
+    }>;
+    /**
+     * One call that looks at everything `pixi-effects-check` looks at inside the page: layout issues over the whole timeline (every
+     * scene's first and last frame and a frame every 0.25 s), fonts and the sound. See `ReviewReport`. Page warnings are in `window.__logs`. The movie is left as it was.
+     */
+    review(opts?: ReviewOptions): Promise<ReviewReport>;
+    /**
+     * The fonts of the text layers: `missing` lists layers none of whose `fontFamily` entries is available in this browser (they are
+     * drawn in a fallback font), `failed` lists web fonts (`@font-face`) whose file could not be loaded.
+     */
+    inspectFonts(): FontReport;
     inspectAudio(opts?: AudioInspectOptions): AudioReport;
     /**
      * Draw the stage now. PixiJS's CullerPlugin only culls inside `app.render()` (the ticker), and we render
@@ -509,4 +633,4 @@ declare class Movie {
     destroy(): Promise<void>;
 }
 
-export { type AudioInspectOptions as A, type ContactSheetOptions as C, type FrameEvent as F, type InspectOptions as I, type LayerInfo as L, type MotionBlurOptions as M, type ProgressEvent as P, type RenderOptions as R, type SnapshotOptions as S, type TimelineData as T, type VolumeEvent as V, type AudioReport as a, type AudioSourceReport as b, type InspectReport as c, type LoaderOption as d, type MotionBlurSpec as e, Movie as f, type MovieErrorEvent as g, type MovieOptions as h, type SoundMeasure as i, type StopEvent as j, type StopImage as k, type StopImagesOptions as l, type TimelineHtmlOptions as m, type TimelineRow as n, type TimelineSvgOptions as o, type TimelineTransition as p, dismissLoader as q, failLoader as r, resolveLoader as s };
+export { type AudioInspectOptions as A, type ContactSheetOptions as C, type FontReport as F, type InspectOptions as I, type LayerInfo as L, type MotionBlurOptions as M, type OnionSkinOptions as O, type ProgressEvent as P, type RenderOptions as R, type SnapshotOptions as S, type TimelineData as T, type VolumeEvent as V, type AudioReport as a, type AudioSourceReport as b, type FrameEvent as c, type InspectReport as d, type IssueGroup as e, type LoaderOption as f, type MotionBlurSpec as g, Movie as h, type MovieErrorEvent as i, type MovieOptions as j, type ReviewOptions as k, type ReviewReport as l, type SoundMeasure as m, type StopEvent as n, type StopImage as o, type StopImagesOptions as p, type TimelineHtmlOptions as q, type TimelineRow as r, type TimelineSvgOptions as s, type TimelineTransition as t, dismissLoader as u, failLoader as v, resolveLoader as w };