@moood/render 0.1.3 → 0.1.5

package/engine/scenestate.js

@@ -10,8 +10,13 @@
 // default — it starts and stops gently; linear, in, out, back, spring, anticipate…). A value set
 // is heard once, where it is set to (on('change')); a value moving there is heard each frame as it
 // moves (on('move')). What a value was a moment ago stays known for a while (was): what lags
-// behind — a coat's tail, hair, a head that follows — reads it. A script may tell that something
-// happened (scene.tell): the game decides what it means.
+// behind — a coat's tail, hair, a head that follows — reads it. A cut (scene.cut) is a new shot:
+// its values set at once and what came before it forgotten — was() reaches back no further, and
+// what has inertia (the camera, a module's springs: e.cut) starts afresh. The scene's start is a
+// cut too. A script may tell that something happened (scene.tell): the game decides what it means.
+// A scene may describe its values (spec.states: each key's range or values, whether it moves
+// smoothly, what it means) — for the game and the agents that turn them; then a
+// key it doesn't describe, or a value outside what it says, is said (window.__mooodWarnings).
 const MooodState = (() => {
   let stage = null, tell = null, save = null, t0 = performance.now();
   let values = {}, cur = {}, tweens = new Map(), listeners = [], timers = [], raf = 0, pending = {}, flushTimer = 0;
@@ -21,7 +26,75 @@ const MooodState = (() => {
   // the engine's own values (engine.js, gl.js: the camera a film moves, its fade): 0 until set
   const ENGINE = { camera_x: 0, camera_h: 0, camera_z: 0, camera_look: 0, fade: 0 };
   let past = new Map();
+  // the last cut (performance.now()): the scene's start or scene.cut; shots — how many scene.cuts
+  // there have been (the scene's start is not one: the viewer keeps where they looked from)
+  let cutAt = t0, shots = 0;
   const report = (who, err) => (window.__mooodErrors = window.__mooodErrors || []).push(`script ${who}: ${err && err.message || err}`);
+  // the scene's description of its values (spec.states), when it has one; what is wrong with what is
+  // set, said once each
+  let states = null;
+  const said = new Set();
+  const say = msg => { if (said.has(msg)) return; said.add(msg); (window.__mooodWarnings = window.__mooodWarnings || []).push(msg); };
+  // the keys the engine itself reads for the scene, each with what it takes (kit.js: keys — the
+  // camera's and fade, an insert's, a place's, a redraw's, the light's looks, a light's on): every
+  // scene's, described or not
+  let own = MooodKit.keys(null);
+  const TYPES = ['number', 'boolean', 'string'];
+  // what is wrong with value v for the description d of key k, or null
+  function wrong(k, d, v) {
+    if (v === null) return null;
+    const show = JSON.stringify(v);
+    if (Array.isArray(d.values)) return d.values.some(x => JSON.stringify(x) === show) ? null : `state "${k}": ${show} is not one of ${d.values.map(x => JSON.stringify(x)).join(', ')}`;
+    const type = Array.isArray(d.range) ? 'number' : d.type;
+    if (type && typeof v !== type) return `state "${k}": ${show} — a ${type} expected`;
+    if (Array.isArray(d.range) && (v < d.range[0] || v > d.range[1])) return `state "${k}": ${show} is outside its range [${d.range.join(', ')}]`;
+    return null;
+  }
+  // spec.states as it is given: { key: {range: [min, max] | values: [...] | type, smooth, means} } (where
+  // a value starts is the scene's `state`)
+  function describe(spec) {
+    const st = spec?.states;
+    if (st == null) return null;
+    if (typeof st !== 'object' || Array.isArray(st)) { say('states: { key: {range | values | type, smooth, means} } expected'); return null; }
+    for (const [k, d] of Object.entries(st)) {
+      if (!d || typeof d !== 'object' || Array.isArray(d)) { say(`states.${k}: an object expected`); continue; }
+      if (d.range !== undefined && !(Array.isArray(d.range) && d.range.length === 2 && d.range.every(Number.isFinite) && d.range[0] < d.range[1])) say(`states.${k}: "range" is [min, max]`);
+      if (d.values !== undefined && !(Array.isArray(d.values) && d.values.length)) say(`states.${k}: "values" is the list of what it can be`);
+      if (d.type !== undefined && !TYPES.includes(d.type)) say(`states.${k}: "type" is one of ${TYPES.join(', ')}`);
+      if ('start' in d) say(`states.${k}: where a value starts is the scene's "state" ("state": {"${k}": …}), not its description`);
+    }
+    states = st;
+    for (const [k, v] of Object.entries(spec.state && typeof spec.state === 'object' ? spec.state : {})) check(k, v);
+    return st;
+  }
+  // a value set: said if the scene's states don't have its key, or it is outside what they say (an
+  // engine's key: what the engine takes, unless the states describe it)
+  function check(key, value) {
+    if (!states) return;
+    const d = states[key] && typeof states[key] === 'object' ? states[key] : own.get(key);
+    if (!d) { say(`state "${key}": not one of the scene's states`); return; }
+    const w = wrong(key, d, value);
+    if (w) say(w);
+  }
+  // A scene without states (above): the keys it knows are its starting state's (declared), the
+  // engine's (own), those its scripts use (set, play, get, on, scene.state.x) or a widget reads, and
+  // those its painting reads (the stage's: its elements' code, its modules — as they are painted). A
+  // key set from outside it (who: the game, a widget, a direction, a render's --set) that none of
+  // them knows is kept (strangers); unknown() says those that nothing has used by the time it is
+  // asked — a render asks once its frames are taken, so a key read late, or only by what is painted
+  // later, is not mistaken for a mistyped one. (A scene with states says a key they lack as it is
+  // set: check.)
+  let declared = new Set(), used = new Set(), strangers = new Map();
+  function outside(key, who = 'a widget', start = true) {
+    key = String(key);
+    if (states || (start && declared.has(key)) || own.has(key) || strangers.has(key)) return;
+    strangers.set(key, who);
+  }
+  function unknown() {
+    const read = stage?.read?.() || new Set();
+    return [...strangers].filter(([k]) => !used.has(k) && !read.has(k))
+      .map(([k, who]) => `${who} sets "${k}": not in the scene's "state", and nothing in it read it — a mistyped key?`);
+  }
 
   // where a move is at `now` (a move along a path: where its path is, `way` 0…1 of it)
   const along = (m, now) => {
@@ -30,9 +103,10 @@ const MooodState = (() => {
     const u = m.curve((now - m.start) / (m.end - m.start));
     return m.way ? m.way(u) : m.from + (m.to - m.from) * u;
   };
-  // what a number was `ago` seconds ago (as it is now if it hasn't moved since)
+  // what a number was `ago` seconds ago (as it is now if it hasn't moved since) — no further back
+  // than the last cut: before it, it was as the cut found it
   function was(key, ago = 0) {
-    const now = performance.now(), at = now - ago * 1000, moves = past.get(key);
+    const now = performance.now(), at = Math.max(cutAt, now - ago * 1000), moves = past.get(key);
     if (!moves || !moves.length) return cur[key];
     for (let i = moves.length - 1; i >= 0; i--) if (moves[i].start <= at) return along(moves[i], at);
     return moves[0].from;
@@ -44,7 +118,7 @@ const MooodState = (() => {
     past.set(key, moves);
   }
 
-  function publish() { cur = { ...values }; for (const [k, tw] of tweens) cur[k] = along(tw, performance.now()); stage?.setState(cur, was, sample); }
+  function publish() { cur = { ...values }; for (const [k, tw] of tweens) cur[k] = along(tw, performance.now()); stage?.setState(cur, was, sample, cutAt, shots); }
   // the moving values, where they are now (the stage asks as it paints a frame): each heard moving
   // from where it was last seen
   function sample() {
@@ -76,6 +150,7 @@ const MooodState = (() => {
   // null removes it. kept: false — the game set it and keeps it itself
   function set(key, value, over = 0, ease = 'smooth', { kept = true } = {}) {
     key = String(key);
+    check(key, value === undefined ? null : value);
     const old = key in cur ? cur[key] : key in values ? values[key] : ENGINE[key];
     if (value === undefined) value = null;
     const now = performance.now();
@@ -93,12 +168,21 @@ const MooodState = (() => {
     if (kept) keep({ [key]: value });
     if (JSON.stringify(old) !== JSON.stringify(value)) emit('change', key, value, old, key);
   }
+  // a cut: a new shot — the values in `changes` set at once (the camera elsewhere, people already
+  // where they got to), the moves of what it names stopped, and the history before it forgotten
+  function cut(changes = {}) {
+    if (!changes || typeof changes !== 'object' || Array.isArray(changes)) throw new Error('cut: an object of values expected');
+    cutAt = performance.now(); shots++;
+    for (const [k, v] of Object.entries(changes)) set(k, v);
+    publish();
+  }
   // several numbers moved together through points, as one movement: keys ['cart_a', 'cart_d'], points
   // [[a, d], …] (from where they are now); over `over` seconds or at `speed` (their units a second,
   // along the way), along `ease` — so it slows nowhere but where the curve says (a path cut into
   // set()s stops at every corner). Returns its seconds.
   function path(keys, points, { over = 0, speed = 0, ease = 'smooth' } = {}) {
     keys = keys.map(String);
+    for (const [i, k] of keys.entries()) for (const p of points) check(k, Number(p[i]) || 0);
     const from = keys.map(k => Number(k in cur ? cur[k] : k in values ? values[k] : ENGINE[k]) || 0);
     const pts = [from, ...points.map(p => keys.map((_, i) => Number(p[i]) || 0))], to = pts[pts.length - 1];
     const ends = [0];
@@ -134,34 +218,44 @@ const MooodState = (() => {
   // the API a script gets: for the scene (id null) or for one element
   function api(who, id, element, shared) {
     const own = fn => (...a) => { try { fn(...a); } catch (err) { report(who, err); } };
+    const use = (...keys) => { for (const k of keys.flat()) used.add(String(k)); };
     const after = (seconds, fn) => { const h = setTimeout(own(fn), Math.max(0, seconds) * 1000); timers.push(() => clearTimeout(h)); };
     return {
       id, element,
       anim: MooodKit.anim, kit: shared.kit, lib: shared.lib,
-      get state() { return cur; },
+      // the ground's height there (metres; spec.relief — 0 without one)
+      ground: (across, distance) => (shared.ground ? shared.ground(across, distance) : 0),
+      // (scene.state.x: x is a key the scene uses)
+      get state() { return new Proxy(cur, { get: (o, k) => { if (typeof k === 'string') used.add(k); return o[k]; } }); },
       get time() { return (performance.now() - t0) / 1000; },   // seconds since the scene opened
-      get: key => cur[key],
-      set: (key, value, over, ease) => set(key, value, over, ease),
-      turn: (key, degrees, over, ease) => turn(key, degrees, over, ease),
-      path: (keys, points, opts) => path(keys, points, opts),
-      was: (key, ago) => was(key, ago),
+      get: key => { use(key); return cur[key]; },
+      set: (key, value, over, ease) => { use(key); set(key, value, over, ease); },
+      cut: changes => { use(Object.keys(changes || {})); cut(changes); },
+      turn: (key, degrees, over, ease) => { use(key); turn(key, degrees, over, ease); },
+      path: (keys, points, opts) => { use(keys); return path(keys, points, opts); },
+      was: (key, ago) => { use(key); return was(key, ago); },
       // a platformer's hero now: { across, elevation (metres), ground } — or null
       hero: () => stage?.hero?.() ?? null,
       // something happened in the scene (about one of its elements, if `about`): the game hears it
       tell: (text, about = null) => tell?.(String(text), about),
+      // something wrong but not an error — a name it does not know — said once, in the scene's errors
+      warn: text => say(`${who}: ${text}`),
       every(seconds, fn) { const h = setInterval(own(fn), Math.max(0.05, seconds) * 1000); timers.push(() => clearInterval(h)); },
       after,
       // a timeline: rows [at, key, value, over?, ease?] — or [at, fn] — where `at` is the second it
       // starts (from now), or '+s': s seconds after the row before it ends ('+0': as it ends); a
       // key in degrees turned the short way: [at, key, {turn: degrees}, over?, ease?]; numbers
-      // moved together through points (path, above): [at, [keys], {path: points}, over, ease?].
+      // moved together through points (path, above): [at, [keys], {path: points}, over, ease?];
+      // a cut (above): [at, 'cut', {values}].
       // Returns when the last row ends (seconds from now).
       play(rows) {
         let end = 0, last = 0;
         for (const row of rows) {
           const [at, a, b, over = 0, ease] = row;
           const start = typeof at === 'string' && at.startsWith('+') ? last + Number(at.slice(1)) : Number(at);
+          if (typeof a !== 'function') use(a === 'cut' ? Object.keys(b || {}) : a);
           if (typeof a === 'function') after(start, a);
+          else if (a === 'cut') after(start, () => cut(b));
           else if (Array.isArray(a) && b && typeof b === 'object' && Array.isArray(b.path)) after(start, () => path(a, b.path, { over, ease }));
           else if (b && typeof b === 'object' && 'turn' in b) after(start, () => turn(a, b.turn, over, ease));
           else after(start, () => set(a, b, over, ease));
@@ -175,6 +269,7 @@ const MooodState = (() => {
       // `over`, path), till it stops; on('load', fn(state))
       on(ev, a, b) {
         const fn = typeof a === 'function' ? a : b, key = typeof a === 'function' ? null : String(a);
+        if (key != null) use(key);
         listeners.push({ ev, key, fn, who });
       },
     };
@@ -191,9 +286,13 @@ const MooodState = (() => {
     stage = opts.stage || stage;
     tell = opts.tell || null;
     save = opts.save || null;
+    own = MooodKit.keys(spec); said.clear();
+    states = describe(spec);
+    for (const [k, v] of Object.entries(state)) check(k, v);
     values = { ...(spec?.state && typeof spec.state === 'object' ? spec.state : {}), ...state };
+    declared = new Set(Object.keys(values)); used = new Set(); strangers = new Map();
     past = new Map();
-    t0 = performance.now();
+    t0 = cutAt = performance.now();
     publish();
     emit('load', null, cur);
     const mine = ++run;
@@ -216,9 +315,22 @@ const MooodState = (() => {
     cancelAnimationFrame(raf); raf = 0;
   }
 
+  // set from outside the scene (above) — by `who` (default: a widget, which has MooodState as it is): a
+  // key it does not know is said
   return {
-    start, stop, set, turn, path, was,
-    get: key => cur[key],
+    start, stop, was,
+    set: (key, value, over, ease, opts = {}) => { outside(key, opts.who); set(key, value, over, ease, opts); },
+    cut: (changes, { who } = {}) => { for (const k of Object.keys(changes || {})) outside(k, who); cut(changes); },
+    turn: (key, degrees, over, ease) => { outside(key); turn(key, degrees, over, ease); },
+    path: (keys, points, opts) => { keys.forEach(k => outside(k)); return path(keys, points, opts); },
+    // keys put into the starting state from outside (a render's --state, over the spec's): kept as
+    // strangers (above) unless the scene knows them
+    check: (keys, who) => keys.forEach(k => outside(k, who, false)),
+    // the keys set from outside that nothing in the scene has used so far: what is said of each
+    unknown,
+    // the shown scene's description of its values (spec.states), or null
+    get states() { return states; },
+    get: key => { used.add(String(key)); return cur[key]; },
     all: () => cur,
     on: (ev, a, b) => api('widget', null, null, { kit: {}, lib: {} }).on(ev, a, b),
   };

package/engine/select.js

@@ -78,12 +78,13 @@ const MooodSelect = (() => {
       const sx = (clientX - r.left) / k - x, sy = (clientY - r.top) / k - y;
       // nearest first, in the renderer's order: it paints far to near, and at equal distance
       // layers in spec order, then objects — so the later one is on top
-      // (looking around, the elements standing about — no landscape layers, the sky behind them)
+      // (looking around, the elements standing about — no landscape layers, the sky behind them; what
+      // is near the eye, while it is seen: not faded out as it is passed, engine.js nearFade)
       const round = I.camSetup(spec).round;
       const things = [
         ...(round ? [] : spec.layers || []).map((L, i) => ({ path: `layers[${i}]`, L, i, at: { m: I.view(cam, dz.Z[i], W, H, dz.yh), D: dz.Z[i] - cam.z } })).filter(t => LAND.has(t.L.kind)),
-        ...(spec.objects || []).map((o, i) => ({ path: `objects[${i}]`, o: placed(dz, o), at: round && o.sky ? null : I.placeOf(o, cam, W, H, dz, round) })).filter(t => t.o.kind !== 'bird' && !t.o.plane),
-      ].map((t, k) => ({ ...t, k })).filter(t => t.at && t.at.D > 0.48 && (!only || only(t.path))).sort((a, b) => a.at.D - b.at.D || b.k - a.k);
+        ...(spec.objects || []).map((o, i) => ({ path: `objects[${i}]`, o: placed(dz, o), at: round && o.sky ? null : I.placeOf(o, cam, W, H, dz, round) })).filter(t => t.o.kind !== 'bird' && !t.o.plane && !t.o.insert && !t.o.unseen),
+      ].map((t, k) => ({ ...t, k })).filter(t => t.at && I.nearFade(t.at.D) >= 0.3 && (!only || only(t.path))).sort((a, b) => a.at.D - b.at.D || b.k - a.k);
       for (const t of things) {
         const m = heroed(t.at.m, t.o, cam, SW, H), s = m[0], px = (sx - m[4]) / s, py = (sy - m[5]) / m[3];
         if (t.o) {

package/engine/soma.md

@@ -0,0 +1,4 @@
+`soma.bin` — the SOMA body: NVIDIA Kimodo's skin of its 77-joint skeleton
+(https://github.com/nv-tlabs/kimodo, `kimodo/assets/skeletons/somaskel77/skin_standard.npz`; Copyright (c)
+2026 NVIDIA CORPORATION & AFFILIATES, Apache License 2.0). Made by `dev/mocap/soma_body.py`; `motion.js`
+draws the motions Kimodo made on it (the sandbox, the render).

package/engine/speech.js

@@ -7,8 +7,11 @@
 // voice being made — a "…" glimmers over them (thinking()).
 const MooodSpeech = (() => {
   let stage = null, canvas = null, layer = null, voiceless = null, raf = 0, queue = Promise.resolve();
-  const bubbles = new Map(); // element id → { el, text, until, pending }
+  // who says it: an element ('dv'), over its point (e.at) or a point it names ('dv#mouth') — one
+  // speaker, one bubble, wherever it is put
+  const bubbles = new Map(); // element id → { el, text, until, pending, at: where it is put ('dv#mouth') }
   const waiting = new Map(); // element id → how many things it is about to say
+  const speaker = ref => String(ref).split('#')[0];
   let current = null; // the voice being heard right now
   let said = 0;       // lines said before the player last spoke up: those not begun yet are dropped
   const NARRATOR = 'narrator';
@@ -47,7 +50,8 @@ const MooodSpeech = (() => {
   }
 
   // plays a line's voice, the bubble glimmering; resolves when it has been heard
-  async function hear(id, text, a, bubble) {
+  async function hear(ref, text, a, bubble) {
+    const id = speaker(ref);
     bubble?.el.classList.add('speaking'); told(id, text, true);
     current = a;
     a.volume = MooodVolume.get('voice');
@@ -65,8 +69,8 @@ const MooodSpeech = (() => {
     current.onended();
   }
 
-  function bubbleFor(id, text, voice, how, who) {
-    const old = bubbles.get(id);
+  function bubbleFor(ref, text, voice, how, who) {
+    const id = speaker(ref), old = bubbles.get(id);
     if (old) old.el.remove();
     const el = document.createElement('div');
     el.className = id === NARRATOR ? 'bubble narrator' : 'bubble';
@@ -76,11 +80,11 @@ const MooodSpeech = (() => {
     if (voice) {
       const again = document.createElement('button');
       again.type = 'button'; again.textContent = '▶'; again.title = 'ещё раз';
-      again.onclick = () => replay(id, text, voice, how, who);
+      again.onclick = () => replay(ref, text, voice, how, who);
       el.append(again);
     }
     layer.append(el);
-    const b = { el, text, until: Infinity, pending: false };
+    const b = { el, text, until: Infinity, pending: false, at: ref };
     bubbles.set(id, b);
     if (!raf) raf = requestAnimationFrame(place);
     return b;
@@ -90,8 +94,8 @@ const MooodSpeech = (() => {
     raf = 0;
     const now = performance.now();
     for (const [id, b] of bubbles) {
-      if (now > b.until) { b.el.remove(); bubbles.delete(id); if (waiting.get(id)) pend(id); continue; }
-      const at = id === NARRATOR ? [innerWidth / 2, innerHeight * 0.86] : stage.screenOf(id, 0.25, true);
+      if (now > b.until) { b.el.remove(); bubbles.delete(id); if (waiting.has(id)) pend(waiting.get(id).at); continue; }
+      const at = id === NARRATOR ? [innerWidth / 2, innerHeight * 0.86] : stage.screenOf(b.at, 0.25, true);
       b.el.style.visibility = at ? '' : 'hidden';
       if (at) b.el.style.transform = `translate(${Math.round(at[0])}px, ${Math.round(at[1])}px) translate(-50%, -100%)`;
       b.el.classList.toggle('fading', now > b.until - 1200);
@@ -100,23 +104,23 @@ const MooodSpeech = (() => {
   }
 
   // someone is about to speak (on) — or no longer (off): a glimmering "…" over them meanwhile
-  function pend(id) {
-    const b = bubbleFor(id, '…');
+  function pend(ref) {
+    const b = bubbleFor(ref, '…');
     b.pending = true;
     b.el.classList.add('pending');
   }
-  function thinking(id, on) {
-    const n = (waiting.get(id) || 0) + (on ? 1 : -1);
-    if (n > 0) waiting.set(id, n); else waiting.delete(id);
+  function thinking(ref, on) {
+    const id = speaker(ref), n = (waiting.get(id)?.n || 0) + (on ? 1 : -1);
+    if (n > 0) waiting.set(id, { n, at: ref }); else waiting.delete(id);
     const b = bubbles.get(id);
-    if (n > 0 && (!b || b.until !== Infinity)) pend(id);
+    if (n > 0 && (!b || b.until !== Infinity)) pend(ref);
     if (n <= 0 && b?.pending) { b.el.remove(); bubbles.delete(id); }
   }
 
-  // id: who says it (an element of the scene); voice/how: heard in that voice, that way, played as
-  // `who` ("Savely, the old keeper"). A line with
-  // a voice appears when it can be heard — its words and its voice together; its voice is made
-  // while the lines before it are said.
+  // id: who says it (an element of the scene; 'id#name' — over a point it names); voice/how: heard
+  // in that voice, that way, played as `who` ("Savely, the old keeper"). A line with a voice appears
+  // when it can be heard — its words and its voice together; its voice is made while the lines
+  // before it are said.
   function say(id, text, { voice, how, who } = {}) {
     text = String(text || '').trim();
     if (!text) return Promise.resolve();
@@ -140,7 +144,7 @@ const MooodSpeech = (() => {
   async function replay(id, text, voice, how, who) {
     const a = await voiced(text, voice, how, who);
     if (!a) return;
-    const b = bubbles.get(id);
+    const b = bubbles.get(speaker(id));
     if (b) b.until = Infinity;
     await hear(id, text, a, b);
     if (b) b.until = performance.now() + 2500;

package/index.js

@@ -1,70 +1,179 @@
 // A moood scene rendered here, with moood's own engine (engine/: the site's web/scene, its version in
 // engine/engine.json) in a Chromium already installed (playwright-core: nothing is downloaded) — no
 // network, no site. Time is a virtual clock, stepped from the scene's start: a frame at a moment is
-// the same every time, with the same state.
-//   render({spec, modules, device, at, state, bare, chromium, date}) → [{at, png, errors}]
+// the same every time, with the same state. Only the frames taken are drawn: up to each moment the
+// scene goes on unseen (its scripts, its state, the memory its modules keep — all as when it plays;
+// the engine's stage.draw(false)), so a late moment costs little more than an early one.
+//   render({spec, modules, device, at, state, set, views, bare, debug, look, crop, chromium, date, engine, each})
+//       → [{at, view, png, errors, warnings, tells, look}]
 //     spec — the scene (readScene(folder) from a world's repository, or any spec);
 //     modules — the modules it lists, themselves: {name: {code, data}} (readModules(world, spec));
 //     device — the frame: 16:9 (1600×900), 4:3, 21:9 (the same height), tile (640×360), big (1920×1080);
 //     at — the moments, seconds from the scene's start (default [0]): a frame each;
 //     state — values over the spec's starting state ({"dawn": 1, "girl": "gone"});
+//     set — values set as the scene goes, as a game sets them: [[second, key, value, over?, ease?], …]
+//       (a film's beat at its second: [[4, "beat", "cover"]]); a cut: [[4, "cut", {values}]] (scene.cut);
+//     views — other cameras on each moment: [{camera_target: "keeper", camera_shot: "close"}, {camera_x: 2},
+//       …] — a frame each (`view` 1, 2 …) of the very moment, the camera there at once; the film (its
+//       state, its clock, its own camera) goes on untouched;
 //     bare — without the title and the captions over it;
+//     debug — what is where, drawn over the frame (the scene's ?debug): ids, boxes, points, notes;
+//       true, or the ids of some elements ('keeper,boy'): only theirs;
+//     look — what is where, as numbers, with each frame (`look`): {t, camera, frame, elements, state}
+//       (the engine's stage.inspect(): each element's box in the frame's pixels, whether it is seen,
+//       its points, its notes, what its last painting cost);
+//     crop — an element's id: each frame only around it (its box, a margin round it);
+//     jpeg — frames as JPEG (`jpg` instead of `png`), quality 90: smaller, for a video;
 //     chromium — the browser's executable (else MOOOD_CHROMIUM, else Playwright's own);
-//     date — what the clock says at the start (default 2026-01-01T12:00:00Z).
-import { readFileSync } from 'node:fs';
+//     date — what the clock says at the start (default 2026-01-01T12:00:00Z);
+//     engine — another engine to render with: a folder like web/scene (another checkout's, an older
+//       package's engine/) — to compare engines;
+//     each — called with each frame as it is taken (async ok); then frames are not kept.
+//   Each frame: its errors, and what the scene's scripts told so far (scene.tell): [{at, text, about}].
+//   renderMotion({motion, at, views, kit, cell, chromium}) → {png, errors}
+//     a person's motion made by a model (moood's make_motion: list_motions(key, body=true) — its `body` is
+//     the motion, its `clip` the people module's entry) as frames on its body (engine/motion.html): a row
+//     per view (front, side, back, or {yaw, pitch, dist}), a column per moment (at, seconds; default eight
+//     across it); kit — the module's clip, its skeleton drawn over the body; cell — [w, h] of a frame.
+// browser(chromium) — the Chromium it renders in, launched (compose.js lays frames out in it too).
+import { existsSync, readFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 import { chromium as browserType } from 'playwright-core';
 
 export { readModules, readScene } from './scene.js';
 
-const PAGE = pathToFileURL(fileURLToPath(new URL('./engine/render.html', import.meta.url))).href;
-export const ENGINE = JSON.parse(readFileSync(new URL('./engine/engine.json', import.meta.url), 'utf8')).engine;
+const OWN = fileURLToPath(new URL('./engine/', import.meta.url));
+export const ENGINE = JSON.parse(readFileSync(join(OWN, 'engine.json'), 'utf8')).engine;
 export const DEVICES = { '16:9': [1600, 900], '4:3': [1200, 900], '21:9': [2100, 900], tile: [640, 360], big: [1920, 1080] };
 const STEP = 100;  // ms: timers fire as they come due, not all at the end of one jump
+const FRAME = 17;  // ms: one frame drawn
+// ms before a frame taken that the scene is painted as when drawn (unseen still): what keeps a memory
+// of its own and depends on how big it is painted (a module's detail drawn only up close) comes to
+// the frame exactly as when the film plays; before that, coarsely
+const SETTLE = 2000;
+const PATIENCE = 10 * 60_000; // ms: how long anything on the page is waited for
 
-export async function render({ spec, modules = {}, device = '16:9', at = [0], state = {}, bare = false, chromium, date } = {}) {
+export const browser = chromium => browserType.launch({
+  executablePath: chromium || process.env.MOOOD_CHROMIUM || undefined,
+  // WebGL on SwiftShader; 2D canvases on the CPU's Skia (SwiftShader takes minutes for many blended fills)
+  args: ['--use-angle=swiftshader', '--enable-unsafe-swiftshader', '--ignore-gpu-blocklist', '--disable-accelerated-2d-canvas',
+         '--allow-file-access-from-files'],
+});
+
+export async function render({ spec, modules = {}, device = '16:9', at = [0], state = {}, set = [], views = [], bare = false, debug = false,
+                               look = false, crop = null, jpeg = false, chromium, date, engine, each } = {}) {
   const size = DEVICES[device];
   if (!size) throw new Error(`device: one of ${Object.keys(DEVICES).join(', ')}`);
   if (!spec || typeof spec !== 'object') throw new Error('spec: a scene expected');
+  const dir = engine ? resolve(engine) : OWN;
+  if (!existsSync(join(dir, 'render.html'))) throw new Error(`engine: ${dir} is not an engine (no render.html in it: a folder like moood/web/scene)`);
   const shown = { ...spec, state: { ...(spec.state && typeof spec.state === 'object' ? spec.state : {}), ...state } };
-  const browser = await browserType.launch({
-    executablePath: chromium || process.env.MOOOD_CHROMIUM || undefined,
-    // WebGL on SwiftShader; 2D canvases on the CPU's Skia (SwiftShader takes minutes for many blended fills)
-    args: ['--use-angle=swiftshader', '--enable-unsafe-swiftshader', '--ignore-gpu-blocklist', '--disable-accelerated-2d-canvas',
-           '--allow-file-access-from-files'],
-  });
+  const b = await browser(chromium);
   try {
-    const page = await (await browser.newContext({ viewport: { width: size[0], height: size[1] } })).newPage();
+    const page = await (await b.newContext({ viewport: { width: size[0], height: size[1] } })).newPage();
+    // a machine under load draws slowly: what waits on the page waits long (Playwright's own: 30 s)
+    page.setDefaultTimeout(PATIENCE);
     const errors = [];
     page.on('pageerror', e => errors.push(String(e.message)));
-    // the clock stands still: only the frames' moments move it (install alone lets it run as time does)
+    // the real clock, before the page's own is stopped: what painting costs is timed by it
+    await page.addInitScript(() => { const now = performance.now.bind(performance); window.__mooodClock = () => now(); });
+    // the clock stands still: only the frames' moments move it (install alone lets it run as time
+    // does — from a minute before, so that however slowly a loaded machine gets to stopping it, it
+    // is stopped ahead of where it is, not behind: "Cannot fast-forward to the past")
     const start = new Date(date || '2026-01-01T12:00:00Z').getTime();
-    await page.clock.install({ time: start });
-    await page.clock.pauseAt(start + 1);
+    await page.clock.install({ time: start - 60_000 });
+    await page.clock.pauseAt(start);
     await page.addInitScript(([s, m]) => {
       window.__mooodSpec = s; window.__mooodModules = m;
       // chance, the same every time (the engine's grain, rain, sparks): the same moment, the same frame
       let seed = 1;
       Math.random = () => { 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; };
     }, [shown, modules]);
-    await page.goto(bare ? `${PAGE}?bare` : PAGE);
+    const query = [bare && 'bare', debug && (debug === true ? 'debug' : `debug=${encodeURIComponent(debug)}`)].filter(Boolean).join('&');
+    await page.goto(`${pathToFileURL(join(dir, 'render.html')).href}${query ? `?${query}` : ''}`);
     // what loads by itself (fonts, the scene's modules) has loaded before the clock moves at all
     await page.evaluate(() => document.fonts.ready);
     await page.waitForTimeout(1000);
-    const frames = [];
+    // values put in its starting state that nothing in the scene uses (a mistyped key): said
+    const extra = Object.keys(state).filter(k => !(spec.state && typeof spec.state === 'object' && k in spec.state));
+    if (extra.length) await page.evaluate(k => typeof MooodState !== 'undefined' && MooodState.check?.(k, '--state'), extra);
+    // an engine that can go on unseen (older ones draw every frame up to the moment)
+    const [unseeing, inspecting, stills] = await page.evaluate(() => ['draw', 'inspect', 'still'].map(f => typeof window.__mooodStage?.[f] === 'function'));
+    if ((look || crop) && !inspecting) throw new Error('this engine does not tell what is where (look, crop): it is older than them');
+    const frames = [], sets = [...set].map(([s, ...rest]) => [Number(s) * 1000, ...rest]).sort((a, b) => a[0] - b[0]);
     let now = 0;
+    // the values due by now, set (the clock stops at each one's second: it is set on time)
+    const due = async () => {
+      while (sets.length && sets[0][0] <= now) {
+        const [, key, value, over, ease] = sets.shift();
+        await page.evaluate(([k, v, o, e]) => (k === 'cut' ? MooodState.cut(v, { who: '--set' }) : MooodState.set(k, v, o, e, { who: '--set' })), [key, value, over, ease]);
+      }
+    };
+    const run = async ms => { await page.clock.runFor(ms); now += ms; await due(); };
+    // on to `ms`, the clock stopping at each value's second (what is due by then is set)
+    const until = async ms => { while (now < ms) await run(Math.min(STEP, ms - now, sets.length ? sets[0][0] - now : STEP)); };
+    const draw = how => unseeing && page.evaluate(v => window.__mooodStage.draw(v), how);
+    // (keys set from outside that nothing in the scene has read — a mistyped one — said with the last
+    // moment's frame: by then whatever reads a key late has read it)
+    const last = Math.max(...at.map(Number));
+    const shot = async (t, view) => {
+      const [said, warned, tells, seen] = await page.evaluate(([l, end]) => [window.__mooodErrors || [], [...(window.__mooodWarnings || []), ...(end ? MooodState.unknown?.() || [] : [])], window.__mooodTells || [],
+        l ? { ...window.__mooodStage.inspect(), state: MooodState.all() } : null], [look || !!crop, t === last]);
+      let clip;
+      if (crop) {
+        const el = seen.elements[crop];
+        if (!el) throw new Error(`crop: there is no element "${crop}" (its id): ${Object.keys(seen.elements).join(', ')}`);
+        if (el.seen && el.box) {
+          const [x, y, w, h] = el.box, m = 0.1 * Math.max(w, h), x0 = Math.max(0, x - m), y0 = Math.max(0, y - m);
+          clip = { x: x0, y: y0, width: Math.min(size[0], x + w + m) - x0, height: Math.min(size[1], y + h + m) - y0 };
+          if (!(clip.width >= 8 && clip.height >= 8)) clip = undefined;
+        }
+        if (!clip) errors.push(`crop: "${crop}" is not in the frame at ${t}s — the whole frame instead`);
+      }
+      const image = await page.screenshot(jpeg ? { type: 'jpeg', quality: 90, clip } : { type: 'png', clip });
+      const frame = { at: t, view, [jpeg ? 'jpg' : 'png']: image, errors: [...new Set([...errors, ...said])].slice(0, 100), warnings: [...new Set(warned)].slice(0, 100), tells, ...(look ? { look: seen } : {}) };
+      if (each) await each(frame); else frames.push(frame);
+    };
+    await due();
     for (const t of [...at].map(Number).sort((a, b) => a - b)) {
-      while (now < t * 1000) {
-        const step = Math.min(STEP, t * 1000 - now);
-        await page.clock.runFor(step);
-        now += step;
+      // unseen up to a frame before the moment (its last seconds painted as when drawn); that frame drawn
+      if (now < t * 1000 - FRAME) {
+        if (now < t * 1000 - SETTLE) { await draw(false); await until(t * 1000 - SETTLE); }
+        await draw('painted'); await until(t * 1000 - FRAME); await draw(true);
       }
+      // (the scene's first frame is drawn at the first display refresh: a moment before it is that frame)
+      await until(Math.max(t * 1000, FRAME));
       await page.clock.runFor(0);
-      const said = await page.evaluate(() => window.__mooodErrors || []);
-      frames.push({ at: t, png: await page.screenshot({ type: 'png' }), errors: [...new Set([...errors, ...said])].slice(0, 100) });
+      await shot(t);
+      if (!views.length) continue;
+      if (!stills) throw new Error('views: this engine cannot draw a moment from another camera (stage.still): it is older than that');
+      for (const [i, view] of views.entries()) {
+        await page.evaluate(v => window.__mooodStage.still(v), view);
+        await shot(t, i + 1);
+      }
     }
     return frames;
   } finally {
-    await browser.close();
+    await b.close();
+  }
+}
+
+export async function renderMotion({ motion, at, views = ['front', 'side'], kit = null, cell = [320, 400], chromium } = {}) {
+  if (!motion || !Array.isArray(motion.names)) throw new Error('motion: the body of a made motion expected (list_motions(key, body=true).body)');
+  const length = (motion.n - 1) / motion.fps;
+  const moments = at && at.length ? at.map(s => Math.min(Math.max(0, Number(s)), length)) : Array.from({ length: 8 }, (_, i) => +(length * i / 7).toFixed(2));
+  const b = await browser(chromium);
+  try {
+    const page = await (await b.newContext({ viewport: { width: cell[0] * moments.length, height: cell[1] * views.length } })).newPage();
+    const errors = [];
+    page.on('pageerror', e => errors.push(String(e.message)));
+    await page.addInitScript(([m, s]) => { window.__mooodMotion = m; window.__mooodMotionShow = s; }, [motion, { at: moments, views, kit, cell }]);
+    await page.goto(pathToFileURL(join(OWN, 'motion.html')).href);
+    await page.waitForFunction(() => document.title === 'ready', null, { timeout: 120_000 });
+    errors.push(...await page.evaluate(() => window.__mooodRenderErrors || []));
+    return { png: await page.screenshot({ type: 'png' }), errors: [...new Set(errors)] };
+  } finally {
+    await b.close();
   }
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@moood/render",
-  "version": "0.1.3",
-  "description": "A moood scene rendered locally — the site's own engine, in a browser already installed — at a moment, with a state: a PNG and the errors its code threw.",
+  "version": "0.1.5",
+  "description": "A moood scene rendered locally — the site's own engine, in a browser already installed — at any moment of it, with a state: frames, a sheet, a video, what is where as numbers, two versions compared; and the errors its code threw. And a person's motion made by a model, as frames on its body.",
   "license": "UNLICENSED",
   "type": "module",
   "main": "index.js",
@@ -12,6 +12,8 @@
     "index.js",
     "cli.js",
     "scene.js",
+    "compose.js",
+    "video.js",
     "engine/",
     "README.md"
   ],