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

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

@@ -0,0 +1,229 @@
+/* Copyright 2023-2026 by Essam Abadir */
+
+/**
+ * setupDoubleSlit_Laser — Laser-style double-slit experiment factory.
+ *
+ * Replaces the radial PointSource with a directional QuantumEmitter (like a
+ * circuit battery). Particles fire rightward with initial momentum; the
+ * engine's brownian motion + wave-walk creates the lateral displacement that
+ * produces interference.
+ *
+ * Slit geometry uses d/a ≈ 5 to match real-world HeNe laser teaching-lab
+ * proportions (slit separation / slit width ≈ 5).
+ *
+ * Includes single-photon mode: fires one particle at a time from a random
+ * spot on the laser aperture, demonstrating that individual particles still
+ * build up the interference pattern.
+ */
+
+import { assertSetupOptions as _assertSetupOptions, requireWorldRect as _requireWorldRect } from './_setupOptions.js';
+import { SlitScreen } from '../../parts/SlitScreen.js';
+import { QuantumEmitter } from '../objects/QuantumEmitter.js';
+import { DetectorWall } from '../../parts/DetectorWall.js';
+import { LargeObject } from '../../parts/LargeObject.js';
+import { CollisionTypes } from '../../parts/CollisionTypes.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 ─────────────────────────────────────────────────────────
+
+    // ── Defaults ────────────────────────────────────────────────────────
+
+    var DEFAULT_VOLTAGE = 2;      // vx: rightward momentum
+    var DEFAULT_AMPERAGE = 8;     // particles per tick
+    var DEFAULT_SLIT_HEIGHT = 20; // px — slit opening (a), gives d/a ≈ 5
+    var DEFAULT_GAP_HEIGHT = 80;  // px — inter-slit wall, gives d = a + gap = 100
+    var SINGLE_PHOTON_DELAY = 8;  // ticks between single-photon emissions
+
+    // ── Setup Factory ───────────────────────────────────────────────────
+
+    /**
+     * Create a laser-style double-slit experiment.
+     *
+     * @param {Object} universe - The engine universe instance (JS or WASM), not yet init'd
+     * @param {Object} options - Configuration
+     * @param {number} [options.wavelength=64] - Wavelength for screen positioning
+     * @param {number} [options.fundamentalDimension=2] - Base dimension
+     * @param {number} [options.detectAtSlits=1] - Slit detection mode (0/1/2)
+     * @param {boolean} [options.absorbAtSlitWall=true] - Absorb vs block at walls
+     * @param {number} [options.wavelengthScale] - Override wavelength constant
+     * @param {number} [options.voltage=2] - Rightward momentum (vx)
+     * @param {number} [options.amperage=8] - Particles per tick
+     * @param {boolean} [options.singlePhoton=false] - Single-photon mode
+     * @param {number} [options.slitHeight=20] - Slit opening height (px)
+     * @param {number} [options.gapHeight=80] - Inter-slit wall height (px)
+     * @returns {Object} { slitScreen, emitter, detectorWall, startWall, interferenceParams, largeObjects, setSinglePhoton }
+     */
+    /**
+     * OPTIONS — this factory's own option vocabulary: EXACTLY the keys it reads.
+     * Exported as `setupDoubleSlit_Laser.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 = [
+        'absorbAtSlitWall', 'amperage', 'detectAtSlits',
+        'fundamentalDimension', 'gapHeight', 'singlePhoton', 'slitHeight',
+        'voltage', 'wavelength', 'wavelengthScale',
+    ];
+
+    function setupDoubleSlit_Laser(universe, options) {
+        options = _assertSetupOptions('setupDoubleSlit_Laser', options, OPTIONS);
+
+        var wavelength = options.wavelength !== undefined ? options.wavelength : 64;
+        var fundamentalDimension = options.fundamentalDimension !== undefined ? options.fundamentalDimension : 2;
+        var detectAtSlits = options.detectAtSlits !== undefined ? options.detectAtSlits : 1;
+        var absorbAtSlitWall = options.absorbAtSlitWall !== undefined ? options.absorbAtSlitWall : true;
+        var canvasRect = universe.universe_rect;
+        // The world height, through the ONE world-rect normalizer (throws on a missing or
+        // non-positive dimension — a zero-high screen would count nothing, silently).
+        var canvasH = _requireWorldRect('setupDoubleSlit_Laser universe.universe_rect', canvasRect).h;
+        var voltage = options.voltage !== undefined ? options.voltage : DEFAULT_VOLTAGE;
+        var amperage = options.amperage !== undefined ? options.amperage : DEFAULT_AMPERAGE;
+        var singlePhoton = options.singlePhoton || false;
+        var slitHeight = options.slitHeight !== undefined ? options.slitHeight : DEFAULT_SLIT_HEIGHT;
+        var gapHeight = options.gapHeight !== undefined ? options.gapHeight : DEFAULT_GAP_HEIGHT;
+
+        // Wavelength constant: higher values create coarser wave-walk oscillation,
+        // producing wider, more detectable interference fringes. 32 gives stable
+        // 4/4 interference tests with ~4000 hits at 5×5000. Lower values (4-16)
+        // produce finer fringes that wash out with aggregated data.
+        var wavelengthScale = options.wavelengthScale !== undefined
+            ? options.wavelengthScale
+            : 32;
+
+        universe.wavelengthScale = wavelengthScale;
+
+        // Init universe: ground-up mode with wave-walk (NOT brownian motion).
+        // brownianMotion:false disables brownian motion, enabling the wave-walk
+        // movement mode where particles move 1px along velocity + 1px perpendicular
+        // via the wavelength-driven coin-flip. This is what produces interference.
+        // (brownianMotion=true would enable pure random walk, which diffuses the pattern.)
+        universe.init(
+            fundamentalDimension,
+            {
+                wavelengthScale: wavelengthScale,
+                brownianMotion: false,   // enables wave-walk mode
+            }
+        );
+
+        // ── Slit Screen (d/a ≈ 5 geometry) ─────────────────────────────
+        var slitScreenLeft = wavelength * 1.5;
+        var slitScreen = new SlitScreen(
+            universe,
+            slitScreenLeft,
+            wavelength,       // wall thickness
+            canvasH,
+            wavelength,
+            absorbAtSlitWall,
+            detectAtSlits,
+            slitHeight,       // override: narrower slits
+            gapHeight         // override: wider gap
+        );
+
+        // ── Start Wall (absorb wall at left edge) ──────────────────────
+        var startWall = new LargeObject(
+            universe,
+            [0, 0, 10, canvasH],
+            CollisionTypes.ABSORB,
+            // RECOLOR removed: deleted in the engine-no-color cut (I1). Stale dead reference.
+            // KILL removed: was a Rust-only divergence, deleted from canonical action set.
+            // The ABSORB collision type already absorbs frames; no action needed here.
+            [],
+            'start_wall',
+            'closest',
+            null,
+            1,
+            [120, 120, 120]
+        );
+
+        // ── Laser Emitter ──────────────────────────────────────────────
+        // Two source rects, one aligned with each slit, positioned close to the
+        // slit screen (x = slitScreenLeft - 6). The wave-walk's coin-flip has a
+        // strong directional bias at high wavelengthScale; placing the source
+        // close minimizes pre-slit drift, keeping slit1/slit2 ratio near 1.0.
+        var laserX = slitScreenLeft - 6;
+        var sourceRect1 = [laserX, slitScreen.slit1_top, 4, slitScreen.slit_height];
+        var sourceRect2 = [laserX, slitScreen.slit2_top, 4, slitScreen.slit_height];
+
+        var effectiveBurst = singlePhoton ? 1 : amperage;
+        var effectiveDelay = singlePhoton ? SINGLE_PHOTON_DELAY : 0;
+
+        var emitter = new QuantumEmitter(
+            universe,
+            [sourceRect1, sourceRect2],
+            voltage, 0,         // vx=rightward, vy=0
+            effectiveBurst,
+            null,               // random charge
+            true,               // auto_fire
+            false,              // directional (not random)
+            Infinity,           // unlimited quanta
+            effectiveDelay      // delay between bursts
+        );
+
+        // ── Detector Wall ──────────────────────────────────────────────
+        var detectorWallX = slitScreen.wall1.rect.left + slitScreen.wall1.rect.w + 3 * wavelength;
+        var detectorWall = new DetectorWall(
+            universe,
+            canvasRect,
+            detectorWallX
+        );
+
+        // ── Interference parameters ────────────────────────────────────
+        var d_distance_between_slits = slitScreen.slit_height + slitScreen.slit_wall_gap_height;
+        var L_distance_slits_to_screen = detectorWall.x - (slitScreen.wall1.rect.left + slitScreen.wall1.rect.w);
+
+        // ── Collect all large objects for rendering ─────────────────────
+        var largeObjects = [];
+        for (var wi = 0; wi < slitScreen.walls.length; wi++) {
+            largeObjects.push(slitScreen.walls[wi]);
+        }
+        largeObjects.push(startWall);
+        largeObjects.push(detectorWall.detector_wall);
+
+        // ── Single-photon toggle ────────────────────────────────────────
+        var currentAmperage = amperage;
+
+        function setSinglePhoton(enabled) {
+            if (enabled) {
+                emitter.setBurstSize(1);
+                // Delay is set at registration; re-register or use setActive to pace
+                // For now, burst_size=1 is the primary control
+            } else {
+                emitter.setBurstSize(currentAmperage);
+            }
+        }
+
+        function setAmperage(newAmperage) {
+            currentAmperage = newAmperage;
+            emitter.setBurstSize(newAmperage);
+        }
+
+        function setVoltage(newVoltage) {
+            emitter.setVelocity(newVoltage, 0);
+        }
+
+        return {
+            slitScreen: slitScreen,
+            emitter: emitter,
+            detectorWall: detectorWall,
+            startWall: startWall,
+            interferenceParams: {
+                d: d_distance_between_slits,
+                L: L_distance_slits_to_screen,
+                wavelength: wavelength
+            },
+            largeObjects: largeObjects,
+            setSinglePhoton: setSinglePhoton,
+            setAmperage: setAmperage,
+            setVoltage: setVoltage
+        };
+    }
+
+    // ── Export ───────────────────────────────────────────────────────────
+
+    setupDoubleSlit_Laser.OPTIONS = OPTIONS;
+
+    export { setupDoubleSlit_Laser };
+

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

@@ -0,0 +1,59 @@
+/* Copyright 2023-2026 by Essam Abadir */
+
+/**
+ * setupEmpty — Engine-agnostic blank-universe factory.
+ *
+ * Initializes the universe (same init contract as every other setup factory) but
+ * creates NO objects and NO emitters. This is the base the AuthorView snapshot
+ * model loads: a saved project opens this page, the universe is init'd here, then
+ * AuthorView.applyDesign reconstructs the saved entities into it. Without the
+ * universe.init() call here, applyDesign would run against an uninitialized
+ * universe and silently restore nothing.
+ *
+ * Engine-agnostic: works with both the JS reference engine and the Rust/WASM engine.
+ */
+
+import { assertSetupOptions as _assertSetupOptions, requireWorldRect as _requireWorldRect } from './_setupOptions.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.
+
+    /**
+     * Initialize a blank universe with the standard dimension stack, no objects.
+     *
+     * @param {Object} universe - The engine universe instance (JS or WASM), not yet init'd
+     * @param {Object} [options]
+     * @param {number} [options.fundamentalDimension=2]
+     * @param {number} [options.wavelengthScale=8]
+     * @returns {Object} { largeObjects: [] }
+     */
+    /**
+     * OPTIONS — this factory's own option vocabulary: EXACTLY the keys it reads.
+     * Exported as `setupEmpty.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 = [
+        'fundamentalDimension', 'wavelengthScale',
+    ];
+
+    function setupEmpty(universe, options) {
+        options = _assertSetupOptions('setupEmpty', options, OPTIONS);
+
+        // The world rect the co-init call wrote (EGPTUniverse.create({rect})) — the ONE size.
+        var canvas_rect = universe.universe_rect;
+        _requireWorldRect('setupEmpty universe.universe_rect', canvas_rect);
+        var fundamentalDimension = options.fundamentalDimension !== undefined ? options.fundamentalDimension : 2;
+        var wavelengthScale = options.wavelengthScale !== undefined ? options.wavelengthScale : 8;
+
+        // Same init contract as setupWaveInterference: ground-up, brownianMotion:false.
+        universe.init(fundamentalDimension, { wavelengthScale: wavelengthScale, brownianMotion: false });
+
+        return { largeObjects: [] };
+    }
+
+    setupEmpty.OPTIONS = OPTIONS;
+
+    export { setupEmpty };
+

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

@@ -0,0 +1,209 @@
+/* Copyright 2023-2026 by Essam Abadir */
+
+/**
+ * setupFxSmoke — Emergent smoke experiment via voxel size-up ladder.
+ *
+ * ── Layer 1: API contract ────────────────────────────────────────────────────
+ *
+ * @param {Object} universe - The engine universe instance (JS or WASM compat shim),
+ *   not yet init'd. `universe.init` is called internally.
+ * @param {Object} [options] - Configuration overrides.
+ * @param {number} [options.velocity=1]
+ *   Rightward emission velocity (px/tick). Units: pixels/tick.
+ * @param {number} [options.fundamentalWaveLength=64]
+ *   Desired wavelength for emitted quanta. Units: pixels.
+ *   Drives `wavelengthScale = max(1, floor(λ/4))`.
+ * @param {number} [options.burstSize=20]
+ *   Quanta emitted per tick from the beam source. Units: quanta/tick.
+ * @param {number} [options.billowDimensions=3]
+ *   Number of extra aggregation dimensions to register (voxel size-up ladder).
+ *   dim0 = 1 px (fundamental leaf), dim+1 = 4 px, dim+2 = 8 px, dim+3 = 16 px.
+ *   Each dimension represents bigger puffs once quanta aggregate into parent frames.
+ *   Range: 1–4. Higher values produce larger maximum puff sizes but require more
+ *   collision events to reach the top level.
+ * @param {boolean} [options.brownianMotion=true]
+ *   Enable Brownian (random) perturbation on each frame per tick. Keeps the beam
+ *   from being perfectly laminar — essential for inter-quantum collision frequency.
+ * @param {number} [options.bulletSpeed=2]
+ *   Speed of the moving Bullet occluder (px/tick). When > 0 a Bullet is placed at
+ *   the beam centre and advances rightward; its BOUNCE collision compresses quanta
+ *   in the wake, driving aggregation into bigger frames (the smoke billow effect).
+ *   Set to 0 to disable the bullet (pure-beam smoke, no projectile).
+ * @param {string} [options.bulletCollision='BOUNCE']
+ *   CollisionTypes value for the Bullet. BOUNCE deflects quanta; WALL stops them
+ *   dead (sharper void). NONE makes the bullet a ghost (visual only, no physics).
+ *
+ * @returns {{
+ *   emitter: QuantumEmitter,
+ *   bullet: Bullet|null,
+ *   largeObjects: LargeObject[]
+ * }}
+ *   bullet is null when options.bulletSpeed === 0.
+ *
+ * ── Layer 2: physics behavior ────────────────────────────────────────────────
+ *
+ * The smoke billow is EMERGENT PHYSICS, not a sprite trick. It mirrors the
+ * Blackbody aggregation mechanic (lib/frqtl/scenes/blackbody.js):
+ *
+ *   universe.withInterQuantumCollisions = true
+ *     → colliding quanta PARENT into compound frames (merge/promote pipeline)
+ *
+ *   addDimension(layer) for each size-up step
+ *     → the engine's Phase B (STRUCTURE) builds higher-dimension frames from
+ *       fundamental-quadtree collisions, growing compound frames with larger rect.w
+ *       (2× per level: 1 px → 4 px → 8 px → 16 px)
+ *
+ *   Bullet (BOUNCE) advancing rightward
+ *     → compresses quanta in the beam's wake → higher local density
+ *     → more inter-quantum collisions → faster aggregation up the size ladder
+ *     → renderer reads each frame's rect.w and sizes the smoke puff accordingly
+ *     → result: varied puff sizes, denser puffs in the wake → billowing smoke
+ *
+ * With no bullet (bulletSpeed=0), the beam still aggregates but more slowly —
+ * you get a smooth column of growing puffs rather than a directional billow.
+ *
+ * With bullet (bulletSpeed>0) the wakes produce large aggregated frames whose
+ * rect.w drives the renderer's `aSize` attribute (three-provider.js) → larger,
+ * softer puff sprites. Faster bullet = denser wake = bigger emergent frames.
+ *
+ * OBSERVED effect (design intent — verified in the realm):
+ *   fx-smoke: at tick ~200 puffs range from 1 px (single leaf) to 8–16 px
+ *   (aggregated compound frames). The bullet wake region shows higher density
+ *   and larger puff sizes than the undisturbed beam. Adjusting the `puff` slider
+ *   (render control, three-provider) scales the sprite size for each puff — the
+ *   variance in sizes is physics, not the slider. Figure TBD (realm verification).
+ */
+
+import { assertSetupOptions as _assertSetupOptions, requireWorldRect as _requireWorldRect } from './_setupOptions.js';
+import { QuantumEmitter } from '../objects/QuantumEmitter.js';
+import { Bullet } from '../objects/Bullet.js';
+import { CollisionTypes } from '../../parts/CollisionTypes.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 ─────────────────────────────────────────────────────────────
+
+    // ── Voxel-ladder dimension levels ────────────────────────────────────────
+    //
+    // The JS reference engine uses integer layer numbers; addDimension(n) registers
+    // a new quadtree level at scale n. The WASM engine's add_dimension() mirrors this.
+    // Blackbody uses fundamental_dim=0 + quantum_dim=4 (one extra level).
+    //
+    // For the smoke ladder we want multiple extra levels so frames can aggregate into
+    // progressively larger puffs. The layer numbers determine the relative cell size:
+    //   layer 0 = fundamental (1 px leaf quanta)
+    //   layer 4 = first aggregation level (cell ≈ 4 px)
+    //   layer 8 = second aggregation level (cell ≈ 8 px)
+    //   layer 12 = third aggregation level (cell ≈ 16 px)
+    //
+    // These follow the same convention as Blackbody (quantum_dim=4).
+    var BILLOW_DIMS = [4, 8, 12];   // up to 3 extra levels; trimmed by billowDimensions option
+
+    // ── Setup factory ────────────────────────────────────────────────────────
+    /**
+     * OPTIONS — this factory's own option vocabulary: EXACTLY the keys it reads.
+     * Exported as `setupFxSmoke.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 = [
+        'billowDimensions', 'brownianMotion', 'bulletCollision', 'bulletSpeed',
+        'burstSize', 'fundamentalWaveLength', 'velocity',
+    ];
+
+    function setupFxSmoke(universe, options) {
+        options = _assertSetupOptions('setupFxSmoke', options, OPTIONS);
+
+        // The world rect the co-init call wrote (EGPTUniverse.create({rect})) — the ONE size.
+        var canvas_rect = universe.universe_rect;
+        _requireWorldRect('setupFxSmoke universe.universe_rect', canvas_rect);
+
+        var desiredWaveLength  = options.fundamentalWaveLength !== undefined ? options.fundamentalWaveLength : 64;
+        var velocity           = options.velocity              !== undefined ? options.velocity              : 1;
+        var burstSize          = options.burstSize             !== undefined ? options.burstSize             : 20;
+        var billowDimensions   = options.billowDimensions      !== undefined ? options.billowDimensions      : 3;
+        var useBrownian        = options.brownianMotion        !== undefined ? options.brownianMotion        : true;
+        var bulletSpeed        = options.bulletSpeed           !== undefined ? options.bulletSpeed           : 2;
+        var bulletCollision    = options.bulletCollision       !== undefined ? options.bulletCollision       : CollisionTypes.BOUNCE;
+
+        var waveLengthMultiplier = Math.max(1, Math.floor(desiredWaveLength / 4));
+
+        // ── Universe init ─────────────────────────────────────────────────────
+        // fundamental_dim=0 — leaf quanta are 1-px frames.
+        // withInterQuantumCollisions = true — inter-quantum collisions drive the
+        // merge/promote pipeline (as lib/frqtl/scenes/blackbody.js sets it).
+        universe.init(0, {
+            wavelengthScale: waveLengthMultiplier,
+            brownianMotion: false,
+            activeAxes: { x: true, y: true, z: true }
+        });
+
+        // Brownian motion keeps the beam from laminar flow → more collisions.
+        universe.brownianMotion = useBrownian;
+
+        // The Blackbody aggregation mechanic: colliding quanta parent up into
+        // compound frames that occupy progressively larger cells in the quadtree.
+        universe.withInterQuantumCollisions = true;
+
+        // Register the voxel size-up ladder — a subset of BILLOW_DIMS trimmed to
+        // billowDimensions entries (max 3 extra levels above fundamental dim=0).
+        var dimsToAdd = Math.max(1, Math.min(billowDimensions, BILLOW_DIMS.length));
+        for (var i = 0; i < dimsToAdd; i++) {
+            universe.addDimension(BILLOW_DIMS[i]);
+        }
+
+        // ── Emitter ───────────────────────────────────────────────────────────
+        // Beam source at canvas centre, firing rightward (3D walk).
+        // The z-axis yo-yo kicks spread the beam into depth, giving the smoke
+        // a 3D volumetric appearance when viewed from an orbit angle.
+        var cx = Math.floor(canvas_rect.w / 2);
+        var cy = Math.floor(canvas_rect.h / 2);
+        var sourceHeight = 10;
+
+        var emitter = new QuantumEmitter(
+            universe,
+            [[cx, cy - Math.floor(sourceHeight / 2), 1, sourceHeight]],
+            velocity, 0,
+            burstSize,
+            1,          // charge = NEGATIVE
+            true,       // auto_fire
+            false,      // not random_direction
+            Infinity,   // quantum_limit
+            0,          // delay
+            false       // wrap = false
+        );
+
+        // ── Bullet (optional) ─────────────────────────────────────────────────
+        // A small BOUNCE LO placed at the beam source, advancing rightward.
+        // Its moving wake compresses quanta → more inter-quantum collisions →
+        // aggregation into bigger frames → billowing smoke puffs (Effect C per design).
+        var bullet = null;
+        if (bulletSpeed > 0 && Bullet) {
+            bullet = new Bullet(universe, {
+                x:             cx,
+                y:             cy - 4,
+                w:             8,
+                h:             8,
+                speed:         bulletSpeed,
+                collisionType: bulletCollision,
+                color:         [40, 40, 40],
+                name:          'smoke_bullet',
+                loop:          true
+            });
+        }
+
+        return {
+            emitter:      emitter,
+            bullet:       bullet,
+            largeObjects: bullet ? [bullet.lo] : []
+        };
+    }
+
+    // ── Export ───────────────────────────────────────────────────────────────
+
+    setupFxSmoke.OPTIONS = OPTIONS;
+
+    export { setupFxSmoke };
+

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

@@ -0,0 +1,80 @@
+/* Copyright 2023-2026 by Essam Abadir */
+
+/**
+ * setupG1Race — UNIT-TEST experiment G1: "LO (a Frame) races a Dim-0 quantum".
+ *
+ * ── Layer 1: API contract ────────────────────────────────────────────────────
+ * @param {Object} universe - Engine universe (WASM; this experiment is wasmOnly).
+ * @param {Object} [opts]
+ * @param {number} [opts.speedProb=0.5] - Initial speed probability for the "LO" frame.
+ * @returns {{ loHandle, loQid, quantumHandle, startX, speedProb }}
+ *   loQid — the QUANTUM_ID of the LO frame (use with setFrameProperty — NOT loHandle).
+ *
+ * ── Layer 2: physics behavior (what this PROVES) ─────────────────────────────
+ * The realization of "an LO extends Frame": both racers are LEAF FRAMES moving
+ * rightward (vx=1), wrapping the canvas. The reference is a Dim-0 "light" quantum —
+ * a fundamental particle that ALWAYS steps (P=1, the speed limit). The "LO" is a
+ * larger Dim-2 leaf (4px voxel) that takes its along-momentum step with probability
+ * = its `speed_prob` (default 0.5) — so it falls behind the light at a rate set by
+ * that probability (E=MC²: a fuller/heavier frame's children have fewer free pixels,
+ * so more of a push converts to motion; here the user sets the probability directly).
+ * The orthogonal wavelength (transverse jitter) is unchanged — only the forward rate
+ * is gated. Sweeping speed_prob 1.0 → 0 sweeps the LO from light-speed to frozen.
+ */
+
+import { assertSetupOptions as _assertSetupOptions, requireWorldRect as _requireWorldRect } from './_setupOptions.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.
+
+    /**
+     * OPTIONS — this factory's own option vocabulary: EXACTLY the keys it reads.
+     * Exported as `setupG1Race.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 = [
+        'loLevel', 'speedProb',
+    ];
+
+    function setupG1Race(universe, opts) {
+        opts = _assertSetupOptions('setupG1Race', opts, OPTIONS);
+        // The world rect the co-init call wrote (EGPTUniverse.create({rect})) — the ONE size.
+        var rect = universe.universe_rect;
+        var ch = _requireWorldRect('setupG1Race universe.universe_rect', rect).h;
+        var startX = 30;
+        var speedProb = (opts.speedProb !== undefined) ? opts.speedProb : 0.5;
+
+        // 2D walk: a gentle transverse wavelength so the racers jitter sideways a little
+        // while the LONGITUDINAL race (the speed_prob gate) is the visible story.
+        universe.init(0, { wavelengthScale: 16, brownianMotion: false });
+
+        // Register Dim 6 so the "LO" can be a 64px voxel/frame there — a big body that
+        // renders clearly as a cube in 3D. The leaf still moves under the move pass; the
+        // gate applies. (mass fullness has a color interpretation via LightColor/Chroma.)
+        var loLevel = (opts.loLevel !== undefined) ? opts.loLevel : 6;   // 2^6 = 64px voxel
+        universe.addDimension(loLevel);
+
+        // Reference: a Dim-0 LIGHT quantum (always P=1), blue, wrapping.
+        var quantumHandle = universe.makeLeafFrame(
+            startX, Math.floor(ch * 0.32), 0, null, 1, 0, true, 0, [120, 200, 255]);
+        universe.injectFrame(quantumHandle);
+
+        // The "LO": a Dim-6 leaf (64px voxel), gold, wrapping — moves with a speed probability.
+        var loHandle = universe.makeLeafFrame(
+            startX, Math.floor(ch * 0.62), loLevel, null, 1, 0, true, 0, [255, 180, 80]);
+        universe.injectFrame(loHandle);
+
+        // set/getFrameProperty key on the QUANTUM_ID, not the makeLeafFrame handle.
+        var loQid = universe.getFrameQuantumId(loHandle);
+        universe.setFrameProperty(loQid, 'speed_prob', speedProb);
+
+        return { loHandle: loHandle, loQid: loQid, quantumHandle: quantumHandle,
+                 startX: startX, speedProb: speedProb };
+    }
+
+    setupG1Race.OPTIONS = OPTIONS;
+
+    export { setupG1Race };
+

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

@@ -0,0 +1,89 @@
+/* Copyright 2023-2026 by Essam Abadir */
+
+/**
+ * setupG2Sweep — UNIT-TEST experiment G2: a MOVING LargeObject (LO extends Frame)
+ * sweeps a field of stationary targets and its collision trigger ABSORBS them.
+ *
+ * ── Layer 1: API contract ────────────────────────────────────────────────────
+ * @param {Object} universe - WASM universe (this experiment is wasmOnly).
+ * @param {Object} [opts]
+ * @param {number} [opts.speedProb=0.6] - Speed probability of the LO's backing frame.
+ * @returns {{ lo, bodyHandle, bodyQid, targets:number, searchW:number }}
+ *
+ * ── Layer 2: physics behavior (what this PROVES) ─────────────────────────────
+ * G2 = "an LO extends Frame" by COMPOSITION. A `LargeObject` is linked to a BACKING
+ * FRAME (a moving leaf) via setLargeObjectFrame; the engine re-centers the LO's search
+ * rect on the frame every tick, so the LO MOVES via the normal move pass + speed_prob
+ * gate (G1). Its search rect (searchW) is LARGER than the 1px body — collisions fire
+ * over the rect, not the frame. The LO's `on:'collision'` op-program (ABSORB here)
+ * runs across its observed dimensions. So the LO both moves like a Frame AND triggers
+ * multi-dimensionally — with the backing frame excluded from its own trigger.
+ */
+
+import { assertSetupOptions as _assertSetupOptions, requireWorldRect as _requireWorldRect } from './_setupOptions.js';
+import { LargeObject } from '../../parts/LargeObject.js';
+import { CollisionTypes } from '../../parts/CollisionTypes.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.
+
+    /**
+     * OPTIONS — this factory's own option vocabulary: EXACTLY the keys it reads.
+     * Exported as `setupG2Sweep.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 = [
+        'speedProb',
+    ];
+
+    function setupG2Sweep(universe, opts) {
+        opts = _assertSetupOptions('setupG2Sweep', opts, OPTIONS);
+        // The world rect the co-init call wrote (EGPTUniverse.create({rect})) — the ONE size.
+        var rect = universe.universe_rect;
+        var world = _requireWorldRect('setupG2Sweep universe.universe_rect', rect);
+        var cw = world.w, ch = world.h;
+        var speedProb = (opts.speedProb !== undefined) ? opts.speedProb : 0.6;
+
+        universe.init(0, { wavelengthScale: 1, brownianMotion: false });
+
+        // ── Target field: a grid of STATIONARY quanta the LO will sweep through. ──
+        var targets = 0;
+        for (var gx = Math.floor(cw * 0.28); gx <= Math.floor(cw * 0.82); gx += 36) {
+            for (var gy = Math.floor(ch * 0.22); gy <= Math.floor(ch * 0.78); gy += 36) {
+                var th = universe.makeLeafFrame(gx, gy, 0, null, 0, 0, false, 0, [90, 150, 220]);
+                universe.injectFrame(th);
+                universe.setFrameProperty(universe.getFrameQuantumId(th), 'is_stationary', true);
+                targets++;
+            }
+        }
+
+        // ── LO BODY: a leaf moving rightward (speed_prob gated), mid-height. ──
+        var bodyY = Math.floor(ch * 0.5);
+        var bodyHandle = universe.makeLeafFrame(20, bodyY, 0, null, 1, 0, false, 0, [255, 120, 80]);
+        universe.injectFrame(bodyHandle);
+        var bodyQid = universe.getFrameQuantumId(bodyHandle);
+        universe.setFrameProperty(bodyQid, 'speed_prob', speedProb);
+
+        // ── The LO: a TALL search rect (covers the field height) + ABSORB trigger. ──
+        // Its rect (searchW × searchH) is far larger than the 1px body — the collision
+        // fires over the rect. ABSORB kills any (non-body) frame inside it.
+        var searchW = 40, searchH = Math.floor(ch * 0.72);
+        var lo = new LargeObject(
+            universe,
+            [20 - searchW / 2, bodyY - searchH / 2, searchW, searchH],
+            CollisionTypes.NONE, ['ABSORB'],
+            'g2_sweeper', 'closest', null, 1, [255, 120, 80]
+        );
+        // Link the LO to its backing frame → it MOVES with the body each tick.
+        universe.setLargeObjectFrame(lo.handle, bodyHandle);
+
+        return { lo: lo, bodyHandle: bodyHandle, bodyQid: bodyQid,
+                 targets: targets, searchW: searchW, searchH: searchH, bodyY: bodyY };
+    }
+
+    setupG2Sweep.OPTIONS = OPTIONS;
+
+    export { setupG2Sweep };
+