@descix/frqtl-node 0.0.0-stage → 0.6.0-p0.1

package/dist/frqtl/parts/index.js

@@ -0,0 +1,33 @@
+/* Copyright 2023-2026 by Essam Abadir */
+
+/**
+ * parts/index.js — THE parts barrel (@descix/frqtl-web/parts): one export per file in this
+ * directory, named by the file. The directory IS the roster — a part joins by being a file here,
+ * and the barrel lists exactly the directory (lib/frqtl/parts/test/barrel-equals-directory.test.mjs).
+ *
+ * Importing it registers every published kind in this realm (each part module registers its own
+ * kind with objects/kinds.js when it evaluates).
+ */
+
+export { CameraControls } from './CameraControls.js';
+export { CameraPath } from './CameraPath.js';
+export { CollisionActions } from './CollisionActions.js';
+export { CollisionTypes } from './CollisionTypes.js';
+export { DetectorWall } from './DetectorWall.js';
+export { FrqtlControlOverlay } from './FrqtlControlOverlay.js';
+export { FrqtlControlsPanel } from './FrqtlControlsPanel.js';
+export { FrqtlVision } from './FrqtlVision.js';
+export { GraphingDetectorWall } from './GraphingDetectorWall.js';
+export { LargeObject } from './LargeObject.js';
+export { LightColor } from './LightColor.js';
+export { LiveChart } from './LiveChart.js';
+export { LogicGate } from './LogicGate.js';
+export { OvenBox } from './OvenBox.js';
+export { PointSource } from './PointSource.js';
+export { Rectangle } from './Rectangle.js';
+export { SlitLightSource } from './SlitLightSource.js';
+export { SlitScreen } from './SlitScreen.js';
+export { SphereEmitter } from './SphereEmitter.js';
+export { Trace } from './Trace.js';
+export { Tunnel } from './Tunnel.js';
+export { Wall } from './Wall.js';

package/dist/frqtl/scenes/absorbing-wall-3d.js

@@ -0,0 +1,33 @@
+/* Copyright 2023-2026 by Essam Abadir */
+
+/**
+ * SCENE — 1B · Absorbing Wall (3D)
+ *
+ * A sketch file: the WHOLE scene as one ES module, `export default function buildExperiment(exp)`. The world
+ * (its co-init call, `exp.createCanvas` / `exp.createScene` — the one place its size is written),
+ * the parts (`exp.addObject`) and the render intent are all here; the sugar
+ * objects, renderer and engine are imports. Registered by lib/shim/registry/walkthrough.js
+ * (rung cl1b-absorbing-wall-3d).
+ */
+
+import { SphereEmitter } from '@descix/frqtl-web/parts';
+
+export default function buildExperiment(exp) {
+  // Collision Lab 1B · 3D — a volumetric (spherical) source into a 3D ABSORB wall
+  // slab (z-slab centered on 0 so the 3D spray collides); orbit the camera to view.
+  var W = 600, H = 400;   // THE WORLD this scene states (its co-init call below)
+  var cy = Math.round(H / 2);
+  var SRC = {
+    preset: 'spherical', is2D: false, center: [Math.round(W * 0.15), cy],
+    chargeMode: 'random', fundamentalDimension: 2, wavelength: 32,
+    burstSize: 24, emitEveryTicks: 1
+  };
+  exp.createScene(W, H, 600, SphereEmitter.worldCfg(SRC));   // THE WORLD: a 3D scene + universe, 600x400x600 — first, then parts
+  exp.addObject('SphereEmitter', SRC);
+  exp.addObject('Wall', {
+    rect: [Math.round(W * 0.6), Math.round(H * 0.2), 20, Math.round(H * 0.6)],
+    z: -80, depth: 160,
+    collisionBehavior: 'absorb', capacity: 64,
+    name: 'absorber', color: [150, 90, 210]
+  });
+}

package/dist/frqtl/scenes/absorbing-wall.js

@@ -0,0 +1,32 @@
+/* Copyright 2023-2026 by Essam Abadir */
+
+/**
+ * SCENE — 1B · Absorbing Wall
+ *
+ * A sketch file: the WHOLE scene as one ES module, `export default function buildExperiment(exp)`. The world
+ * (its co-init call, `exp.createCanvas` / `exp.createScene` — the one place its size is written),
+ * the parts (`exp.addObject`) and the render intent are all here; the sugar
+ * objects, renderer and engine are imports. Registered by lib/shim/registry/walkthrough.js
+ * (rung cl1b-absorbing-wall).
+ */
+
+import { SphereEmitter } from '@descix/frqtl-web/parts';
+
+export default function buildExperiment(exp) {
+  // Collision Lab 1B (Absorbing Wall) — ABSORB v2 (Track A): the wall LO is backed by
+  // a REAL leaf frame; a host tick-fn tallies the killed masses into it + radiates.
+  var W = 600, H = 400;   // THE WORLD this scene states (its co-init call below)
+  var cy = Math.round(H / 2);
+  var SRC = {
+    preset: 'spherical', is2D: true, center: [Math.round(W * 0.15), cy],
+    chargeMode: 'random', fundamentalDimension: 2, wavelength: 32,
+    burstSize: 24, emitEveryTicks: 1
+  };
+  exp.createCanvas(W, H, SphereEmitter.worldCfg(SRC));   // THE WORLD: a 2D canvas + universe — first, then parts
+  exp.addObject('SphereEmitter', SRC);
+  exp.addObject('Wall', {
+    rect: [Math.round(W * 0.6), Math.round(H * 0.2), 20, Math.round(H * 0.6)],
+    collisionBehavior: 'absorb', capacity: 64,
+    name: 'absorber', color: [150, 90, 210]
+  });
+}

package/dist/frqtl/scenes/atomic-model.js

@@ -0,0 +1,88 @@
+/* Copyright 2023-2026 by Essam Abadir */
+
+/**
+ * SCENE — Atomic model
+ *
+ * A sketch file: the WHOLE scene as one `export default function buildExperiment(exp)` module. The
+ * world and the three-level frame hierarchy are built here from the engine's own primitives (leaf
+ * frames — `engine().Frame`, read when the scene builds — and parent frames from a rect). Registered by
+ * lib/shim/registry/walkthrough.js (rung atomic-model).
+ *
+ * Physics (zero new — bench H1, A1, A2, M1, M4): 48 one-pixel quarks fill an 8x8 proton frame; the
+ * proton and one electron sit in a 64x64 atom frame. There is no force equation. Each parent's
+ * compress() pulls its children one pixel toward its centre each tick (A1: a stationary parent
+ * CONFINES a child), a parent's motion is carried by its children (A2), a parent's mass is its
+ * child count (H1), and its wavelength is capacity/mass (M4) — 64/48 → the proton's oscillation.
+ * The atom is stationary: the lab frame. `bonding` (noEscape) traps each quark in its parent's
+ * live rect, so the nucleus holds together: binding emerges from compress, not from a law.
+ *
+ * Order (it seeds the run): world → the three layers → quarks (grid-filled, registered) → proton
+ * from its rect → electron (registered) → atom from its rect → electron into the atom.
+ */
+
+import { Rectangle } from '@descix/frqtl-web/parts';
+import * as OrbitBag from '@descix/frqtl-web/compat/renderer/orbit-bag.js';
+import { engine } from '@descix/frqtl-web/compat/engine.js';
+
+export default function buildExperiment(exp) {
+  var W = 600, H = 600;          // THE WORLD this scene states (its co-init call below)
+
+  var QUARK_LAYER = 0;        // 1x1 leaves
+  var SUBATOMIC_LAYER = 3;    // the proton: 8x8, capacity 64
+  var ATOM_LAYER = 6;         // the atom: 64x64, capacity 4096
+  var QUARKS_PER_PROTON = 48; // the proton's mass at t=0 → wavelength 64/48
+
+  // ── WORLD — a 2D canvas + universe: quark layer fundamental, λ multiplier 1, quarks confined ──
+  exp.createCanvas(W, H, { dimension: QUARK_LAYER, wavelengthScale: 1, bonding: true });
+  var u = exp.universe;
+
+  var quarkDim = u.addDimension(QUARK_LAYER);
+  var subatomicDim = u.addDimension(SUBATOMIC_LAYER);
+  var atomDim = u.addDimension(ATOM_LAYER);
+  var subatomicW = subatomicDim.mb_w, atomW = atomDim.mb_w;
+
+  var Frame = engine().Frame, Charge = engine().Charge;   // the engine's own frame primitive + charge ABI
+  var cx = Math.round(W / 2), cy = Math.round(H / 2);
+  var atomRect = new Rectangle(cx, cy, atomW, atomW, null, true);
+  var protonRect = new Rectangle(cx, cy, subatomicW, subatomicW, null, true);
+  var rect = exp.runner.canvas_rect;
+
+  // ── QUARKS — fill the proton rect column by column ─────────────────────
+  var quarkW = Math.max(1, Math.pow(2, QUARK_LAYER));
+  var quarks = [];
+  for (var x = protonRect.left; x < protonRect.left + protonRect.w && quarks.length < QUARKS_PER_PROTON; x += quarkW) {
+    for (var y = protonRect.top; y < protonRect.top + protonRect.h && quarks.length < QUARKS_PER_PROTON; y += quarkW) {
+      var q = Frame.makeLeafFrame(x, y, QUARK_LAYER, 1, 0, 0, false, Charge.POSITIVE, rect);
+      q.name = 'quark_' + quarks.length;
+      quarks.push(q);
+    }
+  }
+  for (var i = 0; i < quarks.length; i++) { quarkDim.addFrame(quarks[i]); }
+
+  // ── PROTON — the parent frame of the quarks ────────────────────────────
+  var proton = subatomicDim.createFrameFromRect(protonRect, quarks, 0, 0);
+  proton.name = 'proton';
+
+  // ── ELECTRON — one negative leaf, upper-right of the atom ──────────────
+  var electron = Frame.makeLeafFrame(atomRect.left + Math.round(atomW * 0.75), atomRect.top + Math.round(atomW * 0.25),
+                                     QUARK_LAYER, 1, 0, 0, false, Charge.NEGATIVE, rect);
+  electron.name = 'electron';
+  quarkDim.addFrame(electron);
+
+  // ── ATOM — stationary parent of the proton; the electron joins directly ─
+  var atom = atomDim.createFrameFromRect(atomRect, [proton], 0, 0, true, true);
+  atom.name = 'atom';
+  atom.insert(electron);
+
+  u.leafQuantaWidth = quarkW;
+  u.brownianMotion = true;
+
+  // ── VIEW — frame the atom (render only: the 2D camera's `distance` is the visible physics-px
+  //    height). The atom is 64 px in the world; at 1.5x its width it fills two thirds of the view,
+  //    so the proton, its quarks and the electron are individually legible. ─────────────────────
+  var cam = exp.runner.cameraControl;
+  var flat = !OrbitBag.hasAngularPose(cam);
+  if (cam && typeof cam.setOrbit === 'function' && flat) {
+    cam.setOrbit({ target: { x: cx, y: cy }, distance: Math.round(atomW * 1.5) });
+  }
+}

package/dist/frqtl/scenes/big-bang.js

@@ -0,0 +1,46 @@
+/* Copyright 2023-2026 by Essam Abadir */
+
+/**
+ * SCENE — Big Bang
+ *
+ * A sketch file: the WHOLE scene as one ES module, `export default function buildExperiment(exp)`. The world and the
+ * point source are built here; the sugar (PointSource — deprecated V1 sugar, byte-identical), the
+ * renderer and the engine are imports. Registered by lib/shim/registry/walkthrough.js (rung big-bang).
+ *
+ * Physics (zero new — bench M1, H1, H2a-c): one radial burst at the canvas centre — 72 rays (5°) at
+ * radii 32 → 2 — of leaves with NO initial momentum (emergentPhysics). The world generates parent
+ * frames top-down (by how many frames an area can parent, brownian on), so a uniform field clumps into
+ * filaments and voids with no gravity law and no cosmological constant. The source shuts off after
+ * 20 s of ticks (1200).
+ *
+ * Order (it seeds the run): world (with its parent-generation interval) → source → the shut-off tick-fn.
+ */
+
+import { PointSource } from '@descix/frqtl-web/parts';
+
+export default function buildExperiment(exp) {
+  var W = 600, H = 600;          // THE WORLD this scene states (its co-init call below)
+
+  var SOURCE_DIAMETER = 64;     // emission radii 32 → 2 (step 2)
+  var ANGLE_STEP = 5;           // degrees between rays → 72 rays
+  var EMIT_TICKS = 20 * 60;     // the source fires for 1200 ticks
+
+  // ── WORLD — a 2D canvas + universe: fundamental layer 0, λ multiplier 1, parents top-down ──
+  // iframeIntervalSeconds 1/60: parents are generated EVERY tick (the engine freezes the interval at
+  // init, so it rides the world cfg — at the default 1 s, Phase B ran every 60 ticks).
+  exp.createCanvas(W, H, { dimension: 0, wavelengthScale: 1, frames: true, iframeIntervalSeconds: 1 / 60 });
+  var u = exp.universe;
+
+  // ── THE SOURCE — at the centre, no initial momentum, random charge ──────
+  var source = new PointSource(u, Math.floor(W / 2), Math.floor(H / 2), SOURCE_DIAMETER,
+                               0, null, true, Infinity, 0, ANGLE_STEP,
+                               { emergentPhysics: true, minRadius: 2 });
+
+  // ── SHUT-OFF — the bang is one burst era, then the field evolves on its own ──
+  var t = 0;
+  exp.addTickFunction(function () {
+    t++;
+    if (t >= EMIT_TICKS) { source.setActive(false); }
+    return [];
+  });
+}

package/dist/frqtl/scenes/blackbody.js

@@ -0,0 +1,81 @@
+/* Copyright 2023-2026 by Essam Abadir */
+
+/**
+ * SCENE — Blackbody
+ *
+ * A sketch file: the WHOLE scene as one ES module, `export default function buildExperiment(exp)`. The world, the
+ * oven, its thermostat and the radiation sink are all constructed here; the sugar objects
+ * (OvenBox, LargeObject), the renderer and the engine are imports. Registered by
+ * lib/shim/registry/walkthrough.js (rung blackbody).
+ *
+ * Physics (zero new — composition of goldened behaviours): a cavity of absorbing walls holds a
+ * population of leaves; the OvenBox thermostat keeps the cavity's quanta near the TEMPERATURE
+ * target by emitting, and colliding leaves merge into parent frames (bench H2a–c,
+ * collide → merge → promote; `withInterQuantumCollisions`). A parent's fullness IS its frequency
+ * (wavelength = capacity/mass, bench M4), so what leaks out of the slit in the right wall is a
+ * spectrum of frame sizes — the emergent Planck-like curve — with no energy quanta assumed.
+ * Everything that escapes is absorbed by the sink at the right edge (the experiment boundary).
+ *
+ * Order matters (it seeds the run): the world, the brownian/collision flags, the quantum
+ * layer, the thermostat SLOT (reserved before the oven so the oven's own tick-fns run after it),
+ * the oven, the thermostat, the sink. Same calls, same order, same seed ⇒ the same RNG stream.
+ */
+
+import { CollisionActions, CollisionTypes, FrqtlControlOverlay, FrqtlControlsPanel, Rectangle } from '@descix/frqtl-web/parts';
+import * as ControlRegistry from '@descix/frqtl-web/shim/controls/registry.js';
+
+export default function buildExperiment(exp) {
+  var W = 600, H = 400;        // THE WORLD this scene states (its co-init call below)
+
+  var TEMPERATURE = 1500;      // target quanta inside the cavity (the knob below)
+  var QUANTUM_DIM = 3;         // the layer leaves promote into: an 8 px box edge, 64 cells of capacity in 2D
+  var BOX_FRACTION = 1 / 3;    // the cavity's outer box, as a fraction of the canvas
+  var WALL = 10;               // wall thickness (px)
+  var SLIT_HEIGHT = 60;        // the radiation slit in the right wall (px)
+  var SINK_DEPTH = 30;         // the absorbing strip at the right canvas edge (px)
+
+  // ── WORLD — a 2D canvas + universe, fundamental layer 0 (1x1 leaves), λ multiplier 1 ──
+  exp.createCanvas(W, H, { dimension: 0, wavelengthScale: 1 });
+  var u = exp.universe;
+  u.brownianMotion = true;
+  u.withInterQuantumCollisions = true;
+  u.addDimension(QUANTUM_DIM);
+
+  // ── THE OVEN — the cavity, centred on the canvas ────────────────────────
+  var outer = new Rectangle(Math.round(W / 2), Math.round(H / 2),
+                            Math.round(W * BOX_FRACTION), Math.round(H * BOX_FRACTION), null, true);
+  // The thermostat runs FIRST each tick: reserve its slot before the oven registers its own.
+  var thermostatSlot = u.experimentTickFunctions.length;
+  u.experimentTickFunctions.push(null);
+  var oven = exp.addObject('OvenBox', {
+    name: 'oven',
+    left: outer.left + WALL, top: outer.top + WALL,
+    width: outer.w - 2 * WALL, height: outer.h - 2 * WALL,
+    wallThickness: WALL, temperature: TEMPERATURE,
+    slitHeight: SLIT_HEIGHT,          // the slit is in the RIGHT wall (OvenBox's own slit side)
+    color: [120, 120, 120]
+  });
+  u.experimentTickFunctions[thermostatSlot] = oven.getTemperatureTickFunction();
+
+  // ── THE SINK — the experiment boundary on the slit side ─────────────────
+  exp.addObject('LargeObject', {
+    name: 'radiation_sink',
+    rect: { left: W - SINK_DEPTH, top: 0, w: SINK_DEPTH, h: H },
+    collision_type: CollisionTypes.NONE, actions: [CollisionActions.ABSORB],
+    reposition: 'closest', color: [0, 0, 0]
+  });
+
+  // ── THE KNOB — temperature, live (the oven's own thermostat target) ─────
+  var registry = ControlRegistry.makeControlRegistry();
+  registry.registerControls('blackbody', [
+    { kind: 'scalar', id: 'temperature', label: 'temperature (quanta)', min: 50, max: 8000, step: 50,
+      value: TEMPERATURE, fmt: function (v) { return String(v); },
+      onChange: function (v) { oven.setTemperature(v); },
+      place: { x: 0.02, y: 0.03 } }
+  ]);
+  // Chrome (a page only): expose the knobs to a host frame, and mount the overlay through the
+  // runner's ONE door (runner.controlHost) — before a canvas is mounted (a notebook pane) there is
+  // none, so the knobs stay in the exposed registry only.
+  FrqtlControlsPanel.exposeRegistry(registry, { runner: exp.runner });
+  if (exp.runner.controlHost) { FrqtlControlOverlay.mount(exp.runner, { registry: registry, name: 'blackbody' }); }
+}

package/dist/frqtl/scenes/circuit-sat.js

@@ -0,0 +1,127 @@
+/* Copyright 2023-2026 by Essam Abadir */
+
+/**
+ * SCENE — Circuit SAT (a half-adder)
+ *
+ * A sketch file: the WHOLE scene as one ES module, `export default function buildExperiment(exp)`. The world, the two
+ * logic gates, the four rail traces with their input emitters, the two grounded readouts, the live
+ * input knobs and the framing are all here; the sugar (LogicGate, Trace, SphereEmitter), the
+ * renderer and the engine are imports. Registered by lib/shim/registry/walkthrough.js (rung
+ * circuit-sat).
+ *
+ * Physics (zero new — bench LO1/LO6/LO7 + the Trace wiring): input A and input B are laser
+ * emitters that drive quanta down rail traces into an XOR gate (SUM) and an AND gate (CARRY). A
+ * gate's valve opens only when its two input ammeters read the logic it embodies, so the circuit
+ * SETTLES onto the half-adder's answer: SUM = A xor B, CARRY = A and B, read as the current on each
+ * grounded readout. No search algorithm runs.
+ *
+ * Order (it seeds the run): world → SUM gate → CARRY gate → per lane plan row,
+ * the rail trace then its emitter (switched to its input) → the two readouts.
+ */
+
+import { FrqtlControlOverlay, FrqtlControlsPanel, LogicGate, SphereEmitter, Trace } from '@descix/frqtl-web/parts';
+import * as ControlRegistry from '@descix/frqtl-web/shim/controls/registry.js';
+
+export default function buildExperiment(exp) {
+  var W = 760, H = 520;              // THE WORLD this scene states (its co-init call below)
+  var LEFT = 60, TOP = 15;           // the circuit's top-left
+  var RAIL = 6;                      // rail voltage: quanta per tick per input emitter
+  var LEAD = 24, READOUT = 24;       // input-rail and readout trace lengths
+  var INSET = 4;                     // each input emitter sits this far inside its rail's bore mouth
+  var STATE = { a: true, b: false };   // input A HIGH at start: SUM reads 1, CARRY reads 0
+
+  // The input emitter: a narrow 2D laser on the fundamental layer, random ± charge.
+  function emitterBag(center) {
+    var bag = { preset: 'laser', is2D: true, R: 24, orientationDeg: 0, emissionBoxSide: 0,
+                fundamentalDimension: 0, burstSize: RAIL, emitEveryTicks: 1, chargeMode: 'random' };
+    if (center) { bag.center = center; }
+    return bag;
+  }
+
+  // ── WORLD — a 2D canvas + universe; the emitter's own world (its worldCfg) ──
+  exp.createCanvas(W, H, SphereEmitter.worldCfg(emitterBag(null)));
+  var u = exp.universe;
+
+  var MIN = LogicGate.MINIMAL;                                  // bore 3 / wall 3 / length 20
+  var cell = LogicGate.cellSize(MIN.bore, MIN.wallThickness, MIN.length);
+  var gateOpts = { bore: MIN.bore, wallThickness: MIN.wallThickness, length: MIN.length, supplyVoltage: RAIL };
+
+  // ── THE GATES — SUM (XOR) above CARRY (AND) ─────────────────────────────
+  var sum = exp.addObject('LogicGate', Object.assign({ logic: 'XOR', left: LEFT, top: TOP, name: 'SUM', color: [200, 170, 70] }, gateOpts));
+  var carry = exp.addObject('LogicGate', Object.assign({ logic: 'AND', left: LEFT, top: TOP + cell.h, name: 'CARRY', color: [170, 200, 90] }, gateOpts));
+  var gates = { SUM: sum, CARRY: carry };
+
+  // ── THE INPUT RAILS — the lane plan: B and A are SWAPPED on CARRY (AND commutes; the swap buys
+  //    a lane pitch of separation between the two inputs) ──────────────────────────────────────
+  var LANES = [
+    { input: 'A', gate: 'SUM', port: 'inPortA' }, { input: 'B', gate: 'SUM', port: 'inPortB' },
+    { input: 'B', gate: 'CARRY', port: 'inPortA' }, { input: 'A', gate: 'CARRY', port: 'inPortB' }
+  ];
+  var rails = { A: [], B: [] }, parts = [];
+  LANES.forEach(function (row, i) {
+    var port = gates[row.gate][row.port], y = port[1];
+    var t = new Trace(u, { path: [[port[0] - LEAD, y], [port[0], y]], bore: MIN.bore,
+                           wallThickness: MIN.wallThickness, name: 'rail' + row.input + i, color: [90, 120, 200] });
+    var em = exp.addObject('SphereEmitter', Object.assign(emitterBag([t.inPort[0] + INSET, y]),
+                                                          { name: 'input' + row.input + i }));   // parked inside the bore mouth
+    em.setActive(row.input === 'A' ? STATE.a : STATE.b);
+    rails[row.input].push(em);
+    parts.push(t);
+  });
+
+  // ── THE READOUTS — grounded traces off each gate's outlet: their current IS the answer ──
+  function readout(gate, name) {
+    return new Trace(u, { path: [[gate.outPort[0], gate.outPort[1]], [gate.outPort[0] + READOUT, gate.outPort[1]]],
+                          bore: MIN.bore, wallThickness: MIN.wallThickness, ground: true, name: name, color: [60, 160, 220] });
+  }
+  var readouts = { SUM: readout(sum, 'SUM_out'), CARRY: readout(carry, 'CARRY_out') };
+  parts.push(readouts.SUM, readouts.CARRY);
+  parts.forEach(function (p) { p.attachToRunner(exp.runner); });   // every trace reads the tick stream (a declared gate subscribed at addObject)
+
+  function setInput(which, on) {
+    STATE[which] = !!on;
+    rails[which === 'a' ? 'A' : 'B'].forEach(function (em) { em.setActive(STATE[which]); });
+  }
+
+  // ── THE CIRCUIT, PUBLISHED — the parts and the geometry a harness reads (the half-adder
+  //    acceptance rig): each gate's own getState(), each readout's calibrated getDelivered(), the
+  //    input switch, and the layout values its settle budget is computed from. ───────────────
+  exp.circuit = {
+    gates: gates, readouts: readouts,
+    rails: rails, lanes: LANES, setInput: setInput,
+    lead: LEAD, readout: READOUT, inset: INSET
+  };
+
+  // ── THE VIEW — frame the 72x54 px circuit (render only: the 2D camera's distance IS the visible
+  //    physics-px height) ─────────────────────────────────────────────────────────────────────
+  var fp = [LEFT - LEAD, TOP, LEAD + cell.w + READOUT + 4, cell.h * 2];
+  var cam = exp.runner.cameraControl;
+  if (cam && typeof cam.setOrbit === 'function') {
+    cam.setOrbit({ target: { x: fp[0] + fp[2] / 2, y: fp[1] + fp[3] / 2 },
+                   distance: Math.max(fp[3] * 1.35, fp[2] * 1.35 * H / W) });
+  }
+
+  // ── THE KNOBS (on the canvas): the two inputs and the rail ──────────────
+  var registry = ControlRegistry.makeControlRegistry();
+  registry.registerControls('circuit-sat', [
+    { kind: 'scalar', id: 'inputA', label: 'input A', min: 0, max: 1, step: 1, value: STATE.a ? 1 : 0, widget: 'toggle',
+      fmt: function (v) { return v ? '1 (HIGH)' : '0 (LOW)'; }, onChange: function (v) { setInput('a', v); },
+      place: { x: 0.02, y: 0.80 } },
+    { kind: 'scalar', id: 'inputB', label: 'input B', min: 0, max: 1, step: 1, value: STATE.b ? 1 : 0, widget: 'toggle',
+      fmt: function (v) { return v ? '1 (HIGH)' : '0 (LOW)'; }, onChange: function (v) { setInput('b', v); },
+      place: { x: 0.02, y: 0.88 } },
+    { kind: 'scalar', id: 'rail', label: 'rail (burst/tick)', min: 1, max: 16, step: 1, value: RAIL,
+      fmt: function (v) { return String(v) + ' q/tick'; },
+      onChange: function (v) {
+        RAIL = Math.max(0, Math.round(v));
+        sum.setSupplyVoltage(RAIL); carry.setSupplyVoltage(RAIL);
+        rails.A.concat(rails.B).forEach(function (em) { em.setBurstSize(RAIL); });
+      },
+      place: { x: 0.30, y: 0.88 } }
+  ]);
+  // Chrome (a page only): expose the knobs to a host frame, and mount the overlay through the
+  // runner's ONE door (runner.controlHost) — before a canvas is mounted (a notebook pane) there is
+  // none, so the knobs stay in the exposed registry only.
+  FrqtlControlsPanel.exposeRegistry(registry, { runner: exp.runner });
+  if (exp.runner.controlHost) { FrqtlControlOverlay.mount(exp.runner, { registry: registry, name: 'circuit-sat' }); }
+}

package/dist/frqtl/scenes/collision-matrix-3d.js

@@ -0,0 +1,107 @@
+/* Copyright 2023-2026 by Essam Abadir */
+
+/**
+ * SCENE — 3D Collisions Lab
+ *
+ * A sketch file: the WHOLE scene as one ES module, `export default function buildExperiment(exp)`. The 3D world, the
+ * seven head-on lanes of equal-mass voxel pairs, their live knobs and the look are all here; the
+ * lane density table (`collisionMatrixLanes`), the renderer and the engine are imports.
+ * Registered by lib/shim/registry/walkthrough.js (rung collision-matrix-3d).
+ *
+ * Physics (zero new — bench C2, C3, C5, SU1): each lane fires two equal bodies at each other at
+ * speed_prob 1 along x; a lane's density (mass / capacity) sets how hard the bodies are — rigid
+ * bodies bounce cleanly, soft ones press into each other before parting. The lanes sit on a 3x3
+ * y/z grid, so the same contact happens at seven depths: collision is identical on any axis
+ * (2D ≡ 3D). The same engine that makes light makes mechanics — no second physics.
+ *
+ * Order (it seeds the run): world → collisions on → the voxel layer →
+ * per lane, body A then body B (engine-built, capacity read back once) → seat every body.
+ */
+
+import { CameraControls, FrqtlControlOverlay, FrqtlControlsPanel } from '@descix/frqtl-web/parts';
+import * as ControlRegistry from '@descix/frqtl-web/shim/controls/registry.js';
+import { collisionMatrixLanes } from '@descix/frqtl-web/objects/setup/_collisionMatrixLanes.js';
+
+export default function buildExperiment(exp) {
+  var W = 700, H = 700, D = 700;    // THE WORLD this scene states (its co-init call below)
+  var LEVEL = 6;                    // the voxel layer: 64 px bodies, capacity 4096
+
+  // ── WORLD — a 3D scene + universe W×H×D, fundamental layer 0, λ multiplier 1 ──
+  exp.createScene(W, H, D, { dimension: 0, wavelengthScale: 1 });
+  var u = exp.universe;
+  u.withInterQuantumCollisions = true;
+  u.addDimension(LEVEL);
+  exp.runner.setRateLimits({ tpsLimit: 240 });   // pacing only: wall-clock, never the ticks
+
+  var lanesTable = collisionMatrixLanes;   // the ONE lane density table (imported)
+  var voxel = Math.pow(2, LEVEL), half = voxel / 2;
+  var midX = Math.floor(W * 0.5);
+  var ax0 = midX - Math.floor(1.5 * voxel);       // body A, left of centre
+  var bx0 = midX + Math.floor(1.5 * voxel);       // body B, right of centre
+  var N = lanesTable.LANE_DENSITIES.length;       // 7 lanes
+  var spacing = Math.round(H / 4);
+  var laneYs = [], laneZs = [];
+  for (var k = 0; k < N; k++) {
+    laneYs.push(Math.round(H / 2 + (Math.floor(k / 3) - 1) * spacing));   // rows 0,0,0,1,1,1,2
+    laneZs.push(((k % 3) - 1) * spacing);                                 // cols 0,1,2,…
+  }
+
+  // The live knobs: an offset (the bodies miss by that much) and an angle (vy against vx).
+  var offsetPx = 0, angleVy = 0;
+  function seat(qid, cx, cy, cz, dirX, mass) {
+    u.setFrameProperty(qid, 'x', cx);
+    u.setFrameProperty(qid, 'y', cy + dirX * offsetPx);
+    u.setFrameProperty(qid, 'z', cz);
+    u.setFrameProperty(qid, 'vx', dirX);
+    u.setFrameProperty(qid, 'vy', -dirX * angleVy);
+    u.setFrameProperty(qid, 'vz', 0);
+    u.setFrameProperty(qid, 'mass', mass);
+    u.setFrameProperty(qid, 'speed_prob', 1.0);
+  }
+
+  // ── THE BODIES — A then B per lane; the capacity is read back from the engine, never assumed ──
+  var built = [], capacity = null;
+  for (var i = 0; i < N; i++) {
+    var a = u.makeLeafFrame(ax0 - half, laneYs[i] - half, LEVEL, null, 1, 0, true, 0, null);
+    u.injectFrame(a);
+    var aQid = u.getFrameQuantumId(a);
+    var b = u.makeLeafFrame(bx0 - half, laneYs[i] - half, LEVEL, null, -1, 0, true, 0, null);
+    u.injectFrame(b);
+    var bQid = u.getFrameQuantumId(b);
+    if (capacity === null) { capacity = u.getFrameProperty(aQid, 'mass'); }
+    built.push({ aQid: aQid, bQid: bQid });
+  }
+  var masses = lanesTable.laneMassesForCapacity(capacity);
+  var lanes = built.map(function (q, i) {
+    return { aQid: q.aQid, bQid: q.bQid, mass: masses[i], laneY: laneYs[i], laneZ: laneZs[i] };
+  });
+  function reseatAll() {
+    lanes.forEach(function (l) {
+      seat(l.aQid, ax0, l.laneY, l.laneZ, 1, l.mass);
+      seat(l.bQid, bx0, l.laneY, l.laneZ, -1, l.mass);
+    });
+  }
+  reseatAll();
+
+  // ── THE LOOK — lit spheres, coloured by fullness (sparse red → dense violet) ──
+  exp.render({ shape: 'sphere', colorScheme: 'roygbiv' });
+
+  // ── THE KNOBS (on the canvas) + MOVE/LOOK pads ──
+  var registry = ControlRegistry.makeControlRegistry();
+  registry.registerControls('collision-matrix-3d', [
+    { kind: 'scalar', id: 'offset', label: 'offset', min: 0, max: 48, step: 4, value: 0,
+      fmt: function (v) { return String(v); }, onChange: function (v) { offsetPx = v; reseatAll(); },
+      place: { x: 0.02, y: 0.03 } },
+    { kind: 'scalar', id: 'angle', label: 'angle', min: 0, max: 1, step: 0.1, value: 0,
+      fmt: function (v) { return v.toFixed(1); }, onChange: function (v) { angleVy = v; reseatAll(); },
+      place: { x: 0.02, y: 0.12 } }
+  ]);
+  // Chrome (a page only): expose the knobs to a host frame, and mount the overlay through the
+  // runner's ONE door (runner.controlHost) — before a canvas is mounted (a notebook pane) there is
+  // none, so the knobs stay in the exposed registry only.
+  FrqtlControlsPanel.exposeRegistry(registry, { runner: exp.runner });
+  if (exp.runner.controlHost) { FrqtlControlOverlay.mount(exp.runner, { registry: registry, name: 'collision-matrix-3d' }); }
+  if (typeof document !== 'undefined') {
+    if (exp.runner.controlHost) { CameraControls.attach(exp.runner, exp.runner.controlHost); }
+  }
+}

package/dist/frqtl/scenes/counting-wall-3d.js

@@ -0,0 +1,36 @@
+/* Copyright 2023-2026 by Essam Abadir */
+
+/**
+ * SCENE — 1C · Counting Wall (3D)
+ *
+ * A sketch file: the WHOLE scene as one ES module, `export default function buildExperiment(exp)`. The world
+ * (its co-init call, `exp.createCanvas` / `exp.createScene` — the one place its size is written),
+ * the parts (`exp.addObject`) and the render intent are all here; the sugar
+ * objects, renderer and engine are imports. Registered by lib/shim/registry/walkthrough.js
+ * (rung cl1c-counting-wall-3d).
+ */
+
+import { SphereEmitter } from '@descix/frqtl-web/parts';
+
+export default function buildExperiment(exp) {
+  // Collision Lab 1C · 3D — a volumetric source into a 3D Detector Screen slab
+  // (destroy+count) + a LIVE in-scene chart, textured in three; orbit to view.
+  var W = 600, H = 400;   // THE WORLD this scene states (its co-init call below)
+  var cy = Math.round(H / 2);
+  var SRC = {
+    preset: 'spherical', is2D: false, center: [Math.round(W * 0.15), cy],
+    chargeMode: 'random', fundamentalDimension: 2, wavelength: 32,
+    burstSize: 24, emitEveryTicks: 1
+  };
+  exp.createScene(W, H, 600, SphereEmitter.worldCfg(SRC));   // THE WORLD: a 3D scene + universe, 600x400x600 — first, then parts
+  exp.addObject('SphereEmitter', SRC);
+  var screen = exp.addObject('Wall', {
+    rect: [Math.round(W * 0.6), 0, 20, H], z: -80, depth: 160,
+    preset: 'detector-screen', name: 'screen', color: [120, 200, 120]
+  });
+  exp.addObject('LiveChart', {
+    source: screen,
+    rect: [Math.round(W * 0.66), Math.round(H * 0.08), Math.round(W * 0.28), Math.round(H * 0.5)],
+    series: 'bar', label: 'arrivals by y', refreshMs: 100, color: [24, 32, 46]
+  });
+}

package/dist/frqtl/scenes/counting-wall.js

@@ -0,0 +1,38 @@
+/* Copyright 2023-2026 by Essam Abadir */
+
+/**
+ * SCENE — 1C · Counting Wall
+ *
+ * A sketch file: the WHOLE scene as one ES module, `export default function buildExperiment(exp)`. The world
+ * (its co-init call, `exp.createCanvas` / `exp.createScene` — the one place its size is written),
+ * the parts (`exp.addObject`) and the render intent are all here; the sugar
+ * objects, renderer and engine are imports. Registered by lib/shim/registry/walkthrough.js
+ * (rung cl1c-counting-wall).
+ */
+
+import { SphereEmitter } from '@descix/frqtl-web/parts';
+
+export default function buildExperiment(exp) {
+  // Collision Lab 1C (Counting Wall) — the Detector Screen preset (destroy + count),
+  // with a LIVE in-scene LiveChart of the running y-histogram placed beside it.
+  var W = 600, H = 400;   // THE WORLD this scene states (its co-init call below)
+  var cy = Math.round(H / 2);
+  var SRC = {
+    preset: 'spherical', is2D: true, center: [Math.round(W * 0.15), cy],
+    chargeMode: 'random', fundamentalDimension: 2, wavelength: 32,
+    burstSize: 24, emitEveryTicks: 1
+  };
+  exp.createCanvas(W, H, SphereEmitter.worldCfg(SRC));   // THE WORLD: a 2D canvas + universe — first, then parts
+  exp.addObject('SphereEmitter', SRC);
+  var screen = exp.addObject('Wall', {
+    rect: [Math.round(W * 0.6), 0, 20, H],
+    preset: 'detector-screen', name: 'screen', color: [120, 200, 120]
+  });
+  // The interactive counting demo: a live chart of the detector's histogram,
+  // placed to the RIGHT of the screen (past where the quanta are absorbed).
+  exp.addObject('LiveChart', {
+    source: screen,
+    rect: [Math.round(W * 0.66), Math.round(H * 0.08), Math.round(W * 0.28), Math.round(H * 0.5)],
+    series: 'bar', label: 'arrivals by y', refreshMs: 100, color: [24, 32, 46]
+  });
+}