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

package/dist/frqtl/compat/providers/wasm-load-browser.js

@@ -0,0 +1,134 @@
+/* Copyright 2023-2026 by Essam Abadir */
+
+/**
+ * wasm-load-browser.js — the BROWSER loader for the WASM engine (an ES module).
+ *
+ * Imports the wasm-pack --target web glue located BESIDE this tree —
+ * `new URL('../../../fat/pkg-web/egpt_wasm.js', import.meta.url)` — and returns the resolved
+ * WasmUniverse constructor so wasm-engine.js stays env-agnostic. The boot door hands this
+ * loader to `bootEngine` (compat/engine.js); nothing here publishes a global or a ready promise.
+ *
+ * A host serves the engine at its lib/-relative placement (frqtl/compat/… beside fat/pkg-web/…),
+ * so the glue's location is a fact of this file's own URL — there is no override global and no
+ * probe list (a probe list is a silent search). `load(glueUrl)` takes an explicit URL only for a
+ * test that must cache-bust the glue.
+ *
+ * Artifact-safe init (ws-artifact-showcase Bite A5):
+ *   We NEVER call the wasm-pack glue's `default()`/`__wbg_init()` bare (no
+ *   args) — bare, it builds its own `new URL('egpt_wasm_bg.wasm', import.meta.url)`
+ *   and does `fetch(urlObject)` internally, which throws `DataCloneError`
+ *   inside a claude.ai Artifact iframe (its `window.fetch` is proxied to the
+ *   parent via `postMessage`, and a URL object is not structured-clonable).
+ *   Instead we self-fetch the .wasm bytes with a plain STRING url (strings
+ *   clone fine) and hand the glue raw bytes — see the inline comment at the
+ *   `wasmModule.default(...)` call site for the full trace. Regression test:
+ *   wasm-load-browser.test.mjs.
+ *
+ * Package content identity:
+ *   The self-fetched bytes ARE the executing binary, so this is where its identity is
+ *   taken: `loadedWasmSha256()` is the sha256 hex of the `.wasm` instantiated — the same
+ *   definition `published/<id>/PINNED.json` records as `engine.wasmSha256`. The capture
+ *   instrument pins it as `build.wasmSha256`; the serving URL is never identity (the same
+ *   bytes from two origins regenerate one scene). Gate: scene-identity-origin.test.mjs.
+ */
+
+/** The glue's URL: a fact of this module's own placement. */
+export const GLUE_URL = new URL('../../../fat/pkg-web/egpt_wasm.js', import.meta.url).href;
+
+/** sha256 hex of the last binary this loader instantiated; null before any load. */
+let _loadedWasmSha256 = null;
+
+/**
+ * sha256 hex of `bytes` via `crypto.subtle`, or null where the page has none (a
+ * non-secure origin). Null there cannot mint a false identity: `RenderStages.sceneHash`
+ * refuses to hash without the same `crypto.subtle`, so no scene id exists in that page.
+ */
+async function _sha256Hex(bytes) {
+    const subtle = (typeof crypto !== 'undefined') ? crypto.subtle : null;
+    if (!subtle || typeof subtle.digest !== 'function') { return null; }
+    const view = new Uint8Array(await subtle.digest('SHA-256', bytes));
+    let hex = '';
+    for (let i = 0; i < view.length; i++) {
+        hex += (view[i] < 16 ? '0' : '') + view[i].toString(16);
+    }
+    return hex;
+}
+
+/** @returns {string|null} sha256 hex of the instantiated `.wasm`, or null. */
+export function loadedWasmSha256() {
+    return _loadedWasmSha256;
+}
+
+/**
+ * Load the WASM web bundle and return the WasmUniverse constructor.
+ *
+ * @param {string} [glueUrl] - the glue URL (default GLUE_URL); a test passes a cache-busted one.
+ * @returns {Promise<{WasmUniverse: Function}>}
+ */
+export async function load(glueUrl) {
+    const pkgUrl = glueUrl || GLUE_URL;
+    let wasmModule;
+    try {
+        wasmModule = await import(pkgUrl);
+    } catch (e) {
+        throw new Error(
+            '[wasm-load-browser] the WASM package glue did not load from ' + pkgUrl + ' (' +
+            (e && e.message ? e.message : String(e)) + ').\n' +
+            'Build it with:\n' +
+            '  wasm-pack build fat/crates/egpt_wasm --target web --out-dir fat/pkg-web'
+        );
+    }
+
+    // wasm-pack --target web generates an init() default export that,
+    // called bare, builds its OWN `new URL('egpt_wasm_bg.wasm', import.meta.url)`
+    // and does `fetch(thatUrlObject)` internally (verified against
+    // fat/pkg-web/egpt_wasm.js's own __wbg_init/__wbg_load source).
+    //
+    // ARTIFACT-SAFE INIT (ws-artifact-showcase Bite A5): a claude.ai
+    // Artifact runs inside a sandboxed iframe whose `window.fetch` is not
+    // a direct network fetch — it is PROXIED to the parent frame via
+    // `postMessage`, and every postMessage argument must be structured-
+    // clonable (the HTML Structured Clone Algorithm). A `URL` object is
+    // NOT clonable (confirmed identical via the platform's own global
+    // `structuredClone()` — throws `DataCloneError`), so the glue's bare
+    // `fetch(urlObject)` call throws inside an Artifact — this is the
+    // EXACT defect from the real claude.ai paste (`DataCloneError:
+    // Failed to execute 'postMessage' on 'Window': URL object could not
+    // be cloned` at `window.fetch (about:srcdoc:109)` <- `Module.__wbg_init`
+    // <- `load` <- the ESM entry's boot (lib/frqtl/experiments/_shared/doors.js)).
+    //
+    // Fix: we fetch the .wasm bytes OURSELVES with a plain STRING url
+    // (strings clone fine everywhere, including through a postMessage
+    // proxy) and hand the glue raw bytes instead. wasm-bindgen's
+    // `__wbg_init()` takes a BufferSource straight to
+    // `WebAssembly.instantiate(bytes, imports)` — it never touches
+    // `fetch()` again once it has bytes in hand. We pass the bytes via
+    // the glue's non-deprecated `{module_or_path: bytes}` calling
+    // convention (a bare positional BufferSource also works, but trips
+    // the glue's own "using deprecated parameters" console.warn).
+    let wasmSha256 = null;   // no self-fetched bytes (no init export) ⇒ honestly unknown
+    if (typeof wasmModule.default === 'function') {
+        const wasmBgUrl = new URL('egpt_wasm_bg.wasm', pkgUrl).href;
+        const wasmResponse = await fetch(String(wasmBgUrl));
+        if (!wasmResponse.ok) {
+            throw new Error(
+                '[wasm-load-browser] failed to fetch WASM binary: ' +
+                wasmResponse.status + ' ' + wasmResponse.statusText + ' (' + wasmBgUrl + ')'
+            );
+        }
+        const wasmBytes = await wasmResponse.arrayBuffer();
+        wasmSha256 = await _sha256Hex(wasmBytes);
+        await wasmModule.default({ module_or_path: wasmBytes });
+    }
+
+    const WasmUniverse = wasmModule.WasmUniverse;
+    if (!WasmUniverse) {
+        throw new Error('[wasm-load-browser] WasmUniverse not found in loaded WASM module.');
+    }
+    _loadedWasmSha256 = wasmSha256;
+
+    return { WasmUniverse: WasmUniverse };
+}
+
+/** The loader the browser door hands to bootEngine. */
+export const browserWasmLoader = Object.freeze({ env: 'browser', load: function () { return load(); } });

package/dist/frqtl/compat/providers/wasm-load-node.js

@@ -0,0 +1,59 @@
+/* Copyright 2023-2026 by Essam Abadir */
+
+/**
+ * wasm-load-node.js — the NODE loader for the WASM engine (an ES module).
+ *
+ * Resolves the wasm-pack --target nodejs artifact beside this tree
+ * (`new URL('../../../fat/pkg-node/egpt_wasm.js', import.meta.url)`) and returns the
+ * WasmUniverse constructor so wasm-engine.js stays env-agnostic. The node door hands this
+ * loader to `bootEngine` (compat/engine.js).
+ *
+ * The nodejs pkg is CommonJS and SYNCHRONOUS: it reads the .wasm via readFileSync and
+ * instantiates during require(), so it is loaded through `createRequire(import.meta.url)`.
+ * There is NO async init() call. An absent artifact (fat/pkg-node not built) REJECTS naming
+ * the build command — never a silent undefined. This file installs no global.
+ */
+
+import { createRequire } from 'node:module';
+import { fileURLToPath } from 'node:url';
+
+const require = createRequire(import.meta.url);
+
+/** The nodejs glue's path: a fact of this module's own placement. */
+export const NODE_PKG_PATH = fileURLToPath(new URL('../../../fat/pkg-node/egpt_wasm.js', import.meta.url));
+
+/**
+ * Load the WASM universe constructor for node.
+ *
+ * @returns {Promise<{WasmUniverse: Function}>}
+ */
+export function load() {
+    return new Promise(function (resolve, reject) {
+        let wasmMod;
+        try {
+            wasmMod = require(NODE_PKG_PATH);
+        } catch (e) {
+            if (e && e.code === 'MODULE_NOT_FOUND') {
+                reject(new Error(
+                    '[wasm-load-node] WASM node artifact not found at: ' + NODE_PKG_PATH + '\n' +
+                    'Build it with:\n' +
+                    '  wasm-pack build fat/crates/egpt_wasm --target nodejs --out-dir fat/pkg-node\n' +
+                    '(from the FRAQTL repo root; `make wasm-node`)'
+                ));
+                return;
+            }
+            reject(new Error('[wasm-load-node] Failed to load WASM node module: ' + (e && e.message)));
+            return;
+        }
+        const WasmUniverse = wasmMod.WasmUniverse;
+        if (!WasmUniverse) {
+            reject(new Error('[wasm-load-node] WasmUniverse not found in module at ' + NODE_PKG_PATH +
+                '. Ensure wasm-pack built with --target nodejs.'));
+            return;
+        }
+        resolve({ WasmUniverse: WasmUniverse });
+    });
+}
+
+/** The loader the node door hands to bootEngine. */
+export const nodeWasmLoader = Object.freeze({ env: 'node', load: load });

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

@@ -0,0 +1,145 @@
+/* Copyright 2023-2026 by Essam Abadir */
+
+/**
+ * FieldBuilder — shared smooth heightfield builder.
+ *
+ * The ONE field-build source for all renderer providers. Both p5 and three
+ * providers call FieldBuilder.buildHeightField(frameData, opts) to produce
+ * the same smooth Uint8Array heightfield. No per-provider splat loop.
+ *
+ * Algorithm: soft-splat with quadratic falloff kernel + optional separable blur.
+ * Each particle deposits its fullness into a (2R+1)^2 neighborhood with weight
+ *   w(dx,dy) = max(0, 1 - (dx^2+dy^2)/R^2)
+ * Accumulated values are scaled by FIELD_GAIN then clamped to [0,255].
+ * An optional 3-tap separable blur pass smooths the result further.
+ *
+ * Coordinate convention: field[py * w + px], physics-pixel space (y-down, top-left).
+ * Matches the vTexCoord flip in the providers' texture uploads.
+ *
+ * Export:
+ *   FieldBuilder.buildHeightField(frameData, opts) -> Uint8Array(w * h)
+ *   FieldBuilder.FIELD_OPTS  — shared default options constant
+ */
+
+import { requireProviderSize } from './renderer-provider-contract.js';
+
+
+    // Shared constants — both providers use THESE values so they cannot drift.
+    var FIELD_OPTS = {
+        w:      300,    // field texel resolution — a render choice, independent of the world rect
+        h:      200,    // (canvasW/canvasH map physics px onto it per call)
+        radius: 2,      // splat radius in texels
+        gain:   4.0,    // scale factor: typical fullness × gain ≈ mid-range accumulation
+        blur:   true    // run a 3-tap separable blur pass after the splat
+    };
+
+
+    /**
+     * Build a smooth single-channel heightfield from frameData.
+     *
+     * @param {Array<{rect:{x,y}, fullness:number}>} frameData
+     * @param {{w:number, h:number, radius:number, gain:number, blur:boolean,
+     *          canvasW:number, canvasH:number}} opts
+     *   `canvasW`/`canvasH` are REQUIRED: the physics rect the frameData coordinates live in
+     *   (the runner's canvas_rect). Callers spread FIELD_OPTS and add them.
+     * @returns {Uint8Array} length = opts.w * opts.h, values 0-255
+     * @throws {Error} when canvasW/canvasH are absent or not positive finite numbers.
+     */
+    function buildHeightField(frameData, opts) {
+        requireProviderSize('FieldBuilder.buildHeightField(frameData, Object.assign({}, FIELD_OPTS, ' +
+            '{ canvasW, canvasH })) opts.canvasW/canvasH', opts && opts.canvasW, opts && opts.canvasH);
+        var canvasW = opts.canvasW;
+        var canvasH = opts.canvasH;
+        var fw = opts.w      || FIELD_OPTS.w;
+        var fh = opts.h      || FIELD_OPTS.h;
+        var R  = opts.radius !== undefined ? opts.radius : FIELD_OPTS.radius;
+        var gain = opts.gain !== undefined ? opts.gain : FIELD_OPTS.gain;
+        var doBlur = opts.blur !== undefined ? opts.blur : FIELD_OPTS.blur;
+
+        var R2 = R * R;
+        // Use a Float32 accumulation buffer then quantize at the end
+        var accum = new Float32Array(fw * fh);
+
+        if (frameData) {
+            // Map physics-pixel coords → field-texel coords by (fw/canvasW, fh/canvasH).
+            var scaleX = fw / canvasW;
+            var scaleY = fh / canvasH;
+
+            for (var i = 0; i < frameData.length; i++) {
+                var f  = frameData[i];
+                var fx = f.rect.x * scaleX;
+                var fy = f.rect.y * scaleY;
+                var px = Math.round(fx) | 0;
+                var py = Math.round(fy) | 0;
+                var v  = f.fullness || 0;
+                if (v <= 0) continue;
+
+                // Splat into (2R+1)^2 neighborhood
+                var x0 = Math.max(0,  px - R);
+                var x1 = Math.min(fw - 1, px + R);
+                var y0 = Math.max(0,  py - R);
+                var y1 = Math.min(fh - 1, py + R);
+
+                for (var sy = y0; sy <= y1; sy++) {
+                    var dy = sy - py;
+                    for (var sx = x0; sx <= x1; sx++) {
+                        var dx = sx - px;
+                        var d2 = dx * dx + dy * dy;
+                        if (d2 > R2) continue;
+                        var w = 1.0 - d2 / R2;   // quadratic falloff
+                        accum[sy * fw + sx] += v * w;
+                    }
+                }
+            }
+        }
+
+        // Quantize (scale by gain, clamp to [0,255])
+        var out = new Uint8Array(fw * fh);
+        for (var k = 0; k < accum.length; k++) {
+            var val = Math.round(accum[k] * gain * 255);
+            out[k] = val > 255 ? 255 : val;
+        }
+
+        // Optional 3-tap separable Gaussian blur [0.25, 0.5, 0.25]
+        if (doBlur && fw > 2 && fh > 2) {
+            var tmp = new Uint8Array(fw * fh);
+            var row, col, idx, a, b, c;
+
+            // Horizontal pass
+            for (row = 0; row < fh; row++) {
+                var rowBase = row * fw;
+                tmp[rowBase] = out[rowBase];
+                tmp[rowBase + fw - 1] = out[rowBase + fw - 1];
+                for (col = 1; col < fw - 1; col++) {
+                    idx = rowBase + col;
+                    a = out[idx - 1];
+                    b = out[idx];
+                    c = out[idx + 1];
+                    tmp[idx] = (a + 2 * b + c + 2) >> 2;
+                }
+            }
+
+            // Vertical pass (reads tmp, writes out)
+            for (col = 0; col < fw; col++) {
+                out[col] = tmp[col];
+                out[(fh - 1) * fw + col] = tmp[(fh - 1) * fw + col];
+            }
+            for (row = 1; row < fh - 1; row++) {
+                for (col = 0; col < fw; col++) {
+                    a = tmp[(row - 1) * fw + col];
+                    b = tmp[row * fw + col];
+                    c = tmp[(row + 1) * fw + col];
+                    out[row * fw + col] = (a + 2 * b + c + 2) >> 2;
+                }
+            }
+        }
+
+        return out;
+    }
+
+    var FieldBuilder = {
+        FIELD_OPTS:      FIELD_OPTS,
+        buildHeightField: buildHeightField
+    };
+
+export { FieldBuilder };

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

@@ -0,0 +1,163 @@
+/* Copyright 2023-2026 by Essam Abadir */
+
+/**
+ * Filters — built-in post-process filter specs for the RendererProvider shim.
+ *
+ * A filterSpec is a backend-keyed object:
+ *   {
+ *     name:    string,           // unique ID used by filter()/removeFilter()
+ *     glsl:    string,           // GLSL 1.0 WebGL2 fragment body (works both backends)
+ *     strands: function(p5),     // optional: p5.strands JS body for WebGPU
+ *     tsl:     function(THREE),  // optional: TSL node graph for three.js WebGPU
+ *     uniforms: string[]         // uniform names this filter uses
+ *   }
+ *
+ * The glsl field is the day-one portable body — works on the WebGL2 path for
+ * BOTH backends (p5 provider offscreen canvas; three ShaderMaterial quad).
+ * strands/tsl fields are ADDITIVE for the WebGPU path and are NOT required.
+ *
+ * Standard uniforms always available to every filter:
+ *   uResolution  vec2   — canvas size in pixels
+ *   uTime        float  — simulation seconds at the tick being rendered
+ *                         (tick / FILTER_TICKS_PER_SECOND, 60 today; owner:
+ *                         renderer-provider-contract.js `filterTime`) — a paused
+ *                         scene's filters hold still
+ *   uField       sampler2D  — R8 occupancy/height texture (from doTick() frameData)
+ *   uScene       sampler2D  — rendered particle layer (the frame before this pass)
+ *
+ * Coordinate convention: vTexCoord is [0..1] with origin at bottom-left (WebGL
+ * default for textures). The water heightfield uses this directly.
+ *
+ * Usage:
+ *   renderer.filter(Filters.water);
+ *   renderer.filter(Filters.bloom);
+ *   renderer.removeFilter('water');
+ */
+
+
+    // ── Filters.water ────────────────────────────────────────────────────────
+    //
+    // WebGL2 water-surface post-process (§8 from WS_RENDERER_SHIM_DESIGN.md).
+    // uField = occupancy/height from the CA wave; uScene = rendered particle layer.
+    // Computes surface normal via finite differences of the heightfield, then:
+    //   - Refracts the scene lookup by the surface slope
+    //   - Adds a specular highlight from a fixed light
+    //   - Adds fake caustics (bright at high curvature)
+    //   - Applies a shallow-water tint
+
+    var WATER_GLSL = [
+        'precision highp float;',
+        '',
+        'uniform sampler2D uField;',
+        'uniform sampler2D uScene;',
+        'uniform vec2      uResolution;',
+        'uniform float     uTime;',
+        '',
+        'varying vec2 vTexCoord;',
+        '',
+        '// Sample height with a small ripple that advances with simulation time (uTime).',
+        'float height(vec2 uv) {',
+        '    float h = texture2D(uField, uv).r;',
+        '    h += 0.03 * sin(uv.x * 60.0 + uTime * 1.5)',
+        '       + 0.03 * sin(uv.y * 48.0 - uTime * 1.1);',
+        '    return h;',
+        '}',
+        '',
+        'void main() {',
+        '    vec2 uv    = vTexCoord;',
+        '    vec2 texel = 1.0 / uResolution;',
+        '',
+        '    // Surface normal from finite differences (Sobel-ish).',
+        '    float hL = height(uv - vec2(texel.x, 0.0));',
+        '    float hR = height(uv + vec2(texel.x, 0.0));',
+        '    float hD = height(uv - vec2(0.0, texel.y));',
+        '    float hU = height(uv + vec2(0.0, texel.y));',
+        '    vec3  n  = normalize(vec3(hL - hR, hD - hU, 0.18));',
+        '',
+        '    // Refraction: offset scene lookup by surface slope (Snell-ish cheap approx).',
+        '    float refractAmt = 0.025;',
+        '    vec2  refracted  = uv + n.xy * refractAmt;',
+        '    vec3  base       = texture2D(uScene, refracted).rgb;',
+        '',
+        '    // Specular highlight from a fixed directional light.',
+        '    vec3  lightDir = normalize(vec3(0.4, 0.7, 0.6));',
+        '    float spec     = pow(max(dot(n, lightDir), 0.0), 32.0);',
+        '',
+        '    // Fake caustics: bright where the surface focuses (high curvature).',
+        '    float curvature = abs((hL + hR + hU + hD) * 0.25 - height(uv));',
+        '    float caustic   = smoothstep(0.02, 0.12, curvature);',
+        '',
+        '    // Shallow-water tint deepening with height; add specular + caustics.',
+        '    vec3  waterTint = mix(',
+        '        vec3(0.02, 0.10, 0.16),',
+        '        vec3(0.10, 0.34, 0.42),',
+        '        height(uv)',
+        '    );',
+        '    vec3  color = base * 0.65 + waterTint * 0.55',
+        '                + spec    * vec3(0.9, 0.97, 1.0)',
+        '                + caustic * vec3(0.45, 0.85, 0.95);',
+        '',
+        '    gl_FragColor = vec4(color, 1.0);',
+        '}'
+    ].join('\n');
+
+    // ── Filters.bloom ────────────────────────────────────────────────────────
+    //
+    // Simple single-pass bloom / glow: bright areas bleed softly into neighbours.
+    // Uses a 9-tap box blur on pixels above a luminance threshold.
+
+    var BLOOM_GLSL = [
+        'precision highp float;',
+        '',
+        'uniform sampler2D uScene;',
+        'uniform vec2      uResolution;',
+        'uniform float     uTime;',
+        '',
+        'varying vec2 vTexCoord;',
+        '',
+        'float luma(vec3 c) { return dot(c, vec3(0.299, 0.587, 0.114)); }',
+        '',
+        'void main() {',
+        '    vec2 uv    = vTexCoord;',
+        '    vec2 texel = 1.0 / uResolution;',
+        '',
+        '    vec3 base  = texture2D(uScene, uv).rgb;',
+        '',
+        '    // 9-tap box blur of bright regions only',
+        '    vec3 bloom = vec3(0.0);',
+        '    float wSum = 0.0;',
+        '    for (int dx = -2; dx <= 2; dx++) {',
+        '        for (int dy = -2; dy <= 2; dy++) {',
+        '            vec2 off   = vec2(float(dx), float(dy)) * texel * 2.0;',
+        '            vec3 s     = texture2D(uScene, uv + off).rgb;',
+        '            float l    = luma(s);',
+        '            float w    = step(0.5, l);   // only bright pixels contribute',
+        '            bloom += s * w;',
+        '            wSum  += w;',
+        '        }',
+        '    }',
+        '    if (wSum > 0.0) bloom /= wSum;',
+        '',
+        '    // Additive blend: base + soft bloom',
+        '    vec3 color = base + bloom * 0.35;',
+        '    gl_FragColor = vec4(color, 1.0);',
+        '}'
+    ].join('\n');
+
+    // ── Filters catalog ────────────────────────────────────────────────────
+
+    var Filters = {
+        water: {
+            name:     'water',
+            glsl:     WATER_GLSL,
+            uniforms: ['uField', 'uScene', 'uResolution', 'uTime']
+        },
+
+        bloom: {
+            name:     'bloom',
+            glsl:     BLOOM_GLSL,
+            uniforms: ['uScene', 'uResolution', 'uTime']
+        }
+    };
+
+export { Filters };

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

@@ -0,0 +1,85 @@
+/* Copyright 2023-2026 by Essam Abadir */
+
+/**
+ * RenderFamily — the ONE per-frame render-FAMILY decode authority for the 3D provider.
+ *
+ * WHY (Red-Team R2-4 §6; contract: docs/internal/engine/RENDERER_CONTRACT.md,
+ * §per-frame render-intent resolution): the three.js tick loop used to
+ * decide the render path (mesh vs cube vs sphere vs point-sprite) ONCE per tick from a
+ * `RenderShape.resolve(null, opts)` / `RenderMesh.resolve(null, opts)` call — frame hard-coded
+ * `null`, so a correctly-stamped PER-FRAME `render.shape` / `render.mesh` was silently ignored
+ * (the bug class the resolver-only unit tests structurally cannot see: a resolver is 100%
+ * correct while its ONLY caller feeds it null). This file lifts that routing DECISION into a
+ * PURE, Node-testable decode function with a SINGLE caller — mirroring RenderShape.js
+ * (RenderShape.resolve), the existing precedent for "extract the tick-loop routing
+ * decision into a pure decode fn." A future call-site cannot re-pass null silently because this
+ * function has NO null-frame code path — it composes the two authorities per-frame.
+ *
+ * It COMPOSES the two existing decode authorities (never re-maps): RenderMesh first (a mesh stamp
+ * outranks a shape), then RenderShape. It adds NO shader, NO GLSL attribute, NO new vocab — the
+ * three-provider folds the returned family into its existing per-(dim,family) bucket key.
+ *
+ * FAMILY (what THREE object draws the frame):
+ *   'mesh'   (+assetId)          → a clone of a loaded glTF (RenderMesh.resolve truthy; 3D-only)
+ *   'cube'                       → a lit BoxGeometry InstancedMesh (RenderShape 'cube'; 3D-only)
+ *   'sphere'                     → a lit SphereGeometry InstancedMesh (RenderShape 'sphere'; 3D-only)
+ *   'pts' (+uShapeVariant 0|1)   → the Points shader sprite (ball/circle→0, box→1; any 2D shape)
+ *
+ * 3D gate: mesh/cube/sphere are 3D-only families (they are lit meshes). When `is3D` is false
+ * (2D three, or p5 never calls here) they DEGRADE to the 'pts' family exactly as RenderShape
+ * already degrades cube/sphere to the ball/box sprite — no separate 2D branch needed.
+ *
+ * Export contract (PURE — no THREE, no side effects; runs unchanged in pkg-node/conformance):
+ *   RenderFamily.resolveRenderFamily(frame, renderOpts, is3D)
+ *       -> { family:'mesh'|'cube'|'sphere'|'pts', key:string, assetId?:string, uShapeVariant?:number }
+ *   RenderFamily.familyKey(res) -> string   (the bucket-key token: 'mesh:<id>'|'cube'|'sphere'|'pts:<v>')
+ *
+ * Single-source: RenderShape / RenderMesh remain the shape/mesh decode authorities; this file
+ * only ORDERS them into one family verdict. It re-uses their outputs by reference — it never
+ * re-lists shape names or re-reads string_map keys itself.
+ */
+
+import { RenderShape } from './RenderShape.js';
+import { RenderMesh } from './RenderMesh.js';
+
+    /**
+     * Resolve the render FAMILY of one frame, composing RenderMesh (highest) then RenderShape.
+     *
+     * @param {object} frame       - FrameData; frame.data.string_map may carry render.mesh/render.shape.
+     * @param {object} renderOpts  - the setRenderOption bag (opts.mesh / opts.shape scene defaults).
+     * @param {boolean} is3D       - whether the provider is in 3D mode (mesh/cube/sphere families
+     *                               only exist in 3D; 2D degrades every one to the 'pts' sprite).
+     * @returns {{family:string, key:string, assetId?:string, uShapeVariant?:number}}
+     */
+    function resolveRenderFamily(frame, renderOpts, is3D) {
+        // 1. Mesh outranks shape (a per-frame render.mesh stamp routes to a glTF clone). 3D-only.
+        if (is3D) {
+            var assetId = RenderMesh.resolve(frame, renderOpts);
+            if (assetId) {
+                return { family: 'mesh', assetId: assetId, key: 'mesh:' + assetId };
+            }
+        }
+        // 2. Shape family. cube/sphere are lit InstancedMeshes (3D-only); everything else is the
+        //    Points sprite whose ball-vs-box is the per-bucket uShape uniform.
+        var shape = RenderShape.resolve(frame, renderOpts);
+        if (is3D && RenderShape.isCubeMesh(shape)) {
+            return { family: 'cube', key: 'cube' };
+        }
+        if (is3D && RenderShape.isSphereMesh(shape)) {
+            return { family: 'sphere', key: 'sphere' };
+        }
+        var uShapeVariant = RenderShape.toUniform(shape);   // 0 = ball/circle/(degraded cube/sphere), 1 = box
+        return { family: 'pts', uShapeVariant: uShapeVariant, key: 'pts:' + uShapeVariant };
+    }
+
+    /** The bucket-key token for a resolved family (already precomputed on `.key`). */
+    function familyKey(res) {
+        return res && res.key ? res.key : 'pts:0';
+    }
+
+    var RenderFamily = {
+        resolveRenderFamily: resolveRenderFamily,
+        familyKey:           familyKey
+    };
+
+export { RenderFamily };