blockyard 0.0.9 → 0.1.1

package/docs/STATE-2026-09-09.md

@@ -1,200 +0,0 @@
-# State of the project — 2026-09-09 (handoff for an agent with a real browser)
-
-> **Superseded 2026-09-14, names only.** This is a dated record and its measurements stand as
-> written. The names in it are the ones in use that day and are no longer current: the project
-> is **BlockYard** (`/storage/blockyard`, systemd `blockyard.service`, env vars `BLOCKYARD_*`,
-> default web port 21000), and the node it watches is Bitcoin Core. `bmc-port-guard.sh` and
-> `/etc/ssl/bmc-local/ca.crt` are real artefacts on the operator's machine and keep their names.
-
-Written by the session that built the mining/visualisation layer. Everything below was
-run on this box; the things I could **not** do are listed explicitly at the end. Read
-`AGENTS.md` first for the rules (zero dependencies, RPC-only sources, never fabricate a
-figure, a chart never erases itself).
-
-## What is running
-
-| Thing | Where | Note |
-|---|---|---|
-| bmcmonitor | `https://<LAN address>:8088` | systemd `bmcmonitor.service`, TLS via a **local CA** (`/etc/ssl/bmc-local/ca.crt`), binds the **LAN address only** — loopback, docker bridges and the tailnet address all refuse, by design |
-| Node watched | `bmc-main`, RPC `127.0.0.1:8331` | the node's own esplora REST is on `127.0.0.1:3005` |
-| Log tailing | **OFF** (default since today) | the UI reads RPC only. `BMC_MON_LOG_SOURCE=1` re-enables it for parser work; do not add panels that need it |
-| Block-chain node under dev | `/storage/bitcoinmachinecode` | a *different* session works there; do not restart or reindex it casually |
-
-Import the CA or the browser will refuse the certificate. After any deploy, hard-reload:
-asset URLs are stamped `?v=<build>` and the stamp changes when files change, so a tab
-holding an old tab keeps running old code — that has already produced one false report
-today ("still renders nothing" while the fix was on disk and undeployed).
-
-## Verify, don't trust this document
-
-```bash
-cd /storage/bmcmonitor
-npm test                      # unit + render + contract tests
-bash scripts/smoke.sh         # 109 checks against a real server
-npm run counts                # do the documented counts match the suite?
-LAN=$(python3 -c "import json;print(json.load(open('config/local.json'))['server']['hosts'][0])")
-BMC_MON_BASE=https://$LAN:8088 BMC_MON_CA=/etc/ssl/bmc-local/ca.crt npm run render:live
-sudo systemctl restart bmcmonitor          # deploy after editing public/** or server/**
-sudo journalctl -u bmcmonitor -f           # server-side view; the UI records to it
-```
-
-`render:live` renders **every page** under the DOM stub against the running monitor and
-fails if an asserted card is empty. Today it caught, in order: an uncaught `ReferenceError`
-that killed the entire Overview (two cards "rendered nothing" because one line above them
-threw), a `fmt is not defined` crash on the Node page, and a card that no test had ever
-reached.
-
-## What was built today (mining + visualisation)
-
-- **Mining page** (`#mining`): block flow (construction → tip → history, the tip explicitly
-  labelled `current tip`, colour = age verdict), ghost cards for the next blocks marked
-  `not yet assembled`/`estimate`, ancestor-package table (CPFP shape from
-  `getblocktemplate…depends`, with `depends` being **indices into the array**, not txids),
-  and two treemaps.
-- **Treemaps** (`public/js/goggles.js`): one rectangle per transaction, area = vbytes,
-  colour = the feerate it pays, richest-first. The canvas is **the block**: a 14%-full block
-  looks 14% full and the rest is drawn blank and labelled. Cells are bounded (400) and the
-  remainder collapses into ONE aggregate cell so the block is always whole.
-- **Tip freshness** is judged against the chain's own measured block interval, not a fixed
-  clock: amber past ~1× the average gap, red past ~1.5×, floors at 4/8 min. Arrival is only
-  counted when the page **witnessed** the height change — a first paint must not claim a
-  fresh tip (that bug coloured a 14-minute-old block green).
-- **Overview** gained a compact copy of the block map (`ovGnTreemap`, `w4`, `.treemap.sm`).
-
-## Bugs I fixed, so you don't re-diagnose them
-
-- `rows` TDZ in `renderOverview` — two `rows` in one function; killed the whole Overview
-  render (the Fees card and the "mempool vs blocks" card were collateral).
-- `fmt is not defined` in `panels.js:drawSelf` — the Node page crashed.
-- Treemap `drawFrame` referenced `label` without destructuring → **every partly-filled
-  block threw at paint time and the canvas stayed blank**.
-- The treemap tween re-requested animation frames whenever the clock failed to advance
-  (hidden/throttled tab) → unbounded loop. Now a frame budget + stalled-clock check, and
-  the settled layout always draws.
-- **CSP**: the policy is `style-src 'self'` with no `style-src-attr` allowance (correct,
-  tightened earlier today). My new markup emitted `style="..."` and the browser blocked
-  **several hundred** applications, so the train and maps lost every colour. All of it now
-  travels as `data-pool` / `data-rate` / `data-w` / `data-delay` / `data-rail` and lands on
-  `el.style` through the CSSOM (`applyMiningStyles` in `mining.js`, `applyDataSizes` in
-  `app.js`). The palette index comes from our own array — a pool name from the node cannot
-  become CSS. `test/csp.test.js` now fails if any JS-built markup carries a style attribute.
-- **The Fees card** was found with `getElementById('ovFees').closest('.card')`, and the DOM
-  stub answers `closest()` with `null` — so **no test ever exercised that card**. It is now
-  `#ovFeesCard`, addressed by id, and asserted in `test/web-contract.test.js`.
-
-## Known, open, or unverified — this is what a browser is for
-
-1. **Nothing has been seen rendered.** No real-browser harness exists. Layout, colour
-   legibility, overlap, and "does the treemap read as a block" are unverified by me.
-2. **Treemaps at `w4`** (33%) on Mining, `w4` on Overview: is 168px/240px high enough for
-   the labels, and is the "block unfilled" band legible at that width?
-3. **Legend/label collisions** inside rectangles (rate + `k` vbytes text) at small cell
-   sizes, and the `selection ends` / `everything fits in one block` label near the right
-   edge.
-4. **Hover tooltips** (`.goggles-tip`) are positioned `left/bottom` — check they don't
-   cover the cursor's cell or overflow the card.
-5. **Motion**: the map tweens only when the Mining page is open and the template refetches
-   (on load + every 20 s). Confirm the tween is visible, and that `prefers-reduced-motion`
-   snaps without losing information.
-6. **`app.js` boot throws under the DOM stub** (`TypeError` at `boot()`, harness-only). Real
-   browsers don't hit it; it means a stub element is missing, and it will keep biting anyone
-   extending the harness.
-7. Ghost-card forward capacity numbers are **queue-depth estimates**, not node data.
-8. No TLS certificate automation (self-signed local CA), and `:8999` (mempool-backend API)
-   is loopback-only by a netfilter rule — separate from this app.
-
-## Guardrails that will bite if you ignore them
-
-- **Zero dependencies.** No `npm install`. Node builtins and hand-written canvas only.
-- **No host identity in committed files.** `test/privacy.test.js` derives the username,
-  hostname forms and interface addresses at run time and fails on them — it caught a
-  hardcoded LAN address in one of my scripts today. Use RFC 5737 documentation ranges in
-  docs and tests, and read addresses from config/env at run time.
-- **Test counts are generated** (`npm run counts:fix`). Never type them.
-- **Every claim in a comment must be a measurement** with a number and a date. "Seems" is
-  not a justification, and this project has twice been burned by a check that passed for
-  the wrong reason (a vacuous assertion, a stub that answered `null`).
-- A chart **never erases itself** to show a status; absence renders as `–` with a reason,
-  and stale data renders visibly stale.
-- Absent data is **never** filled with a guess: no per-tx `depends` in
-  `getrawmempool` on this node, so cluster analysis is only drawn from
-  `getblocktemplate`, and the panel says which of the two it is.
-
----
-
-## Measured in a real browser (2026-09-10, headless Chromium over CDP)
-
-`scripts/browser-check.mjs` drives Chromium over CDP with Node's built-in WebSocket: it
-loads the page, samples **canvas pixels with getImageData**, reads inline vs computed CSSOM
-values, measures element rects, collects console/exceptions, and can pass the screenshot to
-the local vision model. This is the first time any of this has been looked at rather than
-inferred. It found five defects that 349 passing tests did not.
-
-### Found and fixed
-1. **Shared animation handle.** `goggles.js` kept one module-level `raf` for both maps, so
-   each canvas's render cancelled the *other* one's pending frame — and the first frame was
-   drawn only inside that callback. The loser painted **nothing**: `__hasData: true`, 401
-   rects laid out, 68% of the canvas covered on paper, **zero painted pixels**. Now the
-   handle is per-canvas (`c.__raf`) and the settled layout is painted before any animation.
-2. **Tween grew cells from zero size.** With a snapshot arriving every second, the chart
-   spent most of its life mostly-cleared with 1px rectangles. Now position interpolates and
-   **size never does**; new cells fade in with alpha. A tween must be the difference between
-   two visible states, not the thing that makes pixels exist.
-3. **`style-src` was silently vetoing my own markup** (several hundred blocked
-   applications): all `style="..."` removed in favour of `data-pool` / `data-rate` /
-   `data-w` / `data-h` / `data-delay` / `data-rail` + CSSOM. Guarded by a test that fails if
-   any JS-built markup carries a style attribute.
-4. **`.closest('.card')`** made the Fees card invisible to every test (the DOM stub answers
-   `null`), so it could render nothing forever. Now addressed by `#ovFeesCard`.
-5. **`rows` TDZ** in `renderOverview` killed the whole Overview. Also: the earlier "fixed"
-   report was false because the fix was never **deployed** — deploy is part of a fix.
-
-### Still broken, with the measurements
-- **The Mining page block map still paints nothing** (`gnTreemap`: `rects: 401`,
-  `distinctColours: 0`, `paintedPixelsPct: 0`) while the mempool map on the same page paints
-  100% with the identical code path and the same rect count. I did not find the cause. Start
-  by comparing what differs at `drawFrame` time between the two — `geom.unused` is set for
-  the block map and absent for the mempool map, which changes `region`; instrument
-  `drawFrame` with a counter and a sample of the first rect's `fillStyle`.
-- **The style pass is only half applying.** In the browser: `.bdot` inline style is
-  `background: rgb(95, 176, 201)` with **no `--pool`**, and `.bfill span` has `background`
-  but **no width**, while `document.querySelectorAll('[data-w]')` counts 27 of which **2**
-  have an inline width (the sync hero's, applied by app.js). So `applyMiningStyles` is
-  running an older code path than the one on disk and served (`setProperty` and
-  `applySizes` are both present in the served bytes, and `Cache-Control: no-cache`). That
-  contradiction is unresolved — check whether the module the browser evaluates is the
-  module the server sent (compare `import.meta` resolution / a marker constant), before
-  touching the style code again.
-- **The flow row overflows its card** and is cut off: `.flow` scrollWidth 2236 inside
-  clientWidth 1369. I added `.flow { width: max-content }` + `.flowwrap { overflow-x: auto }`;
-  the browser still measured clipping after the change, so either the CSS did not apply as
-  written or the grid parent constrains it. Re-measure `.flowwrap` rather than `.flow`.
-
-> **Superseded 2026-09-14:** the first two readings above were the harness measuring the
-> previous build, not the page — `Page.navigate` to a URL differing only in its fragment does not
-> reload the document (`docs/RULES.md` rule 25). Re-run against the current build on 2026-09-10,
-> `gnTreemap` and `gnMempoolTreemap` both painted 100% of their pixels.
-
-### Notes on the harness itself
-- Chromium only survives inside one shell invocation, so launch + check must run together:
-  `rm -rf /tmp/cp; (setsid /usr/bin/chromium-browser --headless=new --no-sandbox
-  --user-data-dir=/tmp/cp --remote-debugging-port=9333 --ignore-certificate-errors
-  about:blank &) ; until curl -s 127.0.0.1:9333/json/version >/dev/null; do sleep 2; done;
-  BMC_MON_BASE=https://<lan>:8088 node scripts/browser-check.mjs mining`
-- Quote `--remote-allow-origins=*` or the shell globs it into filenames.
-- **`Page.navigate` to a URL differing only in `#fragment` does not reload the document.**
-  Reusing a warm browser therefore re-measures whatever was loaded before the last deploy:
-  `public/**` changes, the page does not, and every reading is of the previous build. The
-  harness now appends `?t=<ms>` for this reason. Rule 25: prove the browser is running the
-  bytes you served before believing anything it says about them.
-- Do not assert `document.body.firstChild` is an element. Leading whitespace before
-  `<header>` is a `#text` node in every ordinary document; a probe that checked this
-  "proved" the Overview rendered nothing when it had rendered fine throughout.
-- `Page.loadEventFired` is not reliably seen by the current waiter; the probe's
-  **load guard** (abort unless `#nav` and body children exist) is what stops a broken
-  invocation being reported as "the page is blank" — that happened once and the vision
-  model confidently confirmed a blank white page that was only my own bad URL.
-- Vision: this deployment answers with `content: null` and the text in `reasoning`; reading
-  only `content` silently yields an empty review.
-- `mempool-backend.service` has been `failed` since 2026-09-09 16:58 (start-limit hit after
-  12 restarts; its own stdout is not in the journal). Unrelated to the above, untouched.