blockyard 0.0.1 → 0.0.9

package/public/js/tetris.js

@@ -0,0 +1,226 @@
+// TETRUST, the game (operator, 2026-09-12: "a playable tetris game using our 3d Engine ...
+// 'Tetrust' is a play on words for Bitcoiners to always trust and verify").
+//
+// This file is the RULES and nothing else: no DOM, no canvas, no clock. A game is a plain object,
+// every move is a function on it, and the random piece order comes from a seed -- so the whole of
+// it runs under node:test and a board state can be asserted cell by cell. What is drawn (and when)
+// is tetrust.js's business; it asks this file for the tiles and hands them to the 3D engine.
+//
+// Coordinates follow the engine's board: x runs left to right, y runs UP from row 0 on the floor.
+// A piece falls toward y = 0. That is the opposite of most Tetris code, and it is on purpose --
+// the engine draws row 0 at the bottom of the screen, so the rules speak the renderer's language
+// rather than flipping on the way out.
+
+export const COLS = 10;
+export const ROWS = 20;
+
+// Seven pieces, four orientations each, as cells in a 4x4 box (x right, y up). Spelled out rather
+// than rotated by formula: a rotation table is a fact you can read, a matrix is a thing you debug.
+export const PIECES = Object.freeze({
+  I: { color: '#3ec9ff', rot: [[[0, 2], [1, 2], [2, 2], [3, 2]], [[2, 0], [2, 1], [2, 2], [2, 3]], [[0, 1], [1, 1], [2, 1], [3, 1]], [[1, 0], [1, 1], [1, 2], [1, 3]]] },
+  O: { color: '#f5d142', rot: [[[1, 1], [2, 1], [1, 2], [2, 2]], [[1, 1], [2, 1], [1, 2], [2, 2]], [[1, 1], [2, 1], [1, 2], [2, 2]], [[1, 1], [2, 1], [1, 2], [2, 2]]] },
+  T: { color: '#b06bff', rot: [[[0, 1], [1, 1], [2, 1], [1, 2]], [[1, 0], [1, 1], [1, 2], [2, 1]], [[0, 1], [1, 1], [2, 1], [1, 0]], [[1, 0], [1, 1], [1, 2], [0, 1]]] },
+  S: { color: '#2ecc8f', rot: [[[1, 2], [2, 2], [0, 1], [1, 1]], [[1, 2], [1, 1], [2, 1], [2, 0]], [[1, 2], [2, 2], [0, 1], [1, 1]], [[1, 2], [1, 1], [2, 1], [2, 0]]] },
+  Z: { color: '#ef5a5a', rot: [[[0, 2], [1, 2], [1, 1], [2, 1]], [[2, 2], [2, 1], [1, 1], [1, 0]], [[0, 2], [1, 2], [1, 1], [2, 1]], [[2, 2], [2, 1], [1, 1], [1, 0]]] },
+  J: { color: '#3b82f6', rot: [[[0, 2], [0, 1], [1, 1], [2, 1]], [[1, 2], [2, 2], [1, 1], [1, 0]], [[0, 1], [1, 1], [2, 1], [2, 0]], [[1, 2], [1, 1], [1, 0], [0, 0]]] },
+  L: { color: '#f7931a', rot: [[[2, 2], [0, 1], [1, 1], [2, 1]], [[1, 2], [1, 1], [1, 0], [2, 0]], [[0, 1], [1, 1], [2, 1], [0, 0]], [[0, 2], [1, 2], [1, 1], [1, 0]]] },
+});
+export const KINDS = Object.keys(PIECES);
+
+// Scoring is the classic table, times the level: the reward for clearing four at once is well
+// over four singles, which is the whole reason to leave a column open and wait for the I.
+export const LINE_SCORE = [0, 100, 300, 500, 800];
+export const LINES_PER_LEVEL = 10;
+
+/** How long a piece rests on a row before gravity takes it down one, at this level. */
+export function gravityMs(level) {
+  // brisk from the first level (operator: "Smaller, faster, playable!"): 700 ms a row at level
+  // one, 65 ms quicker each level, never under 80
+  return Math.max(80, 700 - (level - 1) * 65);
+}
+
+// A small seeded generator, so a game's piece order is reproducible under test.
+function rng(seed) {
+  let s = (seed >>> 0) || 1;
+  return () => { s = (Math.imul(s, 1664525) + 1013904223) >>> 0; return s / 4294967296; };
+}
+
+// THE SEVEN-BAG: every piece once, in a shuffled order, then a fresh bag. It is what keeps a game
+// fair -- no run of five S pieces, and never more than twelve pieces between one I and the next.
+function fillBag(g) {
+  const bag = [...KINDS];
+  for (let i = bag.length - 1; i > 0; i--) { const j = Math.floor(g.rnd() * (i + 1)); [bag[i], bag[j]] = [bag[j], bag[i]]; }
+  g.queue.push(...bag);
+}
+
+export function newGame(seed = Date.now()) {
+  const g = {
+    // board[y][x] = { k: kind, id } | null. Every locked cell carries an ID it keeps as rows
+    // shift down after a clear: the renderer animates a vanished id as a departure (the cleared
+    // line drifting away) and a moved id as a move, so only the cleared cells leave.
+    board: Array.from({ length: ROWS }, () => new Array(COLS).fill(null)),
+    queue: [], rnd: rng(seed), seed,
+    cur: null,            // { kind, rot, x, y }
+    score: 0, lines: 0, level: 1, pieces: 0, nextId: 1,
+    over: false,
+    cleared: [],          // rows cleared by the last lock, for the renderer to celebrate
+    clearedCells: [],     // ...and the cells that were on them: { x, y, k, id }
+  };
+  fillBag(g);
+  spawn(g);
+  return g;
+}
+
+/** The cells a piece occupies at a position and orientation, in board coordinates. */
+export function cellsOf(kind, rot, x, y) {
+  return PIECES[kind].rot[((rot % 4) + 4) % 4].map(([cx, cy]) => [x + cx, y + cy]);
+}
+
+/** True if any cell is outside the well or on a locked block. Above the well counts as blocked. */
+export function collides(g, cells) {
+  for (const [x, y] of cells) {
+    if (x < 0 || x >= COLS || y < 0 || y >= ROWS) return true;
+    if (g.board[y][x]) return true;
+  }
+  return false;
+}
+
+export function spawn(g) {
+  if (g.queue.length < 7) fillBag(g);
+  const kind = g.queue.shift();
+  const cur = { kind, rot: 0, x: 3, y: ROWS - 4 };
+  g.cur = cur;
+  g.pieces++;
+  // GAME OVER is a piece that cannot even appear: the stack has reached the top of the well
+  if (collides(g, cellsOf(kind, 0, cur.x, cur.y))) { g.over = true; g.cur = null; }
+  return cur;
+}
+
+export function peekNext(g) { return g.queue[0]; }
+
+/** Slide left or right; a blocked slide simply does not happen. */
+export function move(g, dx) {
+  if (!g.cur || g.over) return false;
+  const c = g.cur;
+  if (collides(g, cellsOf(c.kind, c.rot, c.x + dx, c.y))) return false;
+  c.x += dx;
+  return true;
+}
+
+/**
+ * Rotate, with WALL KICKS: a rotation that lands in a wall or a block is tried again shifted one
+ * then two cells either way, and one cell down. Without kicks a piece against the wall cannot
+ * turn, which is the single most common "this game feels broken" in a Tetris.
+ */
+export function rotate(g, dir = 1) {
+  if (!g.cur || g.over) return false;
+  const c = g.cur;
+  const rot = (((c.rot + dir) % 4) + 4) % 4;
+  for (const [kx, ky] of [[0, 0], [-1, 0], [1, 0], [-2, 0], [2, 0], [0, -1], [-1, -1], [1, -1]]) {
+    if (!collides(g, cellsOf(c.kind, rot, c.x + kx, c.y + ky))) { c.rot = rot; c.x += kx; c.y += ky; return true; }
+  }
+  return false;
+}
+
+/** Where the piece would come to rest if dropped: the row the ghost is drawn on. */
+export function ghostY(g) {
+  if (!g.cur) return null;
+  const c = g.cur;
+  let y = c.y;
+  while (!collides(g, cellsOf(c.kind, c.rot, c.x, y - 1))) y--;
+  return y;
+}
+
+/** The piece kind at a cell, or null. */
+export function kindAt(g, x, y) { return g.board[y]?.[x]?.k ?? null; }
+
+function lock(g) {
+  const c = g.cur;
+  for (const [x, y] of cellsOf(c.kind, c.rot, c.x, c.y)) g.board[y][x] = { k: c.kind, id: g.nextId++ };
+  // LINES: every full row goes, and everything above it comes down one
+  const full = [];
+  for (let y = 0; y < ROWS; y++) if (g.board[y].every(Boolean)) full.push(y);
+  // the cells of the lines, kept for the screen: they DRIFT UP AND AWAY (tetrust.js) while the
+  // rows above come down, so the board here has already forgotten them
+  g.clearedCells = full.flatMap((y) => g.board[y].map((cell, x) => ({ x, y, k: cell.k, id: cell.id })));
+  for (const y of [...full].reverse()) { g.board.splice(y, 1); g.board.push(new Array(COLS).fill(null)); }
+  g.cleared = full;
+  if (full.length) {
+    g.lines += full.length;
+    g.score += LINE_SCORE[full.length] * g.level;
+    g.level = 1 + Math.floor(g.lines / LINES_PER_LEVEL);
+  }
+  spawn(g);
+}
+
+/** One step of gravity. Returns true if the piece locked (and so the board changed shape). */
+export function tick(g) {
+  if (!g.cur || g.over) return false;
+  const c = g.cur;
+  if (!collides(g, cellsOf(c.kind, c.rot, c.x, c.y - 1))) { c.y--; g.cleared = []; return false; }
+  lock(g);
+  return true;
+}
+
+/** Soft drop: one row down now, and a point for it. */
+export function softDrop(g) {
+  if (!g.cur || g.over) return false;
+  const c = g.cur;
+  if (collides(g, cellsOf(c.kind, c.rot, c.x, c.y - 1))) { lock(g); return true; }
+  c.y--; g.score += 1; g.cleared = [];
+  return false;
+}
+
+/** Hard drop: straight to the floor, two points a row, and lock. */
+export function hardDrop(g) {
+  if (!g.cur || g.over) return 0;
+  const c = g.cur;
+  const y = ghostY(g);
+  const fell = c.y - y;
+  c.y = y;
+  g.score += 2 * fell;
+  lock(g);
+  return fell;
+}
+
+/**
+ * The board as tiles for the 3D engine (board3d): every locked cell a stone in its piece's
+ * colour, the falling piece standing a little taller, and its GHOST -- where it will land -- as a
+ * thin dim plate on the floor. Ids are positional for the stack and fixed for the piece, so the
+ * renderer sees a still board that changes, not a board that reshuffles.
+ */
+// medium neon blue (operator, 2026-09-12: first "neon yellow wireframes", then "maybe medium neon
+// blue at the bottom instead of bright neon yellow for tetrust block landing locations")
+// The default. The colour is the CALLER's to choose (operator, 2026-09-12: "I want to be able to
+// set the ghost wireframe color") -- this file stays pure and knows nothing of the settings store.
+export const GHOST_WIRE = '#3d8bff';
+
+export function tiles(g, wire = GHOST_WIRE) {
+  const out = [];
+  for (let y = 0; y < ROWS; y++) for (let x = 0; x < COLS; x++) {
+    const cell = g.board[y][x];
+    if (cell) out.push({ txid: `c${cell.id}`, x, y, s: 1, tall: 1, color: PIECES[cell.k].color });
+  }
+  if (g.cur && !g.over) {
+    const c = g.cur;
+    const gy = ghostY(g);
+    if (gy !== c.y) {
+      // THE GHOST IS A WIREFRAME (operator, 2026-09-12: "wireframes on teh bottom of the tetrust
+      // playfield, to show where the pieces are going to drop. The solid dark colored stuff is
+      // too difficult to see"): the outline of a full cube, no fill, in a colour nothing else on
+      // the board uses
+      cellsOf(c.kind, c.rot, c.x, gy).forEach(([x, y], i) => out.push({ txid: `g${i}`, x, y, s: 1, tall: 1, color: PIECES[c.kind].color, wire }));
+    }
+    // the falling piece carries the ids its cells will get when it locks (lock() hands them out in
+    // cellsOf order from nextId), so locking is the same four tiles settling, not four vanishing
+    // and four appearing
+    cellsOf(c.kind, c.rot, c.x, c.y).forEach(([x, y], i) => out.push({ txid: `c${g.nextId + i}`, x, y, s: 1, tall: 1.18, color: PIECES[c.kind].color, piece: true }));
+  }
+  return out;
+}
+
+/** The next piece alone, centred in a 4x4 box, for the preview. */
+export function previewTiles(kind) {
+  if (!kind) return [];
+  return cellsOf(kind, 0, 0, 0).map(([x, y], i) => ({ txid: `n${i}`, x, y, s: 1, tall: 1, color: PIECES[kind].color }));
+}

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();
+}