@moood/render 0.0.0-stage → 0.0.0

package/engine/viewer.js

@@ -0,0 +1,216 @@
+// Looking at a scene without leaving the page: a picture of a scene (or of one being drawn) clicked
+// grows, from where it is, into a view nearly the size of the window — the scene itself, alive
+// (its page in a frame: ?frame), its name, the scenes beside it to go through (← →), the way to
+// its own page; Esc, ✕ or a click beside it puts it back. The address shows the scene's while it is
+// open, so "back" closes it too.
+//   Links marked data-view (its value: the name shown) open in it; the set to go through is the
+//   marked links of the nearest [data-views] around (a strip), or of the whole page.
+//   The scene is laid out once, at the view's own size, and never resized: it grows by scale alone.
+// Where its picture is in the view is where engine.js puts it: the frame is the view's shape held
+// between 4:3 and 21:9 (bars beyond), the picture its 16:9 at the frame's full height, centred — so
+// the view starts scaled to the picture's height, cut to the part of it that shows, right over it.
+// Until the scene has drawn itself (the frame says "moood:shown"), only its picture is seen — the view
+// is cut to it, wherever it grows; then the cut opens to the whole view and the picture goes. So the
+// frame is never seen before there is something in it. Closing, the picture comes back over the scene
+// as the view shrinks — it lands as the picture it left.
+//   A link that knows the content its picture shows (data-key: the scene's content key) opens that
+// content in the front's frame.html — a file beside this one, under the same fingerprint: the browser
+// keeps it for good, and the content too (a key's content never changes); opened again, nothing is asked. If the scene is not there yet when the view has grown, a quiet
+// sign of waiting stands over its picture.
+//   Every scene shown gets a frame of its own, made after the address changed and gone once it is
+// closed: so no step of the browser's history holds a frame — going back never puts one back
+// (empty, or a scene from before) while the view is still there.
+(() => {
+  const MOVE = 320, ROUND = 6;  // ms, as in nav.css; a picture's corners
+  const STAGE = 16 / 9, NARROWEST = 4 / 3, WIDEST = 21 / 9;  // as engine.js frames a scene
+  const FRAME = new URL('../site/frame.html', document.currentScript.src);  // (beside this file)
+  let box = null, veil = null, bar = null, frame = null, still = null, wait = null, name = null, page = null, prev = null, next = null;
+  let items = [], at = 0, pushed = false, closing = 0, landing = 0, waiting = 0, ready = false;
+
+  function build() {
+    veil = document.createElement('div');
+    veil.className = 'viewer-veil';
+    veil.onclick = () => close();
+    box = document.createElement('div');
+    box.className = 'viewer';
+    bar = document.createElement('div');
+    bar.className = 'viewer-bar';
+    prev = button('←', 'предыдущая (←)', () => go(at - 1));
+    next = button('→', 'следующая (→)', () => go(at + 1));
+    name = document.createElement('span');
+    name.className = 'viewer-name';
+    page = document.createElement('a');
+    page.className = 'viewer-page';
+    page.textContent = 'открыть страницей';
+    bar.append(prev, name, next, page, button('✕', 'закрыть (Esc)', () => close()));
+    still = document.createElement('img');
+    still.className = 'viewer-still';
+    still.alt = '';
+    still.onerror = () => { still.hidden = true; };
+    wait = document.createElement('span');
+    wait.className = 'viewer-wait';
+    box.append(bar, still, wait);
+    document.body.append(veil, box);
+    addEventListener('keydown', e => {
+      if (!box.classList.contains('open')) return;
+      if (e.key === 'Escape') close();
+      else if (e.key === 'ArrowLeft') go(at - 1);
+      else if (e.key === 'ArrowRight') go(at + 1);
+    });
+    addEventListener('popstate', () => { if (box.classList.contains('open')) { pushed = false; close(); } });
+    addEventListener('resize', () => { if (box.classList.contains('open')) { size(); fitStill(); } });
+    // the scene in the frame has drawn itself: all of the view shows, its picture goes
+    addEventListener('message', e => {
+      if (!frame || e.source !== frame.contentWindow || e.data !== 'moood:shown') return;
+      ready = true;
+      clearTimeout(waiting);
+      box.classList.remove('waiting');
+      still.classList.add('gone');
+      box.classList.add('moving');
+      settle();
+    });
+  }
+
+  function button(text, title, onclick) {
+    const b = document.createElement('button');
+    b.type = 'button';
+    b.textContent = text;
+    b.title = title;
+    b.onclick = onclick;
+    return b;
+  }
+
+  // the view's own size: nearly the window
+  function size() {
+    const m = Math.min(48, innerWidth * 0.04);
+    Object.assign(box.style, { left: `${m}px`, top: `${m}px`, width: `${innerWidth - 2 * m}px`, height: `${innerHeight - 2 * m}px` });
+  }
+  // where the scene's picture is in the view (inside its border; it may run past the sides)
+  function middle() {
+    const top = bar.offsetHeight, w = box.clientWidth, h = box.clientHeight - top;
+    const a = Math.min(Math.max(w / h, NARROWEST), WIDEST), fh = Math.min(w, h * a) / a, pw = fh * STAGE;
+    return { left: (w - pw) / 2, top: top + (h - fh) / 2, width: pw, height: fh };
+  }
+  // the picture in its place, the sign of waiting in its middle
+  function fitStill() {
+    const m = middle();
+    Object.assign(still.style, { left: `${m.left}px`, top: `${m.top}px`, width: `${m.width}px`, height: `${m.height}px` });
+    Object.assign(wait.style, { left: `${m.left + m.width / 2}px`, top: `${m.top + m.height / 2}px` });
+  }
+  // the view laid over a picture (r, on the screen): scaled to its height, cut to its middle — or itself
+  function over(r) {
+    if (!r) {
+      box.style.transform = '';
+      box.style.clipPath = '';
+      return;
+    }
+    // (the transform counts from the box's outer edge, its border included)
+    const m = middle(), b = box.getBoundingClientRect(), s = r.height / m.height;
+    const left = box.clientLeft + m.left, top = box.clientTop + m.top;
+    const x = r.left + (r.width - m.width * s) / 2 - b.left - left * s, y = r.top - b.top - top * s;
+    box.style.transform = `translate(${x}px, ${y}px) scale(${s})`;
+    box.style.clipPath = picture(s);
+  }
+  // the view cut to the part of the scene's picture that shows (the picture may be wider than the
+  // view), its corners as a picture's at scale s (the clip counts from the box's outer edge too)
+  function picture(s) {
+    const m = middle(), top = box.clientTop + m.top;
+    const side = box.clientLeft + Math.max(0, m.left), bottom = box.offsetHeight - top - m.height;
+    return `inset(${top}px ${side}px ${bottom}px ${side}px round ${ROUND / s}px)`;
+  }
+  // the view in its place, unscaled: all of it once the scene has drawn itself (then no cut: its
+  // shadow shows), until then only its picture
+  function settle() {
+    box.style.transform = 'translate(0, 0) scale(1)';
+    box.style.clipPath = ready ? 'inset(0 0 0 0 round 12px)' : picture(1);
+    clearTimeout(landing);
+    if (ready) landing = setTimeout(() => { box.classList.remove('moving'); box.style.clipPath = ''; }, MOVE);
+  }
+
+  function show(i) {
+    at = i;
+    const it = items[at];
+    name.textContent = it.title || 'сцена';
+    page.href = it.href;
+    prev.disabled = at === 0;
+    next.disabled = at === items.length - 1;
+    ready = false;
+    // still not there once the view has grown: the sign of waiting
+    clearTimeout(waiting);
+    box.classList.remove('waiting');
+    waiting = setTimeout(() => { if (!ready) box.classList.add('waiting'); }, MOVE);
+    still.classList.remove('gone');
+    still.hidden = !it.picture;
+    still.src = it.picture || '';
+    // the scene in a frame of its own, in place of the one before
+    const f = document.createElement('iframe');
+    f.className = 'viewer-frame';
+    f.title = 'сцена';
+    const scene = it.href.match(/\/scenes\/(\d+)$/)?.[1];
+    f.src = scene && it.key ? `${FRAME.pathname}?${new URLSearchParams({ scene, key: it.key })}` : `${it.href}?frame`;
+    f.onload = () => f.contentWindow.addEventListener('keydown', e => { if (e.key === 'Escape') close(); });
+    if (frame) frame.replaceWith(f); else bar.after(f);
+    frame = f;
+  }
+
+  function go(i) {
+    if (i < 0 || i >= items.length || i === at) return;
+    show(i);
+    box.classList.add('moving');
+    settle();  // (cut to the next scene's picture until it has drawn itself)
+    history.replaceState(history.state, '', items[at].href);
+  }
+
+  async function open(list, i, el) {
+    if (!box) build();
+    clearTimeout(closing);
+    items = list;
+    // the address first: the step of history it leaves holds no frame
+    history.pushState({ viewer: true }, '', items[i].href);
+    pushed = true;
+    box.classList.remove('moving', 'closing');
+    show(i);
+    await still.decode().catch(() => {});  // (the picture ready to be seen from the first moment)
+    box.classList.add('open');
+    size();
+    fitStill();
+    over(el.getBoundingClientRect());
+    veil.classList.add('open');
+    box.getBoundingClientRect();  // laid out where it starts, before it moves
+    box.classList.add('moving');
+    settle();
+  }
+
+  function close() {
+    if (!box || !box.classList.contains('open')) return;
+    if (pushed) { pushed = false; history.back(); return; }  // (popstate closes it)
+    clearTimeout(landing);
+    // back into the picture of the scene it shows now, if that is on the page
+    const el = items[at]?.from, back = el?.isConnected ? el.getBoundingClientRect() : null;
+    if (back) {
+      box.style.clipPath = 'inset(0 0 0 0 round 12px)';
+      box.getBoundingClientRect();
+      box.classList.add('moving', 'closing');
+      over(back);
+    }
+    veil.classList.remove('open');
+    closing = setTimeout(() => { box.classList.remove('open', 'moving', 'closing'); over(null); frame?.remove(); frame = null; clearTimeout(waiting); box.classList.remove('waiting'); }, back ? MOVE : 0);
+  }
+
+  // links marked data-view open in the viewer; each grows from (and returns to) its scene's picture
+  document.addEventListener('click', e => {
+    const a = e.target.closest('a[data-view]');
+    if (!a || e.ctrlKey || e.metaKey || e.shiftKey || e.button !== 0) return;
+    e.preventDefault();
+    const group = a.closest('[data-views]') || document;
+    const items = new Map();  // (a scene's picture and its name lead to the same place)
+    for (const l of group.querySelectorAll('a[data-view]')) {
+      const href = l.getAttribute('href'), img = l.querySelector('img');
+      const known = items.get(href);
+      if (!known) items.set(href, { href, title: l.dataset.view, key: l.dataset.key || null, from: img || l, picture: img?.src || null });
+      else if (!known.picture && img) Object.assign(known, { from: img, picture: img.src });
+    }
+    const list = [...items.values()], i = list.findIndex(it => it.href === a.getAttribute('href'));
+    open(list, i, list[i].from);
+  });
+})();

package/engine/volume.js

@@ -0,0 +1,56 @@
+// How loud the site is for whoever listens here: one setting for all of it, every scene — the
+// music and the voices, each 0..1, kept in this browser (and followed by its other tabs). The 🔊 in
+// the crumbs (any [data-volume] button) opens two sliders; the players ask get() and listen on().
+const MooodVolume = (() => {
+  const DEFAULT = { music: 0.4, voice: 1 };
+  const NAMES = { music: 'музыка', voice: 'голоса' };
+  const key = k => `moood:volume:${k}`;
+  const listeners = new Set();
+
+  function get(k) {
+    try { const v = parseFloat(localStorage.getItem(key(k))); if (v >= 0 && v <= 1) return v; } catch {}
+    return DEFAULT[k];
+  }
+  function set(k, v) {
+    try { localStorage.setItem(key(k), String(v)); } catch {}
+    tell(k);
+  }
+  function tell(k) { for (const f of listeners) f(k, get(k)); }
+  // f(kind, value): kind 'music' or 'voice' changed
+  function on(f) { listeners.add(f); }
+  addEventListener('storage', e => { for (const k in DEFAULT) if (e.key === key(k)) tell(k); });
+
+  // ── the sliders ──────────────────────────────────────────────────────────
+  let panel = null;
+  function build() {
+    panel = document.createElement('div');
+    panel.id = 'volume';
+    panel.hidden = true;
+    for (const k in DEFAULT) {
+      const row = document.createElement('label');
+      const name = document.createElement('span');
+      name.textContent = NAMES[k];
+      const r = document.createElement('input');
+      r.type = 'range'; r.min = 0; r.max = 1; r.step = 0.01; r.value = get(k); r.dataset.kind = k;
+      r.oninput = () => set(k, Number(r.value));
+      row.append(name, r);
+      panel.append(row);
+    }
+    document.body.append(panel);
+  }
+  function open(button) {
+    if (!panel) build();
+    for (const r of panel.querySelectorAll('input')) r.value = get(r.dataset.kind);
+    const at = button.getBoundingClientRect();
+    panel.style.left = `${Math.max(8, Math.min(at.left, innerWidth - 228))}px`;
+    panel.style.top = `${at.bottom + 8}px`;
+    panel.hidden = false;
+  }
+  document.addEventListener('click', e => {
+    const b = e.target.closest?.('[data-volume]');
+    if (b) { panel && !panel.hidden ? (panel.hidden = true) : open(b); return; }
+    if (panel && !panel.hidden && !panel.contains(e.target)) panel.hidden = true;
+  });
+
+  return { get, set, on };
+})();

package/engine/widgets.js

@@ -0,0 +1,88 @@
+// Widgets — the scene's own bits of interface over the picture: a sign over someone's head,
+// a clock, a letter, a scoreboard, a panel with buttons (spec.widgets). Each is the artist's
+// HTML + CSS + JS, living right in the page: its markup and styles in a shadow root (so its CSS
+// and the page's don't mix), its scripts run as the page's own, given `root` (that shadow root:
+// root.getElementById, root.querySelector) and `widget` (its element). A widget is laid out in px
+// for a 1080-px-tall screen and scaled with the screen, so it looks the same everywhere. It
+// stands at a point of the frame (interface: a corner, the middle), or follows an element of the scene (hovering `lift` metres
+// over its anchor) as the viewer walks. Errors its scripts throw land in window.__mooodErrors.
+const MooodWidgets = (() => {
+  const REF = 1080;
+  const ANCHORS = { center: [0.5, 0.5], top: [0.5, 0], bottom: [0.5, 1], left: [0, 0.5], right: [1, 0.5],
+    'top-left': [0, 0], 'top-right': [1, 0], 'bottom-left': [0, 1], 'bottom-right': [1, 1] };
+  const report = (key, err) => (window.__mooodErrors = window.__mooodErrors || []).push(`widget ${key}: ${err && err.message || err}`);
+
+  // builds a widget's element: markup into its shadow root, then its scripts, in order
+  function make(w, key) {
+    const el = document.createElement('div');
+    el.className = 'widget';
+    el.dataset.id = key;
+    const root = el.attachShadow({ mode: 'open' });
+    root.innerHTML = `<style>:host{display:block;overflow:hidden}</style>${w.html}`;
+    // markup set as HTML doesn't run its scripts: run them ourselves (after the element is in the page)
+    const scripts = [...root.querySelectorAll('script')];
+    for (const s of scripts) s.remove();
+    el.start = () => {
+      for (const s of scripts) {
+        if (s.src) { const n = document.createElement('script'); n.src = s.src; n.onerror = () => report(key, `can't load ${s.src}`); document.head.append(n); continue; }
+        try { new Function('root', 'widget', s.textContent)(root, el); } catch (err) { report(key, err); }
+      }
+    };
+    return el;
+  }
+
+  function create({ canvas, stage }) {
+    let spec = null, items = [], timers = [], raf = 0, gen = 0;
+    const box = document.createElement('div');
+    box.id = 'widgets';
+    canvas.after(box);
+
+    function show(next) {
+      spec = next;
+      for (const t of timers) clearTimeout(t);
+      timers = [];
+      const list = (Array.isArray(spec?.widgets) ? spec.widgets : []).filter(w => w && typeof w.html === 'string');
+      // keep a widget (and its state) when only its placement changed
+      const old = new Map(items.map(it => [it.src, it]));
+      const fresh = [];
+      items = list.map((w, i) => {
+        const key = w.id || `widget${i}`, src = `${key}\n${w.html}`;
+        let it = old.get(src);
+        if (it) old.delete(src);
+        else { it = { src, el: make(w, key) }; fresh.push(it); }
+        it.w = w;
+        const el = it.el;
+        el.style.width = `${Math.max(1, w.width || 320)}px`;
+        el.style.height = `${Math.max(1, w.height || 120)}px`;
+        el.style.pointerEvents = w.interactive ? 'auto' : 'none';
+        el.classList.toggle('on', !(w.at > 0));
+        if (w.at > 0) timers.push(setTimeout(() => el.classList.add('on'), w.at * 1000));
+        if (w.for > 0) timers.push(setTimeout(() => el.classList.remove('on'), (Math.max(0, w.at || 0) + w.for) * 1000));
+        box.append(el); // in spec order: later ones on top
+        return it;
+      });
+      for (const it of old.values()) it.el.remove();
+      for (const it of fresh) it.el.start();
+      cancelAnimationFrame(raf);
+      const g = ++gen;
+      const loop = () => { if (g !== gen) return; place(); raf = requestAnimationFrame(loop); };
+      if (items.length) loop();
+    }
+
+    function place() {
+      // in the frame (engine.js): bars around it on screens too narrow or wide for it
+      const f = stage.frame(), k = f.h / REF;
+      for (const { w, el } of items) {
+        const [ax, ay] = ANCHORS[w.anchor] || (w.follow ? ANCHORS.bottom : ANCHORS.center);
+        const at = w.follow ? stage.screenOf(w.follow, w.lift ?? 0) : [f.x + (w.x ?? 0.5) * f.w, f.y + (w.y ?? 0.5) * f.h];
+        el.style.visibility = at ? '' : 'hidden';
+        if (!at) continue;
+        const fw = Math.max(1, w.width || 320), fh = Math.max(1, w.height || 120);
+        el.style.transform = `translate(${at[0] - ax * fw * k}px, ${at[1] - ay * fh * k}px) scale(${k})`;
+      }
+    }
+
+    return { show };
+  }
+  return { create };
+})();

package/index.js

@@ -0,0 +1,70 @@
+// 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}]
+//     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"});
+//     bare — without the title and the captions over it;
+//     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';
+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;
+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
+
+export async function render({ spec, modules = {}, device = '16:9', at = [0], state = {}, bare = false, chromium, date } = {}) {
+  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 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'],
+  });
+  try {
+    const page = await (await browser.newContext({ viewport: { width: size[0], height: size[1] } })).newPage();
+    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)
+    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.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);
+    // 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 = [];
+    let now = 0;
+    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;
+      }
+      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) });
+    }
+    return frames;
+  } finally {
+    await browser.close();
+  }
+}

package/package.json

@@ -1,6 +1,13 @@
-{
-  "name": "@moood/render",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+{
+  "name": "@moood/render",
+  "version": "0.0.0",
+  "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.",
+  "license": "UNLICENSED",
+  "type": "module",
+  "main": "index.js",
+  "bin": { "moood-render": "cli.js" },
+  "files": ["index.js", "cli.js", "scene.js", "engine/", "README.md"],
+  "engines": { "node": ">=20" },
+  "dependencies": { "playwright-core": "^1.56.0" },
+  "scripts": { "build": "node build.js" }
+}

package/scene.js

@@ -0,0 +1,43 @@
+// A scene as it lies in its world's repository, put together as moood does it (the scenes service's
+// layout.py): scenes/<folder>/scene.json and its code beside it — elements/<id>.js (objects[].code),
+// elements/<id>.script.js (objects[].script), script.js, lib.js, notes.md, widgets/<id>.html — and
+// the modules it lists (modules/<name>.js, .data.json, in the world's repository).
+import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
+import { join, relative, sep } from 'node:path';
+
+const TOP = { script: 'script.js', lib: 'lib.js', notes: 'notes.md' };
+const IN = { objects: { code: 'elements/{id}.js', script: 'elements/{id}.script.js' }, widgets: { html: 'widgets/{id}.html' } };
+
+const walk = dir => readdirSync(dir).flatMap(f => (statSync(join(dir, f)).isDirectory() ? walk(join(dir, f)) : [join(dir, f)]));
+
+// the spec a scene's folder makes (an error says what is wrong with it)
+export function readScene(folder) {
+  const files = Object.fromEntries(walk(folder).map(p => [relative(folder, p).split(sep).join('/'), readFileSync(p, 'utf8')]));
+  if (!('scene.json' in files)) throw new Error(`${folder}: no scene.json`);
+  const spec = JSON.parse(files['scene.json']);
+  const used = new Set(['scene.json']);
+  for (const [key, name] of Object.entries(TOP)) if (name in files) { spec[key] = files[name].replace(/\n+$/, ''); used.add(name); }
+  for (const [key, fields] of Object.entries(IN)) {
+    for (const item of spec[key] || []) {
+      if (!item || typeof item !== 'object' || !item.id) continue;
+      for (const [field, path] of Object.entries(fields)) {
+        const name = path.replace('{id}', item.id);
+        if (name in files) { item[field] = files[name].replace(/\n+$/, ''); used.add(name); }
+      }
+    }
+  }
+  const extra = Object.keys(files).filter(f => !used.has(f));
+  if (extra.length) throw new Error(`files no element or widget of scene.json names: ${extra.join(', ')}`);
+  return spec;
+}
+
+// the modules a scene lists, from its world's repository: {name: {code, data}}
+export function readModules(world, spec) {
+  const out = {};
+  for (const name of [...new Set((spec.modules || []).filter(n => typeof n === 'string'))].sort()) {
+    const code = join(world, 'modules', `${name}.js`), data = join(world, 'modules', `${name}.data.json`);
+    if (!existsSync(code)) throw new Error(`the scene lists modules/${name}.js, and there is none`);
+    out[name] = { code: readFileSync(code, 'utf8'), data: existsSync(data) ? JSON.parse(readFileSync(data, 'utf8')) : null };
+  }
+  return out;
+}