@moood/render 0.1.4 → 0.1.5

package/engine/kit.js

@@ -9,7 +9,11 @@
 //     uses (spec.modules) and gets them as kit.<name>, as they are at the commit it is shown at.
 //   the scene's lib — code its own elements and scripts share: spec.lib, the body of
 //     function (anim, kit) that returns what it offers.
-// Painting code sees them as e.anim, e.kit, e.lib; scripts as scene.anim, scene.kit, scene.lib.
+//   the scene's land — spec.relief, the body of function (across, distance, anim, lib) that returns
+//     the ground's height there (metres; across to the right of the start's line of sight, distance
+//     ahead of it): what stands, walks, casts a shadow and looks on it, all on the one ground.
+// Painting code sees them as e.anim, e.kit, e.lib, e.ground; scripts as scene.anim, scene.kit,
+// scene.lib, scene.ground.
 // Where a spec's modules come from (the page says, with the spec):
 //   {world, refs} — the world's id and the modules by their content's sha ({name: {code, data}},
 //     as the scene's payload has them: the commit it shows); a module the refs don't name (a draft
@@ -120,9 +124,29 @@ const MooodKit = (() => {
       return built(refs);
     });
   }
-  // what a spec's code shares, once its modules are here: { kit, lib } — or a promise of it (they
-  // are still on their way); `source`: where its modules come from (above). The same modules are
-  // the same kit, and a lib on them is made once.
+  // the ground's height (metres) at (across, distance) as `relief` says — said once if it throws or
+  // returns no number (it is flat there then); null without a relief
+  const grounds = new Map();
+  function groundOf(relief, lib, key) {
+    if (!relief) return null;
+    if (!grounds.has(key)) {
+      let fn = null, said = false;
+      try { fn = new Function('across', 'distance', 'anim', 'lib', relief); } catch (err) { report('relief', err); }
+      const say = msg => { if (!said) { said = true; report('relief', msg); } };
+      grounds.set(key, fn && ((across, distance) => {
+        try {
+          const h = fn(across, distance, anim, lib);
+          if (Number.isFinite(h)) return h;
+          say(`at across ${across}, distance ${distance} it returned ${h}, not a number of metres`);
+        } catch (err) { say(err.message || err); }
+        return 0;
+      }));
+    }
+    return grounds.get(key);
+  }
+  // what a spec's code shares, once its modules are here: { kit, lib, ground } — or a promise of it
+  // (they are still on their way); `source`: where its modules come from (above). The same modules
+  // are the same kit, and a lib on them is made once.
   const kits = new Map();
   function shared(spec, source) {
     const done = ({ mods, key }) => {
@@ -133,10 +157,30 @@ const MooodKit = (() => {
         try { value = new Function('anim', 'kit', lib)(anim, kit) || {}; } catch (err) { report('lib', err); }
         libs.set(`${key}\n\n${lib}`, value);
       }
-      return { kit, lib: lib ? libs.get(`${key}\n\n${lib}`) : {} };
+      const made = lib ? libs.get(`${key}\n\n${lib}`) : {}, relief = typeof spec?.relief === 'string' && spec.relief.trim() ? spec.relief : null;
+      return { kit, lib: made, ground: groundOf(relief, made, `${key}\n\n${lib}\n\n${relief}`) };
     };
     const m = modulesOf(spec, source);
     return m instanceof Promise ? m.then(done) : done(m);
   }
-  return { anim, shared };
+  // The state keys the engine itself reads for a spec — whatever the scene's own code does: the film's
+  // camera and fade (every scene's), an insert's key, a place's, a redraw's, the light's looks, a
+  // light's `on` and place — each with what it takes, as spec.states describes a key ({range} or
+  // {type}; {} — anything). A key set from outside that neither these nor the scene knows, or one of
+  // these set to what the engine can't take, is said (scenestate.js).
+  const NUM = { type: 'number' }, UNIT = { range: [0, 1] };
+  const CAMERA = { camera_target: {}, camera_shot: {}, camera_frame: {}, camera_glide: NUM, camera_x: NUM, camera_z: NUM, camera_look: NUM, camera_h: NUM, fade: UNIT, fade_color: { type: 'string' } };
+  function keys(spec) {
+    const out = new Map(Object.entries(CAMERA)), obj = v => (v && typeof v === 'object' && !Array.isArray(v) ? v : {});
+    const add = (d, ...ks) => { for (const k of ks) if (typeof k === 'string') out.set(k, d); };
+    for (const o of Array.isArray(spec?.objects) ? spec.objects : []) {
+      if (!o || typeof o !== 'object') continue;
+      add(UNIT, o.insert); add(NUM, ...Object.values(obj(o.place)));
+      add({}, ...(Array.isArray(o.redraw) ? o.redraw : Object.keys(obj(o.redraw))));
+    }
+    for (const l of Array.isArray(spec?.lights) ? spec.lights : []) if (l && typeof l === 'object') { add(UNIT, l.on); add(NUM, ...Object.values(obj(l.place))); }
+    add(UNIT, ...Object.keys(obj(obj(spec?.light).looks)));
+    return out;
+  }
+  return { anim, shared, keys };
 })();

package/engine/render.html

@@ -12,9 +12,12 @@
        screenshots for the artist's look at its own work, the pictures of scenes and assistants (MCP).
        The service hands the
        spec in as window.__mooodSpec; errors the scene's code threw end up in
-       window.__mooodRenderErrors, what its scripts told (scene.tell) in window.__mooodTells ({at:
+       window.__mooodRenderErrors, what it does wrong without failing (a name it does not know, a
+       mistyped key) in window.__mooodRenderWarnings, what its scripts told (scene.tell) in window.__mooodTells ({at:
        seconds since it started, text, about}); the title turns "ready" when it is time to take the
-       picture. -->
+       picture. The stage is window.__mooodStage: a render steps the film unseen to the moments it
+       takes (draw(false)) and asks what is where (inspect()); it is checked as it is drawn (a painting cut
+       off by its box is said). ?debug — what is where, over the frame. -->
   <canvas id="scene"></canvas>
   <header class="titles"><h1 id="title"></h1><p id="caption"></p></header>
   <script src="kit.js"></script>
@@ -35,7 +38,7 @@
           document.getElementById('caption').textContent = spec.caption || '';
         }
         const modules = { texts: window.__mooodModules || {} }; // the modules the scene lists, given (kit.js)
-        const canvas = document.getElementById('scene'), stage = Moood.mount(canvas);
+        const canvas = document.getElementById('scene'), stage = window.__mooodStage = Moood.mount(canvas, { check: true });
         // the starting state, scripts running (their errors are reported) — before the scene is shown, so its first frame is as they set it
         const t0 = performance.now(), told = window.__mooodTells = [];
         MooodState.start(spec, {}, { stage, modules, tell: (text, about) => told.push({ at: (performance.now() - t0) / 1000, text, about }) });
@@ -47,6 +50,7 @@
       await new Promise(r => setTimeout(r, 1500));
       errors.push(...(window.__mooodErrors || []));
       window.__mooodRenderErrors = errors;
+      window.__mooodRenderWarnings = [...(window.__mooodWarnings || []), ...MooodState.unknown()];
       document.title = 'ready';
     })();
   </script>

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/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;