blockyard 0.0.1 → 0.1.0

package/docs/EFFECTS-AGENTS.md

@@ -0,0 +1,448 @@
+# Agent effects: a catalogue
+
+(operator, 2026-09-13: *"no more per-tile stuff. Think more tron lightcycles stuff"*, then
+*"Give me at least 25-50 new video game inspired effects. Examine all video games, and explain
+your choices"*, then *"we can even add flying ships or other pixel-graphic inspired art"*.)
+
+This is a design document. Thirty-two of the fifty were built on 2026-09-13 (see **Built so far**
+below, kept as the record of that day) and most were then removed by the operator after seeing
+them on the board; the seven agents present today are the table in the next section. The
+numbering here is what the commits refer to.
+
+---
+
+## What was removed, and what stayed
+
+**2026-09-13, after seeing them on the board, the operator removed twenty-three effects**:
+Mystery ship, De-res, Pipeline, Bombing run, Traffic, Ramp run, Options, Lemmings, Katamari,
+Scan visor, Lock-on, Claim, Tetromino, Asteroids, Squadron, Maze chase, Blast, Invaders, Hopper,
+Snake, Identity disc, Recognizer, and the Glitch field effect.
+
+That is twenty-two of the thirty-two agents and one field. A second pass the same day removed
+**Laser, Lanes (`tempest`) and Sweep (`minesweeper`)**, and a third removed **Marble**.
+**Twenty-nine effects remained: seven agents and twenty-two fields** — thirty since 2026-09-14, with the Markets pipe bulge, a line effect like the pulse.
+
+The agents that stayed:
+
+| kind | what it is |
+|---|---|
+| `lightcycle` | two riders laying light walls until one crashes |
+| `ball` | the lightning ball tracing the grid |
+| `centipede` | a body that weaves down and splits in two |
+| `tractor` | a saucer that draws the tallest transaction up and puts it back |
+| `missile` | arcs raining down against interceptors rising to meet them |
+| `boulderdash` | the board gives way from a point, cubes collapsing outward |
+| `stormball` | ball lightning drifting across the whole view, off-screen to off-screen; its arcs electrify the blocks they strike (replaced `portal`, 2026-09-14) |
+
+Two consequences worth knowing. **No surviving agent HIDES a cube** -- boulder dash shortens rather
+than absorbs -- so the `hide` path is now covered only by the synthetic end-to-end test in
+`agents.test.js`, not by any agent in the wild. And **no surviving agent reads the skyline as
+terrain**: `bomberman` and then `marble` were the two that did, and both went, taking their
+data-aware tests with them. The flat-board guard below still plays every registered agent on a
+uniform board, so the lesson outlives the effects that taught it -- it is the guard, not the
+effects, that keeps the next skyline-reader honest.
+
+Stored settings need no migration: `normalise` rebuilds the effects map from `DEFAULTS` and drops
+keys it does not know, so a `config/blockyard.json` naming a removed effect simply loses it.
+
+## What separates an agent effect from what we already have
+
+The board has thirty idle effects (when this was written, twenty-six). Twenty-three of them are
+**fields**: pure functions of a tile's position and the effect's clock,
+`fxAt(tile, fx) -> {glow, outline, lift, color}`. A field effect has no location of its own — it
+is a pattern evaluated everywhere at once. Plasma, aurora, checker, ripple, quake: every one is a
+formula over `(cx, cy, u)`. (Two of them, `pulse` and `bulge`, play on the Markets price line
+rather than on cubes.)
+
+Seven are **agents** — the table above; when this was written there were two, `lightcycle` and
+`ball`, plus a `packetPaths` primitive no effect uses. An agent has a *position*, a *route it has
+already travelled*, and a *future*. It is drawn as its own geometry over the cubes (`drawCycles`,
+`drawBall`, or the kind's own `draw` in `agents.js`) and it lights the board through `fx.heads` —
+the cubes it is near flash in its colour. That is the difference the operator is pointing at: a
+field is wallpaper, an agent is **something happening**, and you can watch it and wonder what it
+will do.
+
+The existing machinery for agents:
+
+| primitive | what it gives | file |
+|---|---|---|
+| `cyclePath(seed, W, H, from)` | a right-angled route edge to edge, jinking | `blockscene3d.js` |
+| `ballPath(seed, W, H, from, E)` | the same, entered from `E` units off-board | `blockscene3d.js` |
+| `packetPaths(seed, W, H, n)` | `n` short wandering walks, each with its own start | `blockscene3d.js` |
+| `cycleCrashes(paths)` | where two riders collide, worked out up front | `blockscene3d.js` |
+| `cellTops(tiles, W, H)` | the height of the cube under every grid cell | `blockscene3d.js` |
+| `pathHeights(pts, tops, W, H)` | what a route rides over, stepping at corners | `blockscene3d.js` |
+| `chargeTrail(ctx, segs, lw, now)` | the shared electrical wake: puffs, tube, crackle, motes | `details3d.js` |
+| `fx.heads` | `[{x, y, color, alpha, r, lift}]` — how an agent lights cubes. `r` is its reach in GRID UNITS (default 0.8: a gantry lights a swath, a thrown disc lights a point), `lift` throws the cubes it passes | `fxAt` |
+| `AGENTS` registry | `{ build, frame, draw }` per kind; details3d.js keeps only three seams | `agents.js` |
+| `view.unit` | pixels per grid unit — **size every sprite against this, never against `lw`** | `project` |
+
+**Two hard rules any new effect must satisfy**, both enforced by tests:
+
+1. `effects.test.js` plays every `FX_KINDS` entry through `fxAt` and demands it lights something
+   (`worst > 0.3`). Only `pulse` and `bulge` are exempt, because they draw on the price line. **So every new
+   agent must publish `fx.heads`** and join the heads branch — which is also what makes it feel
+   connected to the board rather than painted over it.
+2. `viewer-canvas-rules.test.js`: no `ctx.clip()`, no `globalAlpha`, no composite modes, no
+   `shadowBlur`. Every glow is layered plain `rgba()` fills. This is not a style preference — the
+   software rasteriser drops clipped fills and honours `globalAlpha` inconsistently.
+
+And one rule that is not enforced but matters: **the board is data**. Each cube is a transaction,
+sized by vbytes and coloured by feerate. An effect that reads the data it crosses is worth more
+than one that ignores it — `cascade` already does this (it runs richest-to-cheapest, so the
+effect *is* a reading of the fee structure). The best entries below do the same.
+
+---
+
+## The catalogue
+
+Fifty, grouped by what kind of agent they are. Each says what it does, why it suits *this* board,
+and roughly what it costs. "Data-aware" marks the ones that read the transactions they cross.
+
+### I. Riders — things that travel a route and leave a wake
+
+The `lightcycle` family. Cheap: one polyline, drawn stretch by stretch.
+
+**1. Recognizer** (Tron) — the marching gantry: two legs and a crossbar, striding the board on a
+straight line, lighting a wide swath *under* it rather than a point. Why: our cubes are a city
+from above, and the Recognizer is the canonical "something is patrolling your city" silhouette.
+It also solves a problem the light cycles have — they are thin, and on a dense 96-unit board a
+1-unit wall is faint. A gantry is wide. Cost: low.
+
+**2. Identity disc** (Tron) — thrown from one edge, ricochets off the board's walls three or four
+times, returns. Each bounce flashes the cubes at the impact point. Why: ricochet geometry gives
+*anticipation* — you can see where it will land before it does, which no field effect can offer.
+Cost: low. Route is `ballPath` with reflection instead of jinking.
+
+**3. Snake** (Nibbler/Snake) — a segmented body that grows as it eats: it heads for the *tallest*
+cube on the board, consumes it (a flash), grows two segments, picks the next. **Data-aware** — it
+is literally eating the biggest transactions first, and the body length tells you how many it has
+taken. Cost: low, and the pathfinding is greedy-nearest, not A*.
+
+**4. Centipede** (Centipede) — a column of segments weaving down the board, dropping a row each
+time it hits an edge. Splits into two independent centipedes if something interrupts its middle.
+Why: the split is the memorable part, and our board is a grid of obstacles, which is exactly the
+mushroom field Centipede needs.
+
+**5. Pac-Man** — a mouth running the grid *lines* (not the cells), eating pellets at each
+intersection; four ghosts on their own routes, each with a different pursuit rule (chase, ambush,
+random, scatter). Why: four agents with *different personalities* on one board is the most legible
+"something is happening" our engine could show, and the routes are already right-angled.
+
+**6. Sonic loop** — a rider that accelerates downhill and launches off the top of a tall cube,
+arcing through the air and landing further on. Why: our cubes have real heights (`cellTops`), and
+nothing currently uses height as *terrain*. This makes the skyline matter.
+
+**7. Excitebike ramp run** — same idea, low and fast, with a landing shockwave.
+
+**8. Road Rash / OutRun sweeper** — a horizon-to-foreground racer that grows as it approaches,
+leaving tyre tracks that fade. Why: sells the board's depth, which the oblique camera already has.
+
+**9. Frogger crossing** — several agents crossing simultaneously in opposite lanes at different
+speeds, some of which collide. Why: collisions we already compute (`cycleCrashes`).
+
+**10. Q*bert hopper** — a small agent hopping cube-to-cube diagonally, each landing recolouring
+the cube it lands on for a moment. Why: Q*bert's board *is* our board — an isometric stack of
+cubes. It is the single most on-the-nose match in this list.
+
+**11. Marble Madness roller** — a ball that obeys the skyline: rolls off high cubes toward low
+ones, gathering speed. **Data-aware**: it drains toward the cheap transactions.
+
+**12. Trials rider** — a two-wheeler that follows the height profile of one row, wheelie-ing over
+the tall ones.
+
+### II. Formations — many agents moving as one
+
+The thing our board has never shown: *coordinated* motion. All are cheap because the formation is
+one transform over a sprite list.
+
+**13. Space Invaders descent** — a rank-and-file grid of invaders stepping sideways, dropping a
+row at the edge, accelerating as their numbers fall. They shoot; hit cubes flash and the invader
+above dies. Why: the operator asked for flying ships and pixel art, and this is *the* pixel-art
+formation. Our board is already a grid; the invaders are a grid above it.
+
+**14. Galaga wing** — ships peel off a formation in Lissajous dives and rejoin. Why: the dive
+curve is two sines — trivial — and it looks far more expensive than it is.
+
+**15. Galaga tractor beam** — one ship stops over a tall cube, beams it up (the cube rises off the
+board and vanishes), and a "captured" ghost of it flies in formation. **Data-aware**, and it uses
+`lift`, which most effects ignore.
+
+**16. Xevious bombing run** — a ship crossing at altitude dropping markers ahead of itself; each
+marker detonates on the cube beneath a beat later. Why: the *lead* — the marker lands before the
+bomb — creates suspense.
+
+**17. 1942 barrel roll** — a squadron crossing with a roll animation, sprite-scaled.
+
+**18. R-Type charge beam** — a ship crosses slowly charging (a growing bead), then releases a beam
+that lights *an entire row* of cubes at once. Why: a long wind-up and a big release is a rhythm
+none of our current effects have.
+
+**19. Gradius Options** — a lead ship trailed by four satellites that follow its exact past path
+on a delay. Why: the delayed-follow is four lines of code and reads as intelligence.
+
+**20. Missile Command interception** — arcs rain from the top toward cubes; interceptors launch
+from the bottom and detonate as expanding rings that stop them. Why: two agent populations that
+interact, and the expanding-ring geometry is already in `drawCycles`' de-res.
+
+**21. Asteroids drift** — wireframe polygons tumbling across, splitting into smaller ones when
+they cross a tall cube. Why: pure vector art, which is exactly what this renderer draws natively.
+
+**22. Zerg rush** — a swarm of small agents entering from one edge with slight per-agent noise,
+converging on the tallest cube. Why: emergent-looking, trivially cheap, and **data-aware**.
+
+**23. Lemmings procession** — a line of walkers that turn at obstacles, some digging *through* a
+tall cube (which visibly shortens as they pass). Why: the board changing shape under an effect.
+
+**24. Bomberman blast** — an agent walks the grid, drops a bomb, and the blast runs in four
+straight lines until a tall cube stops it. Why: the cross-shaped blast *reads the skyline* as
+walls — it is a picture of the board's density. **Data-aware**.
+
+### III. Boards that transform — the effect changes the board itself
+
+**25. Tetris drop** — a tetromino falls onto the skyline, locks onto the tops of cubes, and if it
+completes a flat row, that row flashes and clears. Why: we already have `tetris.js` rules, pure
+and tested; this is that rule-set pointed at the block board.
+
+**26. Breakout wall** — the top rows of cubes become bricks; a ball and paddle play a few seconds
+of Breakout against them. Why: `breakout.js` exists and is pure.
+
+**27. Qix / Gravitrons claim** — a line agent crawls the board's perimeter, cuts inward, and the
+enclosed region is claimed (filled with colour). Why: an effect that *encloses* rather than
+sweeps; nothing else here does area.
+
+**28. Pipe Mania** — pipe segments lay themselves tile by tile into a connected run; then fluid
+flows the completed pipe. Why: the two-phase build-then-flow is a strong rhythm.
+
+**29. Minesweeper reveal** — a flood-fill reveal spreading from one cube, stopping at "mines"
+(the highest-feerate transactions), which then flash red. **Data-aware**, and flood-fill from a
+seed is a genuinely different spread shape from a radius.
+
+**30. Boulder Dash collapse** — cubes unsupported by a neighbour fall, cascading. Why: uses the
+skyline as physics.
+
+**31. Katamari roll** — a ball that rolls over the board *absorbing* cubes, visibly growing.
+**Data-aware**: it gets bigger the more weight it crosses.
+
+**32. Dig Dug tunnel** — an agent tunnels *through* the board leaving a visible cleared corridor
+that slowly refills.
+
+### IV. Scanners, beams and sweeps with an agent behind them
+
+**33. Tempest lane pulse** — pulses rushing up lanes from a vanishing point toward the viewer.
+Why: our oblique camera has a natural horizon; this is the only effect that uses the *depth* axis
+as the axis of motion.
+
+**34. Star Fox barrel corridor** — a moving frame of reference: the board appears to bank left and
+right as an unseen ship rolls. Why: cheap (it is a camera trick) and startling.
+
+**35. Rez / Child of Eden lock-on** — a reticle flicks across the board tagging eight cubes in
+sequence, then fires eight homing streaks at all of them at once. Why: the tag-then-release
+rhythm, and **data-aware** if it tags by feerate.
+
+**36. Metroid scan visor** — a horizontal band that, as it passes, briefly *labels* the cubes it
+crosses with their feerate. Why: an effect that makes the board more legible, not less — the only
+one here that adds information.
+
+**37. Sniper glint sweep** — a slow searchlight cone rotating from one corner.
+
+**38. Portal pair** — two portals open on opposite sides; an agent enters one and exits the other,
+carrying its trail through. Why: the trail crossing the discontinuity is a genuinely novel visual.
+
+**39. Tron derez wave** — a front that de-resolutes cubes into shards as it passes and
+re-resolves them behind it. We already have de-res shards in `drawCycles`.
+
+**40. Matrix bullet-time orbit** — everything holds still while one agent orbits the board.
+
+### V. Sprites and pixel art — the operator's "flying ships"
+
+`arkanoid.js` already proves this works: its capsules are multi-part glyph-on-body silhouettes
+with `poly`, `rot` and `floor`, tumbling as they fall, and its enemies are drawn the same way.
+A sprite here is a small list of tiles with offsets — not a bitmap — so it scales, rotates and
+lights like everything else on the board.
+
+**41. UFO flyby** (Space Invaders' mystery ship) — the saucer crossing the top of the board on a
+timer, worth "points"; a rare visitor rather than a regular effect. Why: rarity is its own effect.
+
+**42. Zaxxon isometric fighter** — a ship flying *at an altitude above the board*, with its shadow
+tracking on the cube tops beneath it. Why: we already cast shadows; nothing currently flies.
+
+**43. Choplifter rescue** — a helicopter that descends to a cube, hovers, lifts it, and carries it
+off the board.
+
+**44. Defender sweep + humanoid** — fast horizontal scroll, with a lander stealing a cube and a
+ship intercepting it.
+
+**45. Joust flap** — two winged riders in slow flapping arcs that collide; the higher one wins.
+
+**46. Mario pipe warp** — a sprite descends into the board between two cubes and re-emerges
+elsewhere.
+
+**47. Rampage climb** — a large sprite that climbs the tallest stack and knocks the top cube off.
+
+**48. Pixel-art banner drift** — a sprite spelled out in cubes (a block, a coin, a "GM") drifting
+across as a formation of lit cells, then dispersing. Why: it turns the board itself into the
+sprite — the highest-impact version of pixel art here.
+
+**49. Duck Hunt flush** — birds break from the board and fly off; one is "shot" and falls back in.
+
+**50. Konami code easter egg** — the code typed on the keyboard triggers a scripted sequence
+(a 30-ship formation, or every effect at once for four seconds). Why: it is the arcade tradition
+the whole board is quoting, and it costs nothing until someone finds it.
+
+---
+
+## Built so far
+
+*(The record of 2026-09-13, as written that day. The removals described at the top of this
+document happened afterwards; of the agents named below, only `centipede`, `tractor`, `missile`
+and `boulderdash` remain, alongside `lightcycle`, `ball` and the later `stormball`.)*
+
+Batch one landed 2026-09-13: **recognizer (1), disc (2), snake (3), qbert (10), invaders (13),
+bomberman (24)** -- five different motion vocabularies, two of them data-aware.
+
+Batch two, the same day: **centipede (4), pacman (5), galaga (14), tractor (15), missile (20),
+asteroids (21)**. These add the three things batch one had no example of -- an agent that
+DIVIDES (the centipede splits and both halves carry on), agents with DIFFERENT RULES FROM EACH
+OTHER (four pursuers: chase, ambush, scatter, wander), and TWO POPULATIONS THAT INTERACT (arcs
+raining down against interceptors rising to meet them). The tractor beam is the only agent that
+uses `lift`, and it is data-aware: it takes the tallest transaction on the board and puts it back.
+
+Fourteen agents now. `test/agents.test.js` holds every one of them to the same contract -- builds,
+frames, draws, publishes heads, replays from a seed, and leaves the board's tiles untouched -- so a
+new batch is checked against all of it the moment it is registered.
+
+Batch three, the same day: **tetrisdrop (25), qix (27), minesweeper (29), tempest (33),
+lockon (35), scanvisor (36)**. These work in AREA rather than along a path -- qix claims a region,
+minesweeper floods outward and goes *around* what blocks it -- and two of them add INFORMATION
+rather than decoration, which is the rarest thing an effect here can do: lockon tags the eight
+richest transactions in turn before firing, and scanvisor labels the blocks it crosses with their
+feerate. Three of the six are data-aware. `tetrisdrop` points the real, already-tested rules in
+`tetris.js` at the skyline instead of a well, so the piece shapes are not reinvented.
+
+Batch four, the same day: **katamari (31), boulderdash (30), lemmings (23), marble (11),
+gradius (19), portal (38)**. This is the family that ALTERS the board, and it could not be built
+until heads carried `hide`/`scale` through to the renderer -- see the fourth lesson below. The
+katamari absorbs cubes as it rolls and grows with what it has taken; boulder dash collapses them
+outward from a point; a lemming digs straight through one. All of it snaps back, by construction:
+nothing touches a tile, the override just stops being computed. `marble` is data-aware in a new
+way -- it obeys the board as TERRAIN, rolling greedily downhill, so it drains away from the big
+transactions and shows which way the block leans.
+
+Batch five, the same day: **sonic (6), frogger (9), xevious (16), pipemania (28), derez (39),
+ufo (41)**. `sonic` is the second agent to use height as TERRAIN rather than as an obstacle -- it
+launches off the tallest block in its row and arcs. `xevious` is the only effect where you see what
+is about to happen: the marker lands a beat before the bomb. `derez` takes the board apart as it
+passes and puts it back behind itself, which is the plainest demonstration that an effect can do
+that without touching a tile. `ufo` is deliberately brief -- rarity is its whole design.
+
+**Thirty-two agents, and with the twenty-four field effects that is FIFTY-SIX on the board.**
+Every entry in this catalogue worth building has been built. (An earlier note here said fifty;
+that was my arithmetic, not a count -- there were twenty-four fields, not eighteen.)
+
+**A seventh lesson: a bias written when the list was short becomes a takeover when it grows.**
+`scheduleFx` gave the light cycles a 50% head start on the first effect after the board came to
+rest -- a reasonable flourish among nine effects, and an eighteenfold bias among fifty-six (measured:
+33.2% of picks against 1.8% for an even split). The block-space board re-lays on every pool refresh,
+so that branch fired constantly and the operator saw light cycles and little else. Nothing guarded
+it, which is why it survived four batches of new effects being added around it. `effects.test.js`
+now replicates the scheduler's choice and fails if any kind takes more than twice an even share, or
+if any kind is unreachable.
+
+Related, and the same shape: the recognizer flipped a coin between marching along grid X or grid Y.
+On this camera +10 in grid x moves 73.4 screen pixels horizontally and +10 in grid y moves **zero**
+-- y is depth. So half the time both its legs projected to the same screen x, the gantry collapsed
+into a single vertical line, and it read as a scanning artifact. Geometry that is symmetric in the
+data is not necessarily symmetric on screen.
+
+**A sixth lesson, and the one with the highest recurrence: on this board, FLAT IS THE COMMON CASE.**
+The dense block-space viewer packs thousands of slabs at exactly the same height, so any agent that
+reads the skyline for a gradient finds none. Three were blinded by it before the pattern was
+obvious -- bomberman's wall threshold made every neighbour a wall and the blast drew a dot; marble's
+greedy descent stopped at the first step and it sat still; sonic found no rise, so it never launched
+and parked at the left edge. Each was measured only because its frame sizes stayed suspiciously
+flat across a whole capture.
+
+`agents.test.js` now plays EVERY registered agent on a perfectly uniform board and requires it to
+keep publishing heads and to visit more than a handful of distinct places. A skyline-reading agent
+must degrade to something worth watching, never to nothing.
+
+**A fifth lesson, learned three times in one day: a measurement that contradicts a working picture
+is usually the measurement.** Three times a probe reported an effect doing nothing while the
+screenshot plainly showed it working. Every one announced itself the same way -- *results identical
+across cases that should differ*, or a zero where a picture showed something:
+
+- probing `hide` with `kind: 'katamari'`, which is not a registered kind, so every case fell to
+  `default: FX_NONE` and came back the same;
+- sweeping the board-alterers over a 96x96 grid holding only 3,700 tiles -- 38 rows of 96 -- so the
+  agents roamed empty space and touched nothing. On a fully-populated board the same sweep reports
+  katamari hiding 2,173 cube-frames and boulder dash shrinking 3,404;
+- judging invaders, bomberman and pacman from a four-phase capture of effects that run 6-9 s in
+  distinct phases.
+
+Before believing a null result, check the experiment ran: does the control case behave differently?
+Is the board the agent is walking actually occupied? Did the capture land inside the phase?
+
+**A fourth lesson, and the sharpest one: machinery nobody uses is machinery that does not work.**
+`hide` and `scale` were added to `fxAt`'s result so an effect could eat or collapse a cube and have
+it snap back -- and the heads branch then hardcoded `hide: 0, scale: 1`, so no agent could actually
+reach them. Three batches passed with that dead. It was only caught when batch four's whole family
+(katamari, boulder dash, lemmings) was about to be built on top of it; every one of them would have
+drawn a glow and called it eating. Wire a capability to a caller the same day you add it, or test
+it end to end from the caller's side.
+
+A third lesson, from verifying batch two: **a four-phase capture is not enough to judge an effect.**
+Pac-Man was written up as "did not appear at all" on the strength of one frame; captured every
+500 ms instead, all five characters are plainly there -- the wedge mid-board with its mouth open
+and four ghosts in the corners, eyes tracking him. The effect was fine and the *photograph* was
+mistimed, which is the same mistake twice now (bomberman spends its first 35% walking). Capture
+across the whole run, or do not draw a conclusion. They live in
+`public/js/agents.js` behind the `AGENTS` registry described above; `test/agents.test.js` drives the
+real build/frame/draw path for every registered kind.
+
+Two things learned building them, which apply to all the rest:
+
+- **Size in GRID UNITS, never in line-widths.** `lw` is about one device pixel, so a sprite drawn
+  at `lw * 20` is 20px on any board -- 2.8% of a 705px panel, a speck among 3,700 cubes. The first
+  cut of the recognizer, the invaders and the blast were all invisible for this reason and had to
+  be redrawn against `view.unit` (7.3px per unit on the dense 96-grid board, 16px on the 44-grid
+  one). `drawCycles` had it right all along with `wallH = 3`.
+- **The board is never mutated.** `fxAt` results carry `hide` and `scale`, applied per frame onto a
+  *copy* of the tile. An effect interrupted by a transition or a hidden tab stops being computed
+  and the board is correct again by construction -- which is the only version of "it snaps back"
+  that cannot leak.
+
+## What I would build first, and why
+
+*(The proposal as made before any were built. All six were built; of them only Missile Command
+survived the operator's cull.)*
+
+If the point is to blow people away rather than to add length to a list:
+
+1. **Space Invaders descent (13)** — the formation is the thing our board has never done, and it
+   is instantly recognisable to everyone who will look at a screenshot.
+2. **Q*bert hopper (10)** — the closest match between a real arcade board and ours; it will look
+   *native*, not bolted on.
+3. **Recognizer (1)** — solves the light cycles' real weakness (too thin on a dense board).
+4. **Bomberman blast (24)** — the first genuinely **data-aware** agent: the blast is stopped by
+   the skyline, so the picture it draws is a picture of the mempool's shape.
+5. **Snake (3)** — eats the biggest transactions first, and its own length is the readout.
+6. **Missile Command (20)** — two interacting populations; the most "alive" of the lot.
+
+That is six effects covering all five families, each with a different motion vocabulary. Beyond
+that the list has more ideas than the board has seconds to show them: at one effect every 5-9 s
+plus its own run time, thirty kinds means any given one appears a few times an hour.
+
+## Costs and constraints to respect when building these
+
+- **The dense board is 96 units across** with thousands of slabs. An agent that touches every cube
+  per frame is O(tiles) per frame; the heads branch in `fxAt` is already that, so keep the
+  *number of heads* small (the light cycles use two).
+- **Determinism**: board-level choices come from `fxHash(seed)`, never `Math.random()`, in
+  anything the tests replay. Per-frame sparkle (the crackle) may be random because it is never
+  asserted frame-to-frame.
+- **Every effect needs a switch** in `settings.js` `effects` and a row in `PANEL`, in `FX_KINDS`
+  order, or `effects.test.js` fails. That is a feature: it is what stops an effect shipping
+  without a way to turn it off.
+- **Sprites** should be built as tile lists like `capsuleTiles()`, so they light, shadow and
+  depth-sort with everything else rather than being painted over the top.

package/docs/GETTING-STARTED.md

@@ -0,0 +1,205 @@
+# Getting started: macOS or Linux, from a command prompt
+
+Everything here is typed into a terminal on **the machine that runs Bitcoin Core**. BlockYard
+reads the node's block files to build the explorer's address index, so it runs on the node's
+machine and nowhere else. Ten minutes of typing, then the index build runs on its own.
+
+## 1. Bitcoin Core
+
+BlockYard needs Bitcoin Core **25.0 or later** (`getblock` verbosity 3, which the index follower
+uses; v29 is what it is being released against), with its RPC server on and a transaction index.
+Add to `bitcoin.conf` if they are not there, and restart the node:
+
+```conf
+server=1
+txindex=1
+```
+
+`txindex=1` on a node that has run without it triggers a one-off reindex that takes a while;
+`bitcoin-cli getindexinfo` says `"synced": true` when it is done (with the macOS app bundle,
+`bitcoin-cli` is inside it: `/Applications/Bitcoin-Qt.app/Contents/MacOS/bitcoin-cli`). Everything but the explorer's
+transaction-by-id pages works before that. `coinstatsindex=1` is optional: without it the Chain
+page's UTXO figures are blank and the node is not asked for them.
+
+**Disk:** the address index is about **125 GB**, on top of the node's own ~875 GB of block
+files; the build reads those files once. A different disk from the node's is best, if there is one.
+
+Where `bitcoin.conf` and the data directory are, by default:
+
+| | data directory | `bitcoin.conf` |
+|---|---|---|
+| macOS | `~/Library/Application Support/Bitcoin` | the same directory |
+| Linux | `~/.bitcoin` | the same directory |
+
+A **pruned** node will not do: the index needs every block file.
+
+## 2. Node.js 22 or newer
+
+```bash
+node -v        # v22.x or later
+```
+
+If that prints nothing or an older version:
+
+- **macOS:** `brew install node` (Homebrew's current Node is newer than 22), or the installer
+  from <https://nodejs.org>. (`node@22` from Homebrew is keg-only and needs linking; the plain
+  `node` formula is simpler.)
+- **Linux:** your distribution's `nodejs` package if it is 22+, otherwise the installer or
+  NodeSource repository from <https://nodejs.org>.
+
+## 3. Get BlockYard
+
+```bash
+git clone https://github.com/BobClawblaw/blockyard.git
+cd blockyard
+npm test              # optional: the unit tests; there is no npm install -- no dependencies
+```
+
+## 4. `npm run setup` — the installer
+
+```bash
+npm run setup
+```
+
+It asks for the data directory first and **reads the node's own `bitcoin.conf`** there -- the
+chain, `rpcport`, `rpcconnect`, `rpcuser`/`rpcpassword`, `rpcauth` users, a cookie file the node
+was told to write elsewhere, `server=` and `txindex=`, sections (`[main]`, `[test]`, ...) and
+`includeconf=` all understood -- so the rest arrive as defaults to accept rather than questions
+to answer. Then it checks the answers against the node (every call timed, a verbose mempool read
+included, so you learn how fast the node answers before anything depends on it), asks where the
+web interface and the index go, writes `config/local.json`, and offers to build the address
+index. Every check is a read; nothing on the node is changed. The banner is pixel art and, like
+everything the installer prints, fits an 80-column terminal.
+
+| it asks | default | what it does with the answer |
+|---|---|---|
+| Bitcoin Core data directory | the platform default above | reads `bitcoin.conf`; finds the `.cookie` for RPC authentication, the `blocks/` directory, and `debug.log` |
+| Bitcoin Core RPC URL | from `bitcoin.conf`: `rpcconnect` and `rpcport`, else `http://127.0.0.1:8332` (the chain's default port) | connects, reads the chain and height |
+| a label | `Bitcoin Core` | what the header calls the node |
+| rpcUser / rpcPassword | from `bitcoin.conf` when it has them; *asked only if no cookie is readable* -- an `rpcauth` user is pre-filled, its password is not in the file | a node using `rpcauth` instead of the cookie |
+
+Then it prints the checks. This is what a good node looks like:
+
+```
+  2/6  Checking the node  ────────────────────────────────────────────────────
+
+    ✓ credentials        cookie /Users/you/Library/Application Support/Bitcoin/.cookie
+    ✓ rpc                http://127.0.0.1:8332 answers in 10 ms: chain main, block 967,016 of 967,016 headers
+    ✓ version            /Satoshi:29.1.0/ (290100)
+    ✓ txindex            synced to 966,978
+    · coinstatsindex     off: the Chain page marks UTXO figures unindexed (optional)
+    ✓ getblock 3         the tip block decodes with prevouts (4,077 transactions) in 921 ms
+    ✓ mempool            34,455 transactions, verbose, in 1.0 s
+    · address index rpc  the node has no address index, as expected of Bitcoin Core; BlockYard builds its own
+    ✓ block files        5757 block files and 5757 undo files, 875.9 GB, XOR-obfuscated (xor.dat present)
+    ✓ read a block       blk00000.dat opens and its first record is the genesis block
+    · node log           /Users/you/Library/Application Support/Bitcoin/debug.log (10.3 MB) -- found; not parsed on Bitcoin Core, and not needed
+
+    everything this needs is there
+```
+
+A ✗ names what is missing and what to do about it (`txindex=1`, a readable cookie, the chain
+the node is really on, a pruned node). A slow `getblock 3` (5 s or more) or a slow mempool read
+(10 s or more) is a warning, not a failure: it says the board and the block being built will lag
+behind the node. If the RPC server does not answer it offers to ask again; with anything else
+failing it asks before writing. Every answer is validated before it is accepted -- a URL that is
+not one, a port outside 1-65535, a directory that is not there -- and asked again.
+
+Then, in this order:
+
+| it asks | default | notes |
+|---|---|---|
+| bind address | `127.0.0.1` | keeps it to this machine; `0.0.0.0` opens it to everyone who can reach the port, see [SECURITY.md](SECURITY.md) |
+| port | `21000` | it warns if something (a running BlockYard included) already answers there |
+| index directory | `data/index` inside the checkout | alongside everything else this install writes; about 125 GB for the whole chain -- give another path to put it on a different disk from the node's |
+| build workers | `4` (fewer on a machine with fewer cores or less memory; never more by default) | each needs about 2.5 GB of memory. **Answer 1 if the block files are on spinning disks**: parallel readers only seek against each other and against the node, and the build takes hours there whatever you answer |
+
+It writes `config/local.json` (mode 0600; a backup is kept if one was there) and shows it. The
+number of workers is written as `addressIndexWorkers`, so the background build uses the same one.
+
+**Step 6, building the index** — the default is **(b)ackground**: BlockYard builds it itself
+once it starts, on worker threads, while every page keeps working. **Expect the build to take a few hours** — about two on the installer's default of four workers on NVMe, longer on spinning disks — during which every other page works and address pages show the build's progress in place of a history. The Overview's "What this
+panel cannot tell you" box shows the progress (`the address index is being built: scan 1,234 of
+5,757 (21%), 1,204,511,033 rows so far, about 20 min left`), the address page says the same in
+place of a history, and a notification pops up at the start and when it is done (both appear in
+the events feed, as does a failure) — the address pages fill in from then on, no restart. The
+ETA settles after the first few files. The build is **paced by the node**: it holds while the
+node's RPC is failing or answering slower than the monitor's slow threshold (`rpc.slowLatencyMs`,
+5 s by default), eases off while merely slow, and says so in the progress line and the log; it
+talks to the node over its own RPC connection so the pages are not queued behind it. Reading
+every block file once took **29 min 45 s on 16 workers** on NVMe on the machine it was measured
+on; expect roughly four times that on four. **(h)ere** builds it in this terminal instead, with a
+progress bar and the same pacing; **(l)ater** writes `addressIndexBuild: "manual"` so nothing
+builds until you run this and restart BlockYard:
+
+```bash
+node scripts/index-build.js --out data/index --workers 4
+```
+
+Last question: **start BlockYard now, in this terminal?** — yes runs it right there (Ctrl-C
+stops it, and stops a background build with it; there is no resume, so it starts over on the
+next start); `--start` does the same without asking.
+
+Scripted, with no questions (a fresh machine, a Makefile):
+
+```bash
+node scripts/setup.js --yes --rpc-url http://127.0.0.1:8332 \
+  --datadir "$HOME/Library/Application Support/Bitcoin" --index-dir "$PWD/data/index" --workers 4
+```
+
+Every question has a flag: `--datadir`, `--rpc-url`, `--label`, `--rpc-user` / `--rpc-password`,
+`--host`, `--port`, `--index-dir`, `--workers`. `--build-here` builds in the terminal and
+`--build-later` leaves it to you; `--start` boots the monitor at the end; `--force` replaces an
+existing `config/local.json` (with a backup).
+
+## 5. Run it
+
+```bash
+npm start
+```
+
+The log says `BlockYard 0.1.0 listening on https://127.0.0.1:21000` (its own self-signed
+certificate, made on this first start; the browser warns once and remembers it), then `created the
+first admin account (admin)` with a generated password **shown once** — copy it, or set
+`BLOCKYARD_ADMIN_PASSWORD` before the first start to choose it — then `address index: building
+/Users/you/blockyard/data/index from main's block files with 4 workers -- the Overview shows the
+progress` (and `address index build: paused while the node's RPC is answering in … s` /
+`resumed` if the node struggles) and, when that is done, `address index built: … rows to block N
+in … min -- address pages are live` followed by `address index /Users/you/blockyard/data/index:
+following main from block N`. Open <https://127.0.0.1:21000> and sign in as `admin`. The
+Overview fills in within about thirty seconds; Block space lands a little after. Open Explorer,
+click the latest block, then any output address: while the index is building the page says so
+with the progress; once it is built, its balance, history and unspent outputs appear.
+
+To check the setup again at any time, or after changing the node:
+
+```bash
+npm run check
+```
+
+It runs the same checks against every node in `config/local.json`, with every call timed, and
+exits non-zero if one fails, so it can sit in a health script.
+
+## 6. Keep it running
+
+- **Linux:** as a systemd service — [INSTALL.md §6](INSTALL.md#6-run-it-as-a-service).
+- **macOS:** leave `npm start` running in a terminal (or a `tmux`/`screen` session), or write a
+  `launchd` plist that runs `node server/main.js` in the checkout with `KeepAlive`.
+
+## 7. Updating
+
+```bash
+git pull
+npm test
+```
+
+then restart it. There is nothing to install and no build step. If a release says the index
+format changed, delete the index directory (or rebuild it with the same `index-build.js` command
+into the same directory — the build empties the directory first) and BlockYard builds it again
+on the next start.
+
+## If something does not fill in
+
+[TROUBLESHOOTING.md](TROUBLESHOOTING.md): a node showing offline, an empty block-space board,
+a slow or paused index build, STALLED in the header, a transaction id not found (`txindex`), an
+address page reading *not indexed* or *behind*, no dollar figures, a slow board.