@moood/render 0.0.0-stage → 0.0.0

package/engine/kit.js

@@ -0,0 +1,142 @@
+// What a scene's code shares, and the tools for moving things well.
+//   anim — the animator's toolkit, for every scene: easing curves (a movement starts and stops as
+//     a body does), angles the short way round, smooth noise and steady random (life that doesn't
+//     repeat, the same every time), a two-bone joint (an elbow, a knee: the hand or the foot set
+//     where it must be), poses mixed by weight.
+//   the world's modules — code the world's scenes share (its people, its horses, its things):
+//     modules/<name>.js in the world's repository, the body of function (anim, data) that returns
+//     what it offers (data: modules/<name>.data.json, if there is one). A scene lists the ones it
+//     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.
+// 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
+//     that has just listed it) is the world's main's now (/api/worlds/<world>/modules). The files
+//     are read by /api/worlds/<world>/blobs/<sha> — the same for good, fetched once.
+//   {texts} — the modules themselves, {name: {code, data}} (the renderer is given them).
+const MooodKit = (() => {
+  const clamp = (v, a = 0, b = 1) => Math.max(a, Math.min(b, v));
+  const mix = (a, b, u) => a + (b - a) * u;
+  // u (0…1) of the way between a and b that v is, clamped
+  const span = (v, a, b) => clamp((v - a) / (b - a));
+  // easing: how the 0…1 of a movement's time becomes the 0…1 of its way
+  const ease = {
+    linear: u => u,
+    smooth: u => (1 - Math.cos(Math.PI * u)) / 2,              // starts and stops gently (the default)
+    in: u => u * u * u,                                         // gathers speed, ends at full speed
+    out: u => 1 - Math.pow(1 - u, 3),                           // sets off at once, settles
+    inOut: u => (u < 0.5 ? 4 * u * u * u : 1 - Math.pow(-2 * u + 2, 3) / 2),
+    back: u => { const c = 1.70158; return 1 + (c + 1) * Math.pow(u - 1, 3) + c * Math.pow(u - 1, 2); }, // a little past, and back
+    spring: u => (u >= 1 ? 1 : 1 - Math.exp(-6 * u) * Math.cos(9 * u)),               // overshoots, wobbles, rests
+    anticipate: u => { const c = 1.4; return u * u * ((c + 1) * u - c); },              // back a little first, then go
+  };
+  const easeOf = e => (typeof e === 'function' ? e : ease[e] || ease.smooth);
+  // angles (radians): the short way round from a to b
+  const turn = (a, b, u) => { let d = ((b - a) % (2 * Math.PI) + 3 * Math.PI) % (2 * Math.PI) - Math.PI; return a + d * u; };
+  // steady random: the same n gives the same 0…1, however many other calls came before
+  const hash = (n, seed = 0) => { let h = Math.imul((n * 374761393 + seed * 668265263) | 0, 1274126177); h = (h ^ (h >>> 13)) >>> 0; h = Math.imul(h, 1103515245) >>> 0; return ((h ^ (h >>> 16)) >>> 0) / 4294967296; };
+  // smooth noise along x (−1…1): for breathing, swaying, drifting that never repeats
+  const noise = (x, seed = 0) => { const i = Math.floor(x), f = x - i, s = f * f * (3 - 2 * f); return mix(hash(i, seed) * 2 - 1, hash(i + 1, seed) * 2 - 1, s); };
+  // a few octaves of it, slower ones stronger
+  const drift = (x, seed = 0) => noise(x, seed) * 0.6 + noise(x * 2.1 + 7, seed + 1) * 0.3 + noise(x * 4.3 + 13, seed + 2) * 0.1;
+  // a two-bone joint: from the root (x0, y0) to the end (x1, y1) with bones a and b; bend 1 or −1 —
+  // which side the joint goes. Returns the joint [x, y] (the end out of reach: the limb straight toward it)
+  const joint = (x0, y0, x1, y1, a, b, bend = 1) => {
+    const dx = x1 - x0, dy = y1 - y0, d = Math.min(Math.hypot(dx, dy), a + b - 1e-6), ang = Math.atan2(dy, dx);
+    const k = clamp((a * a + d * d - b * b) / (2 * a * d || 1), -1, 1), off = Math.acos(k) * bend;
+    return [x0 + Math.cos(ang + off) * a, y0 + Math.sin(ang + off) * a];
+  };
+  // poses mixed: pose objects (numbers, or nested objects/arrays of them) weighted [[pose, weight], …]
+  const blend = list => {
+    const total = list.reduce((s, [, w]) => s + w, 0) || 1, [first] = list[0];
+    const go = (sel) => {
+      const v0 = sel(first);
+      if (typeof v0 === 'number') return list.reduce((s, [p, w]) => s + (sel(p) ?? v0) * w, 0) / total;
+      if (Array.isArray(v0)) return v0.map((_, i) => go(p => sel(p)?.[i]));
+      if (v0 && typeof v0 === 'object') return Object.fromEntries(Object.keys(v0).map(k => [k, go(p => sel(p)?.[k])]));
+      return v0;
+    };
+    return go(p => p);
+  };
+  const anim = Object.freeze({ clamp, mix, span, ease, easeOf, turn, hash, noise, drift, joint, blend });
+
+  const report = (who, err) => (window.__mooodErrors = window.__mooodErrors || []).push(`${who}: ${err && err.message || err}`);
+  // files by their content's sha (the same for good), modules made from them, libs made: once each
+  const files = new Map(), made = new Map(), libs = new Map(), mains = new Map();
+  const fileOf = (world, sha) => {
+    if (!files.has(sha)) files.set(sha, fetch(`/api/worlds/${world}/blobs/${sha}`).then(r => (r.ok ? r.text() : Promise.reject(new Error(`${sha}: ${r.status}`)))));
+    return files.get(sha);
+  };
+  const mainOf = world => {
+    if (!mains.has(world)) mains.set(world, fetch(`/api/worlds/${world}/modules`).then(r => (r.ok ? r.json() : {})).catch(() => ({})));
+    return mains.get(world);
+  };
+  function make(name, key, code, data) {
+    if (!made.has(key)) {
+      let value = {};
+      try { value = new Function('anim', 'data', String(code))(anim, data) || {}; } catch (err) { report(`module ${name}`, err); }
+      made.set(key, value);
+    }
+    return made.get(key);
+  }
+  // a spec's modules, as `source` says: {mods: {name: what it offers}, key: which they are} — or a
+  // promise of it
+  function modulesOf(spec, source) {
+    const names = [...new Set((Array.isArray(spec?.modules) ? spec.modules : []).filter(n => typeof n === 'string'))].sort();
+    const out = (mods, keys) => ({ mods, key: keys.join('\n') });
+    if (!names.length) return out({}, []);
+    if (source?.texts) {
+      const mods = {}, keys = [];
+      for (const n of names) {
+        const m = source.texts[n];
+        if (m?.code == null) { report(`module ${n}`, 'not in this world'); continue; }
+        const key = `${n} ${m.code} ${JSON.stringify(m.data ?? null)}`;
+        mods[n] = make(n, key, m.code, m.data ?? null); keys.push(key);
+      }
+      return out(mods, keys);
+    }
+    const world = source?.world;
+    if (world == null) { report('modules', 'the page did not say whose they are'); return out({}, []); }
+    const keyOf = (n, r) => `${n} ${r.code} ${r.data}`;
+    const built = refs => {
+      const mods = {}, keys = [];
+      for (const n of names) if (refs[n]?.code && made.has(keyOf(n, refs[n]))) { mods[n] = made.get(keyOf(n, refs[n])); keys.push(keyOf(n, refs[n])); }
+      return out(mods, keys);
+    };
+    const refs0 = source.refs || {};
+    if (names.every(n => refs0[n]?.code && made.has(keyOf(n, refs0[n])))) return built(refs0);
+    return (names.every(n => refs0[n]?.code) ? Promise.resolve(refs0) : mainOf(world).then(now => ({ ...now, ...refs0 }))).then(async refs => {
+      await Promise.all(names.map(async n => {
+        const r = refs[n];
+        if (!r?.code) { report(`module ${n}`, 'not in this world'); return; }
+        if (made.has(keyOf(n, r))) return;
+        try {
+          const [code, data] = await Promise.all([fileOf(world, r.code), r.data ? fileOf(world, r.data).then(JSON.parse) : null]);
+          make(n, keyOf(n, r), code, data);
+        } catch (err) { report(`module ${n}`, err); }
+      }));
+      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.
+  const kits = new Map();
+  function shared(spec, source) {
+    const done = ({ mods, key }) => {
+      if (!kits.has(key)) kits.set(key, Object.freeze(mods));
+      const kit = kits.get(key), lib = typeof spec?.lib === 'string' && spec.lib.trim() ? spec.lib : null;
+      if (lib && !libs.has(`${key}\n\n${lib}`)) {
+        let value = {};
+        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 m = modulesOf(spec, source);
+    return m instanceof Promise ? m.then(done) : done(m);
+  }
+  return { anim, shared };
+})();

package/engine/live.js

@@ -0,0 +1,23 @@
+// A live channel from the server (a game's, or the artist's work): a WebSocket — unlike a
+// long-lived HTTP request (SSE), it doesn't count against the browser's six connections to a site,
+// which a few open tabs would use up and leave every next page waiting. Each message is an event,
+// most marked (_at) with where it is in the channel; a closed socket is opened again from the last
+// one, so nothing is missed.
+//   MooodLive.open(path, since, handle) — handle(event) for every event but pings
+const MooodLive = (() => {
+  function open(path, since, handle) {
+    let leaving = false;
+    addEventListener('pagehide', () => { leaving = true; });
+    const connect = () => {
+      const ws = new WebSocket(`${location.protocol === 'https:' ? 'wss' : 'ws'}://${location.host}${path}?since=${encodeURIComponent(since)}`);
+      ws.onmessage = m => {
+        const ev = JSON.parse(m.data);
+        if (ev._at) since = ev._at;
+        if (ev.type !== 'ping') handle(ev);
+      };
+      ws.onclose = () => { if (!leaving) setTimeout(connect, 2000); };
+    };
+    connect();
+  }
+  return { open };
+})();

package/engine/mic.js

@@ -0,0 +1,76 @@
+// Speaking. While the player holds the microphone, the page streams it to /listen (the sound
+// service: PCM16, 24 kHz, mono, binary frames), telling what scene it is — its words help hearing
+// names right — and the words come back as they are heard; letting go sends {"type": "done"} and
+// the final text follows.
+const MooodMic = (() => {
+  // a tap on the audio graph: the microphone at the context's own rate, handed on at 24 kHz
+  // (linear interpolation across blocks), whatever rate the browser runs audio at
+  const TAP = `registerProcessor('tap', class extends AudioWorkletProcessor {
+    constructor() { super(); this.step = sampleRate / 24000; this.pos = 0; this.prev = 0; }
+    process(inputs) {
+      const ch = inputs[0][0];
+      if (!ch) return true;
+      const out = [];
+      let pos = this.pos; // where the next sample falls, in this block's samples (-1..0: just before it)
+      while (pos < ch.length - 1) {
+        const i = Math.floor(pos), f = pos - i, a = i < 0 ? this.prev : ch[i];
+        out.push(a + (ch[i + 1] - a) * f);
+        pos += this.step;
+      }
+      this.pos = pos - ch.length; this.prev = ch[ch.length - 1];
+      if (out.length) this.port.postMessage(Float32Array.from(out));
+      return true;
+    }
+  });`;
+  let tapUrl = null;
+
+  // starts an utterance in the scene `spec`; on: { partial(text), final(text), error(text) }.
+  // Returns { done(), cancel() }.
+  async function listen(spec, on) {
+    const q = new URLSearchParams({ title: spec?.title || '', caption: spec?.caption || '' });
+    for (const o of spec?.objects || []) if (o.name) q.append('name', o.name);
+    const ws = new WebSocket(`${location.protocol === 'https:' ? 'wss' : 'ws'}://${location.host}/listen?${q}`);
+    ws.binaryType = 'arraybuffer';
+    const early = []; // what was said before the socket opened
+    ws.onopen = () => { for (const b of early.splice(0)) ws.send(b); };
+    let over = false; // the final text or an error came
+    ws.onmessage = e => {
+      const m = JSON.parse(e.data);
+      if (m.type === 'partial') on.partial(m.text);
+      else if (m.type === 'final') { over = true; on.final(m.text); }
+      else if (m.type === 'error') { over = true; on.error(m.text); }
+    };
+    ws.onclose = () => { if (!over) on.error(''); };
+    let media, ctx;
+    try {
+      media = await navigator.mediaDevices.getUserMedia({ audio: { channelCount: 1, echoCancellation: true, noiseSuppression: true } });
+      ctx = new AudioContext();
+      tapUrl = tapUrl || URL.createObjectURL(new Blob([TAP], { type: 'text/javascript' }));
+      await ctx.audioWorklet.addModule(tapUrl);
+    } catch (err) {
+      ws.close();
+      media?.getTracks().forEach(t => t.stop());
+      throw err;
+    }
+    const tap = new AudioWorkletNode(ctx, 'tap'), mute = ctx.createGain();
+    mute.gain.value = 0;
+    tap.port.onmessage = e => {
+      const f = e.data, pcm = new Int16Array(f.length);
+      for (let i = 0; i < f.length; i++) pcm[i] = Math.max(-1, Math.min(1, f[i])) * 0x7fff;
+      if (ws.readyState === WebSocket.OPEN) ws.send(pcm.buffer); else if (ws.readyState === WebSocket.CONNECTING) early.push(pcm.buffer);
+    };
+    ctx.createMediaStreamSource(media).connect(tap);
+    tap.connect(mute).connect(ctx.destination); // pulled by the graph, heard by no one
+    const close = () => { media.getTracks().forEach(t => t.stop()); ctx.close(); };
+    return {
+      done() {
+        close();
+        const send = () => ws.send(JSON.stringify({ type: 'done' }));
+        if (ws.readyState === WebSocket.OPEN) send(); else ws.addEventListener('open', send);
+      },
+      cancel() { close(); ws.close(); },
+    };
+  }
+
+  return { listen };
+})();

package/engine/music.css

@@ -0,0 +1,28 @@
+/* The world's music panel (music.js): descriptions with weights, settings, save — on the scene
+   page (listening) and the author's page (tuning). */
+#music { position: fixed; top: 16px; left: 16px; bottom: 16px; width: 360px; display: flex; flex-direction: column; border-radius: 16px; background: rgba(8, 10, 16, 0.86); overflow: hidden; z-index: 3; font-size: 13px; color: #e6e8ee; font-family: Georgia, "Times New Roman", serif; }
+/* the panel brings its own buttons: it sits on the dark scene page and the light author's page alike */
+#music button { border: 1px solid rgba(255, 255, 255, 0.2); background: rgba(255, 255, 255, 0.06); color: inherit; font: inherit; font-size: 14px; padding: 4px 12px; border-radius: 999px; cursor: pointer; }
+#music button:hover { background: rgba(255, 255, 255, 0.14); }
+#music[hidden] { display: none; }
+#music .music-head { display: flex; align-items: center; gap: 8px; padding: 10px 12px; border-bottom: 1px solid rgba(255, 255, 255, 0.08); }
+#music .music-head .title { flex: 1; font-size: 15px; }
+#music .play { min-width: 38px; }
+#music .status { padding: 6px 12px 0; font-size: 12px; font-style: italic; opacity: 0.6; min-height: 1.4em; }
+#music .prompts { flex: 1; overflow-y: auto; list-style: none; margin: 0; padding: 8px 12px; display: flex; flex-direction: column; gap: 8px; }
+#music .prompts li { padding: 6px 8px; border-radius: 10px; background: rgba(255, 255, 255, 0.03); opacity: 0.6; }
+#music .prompts li.on { opacity: 1; background: rgba(255, 214, 150, 0.08); }
+#music textarea, #music .add input { width: 100%; box-sizing: border-box; resize: none; field-sizing: content; border: 0; outline: none; background: transparent; color: inherit; font: inherit; line-height: 1.35; }
+#music .row, #music .knobs label { display: flex; align-items: center; gap: 8px; }
+#music input[type=range] { flex: 1; accent-color: #e8c48a; }
+#music .val { width: 3.2em; text-align: right; font-variant-numeric: tabular-nums; opacity: 0.75; font-size: 12px; }
+#music .del { padding: 0 7px; font-size: 12px; }
+#music .add { display: flex; gap: 6px; padding: 8px 12px; border-top: 1px solid rgba(255, 255, 255, 0.08); }
+#music .add input { border-bottom: 1px solid rgba(255, 255, 255, 0.15); }
+#music .knobs { padding: 6px 12px; display: flex; flex-direction: column; gap: 4px; border-top: 1px solid rgba(255, 255, 255, 0.08); }
+#music .knobs .name { width: 5.5em; opacity: 0.8; }
+#music .knobs label.auto input[type=range] { opacity: 0.35; }
+#music .foot { display: flex; justify-content: flex-end; gap: 8px; padding: 8px 12px 12px; }
+#music.readonly .add, #music.readonly .foot, #music.readonly .del { display: none; }
+#music.readonly textarea, #music.readonly input[type=range] { pointer-events: none; }
+@media (max-width: 700px) { #music { left: 8px; right: 8px; width: auto; top: 8px; bottom: auto; max-height: 50vh; } }

package/engine/music.js

@@ -0,0 +1,279 @@
+// A world's music: live instrumental from Lyria RealTime (Gemini API), steered by weighted
+// text descriptions. The artist writes many (most at weight 0); the author tunes them with
+// sliders, adds their own lines, removes the artist's, and saves — a new version of the scene.
+// The stream starts at the first touch of the page (browsers don't let sound start by itself)
+// and follows the open world; changes are sent live while it plays.
+//   It comes through our server (music.mjs), so the Gemini key never reaches the browser:
+//   GET /api/music/stream — frames [type:1][length:4 LE][payload], 1 = PCM16 48 kHz stereo,
+//   2 = a JSON event; POST /api/music/control — prompts, settings, play / pause / reset.
+//   Weight 0 means "not now" and is never sent (the API refuses zero weights).
+const MooodMusic = (() => {
+  const RATE = 48000, LEAD = 0.25; // seconds of audio queued ahead
+  const store = {
+    get: k => { try { return localStorage.getItem(k); } catch { return null; } },
+    set: (k, v) => { try { localStorage.setItem(k, v); } catch {} },
+  };
+  let ui = null, onSave = null;
+  let music = null, savedJson = '';           // what the panel shows / what the scene has
+  let sid = null, opening = null, ctx = null, out = null, nextT = 0;
+  let playing = false, starting = false, sentBpm = null, pushTimer = null;
+  let wanted = store.get('moood:music') !== 'off';
+  MooodVolume.on((kind, v) => { if (kind === 'music' && playing && out) out.gain.setTargetAtTime(v, ctx.currentTime, 0.1); });
+
+  const clone = m => JSON.parse(JSON.stringify(m || { prompts: [] }));
+  const active = () => (music?.prompts || []).filter(p => p.text.trim() && p.weight > 0);
+
+  function status(text) { if (ui) ui.status.textContent = text; }
+
+  // ── the stream ───────────────────────────────────────────────────────────
+  function open() {
+    if (sid) return Promise.resolve();
+    if (opening) return opening;
+    opening = new Promise((resolve, reject) => {
+      const id = 's-' + Math.random().toString(36).slice(2, 12);
+      status('подключаюсь…');
+      fetch(`/api/music/stream?sid=${id}`).then(async r => {
+        if (!r.ok || !r.body) throw new Error('поток музыки не открылся');
+        const reader = r.body.getReader();
+        let buf = new Uint8Array(0);
+        for (;;) {
+          const { value, done } = await reader.read();
+          if (done) break;
+          const joined = new Uint8Array(buf.length + value.length);
+          joined.set(buf); joined.set(value, buf.length);
+          buf = joined;
+          while (buf.length >= 5) {
+            const len = buf[1] | (buf[2] << 8) | (buf[3] << 16) | (buf[4] << 24);
+            if (buf.length < 5 + len) break;
+            const type = buf[0], payload = buf.slice(5, 5 + len);
+            buf = buf.slice(5 + len);
+            if (type === 1) enqueue(payload);
+            else {
+              const ev = JSON.parse(new TextDecoder().decode(payload));
+              if (ev.ready) { sid = id; resolve(); }
+              if (ev.error) { status('ошибка: ' + ev.error); reject(new Error(ev.error)); }
+              if (ev.filtered) status(`не принят: «${ev.filtered}»`);
+            }
+          }
+        }
+        throw new Error('поток закрыт');
+      }).catch(e => {
+        const was = sid === id;
+        if (sid === id) sid = null;
+        sentBpm = null;
+        reject(e);
+        if (was && playing) { playing = false; paint(); status(e.message); }
+      });
+    });
+    return opening.finally(() => { opening = null; });
+  }
+
+  async function control(body) {
+    if (!sid) return;
+    const r = await fetch('/api/music/control', { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify({ sid, ...body }) });
+    if (!r.ok) throw new Error((await r.json().catch(() => ({}))).error || 'управление не прошло');
+  }
+
+  function enqueue(bytes) {
+    window.__mooodMusicChunks = (window.__mooodMusicChunks || 0) + 1; // for checking the stream
+    if (!ctx || !playing) return;
+    const n = bytes.length >> 2, buf = ctx.createBuffer(2, n, RATE);
+    const L = buf.getChannelData(0), R = buf.getChannelData(1);
+    const pcm = new DataView(bytes.buffer, bytes.byteOffset, n * 4);
+    for (let i = 0; i < n; i++) {
+      L[i] = pcm.getInt16(i * 4, true) / 32768;
+      R[i] = pcm.getInt16(i * 4 + 2, true) / 32768;
+    }
+    const src = ctx.createBufferSource();
+    src.buffer = buf;
+    src.connect(out);
+    const at = Math.max(nextT, ctx.currentTime + LEAD);
+    src.start(at);
+    nextT = at + buf.duration;
+  }
+
+  // send what the panel shows: the prompts with weight, and the settings
+  async function push() {
+    if (!sid || !playing) return;
+    const prompts = active();
+    if (!prompts.length) { status('все веса на нуле — тишина'); await control({ action: 'pause' }); return; }
+    const config = {};
+    for (const k of ['density', 'brightness']) if (typeof music[k] === 'number') config[k] = music[k];
+    if (typeof music.bpm === 'number') config.bpm = Math.round(music.bpm);
+    const reset = config.bpm !== sentBpm && sentBpm !== null; // tempo changes need a fresh start
+    sentBpm = config.bpm ?? null;
+    await control({ prompts: prompts.map(p => ({ text: p.text.trim(), weight: p.weight })), config });
+    if (reset) await control({ action: 'reset' });
+    await control({ action: 'play' });
+    status('играет');
+  }
+  function pushSoon() { clearTimeout(pushTimer); pushTimer = setTimeout(() => push().catch(e => status('ошибка: ' + e.message)), 200); }
+
+  async function start() {
+    if (playing || starting) return;
+    starting = true;
+    paint();
+    try {
+      ctx = ctx || new AudioContext({ sampleRate: RATE });
+      await ctx.resume();
+      if (!out) { out = ctx.createGain(); out.connect(ctx.destination); }
+      out.gain.setTargetAtTime(MooodVolume.get('music'), ctx.currentTime, 0.3);
+      await open();
+      if (!wanted) return; // switched off while connecting
+      playing = true;
+      paint();
+      await push();
+    } catch (e) { playing = false; status(e.message); } finally { starting = false; paint(); }
+  }
+  async function stop() {
+    playing = false;
+    paint();
+    status('пауза');
+    if (out && ctx) out.gain.setTargetAtTime(0, ctx.currentTime, 0.25);
+    nextT = 0;
+    try { await control({ action: 'pause' }); } catch {}
+  }
+
+  // ── the panel ────────────────────────────────────────────────────────────
+  function el(tag, cls, text) { const e = document.createElement(tag); if (cls) e.className = cls; if (text !== undefined) e.textContent = text; return e; }
+
+  function build() {
+    const root = el('section');
+    root.id = 'music';
+    root.hidden = true;
+    const head = el('div', 'music-head');
+    const play = el('button', 'play');
+    play.type = 'button';
+    play.onclick = () => { wanted = !(playing || starting); store.set('moood:music', wanted ? 'on' : 'off'); wanted ? start() : stop(); };
+    const title = el('span', 'title', 'Музыка');
+    const close = el('button', 'close', '×');
+    close.type = 'button';
+    close.title = 'закрыть';
+    close.onclick = () => { root.hidden = true; };
+    head.append(play, title, close);
+    const st = el('div', 'status');
+    const list = el('ol', 'prompts');
+    const add = el('form', 'add');
+    const addText = el('input');
+    addText.placeholder = 'своё описание музыки…';
+    const addBtn = el('button', '', '+');
+    add.append(addText, addBtn);
+    add.onsubmit = e => {
+      e.preventDefault();
+      const text = addText.value.trim();
+      if (!text) return;
+      music.prompts.push({ text, weight: 1 });
+      addText.value = '';
+      renderList(); changed();
+    };
+    const knobs = el('div', 'knobs');
+    const save = el('button', 'save', 'сохранить');
+    save.type = 'button';
+    save.onclick = async () => {
+      if (!onSave) return;
+      save.disabled = true;
+      status('сохраняю…');
+      try { await onSave(clone(music)); savedJson = JSON.stringify(music); status(playing ? 'играет' : 'сохранено'); } catch (e) { status('ошибка: ' + e.message); }
+      paint();
+    };
+    const revert = el('button', 'revert', 'как было');
+    revert.type = 'button';
+    revert.onclick = () => { music = JSON.parse(savedJson); renderList(); renderKnobs(); changed(); };
+    const foot = el('div', 'foot');
+    foot.append(revert, save);
+    root.append(head, st, list, add, knobs, foot);
+    document.body.append(root);
+    return { root, play, status: st, list, knobs, save, revert };
+  }
+
+  function slider(min, max, step, value, onInput) {
+    const r = el('input');
+    r.type = 'range'; r.min = min; r.max = max; r.step = step; r.value = value;
+    r.oninput = () => onInput(Number(r.value));
+    return r;
+  }
+
+  function renderList() {
+    ui.list.innerHTML = '';
+    for (const p of music.prompts) {
+      const li = el('li', p.weight > 0 ? 'on' : '');
+      const text = el('textarea');
+      text.rows = 1;
+      text.value = p.text;
+      text.oninput = () => { p.text = text.value; changed(); };
+      const val = el('span', 'val', p.weight.toFixed(2));
+      const w = slider(0, 2, 0.05, p.weight, v => { p.weight = v; val.textContent = v.toFixed(2); li.classList.toggle('on', v > 0); changed(); });
+      const del = el('button', 'del', '×');
+      del.type = 'button';
+      del.title = 'убрать';
+      del.onclick = () => { music.prompts.splice(music.prompts.indexOf(p), 1); renderList(); changed(); };
+      const row = el('div', 'row');
+      row.append(w, val, del);
+      li.append(text, row);
+      ui.list.append(li);
+    }
+  }
+
+  function renderKnobs() {
+    ui.knobs.innerHTML = '';
+    for (const [k, label, min, max, step, def] of [['density', 'плотность', 0, 1, 0.01, 0.5], ['brightness', 'яркость', 0, 1, 0.01, 0.5], ['bpm', 'темп', 60, 200, 1, 90]]) {
+      const set = typeof music[k] === 'number';
+      const row = el('label', set ? '' : 'auto');
+      const val = el('span', 'val', set ? String(music[k]) : 'авто');
+      const r = slider(min, max, step, set ? music[k] : def, v => { music[k] = v; val.textContent = String(v); row.classList.remove('auto'); changed(); });
+      const reset = el('button', 'del', '↺');
+      reset.type = 'button';
+      reset.title = 'авто';
+      reset.onclick = () => { delete music[k]; renderKnobs(); changed(); };
+      row.append(el('span', 'name', label), r, val, reset);
+      ui.knobs.append(row);
+    }
+  }
+
+  function paint() {
+    if (!ui) return;
+    const on = playing || starting;
+    ui.play.textContent = on ? '⏸' : '▶';
+    ui.play.title = on ? 'пауза' : 'играть';
+    const dirty = JSON.stringify(music) !== savedJson;
+    ui.save.disabled = !dirty || !onSave;
+    ui.revert.disabled = !dirty;
+  }
+
+  function changed() { paint(); pushSoon(); }
+
+  // ── the page's side ──────────────────────────────────────────────────────
+  // init: once; toggle: a button that opens the panel (or the page calls panel()); save(music) →
+  // persists it (author)
+  function init({ toggle, save }) {
+    ui = build();
+    onSave = save;
+    if (toggle) toggle.onclick = panel;
+    // sound may only start from a gesture: the first touch of the page starts it
+    const first = () => { removeEventListener('pointerdown', first, true); removeEventListener('keydown', first, true); if (wanted && music && active().length) start(); };
+    addEventListener('pointerdown', first, true);
+    addEventListener('keydown', first, true);
+    status(wanted ? 'заиграет от первого касания' : 'пауза');
+    paint();
+  }
+
+  // the open world's music (from its spec), or none
+  function show(m) {
+    music = clone(m);
+    music.prompts = (music.prompts || []).map(p => ({ text: String(p.text || ''), weight: Number(p.weight) || 0 }));
+    savedJson = JSON.stringify(music);
+    if (!ui) return;
+    renderList();
+    renderKnobs();
+    paint();
+    if (playing) pushSoon();
+  }
+
+  // author or player: players hear, only authors tune
+  function setEditable(on) { if (ui) ui.root.classList.toggle('readonly', !on); }
+
+  // opens or closes the panel
+  function panel() { ui.root.hidden = !ui.root.hidden; }
+
+  return { init, show, setEditable, panel };
+})();

package/engine/nav.css

@@ -0,0 +1,66 @@
+/* Finding one's way, the same on every page: the crumbs — where I am: moood / a world / a game / … —
+   (templates/_crumbs.html), and the viewer — a scene looked at without leaving the page (viewer.js). */
+
+.crumbs { display: flex; flex-wrap: wrap; align-items: baseline; gap: 2px 7px; min-width: 0; font-family: Georgia, "Times New Roman", serif; }
+.crumbs a { color: inherit; text-decoration: none; }
+.crumbs a:hover { text-decoration: underline; }
+.crumbs .brand { font-style: italic; }
+.crumbs .brand .moon { color: #e8c98a; }
+/* a small moon over the m, as in the sign (drawn, not a letter: what is copied is still "moood.me") */
+.crumbs .brand .m { position: relative; }
+.crumbs .brand .m::after { content: ""; position: absolute; left: 0.46em; top: 0.15em; width: 0.15em; height: 0.15em; border-radius: 50%; background: #e8c98a; pointer-events: none; }
+.crumbs .brand .tld { opacity: 0.55; }
+.crumbs .sep { opacity: 0.35; }
+.crumbs .kind { margin-right: -3px; font-size: 0.78em; font-style: italic; opacity: 0.55; }
+.crumbs form { display: inline; }
+.crumbs button { border: 0; background: none; color: inherit; font: inherit; padding: 0; cursor: pointer; opacity: 0.7; }
+.crumbs button:hover { opacity: 1; text-decoration: underline; }
+.crumbs .volume { margin-left: 4px; font-size: 0.85em; }
+.crumbs .volume:hover { text-decoration: none; }
+/* how loud: the music and the voices (volume.js) */
+#volume { position: fixed; z-index: 50; width: 220px; box-sizing: border-box; padding: 10px 12px; display: grid; gap: 8px;
+  border-radius: 10px; background: rgba(14, 17, 22, 0.94); border: 1px solid rgba(255, 255, 255, 0.12); backdrop-filter: blur(6px);
+  box-shadow: 0 10px 30px rgba(0, 0, 0, 0.45); color: rgba(236, 232, 224, 0.92); font: 14px/1.3 Georgia, "Times New Roman", serif; }
+#volume[hidden] { display: none; }
+#volume label { display: grid; grid-template-columns: 64px 1fr; align-items: center; gap: 8px; }
+#volume input { width: 100%; accent-color: #e8c98a; }
+/* over a scene full-screen: top-left */
+#crumbs { position: fixed; left: 12px; top: 10px; z-index: 6; max-width: min(720px, calc(100vw - 24px)); padding: 4px 12px;
+  border-radius: 999px; background: rgba(10, 12, 18, 0.55); backdrop-filter: blur(6px); font-size: 14px; line-height: 1.4;
+  color: rgba(236, 232, 224, 0.92); }
+
+/* a full-screen page whose thing is not there (shell.js lost) */
+.lost { min-height: 100vh; display: flex; flex-direction: column; align-items: center; justify-content: center; gap: 4px;
+  padding: 16px; box-sizing: border-box; background: #0e1116; color: #d6dae1; font: 16px/1.5 Georgia, "Times New Roman", serif; }
+.lost a { color: #e8c98a; }
+.lost .crumbs { margin-bottom: 18px; font-size: 18px; }
+
+/* the viewer */
+.viewer-veil { position: fixed; inset: 0; z-index: 40; background: rgba(4, 6, 10, 0.6); opacity: 0; pointer-events: none; transition: opacity 0.32s ease; }
+.viewer-veil.open { opacity: 1; pointer-events: auto; }
+.viewer { position: fixed; z-index: 41; display: none; flex-direction: column; overflow: hidden; border-radius: 12px; background: #07080c;
+  box-shadow: 0 30px 80px rgba(0, 0, 0, 0.6); border: 1px solid rgba(255, 255, 255, 0.12); }
+.viewer.open { display: flex; }
+.viewer { transform-origin: 0 0; }
+.viewer.moving { transition: transform 0.32s ease, clip-path 0.32s ease; }
+/* the scene's picture, standing in its place until the scene has drawn itself (then fading out),
+   and coming back over it as the view shrinks back into it */
+.viewer-still { position: absolute; object-fit: cover; pointer-events: none; }
+.viewer-still.gone { opacity: 0; transition: opacity 0.3s ease; }
+/* waiting for the scene, over its picture: a slow ring in the middle */
+.viewer-wait { position: absolute; width: 34px; height: 34px; margin: -17px 0 0 -17px; border-radius: 50%;
+  border: 2px solid rgba(255, 255, 255, 0.18); border-top-color: rgba(255, 236, 200, 0.85); opacity: 0; pointer-events: none;
+  transition: opacity 0.3s ease; animation: viewer-wait 1s linear infinite; }
+.viewer.waiting .viewer-wait { opacity: 1; }
+@keyframes viewer-wait { to { transform: rotate(1turn); } }
+.viewer.closing .viewer-still { opacity: 1; transition: opacity 0.25s ease; }
+.viewer-bar { display: flex; align-items: center; gap: 8px; padding: 6px 10px; font: 14px/1.3 Georgia, "Times New Roman", serif;
+  color: rgba(236, 232, 224, 0.92); background: rgba(255, 255, 255, 0.04); border-bottom: 1px solid rgba(255, 255, 255, 0.08); }
+.viewer-bar button { border: 1px solid rgba(255, 255, 255, 0.18); background: none; color: inherit; font: inherit; border-radius: 999px;
+  padding: 1px 10px; cursor: pointer; }
+.viewer-bar button:hover:not(:disabled) { background: rgba(255, 255, 255, 0.1); }
+.viewer-bar button:disabled { opacity: 0.3; cursor: default; }
+.viewer-name { flex: 1; min-width: 0; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; font-style: italic; }
+.viewer-page { color: inherit; opacity: 0.75; font-size: 13px; text-decoration: none; }
+.viewer-page:hover { opacity: 1; text-decoration: underline; }
+.viewer-frame { flex: 1; border: 0; width: 100%; background: #07080c; }