@moood/render 0.1.4 → 0.1.5

package/README.md

@@ -2,7 +2,9 @@
 
 A scene of [moood](https://moood.me) rendered on your machine — with moood's own engine, the version
 the site runs (`moood-render --version`), in a Chromium you have already (nothing is downloaded, no
-network): a PNG and the errors the scene's code threw.
+network): frames at any second of it, a sheet of them, a video of a stretch, what is where as numbers,
+two versions side by side — and the errors the scene's code threw and what the engine found wrong
+with it (a painting cut off by its box in the frame, an unknown camera target …).
 
     npm i -g @moood/render
     moood-render <world>/scenes/<folder> --at 0,2.5 --device 16:9 --out frame.png
@@ -10,28 +12,81 @@ network): a PNG and the errors the scene's code threw.
 - **A scene** is a folder of a world's repository (`scene.json` and its code beside it — see
   https://github.com/moood-me/docs), or a spec as a `.json` file. The modules it lists are read from
   the world's `modules/` (`--world <the world's repository>`; by default two folders up).
-- **`--at`** — moments, in seconds from the scene's start: a frame each (`frame-2.5s.png`). Time is a
-  virtual clock stepped from the start, a tenth of a second at a time; chance (`Math.random`) is the
-  same every run. The same moment and state give the same picture — pixel-close, not bit-equal (the
-  GPU emulation's rounding): compare frames with a small tolerance.
+- **`--at`** — moments, in seconds from the scene's start: a frame each (`frame-2.5s.png`); `0:90:10`
+  — every 10 s from 0 to 90. Time is a virtual clock stepped from the start; chance (`Math.random`)
+  is the same every run. **Only the frames taken are drawn**: up to each moment the scene goes on
+  unseen — its scripts, its state, the memory its modules keep (springs, steps: their code runs every
+  frame as for something out of sight) — so the 80th second costs seconds, not minutes, and looks as
+  it does when the film plays through. The same moment and state give the same picture —
+  pixel-close, not bit-equal (the grain, the GPU emulation's rounding).
 - **`--state '{"dawn": 1}'`** — values over the scene's starting state.
 - **`--set '[[4, "beat", "cover"], [6, "dawn", 1, 3]]'`** — values set as the scene goes, as a game sets
   them: `[second, key, value, over?, ease?]` (the clock stops at each one's second). A film's beat at
-  its second; a branch begun mid-beat.
+  its second; a branch begun mid-beat. `[4, "cut", {"camera_target": "keeper"}]` — a cut (`scene.cut`).
+- **`--states '[{"pose": "bow"}, {"pose": "kneel", "facing": 90}]'`** — the scene played from its start
+  once for each of these (over `--state`): a frame each at each moment (`frame-s1-2s.png` …); with
+  `--sheet`, one picture of them all — a row for each, its moments across, labelled with its values — a gallery of a figure's poses (a
+  world's stand scene that shows a person in the pose its state names), a value's steps side by side.
+- **`--views '[{"camera_target": "keeper", "camera_shot": "close"}, {"camera_x": 2}]'`** — other cameras on
+  each moment: a frame each (`frame-12s-v1.png` …) of that very moment, the camera there at once; the
+  film itself (its state, its clock, its own camera) goes on untouched.
+- **`--sheet sheet.png`** — the frames in one picture, each labelled with its second (and view).
+- **`--video walk.mp4 --from 40 --to 47 --fps 12`** — that stretch as a video (`.mp4`, `.webm`, `.gif`):
+  rhythm, weight, follow-through, which a sheet only hints at. Written by an ffmpeg already here —
+  `MOOOD_FFMPEG`, else the one on the PATH, else the one Playwright keeps beside its browsers (that
+  one writes `.webm` only). `--device tile` (640×360) for a quick look.
+- **`--debug`** — what is where, drawn over the frame (the scene's `?debug` on the site): each element
+  seen — its box and id, its anchor (a ring), its `e.at` point (a cross), its named points (`#name`), its parts
+  (dashed), what its last painting cost,
+  and what its code wrote with `e.debug(value, x?, y?)` (a module's poses and their weights, a target
+  as a point); the scene's second, and its errors and warnings at the top. On the site, `?debug=keeper,boy` — only those.
+- **`--json`** — the same as numbers, beside each frame (`frame-8s.json`): `t`, `camera`, `frame`,
+  `state` (every value at that moment), and per element (by id) `kind`, `seen`, `box` `[x, y, w, h]` (in
+  the frame's pixels — where its painting may reach), `anchor`, `at`, `points` (those its code names:
+  `e.at(x, y, name)`), `parts` (`e.part`: each one's box and distance), `distance` (m), `fade` (as it comes
+  within 60 cm of the eye), `notes` (`e.debug`), `paint` `{ms, repaint: frame | state | once}`.
+- **`--crop <id>`** — each frame only around that element (its box, a margin round it).
+- **`--vs <ref | folder | spec.json>`** — the same moments of another version of the scene: a branch or
+  commit of the world's repository (`--vs main`: before your branch), or another checkout's folder.
+  Each frame is A | B | where they differ (red, brighter the more), and how much: `frame-3s.png —
+  differs: 0.42% of pixels, by up to 37`. Chance is seeded the same in both, so fire and water flicker
+  alike and the difference is what changed. **`--vs-engine <dir>`** — rendered by another engine (a folder
+  like `moood/web/scene` of another checkout); with both, another scene by another engine. An engine
+  older than this one draws every frame up to the moment (slowly).
+- **A world** (its folder, or its `scenes/`) instead of a scene: each of its scenes in turn, the files
+  named by their folders (`frame-kukhnya-2s.png`, `sheet-kukhnya.png`). With `--vs main` — before
+  merging a change to a module or the engine (`--vs-engine`): every scene of the world before and
+  after, and at the end the scenes listed by how much they changed, the most changed first; a scene
+  new on the branch is said so.
 - **What the scene told** (`scene.tell` — a film's `beat:<name>` as a beat ends) is printed with its
   second: `told at 4.50s: beat:cover`.
 - **`--device`** — `16:9` (1600×900), `4:3`, `21:9` (the same height), `tile` (640×360), `big` (1920×1080).
 - **`--bare`** — without the title and captions over it.
 - **The browser**: `--chromium <path>`, or `MOOOD_CHROMIUM`, or Playwright's own (`PLAYWRIGHT_BROWSERS_PATH`).
 
+**What is wrong** is said on stderr, once each, with the second it was first seen: errors the scene's
+code threw (exit 1); and, as `warning: …` (they leave the exit code 0), what the engine found (a
+painting cut off by its box, an unknown `camera_target`); a key
+set from outside — `--set`, `--state`, or the game on the site — that the scene does not know (not
+in its `state`, and nothing in it — its scripts, its painting — has read it by the last moment taken:
+a mistyped key does nothing, silently); and what
+its modules said they do not know — a module calls `e.warn(text)` (an element's; `scene.warn` in a
+script), and the text is said once: `Pete: no pose "wawe" — the poses: stand, wave, crouch, point`.
+
+Asked for wrongly (an unknown option, a moment that is not a number, `--set` given one row, a world
+instead of a scene …), it says what is wrong and how it is asked for, and exits 2. The paths it
+writes are printed. Exits 1 if the scene's code threw or the engine found something wrong.
+
 From code:
 
     import { render, readScene, readModules } from '@moood/render';
-    const spec = readScene('world/scenes/kukhnya');
-    const [frame] = await render({ spec, modules: readModules('world', spec), at: [3] });
-    // frame.png (a Buffer), frame.errors, frame.tells ([{at, text, about}] so far)
+    const spec = readScene('world/scenes/kukhnya');          // readScene(folder, {world, ref: 'main'}) — at a commit
+    const [frame] = await render({ spec, modules: readModules('world', spec), at: [80], look: true });
+    // frame.png (a Buffer), frame.errors, frame.tells ([{at, text, about}] so far), frame.look (--json)
 
-Exits 1 if the scene's code threw.
+`render` also takes `debug`, `crop`, `engine` (another engine's folder) and `each` (called with each
+frame as it is taken, instead of keeping them); `compose.js` lays frames out (`sheet`, `compare`),
+`video.js` writes them as a video.
 
 ## A person's motion
 

package/cli.js

@@ -1,50 +1,300 @@
 #!/usr/bin/env node
-// moood-render <scene folder | spec.json> [--world <its world's repository>] [--device 16:9] [--at 0,1.5,3]
-//              [--state '{"dawn":1}'] [--set '[[4,"beat","cover"]]'] [--bare] [--out frame.png] [--chromium <path>]
-// A frame for each moment (--out frame.png → frame.png, or frame-1.5s.png … for several); the
-// errors the scene's code threw, on stderr; what its scripts told (scene.tell), on stdout. The world defaults to the folder two levels up
-// (<world>/scenes/<folder>): where its modules are.
-// moood-render motion <motion.json> [--at 0,1.5,3] [--views front,side] [--kit] [--out motion.png]
-// A person's motion made by a model (list_motions(key, body=true) saved as a file) as frames on its body.
-import { statSync, writeFileSync, readFileSync } from 'node:fs';
-import { dirname, resolve } from 'node:path';
+// moood-render <scene folder | spec.json | world> — a scene (or each of a world's) rendered here (moood-render --help says how).
+// Frames (or a sheet of them, a video, two versions compared) written where --out says, their paths
+// on stdout; what the scene's scripts told (scene.tell) on stdout; the errors its code threw on stderr
+// (exit 1), and what the engine found wrong with it (warning: …) — exit 0 for those alone. Asked for
+// wrongly: what is wrong, on stderr (exit 2).
+import { existsSync, readFileSync, readdirSync, statSync, writeFileSync } from 'node:fs';
+import { basename, dirname, extname, join, resolve } from 'node:path';
 import { parseArgs } from 'node:util';
-import { ENGINE, readModules, readScene, render, renderMotion } from './index.js';
-
-const { values: o, positionals: [what, file] } = parseArgs({
-  allowPositionals: true,
-  options: { world: { type: 'string' }, device: { type: 'string', default: '16:9' }, at: { type: 'string', default: '0' },
-             state: { type: 'string' }, set: { type: 'string' }, bare: { type: 'boolean' }, out: { type: 'string', default: 'frame.png' },
-             chromium: { type: 'string' }, version: { type: 'boolean' }, views: { type: 'string', default: 'front,side' },
-             kit: { type: 'boolean' } },
-});
-if (o.version) { console.log(`moood engine ${ENGINE}`); process.exit(0); }
-if (!what) { console.error('moood-render <scene folder | spec.json> [--world …] [--device 16:9] [--at 0,1.5] [--state {…}] [--set [[s,k,v],…]] [--bare] [--out frame.png]'); process.exit(2); }
+import { spawnSync } from 'node:child_process';
+import { DEVICES, ENGINE, readModules, readScene, render, renderMotion } from './index.js';
+import { compare, sheet } from './compose.js';
+import { VIDEOS, video } from './video.js';
+
+const HELP = `moood-render <world>/scenes/<folder> | <spec.json> | <world> [options]
+moood-render motion <motion.json> [--at 0,1.5,3] [--views front,side] [--kit] [--out motion.png]
+  a person's motion made by a model (list_motions(key, body=true) saved as a file) as frames on its
+  body: a row per view (front, side, back), a column per moment (default eight across it); --kit —
+  the people module's skeleton over it
+
+  a world (or its scenes/): each of its scenes in turn, the files named by their folders
+  (frame-kukhnya-2s.png) — with --vs main, every scene before and after, listed at the end, the most changed first
 
-if (what === 'motion') {
-  if (!file) { console.error('moood-render motion <motion.json> [--at 0,1.5] [--views front,side] [--kit] [--out motion.png]'); process.exit(2); }
-  const made = JSON.parse(readFileSync(file, 'utf8'));
-  const { png, errors } = await renderMotion({ motion: made.body || made, kit: o.kit ? made.clip : null, chromium: o.chromium,
-                                              at: process.argv.includes('--at') ? o.at.split(',').map(Number) : null, views: o.views.split(',') });
+  --at 0,2.5,10      the moments, in seconds from the scene's start: a frame each;
+                     a range from:to:step — 0:20:2 — is every 2 s from 0 to 20
+  --out frame.png    where (several frames: frame-2.5s.png …)
+  --device 16:9      ${Object.keys(DEVICES).join(', ')}
+  --state '{"dawn": 1}'               values over the scene's starting state
+  --set '[[4, "beat", "cover"]]'      values set as the scene goes: [second, key, value, over?, ease?]
+  --views '[{"camera_target": "keeper"}]' other cameras on each moment (the film untouched)
+  --states '[{"pose": "bow"}, {"pose": "kneel"}]'  the scene played from its start once for each of
+                     these (over --state): a frame each at each moment (frame-s1-2s.png …) — with
+                     --sheet, a grid of variants (a figure's poses, a value's steps) in one picture
+  --bare             without the title and captions
+  --debug            what is where, over the frame: ids, boxes, anchors, points, the code's notes (e.debug)
+  --json             what is where, as numbers, beside each frame (frame-2.5s.json): each element's box
+                     in the frame's pixels, whether it is seen, its points, notes, paint cost; the state
+  --crop <id>        each frame only around that element
+  --sheet <out.png>  the frames in one picture, labelled with their seconds
+  --video <out.mp4> --from 2 --to 8 [--fps 12]   that stretch as a video (.mp4, .webm, .gif)
+  --vs <ref | folder | spec.json>    the same moments of another version of the scene — a branch or
+                     commit of the world's repository (main), another checkout's folder: side by side
+                     with where they differ (frame-2.5s.png: A | B | difference)
+  --vs-engine <dir>  … rendered by another engine: a folder like moood/web/scene
+  --world <dir>      the world's repository (default: two folders up from the scene's)
+  --chromium <path>  the browser (else MOOOD_CHROMIUM, else Playwright's own)
+  --version          the engine's version`;
+
+const OPTIONS = {
+  world: { type: 'string' }, device: { type: 'string', default: '16:9' }, at: { type: 'string' },
+  state: { type: 'string' }, states: { type: 'string' }, set: { type: 'string' }, views: { type: 'string' }, bare: { type: 'boolean' }, debug: { type: 'boolean' },
+  json: { type: 'boolean' }, crop: { type: 'string' }, sheet: { type: 'string' }, video: { type: 'string' },
+  from: { type: 'string' }, to: { type: 'string' }, fps: { type: 'string' }, vs: { type: 'string' }, 'vs-engine': { type: 'string' },
+  out: { type: 'string', default: 'frame.png' }, chromium: { type: 'string' }, version: { type: 'boolean' }, help: { type: 'boolean' },
+  kit: { type: 'boolean' },
+};
+// asked for wrongly: said plainly, with the way it is asked for
+function wrong(msg) { console.error(`moood-render: ${msg}\n(moood-render --help — all it takes)`); process.exit(2); }
+// the option meant, for one mistyped
+const edits = (a, b) => { let row = [...Array(b.length + 1).keys()]; for (const x of a) { const next = [row[0] + 1]; [...b].forEach((y, j) => next.push(Math.min(row[j + 1] + 1, next[j] + 1, row[j] + (x === y ? 0 : 1)))); row = next; } return row[b.length]; };
+const near = name => Object.keys(OPTIONS).map(k => [k, k.startsWith(name) ? 0 : edits(name, k)]).filter(([, d]) => d <= 2).sort((a, b) => a[1] - b[1])[0]?.[0];
+
+let o, rest;
+try { ({ values: o, positionals: rest } = parseArgs({ allowPositionals: true, options: OPTIONS })); } catch (e) {
+  const opt = /'(-{1,2}[^' ]+)/.exec(e.message)?.[1], m = opt && near(opt.replace(/^-+/, ''));
+  wrong(e.code === 'ERR_PARSE_ARGS_UNKNOWN_OPTION' ? `no option ${opt}${m ? ` — --${m}?` : ''}` : e.message.split('\n')[0]);
+}
+if (o.help) { console.log(HELP); process.exit(0); }
+if (o.version) { console.log(`moood engine ${ENGINE}`); process.exit(0); }
+if (!rest.length) wrong('which scene? moood-render <world>/scenes/<folder>');
+// a person's motion (moood-render motion <motion.json>)
+if (rest[0] === 'motion') {
+  if (rest.length !== 2) wrong('which motion? moood-render motion <motion.json> (list_motions(key, body=true) saved as a file)');
+  let made;
+  try { made = JSON.parse(readFileSync(rest[1], 'utf8')); } catch (e) { wrong(`${rest[1]}: not a motion (JSON): ${e.message}`); }
+  const views = o.views ? o.views.split(',') : ['front', 'side'], at = o.at ? o.at.split(',').map(Number) : null;
+  const { png, errors } = await renderMotion({ motion: made.body || made, kit: o.kit ? made.clip : null, chromium: o.chromium, at, views });
   const out = o.out === 'frame.png' ? 'motion.png' : o.out;
   writeFileSync(out, png);
   console.log(out);
   for (const e of errors) console.error(e);
   process.exit(errors.length ? 1 : 0);
 }
+if (o.kit) wrong('--kit is for a motion (moood-render motion <motion.json> --kit)');
+if (rest.length > 1) wrong(`one scene at a time — and ${rest.slice(1).map(a => `"${a}"`).join(', ')}? (a list of moments: --at 0,2,4, no spaces)`);
+const what = resolve(rest[0]);
+
+// ── what is asked ──────────────────────────────────────────────────────
+const json = (name, text, check, example) => {
+  if (text == null) return undefined;
+  let v;
+  try { v = JSON.parse(text); } catch { wrong(`--${name}: not JSON — ${example} (keys and texts in double quotes; the whole in single quotes)`); }
+  const bad = check(v);
+  if (bad) wrong(`--${name}: ${bad} — ${example}`);
+  return v;
+};
+const plain = v => v && typeof v === 'object' && !Array.isArray(v);
+const state = json('state', o.state, v => !plain(v) && 'an object of values', `'{"dawn": 1, "girl": "gone"}'`);
+const set = json('set', o.set, v => {
+  if (!Array.isArray(v)) return 'a list of rows';
+  if (v.length && !Array.isArray(v[0])) return 'a list of rows, and this is one row: wrap it in [ ]';
+  const i = v.findIndex(r => !Array.isArray(r) || r.length < 3 || typeof r[0] !== 'number' || r[0] < 0 || typeof r[1] !== 'string' || (r[1] === 'cut' && !plain(r[2])));
+  return i >= 0 && `row ${i + 1} (${JSON.stringify(v[i])}) is not [second, "key", value, over?, ease?]${v[i]?.[1] === 'cut' ? ' — a cut: [second, "cut", {values}]' : ''}`;
+}, `'[[4, "beat", "cover"], [6, "dawn", 1, 3], [9, "cut", {"camera_target": "keeper"}]]'`);
+const states = json('states', o.states, v => (plain(v) ? 'a list of states, and this is one: wrap it in [ ]' : !Array.isArray(v) || !v.length || !v.every(plain) ? 'a list of objects of values' : null),
+  `'[{"pose": "bow"}, {"pose": "kneel", "facing": 90}]'`);
+const views = json('views', o.views, v => (plain(v) ? 'a list of cameras, and this is one: wrap it in [ ]' : !Array.isArray(v) || !v.every(plain) ? 'a list of objects of values' : null),
+  `'[{"camera_target": "keeper", "camera_shot": "close"}, {"camera_x": 2}]'`);
+if (!DEVICES[o.device]) wrong(`--device ${o.device}: one of ${Object.keys(DEVICES).join(', ')}`);
 
-const folder = statSync(what).isDirectory();
-const spec = folder ? readScene(what) : JSON.parse(readFileSync(what, 'utf8'));
-const world = o.world || (folder ? resolve(what, '..', '..') : dirname(resolve(what)));
-const at = o.at.split(',').map(Number);
-const frames = await render({ spec, modules: readModules(world, spec), device: o.device, at, state: o.state ? JSON.parse(o.state) : {},
-                              set: o.set ? JSON.parse(o.set) : [], bare: o.bare, chromium: o.chromium });
+const seconds = (name, text) => {
+  const v = Number(text);
+  if (text == null || text.trim() === '' || !Number.isFinite(v) || v < 0) wrong(`--${name} ${text ?? ''}: seconds from the scene's start (a number, 0 or more)`);
+  return v;
+};
+// --at: moments and ranges of them
+function moments(text) {
+  const out = [];
+  for (const part of text.split(',').map(s => s.trim()).filter(Boolean)) {
+    const r = part.split(':');
+    if (r.length === 1) { out.push(seconds('at', part)); continue; }
+    if (r.length !== 3) wrong(`--at ${part}: a range is from:to:step (0:20:2 — every 2 s from 0 to 20)`);
+    const [a, b, s] = r.map(x => seconds('at', x));
+    if (!(s > 0) || b < a) wrong(`--at ${part}: from:to:step — from up to to, a step above 0`);
+    for (let i = 0; a + i * s <= b + 1e-9; i++) out.push(Math.round((a + i * s) * 1000) / 1000);
+  }
+  if (!out.length) wrong('--at: which moments? 0,2.5,10 or 0:20:2');
+  return [...new Set(out)].sort((x, y) => x - y);
+}
+
+let at, fps;
+if (o.video) {
+  if (o.at) wrong('--video takes its stretch as --from, --to (and --fps), not --at');
+  if (!VIDEOS.includes(extname(o.video).toLowerCase())) wrong(`--video ${o.video}: a ${VIDEOS.join(', ')}`);
+  if (o.from == null || o.to == null) wrong('--video: which stretch? --from 2 --to 8 (seconds)');
+  const a = seconds('from', o.from), b = seconds('to', o.to);
+  if (b <= a) wrong(`--video: --to (${b}) comes after --from (${a})`);
+  fps = o.fps == null ? 12 : Number(o.fps);
+  if (!(Number.isInteger(fps) && fps >= 1 && fps <= 60)) wrong(`--fps ${o.fps}: frames a second, a whole number 1…60`);
+  if (o.crop) wrong('--crop with --video: a video\'s frames are all one size — leave --crop out');
+  if (o.sheet || o.vs || o['vs-engine'] || views || states) wrong('--video: one at a time — not with --sheet, --vs, --vs-engine, --views or --states');
+  at = Array.from({ length: Math.floor((b - a) * fps + 1e-6) + 1 }, (_, i) => Math.round((a + i / fps) * 1000) / 1000);
+} else {
+  for (const k of ['from', 'to', 'fps']) if (o[k] != null) wrong(`--${k} is for --video (--video out.mp4 --from 2 --to 8); frames: --at 2:8:0.5`);
+  at = moments(o.at ?? '0');
+  if (at.length > 300) wrong(`--at: ${at.length} frames — a video is better for that many (--video out.mp4 --from ${at[0]} --to ${at.at(-1)})`);
+}
+if (o.sheet && extname(o.sheet).toLowerCase() !== '.png') wrong(`--sheet ${o.sheet}: a .png`);
+if (extname(o.out).toLowerCase() !== '.png') wrong(`--out ${o.out}: a .png (a video: --video out.mp4)`);
+if ((o.vs || o['vs-engine']) && o.sheet) wrong('--vs with --sheet: one at a time');
+
+// ── the scene (or every scene of a world) ──────────────────────────────
+// what a path given as a scene is, said plainly when it is not one
+function specAt(path) {
+  if (!existsSync(path)) wrong(`no such file or folder: ${path}`);
+  if (!statSync(path).isDirectory()) {
+    try { return JSON.parse(readFileSync(path, 'utf8')); } catch (e) { wrong(`${path}: not a spec (JSON): ${e.message}`); }
+  }
+  if (!existsSync(join(path, 'scene.json'))) wrong(`${path}: no scene.json — a scene is a world's scenes/<folder>`);
+  try { return readScene(path); } catch (e) { wrong(e.message); }
+}
+// the scenes asked for: one, or — a world, or its scenes/ — each of them
+const scenesOf = path => {
+  if (!existsSync(path) || !statSync(path).isDirectory() || existsSync(join(path, 'scene.json'))) return null;
+  const dir = existsSync(join(path, 'scenes')) ? join(path, 'scenes') : path;
+  const inside = readdirSync(dir).filter(f => existsSync(join(dir, f, 'scene.json'))).sort();
+  return inside.length ? { world: dir === path ? join(path, '..') : path, list: inside.map(f => join(dir, f)) } : null;
+};
+const all = scenesOf(what);
+if (all && (o.video || o.crop)) wrong(`${what} is a world: --${o.video ? 'video' : 'crop'} is for one scene (<world>/scenes/<folder>)`);
+const world = resolve(o.world || (all ? all.world : existsSync(what) && statSync(what).isDirectory() ? join(what, '..', '..') : dirname(what)));
+if (o['vs-engine'] && !existsSync(join(resolve(o['vs-engine']), 'render.html'))) wrong(`--vs-engine ${o['vs-engine']}: not an engine (no render.html in it) — a folder like moood/web/scene`);
+// (a world may lie anywhere in its repository)
+const inGit = dir => spawnSync('git', ['-C', dir, 'rev-parse', '--is-inside-work-tree'], { encoding: 'utf8' }).stdout?.trim() === 'true';
+const modulesOf = (s, ref) => { try { return readModules(world, s, { ref }); } catch (e) { wrong(e.message); } };
+
+// the other version of a scene (--vs: a ref of the world's repository, or another scene's folder or spec)
+function otherOf(what, spec) {
+  if (!o.vs && !o['vs-engine']) return null;
+  let ospec = spec, omods = null, name = o.vs || 'this scene';
+  if (o.vs) {
+    const path = resolve(o.vs);
+    if (existsSync(path)) {
+      if (all) wrong(`--vs ${o.vs}: for a world, another version is a branch or commit of it (--vs main)`);
+      ospec = specAt(path); omods = modulesOf(ospec); name = o.vs;
+    } else {
+      if (!existsSync(what) || !statSync(what).isDirectory()) wrong(`--vs ${o.vs}: no such file or folder (a ref is for a scene's folder in a world's repository)`);
+      if (!inGit(world)) wrong(`--vs ${o.vs}: no such file or folder, and ${world} is not a git repository to find it in as a branch or commit`);
+      try { ospec = readScene(what, { world, ref: o.vs }); } catch (e) {
+        if (!all || !/: there is no /.test(e.message)) wrong(`--vs ${e.message}`);
+        return { missing: `not in ${o.vs}` }; // a scene new on this branch
+      }
+      omods = modulesOf(ospec, o.vs);
+    }
+  }
+  return { spec: ospec, modules: omods, engine: o['vs-engine'], name: `${name}${o['vs-engine'] ? ` · engine ${o['vs-engine']}` : ''}` };
+}
+
+// ── rendering ──────────────────────────────────────────────────────────
+const asked = { device: o.device, state: state || {}, set: set || [], views: views || [], bare: o.bare, debug: o.debug, chromium: o.chromium };
+const several = at.length > 1 || !!views?.length;
+// a frame's file: --out, with the scene's folder (a world's scenes), the variant (--states) and the moment (several)
+const nameOf = (f, ext, scene) => o.out.replace(/\.png$/i, `${scene ? `-${scene}` : ''}${f.variant ? `-s${f.variant}` : ''}${several ? `-${f.at}s${f.view ? `-v${f.view}` : ''}` : ''}`) + ext;
+// the scene rendered — once, or once for each of --states (each frame knows which: `variant`, from 1)
+async function take(args) {
+  if (!states) return render(args);
+  const out = [];
+  for (const [i, s] of states.entries()) for (const f of await render({ ...args, state: { ...args.state, ...s } })) out.push({ ...f, variant: i + 1 });
+  return out;
+}
+const say = v => JSON.stringify(v).replace(/"/g, '').replace(/[{}]/g, '').replace(/,/g, ', ');
+const sheetOf = scene => (scene ? o.sheet.replace(/\.png$/i, `-${scene}.png`) : o.sheet);
+// what is where (--json): an element, a value of the state a line each
+const lookJSON = look => `{\n${Object.entries(look).map(([k, v]) => (plain(v) && (k === 'elements' || k === 'state')
+  ? ` "${k}": {\n${Object.entries(v).map(([id, x]) => `  ${JSON.stringify(id)}: ${JSON.stringify(x)}`).join(',\n')}\n }`
+  : ` "${k}": ${JSON.stringify(v)}`)).join(',\n')}\n}\n`;
+const label = f => `${f.variant ? `${say(states[f.variant - 1])} · ` : ''}${f.at} s${f.view ? ` · view ${f.view}` : ''}`;
 let failed = false;
-for (const f of frames) {
-  const out = frames.length > 1 ? o.out.replace(/(\.png)?$/, `-${f.at}s.png`) : o.out;
-  writeFileSync(out, f.png);
-  console.log(out);
-  for (const e of f.errors) { console.error(`${f.at}s: ${e}`); failed = true; }
+// each error once, with the moment it was first seen (and the scene, of a world's) — and each warning
+// (what the scene does wrong without failing: a name it does not know, a mistyped key), which leaves
+// the exit code as it is
+const seen = new Set();
+const once = (who, e, line) => { if (!seen.has(who + e)) { seen.add(who + e); console.error(line); } };
+const said = (f, who = '') => {
+  for (const e of f.errors) { failed = true; once(who, e, `${f.at}s${who}: ${e}`); }
+  for (const w of f.warnings || []) once(who, w, `${f.at}s${who}: warning: ${w}`);
+};
+const tells = (frames, who = '') => { for (const t of frames.at(-1)?.tells || []) console.log(`${who}told at ${t.at.toFixed(2)}s: ${t.text}${t.about ? ` (${t.about})` : ''}`); };
+const started = Date.now();
+const took = () => `${((Date.now() - started) / 1000).toFixed(1)} s`;
+
+// one scene; `scene` — its folder's name, when it is one of a world's
+async function one(what, spec, scene) {
+  const who = scene ? ` ${scene}` : '';
+  if (o.video) {
+    const v = video(o.video, fps, { chromium: o.chromium });
+    let last = null, n = 0;
+    // (what went wrong first is said: a render that failed, else ffmpeg)
+    let failure = null;
+    try {
+      await render({ spec, modules: modulesOf(spec), at, ...asked, look: o.json, jpeg: true, each: async f => {
+        await v.write(f.jpg); n++; last = f;
+        if (o.json) writeFileSync(nameOf(f, '.json'), lookJSON(f.look));
+      } });
+    } catch (e) { failure = e; }
+    try { await v.done(); } catch (e) { failure ??= e; }
+    if (failure) throw failure;
+    if (last) said(last);
+    console.log(`${o.video} — ${n} frames, ${at[0]}…${at.at(-1)} s at ${fps} a second (${took()}, by ${basename(v.ffmpeg)})`);
+    if (last) tells([last]);
+    return null;
+  }
+  const look = o.json, other = otherOf(what, spec), frames = await take({ spec, modules: modulesOf(spec), at, ...asked, look, crop: o.crop });
+  let most = null;
+  if (other?.missing) {
+    console.log(`${scene}: ${other.missing} — this branch's only`);
+    frames.forEach(f => said(f, who));
+  } else if (other) {
+    const theirs = await take({ spec: other.spec, modules: other.modules ?? modulesOf(other.spec), engine: other.engine, at, ...asked, crop: o.crop });
+    const done = await compare(frames.map((f, i) => ({ a: f.png, b: theirs[i].png, label: `${scene ? `${scene} · ` : ''}${label(f)}` })), { names: [scene || basename(what), other.name], chromium: o.chromium });
+    frames.forEach((f, i) => {
+      const out = nameOf(f, '.png', scene);
+      writeFileSync(out, done[i].png);
+      console.log(`${out} — differs: ${(done[i].share * 100).toFixed(2)}% of pixels, by up to ${done[i].max}`);
+      said(f, who); said(theirs[i], `${who} (${other.name})`);
+    });
+    most = Math.max(...done.map(d => d.share));
+  } else if (o.sheet) {
+    writeFileSync(sheetOf(scene), await sheet(frames.map(f => ({ png: f.png, label: `${scene ? `${scene} · ` : ''}${label(f)}` })), { chromium: o.chromium,
+      // variants (--states) a row each, their moments across
+      cols: states && frames.length / states.length <= 8 ? frames.length / states.length : undefined }));
+    console.log(`${sheetOf(scene)} — ${frames.length} frames (${took()})`);
+    frames.forEach(f => said(f, who));
+  } else {
+    for (const f of frames) { writeFileSync(nameOf(f, '.png', scene), f.png); console.log(nameOf(f, '.png', scene)); said(f, who); }
+  }
+  if (look) for (const f of frames) { writeFileSync(nameOf(f, '.json', scene), lookJSON(f.look)); console.log(nameOf(f, '.json', scene)); }
+  tells(frames, scene ? `${scene}: ` : '');
+  return most;
+}
+
+try {
+  if (!all) await one(what, specAt(what));
+  else {
+    // every scene of the world, one after another; with --vs, which differ most, at the end
+    const most = [];
+    for (const path of all.list) {
+      const scene = basename(path);
+      try { most.push([scene, await one(path, readScene(path), scene)]); } catch (e) { failed = true; console.error(`${scene}: ${e.message}`); }
+    }
+    if (o.vs || o['vs-engine']) {
+      console.log(`\n${all.list.length} scenes (${took()}), by how much they differ:`);
+      for (const [scene, share] of most.filter(([, s]) => s != null).sort((a, b) => b[1] - a[1])) console.log(`  ${(share * 100).toFixed(2).padStart(6)}%  ${scene}`);
+    }
+  }
+} catch (e) {
+  console.error(`moood-render: ${e.message}`);
+  process.exit(e.message.startsWith('crop:') ? 2 : 1);
 }
-for (const t of frames.at(-1)?.tells || []) console.log(`told at ${t.at.toFixed(2)}s: ${t.text}${t.about ? ` (${t.about})` : ''}`);
 process.exit(failed ? 1 : 0);

package/compose.js

@@ -0,0 +1,71 @@
+// Frames laid out by the browser's canvas (nothing else to install): a sheet of them, labelled; and
+// two renders of the same moment side by side with where they differ.
+//   sheet([{png, label}], {cols, chromium}) → a PNG: the frames in rows (`cols` a row, else as many as
+//     suits their number), each with its label above it;
+//   compare([{a, b, label}], {names: [A's, B's], tolerance, chromium}) → [{png, share, max}] — each
+//     pair as A | B | the difference (A dimmed, in red where a pixel's channel differs by more than
+//     `tolerance` of 255, brighter the more), how much of the frame differs (0…1) and by how much at most.
+import { browser } from './index.js';
+
+async function inPage(chromium, fn, arg) {
+  const b = await browser(chromium);
+  try { return await (await b.newPage()).evaluate(fn, arg); } finally { await b.close(); }
+}
+const url = png => `data:image/png;base64,${png.toString('base64')}`;
+const buffer = data => Buffer.from(data.slice(data.indexOf(',') + 1), 'base64');
+
+export async function sheet(frames, { cols: asked, chromium } = {}) {
+  const data = await inPage(chromium, async ({ list, asked }) => {
+    const ims = await Promise.all(list.map(async f => { const i = new Image(); i.src = f.src; await i.decode(); return { i, label: f.label }; }));
+    const n = ims.length, cols = asked || (n <= 4 ? n : n <= 9 ? 3 : n <= 16 ? 4 : 5), rows = Math.ceil(n / cols), LABEL = 26, GAP = 6;
+    const w = Math.min(Math.max(...ims.map(f => f.i.width)), Math.floor(2400 / cols)), k = w / Math.max(...ims.map(f => f.i.width));
+    const h = Math.ceil(Math.max(...ims.map(f => f.i.height)) * k);
+    const c = document.createElement('canvas'), g = c.getContext('2d');
+    c.width = cols * w + (cols + 1) * GAP; c.height = rows * (h + LABEL) + (rows + 1) * GAP;
+    g.fillStyle = '#111'; g.fillRect(0, 0, c.width, c.height);
+    g.font = '15px sans-serif'; g.textBaseline = 'middle';
+    ims.forEach(({ i, label }, j) => {
+      const x = GAP + (j % cols) * (w + GAP), y = GAP + Math.floor(j / cols) * (h + LABEL + GAP);
+      g.fillStyle = '#ddd'; g.fillText(label, x + 4, y + LABEL / 2);
+      g.drawImage(i, x, y + LABEL, i.width * k, i.height * k);
+    });
+    return c.toDataURL('image/png');
+  }, { list: frames.map(f => ({ src: url(f.png), label: f.label })), asked });
+  return buffer(data);
+}
+
+export async function compare(pairs, { names = ['A', 'B'], tolerance = 8, chromium } = {}) {
+  const out = await inPage(chromium, async ({ list, names, tol }) => {
+    const load = async src => { const i = new Image(); i.src = src; await i.decode(); return i; };
+    const pixels = (i, w, h) => { const c = document.createElement('canvas'); c.width = w; c.height = h; const g = c.getContext('2d'); g.drawImage(i, 0, 0); return g.getImageData(0, 0, w, h); };
+    const res = [];
+    for (const { a, b, label } of list) {
+      const [ia, ib] = await Promise.all([load(a), load(b)]), w = Math.max(ia.width, ib.width), h = Math.max(ia.height, ib.height);
+      const A = pixels(ia, w, h), B = pixels(ib, w, h), D = new ImageData(w, h);
+      let n = 0, max = 0;
+      for (let p = 0; p < A.data.length; p += 4) {
+        const d = Math.max(Math.abs(A.data[p] - B.data[p]), Math.abs(A.data[p + 1] - B.data[p + 1]), Math.abs(A.data[p + 2] - B.data[p + 2]));
+        const grey = (A.data[p] + A.data[p + 1] + A.data[p + 2]) / 3 * 0.3;
+        max = Math.max(max, d);
+        if (d > tol) { n++; D.data[p] = Math.min(255, 120 + d * 2); D.data[p + 1] = grey * 0.5; D.data[p + 2] = grey * 0.5; }
+        else { D.data[p] = D.data[p + 1] = D.data[p + 2] = grey; }
+        D.data[p + 3] = 255;
+      }
+      const share = n / (w * h), pw = Math.min(w, 800), k = pw / w, ph = Math.round(h * k), LABEL = 28, GAP = 6;
+      const c = document.createElement('canvas'), g = c.getContext('2d'), dc = document.createElement('canvas');
+      dc.width = w; dc.height = h; dc.getContext('2d').putImageData(D, 0, 0);
+      c.width = 3 * pw + 4 * GAP; c.height = ph + LABEL + 2 * GAP;
+      g.fillStyle = '#111'; g.fillRect(0, 0, c.width, c.height);
+      g.font = '15px sans-serif'; g.textBaseline = 'middle'; g.fillStyle = '#ddd';
+      const said = `${label} · differs: ${(share * 100).toFixed(2)}% of pixels, by up to ${max}`;
+      [[ia, names[0]], [ib, names[1]], [dc, said]].forEach(([im, text], j) => {
+        const x = GAP + j * (pw + GAP);
+        g.fillText(text, x + 4, GAP + LABEL / 2, pw - 8);
+        g.drawImage(im, x, GAP + LABEL, im.width * k, im.height * k);
+      });
+      res.push({ data: c.toDataURL('image/png'), share, max });
+    }
+    return res;
+  }, { list: pairs.map(p => ({ a: url(p.a), b: url(p.b), label: p.label })), names, tol: tolerance });
+  return out.map(r => ({ png: buffer(r.data), share: r.share, max: r.max }));
+}

package/engine/directions.js

@@ -21,9 +21,9 @@ const MooodDirections = (() => {
       back.type = go.type = 'button';
       back.textContent = '◀'; go.textContent = '▶';
       back.title = 'обратно'; go.title = 'превратить';
-      slider.oninput = () => MooodState.set(d.key, Number(slider.value));
-      go.onclick = () => MooodState.set(d.key, 1, SECONDS * (1 - (MooodState.get(d.key) || 0)));
-      back.onclick = () => MooodState.set(d.key, 0, SECONDS * (MooodState.get(d.key) || 0));
+      slider.oninput = () => MooodState.set(d.key, Number(slider.value), 0, undefined, { who: 'a direction' });
+      go.onclick = () => MooodState.set(d.key, 1, SECONDS * (1 - (MooodState.get(d.key) || 0)), undefined, { who: 'a direction' });
+      back.onclick = () => MooodState.set(d.key, 0, SECONDS * (MooodState.get(d.key) || 0), undefined, { who: 'a direction' });
       row.append(name, back, slider, go);
       panel.append(row);
       return { d, row, slider, back, go };