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

package/dist/frqtl/objects/setup/setupCircuitBasic.js

@@ -0,0 +1,447 @@
+/* Copyright 2023-2026 by Essam Abadir */
+
+/**
+ * setupCircuitBasic — Engine-agnostic basic circuit experiment factory.
+ * Battery -> wire -> probe A -> resistor -> probe B -> sink.
+ *
+ * Engine-agnostic: works with both the JS reference engine and the Rust/WASM engine.
+ */
+
+import { assertSetupOptions as _assertSetupOptions, requireWorldRect as _requireWorldRect } from './_setupOptions.js';
+import { LargeObject } from '../../parts/LargeObject.js';
+import { QuantumEmitter } from '../objects/QuantumEmitter.js';
+import { CircuitProbe } from '../objects/CircuitProbe.js';
+import { CollisionTypes } from '../../parts/CollisionTypes.js';
+import { CollisionActions } from '../../parts/CollisionActions.js';
+
+    // The ONE unknown-option-key validator (objects/setup/_setupOptions.js). Resolved
+    // LAZILY in the browser: the game layer defines window.assertSetupOptions before any
+    // page script runs, but reading it at eval time would bake in a load-order dependency.
+
+    // ── Imports ─────────────────────────────────────────────────────────
+
+    // ── Helpers ──────────────────────────────────────────────────────────
+
+    /**
+     * Create a horizontal or vertical wire (two parallel walls).
+     * Returns array of LargeObject instances.
+     */
+    function createWire(universe, x1, y1, x2, y2, width, wallThickness, color) {
+        color = color || [80, 80, 80];
+        var walls = [];
+        var dx = x2 - x1;
+        var dy = y2 - y1;
+        var isHorizontal = Math.abs(dx) >= Math.abs(dy);
+
+        if (isHorizontal) {
+            var left = Math.min(x1, x2);
+            var right = Math.max(x1, x2);
+            var centerY = (y1 + y2) / 2;
+            var segLen = right - left;
+
+            // Top wall
+            walls.push(new LargeObject(
+                universe,
+                [left, centerY - width / 2 - wallThickness, segLen, wallThickness],
+                CollisionTypes.WALL, [], 'TOP', 'bottom', null, 1, color
+            ));
+            // Bottom wall
+            walls.push(new LargeObject(
+                universe,
+                [left, centerY + width / 2, segLen, wallThickness],
+                CollisionTypes.WALL, [], 'BOTTOM', 'top', null, 1, color
+            ));
+        } else {
+            var top = Math.min(y1, y2);
+            var bottom = Math.max(y1, y2);
+            var centerX = (x1 + x2) / 2;
+            var segLen2 = bottom - top;
+
+            // Left wall
+            walls.push(new LargeObject(
+                universe,
+                [centerX - width / 2 - wallThickness, top, wallThickness, segLen2],
+                CollisionTypes.WALL, [], 'LEFT', 'right', null, 1, color
+            ));
+            // Right wall
+            walls.push(new LargeObject(
+                universe,
+                [centerX + width / 2, top, wallThickness, segLen2],
+                CollisionTypes.WALL, [], 'RIGHT', 'left', null, 1, color
+            ));
+        }
+        return walls;
+    }
+
+    /**
+     * Create a battery (source emitter + sink absorber + seal walls).
+     * Returns { emitter, sink, sourceMarker, sealWalls, setAmperage, setVoltage, setEnabled, isEnabled }.
+     */
+    function createBattery(universe, sourceX, sourceY, sinkX, sinkY, amperage, terminalSize, fundamentalDim, voltage, channelWidth, wallThickness) {
+        var sourceColor = [255, 60, 60];
+        var sinkColor = [60, 60, 255];
+        var wallColor = [80, 80, 80];
+
+        // Compute velocity direction
+        var dx = sinkX - sourceX;
+        var dy = sinkY - sourceY;
+        var dist = Math.sqrt(dx * dx + dy * dy) || 1;
+        var vx = (dx / dist) * voltage;
+        var vy = (dy / dist) * voltage;
+
+        // Source emitter
+        var sourceRect = [
+            sourceX - terminalSize / 2, sourceY - terminalSize / 2,
+            terminalSize, terminalSize
+        ];
+
+        var emitter = new QuantumEmitter(
+            universe,
+            [sourceRect],
+            vx, vy,
+            amperage,
+            null,    // random charge
+            true,    // auto_fire
+            false,   // directional, not random
+            Infinity,
+            0
+        );
+
+        // Sink (absorber) — must span the FULL sealed channel cross-section.
+        // A terminal-sized (8px) absorber inside a 10px channel let edge quanta
+        // slip past it into the end-cap wall behind it and bounce back, filling
+        // the right of the wire and building back-pressure across the resistor.
+        // Sizing the absorber across the whole channel (oriented perpendicular to
+        // flow) guarantees every quantum that reaches the terminal is removed.
+        var sinkIsHorizontal = Math.abs(dx) >= Math.abs(dy);
+        var sinkCross = channelWidth > 0 ? channelWidth + 2 * wallThickness : terminalSize;
+        var sinkRect = sinkIsHorizontal
+            ? [sinkX - terminalSize / 2, sinkY - sinkCross / 2, terminalSize, sinkCross]
+            : [sinkX - sinkCross / 2, sinkY - terminalSize / 2, sinkCross, terminalSize];
+        var sink = new LargeObject(
+            universe,
+            sinkRect,
+            CollisionTypes.NONE, [CollisionActions.ABSORB], 'battery_sink', 'closest', null, 1, sinkColor
+        );
+
+        // Source visual marker
+        var sourceMarker = new LargeObject(
+            universe,
+            [sourceX - terminalSize / 2, sourceY - terminalSize / 2, terminalSize, terminalSize],
+            CollisionTypes.NONE, [], 'battery_source_marker', 'closest', null, 1, sourceColor
+        );
+
+        // Seal walls
+        var sealWalls = [];
+        if (channelWidth > 0) {
+            var isHorizontal = Math.abs(dx) >= Math.abs(dy);
+            var cw = channelWidth;
+            var wt = wallThickness;
+            var ts = terminalSize;
+
+            if (isHorizontal) {
+                var flowRight = dx > 0;
+
+                // Source end-cap
+                var capX = flowRight ? sourceX - ts / 2 - wt : sourceX + ts / 2;
+                sealWalls.push(new LargeObject(
+                    universe,
+                    [capX, sourceY - cw / 2 - wt, wt, cw + 2 * wt],
+                    CollisionTypes.WALL, [], flowRight ? 'LEFT' : 'RIGHT', flowRight ? 'right' : 'left', null, 1, wallColor
+                ));
+
+                // Source top/bottom walls
+                var zoneLeft = sourceX - ts / 2;
+                sealWalls.push(new LargeObject(
+                    universe, [zoneLeft, sourceY - cw / 2 - wt, ts, wt],
+                    CollisionTypes.WALL, [], 'TOP', 'bottom', null, 1, wallColor
+                ));
+                sealWalls.push(new LargeObject(
+                    universe, [zoneLeft, sourceY + cw / 2, ts, wt],
+                    CollisionTypes.WALL, [], 'BOTTOM', 'top', null, 1, wallColor
+                ));
+
+                // Sink end-cap
+                var sinkCapX = flowRight ? sinkX + ts / 2 : sinkX - ts / 2 - wt;
+                sealWalls.push(new LargeObject(
+                    universe,
+                    [sinkCapX, sinkY - cw / 2 - wt, wt, cw + 2 * wt],
+                    CollisionTypes.WALL, [], flowRight ? 'RIGHT' : 'LEFT', flowRight ? 'left' : 'right', null, 1, wallColor
+                ));
+
+                // Sink top/bottom walls
+                var sinkZoneLeft = sinkX - ts / 2;
+                sealWalls.push(new LargeObject(
+                    universe, [sinkZoneLeft, sinkY - cw / 2 - wt, ts, wt],
+                    CollisionTypes.WALL, [], 'TOP', 'bottom', null, 1, wallColor
+                ));
+                sealWalls.push(new LargeObject(
+                    universe, [sinkZoneLeft, sinkY + cw / 2, ts, wt],
+                    CollisionTypes.WALL, [], 'BOTTOM', 'top', null, 1, wallColor
+                ));
+            } else {
+                var flowDown = dy > 0;
+
+                // Source end-cap
+                var capY = flowDown ? sourceY - ts / 2 - wt : sourceY + ts / 2;
+                sealWalls.push(new LargeObject(
+                    universe,
+                    [sourceX - cw / 2 - wt, capY, cw + 2 * wt, wt],
+                    CollisionTypes.WALL, [], flowDown ? 'TOP' : 'BOTTOM', flowDown ? 'bottom' : 'top', null, 1, wallColor
+                ));
+
+                // Source left/right walls
+                var zoneTop = sourceY - ts / 2;
+                sealWalls.push(new LargeObject(
+                    universe, [sourceX - cw / 2 - wt, zoneTop, wt, ts],
+                    CollisionTypes.WALL, [], 'LEFT', 'right', null, 1, wallColor
+                ));
+                sealWalls.push(new LargeObject(
+                    universe, [sourceX + cw / 2, zoneTop, wt, ts],
+                    CollisionTypes.WALL, [], 'RIGHT', 'left', null, 1, wallColor
+                ));
+
+                // Sink end-cap
+                var sinkCapY = flowDown ? sinkY + ts / 2 : sinkY - ts / 2 - wt;
+                sealWalls.push(new LargeObject(
+                    universe,
+                    [sourceX - cw / 2 - wt, sinkCapY, cw + 2 * wt, wt],
+                    CollisionTypes.WALL, [], flowDown ? 'BOTTOM' : 'TOP', flowDown ? 'top' : 'bottom', null, 1, wallColor
+                ));
+
+                // Sink left/right walls
+                var sinkZoneTop = sinkY - ts / 2;
+                sealWalls.push(new LargeObject(
+                    universe, [sinkX - cw / 2 - wt, sinkZoneTop, wt, ts],
+                    CollisionTypes.WALL, [], 'LEFT', 'right', null, 1, wallColor
+                ));
+                sealWalls.push(new LargeObject(
+                    universe, [sinkX + cw / 2, sinkZoneTop, wt, ts],
+                    CollisionTypes.WALL, [], 'RIGHT', 'left', null, 1, wallColor
+                ));
+            }
+        }
+
+        var currentAmperage = amperage;
+        var currentVoltage = voltage;
+        var enabled = true;
+
+        var batteryObj = {
+            emitter: emitter,
+            sink: sink,
+            sourceMarker: sourceMarker,
+            sealWalls: sealWalls,
+            enabled: enabled,
+            setAmperage: function (amp) {
+                currentAmperage = amp;
+                emitter.setBurstSize(amp);
+            },
+            setVoltage: function (v) {
+                currentVoltage = v;
+                var ndx = sinkX - sourceX;
+                var ndy = sinkY - sourceY;
+                var ndist = Math.sqrt(ndx * ndx + ndy * ndy) || 1;
+                emitter.setVelocity((ndx / ndist) * v, (ndy / ndist) * v);
+            },
+            setEnabled: function (en) {
+                enabled = en;
+                batteryObj.enabled = en;
+                emitter.setActive(en);
+            },
+            isEnabled: function () { return enabled; }
+        };
+        return batteryObj;
+    }
+
+    /**
+     * Create a resistor (constriction walls).
+     */
+    function createResistor(universe, x, y, length, channelWidth, outerWidth, horizontal, wallThickness, color) {
+        color = color || [140, 100, 50];
+        var walls = [];
+        if (horizontal) {
+            var left = x - length / 2;
+            var topWallH = (outerWidth - channelWidth) / 2;
+            walls.push(new LargeObject(
+                universe,
+                [left, y - outerWidth / 2, length, topWallH],
+                CollisionTypes.WALL, [], 'TOP', 'bottom', null, 1, color
+            ));
+            walls.push(new LargeObject(
+                universe,
+                [left, y + channelWidth / 2, length, topWallH],
+                CollisionTypes.WALL, [], 'BOTTOM', 'top', null, 1, color
+            ));
+        } else {
+            var top2 = y - length / 2;
+            var leftWallW = (outerWidth - channelWidth) / 2;
+            walls.push(new LargeObject(
+                universe,
+                [x - outerWidth / 2, top2, leftWallW, length],
+                CollisionTypes.WALL, [], 'LEFT', 'right', null, 1, color
+            ));
+            walls.push(new LargeObject(
+                universe,
+                [x + channelWidth / 2, top2, leftWallW, length],
+                CollisionTypes.WALL, [], 'RIGHT', 'left', null, 1, color
+            ));
+        }
+        return walls;
+    }
+
+    // ── Setup Factory ───────────────────────────────────────────────────
+
+    /**
+     * Create a basic circuit experiment: battery -> wire -> probeA -> resistor -> probeB -> sink.
+     *
+     * @param {Object} universe - The engine universe instance (JS or WASM), not yet init'd
+     * @param {Object} [options] - Configuration overrides
+     * @param {number} [options.wireWidth=10] - Wire channel width
+     * @param {number} [options.amperage=1] - Emission rate (particles per tick)
+     * @param {number} [options.voltage=10] - Emission velocity
+     * @param {number} [options.resistorWidth=4] - Resistor channel width
+     * @returns {Object} { battery, probes, largeObjects }
+     */
+    /**
+     * OPTIONS — this factory's own option vocabulary: EXACTLY the keys it reads.
+     * Exported as `setupCircuitBasic.OPTIONS` so a composing caller consumes it instead of
+     * retyping it. `setup-factory-option-vocabulary.test.mjs` re-derives the
+     * read-set by static trace and fails if this list drifts from the code.
+     */
+    var OPTIONS = [
+        'amperage', 'emissionRate', 'resistorWidth', 'voltage',
+        'wireWidth',
+    ];
+
+    function setupCircuitBasic(universe, options) {
+        options = _assertSetupOptions('setupCircuitBasic', options, OPTIONS);
+
+        // The world rect the co-init call wrote (EGPTUniverse.create({rect})) — the ONE size.
+        var canvas_rect = universe.universe_rect;
+        _requireWorldRect('setupCircuitBasic universe.universe_rect', canvas_rect);
+
+        var wireWidth = options.wireWidth || 10;
+        // 1 amp now means 10 quanta/tick (was 1). More emitted current → real
+        // crowding/back-pressure at the resistor gap instead of a thin trickle.
+        var QUANTA_PER_AMP = 10;
+        var amperage = (options.amperage || options.emissionRate || 1) * QUANTA_PER_AMP;
+        var voltage = options.voltage || 10;
+        var resistorWidth = options.resistorWidth || 4;
+        var fundamentalDim = 0;
+        var wallThickness = 3;
+
+        // Init universe: ground-up mode with brownian motion
+        universe.init(fundamentalDim, { wavelengthScale: 1 });
+        universe.brownianMotion = true;
+        universe.withInterQuantumCollisions = true;
+
+        // Layout constants (matching WASM adapter exactly)
+        var margin = 40;
+        var centerY = Math.round(canvas_rect.h / 2);
+        var wireLeft = margin;
+        var wireRight = canvas_rect.w - margin;
+        var wireLen = wireRight - wireLeft;
+
+        var batSourceX = wireLeft + 10;
+        var probeAX = wireLeft + Math.round(wireLen * 0.3);
+        var resistorX = wireLeft + Math.round(wireLen * 0.5);
+        var probeBX = wireLeft + Math.round(wireLen * 0.7);
+        var batSinkX = wireRight - 10;
+
+        // Main wire tube
+        var wireWalls = createWire(universe, wireLeft, centerY, wireRight, centerY, wireWidth, wallThickness);
+
+        // Battery
+        var battery = createBattery(
+            universe,
+            batSourceX, centerY,
+            batSinkX, centerY,
+            amperage,
+            wireWidth - 2,
+            fundamentalDim,
+            voltage,
+            wireWidth,
+            wallThickness
+        );
+
+        // Probes
+        var probeA = new CircuitProbe(universe, probeAX, centerY, wireWidth, 'before_resistor');
+        var probeB = new CircuitProbe(universe, probeBX, centerY, wireWidth, 'after_resistor');
+
+        // Resistor
+        var resistorWalls = createResistor(
+            universe, resistorX, centerY, 20, resistorWidth, wireWidth, true, wallThickness
+        );
+
+        // Right-end drain (absorber). Quanta that have crossed the resistor are
+        // removed at the RIGHT END of the wire (full channel cross-section,
+        // extending to the true wire end past the terminal) rather than bouncing
+        // off the terminator and back-filling the wire. Registered for collisions
+        // but intentionally NOT rendered (kept invisible).
+        var drainLeft = wireLeft + Math.round(wireLen * 0.88);
+        var drainRight = wireRight;
+        var drainW = Math.max(1, drainRight - drainLeft);
+        var drain = new LargeObject(
+            universe,
+            [drainLeft, centerY - (wireWidth / 2 + wallThickness), drainW, wireWidth + 2 * wallThickness],
+            CollisionTypes.NONE, [CollisionActions.ABSORB], 'RIGHT_drain', 'closest', null, 1, [40, 40, 70]
+        );
+
+        // Evaluation tick function: sample probes each tick
+        universe.experimentTickFunctions.push(function () {
+            probeA.queryDensity();
+            probeB.queryDensity();
+            return [];
+        });
+
+        var gateThreshold = 3;
+
+        // Collect all large objects for rendering
+        var largeObjects = [];
+        largeObjects.push.apply(largeObjects, wireWalls);
+        largeObjects.push(battery.sink);
+        largeObjects.push(battery.sourceMarker);
+        largeObjects.push.apply(largeObjects, battery.sealWalls);
+        largeObjects.push.apply(largeObjects, resistorWalls);
+        largeObjects.push(probeA.marker);
+        largeObjects.push(probeB.marker);
+
+        return {
+            battery: battery,
+            drain: drain,
+            probes: { before_resistor: probeA, after_resistor: probeB },
+            wireWalls: wireWalls,
+            resistorWalls: resistorWalls,
+            setBatteryAmperage: function (amp) { battery.setAmperage(amp); },
+            setBatteryVoltage: function (v) { battery.setVoltage(v); },
+            getCircuitState: function () {
+                var state = {};
+                var probeMap = { before_resistor: probeA, after_resistor: probeB };
+                for (var name in probeMap) {
+                    if (probeMap.hasOwnProperty(name)) {
+                        var probe = probeMap[name];
+                        state[name] = {
+                            flowRate: probe.getFlowRate(),
+                            lastCount: probe.getLastCount(),
+                            isHigh: probe.isHigh(gateThreshold)
+                        };
+                    }
+                }
+                return state;
+            },
+            largeObjects: largeObjects
+        };
+    }
+
+    // ── Statics (reusable helpers) ──────────────────────────────────────
+
+    setupCircuitBasic.createWire = createWire;
+    setupCircuitBasic.createBattery = createBattery;
+    setupCircuitBasic.createResistor = createResistor;
+
+    // ── Export ───────────────────────────────────────────────────────────
+
+    setupCircuitBasic.OPTIONS = OPTIONS;
+
+    export { setupCircuitBasic, createWire, createBattery, createResistor };
+

package/dist/frqtl/objects/setup/setupCollisionMatrix.js

@@ -0,0 +1,188 @@
+/* Copyright 2023-2026 by Essam Abadir */
+
+/**
+ * setupCollisionMatrix — density-sweep collision experiment.
+ *
+ * ── Layer 1: API contract ────────────────────────────────────────────────────
+ * @param {Object} universe - WASM universe (wasmOnly experiment); init()'d here.
+ * @param {Object} [opts]
+ * @param {number} [opts.level=6]    - Dimension of every body (2^level px voxel; 6 = 64px).
+ * @param {number} [opts.offset=0]   - Transverse launch offset (px): A below / B above the lane.
+ * @param {number} [opts.angle=0]    - Converging vy magnitude (the approach angle).
+ *
+ * @returns {{
+ *   level: number, voxel: number, capacity: number, laneYs: number[], ax0: number, bx0: number,
+ *   lanes: Array<{ name:string, label:string, aQid:number, bQid:number,
+ *                  mass:number, ax0:number, bx0:number, laneY:number }>,
+ *   matrixControl: { getOffset, setOffset, getAngle, setAngle, reset }
+ * }}
+ *
+ * ── Layer 2: physics behavior (what this PROVES) ─────────────────────────────
+ * SEVEN horizontal lanes, each a SYMMETRIC pair of Dim-6 boxes (equal mass) launched head-on
+ * — A from the left (+x), B from the right (−x) — at speed_prob=1. Mass is swept on a LOG
+ * (powers-of-2) scale: 1, 8, 64, 512, 1024, 2048, 4096(=capacity), so density ρ = mass/capacity
+ * runs ≈0.0002 … 1.0 DOWN the lanes: SPARSE at the TOP, FULL at the BOTTOM. Bodies are
+ * COLORLESS; the ROYGBIV render scheme colours each by its fullness.
+ *
+ * withInterQuantumCollisions=true runs voxel_collision_pass — the TWO-BUCKET momentum exchange
+ * (docs/internal/physics-lab/sam_notes/On_Collisions.md §Two-Bucket): colliding boxes EXCHANGE momentum and
+ * CONSERVE it; the per-tick exchange ceiling carries occupancy (ρ_A·ρ_B), so the bounce TIMING
+ * emerges from density — rigid (full) lanes bounce fast and clean, soft (sparse) lanes bounce
+ * slowly. The sweep reads this spectrum at a glance. Cross-lane coupling is impossible: lanes are
+ * y-separated ≫ the voxel, so no two lanes share a collision-proximity bucket.
+ *
+ * activeAxes {x,y}: x carries the head-on approach; the live OFFSET/ANGLE controls (no reload) add
+ * a transverse launch offset + a converging vy so collisions go OFF-AXIS — exercising the engine's
+ * SEPARATE per-axis momentum buckets (inc_x vs inc_y). density-sweep × offset/angle = the "offset
+ * angle combinations". At offset=0, angle=0 it is clean head-on.
+ */
+
+import { assertSetupOptions as _assertSetupOptions, requireWorldRect as _requireWorldRect } from './_setupOptions.js';
+import { collisionMatrixLanes as _lanes } from './_collisionMatrixLanes.js';
+
+    // The ONE unknown-option-key validator (objects/setup/_setupOptions.js). Resolved
+    // LAZILY in the browser: the game layer defines window.assertSetupOptions before any
+    // page script runs, but reading it at eval time would bake in a load-order dependency.
+
+    /**
+     * Lane descriptor: each lane is a SYMMETRIC pair of bodies (both the same mass) at a fixed y.
+     * DENSITY is swept on a strict LOGARITHMIC (powers-of-2) scale from ρ≈0 (one Dim-0 child →
+     * near-total pass-through) to ρ=1 (full box → hard abut) — non-linear probabilistic
+     * effects (collision prob ~ density² with density=mass/capacity) read cleanly on a log scale
+     * (CEO 2026-06-29). speed_prob=1 on every body so ALL lanes approach at the same 1px/tick,
+     * isolating density→collision from the fullness-gate movement-speed effect (that is G1's job).
+     * For a 2D Dim-6 box capacity = 64×64 = 4096 = 2^12, so the ladder is 2^0…2^12. The table is
+     * `_collisionMatrixLanes.js` — shared with the 3D matrix, whose capacity is 64³ and whose
+     * masses therefore differ while the DENSITIES are identical.
+     */
+    /**
+     * OPTIONS — this factory's own option vocabulary: EXACTLY the keys it reads.
+     * Exported as `setupCollisionMatrix.OPTIONS` so a composing caller consumes it instead of
+     * retyping it. `setup-factory-option-vocabulary.test.mjs` re-derives the
+     * read-set by static trace and fails if this list drifts from the code.
+     */
+    var OPTIONS = [
+        'angle', 'level',
+        'offset',
+    ];
+
+    function setupCollisionMatrix(universe, opts) {
+        opts = _assertSetupOptions('setupCollisionMatrix', opts, OPTIONS);
+        var level  = (opts.level   !== undefined) ? opts.level   : 6;
+
+        // The world rect the co-init call wrote (EGPTUniverse.create({rect})) — the ONE size.
+        var rect = universe.universe_rect;
+        var world = _requireWorldRect('setupCollisionMatrix universe.universe_rect', rect);
+        var cw = world.w, ch = world.h;
+
+        // activeAxes: BOTH x and y. x carries the head-on approach; y carries the OFFSET/ANGLE
+        // switch (transverse offset + converging vy) that exercises the engine's SEPARATE per-axis
+        // momentum buckets (inc_x vs inc_y) and the per-axis contact-cross-section ceiling. At
+        // offset=0, angle=0 the motion is pure-x head-on (vy=0); the transverse yo-yo adds only a
+        // small ±1px wiggle that does not cross the ~100px lane spacing over a collision.
+        universe.init(0, {
+            wavelengthScale: 1,
+            brownianMotion: false,
+            activeAxes: { x: true, y: true, z: false }
+        });
+        // Enable the voxel_collision_pass so same-dimension boxes exchange momentum.
+        universe.withInterQuantumCollisions = true;
+
+        universe.addDimension(level);
+        var voxel = Math.pow(2, level);   // 64 for level=6
+        var half  = voxel / 2;            // makeLeafFrame takes TOP-LEFT; we want CENTRES.
+
+        // Canonical launch CENTRES (same for every lane). A left of centre, B right, 3 voxels apart.
+        var midX = Math.floor(cw * 0.5);
+        var ax0  = midX - Math.floor(1.5 * voxel);   // ~254 centre for 700-wide canvas
+        var bx0  = midX + Math.floor(1.5 * voxel);   // ~446 centre
+
+        // Lane y-CENTRES: N lanes evenly distributed (centres at ch*(2i+1)/(2N)). These are CENTRES
+        // — the boxes are placed top-left = centre − half, so a 64px box centred at the bottom lane
+        // (y≈650) spans 618..682 and stays IN BOUNDS (H=700). Passing the centre AS the top-left was
+        // the boundary-kill bug: the bottom lane ran off the edge and the boundary check zeroed it.
+        var N = _lanes.LANE_DENSITIES.length;
+        var laneYs = _lanes.LANE_DENSITIES.map(function (_, i) { return Math.round(ch * (2 * i + 1) / (2 * N)); });
+
+        // OFFSET / ANGLE state (the switch). offsetPx = transverse separation of the pair at launch
+        // (A below centre, B above → glancing); angleVy = converging y-velocity (A up, B down →
+        // both x AND y momentum at impact). Both default 0 = clean head-on.
+        var offsetPx = (opts.offset !== undefined) ? opts.offset : 0;
+        var angleVy  = (opts.angle  !== undefined) ? opts.angle  : 0;
+
+        var capacity = null;
+
+        // Seat one body's position + velocity for the current offset/angle (CENTRE coords).
+        function seat(qid, cx, cy, dirX, mass) {
+            universe.setFrameProperty(qid, 'x',  cx);
+            universe.setFrameProperty(qid, 'y',  cy + dirX * offsetPx);   // A(dirX=+1) below, B above
+            universe.setFrameProperty(qid, 'vx', dirX);
+            universe.setFrameProperty(qid, 'vy', -dirX * angleVy);        // converge toward the lane
+            universe.setFrameProperty(qid, 'mass', mass);
+            universe.setFrameProperty(qid, 'speed_prob', 1.0);
+        }
+
+        // Build every body FIRST — the capacity that sets the lane ladder is whatever the
+        // ENGINE reports for the body it actually built, so the masses cannot be known
+        // until a body exists.
+        var built = [];
+        for (var i = 0; i < N; i++) {
+            var laneY = laneYs[i];
+            // Place COLORLESS boxes (ROYGBIV scheme drives colour from fullness) at top-left = centre−half.
+            var aHandle = universe.makeLeafFrame(ax0 - half, laneY - half, level, null, 1, 0, true, 0, null);
+            universe.injectFrame(aHandle);
+            var aQid = universe.getFrameQuantumId(aHandle);
+            var bHandle = universe.makeLeafFrame(bx0 - half, laneY - half, level, null, -1, 0, true, 0, null);
+            universe.injectFrame(bHandle);
+            var bQid = universe.getFrameQuantumId(bHandle);
+
+            if (capacity === null) { capacity = universe.getFrameProperty(aQid, 'mass'); }
+            built.push({ aQid: aQid, bQid: bQid });
+        }
+
+        var laneMasses = _lanes.laneMassesForCapacity(capacity);
+
+        var lanes = built.map(function (b, i) {
+            var laneY = laneYs[i];
+            var m = laneMasses[i];
+            // SYMMETRIC lane; seat applies mass + the current offset/angle.
+            seat(b.aQid, ax0, laneY, 1, m);
+            seat(b.bQid, bx0, laneY, -1, m);
+
+            return {
+                name:  'm=' + m,
+                label: 'mass ' + m + ' / ' + capacity + ' (density ' + (m / capacity).toPrecision(2) + ')',
+                aQid: b.aQid, bQid: b.bQid, mass: m, ax0: ax0, bx0: bx0, laneY: laneY
+            };
+        });
+
+        function reseatAll() {
+            lanes.forEach(function (lane) {
+                seat(lane.aQid, lane.ax0, lane.laneY, 1, lane.mass);
+                seat(lane.bQid, lane.bx0, lane.laneY, -1, lane.mass);
+            });
+        }
+
+        // ── Live control handle (Blackbody pattern — no reload) ──────────────────
+        // setOffset/setAngle change the transverse offset and converging angle and RE-SEAT every
+        // lane so the new geometry takes effect immediately; reset just re-seats at the current
+        // offset/angle. The density sweep (per lane) × the offset/angle slider = the "offset angle
+        // combinations" the matrix is meant to explore.
+        var matrixControl = {
+            getOffset: function () { return offsetPx; },
+            setOffset: function (v) { offsetPx = v; reseatAll(); },
+            getAngle:  function () { return angleVy; },
+            setAngle:  function (v) { angleVy  = v; reseatAll(); },
+            reset:     function () { reseatAll(); }
+        };
+
+        return {
+            level: level, voxel: voxel, capacity: capacity, laneYs: laneYs,
+            ax0: ax0, bx0: bx0, lanes: lanes, matrixControl: matrixControl
+        };
+    }
+
+    setupCollisionMatrix.OPTIONS = OPTIONS;
+
+    export { setupCollisionMatrix };
+