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

package/dist/frqtl/compat/renderer/RenderMesh.js

@@ -0,0 +1,99 @@
+/* Copyright 2023-2026 by Essam Abadir */
+
+/**
+ * RenderMesh — the ONE resolver for the `render.mesh` external-geometry intent.
+ *
+ * `render.mesh` is an OPEN-ID render-intent key (owned by lib/shim/frame-data
+ * RENDER_INTENT_KEYS; deliberately NO RENDER_INTENT_VALUES entry = accept-any-string).
+ * Its value is an external-geometry ASSET ID — e.g. an Objaverse glTF id or a served
+ * .glb/.gltf URL. It routes a frame/LO to a loaded mesh instead of a sprite/cube.
+ *
+ * Mirrors RenderShape: this file is the DECODE/RESOLVE authority (which asset id applies
+ * to a frame, via the priority chain). It does NOT load anything — asset loading + caching
+ * + FAIL-LOUD-on-failure live in the renderer provider (three GLTFLoader path). Keeping the
+ * resolver pure (no three import) means it runs in pkg-node/conformance unchanged.
+ *
+ * CANONICAL-STACK NOTE: WHICH mesh a frame maps to is a
+ * renderer/sugar/user-space CHOICE derived from FrameData (a frame's layer/mass/fullness,
+ * or an explicit per-frame `render.mesh` string_map key written by sugar). The engine emits
+ * primitives and carries `render.mesh` OPAQUE (I1) — it never interprets it.
+ *
+ * Priority chain (same shape as RenderShape.resolve):
+ *   1. render.mesh key in a FRAME's string_map (per-quantum override; highest priority)
+ *   2. `.mesh` field on a LARGE OBJECT (renderer-only LO field, parallel to lo.sprite /
+ *      lo.renderHint — an LO carries render intent directly; it has no string_map bubble)
+ *   3. mesh in experiment render options (setRenderOption('mesh', id) default)
+ *   4. none (null) — object falls back to its sprite/cube/box/ball path
+ *
+ * Export contract (pure; no side effects, no three dependency):
+ *   RenderMesh.resolve(frame, renderOpts) -> string | null   (asset id, or null = no mesh)
+ *   RenderMesh.hasMesh(frame, renderOpts) -> boolean
+ *   RenderMesh.KEY                        -> 'render.mesh'    (the frame-data-owned key name)
+ */
+
+import * as FrameDataSchema from '../../../shim/frame-data/index.js';
+
+
+    // The open-id render-intent key this resolver decodes. Asserted against the canonical
+    // owner (lib/shim/frame-data RENDER_INTENT_KEYS) so a contract drop FAILS LOUD rather
+    // than silently resolving nothing — same fail-loud discipline as RenderShape's ferry.
+    var KEY = 'render.mesh';
+
+
+    var _schema = FrameDataSchema;
+    if (_schema.RENDER_INTENT_KEYS.indexOf(KEY) === -1) {
+        throw new Error(
+            'RenderMesh: "' + KEY + '" is not a declared render-intent key in lib/shim/frame-data ' +
+            'RENDER_INTENT_KEYS — the open-id key set must be owned there.'
+        );
+    }
+    // render.mesh is OPEN-ID: it must have NO RENDER_INTENT_VALUES entry (accept-any-string).
+    if (_schema.RENDER_INTENT_VALUES[KEY] !== undefined) {
+        throw new Error(
+            'RenderMesh: "' + KEY + '" must be OPEN-ID (no RENDER_INTENT_VALUES entry) — an asset id ' +
+            'is a free string validated at load time by the renderer, not an enum.'
+        );
+    }
+
+    /**
+     * Resolve the external-mesh asset id for one renderable object, from the priority chain.
+     *
+     * @param {object} obj         - a FRAME (obj.data.string_map may carry 'render.mesh') OR a
+     *                               LARGE OBJECT (obj.mesh may carry the asset id directly).
+     * @param {object} renderOpts  - FrqtlApp._renderOptions (the setRenderOption bag).
+     * @returns {string|null} the asset id, or null when no mesh is routed (sprite/cube/box path applies).
+     */
+    function resolve(obj, renderOpts) {
+        var sm = obj && obj.data && obj.data.string_map;
+        if (sm && typeof sm[KEY] === 'string' && sm[KEY].length > 0) {
+            return sm[KEY];
+        }
+        // Per-LO renderer-only field. LOs have no frame-data bubble; they carry render intent
+        // directly on the object (like lo.sprite / lo.renderHint). This keeps RenderMesh the
+        // SINGLE resolver authority for the render.mesh intent across frames AND large objects.
+        if (obj && typeof obj.mesh === 'string' && obj.mesh.length > 0) {
+            return obj.mesh;
+        }
+        if (renderOpts && typeof renderOpts.mesh === 'string' && renderOpts.mesh.length > 0) {
+            return renderOpts.mesh;
+        }
+        return null;
+    }
+
+    /**
+     * True when a frame routes to an external mesh (resolve returns a non-null asset id).
+     * @param {object} frame
+     * @param {object} renderOpts
+     * @returns {boolean}
+     */
+    function hasMesh(frame, renderOpts) {
+        return resolve(frame, renderOpts) !== null;
+    }
+
+    var RenderMesh = {
+        KEY:     KEY,
+        resolve: resolve,
+        hasMesh: hasMesh
+    };
+
+export { RenderMesh };

package/dist/frqtl/compat/renderer/RenderShape.js

@@ -0,0 +1,154 @@
+/* Copyright 2023-2026 by Essam Abadir */
+
+/**
+ * RenderShape — the ONE shape authority for all renderers.
+ *
+ * Resolves the per-frame render shape from the priority chain:
+ *   1. render.shape key in frame's string_map (per-frame override; highest priority)
+ *   2. shape in experiment render options (setRenderOption default; set by the experiment)
+ *   3. Renderer's own fallback (always 'ball')
+ *
+ * This is consumed by BOTH p5 and three providers — no per-provider shape logic.
+ *
+ * Why a single file: a render-color audit found that shape was
+ * driven by a construction-time global in three-provider
+ * and was absent entirely in p5-provider. That creates a provider divergence where
+ * the same experiment renders differently on each provider. RenderShape.js closes
+ * this by being the unique decoder both providers call.
+ *
+ * VALID SHAPES:
+ *   'ball'   — round glowing point sprite (default; unchanged behavior for all existing
+ *              experiments). In three: Gaussian glow in the fragment shader; in p5: ellipse.
+ *   'box'    — filled square at the voxel size (1 Dim-0 = 1 screen px). In three: the
+ *              existing Chebyshev-fill box shader branch (uShape=1); in p5: rect.
+ *   'circle' — outline circle (no fill). In three: same as ball but outline-only via
+ *              discard inside radius; in p5: noFill+stroke ellipse.
+ *   'cube'   — TRUE shaded 3D cube mesh (three.js InstancedMesh; 3D mode only). In three
+ *              (when _is3D): an InstancedMesh of BoxGeometry with per-face brightness
+ *              shading (front/top brighter than sides/back) so cube faces are visually
+ *              distinct. In 2D or p5: silently falls back to 'box' (graceful degradation —
+ *              the engine/physics are untouched; only the render path changes). The cube
+ *              render path completely BYPASSES the Points mesh and GLSL shader; it uses a
+ *              real THREE.Mesh so depth-sorting and face normals work correctly.
+ *   'sphere' — TRUE 3D instanced-sphere mesh (three.js InstancedMesh; 3D mode only) —
+ *              SYMMETRIC with 'cube' (gated on isSphereMesh, exactly like isCubeMesh). In
+ *              three (when _is3D): a per-instance-colored SphereGeometry InstancedMesh (the
+ *              R6 "2D coloring extended to 3D" baseline) that applies render.color per
+ *              instance, so render.shape and render.color stay INDEPENDENT (a forced-red
+ *              sphere is a red sphere, not a point). In 2D or p5: degrades to the filled
+ *              'ball' disc — toUniform('sphere')=0 (ball glow) on the three Points path, and
+ *              p5's default (else) branch draws it as the ball ellipse. No per-provider map:
+ *              this file is the one authority; the fold-in retired the old shapeMesh3D flag.
+ *
+ * Export contract:
+ *   RenderShape.resolve(frame, renderOpts) -> 'ball' | 'box' | 'circle' | 'cube' | 'sphere'
+ *   RenderShape.toUniform(shape)           -> number (three uShape value; cube/sphere→0 = ball
+ *                                             because cube/sphere bypass the point-sprite shader)
+ *   RenderShape.isCubeMesh(shape)          -> boolean (true for 'cube' — instanced-mesh gate)
+ *   RenderShape.isSphereMesh(shape)        -> boolean (true for 'sphere' — instanced-mesh gate)
+ *   RenderShape.VALID_SHAPES               -> string[] (FERRIED from lib/shim/frame-data
+ *                                             RENDER_INTENT_VALUES['render.shape'] — NOT a source here)
+ *
+ * Single-source: the shape VALUE set is owned by lib/shim/frame-data (the foundational
+ * cross-engine render-intent contract). RenderShape is the DECODE authority (resolve/
+ * isCubeMesh/toUniform) but re-exports the value list rather than re-listing it, so adding
+ * a shape is one edit at frame-data.
+ */
+
+import * as FrameDataSchema from '../../../shim/frame-data/index.js';
+
+
+
+    var _schema = FrameDataSchema;
+    var VALID_SHAPES = _schema.RENDER_INTENT_VALUES['render.shape'];
+    if (!Array.isArray(VALID_SHAPES) || VALID_SHAPES.length === 0) {
+        throw new Error(
+            'RenderShape: frame-data RENDER_INTENT_VALUES["render.shape"] is missing or empty — ' +
+            'the shape value set must be owned by lib/shim/frame-data.'
+        );
+    }
+
+    /**
+     * Resolve the shape for one frame, from the priority chain.
+     *
+     * @param {object} frame       - FrameData object; frame.data.string_map may carry 'render.shape'.
+     * @param {object} renderOpts  - FrqtlApp._renderOptions (the setRenderOption bag).
+     * @returns {string} a member of VALID_SHAPES (ferried from frame-data's
+     *   RENDER_INTENT_VALUES['render.shape']: 'ball'|'box'|'circle'|'cube'|'sphere').
+     */
+    function resolve(frame, renderOpts) {
+        // 1. Per-frame override via string_map (highest priority).
+        var sm = frame && frame.data && frame.data.string_map;
+        if (sm && sm['render.shape'] && VALID_SHAPES.indexOf(sm['render.shape']) !== -1) {
+            return sm['render.shape'];
+        }
+        // 2. Experiment default via setRenderOption('shape', ...).
+        var optShape = renderOpts && renderOpts.shape;
+        if (optShape && VALID_SHAPES.indexOf(optShape) !== -1) {
+            return optShape;
+        }
+        // 3. Renderer default.
+        return 'ball';
+    }
+
+    /**
+     * Convert a resolved shape name to the three.js uShape uniform value.
+     *
+     * uShape is a float consumed by the QUANTA_FRAG shader (the Points mesh path):
+     *   0.0 = ball (round Gaussian glow — default)
+     *   1.0 = box  (Chebyshev-fill solid square)
+     *
+     * 'circle' renders via the ball glow path in three (a full separate branch
+     * is a future enhancement — for now circle ≡ ball in three, and is
+     * distinct only in p5 where the stroke/noFill path is available without
+     * any shader change).
+     *
+     * 'cube' in 3D mode BYPASSES the Points mesh and GLSL shader entirely — the
+     * three-provider switches to an InstancedMesh of BoxGeometry instead. This
+     * function returns 0.0 for 'cube' as a safe sentinel; the caller must gate
+     * on RenderShape.isCubeMesh(shape) to know whether to use the instanced-mesh
+     * path vs the Points path. 'sphere' is the same: an instanced mesh in 3D
+     * (gate: isSphereMesh), 0.0 here.
+     *
+     * @param {string} shape - a member of VALID_SHAPES: 'ball' | 'box' | 'circle' | 'cube' | 'sphere'
+     * @returns {number}     - 0.0 (ball/circle/cube/sphere) or 1.0 (box)
+     */
+    function toUniform(shape) {
+        return (shape === 'box') ? 1.0 : 0.0;
+    }
+
+    /**
+     * True when shape should be rendered as a 3D InstancedMesh cube (not a point sprite).
+     * The three-provider gates on this to switch between the Points path and the instanced-mesh path.
+     * In 2D or p5, 'cube' falls back to 'box' in resolve() before isCubeMesh is called.
+     *
+     * @param {string} shape - resolved shape name
+     * @returns {boolean}
+     */
+    function isCubeMesh(shape) {
+        return shape === 'cube';
+    }
+
+    /**
+     * True when shape should be rendered as a 3D InstancedMesh sphere (not a point sprite) —
+     * exactly parallel to isCubeMesh. The three-provider gates its sphere InstancedMesh path
+     * on `_is3D && isSphereMesh(resolvedShape)`, symmetric with the cube gate. In 2D or p5,
+     * 'sphere' degrades to the filled 'ball' disc (toUniform('sphere')=0 / p5's ball branch)
+     * before this matters.
+     *
+     * @param {string} shape - resolved shape name
+     * @returns {boolean}
+     */
+    function isSphereMesh(shape) {
+        return shape === 'sphere';
+    }
+
+    var RenderShape = {
+        VALID_SHAPES: VALID_SHAPES,
+        resolve:      resolve,
+        toUniform:    toUniform,
+        isCubeMesh:   isCubeMesh,
+        isSphereMesh: isSphereMesh
+    };
+
+export { RenderShape };

package/dist/frqtl/compat/renderer/camera2d-geometry.js

@@ -0,0 +1,183 @@
+/* Copyright 2023-2026 by Essam Abadir */
+
+/**
+ * camera2d-geometry.js — THE 2D camera map: the `affine2d` projection's one authority.
+ *
+ * Peer of `providers/three-camera-geometry.js` (the pinhole authority) and, like it, PURE and
+ * backend-free so it is unit-testable in plain Node with no canvas. It lives at
+ * `compat/renderer/` rather than under `providers/` because it is NOT p5-specific: it is the
+ * math of the `projection:{kind:'affine2d'}` mode, and three's own 2D orthographic mode
+ * reports that same kind. Naming it after one provider would be a lie the day the other uses it.
+ *
+ * ── Why 2D pan/zoom is a CAMERA concern, not a render option ─────────────────
+ *
+ * Three reasons, each decisive alone (ratified 2026-07-30):
+ *
+ * 1. **One write path / honest provenance.** Every still stamps `pose` from `cameraControl`.
+ *    If 2D pan/zoom lived on the render surface (a `setRenderOption`, a view rect), a ZOOMED
+ *    2D still's `pose` would read `null` — a mislabeled training record, which is the corpus
+ *    corruption channel reopened by the very feature meant to serve VLA.
+ * 2. **One mapping authority.** `screenToWorld` in 2D must change under pan/zoom. If the
+ *    pan/zoom state lived anywhere but the camera authority, two authorities would feed one
+ *    mapping — the split-basis failure the 3D camera consolidation just eliminated.
+ * 3. **One vocabulary.** "Look at point P at magnification Z" is the same sentence in 2D and
+ *    3D. In 3D it is already `target` + `distance`. Minting a parallel 2D vocabulary
+ *    (`viewRect`, `panX`/`panY`/`zoom`) would fork the pose bag AND fork `CameraPath`.
+ *
+ * ── The degenerate orbit bag ─────────────────────────────────────────────────
+ *
+ * The 2D pose IS the orbit bag with the angular triple absent — NOT a new bag type:
+ *
+ *   `target: {x, y}` — the physics-px point at the VIEW CENTRE; `null` = the canvas centre.
+ *                      **Pan IS target, in both modes — the same key.**
+ *   `distance`       — the VISIBLE PHYSICS-PX HEIGHT of the view; smaller = zoomed IN.
+ *
+ * `distance` is not a pun. In 3D at a fixed vertical FOV the visible height at the target
+ * plane is `2·distance·tan(fovY/2)`, so `distance` ALREADY means "how much world you see" in
+ * both modes — one observable, two projections. There is deliberately no `zoom` field: a
+ * second magnification vocabulary would fork the bag. "Zoom into that region" is
+ * `setOrbit({ target: regionCentre, distance: regionHeight })`.
+ *
+ * A consumer NEVER asks "is this 2D?". It asks which pose fields exist: the handle's
+ * `poseFields` declares exactly the axes it has, so a host hides the angular affordances and
+ * shows the rest by FIELD PRESENCE — the same capability idiom as `roll` and `move()`.
+ *
+ * ── Layer 1: API contract ────────────────────────────────────────────────────
+ *
+ *   POSE_FIELDS_2D(w, h)          — the declared pose axes (distance, target). No azimuth /
+ *                                   elevation / roll: this camera does not have them.
+ *   PRESETS_2D(w, h)              — the named framings, declared beside the axes.
+ *   defaultPose2d(w, h)           — `{distance: h, target: null}` = the whole canvas, 1:1.
+ *   resolveView2d(pose, w, h)     — `{k, cx, cy}`: scale factor and the physics-px point at
+ *                                   the view centre. THE one place the transform is derived.
+ *   screenToWorld2d(pose, w, h, sx, sy, sw, sh) — a point in canvas/buffer space → physics px.
+ *
+ * At the default pose `k === 1` and the map is the IDENTITY — so every existing 2D caller,
+ * drag, pick and capture is byte-unchanged until someone actually pans or zooms.
+ *
+ * ── Layer 2: physics behaviour ───────────────────────────────────────────────
+ * ZERO physics. A view transform at the output boundary: it changes which pixels you are
+ * shown, never a frame, a dimension or a tick. Zooming does not alter the simulation, which
+ * is exactly why it is safe as an observation instrument.
+ */
+
+import * as FieldDescriptorSchema from '../../../shim/field-descriptor/index.js';
+
+
+
+function _fail(msg) {
+    throw new Error('[camera2d-geometry] ' + msg + ' (FAIL-LOUD.)');
+}
+
+
+/**
+ * The DECLARED pose axes of a 2D camera — normalized field descriptors, the same shape the
+ * 3D camera publishes. A host renders whatever THIS camera declares; the absence of
+ * `azimuth`/`elevation`/`roll` is what hides the angular affordances, with no mode sniffing
+ * anywhere.
+ * @param {number} width @param {number} height — physics canvas dims
+ * @returns {Array<object>}
+ */
+function POSE_FIELDS_2D(width, height) {
+    var nfd = FieldDescriptorSchema.normalizeFieldDescriptor;
+    return [
+        nfd({
+            name: 'distance', label: 'zoom', type: 'number', unit: 'px', default: height,
+            // Down to 8 px of visible height is a deep zoom (native pixel scale and beyond);
+            // up to 4x the canvas frames any scene with margin.
+            constraint: { min: 8, max: Math.max(height * 4, 32), integer: false },
+            widgetConfig: { step: Math.max(1, Math.round(height / 60)) },
+            description: 'The VISIBLE HEIGHT of the view in physics pixels — smaller = zoomed IN. ' +
+                'Default = the full canvas height (1:1). The same observable as the 3D camera\'s ' +
+                'distance: "how much world you see".'
+        }),
+        nfd({
+            name: 'target', label: 'centre', type: 'object', unit: 'px', default: null,
+            description: 'The physics-px point {x,y} at the view centre; null = the canvas centre. ' +
+                'Pan IS target — the same key the 3D camera uses.'
+        })
+    ];
+}
+
+/**
+ * PRESETS_2D — the named framings this camera offers, DECLARED beside its axes.
+ *
+ * Lives here rather than inline in the provider for the same reason `POSE_FIELDS_2D` does:
+ * the 3D camera keeps its preset TABLE and its pose descriptors together in
+ * `three-camera-contract.js`, and splitting the 2D pair across two files would leave the
+ * provider holding declarative data. A 2D camera has exactly one framing — the whole canvas.
+ *
+ * @param {number} width @param {number} height — physics canvas dims
+ * @returns {Object<string,object>} preset name → the orbit-bag patch it applies
+ */
+function PRESETS_2D(width, height) {
+    return { fit: { target: null, distance: height } };
+}
+
+/** `{distance: height, target: null}` — the whole canvas at 1:1. @returns {object} */
+function defaultPose2d(width, height) {
+    return { distance: height, target: null };
+}
+
+/**
+ * resolveView2d(pose, width, height) → `{k, cx, cy}` — THE derivation of the 2D view.
+ *
+ *   k       — scale factor = `height / distance`. `k > 1` is zoomed in.
+ *   cx, cy  — the physics-px point held at the view centre (`target`, or the canvas centre).
+ *
+ * Every consumer (the provider's draw transform, `screenToWorld`, the offline
+ * `unprojectStill`) derives from THIS, so the picture and the mapping can never disagree.
+ *
+ * @param {object|null} pose — a (possibly partial) orbit bag
+ * @param {number} width @param {number} height — physics canvas dims
+ * @returns {{k:number, cx:number, cy:number}}
+ */
+function resolveView2d(pose, width, height) {
+    if (!(width > 0 && height > 0)) { _fail('physics dims must be positive, got ' + width + 'x' + height); }
+    var d = (pose && typeof pose.distance === 'number' && isFinite(pose.distance) && pose.distance > 0)
+        ? pose.distance : height;
+    var t = (pose && pose.target && typeof pose.target.x === 'number' && typeof pose.target.y === 'number')
+        ? pose.target : null;
+    return {
+        k:  height / d,
+        cx: t ? t.x : width / 2,
+        cy: t ? t.y : height / 2
+    };
+}
+
+/**
+ * screenToWorld2d — a point in CANVAS space → physics px, under the current 2D pose.
+ *
+ * `srcX/srcY` are in the coordinate space whose extent is `srcW/srcH`. That is deliberately
+ * general: the live provider passes CSS pixels and the canvas's CSS size, while the OFFLINE
+ * `unprojectStill` passes BUFFER pixels and the still's buffer dims. Same map, one
+ * implementation — which is what stops an offline measurement from drifting from the live
+ * drag/pick.
+ *
+ * @param {object|null} pose @param {number} width @param {number} height — physics dims
+ * @param {number} srcX @param {number} srcY @param {number} srcW @param {number} srcH
+ * @returns {{x:number, y:number}}
+ */
+function screenToWorld2d(pose, width, height, srcX, srcY, srcW, srcH) {
+    var sw = (srcW > 0) ? srcW : width;
+    var sh = (srcH > 0) ? srcH : height;
+    var v = resolveView2d(pose, width, height);
+    // 1. source space → canvas-draw space (physics px on an unzoomed canvas)
+    var dx = srcX * (width / sw);
+    var dy = srcY * (height / sh);
+    // 2. invert the draw transform: translate(w/2,h/2) · scale(k) · translate(-cx,-cy)
+    return {
+        x: (dx - width / 2) / v.k + v.cx,
+        y: (dy - height / 2) / v.k + v.cy
+    };
+}
+
+// ── Export ────────────────────────────────────────────────────────────────────
+
+export {
+    POSE_FIELDS_2D,
+    PRESETS_2D,
+    defaultPose2d,
+    resolveView2d,
+    screenToWorld2d
+};