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

package/dist/frqtl/compat/renderer/renderCapabilities-common.js

@@ -0,0 +1,186 @@
+/* Copyright 2023-2026 by Essam Abadir */
+
+/**
+ * renderCapabilities-common.js — the SHARED universal + filter capability
+ * descriptors every `RendererProvider.renderCapabilities()` implementation
+ * declares (WS Studio Controls Realignment, Bite S5b — architect's S5a gate
+ * "minor DRY recommendation": `p5-provider.js` and `three-provider.js` had
+ * byte-identical `_universalRenderCapabilities` bodies + an identical
+ * per-Filters-entry toggle loop, hand-copied across two legitimately-
+ * independent BYO files — a 4th universal knob would have needed adding in
+ * two places. This module is the ONE owner both providers import).
+ *
+ * ── Layer 1: API contract ────────────────────────────────────────────────────
+ *
+ * Pure, module-level free functions — no live WebGL/THREE/canvas instance
+ * needed (capability DESCRIPTORS are static metadata; live VALUES are read
+ * separately via `FrqtlApp.getRenderOption`) — this is what keeps every caller
+ * unit-testable in plain Node with no browser.
+ *
+ * `universalRenderCapabilities(normalizeFieldDescriptor, RenderShapeRef, FrameDataSchemaRef)`
+ *   → the 3 knobs BOTH built-in providers honor identically (README §3):
+ *     `shape` (enum, RenderShape.VALID_SHAPES), `colorScheme` (enum,
+ *     RENDER_INTENT_VALUES['render.colorScheme']), `renderBaseCanvas` (boolean,
+ *     render-only). Does NOT include filter toggles — see `filterRenderCapabilities`
+ *     below (three-provider splices its OWN effect-layer knobs BETWEEN the
+ *     universal 3 and the filter toggles, so the lists are kept separate).
+ *
+ * `meshRenderCapabilities(normalizeFieldDescriptor)`
+ *   → the scene external-mesh pair (`mesh`, `meshScale`) a provider with a mesh
+ *     render path declares (three).
+ *
+ * `filterRenderCapabilities(normalizeFieldDescriptor, FiltersRef)`
+ *   → one `filter.<name>` toggle descriptor (boolean, render-only, default false) per
+ *     `Filters.js` catalog entry — `filter()`/`removeFilter()` are REQUIRED
+ *     contract methods on every provider (README §1), so every provider
+ *     declares every filter identically; this is why the loop is shared
+ *     rather than per-provider.
+ *
+ * A caller composes its own full list as
+ * `universalRenderCapabilities(...).concat(providerOnlyCaps).concat(filterRenderCapabilities(...))`
+ * — see `p5-provider.js`'s `_renderCapabilitiesP5` / `three-provider.js`'s
+ * `_renderCapabilitiesThree` for the two worked call sites.
+ *
+ * `knownRenderCapabilityNames(providers)`
+ *   → the union of names over the renderer registry (`providers/index.js` RENDERER_PROVIDERS,
+ *     each entry registering its static `renderCapabilities` beside `makeProvider`) —
+ *     the "known" set saved render rows are partitioned against.
+ *
+ * ── Module format: an ES module, like every peer under lib/frqtl/compat/renderer/ ──
+ *
+ * ── Layer 2: physics behavior ────────────────────────────────────────────────
+ * Zero physics — pure metadata describing render-surface knobs (root
+ * CLAUDE.md §Object architecture: render is output-boundary only).
+ */
+
+
+
+/** `{value:value}` identity map — the shape `makeControlsForObject.js`'s
+ *  `_enumHandler` requires for `constraint.values` (`_isIdentityValuesMap`). */
+function _identityMap(values) {
+    var m = {};
+    for (var i = 0; i < values.length; i++) { m[values[i]] = values[i]; }
+    return m;
+}
+
+/**
+ * The 3 universal knobs both p5 and three honor identically.
+ * @param {function} normalizeFieldDescriptor — `lib/shim/field-descriptor`'s
+ *   `normalizeFieldDescriptor` (dependency-injected, not required here, so
+ *   this module has no import of its own — mirrors the callers' own
+ *   already-resolved-ref-passing convention).
+ * @param {{VALID_SHAPES:string[]}} RenderShapeRef
+ * @param {{RENDER_INTENT_VALUES:object}} FrameDataSchemaRef
+ * @returns {object[]} 3 normalized field descriptors.
+ */
+function universalRenderCapabilities(normalizeFieldDescriptor, RenderShapeRef, FrameDataSchemaRef) {
+    return [
+        normalizeFieldDescriptor({
+            name: 'shape', type: 'enum', default: 'ball',
+            // Bite 5b A3: this is the render-LEVEL DEFAULT shape (per-object sugar like a
+            // SphereEmitter's `renderShape` field overrides it per-leaf via render.shape) —
+            // labelled "Default Shape" so the scoping reads true. `label` overrides the shown
+            // control label only; the capability key stays `shape` (setRenderOption('shape',…)).
+            label: 'Default Shape',
+            constraint: { values: _identityMap(RenderShapeRef.VALID_SHAPES) },
+            description: 'Render-level DEFAULT particle shape (RenderShape.js — the one shape ' +
+                'authority). A per-object sugar override (e.g. a SphereEmitter renderShape) wins ' +
+                'per-leaf via the render.shape key; this is the fallback when none is set.'
+        }),
+        normalizeFieldDescriptor({
+            name: 'colorScheme', type: 'enum', default: 'warmcool',
+            constraint: { values: _identityMap(FrameDataSchemaRef.RENDER_INTENT_VALUES['render.colorScheme']) },
+            description: 'Per-experiment default fullness-to-color ramp (LightColor.js — the one color authority).'
+        }),
+        normalizeFieldDescriptor({
+            name: 'renderBaseCanvas', type: 'boolean', default: true, engineVisible: false,
+            description: 'Whether the particle/base layer composites into the scene before any ' +
+                'post-process pass (README §3). Both p5 and three honor this identically; the write ' +
+                'gate coerces a 0/1 control value to the boolean the providers read.'
+        })
+    ];
+}
+
+/**
+ * The scene external-mesh pair, declared by a provider with a mesh render path (three):
+ * `mesh` is read one hop away, in `RenderMesh.resolve(frame, renderOpts)` (priority #3,
+ * below a frame's `render.mesh` and a large object's `mesh`); `meshScale` scales the clones.
+ * @param {function} normalizeFieldDescriptor
+ * @returns {object[]} 2 normalized field descriptors.
+ */
+function meshRenderCapabilities(normalizeFieldDescriptor) {
+    return [
+        normalizeFieldDescriptor({
+            name: 'mesh', type: 'string', default: null,
+            description: 'Scene-default external glTF asset id (URL) every frame is drawn as, in 3D. ' +
+                'OPEN-ID like its per-frame twin render.mesh; unset draws the shape path.'
+        }),
+        normalizeFieldDescriptor({
+            name: 'meshScale', type: 'number', unit: 'multiplier', default: 1,
+            constraint: { min: 0.01, max: 100, integer: false },
+            description: 'Scene-wide scale multiplier for external-mesh clones (a frame\'s ' +
+                'render.meshScale overrides it per frame).'
+        })
+    ];
+}
+
+/**
+ * One `filter.<name>` toggle capability per `Filters.js` catalog entry.
+ * @param {function} normalizeFieldDescriptor
+ * @param {object} FiltersRef — `Filters.js`'s exported catalog (`{water:{...}, bloom:{...}, ...}`).
+ * @returns {object[]} `Object.keys(FiltersRef).length` normalized field descriptors.
+ */
+function filterRenderCapabilities(normalizeFieldDescriptor, FiltersRef) {
+    var caps = [];
+    var filterNames = Object.keys(FiltersRef);
+    for (var i = 0; i < filterNames.length; i++) {
+        caps.push(normalizeFieldDescriptor({
+            name: 'filter.' + filterNames[i], type: 'boolean', default: false, engineVisible: false,
+            description: 'Toggle the "' + filterNames[i] + '" post-process filter ' +
+                '(Filters.js — the runner routes the write to filter()/removeFilter(); a 0/1 ' +
+                'control value is coerced to the boolean).'
+        }));
+    }
+    return caps;
+}
+
+/**
+ * The union of capability NAMES every registered renderer declares — the "known" set a
+ * saved render row is partitioned against (declared by the target / by another renderer /
+ * by none). Read off each registry entry's STATIC `renderCapabilities` (the providers
+ * register it beside `makeProvider`), so no provider is constructed and no name is listed
+ * by hand.
+ * @param {Object<string, {renderCapabilities:function}>} providers — `RENDERER_PROVIDERS`.
+ * @returns {string[]} sorted, de-duplicated names.
+ * @throws {Error} when the registry is missing or an entry exposes no static renderCapabilities.
+ */
+function knownRenderCapabilityNames(providers) {
+    if (!providers || typeof providers !== 'object') {
+        throw new Error('[RenderCapabilitiesCommon.knownRenderCapabilityNames] requires the renderer ' +
+            'registry (providers/index.js RENDERER_PROVIDERS); got ' + (providers === null ? 'null' : typeof providers) +
+            '. (FAIL-LOUD.)');
+    }
+    var seen = {};
+    var ids = Object.keys(providers);
+    for (var i = 0; i < ids.length; i++) {
+        var entry = providers[ids[i]];
+        if (!entry || typeof entry.renderCapabilities !== 'function') {
+            throw new Error('[RenderCapabilitiesCommon.knownRenderCapabilityNames] registered renderer "' +
+                ids[i] + '" exposes no static renderCapabilities() — every registry entry publishes its ' +
+                'capability descriptors beside makeProvider. (FAIL-LOUD.)');
+        }
+        var caps = entry.renderCapabilities();
+        for (var j = 0; j < caps.length; j++) { seen[caps[j].name] = true; }
+    }
+    return Object.keys(seen).sort();
+}
+
+// ── Export ────────────────────────────────────────────────────────────────────
+
+export {
+    universalRenderCapabilities,
+    filterRenderCapabilities,
+    knownRenderCapabilityNames,
+    meshRenderCapabilities,
+    _identityMap
+};

package/dist/frqtl/compat/renderer/renderer-provider-contract.js

@@ -0,0 +1,238 @@
+/* Copyright 2023-2026 by Essam Abadir */
+
+/**
+ * renderer-provider-contract.js — the CODE OWNER of the `RendererProvider` method lists.
+ *
+ * `RendererProvider` is duck-typed: a BYO renderer is a plain object from a
+ * `makeProvider()` factory, registered through the boot-fixed display slot. Nothing is
+ * imported to implement it — which is exactly why the METHOD LISTS need one owner. Before
+ * this module they existed only as prose in `docs/internal/engine/RENDERER_CONTRACT.md` §1
+ * and as scattered `typeof provider.X === 'function'` checks in the hosts; a BYO author
+ * checking their own object had to hand-copy the list, which is the schema-mirror
+ * anti-pattern with the doc as the mirror. THIS FILE is now the owner; the doc cites it.
+ *
+ * The two lists are transcribed from RENDERER_CONTRACT.md §1 / §1a. A method's SEMANTICS
+ * stay in that document — this module owns only the NAMES and the required/optional split,
+ * because that is the only part a program can check — plus the checkable rules the built-in
+ * providers share: `requireProviderSize` (init/setSize take the runner's physics rect, REQUIRED),
+ * `requireMountHost` (init's `parentEl` names the element the canvas mounts in, REQUIRED),
+ * `requireSceneSurface` (init RETURNS its HTMLCanvasElement), `SCENE_SURFACE_ATTR` (the marker
+ * the runner stamps on that canvas) and `filterTime` (the value of the standard `uTime` filter
+ * uniform, derived from the tick being rendered).
+ *
+ * ── THE REQUIRED/OPTIONAL SPLIT IS LOAD-BEARING ─────────────────────────────
+ *
+ * An absent OPTIONAL capability is NEVER an error (RENDERER_CONTRACT §1a, "absent ⇒
+ * hidden, never an error"): a provider that omits `getCameraControl` simply gets no camera
+ * strip. Hosts capability-check per method — they never renderer-sniff. So
+ * `validateRendererProvider` reports optionals as CAPABILITIES, never as failures, and its
+ * `ok` is decided by the REQUIRED nine alone.
+ *
+ * ── IT IS A VALIDATOR, NOT A GATE ───────────────────────────────────────────
+ *
+ * `validateRendererProvider` NEVER THROWS — not even on a non-object. It returns a report;
+ * the CALLER decides whether a missing method is fatal in its context (a host that boots a
+ * provider fails loud; an authoring tool that lints one shows a list). A validator that
+ * threw would force every caller to wrap it in try/catch to ask a question.
+ *
+ * @example
+ *   import { validateRendererProvider } from '@descix/frqtl-web';   // or '@descix/frqtl-node'
+ *   const report = validateRendererProvider(myProvider);
+ *   if (!report.ok) throw new Error('BYO renderer missing: ' + report.missing.join(', '));
+ *   // report.capabilities → e.g. ['renderCapabilities', 'captureStill']
+ */
+
+
+    /**
+     * The nine REQUIRED methods. Every renderer — built-in or BYO — must implement
+     * exactly these; nothing above the shim calls anything else on a renderer.
+     * @type {string[]}
+     */
+    var RENDERER_PROVIDER_REQUIRED = [
+        'init',          // create canvas/context (+ scene/buffers); RETURNS the HTMLCanvasElement
+        'setSize',       // resize the drawing surface
+        'start',         // may be a NO-OP (the RAF loop is FrqtlApp's)
+        'stop',
+        'destroy',       // tear down; release GL resources
+        'renderTick',    // draw ONE frame from pure data
+        'filter',        // queue/apply a post-process pass
+        'removeFilter',  // remove a queued pass by name
+        'raw'            // the underlying backend object (escape hatch)
+    ];
+
+    /**
+     * The five OPTIONAL capabilities. Absent ⇒ the corresponding host UI is hidden.
+     * NEVER an error.
+     * @type {string[]}
+     */
+    var RENDERER_PROVIDER_OPTIONAL = [
+        'renderCapabilities',  // FieldDescriptor[] — this provider's own render knobs
+        'getCameraControl',    // the orbit/pose sugar handle
+        'screenToWorld',       // unproject a canvas point to a world point
+        'captureStill',        // the `composite` stage tap
+        'projection'           // the scene's camera intrinsics (rides the SceneRecord)
+    ];
+
+    /**
+     * Check a candidate against the frozen `RendererProvider` contract.
+     *
+     * @param {object} provider - the object a `makeProvider()` factory returned.
+     * @returns {{ok: boolean, missing: string[], capabilities: string[]}}
+     *   `ok`           — true iff EVERY required name is a function.
+     *   `missing`      — the required names that are not functions (in contract order).
+     *   `capabilities` — the optional names that ARE functions (in contract order).
+     *   A non-object argument reports every required name missing and no capabilities —
+     *   it does not throw.
+     */
+    function validateRendererProvider(provider) {
+        var isObject = (provider !== null && (typeof provider === 'object' || typeof provider === 'function'));
+        if (!isObject) {
+            return { ok: false, missing: RENDERER_PROVIDER_REQUIRED.slice(), capabilities: [] };
+        }
+        var missing = RENDERER_PROVIDER_REQUIRED.filter(function (name) {
+            return typeof provider[name] !== 'function';
+        });
+        var capabilities = RENDERER_PROVIDER_OPTIONAL.filter(function (name) {
+            return typeof provider[name] === 'function';
+        });
+        return { ok: missing.length === 0, missing: missing, capabilities: capabilities };
+    }
+
+    function _isPositiveFinite(n) {
+        return typeof n === 'number' && isFinite(n) && n > 0;
+    }
+
+    /**
+     * The `init({width, height})` / `setSize(width, height)` size rule, owned here so both
+     * built-in providers throw the SAME sentence. `width`/`height` are the runner's physics
+     * rect (`runner.canvas_rect`), which `FrqtlApp.createCanvas` hands to
+     * `provider.init({width, height})`; the scene writes that rect ONCE through
+     * `exp.createCanvas(w, h, cfg)` / `exp.createScene(w, h, d, cfg)`. A provider holds no size of
+     * its own. The display size is the host element's CSS box, never a provider argument.
+     *
+     * Unlike `validateRendererProvider`, this IS a gate: it THROWS on a missing or non-positive
+     * dimension (a defaulted size would draw a confident picture of the wrong world).
+     *
+     * @param {string} who    - the calling site, e.g. `'p5Provider.init'`.
+     * @param {*}      width
+     * @param {*}      height
+     * @throws {Error} unless both are positive finite numbers.
+     */
+    function requireProviderSize(who, width, height) {
+        if (_isPositiveFinite(width) && _isPositiveFinite(height)) { return; }
+        throw new Error(who + ': width and height must be positive finite numbers (got width=' +
+            String(width) + ', height=' + String(height) + '). They are the runner\'s physics rect ' +
+            '(runner.canvas_rect), handed over by FrqtlApp.createCanvas as provider.init({width, height}) ' +
+            'and written once by the scene\'s exp.createCanvas(w, h, cfg) / exp.createScene(w, h, d, cfg). ' +
+            'A provider has no default size; the display size is the host element\'s CSS box, never a ' +
+            'provider argument.');
+    }
+
+    /**
+     * The `init({parentEl})` mount rule, owned here so both DOM providers throw the SAME sentence.
+     * `parentEl` is the runner's `canvasParentId` (`new FrqtlApp({ canvasParentId })` /
+     * `new RecipeContext({ canvasParentId })`), handed over by `FrqtlApp.createCanvas` as
+     * `provider.init({ parentEl })`. It must be a non-empty string naming an element in `document`;
+     * the provider appends its canvas THERE. There is no default mount: a canvas appended to
+     * `document.body` is a canvas the layout never placed.
+     *
+     * Only a provider that MOUNTS calls this — a DOM-free runner (node, the headless renderer)
+     * legitimately has no `canvasParentId`, so the runner never demands one.
+     *
+     * @param {string} who      - the calling site, e.g. `'threeProvider.init'`.
+     * @param {*}      parentEl - the element id from `init(opts).parentEl`.
+     * @returns {HTMLElement} the element named by `parentEl`.
+     * @throws {Error} unless `parentEl` names an element in the page.
+     */
+    function requireMountHost(who, parentEl) {
+        var named = typeof parentEl === 'string' && parentEl.length > 0;
+        var hasDoc = typeof document !== 'undefined' && document !== null &&
+            typeof document.getElementById === 'function';
+        var host = (named && hasDoc) ? document.getElementById(parentEl) : null;
+        if (host) { return host; }
+        var got = !named ? (typeof parentEl === 'string' ? '""' : String(parentEl))
+            : !hasDoc ? JSON.stringify(parentEl) + ', and there is no document'
+            : JSON.stringify(parentEl) + ', which names no element in the page';
+        throw new Error(who + ': canvasParentId is required and must name an element in the page (got ' +
+            got + '). The runner hands it as init({ parentEl }) from new FrqtlApp({ canvasParentId }) / ' +
+            'new RecipeContext({ canvasParentId }). There is no default mount: a canvas appended to ' +
+            'document.body is a canvas the layout never placed. (FAIL-LOUD.)');
+    }
+
+    /**
+     * The attribute that marks a document's scene drawing surface — the ONE DOM-checkable fact
+     * about a provider's surface. `FrqtlApp.createCanvas` (the one mount site) stamps it on the
+     * canvas `provider.init` returned; anything that must find the scene's pixels (a paint
+     * oracle, the eyes) reads `[SCENE_SURFACE_ATTR]` instead of guessing among a document's
+     * canvases. Re-exported to consumers above the engine by `lib/shim/render/render-stages.js`.
+     * @type {string}
+     */
+    var SCENE_SURFACE_ATTR = 'data-frqtl-scene-surface';
+
+    /**
+     * The `init` return rule: `provider.init(opts)` RETURNS its drawing surface as an
+     * `HTMLCanvasElement` (RENDERER_CONTRACT §1). Duck-typed on the element's own shape (tag
+     * CANVAS + `setAttribute` + `getContext`), never `instanceof`, so a canvas made in another
+     * realm (an iframe, a notebook realm) is still a canvas.
+     *
+     * @param {string} who - the calling site, e.g. `'FrqtlApp.createCanvas'`.
+     * @param {*}      el  - what `provider.init` returned.
+     * @returns {HTMLCanvasElement} `el`, unchanged.
+     * @throws {Error} unless `el` is a canvas element.
+     */
+    function requireSceneSurface(who, el) {
+        var isCanvas = el !== null && typeof el === 'object' &&
+            typeof el.tagName === 'string' && el.tagName.toUpperCase() === 'CANVAS' &&
+            typeof el.setAttribute === 'function' && typeof el.getContext === 'function';
+        if (isCanvas) { return el; }
+        var got = (el === null || el === undefined) ? String(el)
+            : (typeof el === 'object' && typeof el.tagName === 'string') ? '<' + el.tagName.toLowerCase() + '>'
+            : (typeof el === 'object' && el.elt !== undefined) ? 'a p5.Element (return its .elt)'
+            : typeof el;
+        throw new Error(who + ': provider.init(opts) must RETURN its drawing surface as an HTMLCanvasElement ' +
+            '(got ' + got + '). The runner stamps ' + SCENE_SURFACE_ATTR + ' on it so the scene surface ' +
+            'is declared, never guessed among the document\'s canvases (RENDERER_CONTRACT §1, init row; ' +
+            'owner: lib/frqtl/compat/renderer/renderer-provider-contract.js).');
+    }
+
+    /**
+     * Ticks per second of filter time. The GYM runs a scene at a 60 TPS cap by default
+     * (CompareView's TPS field), so there a filter animated by `uTime` keeps the pace it had
+     * when it was fed wall-clock seconds; at any other rate it runs at that rate's pace.
+     * @type {number}
+     */
+    var FILTER_TICKS_PER_SECOND = 60;
+
+    /**
+     * The `uTime` filter uniform: seconds of SIMULATION time at the tick being rendered,
+     * `universeData.tick / FILTER_TICKS_PER_SECOND`. Every provider feeds every filter pass this
+     * value, so a filter's animation is a function of the tick: a still of one scene at one
+     * tick is reproducible, both providers agree, and paused water stops moving. Not wrapped:
+     * a wrap would be a visible jump in the animation.
+     *
+     * @param {object} tickData - the TickData the provider is drawing (carries `universeData.tick`).
+     * @returns {number} seconds of simulation time.
+     * @throws {Error} when `tickData` carries no finite non-negative tick (nothing to time the
+     *   filter by: a wall-clock fallback would make the still unreproducible again).
+     */
+    function filterTime(tickData) {
+        var tick = tickData && tickData.universeData && tickData.universeData.tick;
+        if (typeof tick === 'number' && isFinite(tick) && tick >= 0) {
+            return tick / FILTER_TICKS_PER_SECOND;
+        }
+        throw new Error('filterTime: the TickData being rendered must carry universeData.tick (got ' +
+            String(tick) + '). uTime is simulation time at the rendered tick, never the wall clock ' +
+            '(owner: lib/frqtl/compat/renderer/renderer-provider-contract.js). (FAIL-LOUD.)');
+    }
+
+export {
+    RENDERER_PROVIDER_REQUIRED,
+    RENDERER_PROVIDER_OPTIONAL,
+    SCENE_SURFACE_ATTR,
+    validateRendererProvider,
+    requireProviderSize,
+    requireMountHost,
+    requireSceneSurface,
+    FILTER_TICKS_PER_SECOND,
+    filterTime
+};

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

@@ -0,0 +1,172 @@
+/* Copyright 2023-2026 by Essam Abadir */
+
+/**
+ * unprojectStill.js — THE pixel→universe mapping authority for a CAPTURED still (R5).
+ *
+ * Peer of `FieldBuilder.js` (the one field source) and `captureStill-common.js` (the one
+ * readback): a single canonical module every consumer FERRIES instead of writing its own.
+ *
+ * ── Why this exists ──────────────────────────────────────────────────────────
+ *
+ * "Which universe pixel is this image pixel?" is the question every measurement over a
+ * capture actually asks — ring radii, fringe spacing, an object's apparent position. An
+ * OFFLINE corpus consumer cannot ask the live renderer: there is no `screenToWorld` in a
+ * JSONL row. And for a perspective camera the pose bag plus the buffer dims are NOT enough —
+ * the mapping is underdetermined without the camera intrinsics. That is precisely why
+ * eyeballed measurements over screenshots come out shaky.
+ *
+ * So the scene record carries `projection` (the intrinsics) and this module composes it with
+ * the still's `pose` and dims into an unambiguous answer. It is a CONTRACT FUNCTION, not
+ * prose: a consumer's hand-written unproject drifting from the provider's is the
+ * schema-mirror bug applied to MATH, and it is silent — it returns plausible wrong numbers.
+ *
+ * ── Layer 1: API contract ────────────────────────────────────────────────────
+ *
+ * `UnprojectStill.unprojectStill(scene, still, bufX, bufY, worldZ?) → {x, y} | null`
+ *
+ *   @param {object} scene — a SceneRecord (`projection`, `physicsW`, `physicsH`).
+ *   @param {object} still — a still record (`width`, `height`, `cssWidth`, `cssHeight`,
+ *     `pose`). Must be an `rgba8` still: the `framedata` and `r8` channels are not rasters
+ *     of the composited canvas, so a canvas-pixel unprojection is meaningless for them and
+ *     THROWS rather than returning a number nobody should trust. (For `r8`, use
+ *     `fieldTexelToPhysics` below — the field has its own, simpler map.)
+ *   @param {number} bufX,bufY — coordinates in the still's OWN BUFFER (i.e. an array index
+ *     pair: `data[(bufY*width + bufX)*4]`). That is what a corpus consumer actually holds —
+ *     not a CSS coordinate. The conversion to CSS units happens here, once.
+ *   @param {number} [worldZ=0] — the universe z-plane to intersect (3D only; ignored in 2D).
+ *   @returns {{x:number,y:number}|null} physics-pixel point, or `null` when the ray cannot
+ *     resolve (parallel to the plane, or beyond the scene-scale sanity bound).
+ *
+ * `UnprojectStill.fieldTexelToPhysics(scene, still, texX, texY) → {x, y}`
+ *   The `r8` channel's own map: field texel → physics pixel, the exact inverse of the scale
+ *   `FieldBuilder` applied (`fw/canvasW`, `fh/canvasH`). Separate function because the field
+ *   is built in physics space and never passes through a camera — conflating it with the
+ *   canvas unprojection is how a radial profile silently acquires a perspective error.
+ *
+ * ── FAIL-LOUD ────────────────────────────────────────────────────────────────
+ *
+ * A `null`/unknown `projection` THROWS naming the gap (a BYO provider that declares no
+ * intrinsics cannot be unprojected — and guessing `affine2d` under a perspective camera is
+ * the exact "silent 2D-affine fallback" the renderer contract already bans). A
+ * `kind:'perspective'` still with no `pose` THROWS. A wrong-format still THROWS. None of
+ * these returns a plausible wrong number.
+ *
+ * ── Layer 2: physics behaviour ───────────────────────────────────────────────
+ *
+ * ZERO physics: a coordinate transform at the output boundary. It reads records; it cannot
+ * touch a frame, a dimension or a tick.
+ */
+
+import * as ThreeCameraGeometry from './providers/three-camera-geometry.js';
+import * as Camera2dGeometry from './camera2d-geometry.js';
+
+
+
+function _fail(msg) {
+    throw new Error('[unprojectStill] ' + msg + ' (FAIL-LOUD — never a plausible wrong point.)');
+}
+
+
+/**
+ * The 2D camera map — the SAME authority the live p5 provider draws and picks with. Ferried,
+ * never re-derived: a second copy of the pan/zoom terms is the schema-mirror bug applied to
+ * MATH, and it fails silently.
+ */
+
+function _num(v, name) {
+    if (typeof v !== 'number' || !isFinite(v)) { _fail(name + ' must be a finite number, got ' + String(v)); }
+    return v;
+}
+
+function _requireRaster(still) {
+    if (!still || typeof still !== 'object') { _fail('expected a still record, got ' + String(still)); }
+    if (still.format !== 'rgba8') {
+        _fail('this still\'s format is ' + JSON.stringify(still.format) + ', not "rgba8" — the ' +
+              'framedata and r8 channels are not rasters of the composited canvas, so a ' +
+              'canvas-pixel unprojection has no meaning for them (for r8 use fieldTexelToPhysics)');
+    }
+    return still;
+}
+
+/**
+ * unprojectStill — see the module docstring.
+ * @returns {{x:number,y:number}|null}
+ */
+function unprojectStill(scene, still, bufX, bufY, worldZ) {
+    if (!scene || typeof scene !== 'object') { _fail('expected a SceneRecord, got ' + String(scene)); }
+    _requireRaster(still);
+    var proj = scene.projection;
+    if (!proj || typeof proj.kind !== 'string') {
+        _fail('the SceneRecord carries no `projection` — its provider declared no intrinsics, ' +
+              'so this capture cannot be unprojected. Guessing an affine map under a ' +
+              'perspective camera would compute the WRONG point silently');
+    }
+    var pw = _num(scene.physicsW, 'scene.physicsW');
+    var ph = _num(scene.physicsH, 'scene.physicsH');
+    var bw = _num(still.width,  'still.width');
+    var bh = _num(still.height, 'still.height');
+    _num(bufX, 'bufX'); _num(bufY, 'bufY');
+
+    if (proj.kind === 'affine2d') {
+        // The 2D map composes (buffer → canvas) with the CAMERA's pan/zoom, and it DELEGATES
+        // to the same `camera2d-geometry` authority the live provider draws and picks with —
+        // so an offline measurement cannot drift from the picture. The still's own `pose`
+        // supplies {distance, target}; at the default pose the scale is 1 and this reduces
+        // EXACTLY to the previous pure ratio, so unzoomed captures are byte-unchanged.
+        //
+        // This is load-bearing, not tidiness: without the pose terms a ZOOMED 2D still would
+        // unproject as though it showed the whole universe — a silently wrong answer of
+        // exactly the kind that made screenshot measurements untrustworthy.
+        return Camera2dGeometry.screenToWorld2d(still.pose, pw, ph, bufX, bufY, bw, bh);
+    }
+
+    if (proj.kind === 'perspective') {
+        var pose = still.pose;
+        if (!pose || typeof pose !== 'object') {
+            _fail('a perspective still needs its `pose` provenance to unproject — a 3D capture ' +
+                  'with a null pose is not comparable run-to-run and is not acceptance evidence');
+        }
+        var fovY = _num(proj.fovY, 'projection.fovY');
+        // Buffer px → CSS px (the units the pinhole authority takes). cssWidth/Height default
+        // to the buffer dims when the capture had no distinct CSS size (headless).
+        var cw = (typeof still.cssWidth  === 'number' && still.cssWidth  > 0) ? still.cssWidth  : bw;
+        var ch = (typeof still.cssHeight === 'number' && still.cssHeight > 0) ? still.cssHeight : bh;
+        var cssX = bufX * (cw / bw);
+        var cssY = bufY * (ch / bh);
+        // ONE mapping authority: delegate to the SAME analytic pinhole the live provider's
+        // screenToWorld uses, with the captured fovY passed as data.
+        return ThreeCameraGeometry._screenToWorldThree(
+            pose, pw, ph, cssX, cssY, cw, ch, (typeof worldZ === 'number') ? worldZ : 0, fovY);
+    }
+
+    _fail('unknown projection kind ' + JSON.stringify(proj.kind) +
+          ' — known kinds: affine2d, perspective');
+}
+
+/**
+ * fieldTexelToPhysics — the `r8` channel's own map (the exact inverse of FieldBuilder's scale).
+ * @param {object} scene @param {object} still @param {number} texX @param {number} texY
+ * @returns {{x:number,y:number}}
+ */
+function fieldTexelToPhysics(scene, still, texX, texY) {
+    if (!scene || typeof scene !== 'object') { _fail('expected a SceneRecord, got ' + String(scene)); }
+    if (!still || still.format !== 'r8') {
+        _fail('fieldTexelToPhysics expects an "r8" (field) still, got ' +
+              JSON.stringify(still && still.format));
+    }
+    var pw = _num(scene.physicsW, 'scene.physicsW');
+    var ph = _num(scene.physicsH, 'scene.physicsH');
+    var fw = _num(still.width,  'still.width');
+    var fh = _num(still.height, 'still.height');
+    _num(texX, 'texX'); _num(texY, 'texY');
+    // FieldBuilder maps physics → texel by (fw/canvasW, fh/canvasH); this is that inverse.
+    // The field never passes through a camera, which is exactly why it is a separate map.
+    return { x: texX * (pw / fw), y: texY * (ph / fh) };
+}
+
+// ── Export ────────────────────────────────────────────────────────────────────
+
+export {
+    unprojectStill,
+    fieldTexelToPhysics
+};