blockyard 0.0.1 → 0.0.9

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

package/public/login.html

@@ -0,0 +1,33 @@
+<!doctype html>
+<html lang="en" data-blockyard-build="%BLOCKYARD_BUILD%">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<meta name="referrer" content="no-referrer">
+<title>sign in - BlockYard</title>
+<link rel="stylesheet" href="/css/app.css">
+<link rel="icon" href="data:image/svg+xml,%3Csvg%20xmlns%3D%22http%3A%2F%2Fwww.w3.org%2F2000%2Fsvg%22%20viewBox%3D%220%200%2032%2032%22%3E%3Cdefs%3E%3ClinearGradient%20id%3D%22g%22%20x1%3D%220%22%20y1%3D%220%22%20x2%3D%221%22%20y2%3D%221%22%3E%3Cstop%20offset%3D%220%22%20stop-color%3D%22%23ffb85c%22%2F%3E%3Cstop%20offset%3D%22.55%22%20stop-color%3D%22%23f7931a%22%2F%3E%3Cstop%20offset%3D%221%22%20stop-color%3D%22%23a8640d%22%2F%3E%3C%2FlinearGradient%3E%3C%2Fdefs%3E%3Crect%20width%3D%2232%22%20height%3D%2232%22%20rx%3D%227.5%22%20fill%3D%22url%28%23g%29%22%2F%3E%3Cg%20fill%3D%22%2316110a%22%20opacity%3D%22.14%22%3E%3Crect%20x%3D%224%22%20y%3D%2224.6%22%20width%3D%228%22%20height%3D%223.6%22%20rx%3D%221%22%2F%3E%3Crect%20x%3D%2213%22%20y%3D%2224.6%22%20width%3D%226%22%20height%3D%223.6%22%20rx%3D%221%22%2F%3E%3Crect%20x%3D%2220%22%20y%3D%2224.6%22%20width%3D%228%22%20height%3D%223.6%22%20rx%3D%221%22%2F%3E%3C%2Fg%3E%3Cpath%20fill%3D%22%231a1206%22%20fill-rule%3D%22evenodd%22%20d%3D%22M5%208h6.6a4.2%204.2%200%200%201%202.35%207.66A4.4%204.4%200%200%201%2012%2024H5Zm3.3%202.9v3.5h3.1a1.75%201.75%200%200%200%200-3.5Zm0%206.4v3.8h3.4a1.9%201.9%200%200%200%200-3.8Z%22%2F%3E%3Cpath%20fill%3D%22%231a1206%22%20d%3D%22M16.8%208h3.3l2.75%205.3L25.6%208h3.3l-4.85%208.8V24h-3.3v-7.2Z%22%2F%3E%3C%2Fsvg%3E">
+</head>
+<body class="login-body">
+  <div class="login-card">
+    <h1>Block<b>Yard</b></h1>
+    <p class="sub" id="sub">Bitcoin node monitor</p>
+
+    <div class="err hidden" id="err"></div>
+
+    <form id="f" autocomplete="on">
+      <div class="field">
+        <label for="u">username</label>
+        <input id="u" name="username" autocomplete="username" autocapitalize="none" spellcheck="false" required>
+      </div>
+      <div class="field">
+        <label for="p">password</label>
+        <input id="p" name="password" type="password" autocomplete="current-password" required>
+      </div>
+      <button class="btn primary block" id="go" type="submit">sign in</button>
+    </form>
+    <p class="note tiny faint mt-14" id="hint">Read-only by default. This tool cannot start, stop or reconfigure the node unless the operator has explicitly enabled specific actions.</p>
+  </div>
+  <script type="module" src="/js/login.js"></script>
+</body>
+</html>

package/scripts/blockfile-measure.js

@@ -0,0 +1,156 @@
+#!/usr/bin/env node
+// What would an address index over this node's chain cost? Measured on the node's own files, not
+// estimated from blog posts.
+//
+//   node scripts/blockfile-measure.js [--dir <datadir>/blocks] [--files 0,500,...] [--sample N] [--verify]
+//
+// For each sampled blkNNNNN.dat and its revNNNNN.dat it times, separately: the disk read, the XOR,
+// decoding every block (transactions, output scripts, addresses), pairing each block with its undo
+// record (shape, then Core's checksum), and decoding the undo data (every spent output, with its
+// address). It counts what an index would have to store -- a funding row per spendable output, a
+// spending row per input -- and extrapolates across all files by interpolating between the samples,
+// because file contents change a great deal over the chain's history.
+//
+// --verify also checks one block per sampled file against getblock <hash> 3 (every prevout), so the
+// numbers are never measured on a decoder that is quietly wrong.
+//
+// Read-only: the node's files are opened for reading and nothing else.
+import { openSync, readSync, closeSync, fstatSync, readdirSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import { createHash } from 'node:crypto';
+import { Reader, readHeader, readTx, classifyScript } from '../server/chain/tx.js';
+import { xorKey, unxor, records, decodeBlockUndo, pairBlocksWithUndo, MAGIC } from '../server/chain/blockfile.js';
+
+const arg = (name, def) => { const i = process.argv.indexOf(`--${name}`); return i > 0 ? process.argv[i + 1] : def; };
+const dir = arg('dir', '/storage/core-oracle/blocks');
+const all = readdirSync(dir).filter((f) => /^blk\d{5}\.dat$/.test(f)).sort();
+const last = all.length - 1;
+// the newest file is still being written, so the default sample stops one short of it
+const sample = arg('files', null)
+  ? arg('files').split(',').map(Number)
+  : Array.from({ length: Number(arg('sample', 16)) }, (_, i) => Math.round((i * (last - 1)) / (Number(arg('sample', 16)) - 1)));
+const key = xorKey(dir);
+const verify = process.argv.includes('--verify');
+const ms = (t0) => performance.now() - t0;
+
+let rpcCall = null;
+if (verify) {
+  const { loadConfig } = await import('../server/config.js');
+  const { RpcClient } = await import('../server/rpc/client.js');
+  const cfg = loadConfig();
+  const node = cfg.nodes.find((n) => n.datadir && dir.startsWith(n.datadir)) ?? cfg.nodes[0];
+  const rpc = new RpcClient(node, { ...(cfg.rpc ?? {}), ...(node.rpc ?? {}) }, { log: { info() {}, warn() {}, error() {}, debug() {} } });
+  rpcCall = async (method, params) => {
+    const [r] = await rpc.batch([{ method, params }], { key: `measure:${method}:${params[0]}`, timeoutMs: 600_000, maxWaitMs: 600_000 });
+    if (!r.ok) throw new Error(`${method}: ${r.error?.message}`);
+    return r.result;
+  };
+}
+
+function readRaw(file) {
+  const fd = openSync(file, 'r');
+  try {
+    const size = fstatSync(fd).size;
+    const buf = Buffer.allocUnsafe(size);
+    let got = 0;
+    while (got < size) { const n = readSync(fd, buf, got, size - got, got); if (n === 0) break; got += n; }
+    return buf.subarray(0, got);
+  } finally { closeSync(fd); }
+}
+
+const rows = [];
+for (const n of sample) {
+  const id = String(n).padStart(5, '0');
+  const r = { file: n };
+  let t = performance.now();
+  const blk = readRaw(path.join(dir, `blk${id}.dat`));
+  const rev = readRaw(path.join(dir, `rev${id}.dat`));
+  r.readMs = ms(t); r.blkMB = blk.length / 1e6; r.revMB = rev.length / 1e6;
+  t = performance.now(); unxor(blk, key); unxor(rev, key); r.xorMs = ms(t);
+
+  // blocks: full decode, addresses included (classifyScript runs per output inside readTx)
+  t = performance.now();
+  const blocks = [];
+  let txs = 0, outputs = 0, inputs = 0, funding = 0, height0 = null;
+  const scripts = new Set();
+  for (const rec of records(blk, MAGIC.main)) {
+    const rd = new Reader(rec.body);
+    const header = readHeader(rd);
+    const ntx = rd.varint();
+    const inCounts = [];
+    for (let i = 0; i < ntx; i++) {
+      const tx = readTx(rd);
+      txs++; outputs += tx.vout.length;
+      if (i > 0) { inputs += tx.vin.length; inCounts.push(tx.vin.length); }
+      for (const o of tx.vout) if (o.scriptPubKey.type !== 'nulldata') { funding++; scripts.add(createHash('sha256').update(o.scriptPubKey.hex).digest('base64').slice(0, 11)); }
+    }
+    blocks.push({ header, ntx, inCounts });
+  }
+  r.decodeMs = ms(t);
+  Object.assign(r, { blocks: blocks.length, txs, outputs, inputs, funding, distinctScripts: scripts.size });
+
+  // pair each block with its undo record: tx count first, then Core's checksum
+  t = performance.now();
+  const undos = [...records(rev, MAGIC.main, 32)];
+  const pairs = pairBlocksWithUndo(blocks.map((b) => ({ hash: b.header.hash, previousblockhash: b.header.previousblockhash, ntx: b.ntx })), undos);
+  const paired = [...pairs].map(([i, u]) => [blocks[i], u]);
+  r.pairMs = ms(t); r.paired = paired.length; r.undoRecords = undos.length;
+
+  // undo: every spent coin, with the address its script pays
+  t = performance.now();
+  let spent = 0, special = 0;
+  for (const [, u] of paired) {
+    for (const coins of decodeBlockUndo(u.body)) for (const c of coins) {
+      spent++;
+      classifyScript(c.script);
+      if (c.script.length === 67) special++;       // an uncompressed-key P2PK, rebuilt from 33 bytes
+    }
+  }
+  r.undoMs = ms(t); r.spent = spent; r.p2pkUncompressedSpent = special;
+
+  if (verify && paired.length) {
+    const [b, u] = paired[Math.floor(paired.length / 2)];
+    const want = await rpcCall('getblock', [b.header.hash, 3]);
+    const undo = decodeBlockUndo(u.body);
+    let bad = 0, checked = 0;
+    want.tx.slice(1).forEach((tx, i) => tx.vin.forEach((vin, j) => {
+      const c = undo[i][j]; const p = vin.prevout; checked++;
+      if (c.value_sat !== Math.round(p.value * 1e8) || c.script.toString('hex') !== p.scriptPubKey.hex || c.height !== p.height || c.coinbase !== p.generated) bad++;
+    }));
+    r.verified = { height: want.height, coins: checked, mismatches: bad };
+    height0 = want.height;
+  }
+  rows.push(r);
+  const f = (v, d = 0) => v.toFixed(d);
+  console.log(`blk${id}: ${f(r.blkMB)}+${f(r.revMB)} MB read ${f(r.readMs)} ms, xor ${f(r.xorMs)}, decode ${f(r.decodeMs)}, pair ${f(r.pairMs)}, undo ${f(r.undoMs)} | ${r.blocks} blocks (${r.paired} paired), ${txs} tx, ${outputs} out, ${inputs} in${r.verified ? ` | verified h${r.verified.height}: ${r.verified.coins} coins, ${r.verified.mismatches} mismatches` : ''}${height0 == null ? '' : ''}`);
+}
+
+// extrapolate across every file by linear interpolation between sampled files
+const at = (k, fileNo) => {
+  const s = rows;
+  if (fileNo <= s[0].file) return s[0][k];
+  for (let i = 1; i < s.length; i++) if (fileNo <= s[i].file) {
+    const a = s[i - 1], b = s[i]; const u = (fileNo - a.file) / Math.max(1, b.file - a.file);
+    return a[k] + (b[k] - a[k]) * u;
+  }
+  return s[s.length - 1][k];
+};
+const total = (k) => { let v = 0; for (let fno = 0; fno <= last; fno++) v += at(k, fno); return v; };
+const T = Object.fromEntries(['blkMB', 'revMB', 'readMs', 'xorMs', 'decodeMs', 'pairMs', 'undoMs', 'txs', 'outputs', 'inputs', 'funding', 'spent'].map((k) => [k, total(k)]));
+const h = (x) => (x / 3.6e6).toFixed(2);
+const G = (x) => (x / 1e9).toFixed(2);
+const summary = {
+  files: all.length, sampled: sample.length,
+  data: { blkGB: +(T.blkMB / 1e3).toFixed(1), revGB: +(T.revMB / 1e3).toFixed(1) },
+  counts: { txs: Math.round(T.txs), outputs: Math.round(T.outputs), inputs: Math.round(T.inputs), fundingRows: Math.round(T.funding), spendingRows: Math.round(T.spent) },
+  singleCoreHours: { read: +h(T.readMs), xor: +h(T.xorMs), decodeBlocks: +h(T.decodeMs), pairUndo: +h(T.pairMs), decodeUndo: +h(T.undoMs), cpuTotal: +h(T.xorMs + T.decodeMs + T.pairMs + T.undoMs) },
+  // raw row bytes for two designs, before any storage-engine overhead
+  indexGB: {
+    historyOnly: +G((T.funding + T.spent) * 12),       // script-hash prefix 8 B + height 4 B, and outpoint prefix 8 B + height 4 B
+    withValues: +G((T.funding + T.spent) * 20),        // the same plus an 8 B amount, so a balance needs no node call
+  },
+};
+console.log(JSON.stringify(summary, null, 1));
+const out = arg('json', null);
+if (out) writeFileSync(out, JSON.stringify({ measuredAt: new Date().toISOString(), dir, sample: rows, summary }, null, 1) + '\n');
+process.exit(0);

package/scripts/browser-check.mjs

@@ -0,0 +1,286 @@
+// Look at the page with a real browser, and ask the vision model what it sees.
+//
+// Two kinds of evidence, deliberately kept apart:
+//   HARD   -- pixels sampled in the page by Runtime.evaluate, and element rects. The
+//            canvas is same-origin, so getImageData answers "did anything actually get
+//            painted, and in which colours" without any judgement at all.
+//   SOFT   -- a screenshot handed to the local vision model (qwen3.8 on the bench host).
+//            Good for "does this read as a block being filled", "is the legend legible",
+//            "do these overlap". Bad at precise numbers. Where the two disagree, the
+//            pixels win, and the report says so.
+//
+// Zero dependencies: Chromium speaks CDP over a plain WebSocket, and Node 22 ships one.
+//
+//   BLOCKYARD_BASE=https://<lan>:8088 [BROWSER_CDP=http://127.0.0.1:9333] \
+//   [VISION_BASE=http://198.51.100.20:8888 VISION_MODEL=<model-id>] \
+//     node scripts/browser-check.mjs [overview|mining]
+import { execFileSync } from 'node:child_process';
+
+const BASE = process.env.BLOCKYARD_BASE;
+const CDP = process.env.BROWSER_CDP ?? 'http://127.0.0.1:9333';
+const VISION_BASE = process.env.VISION_BASE;   // the local vision model, e.g. vLLM on the bench host
+const VISION_MODEL = process.env.VISION_MODEL ?? 'qwen3.8-flash-next';
+const PAGE = process.argv[2] ?? 'mining';
+if (!BASE) {
+  console.log('usage: BLOCKYARD_BASE=https://<address>:8088 node scripts/browser-check.mjs [overview|mining]');
+  console.log('       needs a headless chromium with --remote-debugging-port and --ignore-certificate-errors');
+  process.exit(2);
+}
+const URL = `${BASE}/#${PAGE}`;
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+
+// ------------------------------------------------------------------ CDP client
+const targets = JSON.parse(await (await fetch(`${CDP}/json/list`)).text());
+const page = targets.find((t) => t.type === 'page');
+if (!page) { console.log('no page target; is chromium running headless with --remote-debugging-port?'); process.exit(1); }
+
+const ws = new WebSocket(page.webSocketDebuggerUrl);
+await new Promise((res, rej) => { ws.onopen = res; ws.onerror = rej; });
+
+let nextId = 1;
+const pending = new Map();
+const events = [];
+const consoleErrors = [];
+const exceptions = [];
+ws.onmessage = (ev) => {
+  const msg = JSON.parse(ev.data);
+  if (msg.id && pending.has(msg.id)) { pending.get(msg.id)(msg); pending.delete(msg.id); }
+  if (msg.method) {
+    events.push(msg.method);
+    if (msg.method === 'Runtime.exceptionThrown') {
+      exceptions.push(msg.params.exceptionDetails?.exception?.description ?? msg.params.exceptionDetails?.text);
+    }
+    if (msg.method === 'Runtime.consoleAPICalled' && ['error', 'warning'].includes(msg.params.type)) {
+      consoleErrors.push((msg.params.args ?? []).map((a) => a.value ?? a.description ?? a.type).join(' '));
+    }
+    if (msg.method === 'Log.entryAdded' && ['error', 'warning'].includes(msg.params.entry.level)) {
+      consoleErrors.push(`[${msg.params.entry.source}] ${msg.params.entry.text}`.slice(0, 200));
+    }
+  }
+};
+const send = (method, params = {}) => new Promise((res) => {
+  const id = nextId++;
+  pending.set(id, (msg) => res(msg.result ?? msg.error ?? {}));
+  ws.send(JSON.stringify({ id, method, params }));
+});
+
+await send('Page.enable');
+await send('Runtime.enable');
+await send('Log.enable');
+await send('Network.enable');
+await send('Emulation.setDeviceMetricsOverride', { width: 1440, height: 1900, deviceScaleFactor: 1, mobile: false });
+
+const loadWait = new Promise((res) => {
+  const wait = (ev) => { if (ev === 'Page.loadEventFired') res(true); };
+  const orig = ws.onmessage;
+  ws.onmessage = (m) => { orig(m); wait(JSON.parse(m.data).method); };
+  setTimeout(() => res(false), 25_000);
+});
+// Cache-bust deliberately: Page.navigate to a URL that differs from the current one only
+// in its #fragment is a NO-OP, so reusing a still-open browser silently re-measures the
+// document that was loaded before the last deploy. Every "old code path" and "blank
+// canvas" reading this harness ever produced against a warm browser was this.
+//
+// ...and the query-string bust is NOT enough on its own. It changes the
+// DOCUMENT url only; the ES MODULES the document imports keep their own urls,
+// so a warm browser serves them from cache and the harness measures the
+// PREVIOUS build's JavaScript against the current build's HTML. Measured
+// 2026-09-10: the viewer's projection was replaced outright, the server was
+// confirmed to be serving the new file, every unit test agreed -- and the
+// screenshot kept showing the old camera, from a headless shell that had been
+// up 48 hours. Disabling the network cache is what makes this harness
+// trustworthy for a JS change at all.
+await send('Network.enable', {});
+await send('Network.setCacheDisabled', { cacheDisabled: true });
+const busted = URL + (URL.includes('?') ? '&' : '?') + 't=' + Date.now();
+await send('Page.navigate', { url: busted });
+const loaded = await loadWait;
+// A document can load and still not be the app (a redirect to the login page loads
+// perfectly well). Assert the shell is here before judging anything drawn inside it.
+// NOTE what this does NOT check: document.body.firstChild. Leading whitespace is a text
+// node in every ordinary document, and an earlier throwaway probe asserted on exactly
+// that and "proved" the app rendered nothing when it had rendered fine all along.
+const shell = await send('Runtime.evaluate', {
+  expression: `JSON.stringify({ bodyKids: document.body.children.length, nav: !!document.querySelector('#nav'), login: location.pathname.startsWith('/login') })`,
+  returnByValue: true,
+}).then((r) => JSON.parse(r?.result?.value || '{}'));
+if (!shell.bodyKids || !shell.nav || shell.login) {
+  console.error(`not the app: bodyKids=${shell.bodyKids} nav=${shell.nav} path=${shell.login ? '/login' : '?'}`);
+  await browser.close();
+  process.exit(1);
+}
+// The mining page asks the node for a block template on load (~1.3 s) and the map tweens
+// for ~520 ms after that. Judge nothing before it has settled.
+//
+// AND switch the SPA to the requested page the way a user does — by clicking the nav
+// button. Loading `/#mining` in this harness has repeatedly measured the OVERVIEW instead
+// (every canvas zeroSized or from the wrong page), because the hash route is applied
+// inside boot's async tail and a hash-only change on a warm document is no kind of
+// navigation at all (rule 25). Clicking is deterministic; hoping for the hash is not.
+await sleep(3000);
+if (PAGE !== 'overview') {
+  await send('Runtime.evaluate', { expression: `document.querySelector('#nav button[data-page=${JSON.stringify(PAGE)}]')?.click()` });
+}
+await sleep(4000);
+// Prove we are on the page we claim to be measuring, before judging a single pixel.
+const onPage = JSON.parse(await send('Runtime.evaluate', {
+  expression: `(() => { const on = document.querySelector('.page.on'); return JSON.stringify({page: on?.dataset?.page ?? null, hash: location.hash}) })()`,
+  returnByValue: true,
+}).then((r) => r?.result?.value ?? '{}'));
+if (onPage.page && onPage.page !== PAGE) {
+  console.error(`not on #${PAGE}: the app is showing "${onPage.page}". The page switch failed; every measurement below would describe the wrong page.`);
+  ws.close();
+  process.exit(1);
+}
+
+// Refuse to review a page that did not load. Without this guard a broken invocation
+// (an empty BLOCKYARD_BASE once sent it to https://:8088) produced a blank screenshot,
+// the vision model confidently reported "the page is completely empty", and that read
+// would have been believed. Check the document before asking anyone to judge it.
+const sanity = await send('Runtime.evaluate', {
+  expression: `JSON.stringify({
+    href: location.href,
+    title: document.title,
+    nav: !!document.getElementById('nav'),
+    nodes: document.body ? document.body.childElementCount : 0,
+    text: document.body ? document.body.innerText.replace(/\\s+/g,' ').slice(0,120) : ''
+  })`,
+  returnByValue: true,
+});
+let sanityObj = {};
+try { sanityObj = JSON.parse(sanity.result?.value ?? '{}'); } catch { /* reported below */ }
+if (!sanityObj.nav || !sanityObj.nodes) {
+  console.log(`\n== ${URL} ==`);
+  console.log(`ABORT: nothing to look at. href=${sanityObj.href} title=${JSON.stringify(sanityObj.title)} bodyChildren=${sanityObj.nodes}`);
+  console.log('The browser reached a document with no app in it. Check BLOCKYARD_BASE (and that the service is up) before reading anything into a screenshot.');
+  if (consoleErrors.length) consoleErrors.slice(0, 5).forEach((e) => console.log(`   ! ${e}`));
+  ws.close();
+  process.exit(3);
+}
+
+// ------------------------------------------------------- HARD: measure the page
+const PROBE = () => {
+  const out = { canvases: {}, rects: {}, cssom: {}, text: {}, scroll: {} };
+  const px = (id, label) => {
+    const c = document.getElementById(id);
+    if (!(c instanceof HTMLCanvasElement)) { out.canvases[id] = { missing: true }; return; }
+    const r = c.getBoundingClientRect();
+    out.rects[id] = { x: Math.round(r.x), y: Math.round(r.y), w: Math.round(r.width), h: Math.round(r.height) };
+    if (!r.width || !r.height) { out.canvases[id] = { zeroSized: true }; return; }
+    let ctx;
+    try { ctx = c.getContext('2d', { willReadFrequently: true }); } catch { out.canvases[id] = { noContext: true }; return; }
+    const dpr = c.width / r.width || 1;
+    const data = ctx.getImageData(0, 0, c.width, c.height).data;
+    const colours = new Map();
+    let lit = 0;
+    for (let i = 0; i < data.length; i += 4 * 17) {          // sampled every 17 px, fast and enough
+      const a = data[i + 3];
+      if (a < 8) continue;
+      const key = `${data[i] >> 3},${data[i + 1] >> 3},${data[i + 2] >> 3}`;
+      colours.set(key, (colours.get(key) ?? 0) + 1);
+      if (data[i] + data[i + 1] + data[i + 2] > 200) lit++;
+    }
+    const top = [...colours.entries()].sort((a, b) => b[1] - a[1]).slice(0, 6);
+    out.canvases[id] = {
+      sampled: label, dpr: +dpr.toFixed(2),
+      // If nothing painted, say what the drawing code left behind: __hasData is set by
+      // paint(), __rects by the treemap layout. hasData=true with 0 colours means it drew
+      // and something wiped it; false means the draw never ran at all.
+      hasData: !!c.__hasData, rects: c.__rects?.size ?? 0, cells: c.__cells ?? 0,
+      backing: `${c.width}x${c.height}`,
+      distinctColours: colours.size, litPixels: lit,
+      topColourShares: top.map(([k, v]) => `${k}:${(100 * v / [...colours.values()].reduce((a, b) => a + b, 0)).toFixed(0)}%`),
+      paintedPixelsPct: +((100 * [...colours.values()].reduce((a, b) => a + b, 0)) / (data.length / (4 * 17))).toFixed(1),
+    };
+  };
+  ['gnMempoolTreemap', 'ovGnTreemap', 'ovTrain', 'ovMpChart', 'ovFeeChart', 'mnFeeLandscape']
+    .forEach((id) => px(id, document.getElementById(id) ? 'present' : 'absent'));
+
+  // CSSOM applied? If the CSP/CSSOM conversion is broken the marks have no background.
+  const dots = [...document.querySelectorAll('.bdot')].slice(0, 6);
+  out.cssom.bdotBackgrounds = dots.map((d) => getComputedStyle(d).backgroundColor);
+  const cards = [...document.querySelectorAll('.bcard')].slice(0, 8);
+  out.cssom.cardPoolVars = cards.map((c) => getComputedStyle(c).getPropertyValue('--pool').trim() || '(none)');
+  const rail = document.querySelector('.rail');
+  out.cssom.railDuration = rail ? getComputedStyle(rail).animationDuration : '(no rail)';
+  const bar = document.querySelector('.bfill span');
+  out.cssom.fillWidth = bar ? `${getComputedStyle(bar).width} (data-w=${bar.dataset?.w ?? '-'})` : '(no fill)';
+  // Distinguish "we never set it" from "the browser computed something else": inline CSSOM
+  // values are what applyMiningStyles writes, computed values are what actually renders.
+  out.cssom.cardInlinePool = [...document.querySelectorAll('.bcard')].slice(0, 4)
+    .map((c) => `${c.style.getPropertyValue('--pool') || '(unset)'}|computed:${getComputedStyle(c).getPropertyValue('--pool').trim() || '(none)'}`);
+
+  // Card geometry: overlapping cards is the classic flexbox overflow failure.
+  const flows = [...document.querySelectorAll('.flow, .flowwrap')];
+  out.rects.flowOverflow = flows.map((f) => ({ scrollW: f.scrollWidth, clientW: f.clientWidth, clipped: f.scrollWidth > f.clientWidth + 2 }));
+
+  const txt = (id) => { const el = document.getElementById(id); const s = (el?.textContent ?? '').trim(); return s.length > 160 ? `${s.slice(0, 160)}…` : s; };
+  ['ovFeesCard', 'ovMpVsBlock', 'ovMpVsBlockKv', 'ovMempoolCard', 'ovGnTreemapNote', 'gnMempoolNote', 'mnPools', 'ovCaveats']
+    .forEach((id) => { out.text[id] = txt(id); });
+  out.scroll = { bodyH: document.body.scrollHeight, winH: innerHeight };
+  return out;
+};
+const probed = await send('Runtime.evaluate', { expression: `(${PROBE.toString()})()`, returnByValue: true });
+const hard = probed.result?.value ?? { error: probed.error ?? 'no value' };
+
+const shot = await send('Page.captureScreenshot', { format: 'png' });
+const png = shot.data ?? null;
+
+// ------------------------------------------------------- SOFT: ask the vision model
+let soft = null;
+if (png && VISION_BASE) {
+  const prompt = [
+    'You are reviewing a screenshot of a self-hosted Bitcoin node monitor (dark theme).',
+    `This is the "${PAGE}" page. Report only what you can see, and say "cannot tell" rather than guessing.`,
+    'Answer each numbered question in one short sentence:',
+    '1. Are any large areas blank, empty boxes, or placeholder dashes? Name them.',
+    '2. Is there a treemap of rectangles (a block-space map)? Do the rectangles vary in size and colour, and is any large unfilled band visible?',
+    '3. Is there a row of block cards? Read the height numbers you can see, left to right, and say whether one is marked as current.',
+    '4. Is any text unreadable because of low contrast, overlap, or clipping?',
+    '5. Does anything look obviously broken (misaligned, clipped, overlapping, wrong colours)?',
+    '6. What is the single most damaging visual problem on this page, if any?',
+  ].join('\n');
+  const res = await fetch(`${VISION_BASE}/v1/chat/completions`, {
+    method: 'POST',
+    headers: { 'content-type': 'application/json' },
+    body: JSON.stringify({
+      model: VISION_MODEL,
+      max_tokens: 700,
+      temperature: 0.2,
+      messages: [{ role: 'user', content: [
+        { type: 'text', text: prompt },
+        { type: 'image_url', image_url: { url: `data:image/png;base64,${png}` } },
+      ] }],
+    }),
+  });
+  const j = await res.json().catch(() => null);
+  const m = j?.choices?.[0]?.message ?? {};
+  // This deployment is a reasoning model: it can answer with content=null and the text in
+  // `reasoning`. Reading only `content` reports a confident-looking empty review, which is
+  // the worst possible failure for a check whose whole job is to notice problems.
+  soft = m.content ?? m.reasoning ?? JSON.stringify(j).slice(0, 400);
+}
+
+// ------------------------------------------------------------------- report
+console.log(`\n== ${URL} ${loaded ? '' : '(load event not seen)'} ==`);
+console.log(`console errors/warnings: ${consoleErrors.length}`);
+consoleErrors.slice(0, 8).forEach((e) => console.log(`   ! ${e}`));
+if (exceptions.length) { console.log(`uncaught exceptions: ${exceptions.length}`); exceptions.slice(0, 5).forEach((e) => console.log(`   !! ${String(e).split('\n')[0]}`)); }
+console.log('\n-- HARD: canvas pixels sampled in the page --');
+for (const [id, v] of Object.entries(hard.canvases ?? {})) console.log(`   ${id.padEnd(18)} ${JSON.stringify(v)}`);
+console.log('-- HARD: CSSOM + geometry --');
+console.log('   ', JSON.stringify(hard.cssom));
+console.log('   flow:', JSON.stringify(hard.rects?.flowOverflow));
+console.log('-- HARD: text on the page --');
+for (const [id, v] of Object.entries(hard.text ?? {})) if (v) console.log(`   ${id.padEnd(16)}: ${String(v).slice(0, 120)}`);
+console.log(`   page height ${hard.scroll?.bodyH} vs window ${hard.scroll?.winH}`);
+if (png) {
+  const fs = await import('node:fs');
+  const path = `/tmp/browser-check-${PAGE}.png`;
+  fs.writeFileSync(path, Buffer.from(png, 'base64'));
+  console.log(`\nscreenshot: ${path} (${Math.round(png.length * 3 / 4 / 1024)} KB)`);
+}
+console.log(`\n-- SOFT: ${VISION_MODEL} on the screenshot --`);
+console.log(soft ? soft.split('\n').map((l) => `   ${l.trim()}`).filter((l) => l.trim()).join('\n') : '   (no VISION_BASE set, so the screenshot was not reviewed)');
+console.log('\nHARD evidence is measured in the page; SOFT is a model\'s reading. Where they disagree, the pixels win.');
+ws.close();