blockyard 0.0.9 → 0.1.1

package/public/js/blockanoid.js

@@ -10,7 +10,7 @@ import {
   newGame, advance, step, movePaddle, nudge, launch, fire, tiles, remaining, powers, setOptions,
   COLS, ROWS, LIVES, CAPSULE_LETTER, layoutFor,
 } from './arkanoid.js';
-import { loadSettings, setSetting, blockanoidOptions } from './settings.js';
+import { loadSettings, setSetting, blockanoidOptions, nextSky, SKY_LABELS } from './settings.js';
 import * as sound from './tetsound.js';
 
 const SCORES_KEY = 'blockyard.blockanoid.scores';
@@ -130,9 +130,20 @@ function drawScores(highlightAt = null) {
   if (t.innerHTML !== html) t.innerHTML = html;
 }
 
-const SWITCHES = [['baStars', 'stars'], ['baGalaxy', 'galaxy'], ['baNeon', 'neon'], ['baSfx', 'sfx']];
+const SWITCHES = [['baNeon', 'neon'], ['baSfx', 'sfx']];
+/** The sky button says which sky it is on, and lights up while there is one. */
+function skyButton(id, sky) {
+  const b = el(id);
+  if (!b) return;
+  b.textContent = `\u2600 ${SKY_LABELS[sky] ?? sky}`;
+  b.classList.toggle('on', sky !== 'none');
+  b.setAttribute('aria-pressed', sky !== 'none' ? 'true' : 'false');
+}
 function drawSwitches() {
   const b = blockanoidOptions(loadSettings());
+  // ONE SKY BUTTON (docs/PLAN-SKIES.md): Galaxy, Earth or none, round the ring, in place of the old
+  // star field and galaxy pair -- the same setting the Sky tab's table shows for this board
+  skyButton('baSkySw', b.sky.sky);
   for (const [id, key] of SWITCHES) {
     const btn = el(id);
     if (!btn) continue;
@@ -146,7 +157,6 @@ function flip(key) {
   setSetting(loadSettings(), `blockanoid.${key}`, !cur);
   sound.unlock();
   drawSwitches();
-  if (key === 'stars' || key === 'galaxy') drawSky();
   // capsules and minions change the RULES, so a flip must reach the game IN PLAY, not just the
   // next one -- otherwise the switch does nothing until you lose, which reads as a broken control
   if (G.game) { const b = blockanoidOptions(loadSettings()); setOptions(G.game, { capsules: b.capsules, enemies: b.enemies }); }
@@ -159,10 +169,7 @@ function drawSky() {
   const b = blockanoidOptions(loadSettings());
   board3d(sky, [], {
     ...SKY,
-    stars: b.stars, galaxy: b.stars && b.galaxy, galaxyAt: b.galaxyAt,
-    starDensity: b.starDensity, starBrightness: b.starBrightness,
-    nebulae: b.nebulae, galaxies: b.galaxies, dust: b.dust, clusters: b.clusters,
-    starColours: b.starColours, starGlints: b.starGlints,
+    ...b.sky,          // which sky this board chose, and what it is made of (settings.js skyFor)
   });
 }
 
@@ -327,6 +334,7 @@ function bind() {
   });
   court?.addEventListener('contextmenu', (e) => { if (G.running) e.preventDefault(); });
   for (const [id, key] of SWITCHES) el(id)?.addEventListener('click', () => flip(key));
+  el('baSkySw')?.addEventListener('click', () => { const s = loadSettings(); setSetting(s, 'blockanoid.sky', nextSky(blockanoidOptions(s).sky.sky)); sound.unlock(); drawSwitches(); drawSky(); draw(); });
 }
 
 export function renderBlockanoid(s, state, h) {

package/public/js/blockout.js

@@ -12,7 +12,7 @@ import {
   newGame, advance, step, movePaddle, nudge, launch, tiles, remaining,
   COLS, ROWS, LIVES,
 } from './breakout.js';
-import { loadSettings, setSetting, blockoutOptions } from './settings.js';
+import { loadSettings, setSetting, blockoutOptions, nextSky, SKY_LABELS } from './settings.js';
 import * as sound from './tetsound.js';
 
 const SCORES_KEY = 'blockyard.blockout.scores';
@@ -145,9 +145,20 @@ function drawScores(highlightAt = null) {
   if (t.innerHTML !== html) t.innerHTML = html;
 }
 
-const SWITCHES = [['boStars', 'stars'], ['boGalaxy', 'galaxy'], ['boNeon', 'neon'], ['boSfx', 'sfx']];
+const SWITCHES = [['boNeon', 'neon'], ['boSfx', 'sfx']];
+/** The sky button says which sky it is on, and lights up while there is one. */
+function skyButton(id, sky) {
+  const b = el(id);
+  if (!b) return;
+  b.textContent = `\u2600 ${SKY_LABELS[sky] ?? sky}`;
+  b.classList.toggle('on', sky !== 'none');
+  b.setAttribute('aria-pressed', sky !== 'none' ? 'true' : 'false');
+}
 function drawSwitches() {
   const b = blockoutOptions(loadSettings());
+  // ONE SKY BUTTON (docs/PLAN-SKIES.md): Galaxy, Earth or none, round the ring, in place of the old
+  // star field and galaxy pair -- the same setting the Sky tab's table shows for this board
+  skyButton('boSkySw', b.sky.sky);
   for (const [id, key] of SWITCHES) {
     const btn = el(id);
     if (!btn) continue;
@@ -161,7 +172,6 @@ function flip(key) {
   setSetting(loadSettings(), `blockout.${key}`, !cur);
   sound.unlock();
   drawSwitches();
-  if (key === 'stars' || key === 'galaxy') drawSky();
   G.dirty = true;
   draw();
 }
@@ -172,10 +182,7 @@ function drawSky() {
   const b = blockoutOptions(loadSettings());
   board3d(sky, [], {
     ...SKY,
-    stars: b.stars, galaxy: b.stars && b.galaxy, galaxyAt: b.galaxyAt,
-    starDensity: b.starDensity, starBrightness: b.starBrightness,
-    nebulae: b.nebulae, galaxies: b.galaxies, dust: b.dust, clusters: b.clusters,
-    starColours: b.starColours, starGlints: b.starGlints,
+    ...b.sky,          // which sky this board chose, and what it is made of (settings.js skyFor)
   });
 }
 
@@ -329,6 +336,7 @@ function bind() {
   court?.addEventListener('pointermove', onPointer);
   court?.addEventListener('pointerdown', (e) => { onPointer(e); serve(); });
   for (const [id, key] of SWITCHES) el(id)?.addEventListener('click', () => flip(key));
+  el('boSkySw')?.addEventListener('click', () => { const s = loadSettings(); setSetting(s, 'blockout.sky', nextSky(blockoutOptions(s).sky.sky)); sound.unlock(); drawSwitches(); drawSky(); draw(); });
 }
 
 export function renderBlockout(s, state, h) {

package/public/js/blockscene3d.js

@@ -852,21 +852,50 @@ const flipOf = (o) => (o.flipY === false ? -1 : 1);
 // settings"). Each lamp is a direction over the board for the dome's slope shading (grid x,
 // screen-up rows, up) and a direction across the screen for the side faces (x right, y down);
 // `overhead` is straight above, so no slope is in shade and every side takes the same light.
+// SIX PLACEMENTS AT THREE HEIGHTS (operator, 2026-09-16: "add more camera light angles ... Low
+// Middle and High light placement locations, top left, top right, bottom left, bottom right,
+// viewer, direct overhead"). A placement is a direction across the board (x right, y screen-up);
+// the height is the lamp's elevation over it: low 25°, middle 45°, high 65°. `overhead` ignores
+// the height. The old names (upper-left, upper-right) still answer, as top-left and top-right at
+// the middle height; `front` is the lamp at the viewer. (Not 'viewer': `light: 'viewer'` is the
+// Markets board's own flat, viewer-lit finish -- viewerLit below -- and a placement of that name
+// turned the whole block board flat-shaded, which the operator saw at once on 2026-09-16.)
+export const LIGHT_PLACES = Object.freeze({
+  'overhead': [0, 0], 'top-left': [-1, 1], 'top-right': [1, 1], 'bottom-left': [-1, -1], 'bottom-right': [1, -1], 'front': [0, -1],
+});
+export const LIGHT_HEIGHTS = Object.freeze({ low: 25, middle: 45, high: 65 });
+const LIGHT_ALIASES = Object.freeze({ 'upper-left': 'top-left', 'upper-right': 'top-right' });
+export function lampFor(place, height = 'middle') {
+  const p = LIGHT_PLACES[place] ?? LIGHT_PLACES['top-left'];
+  if (!p[0] && !p[1]) return { L: [0, 0, 1], side: [0, 0] };
+  const el = ((LIGHT_HEIGHTS[height] ?? 45) * Math.PI) / 180;
+  const n = Math.hypot(p[0], p[1]) || 1;
+  const ax = p[0] / n, ay = p[1] / n;
+  // the side faces take the lamp's direction across the screen (y down), weaker the higher it hangs
+  const k = 0.9 * Math.cos(el) / Math.cos((45 * Math.PI) / 180);
+  return { L: [ax * Math.cos(el), ay * Math.cos(el), Math.sin(el)], side: [ax * k, -ay * k] };
+}
 export const LIGHTS = Object.freeze({
-  'overhead': { L: [0, 0, 1], side: [0, 0] },
-  'upper-left': { L: [-0.55, 0.55, 0.63], side: [-0.7071, -0.7071] },
-  'upper-right': { L: [0.55, 0.55, 0.63], side: [0.7071, -0.7071] },
-  'front': { L: [0, -0.55, 0.63], side: [0, 0.9] },
+  'overhead': lampFor('overhead'),
+  'top-left': lampFor('top-left'), 'top-right': lampFor('top-right'), 'bottom-left': lampFor('bottom-left'), 'bottom-right': lampFor('bottom-right'), 'front': lampFor('front'),
+  'upper-left': lampFor('top-left'), 'upper-right': lampFor('top-right'),
 });
-export const LIGHT_DEFAULT = 'upper-left';
+export const LIGHT_DEFAULT = 'top-left';
+// the middle of the shipped brightness range: `lightGain` stretches the faces about this point
+const LIT_MID = 0.58;
 const NEON_HEX = /^#[0-9a-f]{6}$/i;
 export function lightOf(o = {}) {
-  return LIGHTS[o.light] ? o.light : o.overheadLight === true ? 'overhead' : LIGHT_DEFAULT;
+  const name = LIGHT_ALIASES[o.light] ?? o.light;
+  return LIGHT_PLACES[name] ? name : o.overheadLight === true ? 'overhead' : LIGHT_DEFAULT;
+}
+/** The lamp a board asks for: its placement at its height. */
+export function lampOf(o = {}) {
+  return lampFor(lightOf(o), LIGHT_HEIGHTS[o.lightHeight] ? o.lightHeight : 'middle');
 }
 export function domeLight(t, o = {}) {
   const { dome = 0, gridW = 0, gridH = 0 } = o;
   if (!dome || !gridW || !gridH) return 1;
-  const lamp = LIGHTS[lightOf(o)];
+  const lamp = lampOf(o);
   // straight above: the slope shades nothing -- the bottom rows, which lean away from a corner
   // lamp and sat at the 0.6 floor, read as bright as the middle
   if (lamp.L[0] === 0 && lamp.L[1] === 0) return 1;
@@ -912,8 +941,20 @@ export const FX_NONE = Object.freeze({ glow: 0, outline: 0, lift: 0, color: null
 // just outside one side of the board and leaving past the other
 export function fxFront(fx) {
   const qs = [0, fx.gridW * fx.dx, fx.gridH * fx.dy, fx.gridW * fx.dx + fx.gridH * fx.dy];
-  const lo = Math.min(...qs) - 4, hi = Math.max(...qs) + 4;
-  return lo + fx.u * (hi - lo);
+  // THE MARGIN IS THE PANEL'S, NOT A CONSTANT (operator, 2026-09-15: "It needs to cleanly travel on
+  // and off screen"). Four units clears the BOARD, and the panel reaches much further than that --
+  // measured 21.8 units beyond a 96-wide board -- so a front that started four units out began its
+  // sweep in plain view and ended it there. render3d measures the real overhang from the viewRect
+  // and puts it on `fx.margin`; four is the fallback for a caller with no panel (tests).
+  const m = fx.margin ?? 4;
+  const lo = Math.min(...qs) - m, hi = Math.max(...qs) + m;
+  // A SEARCHLIGHT PANS (operator, 2026-09-15: "the scanner needs to be more like a search light,
+  // slowly panning back and forth"). A single linear pass is a scanner; sweeping out and back is a
+  // light being AIMED, which is what reads as something looking for things. `pan` is set for the
+  // top-down board only -- on the price chart the camera is low and one pass along the hours is
+  // the right motion.
+  const t = fx.pan ? 1 - Math.abs(((fx.u * 2) % 2) - 1) : fx.u;
+  return lo + t * (hi - lo);
 }
 
 // a deterministic 0..1 from an integer: where a firework bursts, which cube flares. Hashed, not
@@ -957,8 +998,26 @@ export function fxAt(t, fx) {
       return { glow: A * w, outline: 0.8 * A * w, lift: 0, color: [255, 255, 255] };
     }
     case 'scan': {
-      const w = g((along() - fxFront(fx)) / 1.6);
-      return { glow: 0.8 * A * w, outline: 0.5 * A * w, lift: 0, color: [120, 220, 255] };
+      // the beam's own width -- ten units, so a whole swath of blocks is lit as it passes
+      // (2026-09-15: "Reach more blocks with the scanner effect")
+      // THE LIGHT IS THE POINT (operator, 2026-09-15: "We really need to make it much more obvious
+      // somehow that the blocks are being illuminated"). The swath tracks the beam's own half-width
+      // (fx.beamR, set with the cone) so light and geometry cannot disagree, and it hits harder:
+      // a near-white glow, a bright outline and real lift, so a struck cube stands up out of the
+      // board rather than merely brightening.
+      const w = g((along() - fxFront(fx)) / (fx.beamR ?? 5.5));
+      return { glow: Math.min(1, 1.6 * A * w), outline: Math.min(1, 1.2 * A * w), lift: 1.4 * A * w, color: [225, 248, 255] };
+    }
+    case 'xray': {
+      // X-RAY (2026-09-15, operator: "Add xray as additional choosable effect"): a front sweeps the
+      // board and behind it every tile goes x-ray -- its body dims to glass and its edges and a
+      // raster across its faces light up (buildScene's xray treatment) -- then develops back to
+      // solid over a few units, the front itself a bright edge
+      const d = fxFront(fx) - along();                                // > 0 once the front has passed
+      const edge = g(d / 1.2);
+      const back = d > 0 && d < 9 ? (d < 5 ? 1 : 1 - (d - 5) / 4) : 0;
+      const xray = Math.max(edge, back) * A;
+      return xray > 0.02 ? { glow: 0.5 * A * edge, outline: A * Math.max(edge, 0.8 * back), lift: 0, color: [190, 240, 255], xray } : FX_NONE;
     }
     case 'ball': {
       // "illuminating everything it comes near": brightest right under the ball, gone ~5 units off
@@ -997,30 +1056,41 @@ export function fxAt(t, fx) {
       return { glow: hot * A * w, outline: 0.8 * hot * A * w, lift: (inward ? 0.4 : 3.2) * A * w,
         color: inward ? [150, 190, 255] : [255, 255, 245] };
     }
-    case 'firework': {
-      // three bursts, each at its own moment and place, each a ring that expands and dies
-      let glow = 0, outline = 0, lift = 0, col = [255, 200, 120];
-      for (let i = 0; i < 3; i++) {
-        const t0 = 0.05 + 0.26 * i, life = 0.45;
-        const v = (fx.u - t0) / life;
-        if (!(v > 0 && v < 1)) continue;
-        const bx = fxHash(fx.seed + i * 31 + 1) * fx.gridW, by = fxHash(fx.seed + i * 31 + 2) * fx.gridH;
-        const r = 9 * Math.pow(v, 0.55);
-        const w = g((Math.hypot(cx - bx, cy - by) - r) / 1.4) * (1 - v);
-        if (w > glow) {
-          glow = w; outline = 0.9 * w; lift = 1.8 * w;
-          col = [[255, 170, 110], [140, 220, 255], [220, 160, 255]][i];
-        }
-      }
-      return glow > 0.02 ? { glow: A * glow, outline: A * outline, lift: A * lift, color: col } : FX_NONE;
-    }
+    // 'firework' lights through fxNow's heads now (details3d fireworkShells): one head per live
+    // shell, in the shell's colour -- see the heads branch below
     case 'flare': {
       // one cube goes supernova and lights its neighbourhood -- the same hashed cube every replay
       const fxp = fxHash(fx.seed + 7) * fx.gridW, fyp = fxHash(fx.seed + 8) * fx.gridH;
       const bell = Math.sin(Math.PI * fx.u);
       const d = Math.hypot(cx - fxp, cy - fyp);
-      const w = g(d / (1.2 + 7 * bell)) * bell;
-      return w > 0.02 ? { glow: A * w, outline: 0.8 * A * w, lift: 1.4 * A * w, color: [255, 245, 205] } : FX_NONE;
+      // A SUPERNOVA'S LIGHT (2026-09-15, drawn in details3d drawSupernova): on a thin board -- the
+      // price board, eight deep -- the light reaches three times as far, so the chart is lit, and
+      // it cools with the remnant, gold to red to violet, after the white of the blast
+      const thin = fx.gridH <= 12;
+      const w = g(d / (1.2 + (thin ? 22 : 7) * bell)) * bell;
+      const cool = Math.max(0, Math.min(1, (fx.u - 0.2) / 0.8));
+      // white at the blast, then blue, then violet, as the cloud goes (details3d drawSupernova)
+      const col = cool < 0.3 ? [Math.round(255 - 105 * cool / 0.3), Math.round(255 - 60 * cool / 0.3), 255] : [Math.round(150 + 25 * (cool - 0.3) / 0.7), Math.round(195 - 85 * (cool - 0.3) / 0.7), 255];
+      // THE SHOCKWAVE THROWS WHAT IT CROSSES (operator, 2026-09-15: "Consider perturbing all the
+      // candles that are affected by the shockwave"): the ring drawn in drawSupernova (4.5 shell
+      // radii, out over u 0.14-0.6) runs through the tiles here too -- a tile it reaches is thrown
+      // up hard and lit white, and shakes itself out for a while after the front has passed
+      let lift = 1.4 * A * w, glow = A * w, outline = 0.8 * A * w, colour = col;
+      if (fx.u >= 0.14) {
+        const fr = Math.min(1, (fx.u - 0.14) / 0.46), ring = (thin ? 27 : 31) * (1 - Math.pow(1 - fr, 2.2));
+        const front = g((d - ring) / 1.8) * (1 - fr * 0.6);
+        const passed = ring - d;                              // > 0 once the front has gone by
+        // the shaking starts as the front APPROACHES, five units out, not once it has passed
+        // (operator: "trigger their shaking sooner in the blast radius")
+        const shake = passed > -5 && fx.u < 0.75 ? Math.max(0, Math.sin(fx.u * 70 + jitterOf(t.txid, 'sn' + fx.seed) * 6.28)) * Math.exp(-Math.max(0, passed) / 12) * (1 - (fx.u - 0.14) / 0.61) : 0;
+        if (front > 0.02 || shake > 0.02) {
+          lift = Math.max(lift, 0.5 * A * front + 0.12 * A * shake);   // a tenth of the first cut (operator: "affects the candles too much", "half as much still", "we really need to turn down the block shaking")
+          glow = Math.max(glow, A * front + 0.4 * A * shake);
+          outline = Math.max(outline, A * front);
+          if (front > w) colour = [255, 255, 255];
+        }
+      }
+      return glow > 0.02 || lift > 0.05 ? { glow: Math.min(1, glow), outline: Math.min(1, outline), lift, color: colour } : FX_NONE;
     }
     case 'wave': {
       // a swell rolling across the board: the cubes rise and fall with it, several crests at once
@@ -1125,6 +1195,9 @@ export function fxAt(t, fx) {
       const col = [Math.round(140 + 115 * ph), Math.round(90 + 140 * (1 - ph)), Math.round(190 + 60 * ph)];
       return { glow: 0.85 * A * w, outline: 0.2 * A * w, lift: 0, color: col };
     }
+    case 'pulse':        // the price line's surge lights the candles under its head (details3d fxNow)
+    case 'firework':     // each shell lights its surroundings in its colour (details3d fxNow)
+    case 'blackhole':    // the hole's head shrinks the candles it reaches toward nothing (scale) and lights the rest orange
     case 'lightcycle':
     case 'packets':
     case 'centipede':
@@ -1151,10 +1224,29 @@ export function fxAt(t, fx) {
           // the very fade that meant it was working. Measured: 0 cubes hidden over a whole run.
           // So the physical effect uses PROXIMITY alone and the visual effect keeps using w.
           const reach = g(Math.hypot(ddx, ddy) / Math.max(0.2, hd.r ?? 0.8));
+          // `release` (1 unless the head says otherwise): the head letting go of everything it
+          // holds, evenly -- the pull and the scale fade by it, so a tile under the head glides
+          // home over the head's whole release rather than when its reach finally passes it
+          const rel = hd.release ?? 1;
           best = {
             glow: 0.85 * w, outline: 0.8 * w, lift: (hd.lift ?? 0) * w, color: hd.color,
             hide: (hd.hide ?? 0) > 0 && reach > 0.45 ? 1 : 0,
-            scale: hd.scale == null ? 1 : 1 - (1 - hd.scale) * reach,
+            scale: hd.scale == null ? 1 : 1 - (1 - hd.scale) * reach * rel,
+            // `pull`: how hard the head drags this tile toward itself (the black hole; buildScene
+            // shears the faces toward the head's screen point by it)
+            pull: (hd.pull ?? 0) * reach * rel, pullAt: hd.pull ? { x: hd.x, y: hd.y, z: hd.z ?? 0 } : null,
+            // the pull at the head's full size (rPeak): the orbit is laid out against this, so it
+            // does not unwind as the head shrinks; the current pull only says how far along the
+            // line from home to that orbit the tile sits
+            pullPeak: (hd.pull ?? 0) * (hd.rPeak ? g(Math.hypot(ddx, ddy) / Math.max(0.2, hd.rPeak)) : reach),
+            // `lean`: how much the corners lean and stretch toward the head on top of the glide
+            // (1 on the price board; 0 on the block board, where the cubes are lifted out whole)
+            lean: hd.lean ?? 1,
+            // `shrink`: scale the footprint with the height, so the cube stays a cube as it goes
+            shrink: hd.shrink ? 1 : 0,
+            // `orbitR`: the head's reach in grid units -- buildScene lays the block board's orbits
+            // out at a fixed distance round the hole from it, rather than part-way home
+            orbitR: hd.r ?? 0,
           };
         }
       }
@@ -1208,7 +1300,7 @@ export function buildScene(tiles, o = {}) {
   // among equals the one further from the vanishing point first (its sides
   // lean outward, away from its nearer neighbours).
   const vx0 = o.vanishX ?? 0, vy0 = o.vanishY ?? 0;
-  const ordered = o.oblique && o.order === 'diagonal' ? diagonalOrder(tiles) : o.oblique ? obliqueOrder(tiles, o) : tiles.map((t) => (growth.has(t) ? { ...t, boost: growth.get(t) } : t))
+  const ordered = o.order === 'given' ? tiles.slice() : o.oblique && o.order === 'diagonal' ? diagonalOrder(tiles) : o.oblique ? obliqueOrder(tiles, o) : tiles.map((t) => (growth.has(t) ? { ...t, boost: growth.get(t) } : t))
     .map((t) => { const c = project(t.x + t.s / 2, t.y + t.s / 2, 0, o); return { t, top: (t.z ?? 0) + (t.floor ?? 0) + cubeHeight(t), d: Math.hypot(c.x - vx0, c.y - vy0) }; })
     // Under the oblique camera a cube reaches STRAIGHT UP from its footprint (measured: height
     // moves screen y only, grid x moves screen x only), so it can only cover blocks at smaller
@@ -1220,6 +1312,12 @@ export function buildScene(tiles, o = {}) {
   const ground = [];
   const air = [];
   const shadows = [];
+  // IN THE AIR, PAINTED LAST (operator, 2026-09-15, of the black hole on the block board: "There
+  // are too many collision errors happening"): a cube pulled off the board toward the hole was
+  // still painted in the board's own order, so it cut through the neighbours it was passing over.
+  // Its faces are moved to the end of the frame instead, the least-pulled first, so the ones
+  // nearest the hole are on top of everything
+  const pulled = new Map();
   let minX = Infinity, maxX = -Infinity, minY = Infinity, maxY = -Infinity;
   const note = (p) => {
     if (p.x < minX) minX = p.x;
@@ -1257,7 +1355,10 @@ export function buildScene(tiles, o = {}) {
   })).filter((e) => e.k > 0.01) : [];
   // the lamp's direction across the screen, for the side faces (LIGHTS); under the overhead
   // lamp every side takes the same light, a shade under the top
-  const lampSide = LIGHTS[lightOf(o)].side;
+  const lampSide = lampOf(o).side;
+  // the lamp's hardness and how bright the tops sit under it (see the side loop below)
+  const gain = Number.isFinite(o.lightGain) ? Math.max(0.2, Math.min(3, o.lightGain)) : 1;
+  const topLit = Number.isFinite(o.topLight) ? Math.max(0.1, Math.min(1.4, o.topLight)) : 0.8;
   for (const t of ordered) {
     const fxv = (t.z ?? 0) > 0.02 ? FX_NONE : fxAt(t, o.fx);
     // GONE FOR THE DURATION, not deleted: a hidden cube is skipped this frame and drawn again the
@@ -1266,10 +1367,70 @@ export function buildScene(tiles, o = {}) {
     // A SHORTER CUBE, the same way: `tall` on a copy. A collapse or a dig is a height override,
     // never an edit to the tile the board was built from.
     const sc = fxv.scale == null ? 1 : fxv.scale;
-    const shaped = sc < 0.999 ? { ...t, tall: Math.max(0.04, cubeHeight(t) * sc) } : t;
+    let shaped = sc < 0.999 ? { ...t, tall: Math.max(0.04, cubeHeight(t) * sc) } : t;
+    // a WHOLE smaller cube, not a plate, where the head asks for it (the black hole over the block
+    // board): the footprint shrinks about its centre with the height
+    if (sc < 0.999 && fxv.shrink) { const s2 = Math.max(0.08, t.s * Math.max(0.08, sc)); shaped = { ...shaped, x: t.x + (t.s - s2) / 2, y: t.y + (t.s - s2) / 2, s: s2 }; }
     // NEON is a flat cube: no facets, no crown -- solid faces and the tubes on their edges
     const f = tileFaces(fxv.lift > 0.001 ? { ...shaped, fxz: fxv.lift } : shaped, o, t.s >= facetMin && o.neon !== true);
-    const a = t.alpha ?? 1;
+    // SPAGHETTIFIED (operator, 2026-09-15: "the candles need to stretch and bend toward the hole
+    // before they shrink"): a tile within a pulling head's reach has its faces sheared toward the
+    // head's point on screen -- the top corners dragged hard, the base corners a little -- so it
+    // leans and lengthens toward the hole before the scale takes it. Each corner object is moved
+    // once, however many faces share it.
+    if (fxv.pull > 0.001 && fxv.pullAt) {
+      pulled.set(String(t.txid), fxv.pull);
+      // ...AND ORBITS (operator, 2026-09-15: "The chart bars need to cleanly orbit the disc"): the
+      // tile is swept round the hole along the disk's flow as it is drawn in -- its centre swings
+      // about the hole by an angle that grows with the pull and the clock, on a radius that
+      // shrinks with the pull, flattened toward the disk's plane -- and its corners lean and
+      // stretch toward the hole on top of that
+      const hp = project(fxv.pullAt.x, fxv.pullAt.y, fxv.pullAt.z, o);
+      // EVERY CORNER THE CUBE HAS, the bevel's inner quad included -- it was left at home while
+      // the top and sides moved, so a bevelled cube on the block board drew as a slab stretched
+      // from its old place to its new one (operator, 2026-09-15: "too much bad shearing"); the
+      // crown's points are projected later through f.P, which is shifted the same way below
+      const pts = [...f.top, ...f.sides.flatMap((sd) => sd.points), ...(f.inset ?? [])];
+      const uniq = [...new Set(pts)];
+      const cx0 = uniq.reduce((a, p) => a + p.x, 0) / uniq.length, cy0 = uniq.reduce((a, p) => a + p.y, 0) / uniq.length;
+      // THE ORBIT IS LAID OUT AGAINST THE HOLE'S FULL SIZE, and the tile sits somewhere on the
+      // straight line between its home and that orbit by the CURRENT pull (operator, 2026-09-15:
+      // "Instead of the bars reversing into place, can they just reorient themselves into their
+      // original positions when the blackhole starts to disappear?"). While the hole grows the
+      // tile glides out to its orbit and turns with it; while it shrinks the pull falls and the
+      // tile glides straight home -- the orbit never unwinds.
+      // STEADILY (operator, 2026-09-15: "The bars don't cleanly leave or return ... They sorta get
+      // ripped off, and snapped back into place"): the capture and the release are eased with a
+      // smoothstep, and the orbit is KEPLERIAN -- its angular speed goes with the square of the
+      // pull, so a bar far out barely turns and one close in whips round -- where before every
+      // bar's target swept a wide circle at one speed and a bar just being caught was yanked after
+      // it. The angle's starting offset is small for the same reason.
+      const peak = Math.max(fxv.pullPeak ?? fxv.pull, 0.001), kl = Math.min(1, fxv.pull / peak), k0 = kl * kl * (3 - 2 * kl);
+      const dx = cx0 - hp.x, dy = cy0 - hp.y, r0 = Math.hypot(dx, dy) || 1, a0 = Math.atan2(dy, dx);
+      // HALF THE SPEED (operator, 2026-09-15: "The bars sping around much much too quickly. Try to
+      // calm it down by at least half to start" -- then "slow the spin ... by another half. Want it
+      // smoother and calmer"): 0.00035 a millisecond at full pull, a quarter of the 0.0014 it was
+      const swing = peak * peak * (o.now ?? 0) * 0.00035 + 0.5 * peak;   // clockwise on screen, Keplerian
+      // ROUND THE HOLE, on the block board (operator, 2026-09-15: "the blocks don't look right"):
+      // part-way home from a hole twenty units up left the cubes hanging in the middle distance;
+      // each is carried instead to its own ring round the hole, one and a half to three reaches
+      // out in screen pixels, and glides straight back from it as the pull falls
+      const ring = fxv.lean === 0 && fxv.orbitR > 0 && o.unit ? fxv.orbitR * o.unit * (1.5 + 1.5 * fxHash(Math.round(t.x * 31 + t.y * 7 + 3))) : null;
+      const r1 = ring != null ? r0 + (ring - r0) * peak : r0 * (1 - 0.55 * peak), a1 = a0 + swing;
+      const cx1 = hp.x + Math.cos(a1) * r1, cy1 = hp.y + Math.sin(a1) * r1 * (1 - 0.6 * peak);      // flattened toward the disk
+      const sx = (cx1 - cx0) * k0, sy = (cy1 - cy0) * k0;
+      const tops = new Set([...f.top, ...f.sides.flatMap((sd) => [sd.points[0], sd.points[1]])]);
+      for (const p of uniq) {
+        p.x += sx; p.y += sy;                                           // carried toward, and round, the orbit
+        const k = (tops.has(p) ? 0.55 : 0.2) * peak * k0 * (fxv.lean ?? 1);   // and leaning in (not on the block board: lean 0)
+        p.x += (hp.x - p.x) * k; p.y += (hp.y - p.y) * k;
+      }
+      const P0 = f.P, kc = 0.55 * peak * k0 * (fxv.lean ?? 1);
+      f.P = (x, y, z) => { const p = P0(x, y, z); const q = { x: p.x + sx, y: p.y + sy }; q.x += (hp.x - q.x) * kc; q.y += (hp.y - q.y) * kc; return q; };
+    }
+    // an x-rayed tile's body is glass: most of its alpha goes, and its edges come back below
+    const xray = fxv.xray ?? 0;
+    const a = (t.alpha ?? 1) * (1 - 0.72 * xray);
     const airborne = (t.z ?? 0) > 0.02;
     const out = airborne && !o.oblique ? air : ground;
     // A tile that just locked flashes brighter for a moment -- the Tetris
@@ -1388,11 +1549,19 @@ export function buildScene(tiles, o = {}) {
       // brighter, one turned away falls into shadow
       const d = side.nx * lampSide[0] + side.ny * lampSide[1];
       // from the viewer: a face pointing down the screen (toward the camera) takes the most light
-      const k = viewerLit ? 0.6 + 0.42 * Math.max(0, side.ny) + 0.3 * Math.max(0, side.nx) - 0.16 * Math.max(0, -side.nx) : 0.34 + 0.26 * (d + 1);
+      const k0 = viewerLit ? 0.6 + 0.42 * Math.max(0, side.ny) + 0.3 * Math.max(0, side.nx) - 0.16 * Math.max(0, -side.nx) : 0.34 + 0.26 * (d + 1);
+      // HOW HARD THE LAMP IS (operator, 2026-09-16: "we need better lighting on the front of the
+      // blocks. Still looks too washed out and not illuminated well enough"). The shipped range put
+      // every face between 0.34 and 0.86 of its colour with the top at 0.8: a narrow band, and a
+      // board of it reads as tinted rather than lit. `lightGain` stretches that range about its
+      // middle -- above 1 the face turned to the lamp goes brighter than its own colour and the one
+      // turned away falls properly dark. 1 is exactly what every board drew before this.
+      const k = Math.max(0.06, Math.min(1.4, LIT_MID + (k0 - LIT_MID) * gain));
       out.push({ txid: t.txid, face: 'side', key: side.key, points: side.points, fill: shade(c, k * lit, a), ...(viewerLit ? { stroke: lift(c, 0.45, round3(0.5 * a)) } : {}) });
       side.points.forEach(note);
     }
-    out.push({ txid: t.txid, face: 'top', points: f.top, fill: shade(c, (viewerLit ? 1.02 : 0.8) * lit, a), stroke: viewerLit ? lift(c, 0.55, round3(0.6 * a)) : `rgba(0,0,0,${round3(seam * a)})` });
+    const topK = viewerLit ? 1.02 : Math.max(0.06, Math.min(1.4, LIT_MID + (topLit - LIT_MID) * gain));
+    out.push({ txid: t.txid, face: 'top', points: f.top, fill: shade(c, topK * lit, a), stroke: viewerLit ? lift(c, 0.55, round3(0.6 * a)) : `rgba(0,0,0,${round3(seam * a)})` });
     f.top.forEach(note);
 
     if (f.innerG && !viewerLit) {
@@ -1582,6 +1751,23 @@ export function buildScene(tiles, o = {}) {
     // a tint at the top's weight (0.5) was there in the pixels and nowhere to the eye (measured:
     // the scan's peak moved a candle's face by a 0.26 cyan wash). At 0.85 it reads as struck.
     if (pulse > 0.03 && o.axes) for (const side of f.sides) out.push({ txid: t.txid, face: 'glow', points: side.points, fill: `rgba(${fxv.color.join(',')},${round3(0.85 * pulse * a)})` });
+    // THE X-RAY TREATMENT: bright edges round every face, and a raster of thin lines across the top
+    // and the sides, so the tile reads as a wireframe scan of itself
+    if (xray > 0.02) {
+      const xc = `rgba(200,245,255,${round3(0.95 * xray)})`;
+      out.push({ txid: t.txid, face: 'outline', points: f.top, fill: 'rgba(0,0,0,0)', stroke: xc, lw: 1.2, always: true });
+      for (const side of f.sides) out.push({ txid: t.txid, face: 'outline', points: side.points, fill: 'rgba(0,0,0,0)', stroke: xc, lw: 1.2, always: true });
+      const raster = (poly) => {
+        const [p0, p1, p2, p3] = poly;                                 // p0->p1 and p3->p2 are the edges the lines run between
+        for (let i = 1; i <= 3; i++) {
+          const u = i / 4;
+          const a0 = { x: p0.x + (p3.x - p0.x) * u, y: p0.y + (p3.y - p0.y) * u }, b0 = { x: p1.x + (p2.x - p1.x) * u, y: p1.y + (p2.y - p1.y) * u };
+          out.push({ txid: t.txid, face: 'outline', points: [a0, b0], fill: 'rgba(0,0,0,0)', stroke: `rgba(160,230,255,${round3(0.45 * xray)})`, lw: 0.8, always: true });
+        }
+      };
+      raster(f.top);
+      for (const side of f.sides) raster(side.points);
+    }
     if (fxv.outline > 0.03) {
       const col = fxv.color.join(',');
       out.push({ txid: t.txid, face: 'outline', points: f.top, fill: 'rgba(0,0,0,0)', stroke: `rgba(${col},${round3(0.95 * fxv.outline * a)})`, lw: 1 + 4 * fxv.outline });
@@ -1630,7 +1816,13 @@ export function buildScene(tiles, o = {}) {
       if (o.oblique && !viewerLit && zt < 1.5) shadows.push(...restingShadowOps(t, o, 1 - zt / 1.5));
     }
   }
-  const ops = o.oblique ? [...shadows, ...ground] : [...ground, ...shadows, ...air];
+  let ops = o.oblique ? [...shadows, ...ground] : [...ground, ...shadows, ...air];
+  if (pulled.size) {
+    const rest = [], lifted = [];
+    ops.forEach((op, i) => (pulled.has(String(op.txid)) ? lifted : rest).push({ op, i }));
+    lifted.sort((p, q) => (pulled.get(String(p.op.txid)) - pulled.get(String(q.op.txid))) || (p.i - q.i));
+    ops = [...rest.map((e) => e.op), ...lifted.map((e) => e.op)];
+  }
   return { ops, bounds: ops.length ? { minX, maxX, minY, maxY } : null, count: ordered.length };
 }
 

package/public/js/charts.js

@@ -12,12 +12,11 @@
 // old chart and calling it current is the same sin as inventing a number, so the
 // pill says how old it is.
 const M = { top: 8, right: 10, bottom: 18, left: 46 };
-const COL = {
-  grid: '#20252d', axis: '#2c323c', text: '#6a7484', textDim: '#4d5665',
-  accent: '#f7931a', ok: '#2ecc8f', warn: '#f0b429', bad: '#ef5a5a',
-  info: '#58a6ff', purple: '#a78bfa', cyan: '#4dd0e1', pink: '#f06ba7',
-};
-const PALETTE = [COL.accent, COL.info, COL.ok, COL.purple, COL.cyan, COL.pink, COL.warn, COL.bad];
+// THE COLOURS COME FROM THE THEME (theme.js, 2026-09-16): COL is the theme module's live object,
+// refilled when the operator picks a theme, and the chrome colours below read INK the same way --
+// a chart painted from literals of the dark look was unreadable on a light card.
+import { COL, INK } from './theme.js';
+const palette = () => [COL.accent, COL.info, COL.ok, COL.purple, COL.cyan, COL.pink, COL.warn, COL.bad];
 
 function prep(canvas) {
   const dpr = Math.min(window.devicePixelRatio || 1, 2);
@@ -64,7 +63,7 @@ export function resetCanvas(canvas) {
 export function empty(canvas, msg = 'no data from the node yet') {
   if (canvas.__hasData) { markStale(canvas, msg); return; }
   const { ctx, w, h } = prep(canvas);
-  ctx.fillStyle = '#4d5665';
+  ctx.fillStyle = INK.textDim;
   ctx.textAlign = 'center';
   ctx.fillText(msg, w / 2, h / 2);
   ctx.textAlign = 'left';
@@ -83,8 +82,8 @@ export function markStale(canvas, msg = 'no fresh samples') {
   const tw = ctx.measureText(label).width;
   const pw = tw + 20;
   const x = Math.max(4, w - pw - 6);
-  ctx.fillStyle = '#12151a';
-  ctx.strokeStyle = '#3d4552';
+  ctx.fillStyle = INK.panel;
+  ctx.strokeStyle = INK.panelLine;
   ctx.lineWidth = 1;
   ctx.beginPath();
   ctx.roundRect(x, 4, pw, 16, 5);
@@ -94,7 +93,7 @@ export function markStale(canvas, msg = 'no fresh samples') {
   ctx.beginPath();
   ctx.arc(x + 9, 12, 3, 0, 7);
   ctx.fill();
-  ctx.fillStyle = '#b9c3d1';
+  ctx.fillStyle = INK.label;
   ctx.textAlign = 'left';
   ctx.fillText(label, x + 15, 12);
 }
@@ -205,7 +204,8 @@ export function lineChart(canvas, series, opts = {}) {
 
   for (let si = 0; si < pts.length; si++) {
     const s = pts[si];
-    const color = s.color ?? PALETTE[si % PALETTE.length];
+    const pal = palette();
+    const color = s.color ?? pal[si % pal.length];
     const yOf = s.axis === 'right' ? Y2 : (opts.logY ? (v) => logY(v, lo, hi, L, plotH) : Y);
     const sorted = s.points.slice().sort((a, b) => a.t - b.t);
 
@@ -318,15 +318,15 @@ function attachLineTip(canvas, opts) {
     if (!rows.length) return hideTip(canvas);
     redraw(canvas);
     const { ctx } = ctxOf(canvas);
-    ctx.strokeStyle = '#ffffff30';
+    ctx.strokeStyle = INK.faintLine;
     ctx.beginPath(); ctx.moveTo(nearX, c.L.top); ctx.lineTo(nearX, c.L.top + c.plotH); ctx.stroke();
     const fmt = opts.fmtTip ?? ((v, s) => short(v));
     const boxW = 118;
     const boxH = 14 + rows.length * 12;
     const bx = Math.min(c.w - boxW - 4, nearX + 8);
     const by = c.L.top + 4;
-    ctx.fillStyle = '#0c0e11e8';
-    ctx.strokeStyle = '#2c323c';
+    ctx.fillStyle = INK.tip;
+    ctx.strokeStyle = INK.tipLine;
     ctx.beginPath(); ctx.roundRect(bx, by, boxW, boxH, 5); ctx.fill(); ctx.stroke();
     ctx.textAlign = 'left';
     ctx.fillStyle = COL.text;
@@ -335,11 +335,11 @@ function attachLineTip(canvas, opts) {
       const y = by + 20 + i * 12;
       ctx.fillStyle = row.color;
       ctx.fillRect(bx + 6, y - 3, 6, 2);
-      ctx.fillStyle = '#c7cfdb';
+      ctx.fillStyle = INK.tipText;
       const label = (row.label || '').slice(0, 12);
       ctx.fillText(label, bx + 16, y - 2);
       ctx.textAlign = 'right';
-      ctx.fillStyle = '#e8edf5';
+      ctx.fillStyle = INK.bright;
       ctx.fillText(fmt(row.v, row), bx + boxW - 6, y - 2);
       ctx.textAlign = 'left';
     });
@@ -512,7 +512,7 @@ export function meter(canvas, { value, max, label, danger = 0.9, fmt }) {
   const a1 = Math.PI * 2;
   ctx.lineWidth = Math.max(7, r * 0.34);
   ctx.lineCap = 'butt';
-  ctx.strokeStyle = '#171b21';
+  ctx.strokeStyle = INK.panel;
   ctx.beginPath(); ctx.arc(cx, cy, r, a0, a1); ctx.stroke();
   // the region past which the node starts feerate-evicting
   ctx.strokeStyle = hexA(COL.bad, 0.5);
@@ -520,7 +520,7 @@ export function meter(canvas, { value, max, label, danger = 0.9, fmt }) {
   const col = pct >= danger ? COL.bad : pct > 0.75 ? COL.warn : COL.ok;
   ctx.strokeStyle = col;
   ctx.beginPath(); ctx.arc(cx, cy, r, a0, a0 + Math.PI * Math.min(1, pct)); ctx.stroke();
-  ctx.fillStyle = '#e8edf5';
+  ctx.fillStyle = INK.bright;
   ctx.textAlign = 'center';
   ctx.font = '600 17px ui-monospace, monospace';
   ctx.fillText(`${((value / max) * 100).toFixed(1)}%`, cx, cy - 4);
@@ -556,12 +556,12 @@ export function stackedBars(canvas, rows, opts = {}) {
     ctx.fillStyle = COL.text;
     ctx.textAlign = 'right';
     ctx.fillText(String(r.label ?? '').slice(0, 20), L.left - 6, y + rowH / 2);
-    ctx.fillStyle = '#12151a';
+    ctx.fillStyle = INK.panel;
     ctx.fillRect(L.left, y + 2, plotW, rowH - 5);
     const bw = (r.value / max) * plotW;
     ctx.fillStyle = r.color ?? COL.accent;
     ctx.fillRect(L.left, y + 2, Math.max(1, bw), rowH - 5);
-    ctx.fillStyle = '#e8edf5';
+    ctx.fillStyle = INK.bright;
     ctx.textAlign = 'left';
     ctx.fillText(String(r.display ?? short(r.value)), L.left + Math.min(bw + 5, plotW - 40), y + rowH / 2);
   });
@@ -632,4 +632,4 @@ function hexA(hex, a) {
 }
 function clampN(v, lo, hi) { return Math.max(lo, Math.min(hi, v)); }
 
-export { COL, PALETTE };
+export { COL, palette };