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

package/dist/frqtl/compat/renderer/orbit-bag.js

@@ -0,0 +1,216 @@
+/* Copyright 2023-2026 by Essam Abadir */
+
+/**
+ * orbit-bag.js — THE point-shape authority for the camera pose bag.
+ *
+ * Peer of `renderCapabilities-common.js` and `captureStill-common.js`: a shared contract-half
+ * BOTH providers import, so the pose vocabulary has ONE owner instead of one per provider.
+ * (`camera2d-geometry.js` and `providers/three-camera-geometry.js` are the per-projection MATH
+ * authorities and stay exactly that — this file does no geometry, only shape.)
+ *
+ * ── Why this file exists (V4 UX, fix 3) ──────────────────────────────────────
+ *
+ * The two providers each hand-validated `target` and disagreed, in two different wrong ways:
+ * the 2D handle threw `target.x must be a finite number` on the array spelling, while the 3D
+ * handle SILENTLY RESET a malformed target to `null` and re-centred the camera. The second is
+ * a fail-loud breach on its own (RENDERER_CONTRACT §1a.2: throw-or-apply, never
+ * clamp-and-continue), and the pair is a validation schema mirror — two modules hand-listing a
+ * shape the contract owns. So the shape moves HERE and both providers ferry through it.
+ *
+ * ── The vocabulary ───────────────────────────────────────────────────────────
+ *
+ * A point-valued pose field accepts BOTH spellings, because a reader trained on p5 writes
+ * either one and both are unambiguous:
+ *
+ *   `{x, y, z}`  — the canonical OBJECT form (`z` optional ⇒ 0)
+ *   `[x, y, z]`  — the ARRAY form (`[x, y]` is accepted; `z` ⇒ 0)
+ *   `null` / `undefined` — UNSET (the camera re-centres on the scene). This is a declared
+ *                  value, not a malformed one, exactly as it is in the schema accessors.
+ *
+ * OUTPUT is always the object form — `getOrbit()` is unchanged and a captured pose still
+ * round-trips value-exact through `setOrbit`. The array is an accepted INPUT spelling only:
+ * the same "an enum accepts a key or a value" precedent, applied to points. Anything else —
+ * a string, a 4-tuple, a bag with a NaN — THROWS one identical message under EVERY provider,
+ * naming both accepted spellings. Two providers disagreeing about a shape is the drift this
+ * owner exists to make impossible.
+ *
+ * A 2D handle PROJECTS the normalized point (it stores `{x, y}` and ignores `z`) — it does not
+ * re-validate, and it does not get its own opinion about the spelling.
+ *
+ * ── Layer 1: API contract ────────────────────────────────────────────────────
+ *
+ *   POINT_FIELDS                     — the pose keys that are point-valued (`target` today).
+ *                                      A future point field joins this list and both providers
+ *                                      accept both spellings for it for free.
+ *   normalizePoint(value, fieldName) — throw-or-return `{x, y, z}` (or `null` for unset).
+ *   normalizeOrbitPatch(patch)       — a COPY of the patch with every point field normalized.
+ *                                      Non-point keys are passed through untouched (the
+ *                                      per-axis finite guards stay with the provider that
+ *                                      declares those axes).
+ *   ANGULAR_FIELDS                   — the pose keys that ROTATE the view (azimuth, elevation,
+ *                                      roll). A camera that declares none of them is flat.
+ *   hasAngularPose(cameraHandle)     — THE 3D-ness predicate: does this camera handle declare an
+ *                                      angular axis in its own `poseFields`? Every consumer that
+ *                                      must branch on "is this scene 3D?" asks this — never handle
+ *                                      presence (the 2D p5 camera is a real handle too) and never
+ *                                      a renderer sniff. `null` (no pose control at all) is flat;
+ *                                      a handle without a `poseFields` array breaks the camera
+ *                                      contract and THROWS.
+ *   makePoseNotice()                 — the POSE-CHANGE notice every camera handle publishes as
+ *                                      `addPoseListener(fn) → unsubscribe`: `{ add, notify }`.
+ *                                      A provider calls `notify(bag)` from the ONE place its pose
+ *                                      is applied, so EVERY write reaches every listener (pads,
+ *                                      camera strip, wheel, page-code `setOrbit`, a resize). A
+ *                                      dependent that re-derived the notice per write site would
+ *                                      go silently stale on the site it forgot.
+ *
+ * ── Layer 2: physics behaviour ───────────────────────────────────────────────
+ * ZERO physics. This is pose-input spelling at the output boundary: it changes which pixels
+ * you are shown, never a frame, a dimension or a tick.
+ */
+
+
+/** The pose keys whose value is a POINT. Named once so no consumer re-lists them. */
+var POINT_FIELDS = ['target'];
+
+/** The pose keys that ROTATE the view. Named once: the 2D provider's setOrbit guard and the
+ *  3D-ness predicate both read it. */
+var ANGULAR_FIELDS = ['azimuth', 'elevation', 'roll'];
+
+/**
+ * hasAngularPose(cameraHandle) — THE 3D-ness predicate, asked of the handle's own axis
+ * declaration (`poseFields[].name`), never of its presence.
+ *
+ * @param {object|null} cameraHandle — a `getCameraControl()` handle, or null (no pose control).
+ * @returns {boolean} true iff the handle declares at least one ANGULAR_FIELDS axis.
+ * @throws {Error} when a non-null handle publishes no `poseFields` array (camera contract breach).
+ */
+function hasAngularPose(cameraHandle) {
+    if (cameraHandle === null || cameraHandle === undefined) { return false; }
+    var fields = cameraHandle.poseFields;
+    if (!Array.isArray(fields)) {
+        throw new Error('camera pose: the camera handle publishes no `poseFields` array, so whether ' +
+            'it has angular axes cannot be read — every getCameraControl() handle declares its ' +
+            'axes (RENDERER_CONTRACT §1a.2). (FAIL-LOUD.)');
+    }
+    for (var i = 0; i < fields.length; i++) {
+        if (fields[i] && ANGULAR_FIELDS.indexOf(fields[i].name) !== -1) { return true; }
+    }
+    return false;
+}
+
+/** @private — the ONE message, so both providers are byte-identical on a bad input. */
+function _reject(fieldName, value) {
+    throw new Error('camera pose: `' + fieldName + '` must be a POINT — either {x, y, z} or ' +
+        '[x, y, z] (z optional, defaults to 0), with finite numbers, or null to re-centre. ' +
+        'Got ' + _describe(value) + '. Throw-or-apply: a malformed point is never silently ' +
+        'reset and never silently clamped. (FAIL-LOUD.)');
+}
+
+/** @private — a short, honest rendering of whatever arrived. */
+function _describe(v) {
+    if (Array.isArray(v)) { return 'an array of length ' + v.length + ' (' + v.join(', ') + ')'; }
+    if (v === null) { return 'null'; }
+    if (typeof v === 'object') {
+        var keys = [];
+        for (var k in v) { if (Object.prototype.hasOwnProperty.call(v, k)) { keys.push(k); } }
+        return 'an object {' + keys.join(', ') + '}';
+    }
+    return typeof v + ' ' + String(v);
+}
+
+/** @private */
+function _finiteOrNull(v) {
+    return (typeof v === 'number' && isFinite(v)) ? v : null;
+}
+
+/**
+ * normalizePoint(value, fieldName) — the ONE point-shape gate.
+ *
+ * @param {object|Array|null|undefined} value — `{x,y,z?}`, `[x,y,z?]`, or null/undefined.
+ * @param {string} fieldName — the pose key, for the message (e.g. 'target').
+ * @returns {{x:number,y:number,z:number}|null} the canonical object form, or null for unset.
+ * @throws {Error} one identical message under every provider on anything else.
+ */
+function normalizePoint(value, fieldName) {
+    if (value === null || value === undefined) { return null; }
+    var x, y, z;
+    if (Array.isArray(value)) {
+        // `[x, y]` and `[x, y, z]` only: a 1- or 4-tuple is a mistake, not a shorthand.
+        if (value.length !== 2 && value.length !== 3) { _reject(fieldName, value); }
+        x = _finiteOrNull(value[0]);
+        y = _finiteOrNull(value[1]);
+        z = (value.length === 3) ? _finiteOrNull(value[2]) : 0;
+    } else if (typeof value === 'object') {
+        x = _finiteOrNull(value.x);
+        y = _finiteOrNull(value.y);
+        z = (value.z === undefined || value.z === null) ? 0 : _finiteOrNull(value.z);
+    } else {
+        _reject(fieldName, value);
+    }
+    if (x === null || y === null || z === null) { _reject(fieldName, value); }
+    return { x: x, y: y, z: z };
+}
+
+/**
+ * normalizeOrbitPatch(patch) — normalize every point-valued field of a setOrbit patch.
+ *
+ * A patch is PARTIAL by contract (only the keys it mentions are applied), so a point field is
+ * normalized only when the patch MENTIONS it — `'target' in patch` — which is what keeps an
+ * explicit `target:null` (re-centre) distinguishable from an unmentioned target.
+ *
+ * @param {object} patch — a setOrbit spec.
+ * @returns {object} a COPY with point fields in canonical object form; non-point keys verbatim.
+ */
+function normalizeOrbitPatch(patch) {
+    if (!patch || typeof patch !== 'object') { return patch; }
+    var out = {}, k;
+    for (k in patch) {
+        if (Object.prototype.hasOwnProperty.call(patch, k)) { out[k] = patch[k]; }
+    }
+    for (var i = 0; i < POINT_FIELDS.length; i++) {
+        var f = POINT_FIELDS[i];
+        if (f in patch) { out[f] = normalizePoint(patch[f], f); }
+    }
+    return out;
+}
+
+// ── Export ────────────────────────────────────────────────────────────────────
+
+/**
+ * makePoseNotice() → `{ add(fn) → unsubscribe, notify(bag) }` — the pose-change listener list a
+ * camera handle publishes as `addPoseListener`. Listeners are provider-scoped (every handle the
+ * provider returns shares one list), so a listener registered through one handle hears a write
+ * made through another. `notify` iterates a SNAPSHOT (a listener may unsubscribe itself) and lets
+ * a listener's throw propagate to the pose writer — a dependent that cannot follow the camera
+ * fails loud at the write, never silently. A non-function listener THROWS at `add`.
+ */
+function makePoseNotice() {
+    var listeners = [];
+    return {
+        add: function (fn) {
+            if (typeof fn !== 'function') {
+                throw new TypeError('[OrbitBag] addPoseListener(fn) needs a function, got ' +
+                    String(fn) + '. (FAIL-LOUD.)');
+            }
+            if (listeners.indexOf(fn) === -1) { listeners.push(fn); }
+            return function () {
+                var i = listeners.indexOf(fn);
+                if (i !== -1) { listeners.splice(i, 1); }
+            };
+        },
+        notify: function (bag) {
+            var ls = listeners.slice();
+            for (var i = 0; i < ls.length; i++) { ls[i](bag); }
+        }
+    };
+}
+
+export {
+    makePoseNotice,
+    POINT_FIELDS,
+    ANGULAR_FIELDS,
+    normalizePoint,
+    normalizeOrbitPatch,
+    hasAngularPose
+};

package/dist/frqtl/compat/renderer/providers/godrays-layer.js

@@ -0,0 +1,213 @@
+/* Copyright 2023-2026 by Essam Abadir */
+
+/**
+ * godrays-layer.js — the three provider's god-rays layer: WHAT the rays are computed from
+ * (the source rule), the light position, and the radial march + composite passes.
+ *
+ * God-rays are a render effect computed from the density of the LIGHT particles: by default
+ * (`godraySource: 'leaf'`) the frames of the fundamental (lowest) layer. A parent frame at a higher layer is drawn in the scene
+ * but is neither a ray source nor a ray shadow; an LO is not a frame, so it is no source
+ * either (the provider keeps it as a depth-only occluder). Every god-rays site — the
+ * provider's source pass (per-bucket / cube / clone visibility) and `lightUV` here — asks
+ * `isGodraySource`; none re-states the rule.
+ *
+ * What stays in `three-provider.js`: `_renderGodraySource`, which needs the provider's live
+ * scene objects, and the orchestration in `_renderGodrays`. This file is its own because the
+ * rule is pure and because `three-provider.js` sits at the per-file ceiling
+ * `verify-publish-surface.mjs` enforces, whose instruction is to split at a natural seam.
+ *
+ * An ES module: `three-provider.js` imports it; `providers/test/godrays-layer.test.mjs` drives it in node.
+ */
+
+
+
+    /**
+     * The world's fundamental layer as TickData states it: the lowest ALLOCATED layer in
+     * `tickData.dimensionData` (ENGINE_CONTRACT: the fundamental is derived as the lowest
+     * layer that exists; the engine collects one DimensionData per allocated layer). A
+     * renderer has no universe handle, so TickData is its one read. `null` for a world with
+     * no dimension and no frame; THROWS when frames arrive with no dimension to place them.
+     * @param {object} tickData
+     * @returns {number|null}
+     */
+    function fundamentalLayerOf(tickData) {
+        var dd = tickData && tickData.dimensionData;
+        var lowest = null;
+        if (dd) {
+            for (var i = 0; i < dd.length; i++) {
+                var l = dd[i] && dd[i].layer;
+                if (typeof l === 'number' && (lowest === null || l < lowest)) { lowest = l; }
+            }
+        }
+        if (lowest === null && tickData && tickData.frameData && tickData.frameData.length) {
+            throw new Error('GodraysLayer: tickData carries ' + tickData.frameData.length + ' frames but no ' +
+                'dimensionData[].layer, so the fundamental layer the god-rays are computed from cannot be named.');
+        }
+        return lowest;
+    }
+
+    /**
+     * Is a frame at `layer` a god-rays source? Exactly the fundamental-layer frames.
+     * @param {number} layer             — FrameData.layer
+     * @param {number|null} fundamental  — fundamentalLayerOf(tickData)
+     * @returns {boolean}
+     */
+    function isGodraySource(layer, fundamental) {
+        return fundamental !== null && layer === fundamental;
+    }
+
+    /**
+     * The `godraySource` render option — the ONE owner of its values and default. A scene picks
+     * what the rays are computed from: 'leaf' (the fundamental-layer frames; LOs depth-only) or
+     * 'all' (the whole lit scene: every frame of every layer and every LO). The renderer reads
+     * it through the options bag; the engine interprets nothing.
+     */
+    var GODRAY_SOURCES = ['leaf', 'all'];
+    var GODRAY_SOURCE_DEFAULT = 'leaf';
+
+    /**
+     * The effective source for a bag value: unset → the default; anything not declared THROWS
+     * naming every legal value.
+     * @param {*} value — opts.godraySource
+     * @returns {'leaf'|'all'}
+     */
+    function resolveGodraySource(value) {
+        if (value === undefined || value === null) { return GODRAY_SOURCE_DEFAULT; }
+        if (GODRAY_SOURCES.indexOf(value) === -1) {
+            throw new Error('GodraysLayer: godraySource ' + JSON.stringify(value) + ' is not one of [' +
+                GODRAY_SOURCES.join(', ') + '] (default ' + JSON.stringify(GODRAY_SOURCE_DEFAULT) + ').');
+        }
+        return value;
+    }
+
+    /**
+     * The frames the god-rays are computed from: the fundamental layer under 'leaf' (the
+     * default), every frame under 'all'.
+     * @param {object} tickData
+     * @param {*} [source] — opts.godraySource
+     * @returns {Array<object>}
+     */
+    function godraySourceFrames(tickData, source) {
+        var fd = (tickData && tickData.frameData) || [];
+        if (resolveGodraySource(source) === 'all') { return fd.slice(); }
+        var fund = fundamentalLayerOf(tickData);
+        var out = [];
+        for (var i = 0; i < fd.length; i++) { if (isGodraySource(fd[i].layer, fund)) { out.push(fd[i]); } }
+        return out;
+    }
+
+    // R4-B god-rays — radial light-scattering march (adapted from abberg's
+    // VolumetericLightShader / GPU Gems 3). For each pixel it steps TOWARD the
+    // projected light position, accumulating SOURCE brightness with exponential
+    // decay → bright shafts where the path crosses luminous quanta, ray-shadows
+    // where an occluder hid them. Output is PURE rays (starts at 0, no base scene
+    // term) so the composite adds them once over the unblurred full scene.
+    var GODRAY_BLUR_FRAG = [
+        'uniform sampler2D uScene;',
+        'uniform vec2  uLightPos;',   // light position in [0,1] screen UV
+        'uniform float uDecay;',
+        'uniform float uDensity;',
+        'uniform float uWeight;',
+        'uniform float uExposure;',
+        'varying vec2 vTexCoord;',
+        'const int SAMPLES = 50;',
+        'void main() {',
+        '  vec2 tc = vTexCoord;',
+        '  vec2 delta = (tc - uLightPos) * (1.0 / float(SAMPLES)) * uDensity;',
+        '  vec3 rays = vec3(0.0);',
+        '  float decay = 1.0;',
+        '  for (int i = 0; i < SAMPLES; i++) {',
+        '    tc -= delta;',
+        '    vec3 s = texture2D(uScene, tc).rgb;',
+        '    rays += s * decay * uWeight;',
+        '    decay *= uDecay;',
+        '  }',
+        '  gl_FragColor = vec4(rays * uExposure, 1.0);',
+        '}'
+    ].join('\n');
+
+    // R4-B composite — unblurred scene + additive rays * intensity knob.
+    var GODRAY_COMP_FRAG = [
+        'uniform sampler2D uScene;',
+        'uniform sampler2D uRays;',
+        'uniform float uIntensity;',
+        'varying vec2 vTexCoord;',
+        'void main() {',
+        '  vec3 scene = texture2D(uScene, vTexCoord).rgb;',
+        '  vec3 rays  = texture2D(uRays,  vTexCoord).rgb;',
+        '  gl_FragColor = vec4(scene + rays * uIntensity, 1.0);',
+        '}'
+    ].join('\n');
+
+    /**
+     * The live passes, created lazily by the provider on first activation.
+     * @param {object} THREE
+     * @param {string} quadVert — the provider's full-screen-quad vertex shader
+     * @param {number} w @param {number} h — the provider's physical size
+     * @returns {{rtSource:object, setSize:Function, lightUV:Function, march:Function}}
+     */
+    function makeGodrayPasses(THREE, quadVert, w, h) {
+        var fxScene = new THREE.Scene();
+        var fxQuad  = new THREE.Mesh(new THREE.PlaneGeometry(2, 2), null);
+        fxScene.add(fxQuad);
+        var vLight = new THREE.Vector3();
+        var blurMat = new THREE.ShaderMaterial({
+            uniforms: {
+                uScene:    { value: null },
+                uLightPos: { value: new THREE.Vector2(0.5, 0.5) },
+                uDecay:    { value: 0.95 },
+                uDensity:  { value: 0.8  },
+                uWeight:   { value: 0.4  },
+                uExposure: { value: 0.35 }
+            },
+            vertexShader: quadVert, fragmentShader: GODRAY_BLUR_FRAG, depthWrite: false, depthTest: false
+        });
+        var compMat = new THREE.ShaderMaterial({
+            uniforms: { uScene: { value: null }, uRays: { value: null }, uIntensity: { value: 1.0 } },
+            vertexShader: quadVert, fragmentShader: GODRAY_COMP_FRAG, depthWrite: false, depthTest: false
+        });
+        var passes = {
+            rtSource: new THREE.WebGLRenderTarget(w, h),   // the SOURCE image the provider renders into
+            setSize: function (sw, sh) { passes.rtSource.setSize(sw, sh); },
+            // Light position in [0,1] screen UV: the fullness-weighted centroid of the SOURCE
+            // frames, projected through `camera` (2D ortho + 3D persp); screen centre when none.
+            lightUV: function (tickData, camera, source) {
+                var fd = godraySourceFrames(tickData, source);
+                var sx = 0, sy = 0, sz = 0, sw = 0;
+                for (var i = 0; i < fd.length; i++) {
+                    var f = fd[i];
+                    var wt = (f.fullness || 0) + 0.05;   // floor so empty-fullness still weighs
+                    sx += f.rect.x * wt; sy += f.rect.y * wt; sz += (f.z || 0) * wt; sw += wt;
+                }
+                if (sw <= 0) { return new THREE.Vector2(0.5, 0.5); }
+                vLight.set(sx / sw, sy / sw, sz / sw).project(camera);   // → NDC [-1,1]
+                return new THREE.Vector2(vLight.x * 0.5 + 0.5, vLight.y * 0.5 + 0.5);
+            },
+            // Pass 2: march sourceRT → rtRays. Pass 3: sceneRT + rays × intensity → screen.
+            march: function (renderer, quadCamera, sceneRT, sourceRT, rtRays, lightUV, density, intensity) {
+                blurMat.uniforms.uScene.value = sourceRT.texture;
+                blurMat.uniforms.uLightPos.value.copy(lightUV);
+                if (typeof density === 'number') { blurMat.uniforms.uDensity.value = density; }
+                fxQuad.material = blurMat;
+                renderer.setRenderTarget(rtRays);
+                renderer.render(fxScene, quadCamera);
+                compMat.uniforms.uScene.value = sceneRT.texture;
+                compMat.uniforms.uRays.value  = rtRays.texture;
+                compMat.uniforms.uIntensity.value = intensity;
+                fxQuad.material = compMat;
+                renderer.setRenderTarget(null);
+                renderer.render(fxScene, quadCamera);
+            }
+        };
+        return passes;
+    }
+
+export {
+    fundamentalLayerOf,
+    isGodraySource,
+    godraySourceFrames,
+    GODRAY_SOURCES,
+    GODRAY_SOURCE_DEFAULT,
+    resolveGodraySource,
+    makeGodrayPasses
+};

package/dist/frqtl/compat/renderer/providers/index.js

@@ -0,0 +1,22 @@
+/* Copyright 2023-2026 by Essam Abadir */
+
+/**
+ * providers/index.js — THE renderer registry: every built-in RendererProvider by its boot name.
+ *
+ *   RENDERER_PROVIDERS[name] = { makeProvider(cfg) → provider, renderCapabilities() → descriptors }
+ *
+ * The boot module selects a provider by name from this table (`?renderer=` / `bootRealm({ renderer })`);
+ * `RenderCapabilitiesCommon.knownRenderCapabilityNames(RENDERER_PROVIDERS)` is the "known" set saved
+ * render rows are partitioned against. A BYO renderer is handed to the boot module as an instance; it
+ * never joins this table.
+ *
+ * Zero physics: a provider reads TickData and draws.
+ */
+
+import { makeP5Provider, _renderCapabilitiesP5 } from './p5-provider.js';
+import { makeThreeProvider, _renderCapabilitiesThree } from './three-provider.js';
+
+export const RENDERER_PROVIDERS = Object.freeze({
+    p5: Object.freeze({ makeProvider: makeP5Provider, renderCapabilities: _renderCapabilitiesP5 }),
+    three: Object.freeze({ makeProvider: makeThreeProvider, renderCapabilities: _renderCapabilitiesThree })
+});