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

package/dist/frqtl/objects/objects/emitterProgram.js

@@ -0,0 +1,209 @@
+/* Copyright 2023-2026 by Essam Abadir */
+
+/**
+ * emitterProgram.js — the emitter as an engine-AGNOSTIC handle-program (sugar).
+ *
+ * G-EMIT-2: the emitter is NOT an engine object and NOT a per-engine provider method — it is a
+ * host tick-function (a "handle program") composed entirely from the generic engine primitives
+ * `universe.random()`, `universe.makeLeafFrame(...)`, and `universe.injectFrame(...)`. Both engines
+ * (WASM canonical + the JS reference) expose those primitives identically, so this ONE function is
+ * the single source of emit behavior — replacing the former dual per-engine `registerEmitter`
+ * implementations (compat/providers + the JS reference engine).
+ *
+ * DRAW-ORDER CONTRACT (golden-locked on WASM — do not reorder):
+ *   per emitted leaf:  random()→x, random()→y, [random()→angle if randomDirection],
+ *                      [random()→charge if charge is null], then makeLeafFrame(...) which on WASM
+ *                      draws ONE more internally (the ctor charge-mirror, always). The JS reference
+ *                      makeLeafFrame draws 0 there (charge is passed in) — engines may diverge
+ *                      (WASM is canonical); only the WASM goldens are asserted.
+ *
+ *   OPT-IN 3D z-SPREAD: `em.zMin`/`em.zDepth` default to `null` — when
+ *   both are absent, ZERO additional draws execute and this tick-fn is byte-identical to the
+ *   contract above (every existing 2D caller — QuantumEmitter, PointSource — is unaffected).
+ *   When a caller opts in (`em.zMin` a number), ONE additional `random()` draw executes AFTER
+ *   `injectFrame` (uniformly distributing the emitted leaf across `[zMin, zMin+zDepth)`), then a
+ *   `setFrameProperty(qid, 'z', z)` write — the canonical z-placement precedent
+ *   (a THIRD setFrameProperty call, never inserted into the locked x/y/[angle]/[charge] sequence).
+ *   `makeLeafFrame` has no z argument — no engine change, this composes existing primitives.
+ *
+ *   OPT-IN 3D ISOTROPIC SCATTER: `em.zIsotropy`
+ *   (default falsy) — when BOTH `em.randomDirection` AND `em.zIsotropy` are true, the
+ *   random-direction draw becomes a full unit-SPHERE direction (azimuth + polar angle,
+ *   TWO draws replacing the 2D branch's ONE) instead of a 2D-plane circle, and the drawn
+ *   `vz` is written via a FOURTH `setFrameProperty` call (sharing the SAME qid lookup as
+ *   the zMin branch above when both are armed). Every existing `randomDirection:true`
+ *   caller has `zIsotropy` false/undefined and takes the unchanged 2D-circle branch —
+ *   byte-identical, zero extra draws.
+ *
+ * The emState object is OWNED by the sugar (QuantumEmitter / PointSource). The sugar mutates it
+ * directly for active / velocity / burst-size / source-rect changes — there is no provider
+ * setEmitter* ABI. The tick-fn closes over emState so those mutations take effect live.
+ *
+ * DSE LAB (systematic controls): `em.everyNTicks` (opt-in,
+ * default null/undefined = fire every active tick, byte-identical to every existing
+ * caller) throttles firing to once every N ticks — a LIVE, per-tick-read cadence knob
+ * (mutate `em.everyNTicks` directly on the live emState any time; no re-init). This is
+ * DIFFERENT from `delay`/`remainingDelay`, which is a ONE-TIME initial wait before the
+ * FIRST burst (`remainingDelay` never resets after reaching 0 — ground-truthed by
+ * reading this file — so `delay` cannot serve as a repeating rate control). `fireOnce`
+ * (exported below) is the manual single-burst primitive for a "FIRE" button —
+ * refactored out of the tick-fn's burst loop (`_fireBurst`) so BOTH the automatic
+ * per-tick path and a manual trigger share the IDENTICAL draw-order/injection logic;
+ * zero duplication, zero change to the golden-locked draw order for the automatic path.
+ */
+
+    'use strict';
+
+    /**
+     * Core burst-firing logic — shared by the automatic tick-fn AND `fireOnce` (the
+     * manual "FIRE" trigger). Extracted verbatim from the tick-fn (no logic change) so
+     * a manual single-burst call reuses the EXACT same draw-order/injection path as an
+     * automatic tick, rather than a second hand-rolled copy.
+     * @param {Object} universe
+     * @param {Object} em
+     */
+    function _fireBurst(universe, em) {
+        var burstLeft = em.burstSize;
+        for (var bi = 0; bi < burstLeft && em.remainingQuanta > 0; bi++) {
+            var rects = em.sourceRects;
+            for (var ri = 0; ri < rects.length && em.remainingQuanta > 0; ri++) {
+                var srcRect = rects[ri];                                   // [l, t, w, h]
+                var x = srcRect[0] + universe.random() * srcRect[2];       // draw 1
+                var y = srcRect[1] + universe.random() * srcRect[3];       // draw 2
+
+                var vx = em.vx;
+                var vy = em.vy;
+                var vzOut = null; // set only by the zIsotropy branch below
+                if (em.randomDirection) {
+                    if (em.zIsotropy) {
+                        // Velocity z-symmetry consistent with its
+                        // profile: a real-depth-armed ISOTROPIC point source scatters
+                        // on the unit SPHERE (azimuth + polar), not just the XY plane —
+                        // mirrors directedRedirectProgram.js's own polarSpreadRad>0
+                        // sphere draw. OPT-IN (em.zIsotropy defaults false) — zero extra
+                        // draws for every pre-existing randomDirection:true caller, which
+                        // takes the `else` 2D-circle branch unchanged (SAME single draw,
+                        // SAME golden-locked position in the sequence).
+                        var az = universe.random() * 2 * Math.PI;          // draw 3a
+                        var cosPolar = universe.random() * 2 - 1;          // draw 3b
+                        var sinPolar = Math.sqrt(Math.max(0, 1 - cosPolar * cosPolar));
+                        var speed3 = Math.sqrt(vx * vx + vy * vy) || 1;
+                        vx = Math.cos(az) * sinPolar * speed3;
+                        vy = Math.sin(az) * sinPolar * speed3;
+                        vzOut = cosPolar * speed3;
+                    } else {
+                        var angle = universe.random() * 2 * Math.PI;          // draw 3
+                        var speed = Math.sqrt(vx * vx + vy * vy) || 1;
+                        vx = Math.cos(angle) * speed;
+                        vy = Math.sin(angle) * speed;
+                    }
+                }
+
+                var chargeInt;
+                if (em.charge === null || em.charge === undefined) {
+                    chargeInt = (universe.random() < 0.5) ? 0 : 1;        // draw 4
+                } else {
+                    chargeInt = (em.charge === 'Positive' || em.charge === 'POSITIVE') ? 0 : 1;
+                }
+
+                // LEVEL (leaf scale) is a UNIVERSE property, NOT an emitter constant: a
+                // fundamental leaf is created at the universe's fundamental-dimension level
+                // (wave-interference / double-slit run at dimension 2 → 4×4 leaves, capacity 16
+                // → wavelength 16·WC). Pass null so makeLeafFrame derives it from the universe;
+                // a non-null em.fundamentalDim is an explicit override. (Hardcoding 0 here
+                // collapsed capacity 16→1 and wavelength 128→8 — the wave-richness regression.)
+                var level = (em.fundamentalDim != null) ? em.fundamentalDim : null;
+                // makeLeafFrame draws ONE more on WASM (ctor charge-mirror) → golden +1.
+                // R3-1: thread per-frame render.shape (10th) + render.outline (11th) EXACTLY as
+                // em.color is threaded (9th) — so QuantumEmitter/PointSource gain the same per-frame
+                // render reach SphereEmitter3D has. All three ride makeLeafFrame's WASM-side
+                // string_map merge stamp (0 RNG draws, golden preserved). Null default → no key →
+                // byte-identical for every pre-existing caller. WASM-ONLY (the frozen JS reference
+                // makeLeafFrame ignores the shape/outline positionals — a DOCUMENTED no-op, see the
+                // wasm-engine makeLeafFrame docstring + the render-intent-merge test; the realm is WASM).
+                var handle = universe.makeLeafFrame(
+                    x, y, level,
+                    (em.wavelength !== null && em.wavelength !== undefined) ? em.wavelength : 0,
+                    vx, vy, !!em.wrap, chargeInt,
+                    em.color || null,
+                    (em.renderShape != null && em.renderShape !== '') ? em.renderShape : null,
+                    (em.renderOutline != null) ? em.renderOutline : null
+                );
+                // liveQuantaCap refused the add: no leaf was born, so a finite quantumLimit is
+                // not spent on it (below the cap the handle is never null — byte-identical).
+                if (handle === null) { continue; }
+                universe.injectFrame(handle);
+
+                // OPT-IN 3D z-SPREAD (see module docstring). em.zMin is null for every
+                // existing 2D caller — this branch is dead code (0 extra draws) unless a
+                // caller explicitly opts in (PointSource `opts.zMin`/`opts.zDepth`).
+                // Shares the SAME qid lookup with the zIsotropy vz write
+                // below (never a second getFrameQuantumId call for the same handle).
+                var zMinArmed = (em.zMin !== null && em.zMin !== undefined);
+                if (zMinArmed || vzOut !== null) {
+                    var qid = universe.getFrameQuantumId(handle);
+                    if (zMinArmed) {
+                        var zDepth = (em.zDepth !== null && em.zDepth !== undefined) ? em.zDepth : 0;
+                        var z = em.zMin + (zDepth > 0 ? universe.random() * zDepth : 0); // extra draw, opt-in only
+                        universe.setFrameProperty(qid, 'z', z);
+                    }
+                    if (vzOut !== null) {
+                        universe.setFrameProperty(qid, 'vz', vzOut);
+                    }
+                }
+
+                em.remainingQuanta--;
+            }
+        }
+    }
+
+    /**
+     * Build a host tick-function that fires one emitter, drawing from the engine's single RNG and
+     * injecting leaves via the generic primitives. Push the returned fn onto
+     * `universe.experimentTickFunctions`.
+     *
+     * @param {Object} universe - engine universe exposing random()/makeLeafFrame()/injectFrame().
+     * @param {Object} em - emitter state: {
+     *     sourceRects: Array<[l,t,w,h]>, vx, vy, burstSize, charge: (null|'POSITIVE'|'NEGATIVE'),
+     *     randomDirection: bool, remainingQuanta: number, delay, remainingDelay,
+     *     active: bool, tombstoned: bool, color: [r,g,b,a]|null, wrap: bool,
+     *     wavelength: number|null, fundamentalDim: number, everyNTicks: number|null }
+     * @returns {Function} tick-fn (returns [] — frames are injected via injectFrame, not returned).
+     */
+    function buildEmitterTickFn(universe, em) {
+        return function () {
+            if (em.tombstoned || !em.active) return [];
+            if (em.remainingDelay > 0) { em.remainingDelay--; return []; }
+            if (em.remainingQuanta <= 0) return [];
+
+            // OPT-IN firing-rate cadence (DSE Lab): null/undefined/<=1 -> fire every
+            // active tick (byte-identical to pre-Lab behavior — this branch is dead
+            // code for every existing caller, which never sets em.everyNTicks).
+            if (em.everyNTicks !== null && em.everyNTicks !== undefined && em.everyNTicks > 1) {
+                em._rateCounter = (em._rateCounter || 0) + 1;
+                if (em._rateCounter % em.everyNTicks !== 0) return [];
+            }
+
+            _fireBurst(universe, em);
+            return [];
+        };
+    }
+
+    /**
+     * Manual single-burst trigger (DSE Lab "FIRE" button, autofire off). Bypasses the
+     * `active`/`remainingDelay`/`everyNTicks` GATING (an explicit user action should
+     * always fire on request) but still respects `tombstoned`/`remainingQuanta` (a
+     * disposed or already-exhausted emitter cannot be forced to fire past its limit).
+     * Reuses the IDENTICAL `_fireBurst` draw-order/injection path the automatic tick-fn
+     * uses — no second implementation.
+     * @param {Object} universe
+     * @param {Object} em
+     */
+    function fireOnce(universe, em) {
+        if (em.tombstoned || em.remainingQuanta <= 0) return;
+        _fireBurst(universe, em);
+    }
+
+
+export { buildEmitterTickFn, fireOnce };
+

package/dist/frqtl/objects/objects/frqtl-control-slider.js

@@ -0,0 +1,197 @@
+/* Copyright 2023-2026 by Essam Abadir */
+
+/**
+ * frqtl-control-slider.js — the SINGLE scalar-control widget
+ * (gym-controls-as-sugar, Layer B).
+ *
+ * ── Layer 1: API contract ────────────────────────────────────────────────────
+ *
+ * `mount(hostEl, opts) → { dispose() }` renders ONE slider+label+value row
+ * (appended into `hostEl`, a parent container — multiple sliders may share
+ * one `hostEl`, each disposable independently) from a normalized `kind:
+ * 'scalar'` descriptor's DISPLAY shape (`{id,label,min,max,step,value,
+ * valueText}` — the SAME serializable shape `lib/shim/rpc`'s dispatch and
+ * `frqtl-controls-panel.js`'s `listControls`/`setControlValue` already
+ * produce). Dragging the slider calls back into the caller, which decides
+ * HOW the value gets applied:
+ *
+ *   `opts.descriptor` — a LIVE, normalized descriptor object
+ *     (`{id,label,min,max,step,value,fmt,onChange}`) in the SAME window.
+ *     The STANDALONE in-app path: the widget mutates `descriptor.value` and
+ *     calls `descriptor.onChange(value)` DIRECTLY — no transport, no RPC,
+ *     the same-realm case.
+ *
+ *   `opts.initial` + `opts.onInput` — the DECOUPLED path: `opts.initial` is
+ *     the display-shape descriptor above; `opts.onInput(value)` is called on
+ *     drag and may return a plain `{value,valueText}` OR a
+ *     `Promise<{value,valueText}>` — the widget awaits either uniformly and
+ *     refreshes the displayed value/text from whatever settles. This is the
+ *     REMOTE path: the caller supplies an `onInput` that dispatches however
+ *     it needs to (e.g. `frqtl-controls-panel.js` passes
+ *     `function(v){ return handle.call('setControlValue',[name,d.id,v]); }`,
+ *     reusing its OWN `lib/shim/rpc`-backed transport handle) — this widget
+ *     itself knows NOTHING about registries, RPC, or transports; it is
+ *     PURELY the rendering/wiring widget (the architectural point of this
+ *     layer: "panel = collection host + transport plumbing; control lib =
+ *     the widget").
+ *
+ * Exactly one of `opts.descriptor` OR (`opts.initial` + `opts.onInput`) is
+ * required — FAIL-LOUD otherwise.
+ *
+ * ── DRY discipline (the architectural point of Layer B) ──────────────────────
+ *
+ * Before this layer, `frqtl-controls-panel.js` built slider+label+value DOM
+ * internally (one implementation). This file is now THE ONE slider-rendering
+ * implementation; `frqtl-controls-panel.js` REFACTORED to call `mount()` here
+ * once per `kind:'scalar'` descriptor instead of building rows itself — see
+ * that file's own `renderRows` for the (now much smaller) call site. No
+ * behavior change to the panel's public API or its two demo placements.
+ *
+ * ── Layer 2: physics behavior ────────────────────────────────────────────────
+ *
+ * This file adds ZERO physics — pure UI plumbing over a caller-supplied
+ * descriptor/callback. Moving this slider produces the IDENTICAL simulation
+ * effect as moving any other consumer of the same declared-once control
+ * (proven by the Layer-B Rule-0 oracle: collision-matrix's `angle` control
+ * driven simultaneously by its own page slider, the panel's slider, and a
+ * standalone `frqtl-control-slider` instance — all three the SAME CONTROLS
+ * array entry).
+ */
+
+
+/**
+ * mount(hostEl, opts) — render one slider+label+value row into `hostEl`.
+ *
+ * @param {HTMLElement} hostEl — parent container to append the row into.
+ * @param {object} opts
+ * @param {object} [opts.descriptor] — a LIVE, normalized descriptor
+ *   `{id,label,min,max,step,value,fmt,onChange}` — the in-app direct path.
+ * @param {{id:string,label:string,min:number,max:number,step:number,
+ *   value:number,valueText:string}} [opts.initial] — REQUIRED when
+ *   `opts.descriptor` is absent: the initial serializable display state.
+ * @param {(value:number) => (*|Promise<{value:number,valueText:string}>)} [opts.onInput] —
+ *   REQUIRED when `opts.descriptor` is absent: called with the new numeric
+ *   value on drag; its (possibly-Promised) return refreshes the displayed
+ *   value/text.
+ * @returns {{dispose: () => void, setValue: (value:number, valueText?:string) => void}}
+ *   `setValue` (gym-controls-as-sugar FULL CONVERGENCE build, Stage ii item 5
+ *   — the `ControlSync` reconciliation target) is DISPLAY-ONLY: it writes the
+ *   slider's `.value` DOM property and the value label directly and NEVER
+ *   fires `onInput`/`onChange` (setting an `<input>`'s `.value` property does
+ *   not dispatch a synthetic `input` event — only genuine user interaction
+ *   does; hard-tested via a spy in `frqtl-control-slider.test.mjs`). This is
+ *   what makes N concurrent widgets reconcilable without an echo/feedback
+ *   loop: `ControlSync` calls `setValue()` to REFLECT canonical state, which
+ *   can never itself re-trigger a write.
+ * @throws {Error} FAIL-LOUD on a missing host element, or when neither
+ *   `opts.descriptor` nor both of `opts.initial`/`opts.onInput` are supplied.
+ */
+function mount(hostEl, opts) {
+    opts = opts || {};
+    if (!hostEl) {
+        throw new Error('[frqtl-control-slider] mount requires a host element. (FAIL-LOUD.)');
+    }
+
+    var initial, onInput;
+    if (opts.descriptor) {
+        var d = opts.descriptor;
+        if (!d.id || typeof d.min !== 'number' || typeof d.max !== 'number' || typeof d.step !== 'number') {
+            throw new Error('[frqtl-control-slider] mount({descriptor}) requires a normalized ' +
+                'scalar descriptor with id/min/max/step. (FAIL-LOUD.)');
+        }
+        // A bind-only descriptor (no onChange) has NO write path this widget can
+        // execute — this file deliberately has zero dependency on registries/
+        // controlBind.js (Layer B: "the widget knows nothing about transports").
+        // Dragging it would otherwise silently do nothing (the exact class of
+        // bug the gym-controls-as-sugar FULL CONVERGENCE build fixed in the panel).
+        // Route a bind-only descriptor through frqtl-controls-panel.js instead
+        // (mode:'in-app'/'iframe', which DOES resolve bind execution), or mount
+        // this widget via the opts.initial/onInput decoupled path with onInput
+        // calling the panel's dispatch/RPC directly.
+        if (typeof d.onChange !== 'function' && d.bind) {
+            throw new Error('[frqtl-control-slider] mount({descriptor}) was given a bind-only ' +
+                'descriptor (id "' + d.id + '", no onChange) — the standalone opts.descriptor path ' +
+                'has no bind-execution context and cannot write it. Use frqtl-controls-panel.js\'s ' +
+                'mount() instead, or mount this widget via opts.initial + opts.onInput with onInput ' +
+                'calling the panel\'s dispatch/RPC. (FAIL-LOUD — never a silent no-op on drag.)');
+        }
+        initial = {
+            id: d.id, label: d.label, min: d.min, max: d.max, step: d.step, value: d.value,
+            valueText: (typeof d.fmt === 'function') ? d.fmt(d.value) : String(d.value)
+        };
+        onInput = function (v) {
+            d.value = v;
+            if (typeof d.onChange === 'function') { d.onChange(v); }
+            return { value: v, valueText: (typeof d.fmt === 'function') ? d.fmt(v) : String(v) };
+        };
+    } else {
+        if (!opts.initial || typeof opts.onInput !== 'function') {
+            throw new Error('[frqtl-control-slider] mount requires EITHER opts.descriptor OR ' +
+                'BOTH opts.initial and opts.onInput. (FAIL-LOUD.)');
+        }
+        initial = opts.initial;
+        onInput = opts.onInput;
+    }
+
+    var row = document.createElement('div');
+    row.className = 'frqtl-control-slider-row';
+    row.style.cssText = 'display:flex;align-items:center;gap:8px;margin:4px 0;font:12px sans-serif;color:#ccc;';
+
+    var labelEl = document.createElement('span');
+    labelEl.textContent = initial.label + ':';
+    labelEl.style.cssText = 'min-width:56px;';
+
+    var slider = document.createElement('input');
+    slider.type = 'range';
+    slider.min = initial.min; slider.max = initial.max; slider.step = initial.step; slider.value = initial.value;
+    slider.setAttribute('data-frqtl-control-id', initial.id);
+
+    var valEl = document.createElement('span');
+    valEl.textContent = initial.valueText;
+    valEl.style.cssText = 'min-width:32px;text-align:right;color:#ffb450;';
+
+    slider.addEventListener('input', function () {
+        var v = parseFloat(slider.value);
+        Promise.resolve(onInput(v)).then(function (result) {
+            if (result && result.valueText !== undefined) { valEl.textContent = result.valueText; }
+        }).catch(function (e) {
+            valEl.textContent = 'ERR';
+            if (typeof console !== 'undefined' && console.error) {
+                console.error('[frqtl-control-slider] onInput failed:', e);
+            }
+        });
+    });
+
+    row.appendChild(labelEl);
+    row.appendChild(slider);
+    row.appendChild(valEl);
+    hostEl.appendChild(row);
+
+    // Fallback formatter for setValue()'s optional valueText: the descriptor
+    // path still has a live `d.fmt`; the decoupled (opts.initial/onInput) path
+    // has no formatter at all (only the ORIGINAL initial.valueText), so
+    // setValue() callers on that path should pass valueText explicitly —
+    // String(v) is the honest default, never a fabricated format.
+    var formatFallback = (opts.descriptor && typeof opts.descriptor.fmt === 'function')
+        ? opts.descriptor.fmt
+        : function (v) { return String(v); };
+
+    return {
+        dispose: function () {
+            if (row.parentNode) { row.parentNode.removeChild(row); }
+        },
+        // Display-only reconciliation write — see the @returns docstring above
+        // for the no-loop invariant this depends on.
+        setValue: function (value, valueText) {
+            slider.value = value;
+            valEl.textContent = (valueText !== undefined) ? valueText : formatFallback(value);
+        }
+    };
+}
+
+// ── Export ────────────────────────────────────────────────────────────────────
+
+var FrqtlControlSlider = { mount: mount };
+
+export { FrqtlControlSlider };
+