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

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

@@ -0,0 +1,239 @@
+/* Copyright 2023-2026 by Essam Abadir */
+
+/**
+ * setupTraceCircuit — the smallest complete circuit on this floor: SOURCE → TRACE → GROUND.
+ *
+ * ── Layer 1: API contract ────────────────────────────────────────────────────
+ *
+ * Composes THREE already-committed pieces and adds no physics of its own (SU1):
+ *   1. a `SphereEmitter` on the `'laser'` preset — the VOLTAGE source, parked just
+ *      inside the Trace's inlet and aimed down the first leg, so the whole burst is
+ *      fed into the bore instead of sprayed at the inlet walls;
+ *   2. a `Trace` — the WIRE (mirror `Tunnel` runs + directed `Tunnel` corners);
+ *   3. that Trace's own `ground:true` terminal — the SINK, which also tallies delivery.
+ *
+ * @param {Object} universe - a constructed, NOT-yet-init'd EGPTUniverse. This factory
+ *   IS the sketch: it inits the world FIRST and then constructs parts (world.init()
+ *   FIRST → CONSTRUCT parts → WIRE → RUN), so part construction order is irrelevant.
+ *   Runs the FAST PATH
+ *   (`withInterQuantumCollisions:false`): that is the lossless-waveguide regime the
+ *   Trace datasheet is quoted in. Turning inter-quantum collisions ON is RESISTANCE and
+ *   makes this a different, current-limited component.
+ * @param {Object} [options]
+ * @param {Array<Array<number>>} [options.path] - the Trace route (cardinal waypoints).
+ *   Default: a straight 400px run across the middle of the canvas.
+ * @param {number} [options.bore=12] @param {number} [options.wallThickness=6]
+ * @param {number} [options.voltage=6] - emitter burst per tick. LIVE. Measured Ohmic:
+ *   delivered current is a straight multiple of this with no knee (see Layer 2).
+ * @param {boolean} [options.active=true]
+ * @param {number} [options.lanes=1] - build N PARALLEL Traces at the published pitch,
+ *   sharing rails, with only lane 0 energised. This is the miniaturization demo: the
+ *   dark lanes are the crosstalk measurement.
+ *
+ * @returns {{ trace, traces, emitterControl, traceControl, largeObjects, onTick, dispose }}
+ *   `traceControl` is the live sugar handle (the canonical knob pattern):
+ *   `setVoltage/getVoltage`, `setActive`, `getDelivered`, `getCurrent`,
+ *   `getConductance`, `getCrosstalk`, `controls`.
+ *
+ * ── Layer 2: physics behavior ────────────────────────────────────────────────
+ * Zero new physics. What the two knobs do to the running scene:
+ *
+ *   `voltage` (emitter burst/tick) — the current is LINEAR in it with no ceiling in
+ *   this regime: the Trace is a lossless waveguide, so whatever the source pushes in
+ *   arrives. Conductance (delivered/tick ÷ emitted/tick) measured 1.00 ± 0.02 on a
+ *   straight run against 0.29 for the same source and ground with the Trace REMOVED.
+ *
+ *   `lanes` — stacks independent parallel Traces wall-against-wall at
+ *   `Trace.lanePitch(bore, wallThickness)`. Only lane 0 is fed; the readout on the dark
+ *   lanes IS the crosstalk measurement — 0.98 % into the immediately adjacent lane at
+ *   bore 3 / wall 3 (9px pitch), and EXACTLY zero into every lane beyond it. This is the
+ *   picture that shows the part shrinks: four 3px-bore lanes inside a 36px band with the
+ *   energised lane still at G = 0.98.
+ *
+ * The full datasheet — bore, length, wall-thickness floor, corner throughput — lives in
+ * `Trace.js`'s Layer 2. It is quoted there once and not restated here.
+ */
+
+import { assertSetupOptions as _assertSetupOptions, requireWorldRect as _requireWorldRect } from './_setupOptions.js';
+import { Trace } from '../../parts/Trace.js';
+import { setupSphereEmitter3D } from './setupSphereEmitter3D.js';
+
+    /** Degrees → the emitter yaw that aims a burst down the Trace's first leg. */
+    function _aimDeg(path) {
+        var dx = path[1][0] - path[0][0], dy = path[1][1] - path[0][1];
+        if (dx > 0) { return 0; }
+        if (dx < 0) { return 180; }
+        return dy > 0 ? 90 : 270;
+    }
+    /**
+     * OPTIONS — this factory's own option vocabulary: EXACTLY the keys it reads.
+     * Exported as `setupTraceCircuit.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 = [
+        'active', 'bore', 'lanes', 'path',
+        'runner', 'voltage', 'wallThickness',
+    ];
+
+    function setupTraceCircuit(universe, options) {
+        options = _assertSetupOptions('setupTraceCircuit', options, OPTIONS);
+        var TraceCls = Trace;
+        var emitterFactory = setupSphereEmitter3D;
+
+        // The world rect the co-init call wrote (EGPTUniverse.create({rect})) — the ONE size.
+        var world = _requireWorldRect('setupTraceCircuit universe.universe_rect', universe.universe_rect);
+        var W = world.w, H = world.h;
+        var bore = options.bore !== undefined ? options.bore : 12;
+        var wallThickness = options.wallThickness !== undefined ? options.wallThickness : 6;
+        var voltage = options.voltage !== undefined ? options.voltage : 6;
+        var lanes = Math.max(1, options.lanes !== undefined ? options.lanes : 1);
+        var active = options.active !== undefined ? !!options.active : true;
+
+        // Independent Traces stack wall-against-wall. NOT bore+wallThickness: that would
+        // put each pair of neighbours' mirrors on the SAME pixels, which measured 31 %
+        // crosstalk while the energised lane still read G = 0.98 (a silent failure).
+        var pitch = TraceCls.lanePitch(bore, wallThickness);
+        var midY = Math.round(H / 2) - Math.round((lanes - 1) * pitch / 2);
+        var basePath = options.path || [[40, midY], [Math.max(140, W - 60), midY]];
+
+        // ══ STEP 1 — THE WORLD ══════════════════════════════════════════════
+        // This factory IS the sketch: it inits the world FIRST, before any part.
+        // Everything below is part construction, and construction ORDER among parts
+        // no longer matters (the old "source first, walls second" idiom existed only
+        // because the emitter factory owned init; it does not any more).
+        var aim = _aimDeg(basePath);
+        var inPort = basePath[0];
+        var inset = 4;
+        var emitterOpts = {
+            preset: 'laser', is2D: true, R: 24,
+            center: [
+                inPort[0] + (aim === 0 ? inset : aim === 180 ? -inset : 0),
+                inPort[1] + (aim === 90 ? inset : aim === 270 ? -inset : 0)
+            ],
+            orientationDeg: aim,
+            emissionBoxSide: 0, fundamentalDimension: 0,
+            burstSize: voltage, emitEveryTicks: 1,
+            chargeMode: 'random'
+        };
+        emitterFactory.initWorld(universe, emitterOpts);
+
+        // ══ STEP 2 — THE PARTS ══════════════════════════════════════════════
+        var emitterResult = emitterFactory(universe, emitterOpts);
+        var emitterControl = emitterResult.sphereEmitterControl;
+        emitterControl.setActive(active);
+
+        // Lane 0 carries the authored route; extra lanes are that route offset by the
+        // pitch, so exactly one wall of separation sits between neighbours (the measured
+        // stacking geometry).
+        var traces = [];
+        for (var i = 0; i < lanes; i++) {
+            var lanePath = basePath.map(function (p) { return [p[0], p[1] + i * pitch]; });
+            traces.push(new TraceCls(universe, {
+                path: lanePath, bore: bore, wallThickness: wallThickness,
+                ground: true, name: 'trace' + i,
+                color: i === 0 ? [90, 120, 200] : [70, 80, 110]
+            }));
+        }
+        var trace = traces[0];
+
+        var control = {
+            setVoltage: function (v) {
+                voltage = Math.max(0, Math.round(v));
+                emitterControl.setBurstSize(voltage);
+                return voltage;
+            },
+            getVoltage: function () { return voltage; },
+            setActive: function (v) { emitterControl.setActive(!!v); },
+            getDelivered: function () { return trace.getDelivered(); },
+            getCurrent: function () { return trace.getCurrent(); },
+            /** delivered/tick ÷ emitted/tick — 1.0 is a perfect conductor. */
+            getConductance: function () { return voltage ? trace.getCurrent() / voltage : 0; },
+            /** Fraction of lane 0's current appearing in the dark lanes (0 with lanes=1). */
+            getCrosstalk: function () {
+                if (traces.length < 2) { return 0; }
+                var lead = trace.getCurrent();
+                if (!lead) { return 0; }
+                var dark = 0;
+                for (var k = 1; k < traces.length; k++) { dark += traces[k].getCurrent(); }
+                return dark / lead;
+            },
+            getPitch: function () { return pitch; },
+            getLanes: function () { return traces.length; }
+        };
+
+        // The standardized descriptor array — declared ONCE, consumed by both the page's
+        // own sliders and any host control strip (the established `controls` idiom).
+        control.controls = [
+            {
+                id: 'voltage', label: 'voltage (burst/tick)',
+                min: 0, max: 32, step: 1, value: voltage,
+                fmt: function (v) { return String(v) + ' q/tick'; },
+                get: function () { return control.getVoltage(); },
+                onChange: function (v) { control.setVoltage(v); }
+            },
+            {
+                // REBUILD-class: bore is wall geometry, so the page re-runs setup().
+                id: 'bore', label: 'bore (rebuild)',
+                min: 1, max: 40, step: 1, value: bore, rebuild: true,
+                fmt: function (v) { return String(v) + 'px'; },
+                get: function () { return bore; },
+                onChange: function () { /* the page owns the rebuild — see `rebuild:true` */ }
+            },
+            {
+                id: 'lanes', label: 'parallel lanes (rebuild)',
+                min: 1, max: 8, step: 1, value: lanes, rebuild: true,
+                fmt: function (v) { return String(v) + ' @ ' + pitch + 'px pitch'; },
+                get: function () { return control.getLanes(); },
+                onChange: function () { /* rebuild */ }
+            }
+        ];
+
+        var result = {
+            trace: trace,
+            traces: traces,
+            emitterControl: emitterControl,
+            traceControl: control,
+            // FrqtlApp.setup() auto-wires this for rendering.
+            largeObjects: traces.reduce(function (acc, t) { return acc.concat(t.largeObjects); }, []),
+            /**
+             * The ONE per-tick call — drives every lane's junctions + ground sampling.
+             * `attachToRunner` below wires it for you; this stays public for a harness
+             * that ticks the universe directly with no runner.
+             */
+            onTick: function (tickData) {
+                for (var k = 0; k < traces.length; k++) { traces[k].onTick(tickData); }
+            },
+            /**
+             * Subscribe every lane to the runner's per-tick fan-out. REQUIRED: nothing in
+             * `FrqtlApp` calls a setupResult's `onTick`, so without this the corner
+             * junctions never redirect and `getDelivered()`/`getCurrent()` read 0 forever —
+             * which looks exactly like "the wire doesn't conduct" (QA hit precisely that).
+             * Uses `addTickListener`, the multi-subscriber peer of the page's single `onTick`
+             * slot, so it never steals the page's own hook. Idempotent per lane.
+             * @param {Object} runner - an FrqtlApp.
+             */
+            attachToRunner: function (runner) {
+                for (var k = 0; k < traces.length; k++) { traces[k].attachToRunner(runner); }
+                return result;
+            },
+            // CANONICAL TEARDOWN — the runner calls this before installing the next
+            // setupResult, so a rebuild never stacks emitters or walls. Each Trace's own
+            // dispose drops its tick subscription too.
+            dispose: function () {
+                if (emitterResult && typeof emitterResult.dispose === 'function') { emitterResult.dispose(); }
+                traces.forEach(function (t) { t.dispose(); });
+            }
+        };
+
+        // Auto-wire when the caller hands us the runner (the page idiom below). Optional:
+        // a caller without a runner calls `result.attachToRunner(runner)` after setup, or
+        // drives `result.onTick(tickData)` itself.
+        if (options.runner) { result.attachToRunner(options.runner); }
+        return result;
+    }
+
+    setupTraceCircuit.OPTIONS = OPTIONS;
+
+    export { setupTraceCircuit };
+

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

@@ -0,0 +1,240 @@
+/* Copyright 2023-2026 by Essam Abadir */
+
+/**
+ * setupTunnelLab — DirectedTunnel ISOLATION (I1, the directed-tunnel composition model
+ * §3): ONE `DirectedTunnel`, gun-chamber mechanics (fill / escape / dispersion) at a
+ * live-tunable scale — the visual half of the scale-sweep measurement, same methodology,
+ * same source shape.
+ *
+ * ── Layer 1: API contract ────────────────────────────────────────────────────
+ *
+ * @param {Object} universe - WASM universe (not yet init'd — this factory calls init()).
+ *   NOTE ON DETERMINISTIC SEEDING: same convention as every other setup factory
+ *   (`setupGunChamber.js`) — `universe` arrives ALREADY
+ *   CONSTRUCTED with its seed fixed by `FrqtlApp`; there is no `opts.seed` here.
+ * @param {Object} [opts]
+ * @param {number} [opts.bore=40] - Tunnel bore (interior height/cross-section), pixels.
+ *   REINIT-CLASS (changing it needs a fresh `runner.setup()` — matches the sweep's own
+ *   per-cell tunnel construction; the tunnel geometry is not a live-resizable rect).
+ * @param {number} [opts.length=240] - Tunnel length (interior width), pixels. REINIT-CLASS.
+ * @param {number} [opts.wavelength=64] - Per-frame wavelength override for EVERY hand-
+ *   placed source quantum (the SAME `makeLeafFrame` per-frame override the sweep uses —
+ *   `QuantumEmitter` has no wavelength field, which is exactly why this factory hand-
+ *   places quanta via a local host tick-fn instead of `DirectedTunnel`'s `options.emitter`
+ *   — see the Layer 2 note below). LIVE (`setupResult.sourceState.wavelength`).
+ *   **CEILING ("the wavelength slider has no effect"
+ *   root cause):** Engine Invariant #6 is `mass = max(1, capacity/wavelength)` —
+ *   at this factory's `FUNDAMENTAL_DIMENSION=2`, `capacity = (2^2)^2 = 16`
+ *   (`setupTunnelLab.CAPACITY`, exported below), so ANY `wavelength >= capacity`
+ *   (16) saturates `mass` at its floor (1) and therefore ALSO saturates the
+ *   DERIVED wavelength (`capacity/mass`) at exactly `capacity` (16) — `wavelength:
+ *   64`, `128`, or `1000000` are ALL physically IDENTICAL to `wavelength: 16`
+ *   (same mass, same transverse-oscillation period). This was NOT a collision-
+ *   reset bug (verified: `mass` survives every wall behavior — option1/option2/
+ *   composable — unchanged across ticks, pkg-node probe) — it is a genuine
+ *   ceiling in the formula. Only `wavelength` values in `(0, capacity]` (i.e.
+ *   `(0, 16]` here) produce DISTINCT mass/oscillation-period values; `tunnel-lab
+ *   /index.html`'s own wavelength slider is clamped to `setupTunnelLab.
+ *   MAX_USEFUL_WAVELENGTH` (= `CAPACITY`) for exactly this reason — one
+ *   authority, no hand-typed "16" duplicate in the page.
+ * @param {string} [opts.wallBehavior='option2'] - Initial `DirectedTunnel.behavior`
+ *   (`DirectedTunnel.BEHAVIORS` — option1 | option2 | any `SlitLinerScatter` composable
+ *   name). LIVE — `setupResult.tunnel.updateBehavior(newBehavior)`.
+ * @param {number} [opts.sourceDensity=5] - Quanta hand-placed per burst. LIVE
+ *   (`setupResult.sourceState.density`). NOTE: this is the FACTORY's own
+ *   omitted-opt default (unchanged, for any headless caller) — `tunnel-lab
+ *   /index.html`'s own UI default is 10 (the
+ *   population-density fix: the page ALWAYS passes an explicit value read
+ *   from its own `<input>` default, so this factory default is never
+ *   actually reached by the page — see that file's own docstring for the
+ *   pkg-node-measured TPS/alive-count calibration against `setupGunChamber
+ *   .js`'s own 20/tick emission rate).
+ * @param {number} [opts.sourceRate=10] - Ticks between bursts (an `everyNTicks`-style
+ *   cadence, mirroring `emitterProgram.js`'s own live cadence knob). LIVE
+ *   (`setupResult.sourceState.rate`). NOTE: same as `sourceDensity` above —
+ *   the factory default (unchanged) vs. the page's own UI default (1) diverge
+ *   for the same reason.
+ * @param {boolean} [opts.sourceActive=true] - Master on/off for the burst source. LIVE
+ *   (`setupResult.sourceState.active`).
+ * @param {number} [opts.depth] - 3D toggle. OMITTED
+ *   (default) -> 2D (byte-identical to every pre-existing caller). A positive
+ *   value -> real z-containment (`activeAxes:{x,y,z}` on `universe.init()`,
+ *   `DirectedTunnel`'s own `depth`/`z=-depth/2`, hand-placed quanta z-centred)
+ *   — the standard `options.depth` recipe. REINIT-CLASS
+ *   (only meaningful at construction, like bore/length).
+ * @param {'spray'|'beam'} [opts.velocityProfile='spray'] - tunnel-lab has the
+ *   source-profile selection off the shared surface: the SAME `SustainedSource.SOURCE_SPEC_FIELDS.
+ *   velocityProfile` axis `LightSource`'s own `particleWalk` burst always uses
+ *   (`'beam'`, hardcoded there) — exposed here so tunnel-lab can be set to
+ *   `'beam'` and produce a directly comparable collimated source to
+ *   lightsource-lab's default particleWalk mode at matched bore/length/
+ *   wavelength/wallBehavior ("same settings -> same visuals"). Default `'spray'`
+ *   — byte-identical to every pre-existing caller (this factory's own original
+ *   hardcoded biased-fan shape, unchanged). LIVE (`setupResult.sourceState.
+ *   velocityProfile` — `placeSourceQuanta` reads it fresh every burst, no reinit).
+ *
+ * @returns {{
+ *   tunnel: DirectedTunnel, sourceState: {density:number, rate:number, wavelength:number,
+ *   active:boolean}, largeObjects: LargeObject[]
+ * }}
+ * `largeObjects` (= `tunnel.largeObjects`) is the canonical key `FrqtlApp.setup()`
+ * auto-wires for rendering (matches every other setup factory).
+ *
+ * ── Layer 2: physics behavior ────────────────────────────────────────────────
+ *
+ * **Zero new physics (canonical-bench SU1)** — this factory only WIRES existing
+ * primitives: `DirectedTunnel` (itself zero new physics over `Tube`), and a burst source
+ * built from the SAME `makeLeafFrame`+`injectFrame`+`universe.random()` primitives the
+ * scale-sweep script and every hand-placed-quantum experiment already use. The source is
+ * a LOCAL host tick-fn (NOT `QuantumEmitter`) because `QuantumEmitter`'s constructor has
+ * no wavelength field — the isolation lab needs the SAME per-frame wavelength override
+ * the scale sweep uses so the page visually demonstrates EXACTLY what the sweep
+ * measured, not a physically-different (unmodifiable-wavelength) source. Pushed onto
+ * `universe.experimentTickFunctions` (Phase A, matching `emitterProgram.js`'s own
+ * registration point) — legitimate here because, unlike `DirectedTunnel`'s `option1`
+ * redirect (which needs Phase-D `tickData`), injection is a pre-tick primitive with no
+ * such timing constraint.
+ *
+ * **Gun-chamber convention**: `capNegX:true, capPosX:false` — a CLOSED breech (source
+ * fires INTO the bore, quanta bounce/fill) and an OPEN muzzle (quanta escape, then
+ * disperse freely with no walls) — the Gun-Chamber model (particles ping-pong
+ * in a tube, escape the open end, spread comes from dispersion AFTER escape).
+ *
+ * **Fundamental dimension = 2** (matches `setupDoubleSlit.js`'s default AND the scale-
+ * sweep's own convention — level 0 pins wavelength to a no-op): a level-0 leaf has `capacity=1`, so
+ * `mass=max(1,capacity/wavelength)` is PINNED at 1 for any `wavelength>=2` — the
+ * wavelength slider would be a silent no-op at level 0.
+ *
+ * **Biased entrance (bunched near the TOP wall)** — the SAME shape the scale sweep uses,
+ * because a symmetric/spread entrance is already balanced and shows no washout effect at
+ * all (the scale sweep's own finding); bunching is what makes
+ * "uniformizes vs transmits unmodified" visually OBSERVABLE as the population fills the
+ * bore over time.
+ */
+
+import { assertSetupOptions as _assertSetupOptions, requireWorldRect as _requireWorldRect } from './_setupOptions.js';
+import { DirectedTunnel } from '../objects/DirectedTunnel.js';
+import * as SustainedSource from '../objects/sustainedSource.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 ─────────────────────────────────────────────────────────────
+
+    var FUNDAMENTAL_DIMENSION = 2; // matches setupDoubleSlit.js + the scale-sweep script
+
+    // The ONE authority for "what's the largest
+    // wavelength value that still produces a DISTINCT mass from any larger one"
+    // at this factory's FUNDAMENTAL_DIMENSION. Engine Invariant #6:
+    // `mass = max(1, capacity/wavelength)` — the floor (mass=1) is reached
+    // exactly at `wavelength === capacity`; every wavelength beyond that is
+    // indistinguishable. `tunnel-lab/index.html` reads this (never a hand-typed
+    // "16" literal) to clamp its wavelength slider's max to the achievable range.
+    // Derived from `SustainedSource.capacityAtDimension` — the SAME
+    // authority `setupLightSourceLab.js` now also derives its own
+    // MAX_USEFUL_WAVELENGTH from (AC4: "same MAX_USEFUL_WAVELENGTH clamp
+    // authority" for both labs).
+    var TUNNEL_LAB_CAPACITY = SustainedSource.capacityAtDimension(FUNDAMENTAL_DIMENSION); // 16 at FUNDAMENTAL_DIMENSION=2
+    /**
+     * OPTIONS — this factory's own option vocabulary: EXACTLY the keys it reads.
+     * Exported as `setupTunnelLab.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 = [
+        'bore', 'depth',
+        'length', 'sourceActive', 'sourceDensity', 'sourceRate',
+        'velocityProfile', 'wallBehavior', 'wavelength',
+    ];
+
+    function setupTunnelLab(universe, opts) {
+        opts = _assertSetupOptions('setupTunnelLab', opts, OPTIONS);
+        // The world rect the co-init call wrote (EGPTUniverse.create({rect})) — the ONE size.
+        var canvasRect = universe.universe_rect;
+        var world = _requireWorldRect('setupTunnelLab universe.universe_rect', canvasRect);
+        var cw = world.w, ch = world.h;
+
+        var bore = opts.bore !== undefined ? opts.bore : 40;
+        var length = opts.length !== undefined ? opts.length : 240;
+        var wavelength = opts.wavelength !== undefined ? opts.wavelength : 64;
+        var wallBehavior = opts.wallBehavior !== undefined ? opts.wallBehavior : 'option2';
+        var sourceDensity = opts.sourceDensity !== undefined ? opts.sourceDensity : 5;
+        var sourceRate = opts.sourceRate !== undefined ? opts.sourceRate : 10;
+        var sourceActive = opts.sourceActive !== undefined ? !!opts.sourceActive : true;
+        // OPT-IN 3D, OMISSION-preserves-2D
+        // (the "before adding a creation-method parameter" discipline): mirrors
+        // the standard `options.depth` recipe — omitted/null ->
+        // 2D (zContain:false, byte-identical to every existing caller); a
+        // positive value -> real z-containment (Tube/DirectedTunnel heritage —
+        // `options.depth` already existed on DirectedTunnel, T1; this factory
+        // simply now forwards it + arms activeAxes).
+        var depth = (opts.depth !== undefined && opts.depth !== null) ? opts.depth : null;
+        // Default 'spray' is byte-identical to every pre-existing
+        // caller (this factory's own original hardcoded value below).
+        var velocityProfile = opts.velocityProfile !== undefined ? opts.velocityProfile : 'spray';
+
+        var initOpts = {};
+        if (depth !== null) { initOpts.activeAxes = { x: true, y: true, z: true }; }
+        universe.init(FUNDAMENTAL_DIMENSION, initOpts);
+
+        var left = Math.round(cw * 0.1);
+        var top = Math.round(ch / 2 - bore / 2);
+
+        var tunnelOpts = {
+            left: left, top: top, length: length, width: bore,
+            capNegX: true, capPosX: false, // closed breech, open muzzle — Gun-Chamber convention
+            behavior: wallBehavior,
+        };
+        if (depth !== null) { tunnelOpts.depth = depth; tunnelOpts.z = -depth / 2; }
+        var tunnel = new DirectedTunnel(universe, tunnelOpts);
+
+        // One source surface: the recurring
+        // burst injector now routes through `sustainedSource.js`'s ONE
+        // `buildSustainedSource` authority — the SAME surface
+        // `setupLightSourceLab.js` (via `LightSource`'s own opt-in
+        // `options.sustain`) now also consumes. `velocityProfile:'spray'` +
+        // `entranceBias:'top'` reproduce this factory's PRE-EXISTING biased-
+        // random-fan shape EXACTLY (the "uniformization visible" demo shape —
+        // see the module docstring's "Biased entrance" note); `zIsotropy:true`
+        // (the default) is the 3D-SYMMETRIC EMISSION fix (§4
+        // option (a)) — when `depth` is armed, every burst now ALSO draws a `vz`
+        // symmetric to the `vy` spread, instead of pinning z-momentum at zero
+        // forever (the tester-measured z/y=0.23 flatness root cause).
+        var src = SustainedSource.buildSustainedSource(universe, tunnel.innerRect, true /* capNegX (Gun-Chamber closed breech) */, depth !== null, {
+            wavelength: wavelength,
+            velocityProfile: velocityProfile,
+            entranceBias: 'top',
+            zIsotropy: true,
+            density: sourceDensity,
+            rate: sourceRate,
+            active: sourceActive,
+        });
+        var sourceState = src.sourceState;
+
+        return {
+            tunnel: tunnel,
+            sourceState: sourceState,
+            // FrqtlApp.setup() (FrqtlApp.js:528) auto-wires
+            // the render list; today the world's own census carries them by construction.
+            largeObjects: tunnel.largeObjects,
+            // CANONICAL TEARDOWN (the reinit-
+            // compounding fix): `FrqtlApp.prototype.setup()` calls THIS
+            // automatically before installing the NEXT setupResult. Delegates to
+            // `src.dispose()` (the ONE `sustainedSource.js` teardown mechanism)
+            // rather than re-deriving the tag-then-splice idiom a second time.
+            dispose: src.dispose,
+        };
+    }
+
+    // ONE authority for the achievable wavelength ceiling at this factory's
+    // FUNDAMENTAL_DIMENSION (see the TUNNEL_LAB_CAPACITY comment above) — the
+    // page reads this instead of hand-typing "16".
+    setupTunnelLab.FUNDAMENTAL_DIMENSION = FUNDAMENTAL_DIMENSION;
+    setupTunnelLab.CAPACITY = TUNNEL_LAB_CAPACITY;
+    setupTunnelLab.MAX_USEFUL_WAVELENGTH = TUNNEL_LAB_CAPACITY;
+
+    setupTunnelLab.OPTIONS = OPTIONS;
+
+    export { setupTunnelLab };
+