blockyard 0.0.1 → 0.1.0

package/public/js/tetrust.js

@@ -0,0 +1,356 @@
+// TETRUST, the tab (operator, 2026-09-12: "Add a new tab called 'Tetrust' - I want it to be a
+// playable tetris game using our 3d Engine. Pauses when you tab away, and has a Resume play
+// button. Make the Tetris game absolutely beautiful leveraging our framework ... Add score. Add a
+// high score table").
+//
+// The rules live in tetris.js and know nothing of the screen. This file is the screen: the well
+// is the same board3d the Markets and Block space boards use, with the same oblique camera and
+// the same domed board ("Make it spherical like our default display"), and the panel behind it is
+// the same sky (drawSky). The game inherits the framework rather than imitating it.
+import { board3d } from './details3d.js';
+import { newGame, tick, move, rotate, softDrop, hardDrop, tiles, previewTiles, peekNext, gravityMs, PIECES, COLS, ROWS } from './tetris.js';
+import { loadSettings, setSetting, tetrustOptions } from './settings.js';
+import * as sound from './tetsound.js';
+
+const SCORES_KEY = 'blockyard.tetrust.scores';
+const KEEP = 10;
+
+// the well's camera: the Block space look (an oblique board, cubes with height, the sphere) on a
+// tall well. `still` so a key press lands where you pressed it; no idle effects while playing.
+const WELL = {
+  gridW: COLS, gridH: ROWS,
+  oblique: { ox: 0.10, oy: 0.30, headroom: 3, flight: 0 },
+  dome: 5,                              // the default board's sphere (operator: "spherical like our default display")
+  light: 'overhead',                    // the lamp straight above, so the bottom rows are not in the dome's shade
+  gridStep: 1,
+  space: true,
+  background: 'rgba(0,0,0,0)',          // clear: the panel's sky shows through ("Fill the entire panel with black")
+  spaceFloor: 'rgba(0,0,0,0.22)',       // and through the board itself ("The playfield needs to be transparent to show the stars and galaxy behind it")
+  neonCell: 'rgba(60,200,140,0.18)',
+};
+const PREVIEW = { gridW: 4, gridH: 4, oblique: { ox: 0.10, oy: 0.30, headroom: 2, flight: 0 }, dome: 0, gridStep: 1, space: false, background: 'rgba(0,0,0,1)', grid: false };
+
+// THE SKY (operator: "Have this entire panel filled black and rendering the spiral galaxy for this
+// display. Have the text floating over the spiral galaxy, and then the playboard gets drawn when
+// you hit play"): the panel's own canvas behind the title and the well, an empty board with no
+// floor and no grid -- so nothing but black and the star field -- carrying the game's switches
+// for the sky and the galaxy and the display's choices for what the sky is made of. Its own
+// canvas, so the game's every-key-press repaint of the well never touches a star.
+// `maxDpr: 1`: the sky is drawn at one device pixel per CSS pixel whatever the screen has. The
+// star count follows the pixel count, so on a 2x screen that is a quarter of the stars a frame --
+// and a panel-sized galaxy at 2x made the game stutter ("The galaxy rendering is really slow in
+// teh game display. smooth that shit out"). Stars are points; nobody can tell.
+// `still` here means only that the (nonexistent) tiles never fly: render3d keeps the loop alive
+// for the stars themselves, which is what turns the galaxy.
+const SKY = { gridW: COLS, gridH: ROWS, oblique: { ox: 0.10, oy: 0.30, headroom: 3, flight: 0 }, dome: 0, space: false, grid: false, background: 'rgba(0,0,0,1)', idleFx: false, shadows: false, still: true, transition: { rise: 0, travel: 1, drop: 0 }, maxDpr: 1 };
+
+// THE DRIFT (operator: "have the block pieces drift up and away and completing lines", then
+// "have teh blocks fly up off the screen entirely. Not dissapear just above the playfield"): a
+// cleared line's cells launch off the board -- gathering speed, full colour all the way -- and
+// leave through the top of the canvas
+const DRIFT_MS = 1100;
+const DRIFT_RISE = 80;                  // units of height at the end: well past the canvas top from any row
+
+const G = {
+  game: null, running: false, paused: false, why: '', raf: null, last: 0, acc: 0, dirty: true, bound: false,
+  state: null, h: null, nextKind: undefined,
+  drift: [],                            // { id, x, y, color, dx, t0 } cells on their way up
+};
+
+function opts(base) {
+  // FAST AND PLAIN (operator, 2026-09-12: "the movement is way too slow. We need to stop all
+  // effects, and just treat the blocks differently ... Smaller, faster, playable! No effects for
+  // in-motion blocks"). The first cut inherited every display setting, and a forty-thousand-star
+  // galaxy behind a 2.4-megapixel well is not a game. The well draws the well and -- only when
+  // the game's own switch says so -- the sky behind it: no idle effects, no shadows, flat cubes
+  // with their edges, no finishes on the pieces, and every move lands at once.
+  const t = tetrustOptions(loadSettings());
+  return {
+    ...base,
+    // `space: true` is the plain translucent floor (no deck texture, no dots). The first cut had
+    // space off and got the textured deck back, and its per-cell neon glow turned the well into a
+    // loud green lattice: the glow and the halo are silenced here, and the grid is a quiet line.
+    space: true, idleFx: false, shadows: false,
+    hover: false,                           // a playfield does not light up under the pointer
+    // no sky on the well itself: the sky is the panel's canvas behind it (drawSky)
+    stars: false, galaxy: false,
+    // the grid is the operator's now (settings tetrust.grid and its colour and intensity rows).
+    // The glow and the halo stay silenced: a lit lattice under the stack is noise, not a board.
+    ...t.gridOpts, grid: t.grid,
+    edges: true, facetPx: Infinity, crownPx: Infinity, sheen: false,
+    // neon on the pieces is the game's own switch (settings tetrust.neon and its colour rows)
+    neon: t.neon, neonSource: t.neonSource, neonColour: t.neonColour, neonBrightness: t.neonBrightness,
+    wireWidth: t.ghostWidth,
+    // STILL: drawn as laid, no choreography at all. A transition of zero was not enough -- the
+    // planner's per-tile stagger (seconds between one cube's drop and the next) still applied,
+    // and a piece's four cells came down one after another instead of as one shape.
+    still: true,
+    transition: { rise: 0, travel: 1, drop: 0 },
+  };
+}
+
+// ------------------------------------------------------------------ scores, this browser's
+export function loadScores(storage = globalThis.localStorage) {
+  try {
+    const raw = storage?.getItem(SCORES_KEY);
+    const list = raw ? JSON.parse(raw) : [];
+    return Array.isArray(list) ? list.filter((r) => r && Number.isFinite(r.score)).slice(0, KEEP) : [];
+  } catch { return []; }
+}
+export function recordScore(entry, storage = globalThis.localStorage) {
+  const list = [...loadScores(storage), { score: entry.score, lines: entry.lines, level: entry.level, at: entry.at ?? Date.now() }]
+    .sort((a, b) => b.score - a.score || b.lines - a.lines)
+    .slice(0, KEEP);
+  try { storage?.setItem(SCORES_KEY, JSON.stringify(list)); } catch { /* private mode, quota */ }
+  return list;
+}
+/** Where a score would land in the table, 1-based, or null if it would not make it. */
+export function rankOf(score, list) {
+  const i = list.findIndex((r) => score > r.score);
+  if (i >= 0) return i + 1;
+  return list.length < KEEP ? list.length + 1 : null;
+}
+
+// ------------------------------------------------------------------ the drift
+/**
+ * The tiles of the cells on their way up, at `now`: each rises on an ease-out, slides a little
+ * to its own side, and darkens to the black behind it. The engine's still plan pins z and alpha
+ * (a still board is a still board), so the rise is the tile's FLOOR and the fade is its colour.
+ */
+export function driftTiles(drift, now, ms = DRIFT_MS) {
+  const out = [];
+  for (const d of drift) {
+    const t = Math.min(1, Math.max(0, (now - d.t0) / ms));
+    if (t >= 1) continue;
+    const e = t * t * (3 - 2 * t) * 0.35 + t * t * 0.65;   // a launch: slow off the board, then away
+    const k = t < 0.85 ? 1 : 1 - (t - 0.85) / 0.15;     // full colour until the last stretch, off screen by then
+    out.push({ txid: `d${d.id}`, x: d.x + d.dx * e, y: d.y, s: 1, tall: 1, floor: DRIFT_RISE * e, color: fade(d.color, k) });
+  }
+  return out;
+}
+function fade(hex, k) {
+  const h = hex.replace('#', '');
+  const ch = (i) => Math.round(parseInt(h.slice(i, i + 2), 16) * k);
+  return `#${[ch(0), ch(2), ch(4)].map((v) => Math.max(0, Math.min(255, v)).toString(16).padStart(2, '0')).join('')}`;
+}
+function startDrift(cells, now) {
+  for (const c of cells) G.drift.push({ id: c.id, x: c.x, y: c.y, color: PIECES[c.k].color, dx: (c.x - (COLS - 1) / 2) * 0.12, t0: now });
+}
+
+// ------------------------------------------------------------------ the screen
+const el = (id) => document.getElementById(id);
+
+function overlay(msg, sub, button, dim = false) {
+  const ov = el('tetOver'), m = el('tetMsg'), s = el('tetSub'), b = el('tetResume');
+  if (!ov) return;
+  ov.classList.toggle('hidden', !msg);
+  ov.classList.toggle('dim', dim);      // clear over the sky; dimmed over a held or finished board
+  if (m) m.textContent = msg ?? '';
+  if (s) s.textContent = sub ?? '';
+  if (b) b.textContent = button ?? 'play';
+}
+
+function drawStats() {
+  const g = G.game, box = el('tetStats');
+  if (!box) return;
+  const rows = g
+    ? [['score', g.score.toLocaleString()], ['lines', String(g.lines)], ['level', String(g.level)], ['pieces', String(g.pieces)], ['gravity', `${gravityMs(g.level)} ms`]]
+    : [['score', '–'], ['lines', '–'], ['level', '–']];
+  const html = rows.map(([k, v]) => `<i>${k}</i><b>${v}</b>`).join('');
+  if (box.innerHTML !== html) box.innerHTML = html;
+}
+
+function drawScores(highlightAt = null) {
+  const t = el('tetScores');
+  if (!t) return;
+  const list = loadScores();
+  const html = list.length
+    ? `<tr><th>#</th><th>score</th><th>lines</th><th>lvl</th><th>when</th></tr>` + list.map((r, i) =>
+      `<tr${r.at === highlightAt ? ' class="now"' : ''}><td>${i + 1}</td><td>${r.score.toLocaleString()}</td><td>${r.lines}</td><td>${r.level}</td><td>${new Date(r.at).toISOString().slice(0, 10)}</td></tr>`).join('')
+    : `<tr><td class="faint">no verified blocks yet — clear a line</td></tr>`;
+  if (t.innerHTML !== html) t.innerHTML = html;
+}
+
+// THE GAME'S OWN SWITCHES (operator: "Toggle for each in the game display"): three buttons on the
+// HUD, the same settings the Display panel shows, so a flip in either place is a flip in both
+const SWITCHES = [['tetStars', 'stars'], ['tetGalaxy', 'galaxy'], ['tetMusic', 'music'], ['tetSfx', 'sfx']];
+function drawSwitches() {
+  const t = tetrustOptions(loadSettings());
+  for (const [id, key] of SWITCHES) {
+    const b = el(id);
+    if (!b) continue;
+    b.classList.toggle('on', !!t[key]);
+    b.setAttribute('aria-pressed', t[key] ? 'true' : 'false');
+  }
+  applySound(t);
+}
+function applySound(t) {
+  sound.setSfx(t.sfx);
+  // the tune plays while the game runs; a pause holds it; the switch off stops it
+  sound.setMusic(t.music && G.running && !G.paused);
+}
+function flip(key) {
+  const cur = tetrustOptions(loadSettings())[key];
+  setSetting(loadSettings(), `tetrust.${key}`, !cur);
+  sound.unlock();
+  drawSwitches();
+  if (key === 'stars' || key === 'galaxy') drawSky();
+  G.dirty = true;
+  if (!G.running || G.paused) draw();
+}
+
+function drawSky() {
+  const sky = el('tetSky');
+  if (!sky) return;
+  const t = tetrustOptions(loadSettings());
+  board3d(sky, [], {
+    ...SKY,
+    stars: t.stars, galaxy: t.stars && t.galaxy, galaxyAt: t.galaxyAt,
+    starDensity: t.starDensity, starBrightness: t.starBrightness,
+    nebulae: t.nebulae, galaxies: t.galaxies, dust: t.dust, clusters: t.clusters, starColours: t.starColours, starGlints: t.starGlints,
+  });
+}
+
+function draw(now = performance.now()) {
+  const g = G.game;
+  const well = el('tetWell');
+  el('tetWellWrap')?.classList.toggle('idle', !g);
+  // the board is drawn when you hit play: `.tetwell.idle` is visibility:hidden, so an idle well is
+  // off screen and painting it would be a board3d pass for nothing
+  if (well && g) board3d(well, [...tiles(g, tetrustOptions(loadSettings()).ghostColour), ...driftTiles(G.drift, now)], opts(WELL));
+  // the preview only when the next piece changes: it is a second board, and redrawing it on
+  // every key press was paying for two scenes per move
+  const nk = g ? peekNext(g) : null;
+  if (nk !== G.nextKind) {
+    G.nextKind = nk;
+    const nx = el('tetNext');
+    if (nx) board3d(nx, previewTiles(nk), opts({ ...PREVIEW, stars: false }));
+  }
+  drawStats();
+}
+
+// ------------------------------------------------------------------ the loop
+function frame(t) {
+  G.raf = null;
+  if (!G.running) return;
+  // PAUSE WHEN YOU LOOK AWAY: another browser tab, or another tab of this app. A game that keeps
+  // falling while you read the Mempool page is a game you come back to lost.
+  if (document.hidden || G.state?.page !== 'tetrust') { pause(document.hidden ? 'paused — you looked away' : 'paused — you changed tabs'); return; }
+  const dt = G.last ? Math.min(250, t - G.last) : 0;
+  G.last = t;
+  G.acc += dt;
+  const g = G.game;
+  const ms = gravityMs(g.level);
+  const levelBefore = g.level;
+  while (G.acc >= ms && !g.over) { G.acc -= ms; if (tick(g)) { G.dirty = true; afterLock(g, t); } else G.dirty = true; }
+  if (g.level > levelBefore) sound.play('level');
+  if (g.over) { gameOver(); return; }
+  // the drift keeps the loop drawing until the last cell has gone
+  if (G.drift.length) {
+    G.drift = G.drift.filter((d) => t - d.t0 < DRIFT_MS);
+    G.dirty = true;
+  }
+  if (G.dirty) { draw(t); G.dirty = false; }
+  G.raf = requestAnimationFrame(frame);
+}
+
+// what happens when a piece locks: the sound of it, and the lines it made leaving
+function afterLock(g, now) {
+  if (g.cleared?.length) {
+    startDrift(g.clearedCells ?? [], now);
+    sound.play(g.cleared.length >= 4 ? 'tetris' : 'clear');
+    g.cleared = []; g.clearedCells = [];
+  } else sound.play('lock');
+}
+
+function start() {
+  G.game = newGame();
+  G.drift = [];
+  G.running = true; G.paused = false; G.acc = 0; G.last = 0; G.dirty = true;
+  overlay(null);
+  drawScores();
+  sound.unlock();
+  drawSwitches();
+  if (!G.raf) G.raf = requestAnimationFrame(frame);
+}
+
+function pause(why) {
+  if (!G.running || G.paused) return;
+  G.paused = true; G.why = why;
+  overlay(why, 'the stack is holding', 'resume', true);
+  sound.holdMusic(true);
+  G.h?.toast?.(why);
+}
+
+function resume() {
+  if (!G.running) { start(); return; }
+  if (!G.paused) return;
+  G.paused = false; G.last = 0; G.dirty = true;
+  overlay(null);
+  sound.unlock();
+  sound.holdMusic(false);
+  if (!G.raf) G.raf = requestAnimationFrame(frame);
+}
+
+function gameOver() {
+  const g = G.game;
+  G.running = false; G.paused = false;
+  sound.setMusic(false);
+  sound.play('over');
+  draw();
+  const list = loadScores();
+  const rank = rankOf(g.score, list);
+  const at = Date.now();
+  if (rank) recordScore({ score: g.score, lines: g.lines, level: g.level, at });
+  drawScores(rank ? at : null);
+  overlay(
+    `verified ${g.lines} line${g.lines === 1 ? '' : 's'}`,
+    `${g.score.toLocaleString()} points at level ${g.level}${rank ? ` — #${rank} on this browser` : ''}. Trust, but verify.`,
+    'play again',
+    true,
+  );
+}
+
+// ------------------------------------------------------------------ input
+function onKey(e) {
+  if (G.state?.page !== 'tetrust') return;
+  const tag = e.target?.tagName;
+  if (tag === 'INPUT' || tag === 'TEXTAREA' || tag === 'SELECT') return;
+  if (e.key === 'Enter') { e.preventDefault(); resume(); return; }
+  if (e.key === 'p' || e.key === 'P' || e.key === 'Escape') { if (G.running) { e.preventDefault(); G.paused ? resume() : pause('paused'); } return; }
+  if (!G.running || G.paused || !G.game || G.game.over) return;
+  const g = G.game;
+  let used = true;
+  // arrows or WASD (operator: "Add WASD for tetris controls as well")
+  switch (e.key) {
+    case 'ArrowLeft': case 'a': case 'A': if (move(g, -1)) sound.play('move'); break;
+    case 'ArrowRight': case 'd': case 'D': if (move(g, 1)) sound.play('move'); break;
+    case 'ArrowUp': case 'w': case 'W': case 'x': case 'X': if (rotate(g, 1)) sound.play('rotate'); break;
+    case 'z': case 'Z': case 'q': case 'Q': if (rotate(g, -1)) sound.play('rotate'); break;
+    case 'ArrowDown': case 's': case 'S': if (softDrop(g)) afterLock(g, performance.now()); else sound.play('soft'); break;
+    case ' ': hardDrop(g); sound.play('drop'); afterLock(g, performance.now()); break;
+    default: used = false;
+  }
+  if (used) { e.preventDefault(); G.dirty = true; if (g.over) gameOver(); }
+}
+
+function bind() {
+  if (G.bound) return;
+  G.bound = true;
+  document.addEventListener('keydown', onKey);
+  document.addEventListener('visibilitychange', () => { if (document.hidden && G.running && !G.paused) pause('paused — you looked away'); });
+  el('tetResume')?.addEventListener('click', () => resume());
+  for (const [id, key] of SWITCHES) el(id)?.addEventListener('click', () => flip(key));
+}
+
+export function renderTetrust(s, state, h) {
+  G.state = state; G.h = h;
+  bind();
+  drawSwitches();
+  drawSky();
+  if (!G.game) { overlay('Tetrust', 'trust, but verify — every line you clear is a block you verified. Enter or the button to play; arrows move, ↑ rotates, space drops.', 'play'); drawStats(); drawScores(); draw(); return; }
+  if (G.running && G.paused) overlay(G.why, 'the stack is holding', 'resume', true);
+  // a render while we are the page and not paused: keep the loop alive
+  if (G.running && !G.paused && !G.raf) { G.last = 0; G.raf = requestAnimationFrame(frame); }
+  else G.dirty = true, draw();
+}

package/public/js/tetsound.js

@@ -0,0 +1,175 @@
+// TETRUST SOUND (operator, 2026-09-12: "We need to add Tetris music and sound effects to teh
+// gameplay. Toggle for each in the game display").
+//
+// No files and no dependencies, so everything here is SYNTHESISED with the Web Audio API: the
+// music is a note table played on oscillators, the effects are short shaped tones. The tune is
+// Korobeiniki, the Russian folk song everyone knows as the Tetris theme -- public domain, older
+// than any game. A browser lets audio start only on a gesture, so the context is made lazily on
+// the first play or key press, and nothing here throws where there is no AudioContext at all
+// (tests, or a browser with audio blocked): every call is a no-op then.
+
+const HZ = { A4: 440, B4: 493.88, C5: 523.25, D5: 587.33, E5: 659.25, F5: 698.46, G5: 783.99, A5: 880, GS4: 415.3, E4: 329.63, R: 0 };
+
+// Korobeiniki, A minor, one verse: [note, beats]
+export const THEME = Object.freeze([
+  ['E5', 1], ['B4', 0.5], ['C5', 0.5], ['D5', 1], ['C5', 0.5], ['B4', 0.5],
+  ['A4', 1], ['A4', 0.5], ['C5', 0.5], ['E5', 1], ['D5', 0.5], ['C5', 0.5],
+  ['B4', 1.5], ['C5', 0.5], ['D5', 1], ['E5', 1],
+  ['C5', 1], ['A4', 1], ['A4', 1], ['R', 1],
+  ['D5', 1.5], ['F5', 0.5], ['A5', 1], ['G5', 0.5], ['F5', 0.5],
+  ['E5', 1.5], ['C5', 0.5], ['E5', 1], ['D5', 0.5], ['C5', 0.5],
+  ['B4', 1], ['B4', 0.5], ['C5', 0.5], ['D5', 1], ['E5', 1],
+  ['C5', 1], ['A4', 1], ['A4', 1], ['R', 1],
+]);
+export const BPM = 148;
+
+// the effects: [frequency from, frequency to, seconds, wave, gain]
+export const SFX = Object.freeze({
+  move: [520, 520, 0.045, 'square', 0.05],
+  rotate: [780, 980, 0.06, 'square', 0.05],
+  soft: [300, 300, 0.03, 'triangle', 0.04],
+  drop: [160, 70, 0.11, 'sawtooth', 0.09],
+  lock: [220, 180, 0.07, 'triangle', 0.06],
+  clear: [420, 1320, 0.28, 'square', 0.08],
+  tetris: [330, 1760, 0.45, 'square', 0.1],
+  over: [440, 90, 0.7, 'sawtooth', 0.09],
+  level: [660, 1320, 0.22, 'triangle', 0.07],
+  // BLOCKOUT (breakout.js): the bat is a low knock, a brick a short blip -- higher for the dear
+  // rows -- a wall a duller tap, and a lost ball a drop. The module is the games' sound, not
+  // Tetrust's alone; both set `sfx` from their own switch as they render, and only one plays at a
+  // time because only one tab is on screen.
+  // PING AND PONG (operator, 2026-09-12: "make sure to have distinct 'Ping' and 'Pong' sounds like
+  // Arkanoid does for the paddle and block impacts"). They were 300 Hz and 680 Hz, both falling
+  // square blips -- close enough in timbre that with the ball moving you could not tell which had
+  // happened without looking. Now they are opposite in every dimension a listener actually uses:
+  //
+  //   PONG (bat)    low, and it FALLS     -- a soft wooden knock under you
+  //   PING (brick)  high, and it RISES    -- a bright strike up at the wall
+  //
+  // Pitch alone is a weak cue on small speakers; the direction of the sweep survives them.
+  paddle: [200, 150, 0.075, 'triangle', 0.075],
+  brick: [1046, 1245, 0.042, 'square', 0.05],
+  brickhard: [1396, 1760, 0.05, 'square', 0.055],
+  wall: [420, 400, 0.04, 'triangle', 0.04],
+  life: [320, 90, 0.42, 'sawtooth', 0.08],
+  levelup: [520, 1180, 0.3, 'triangle', 0.07],
+  // BLOCKANOID (arkanoid.js): a silver brick RINGS rather than breaks and gold rings harder and
+  // lower, so the ear learns which bricks are worth hitting before the eye does. A capsule is a
+  // rising chime (it is always good news), the laser a short zap, a minion a dull pop.
+  silver: [560, 620, 0.06, 'triangle', 0.055],
+  gold: [240, 210, 0.07, 'square', 0.05],
+  capsule: [620, 1560, 0.22, 'triangle', 0.075],
+  laser: [1200, 420, 0.05, 'sawtooth', 0.045],
+  enemy: [380, 140, 0.12, 'sawtooth', 0.06],
+});
+
+const S = { ctx: null, music: false, sfx: false, timer: null, at: 0, i: 0, gain: null, live: new Set() };
+
+function context() {
+  if (S.ctx) return S.ctx;
+  const AC = globalThis.AudioContext || globalThis.webkitAudioContext;
+  if (!AC) return null;
+  try {
+    S.ctx = new AC();
+    S.gain = S.ctx.createGain();
+    S.gain.gain.value = 0.9;
+    S.gain.connect(S.ctx.destination);
+  } catch { S.ctx = null; }
+  return S.ctx;
+}
+
+/** Call on a user gesture: a suspended context (autoplay policy) is resumed here. */
+export function unlock() {
+  const c = context();
+  if (c && c.state === 'suspended') c.resume().catch(() => {});
+}
+
+function tone(freqFrom, freqTo, secs, wave, gain, at = null) {
+  const c = context();
+  if (!c) return;
+  const t0 = at ?? c.currentTime;
+  const o = c.createOscillator(), g = c.createGain();
+  o.type = wave;
+  o.frequency.setValueAtTime(freqFrom, t0);
+  if (freqTo !== freqFrom) o.frequency.exponentialRampToValueAtTime(Math.max(1, freqTo), t0 + secs);
+  g.gain.setValueAtTime(0.0001, t0);
+  g.gain.exponentialRampToValueAtTime(gain, t0 + 0.008);
+  g.gain.exponentialRampToValueAtTime(0.0001, t0 + secs);
+  o.connect(g); g.connect(S.gain);
+  o.start(t0); o.stop(t0 + secs + 0.02);
+  // remembered until it has played, so a stop (pause, switch off) can cut what was scheduled
+  // ahead rather than letting a second and a half of tune run on
+  S.live.add(o);
+  o.onended = () => S.live.delete(o);
+}
+function hush() {
+  for (const o of S.live) { try { o.stop(); } catch { /* already stopped */ } }
+  S.live.clear();
+}
+
+/** One sound effect, if effects are on. */
+export function play(name) {
+  if (!S.sfx) return;
+  const d = SFX[name];
+  if (!d) return;
+  tone(d[0], d[1], d[2], d[3], d[4]);
+}
+
+export function setSfx(on) { S.sfx = !!on; }
+
+// THE MUSIC: a lookahead scheduler. Every 200 ms it schedules whatever notes fall in the next
+// 1.5 s, on the AUDIO clock (absolute times), so the tune keeps its tempo however late the page's
+// timers run -- and they run late: a galaxy repaint or a well repaint can hold the main thread
+// well past a timer. The first cut looked 250 ms ahead on a 90 ms timer and stuttered whenever a
+// frame took longer than that ("the music is glitching out and not playing at a steady state").
+// A stop takes at most the lookahead to fall silent, which a pause can afford. Melody on a square
+// wave, the same note an octave down on a soft triangle underneath.
+// (second cut, same day: "The song wobbles and is not consistent ... lock that shit down". The
+// wobble was not the lookahead: the HUD redraw called setMusic(true) on every app render, and
+// each call restarted the scheduler from "now" over the notes already queued -- so the tune
+// stuttered on itself every few seconds. setMusic is idempotent now, and the lookahead is a
+// generous four seconds: the notes are on the audio thread's clock the moment they are queued,
+// and nothing the page does after that can move them.)
+const LOOKAHEAD_S = 4;
+const TIMER_MS = 500;
+function schedule() {
+  const c = S.ctx;
+  if (!c || !S.music) return;
+  const beat = 60 / BPM;
+  // fallen behind (the tab was hidden, the thread was held): pick the tune up from now rather
+  // than cramming the missed notes into an instant
+  if (S.at < c.currentTime - 0.05) S.at = c.currentTime + 0.02;
+  while (S.at < c.currentTime + LOOKAHEAD_S) {
+    const [name, beats] = THEME[S.i % THEME.length];
+    const dur = beats * beat;
+    const hz = HZ[name] ?? 0;
+    if (hz > 0) {
+      tone(hz, hz, dur * 0.88, 'square', 0.045, S.at);
+      tone(hz / 2, hz / 2, dur * 0.88, 'triangle', 0.03, S.at);
+    }
+    S.at += dur;
+    S.i++;
+  }
+  S.timer = setTimeout(schedule, TIMER_MS);
+}
+
+export function setMusic(on) {
+  const want = !!on;
+  if (want === S.music && (!want || S.timer)) return;    // already so: never restart a running tune
+  S.music = want;
+  if (S.timer) { clearTimeout(S.timer); S.timer = null; }
+  if (!S.music) { hush(); return; }
+  const c = context();
+  if (!c) return;
+  if (c.state === 'suspended') c.resume().catch(() => {});
+  S.at = c.currentTime + 0.05;
+  schedule();
+}
+
+/** Hold the tune (a pause): the scheduler stops, the place in the tune is kept. */
+export function holdMusic(hold) {
+  if (hold) { if (S.timer) { clearTimeout(S.timer); S.timer = null; } hush(); return; }
+  if (S.music && !S.timer && S.ctx) { S.at = S.ctx.currentTime + 0.05; schedule(); }
+}
+
+export function state() { return { music: S.music, sfx: S.sfx, live: !!S.ctx }; }