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

package/dist/frqtl/parts/LargeObject.js

@@ -0,0 +1,406 @@
+/* Copyright 2023-2026 by Essam Abadir */
+
+/**
+ * LargeObject — Engine-agnostic large object (wall, boundary, detector).
+ * Engine-agnostic: works with both the JS reference engine and the Rust/WASM engine.
+ *
+ * Uses handle-based API: calls universe.registerLargeObject(spec) and stores
+ * the opaque handle for subsequent mutations.
+ *
+ * Emits the CANONICAL spec in JS-native vocabulary:
+ *   - collision_type: SCREAMING_SNAKE string
+ *   - actions: SCREAMING_SNAKE array
+ *   - reposition: literal string including 'closest'
+ * All engine-specific wire-format translation lives in the shim providers
+ * (compat/providers/js-engine.js and compat/providers/wasm-engine.js).
+ * No engine-sniffing above the shim (WS-A §2 invariant).
+ */
+
+import * as ct from './CollisionTypes.js';
+import * as ca from './CollisionActions.js';
+import { compileActions as _compileActions } from '../objects/objects/actionCompiler.js';
+import { Rectangle as _Rectangle } from './Rectangle.js';
+import { registerKind } from '../objects/kinds.js';
+import { SCOPE_DESCRIPTORS } from '../objects/schema/scopes.js';
+
+    var CollisionTypes, CollisionActions;
+
+    // PR-1 (Rectangle everywhere): this.rect is a REAL Rectangle instance (parts/Rectangle.js,
+    // imported — center↔left/top auto-recompute), not a hand-rolled {left,top,w,h} bag.
+
+    CollisionTypes = ct.CollisionTypes;
+    CollisionActions = ca.CollisionActions;
+
+    /**
+     * Build a LargeObject `.rect` for the 2D (4-element) case: a REAL Rectangle instance
+     * (is_centered=false) so a center write (`.x`/`.y`) auto-recomputes left/top and vice
+     * versa (PR-1 — audit item 3). A non-enumerable `toJSON` is attached so JSON-serializing
+     * consumers (codegen `_jsonCopy`, bundle export, save-state) still produce the SAME plain
+     * `{left,top,w,h}` shape they always did — the Rectangle's own enumerable fields are
+     * `_left/_x/...`, which WOULD drift; `toJSON` pins the wire shape. (`left/top/w/h` are read
+     * via getters by every direct consumer, so those are unaffected.) 6-element z/d rects are
+     * handled by the caller (a 2D Rectangle cannot carry z/d — see the constructor).
+     */
+    function _makeLoRect(left, top, w, h) {
+        if (typeof _Rectangle !== 'function') {
+            // Fail-soft: no Rectangle class in scope (degenerate env) → the legacy bare bag.
+            return { left: left, top: top, w: w, h: h };
+        }
+        var r = new _Rectangle(left, top, w, h, null, false);   // is_centered=false → (left,top) corner
+        Object.defineProperty(r, 'toJSON', {
+            value: function () { return { left: this.left, top: this.top, w: this.w, h: this.h }; },
+            enumerable: false
+        });
+        return r;
+    }
+
+
+    // ── Helpers ─────────────────────────────────────────────────────────
+
+    /**
+     * Normalize a rect to array form: legacy [left, top, w, h] (4 elements), or the
+     * explicit-z/depth [left, top, z, w, h, d] (6 elements — FRQTL-MAINT 2026-07-01,
+     * MIRRORS the engine's Rectangle::from_top_left(l,t,z,w,h,d) argument order; see
+     * egpt_wasm/src/lib.rs rect_to_z_capable_rectangle). Accepts: [l,t,w,h],
+     * [l,t,z,w,h,d], {left,top,w,h}, {left,top,w,h,z,d}, or Rectangle instances.
+     * Pure shape coercion — no engine knowledge.
+     */
+    function rectToArray(rect) {
+        if (!rect) return null;
+        if (Array.isArray(rect)) return rect;
+        if (rect.left !== undefined) {
+            if (rect.z !== undefined || rect.d !== undefined) {
+                return [
+                    rect.left, rect.top,
+                    rect.z !== undefined ? rect.z : 0,
+                    rect.w, rect.h,
+                    rect.d !== undefined ? rect.d : rect.w,
+                ];
+            }
+            return [rect.left, rect.top, rect.w, rect.h];
+        }
+        if (rect.x !== undefined && rect.width !== undefined) return [rect.x, rect.y, rect.width, rect.height];
+        return rect;
+    }
+
+    // ── LargeObject ─────────────────────────────────────────────────────
+
+    /**
+     * Engine-agnostic large object wrapper.
+     *
+     * @param {Object} universe - The engine universe instance (JS or WASM)
+     * @param {Array|Object} rect - Bounding rectangle [left, top, w, h], {left,top,w,h},
+     *   or — FRQTL-MAINT (2026-07-01), explicit z/depth — [left, top, z, w, h, d] /
+     *   {left, top, w, h, z, d}. MIRRORS the engine's Rectangle::from_top_left(l,t,z,w,h,d)
+     *   argument order (egpt_wasm/src/lib.rs rect_to_z_capable_rectangle). Omitting z/d
+     *   is back-compat: the engine defaults z=0, d=w (bit-identical to the pre-fix
+     *   hardcoded behavior) — WASM-only (the frozen JS reference engine is 2D-only and
+     *   ignores any elements past index 3).
+     *   IMPORTANT: always pass [left, top, w, h] (is_centered=false convention).
+     *   The engine constructs Rectangle(left,top,w,h,null,false) internally.
+     *   Never pass a center-based coordinate here — see Rectangle class (quadtree.js)
+     *   where is_centered defaults to TRUE, a common footgun.
+     * @param {string} collision_type - CollisionTypes value (SCREAMING_SNAKE)
+     * @param {Array<string>} actions - CollisionActions values (SCREAMING_SNAKE)
+     * @param {string} name - Identifier
+     * @param {string} reposition - Eject direction: 'top','bottom','left','right','closest'
+     * @param {Array|null} observedDimensions - Dimension layers to observe (legacy param;
+     *   prefer passing a single layer number via the `layer` property after construction,
+     *   or pass [layer] here). null = object is visible to all dimensions.
+     * @param {number} search_padding - RESERVED / UNUSED positional placeholder. The engine no
+     *   longer reads it: the collision search rect expands by the dimension's `mb_w`
+     *   (EGPTfrqtl.js::update). Kept as positional arg #8 so `color` (#9) stays in place for the
+     *   ~50 positional callers. Do not wire new behavior to it.
+     * @param {Array} color - RGB color [r, g, b]
+     * @param {boolean} [collectCollided=false] - G1: when true, the engine accumulates a
+     *   point-in-time FrameData copy for each collided frame into a per-LO buffer
+     *   (cleared at the start of each tick). Marshalled out in Phase D as
+     *   `tickData.objects[handle].frames` (no per-LO collision query).
+     */
+    function LargeObject(universe, rect, collision_type, actions, name, reposition, observedDimensions, search_padding, color, collectCollided) {
+        // Defaults
+        actions = actions || [];
+        name = name || '';
+        reposition = reposition || 'closest';
+        observedDimensions = observedDimensions || null;
+        search_padding = (search_padding !== undefined) ? search_padding : 1;
+        color = color || [120, 120, 120];
+        collectCollided = collectCollided || false;
+
+        this.universe = universe;
+        this._schemaKind = 'LargeObject';
+        // rect is [left, top, w, h] (legacy) or [left, top, z, w, h, d] (FRQTL-MAINT
+        // 2026-07-01, explicit z/depth) — is_centered=false convention either way.
+        var ra = rectToArray(rect);
+        this.rect = (ra.length === 6)
+            // 3D z/d rect — the canonical Rectangle is 2D (x,y,left,top,right,bottom); it
+            // cannot carry z/d. Keep the explicit bare bag for WASM-only 3D LOs (Tube
+            // slabs — box-vs-plane derivation reads rect.d). PR-1 flag: a z-capable Rectangle is
+            // a separate, larger change; out of this pass's scope (see the build report).
+            ? { left: ra[0], top: ra[1], z: ra[2], w: ra[3], h: ra[4], d: ra[5] }
+            // 2D rect — a REAL Rectangle instance (PR-1): center↔left/top auto-recompute.
+            : _makeLoRect(ra[0], ra[1], ra[2], ra[3]);
+        this.color = color;
+        this.alpha = 255;
+        this.visible = true;
+        this.drawAsCircle = false;
+        this.name = name;
+        this.collision_type = collision_type;
+        this.reposition = reposition;
+        this.search_padding = search_padding;
+        // G1: mirror collect_collided flag on JS-side wrapper.
+        this.collect_collided = collectCollided;
+        // this.actions is set after compilation (see compilation block below)
+
+        // layer: the single dimension index this object is scoped to (null = all).
+        // Derived from observedDimensions: if observedDimensions is [n], layer = n.
+        // Settable directly as lo.layer = n; the schema field reads/writes this.
+        this.layer = (Array.isArray(observedDimensions) && observedDimensions.length === 1)
+            ? observedDimensions[0]
+            : null;
+
+        // ── Action → op-program compilation (the ONLY execution path) ───────
+        // Every action and the collision_type velocity response are lowered to an
+        // op-program here, BEFORE registerLargeObject(), so the engine receives the
+        // behaviour atomically with the registration. There is no native dispatch to
+        // fall back to, so there is nothing to catch: a compiler that will not load, or
+        // an action that will not compile, is a bug that must surface at construction —
+        // swallowing it registers a wall that silently does nothing.
+        var _compile = _compileActions;
+        var compiled = _compile(actions, name, reposition, collision_type);
+        var compiledProgram = compiled.program;
+        // A compiled program owns ALL behaviour, so the spec's collision_type goes to
+        // NONE — the engine must never be handed a second, competing description.
+        var nativeCollisionType = (compiledProgram !== null) ? CollisionTypes.NONE : collision_type;
+
+        // Mirror the DECLARED actions on the JS-side wrapper: they are what the inspector
+        // shows and what serializeDesign must round-trip to rebuild this object. (This
+        // used to mirror the compiler's leftovers, which were always empty — so a saved
+        // design lost its actions.)
+        this.actions = actions.slice();
+
+        // Mirror the compiled op-program so the schema inspector / conformance suite
+        // can read it from the JS-side wrapper. null if nothing compiled.
+        this.program = compiledProgram;
+
+        // Emit the WIRE spec — and ONLY what the engine actually has. A LargeObject is
+        // {rect, name, observed_dimensions, program, collect_collided, region}; there is no
+        // collision_type, actions or reposition field on the ABI, so sending them describes
+        // a configuration nothing listens to. Those three stay on the JS wrapper above,
+        // where the inspector and serializeDesign read them.
+        void nativeCollisionType;
+        var spec = {
+            rect: ra,
+            name: name,
+            observed_dimensions: observedDimensions || [],
+        };
+
+        // Attach the compiled op-program atomically (if any).
+        // Both JS and WASM engines accept program in the registerLargeObject spec.
+        if (compiledProgram !== null) {
+            spec.program = compiledProgram;
+        }
+
+        // G1: attach collect_collided to spec when requested.
+        // Only include when true to keep the wire-format clean (false is the default).
+        if (collectCollided) {
+            spec.collect_collided = true;
+        }
+
+        this.handle = universe.registerLargeObject(spec);
+
+        // ── SELF-REGISTER INTO THE WORLD'S WRAPPER CENSUS ────────────────────
+        // CONSTRUCTED = IN THE WORLD = ON SCREEN. This is the ONE wrapper construction
+        // seam, so this is where THE_MINIMAL_SIM's own sentence ("LARGE OBJECTS …
+        // self-registers") becomes true for RENDER as well as physics. Before this, a
+        // second `runner.addLargeObject(lo)` call was required to be seen at all — a
+        // shadow census whose divergence from the engine registry produced an object that
+        // collided and counted correctly and was invisible in every picture, silently.
+        //
+        // The census lives on the WORLD (not on a host runner) because the primitive
+        // surface must be reachable with no host at all: a headless rig constructs walls on
+        // a bare universe, and coupling the constructor to an ambient runner would break
+        // the split's first law. The renderer DERIVES its draw list from here.
+        //
+        // The array is created on demand so ANY universe object carries a census — there is
+        // one code path, not a "if the universe supports it" fork.
+        if (!Array.isArray(universe.largeObjects)) { universe.largeObjects = []; }
+        universe.largeObjects.push(this);
+    }
+
+    /**
+     * setRect(rect) — move/resize THIS LO: the JS wrapper's drawn rect AND the engine's
+     * registered rect, in ONE call (the same pair a Wall's setRect keeps in step). `rect` is the
+     * write wire in the LO's OWN form: `[l,t,w,h]` for a 2D LO, `[l,t,z,w,h,d]` for a z-capable
+     * one — a mismatched form THROWS (an LO's z-capability is fixed at construction). A part
+     * moving a member it owns (an emitter's Design marker) calls this. Zero physics: placement.
+     * @param {number[]} rect @returns {LargeObject} this
+     */
+    LargeObject.prototype.setRect = function (rect) {
+        var deep = (typeof this.rect.z === 'number');
+        if (!Array.isArray(rect) || rect.length !== (deep ? 6 : 4) ||
+            !rect.every(function (v) { return typeof v === 'number' && isFinite(v); })) {
+            throw new TypeError('[LargeObject.setRect] "' + this.name + '" is a ' + (deep ? 'z-capable' : '2D') +
+                ' LO and takes ' + (deep ? '[l,t,z,w,h,d]' : '[l,t,w,h]') + ' of finite numbers; got ' +
+                JSON.stringify(rect) + '. (FAIL-LOUD.)');
+        }
+        var r = this.rect;
+        if (deep) {
+            r.left = rect[0]; r.top = rect[1]; r.z = rect[2]; r.w = rect[3]; r.h = rect[4]; r.d = rect[5];
+        } else {
+            // w/h first, then the linked left/top setters (they read the new w/h).
+            r.w = rect[2]; r.h = rect[3]; r.left = rect[0]; r.top = rect[1];
+        }
+        if (this.universe && typeof this.universe.updateObjectProperty === 'function') {
+            this.universe.updateObjectProperty(this.handle, 'LargeObject', 'rect', rect.slice());
+        }
+        return this;
+    };
+
+    /**
+     * Change collision type at runtime (e.g. gate open/close).
+     * @param {string} ct - CollisionTypes value (SCREAMING_SNAKE)
+     */
+    LargeObject.prototype.setCollisionType = function (ct) {
+        this.collision_type = ct;
+        // Pass canonical SCREAMING_SNAKE; provider translates for target engine.
+        this.universe.setLargeObjectCollisionType(this.handle, ct);
+    };
+
+    /**
+     * Enable/disable this large object.
+     * @param {boolean} active
+     */
+    LargeObject.prototype.setActive = function (active) {
+        this.universe.setLargeObjectActive(this.handle, active);
+    };
+
+    /**
+     * Recompile this LargeObject's collision op-program from a NEW
+     * collision_type/actions pair and PUSH it to the running engine (WS Studio
+     * Controls Realignment S4, design §2.3.5 / CEO-ratified §4 call #7 —
+     * "flipping a wall into a detector mid-run is exactly the live-drive
+     * wonder"). `collision_type`/`actions` are compile-ONCE sugar inputs
+     * (actionCompiler.js lowers them to an op-program at REGISTRATION,
+     * `engineVisible:false` — see the schema field docs) — a bare
+     * `updateObjectProperty` mirror-write to either field updates ONLY this JS
+     * wrapper's display value, never the running op-program
+     * (`makeControlsForObject.js` scope note #5's "mirror-only" gap). This
+     * helper composes the SAME two primitives the constructor used at
+     * registration time — `actionCompiler.compileActions()` +
+     * `universe.updateObjectProperty(handle, 'LargeObject', 'program', …)` —
+     * so a live edit actually retargets the running behavior.
+     *
+     * `FrqtlApp.updateObjectProperty` calls this automatically when
+     * `prop` is `'collision_type'` or `'actions'` for a LargeObject/backdrop —
+     * callers do not need to call this directly under normal use.
+     *
+     * @param {Object} [opts]
+     * @param {string} [opts.collisionType] - new CollisionTypes value (SCREAMING_SNAKE).
+     *   Defaults to this.collision_type (the current USER-FACING value — never
+     *   the internal NONE the engine received when a program was compiled).
+     * @param {Array<string>} [opts.actions] - new CollisionActions[] (SCREAMING_SNAKE).
+     *   Defaults to this.actions (the currently declared actions).
+     */
+    LargeObject.prototype.recompileActions = function (opts) {
+        opts = opts || {};
+        var newCollisionType = (opts.collisionType !== undefined) ? opts.collisionType : this.collision_type;
+        var newActions = (opts.actions !== undefined) ? opts.actions : this.actions;
+
+        var compile = _compileActions;
+        var compiled = compile(newActions, this.name, this.reposition, newCollisionType);
+
+        var nativeCollisionType = newCollisionType;
+        if (compiled.program !== null) {
+            // Same G2 rule as the constructor: a compiled program takes over ALL
+            // velocity behavior, so the engine's native collision_type must be NONE.
+            nativeCollisionType = CollisionTypes.NONE;
+        }
+
+        // Mirror the USER-FACING values on the wrapper (inspector/serialize source of
+        // truth) — collision_type stays the semantic value (e.g. 'WALL'), not the
+        // internal NONE sent below (matches the constructor's own this.collision_type
+        // assignment, which happens BEFORE compilation).
+        this.collision_type = newCollisionType;
+        this.actions = newActions.slice();
+        this.program = compiled.program;
+
+        if (this.universe && typeof this.universe.updateObjectProperty === 'function') {
+            this.universe.updateObjectProperty(this.handle, 'LargeObject', 'program', compiled.program);
+        }
+    };
+
+    /**
+     * Full teardown (WS Studio Controls Realignment S4, design item 1): unregister
+     * this LargeObject engine-side, removing its compiled collision op-program
+     * (actionCompiler.js's output) and its collision registration from the
+     * RUNNING engine — not just this JS wrapper's render-list membership.
+     * A render-list splice alone would leave the engine registration; without
+     * this call the engine keeps evaluating collisions against a "deleted"
+     * object forever. Idempotent — a second call (double-delete / teardown race)
+     * is a safe no-op.
+     *
+     * ONE call leaves BOTH censuses: `unregisterLargeObject` drops the engine
+     * registration AND splices this wrapper out of the world's wrapper census (which
+     * the renderer derives its draw list from), so a disposed object cannot keep
+     * drawing a body that no longer collides. A universe with no unregister seam (a
+     * bare stub) still loses its census entry here — the wrapper is gone either way.
+     */
+    LargeObject.prototype.dispose = function () {
+        if (this._disposed) { return; }
+        this._disposed = true;
+        if (this.universe && typeof this.universe.unregisterLargeObject === 'function') {
+            this.universe.unregisterLargeObject(this.handle);
+        } else if (this.universe && Array.isArray(this.universe.largeObjects)) {
+            var i = this.universe.largeObjects.indexOf(this);
+            if (i !== -1) { this.universe.largeObjects.splice(i, 1); }
+        }
+    };
+
+    // ── Statics ─────────────────────────────────────────────────────────
+    // rectToArray is a pure shape helper (no engine knowledge).
+    // Re-exported for consumers that need to normalize rects (e.g. CircuitGate).
+    LargeObject.rectToArray = rectToArray;
+
+    // ── The kind (objects/kinds.js): descriptor, construction defaults, builder ──────────
+
+
+    registerKind(LargeObject, {
+        from: import.meta.url,
+        descriptor: SCOPE_DESCRIPTORS.LargeObject,   // the engine door's scope row (schema/scopes.js) — by reference, its ONE owner
+        defaults: {
+        collision_type: 'BOUNCE',
+        actions: [],
+        reposition: 'closest',
+        search_padding: 1,
+        color: [120, 120, 120]
+        },
+        build: function (props, ctx, Class) {
+            var LO = Class;   // the class that registered (a composed fork's own class)
+            var bw = (props.rect && props.rect.w)    || 70;
+            var bh = (props.rect && props.rect.h)    || 70;
+            var bl = (props.rect && props.rect.left  != null) ? props.rect.left : Math.round(ctx.x - bw / 2);
+            var bt = (props.rect && props.rect.top   != null) ? props.rect.top  : Math.round(ctx.y - bh / 2);
+            var ctype = props.collision_type || 'RANDOM_XY';
+            var actions = props.actions || [];
+            var loName = props.name || ('block ' + (ctx.runner.largeObjects.length + 1));
+            var reposition = props.reposition || 'closest';
+            var color = props.color || [210, 90, 90];
+            // layer → observedDimensions: pass [layer] to scope to a single dimension, null for all.
+            var loObsDims = (props.layer != null) ? [props.layer] : null;
+            // search_padding (arg #8) is a reserved/unused positional placeholder — the engine ignores
+            // it (collision search rect expands by dim.mb_w). Pass 1 to keep `color` (#9) in position.
+            var lo = new LO(ctx.runner.universe, [bl, bt, bw, bh], ctype, actions, loName,
+                            reposition, loObsDims, 1, color);
+            if (props.alpha        != null) { lo.alpha        = props.alpha; }
+            if (props.visible      != null) { lo.visible      = props.visible; }
+            if (props.drawAsCircle != null) { lo.drawAsCircle = props.drawAsCircle; }
+            lo._schemaKind = Class.name;
+            return lo;
+        }
+    });
+
+    // ── Export ───────────────────────────────────────────────────────────
+
+    export { LargeObject };
+

package/dist/frqtl/parts/LightColor.js

@@ -0,0 +1,255 @@
+/* Copyright 2023-2026 by Essam Abadir */
+
+/**
+ * LightColor — canonical single-source color mapping for all renderers.
+ *
+ * This is the ONE color source for all renderers. Both p5 and three providers call
+ * LightColor.getRgbBySchemeName(scheme, v01) — no per-renderer color map,
+ * no per-shader color spectrum, no alpha ramp duplicated in any provider.
+ *
+ * Semantics: smooth chroma.js mix across the named-color stops — ONE chroma
+ * (assets/vendor/chroma.mjs) imported in every realm, so node and the browser
+ * compute the same colour.
+ *
+ * Export contract (ALL functions are pure; no side-effects):
+ *   LightColor.getRgbColorFromFullness(v01)       -> [r, g, b]   (back-compat, calls warmcool)
+ *   LightColor.getRgbColorFromFrequency(v01)      -> [r, g, b]   (new; 7-stop ROYGBIV, no pink)
+ *   LightColor.getRgbBySchemeName(scheme, v01)    -> [r, g, b]   (dispatch; 'roygbiv'|'warmcool')
+ *   LightColor.getAlphaFromIntensity(v01)         -> number 0..1 (single alpha authority)
+ *   LightColor.getColorNameFor(fullness)          -> string
+ *   LightColor.getFullnessForColorName(name)      -> number
+ *   LightColor.fullnessColorMap                   -> { name: threshold }
+ */
+
+import chroma from '../assets/vendor/chroma.mjs';
+
+
+    // ── warmcool map (existing; back-compat) ─────────────────────────────────
+    // 9 stops red→…→violet→pink. Kept for existing experiments that use the
+    // default scheme. The pink terminus is an artifact of the original design;
+    // use 'roygbiv' for a spectrally correct ramp.
+    var fullnessColorMap = {
+        'red':    0.1,
+        'orange': 0.2,
+        'yellow': 0.3,
+        'green':  0.4,
+        'cyan':   0.5,
+        'blue':   0.6,
+        'indigo': 0.7,
+        'violet': 0.8,
+        'pink':   0.9
+    };
+
+    // ── ROYGBIV map (new; spectrally clean, NO pink) ─────────────────────────
+    // 7 stops: red→orange→yellow→green→blue→indigo→violet.
+    // v01=0 = red (lowest frequency / highest fullness = most mass-dense), v01=1 = violet.
+    // Physics: fullness = mass/capacity = frequency proxy (wavelength = capacity/mass →
+    // frequency ∝ mass/capacity). Mapping fullness→ROYGBIV therefore maps frequency to
+    // spectrum with zero engine change.
+    var roygbivStops = [
+        { threshold: 0.0,       name: 'red',    rgb: [255, 0,   0]   },
+        { threshold: 1/6,       name: 'orange', rgb: [255, 127, 0]   },
+        { threshold: 2/6,       name: 'yellow', rgb: [255, 255, 0]   },
+        { threshold: 3/6,       name: 'green',  rgb: [0,   200, 0]   },
+        { threshold: 4/6,       name: 'blue',   rgb: [0,   0,   255] },
+        { threshold: 5/6,       name: 'indigo', rgb: [75,  0,   130] },
+        { threshold: 1.0,       name: 'violet', rgb: [148, 0,   211] }
+    ];
+
+
+
+
+    // chroma-based smooth mix for the warmcool ramp.
+    function _chromaWarmcool(fullness) {
+        var colorNames = Object.keys(fullnessColorMap);
+        var targetColor = colorNames[colorNames.length - 1];
+        for (var i = 0; i < colorNames.length; i++) {
+            if (fullness <= fullnessColorMap[colorNames[i]]) {
+                targetColor = colorNames[i];
+                break;
+            }
+        }
+        if (targetColor === colorNames[0]) {
+            var r0 = chroma(targetColor).rgb();
+            return [Math.round(r0[0]), Math.round(r0[1]), Math.round(r0[2])];
+        }
+        var targetIndex = colorNames.indexOf(targetColor);
+        var previousColor = colorNames[targetIndex - 1];
+        var mixRatio = (fullness - fullnessColorMap[previousColor]) /
+                       (fullnessColorMap[targetColor] - fullnessColorMap[previousColor]);
+        var mixed = chroma.mix(previousColor, targetColor, isNaN(mixRatio) ? 0 : mixRatio);
+        var rgb = mixed.rgb();
+        return [Math.round(rgb[0]), Math.round(rgb[1]), Math.round(rgb[2])];
+    }
+
+    // chroma-based smooth mix for the ROYGBIV ramp.
+    function _chromaRoygbiv(v01) {
+        var v = Math.max(0, Math.min(1, v01));
+        var lo = roygbivStops[0], hi = roygbivStops[roygbivStops.length - 1];
+        for (var i = 0; i < roygbivStops.length - 1; i++) {
+            if (v <= roygbivStops[i + 1].threshold) {
+                lo = roygbivStops[i]; hi = roygbivStops[i + 1]; break;
+            }
+        }
+        var span = hi.threshold - lo.threshold;
+        var t    = span > 0 ? (v - lo.threshold) / span : 0;
+        var mixed = chroma.mix(chroma.rgb(lo.rgb), chroma.rgb(hi.rgb), t);
+        var rgb = mixed.rgb();
+        return [Math.round(rgb[0]), Math.round(rgb[1]), Math.round(rgb[2])];
+    }
+
+    /**
+     * getAlphaFromIntensity — single alpha authority for ALL renderers.
+     *
+     * Layer 1 (API): v01 is the intensity proxy (fullness = mass/capacity ∈ [0,1]).
+     *   Returns an alpha value in [0..1].
+     * Layer 2 (physics): fullness = frequency proxy (high fullness = high mass-density =
+     *   high frequency). Dense quanta (high fullness) appear bright; sparse quanta
+     *   (low fullness) appear dim — amplitude proportional to density.
+     *
+     * Dynamic range: `floor` (dim; near-empty quanta, default 0.35) to 1.0 (full alpha;
+     * full quanta). Previous per-provider floor was 180/255≈0.71 — too high, quanta could
+     * not read as dim. The wider default range (0.35..1.0) lets sparse quanta in the
+     * LOW×LOW lane of the collision matrix visually signal their sparsity.
+     *
+     * FRQTL-MAINT (2026-07-02, CEO render-tier-table ruling): `floor` is now an OPTIONAL
+     * second parameter (default 0.35 — every existing call site that omits it is
+     * byte-identical). This is the "extend, don't bypass" answer to the render-tier
+     * table's need for a true-invisible-below-a-mass-gate tier (e.g. air, Dim 2, mass≤2):
+     * that is NOT expressed by passing `floor:0` here (0 + v*0.65 is still nonzero for any
+     * v>0) — a genuine "invisible" tier is a SEPARATE, prior gate the CALLER applies
+     * (skip calling this function / force alpha=0 outright when the frame's mass is below
+     * the gate) BEFORE reaching for a dynamic-range floor at all. `floor` exists for tiers
+     * that want a DIFFERENT dim/bright dynamic range than the 0.35..1.0 default (e.g. a
+     * greyscale smoke tier that wants to read as dimmer overall) — it does not itself
+     * implement invisibility.
+     *
+     * @param {number} v01 - intensity value (fullness) in [0, 1]
+     * @param {number} [floor=0.35] - alpha at v01=0 (the low end of the dynamic range).
+     * @returns {number} alpha in [0, 1]
+     */
+    function getAlphaFromIntensity(v01, floor) {
+        var v = Math.max(0, Math.min(1, v01));
+        var f = (floor !== undefined && floor !== null) ? Math.max(0, Math.min(1, floor)) : 0.35;
+        // linear ramp: floor at v=0, 1.0 at v=1.
+        return f + v * (1 - f);
+    }
+
+    /**
+     * getRgbColorFromFrequency — 7-stop clean ROYGBIV ramp (NO pink terminus).
+     *
+     * Layer 1 (API): v01 is fullness (= frequency proxy). Returns [r,g,b] (0-255 ints).
+     * Layer 2 (physics): v01=0 → red (lowest frequency / sparsest), v01=1 → violet
+     *   (highest frequency / densest). Spectrally correct light-spectrum ordering.
+     *
+     * @param {number} v01 - fullness / frequency proxy in [0, 1]
+     * @returns {number[]} [r, g, b]  (0-255 ints)
+     */
+    function getRgbColorFromFrequency(v01) {
+        return _chromaRoygbiv(v01);
+    }
+
+    // ── greyscale ramp (FRQTL-MAINT 2026-07-02, CEO render-tier-table ruling) ────────
+    // §1 Dim→visual table: smoke/haze (the high-dim tiers) are "greyscale + alpha by
+    // density" — a neutral (no hue) ramp from dark (sparse) to near-white (dense), so
+    // density reads on BOTH channels (darker+more-transparent = sparse edges, brighter+
+    // more-opaque = dense core) — the standard smoke-rendering technique. 2-stop ramp
+    // (degenerate case of the same chroma mix every other scheme uses — no new
+    // interpolation code).
+    var greyscaleStops = [
+        { threshold: 0.0, name: 'greyscale-dark',  rgb: [60,  60,  60]  },
+        { threshold: 1.0, name: 'greyscale-light', rgb: [235, 235, 235] }
+    ];
+
+    function _chromaGreyscale(v01) {
+        var v = Math.max(0, Math.min(1, v01));
+        var mixed = chroma.mix(chroma.rgb(greyscaleStops[0].rgb), chroma.rgb(greyscaleStops[1].rgb), v);
+        var rgb = mixed.rgb();
+        return [Math.round(rgb[0]), Math.round(rgb[1]), Math.round(rgb[2])];
+    }
+
+    /**
+     * getRgbColorFromGreyscale — dark→light neutral ramp (density proxy, no hue).
+     *
+     * Layer 1 (API): v01 is fullness (density proxy). Returns [r,g,b] (0-255 ints).
+     * Layer 2 (physics): v01=0 → dark grey (sparse), v01=1 → near-white (dense) — the
+     *   smoke/haze tiers (§1 Dim 4/5) read density via BOTH this ramp AND alpha
+     *   (getAlphaFromIntensity), matching the standard smoke-rendering technique.
+     *
+     * @param {number} v01 - fullness / density proxy in [0, 1]
+     * @returns {number[]} [r, g, b]  (0-255 ints)
+     */
+    function getRgbColorFromGreyscale(v01) {
+        return _chromaGreyscale(v01);
+    }
+
+    /**
+     * getRgbBySchemeName — single dispatch for named color schemes.
+     *
+     * Layer 1 (API): scheme ∈ 'roygbiv' | 'warmcool' | 'greyscale'. v01 is fullness in
+     *   [0,1]. Unknown scheme → falls through to warmcool (back-compat). Returns [r,g,b]
+     *   (0-255 ints).
+     * Layer 2 (physics): 'roygbiv' maps fullness→ROYGBIV spectrum (frequency-correct);
+     *   'warmcool' maps fullness→warm-to-cool legacy ramp (existing behavior); 'greyscale'
+     *   (FRQTL-MAINT 2026-07-02) maps fullness→dark-to-light neutral ramp (the §1 smoke/
+     *   haze tiers' shading mode).
+     *
+     * Both providers call THIS instead of calling getRgbColorFromFullness directly —
+     * no per-renderer color logic.
+     *
+     * @param {string} scheme - 'roygbiv' | 'warmcool' | 'greyscale'
+     * @param {number} v01    - fullness in [0, 1]
+     * @returns {number[]} [r, g, b]  (0-255 ints)
+     */
+    function getRgbBySchemeName(scheme, v01) {
+        if (scheme === 'roygbiv')   return getRgbColorFromFrequency(v01);
+        if (scheme === 'greyscale') return getRgbColorFromGreyscale(v01);
+        return getRgbColorFromFullness(v01);  // 'warmcool' or unknown → back-compat
+    }
+
+    /**
+     * getRgbColorFromFullness — warmcool ramp (back-compat; callers prefer getRgbBySchemeName).
+     *
+     * chroma.js smooth mix (canonical semantics, every realm).
+     *
+     * @param {number} fullness - Value typically in 0..1 range
+     * @returns {number[]} [r, g, b]  (0-255 ints)
+     */
+    function getRgbColorFromFullness(fullness) {
+        return _chromaWarmcool(fullness);
+    }
+
+    /**
+     * Get the named color for a fullness value (nearest ceiling threshold).
+     * @param {number} fullness
+     * @returns {string} Color name
+     */
+    function getColorNameFor(fullness) {
+        var colorNames = Object.keys(fullnessColorMap);
+        for (var i = 0; i < colorNames.length; i++) {
+            if (fullness <= fullnessColorMap[colorNames[i]]) return colorNames[i];
+        }
+        return 'pink';
+    }
+
+    /**
+     * Get the fullness threshold for a named color.
+     * @param {string} name
+     * @returns {number}
+     */
+    function getFullnessForColorName(name) {
+        return fullnessColorMap[name] !== undefined ? fullnessColorMap[name] : 0.5;
+    }
+
+    var LightColor = {
+        fullnessColorMap:           fullnessColorMap,
+        getRgbColorFromFullness:    getRgbColorFromFullness,
+        getRgbColorFromFrequency:   getRgbColorFromFrequency,
+        getRgbColorFromGreyscale:   getRgbColorFromGreyscale,
+        getRgbBySchemeName:         getRgbBySchemeName,
+        getAlphaFromIntensity:      getAlphaFromIntensity,
+        getColorNameFor:            getColorNameFor,
+        getFullnessForColorName:    getFullnessForColorName
+    };
+
+export { LightColor };