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

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

@@ -0,0 +1,259 @@
+/* Copyright 2023-2026 by Essam Abadir */
+
+/**
+ * captureStill-common.js — the SHARED pixel-readback + bag-assembly owner for every
+ * `RendererProvider.captureStill()` implementation (the `composite`-stage tap executor,
+ * docs/internal/engine/RENDERER_CONTRACT.md §1a.4).
+ *
+ * Peer of `renderCapabilities-common.js` in this directory, and it exists for the same
+ * reason: without it, `p5-provider.js` and `three-provider.js` would each carry their own
+ * row-order flip, their own bag-shape assembly, and their own "is this buffer actually
+ * non-blank?" check — three chances for the two backends to disagree about what a still
+ * IS. A capture that silently differs per backend is exactly the corrupted-corpus failure
+ * the provenance contract exists to prevent, so the parts that are NOT backend-specific
+ * live here once, and each provider contributes only its own irreducible readback call.
+ *
+ * ── Layer 1: API contract ────────────────────────────────────────────────────
+ *
+ * Three pure, module-level free functions — no live WebGL/THREE/p5 instance is captured;
+ * every backend handle arrives as an ARGUMENT, which is what keeps the readback logic
+ * unit-testable in plain Node (a `Uint8Array` and a `{ readPixels }` object are enough).
+ *
+ * `flipRowsToTopLeft(src, width, height)` → `Uint8ClampedArray`
+ *   Reverse the ROW order of an RGBA8 buffer. WebGL's `readPixels` origin is BOTTOM-LEFT;
+ *   the contract's origin is TOP-LEFT (§1a.4), so a GL-based provider flips and a 2D-canvas
+ *   provider (already top-left) does not. This is the one place the flip is written: an
+ *   inverted still is invisible to every non-visual check and reads as "the physics is
+ *   upside down", which is the worst kind of wrong answer — confidently mirrored data.
+ *
+ * `captureFrom2dCanvas(canvas, meta)` → the provider bag
+ *   The 2D-canvas path (p5). `getImageData` is already RGBA, row-major, top-left, so no
+ *   flip. Reads the canvas's BACKING-STORE size (`canvas.width/height`) — never its CSS
+ *   size — because that is what `uResolution` means (§4).
+ *
+ * `captureFromGl(gl, width, height, meta)` → the provider bag
+ *   The WebGL path (three). `readPixels` into a fresh `Uint8Array`, then ONE
+ *   `flipRowsToTopLeft`. The CALLER must have re-rendered its retained scene in the SAME
+ *   JS task immediately before calling this (see the readback guarantee below).
+ *
+ * `meta` (both capture fns) carries the fields only the PROVIDER is the authority for:
+ *   `{ cssWidth, cssHeight, physicsW, physicsH, filtersApplied, renderBaseCanvas,
+ *      filterTime, composited }`.
+ *   `filtersApplied` MUST come from the provider's own ORDERED `_filters` list — never
+ *   from the runner's unordered `_activeFilters` map, which is also blind to a direct BYO
+ *   `prov.filter()` call and would therefore lie for exactly the BYO case.
+ *   `filterTime` is the `uTime` the provider fed its filter passes (the contract's
+ *   `filterTime` of the rendered tick): a number when `filtersApplied` is non-empty, null
+ *   when it is empty.
+ *   `composited` is the TickData the provider last drew (its own retained `_lastTickData`);
+ *   its `universeData.tick` becomes the bag's `renderedTick` — the provider's REPORT of which
+ *   tick these pixels are, which the tap mechanism compares against its stamp.
+ *
+ * The returned bag is the §1a.4 provider shape:
+ *   `{ pixels, width, height, cssWidth, cssHeight, physicsW, physicsH,
+ *      filtersApplied, renderBaseCanvas, filterTime, renderedTick }`
+ * The RUNNER then normalizes it into the generic tap bag (`lib/shim/render/render-stages`
+ * `normalizeStill`, where `pixels` becomes the stage-agnostic `data` payload and the
+ * dispatcher adds `stage`/`tick`/`pose`/`composedOf`/`renderOptions`). Providers never
+ * import the shim — a BYO renderer's whole capture burden stays ONE method.
+ *
+ * ── The readback-correctness guarantee (the hard sentence) ────────────────────
+ *
+ * A returned bag is the FULL composited canvas — all three layers (§8) plus every active
+ * filter pass (§4) — as of the last completed `renderTick`/`repaint`. The WebGL trap:
+ * `three-provider.js` constructs its `WebGLRenderer` WITHOUT `preserveDrawingBuffer`, so a
+ * `readPixels` in a LATER task reads a CLEARED buffer and would return an all-black still.
+ * The compliant GL path therefore re-renders its RETAINED scene (the scene graph and the
+ * filter passes both persist between ticks) and reads back IN THE SAME JS TASK. Flipping
+ * `preserveDrawingBuffer:true` globally is the WRONG fix: it taxes every frame to subsidise
+ * occasional captures and leaves the guarantee implicit rather than enforced.
+ * `assertNonBlank` below is the belt-and-braces check that this actually happened — a
+ * uniformly-zero buffer THROWS rather than being handed back as evidence.
+ *
+ * ── FAIL-LOUD, never a null image ────────────────────────────────────────────
+ *
+ * Every function here throws on a bad input (absent canvas, no 2D context, no GL context,
+ * a length mismatch, a uniformly-blank readback). A capability that is ABSENT hides an
+ * affordance (the `move()` precedent — a host capability-checks and shows no button); a
+ * capability that is PRESENT but cannot honor its guarantee THROWS. A black still from a
+ * cleared framebuffer is a lie in the product surface, the same violation class as a
+ * hardcoded backend label (dep-map rule 4).
+ *
+ * ── Module format: an ES module, like every peer under lib/frqtl/compat/renderer/ ──
+ *
+ * ── Layer 2: physics behaviour ───────────────────────────────────────────────
+ * ZERO physics. This is the output boundary reading its own output: nothing here touches a
+ * frame, a dimension or a tick, so no canonical-bench golden can move because of it.
+ */
+
+
+
+function _fail(msg) {
+    throw new Error('[captureStill] ' + msg + ' (FAIL-LOUD — never a null or blank still.)');
+}
+
+/**
+ * Reverse the ROW order of an RGBA8 buffer (bottom-left origin → top-left origin).
+ *
+ * @param {Uint8Array|Uint8ClampedArray|Array<number>} src — RGBA8, `width*height*4` long
+ * @param {number} width  — pixels per row
+ * @param {number} height — number of rows
+ * @returns {Uint8ClampedArray} a NEW buffer, rows reversed, channels untouched
+ * @throws {Error} on a length that is not exactly width*height*4
+ */
+function flipRowsToTopLeft(src, width, height) {
+    if (!src || typeof src.length !== 'number') { _fail('flipRowsToTopLeft: src is not an indexed buffer'); }
+    var stride = width * 4;
+    if (src.length !== stride * height) {
+        _fail('flipRowsToTopLeft: buffer length ' + src.length + ' != width*height*4 (' +
+              width + '*' + height + '*4 = ' + (stride * height) + ')');
+    }
+    var out = new Uint8ClampedArray(src.length);
+    for (var row = 0; row < height; row++) {
+        var from = (height - 1 - row) * stride;
+        for (var i = 0; i < stride; i++) { out[row * stride + i] = src[from + i]; }
+    }
+    return out;
+}
+
+/**
+ * Throw if a readback is uniformly one value across every byte.
+ *
+ * A composited scene with a background and at least one quantum is never uniform, so a
+ * uniform buffer means the readback happened against a cleared/unbound framebuffer — the
+ * black-still failure mode. This is checked HERE (not in the test) so a broken realm path
+ * reports itself instead of quietly feeding a training corpus.
+ *
+ * @param {Uint8Array|Uint8ClampedArray} buf
+ * @param {string} where — the provider/path name for the message
+ */
+function assertNonBlank(buf, where) {
+    if (!buf.length) { _fail(where + ': readback returned an EMPTY buffer'); }
+    var first = buf[0];
+    for (var i = 1; i < buf.length; i++) {
+        if (buf[i] !== first) { return; }
+    }
+    _fail(where + ': readback is UNIFORMLY ' + first + ' across every byte — the buffer was ' +
+          'cleared or unbound. A GL provider must re-render its retained scene and read back ' +
+          'in the SAME JS task (no preserveDrawingBuffer)');
+}
+
+/** Validate + copy the provider-authored provenance half of the bag. */
+function _meta(meta, width, height) {
+    meta = meta || {};
+    if (!Array.isArray(meta.filtersApplied)) {
+        _fail('meta.filtersApplied must be the provider\'s ORDERED filter-name array (its own ' +
+              '_filters list is the one authority — never the runner\'s unordered _activeFilters map)');
+    }
+    // physicsW/H is the UNIVERSE-MAPPING half of provenance: it is what lets a consumer turn a
+    // pixel back into a physics coordinate. Defaulting it to the buffer dims INVENTED a
+    // universe size — silently correct only when the canvas happens to be 1:1 with the
+    // universe, and a mislabeled corpus row otherwise. There is no honest fallback, so this
+    // throws.
+    if (!(typeof meta.physicsW === 'number' && meta.physicsW > 0) ||
+        !(typeof meta.physicsH === 'number' && meta.physicsH > 0)) {
+        _fail('meta.physicsW/physicsH must be the POSITIVE physics-canvas dimensions this ' +
+              'buffer maps from — they are the universe-mapping half of provenance and cannot ' +
+              'be guessed from the buffer size (that is only right at 1:1). Got ' +
+              String(meta.physicsW) + 'x' + String(meta.physicsH));
+    }
+    // renderedTick is the TICK half of provenance, reported by the one party that knows which
+    // TickData these pixels were drawn from. The tap stamps `tick` off the LOOP, and the loop
+    // may have ticked past the last draw (a batched rAF frame renders only its last tick), so
+    // without this report nothing could tell a still labelled t from pixels of t+k.
+    var composited = meta.composited;
+    var renderedTick = composited && composited.universeData && composited.universeData.tick;
+    if (!(typeof renderedTick === 'number' && isFinite(renderedTick))) {
+        _fail('meta.composited must be the TickData this provider last drew (its retained ' +
+              '_lastTickData, carrying universeData.tick) — nothing has been composited, so ' +
+              'there is no tick these pixels could be labelled with');
+    }
+    // filterTime is the CLOCK half of a filtered still's provenance: a filter that animates on
+    // `uTime` draws different pixels at a different time, so a filtered still without the time
+    // it drew with is not regenerable. A filter ran ⇔ a time was fed.
+    var filterTime = (meta.filterTime === undefined) ? null : meta.filterTime;
+    var filtered = meta.filtersApplied.length > 0;
+    if (filtered ? !(typeof filterTime === 'number' && isFinite(filterTime)) : filterTime !== null) {
+        _fail('meta.filterTime must be the finite uTime the filter passes drew with when ' +
+              'filtersApplied is non-empty, and null when it is empty (filtersApplied ' +
+              JSON.stringify(meta.filtersApplied) + ', filterTime ' + String(filterTime) + ')');
+    }
+    return {
+        renderedTick: renderedTick,
+        width:  width,
+        height: height,
+        // cssWidth/Height DO default to the buffer dims: that is the IDENTITY case (a canvas
+        // with no CSS scaling), not an invented value — and a headless capture genuinely has
+        // no CSS size to report.
+        cssWidth:  (typeof meta.cssWidth  === 'number' && meta.cssWidth  > 0) ? meta.cssWidth  : width,
+        cssHeight: (typeof meta.cssHeight === 'number' && meta.cssHeight > 0) ? meta.cssHeight : height,
+        physicsW: meta.physicsW,
+        physicsH: meta.physicsH,
+        filtersApplied: meta.filtersApplied.slice(),
+        renderBaseCanvas: (typeof meta.renderBaseCanvas === 'boolean') ? meta.renderBaseCanvas : null,
+        filterTime: filterTime
+    };
+}
+
+/**
+ * Capture from a 2D canvas (the p5 path). `getImageData` is already RGBA, row-major,
+ * TOP-LEFT — no flip.
+ *
+ * @param {HTMLCanvasElement} canvas
+ * @param {object} meta — see the module docstring
+ * @returns {object} the §1a.4 provider bag
+ */
+function captureFrom2dCanvas(canvas, meta) {
+    if (!canvas) {
+        _fail('no canvas to read — captureStill() was called before init() created one');
+    }
+    var ctx = (typeof canvas.getContext === 'function') ? canvas.getContext('2d') : null;
+    if (!ctx || typeof ctx.getImageData !== 'function') {
+        _fail('the canvas has no readable 2D context (getImageData unavailable)');
+    }
+    var w = canvas.width, h = canvas.height;
+    if (!(w > 0 && h > 0)) { _fail('canvas backing store is ' + w + 'x' + h); }
+    var img = ctx.getImageData(0, 0, w, h);
+    if (!img || !img.data || img.data.length !== w * h * 4) {
+        _fail('getImageData returned ' + (img && img.data ? img.data.length : 'nothing') +
+              ' bytes, expected ' + (w * h * 4));
+    }
+    assertNonBlank(img.data, '2d-canvas');
+    var bag = _meta(meta, w, h);
+    // Copy: the ImageData buffer is owned by the context and may be reused.
+    bag.pixels = new Uint8ClampedArray(img.data);
+    return bag;
+}
+
+/**
+ * Capture from a WebGL context (the three path). The caller MUST have re-rendered its
+ * retained scene in this SAME JS task immediately before calling this.
+ *
+ * @param {WebGLRenderingContext|WebGL2RenderingContext} gl
+ * @param {number} width  — framebuffer width in backing-store pixels
+ * @param {number} height — framebuffer height in backing-store pixels
+ * @param {object} meta — see the module docstring
+ * @returns {object} the §1a.4 provider bag (rows already flipped to top-left)
+ */
+function captureFromGl(gl, width, height, meta) {
+    if (!gl || typeof gl.readPixels !== 'function') {
+        _fail('no WebGL context to read — captureStill() was called before init(), or the ' +
+              'context was lost');
+    }
+    if (!(width > 0 && height > 0)) { _fail('GL framebuffer is ' + width + 'x' + height); }
+    var raw = new Uint8Array(width * height * 4);
+    gl.readPixels(0, 0, width, height, gl.RGBA, gl.UNSIGNED_BYTE, raw);
+    assertNonBlank(raw, 'webgl');
+    var bag = _meta(meta, width, height);
+    bag.pixels = flipRowsToTopLeft(raw, width, height);
+    return bag;
+}
+
+// ── Export ────────────────────────────────────────────────────────────────────
+
+export {
+    flipRowsToTopLeft,
+    assertNonBlank,
+    captureFrom2dCanvas,
+    captureFromGl
+};

package/dist/frqtl/compat/renderer/display-slot.js

@@ -0,0 +1,96 @@
+/* Copyright 2023-2026 by Essam Abadir */
+
+/**
+ * display-slot.js — THE DISPLAY SLOT: the ONE answer to "which provider owns the display".
+ *
+ * ── The ratified rule (RENDERER_CONTRACT §9 + §1a.5, CEO 2026-08-01) ─────────
+ *
+ *   The DISPLAY provider is boot-fixed; OBSERVERS are live.
+ *
+ * Exactly one `RendererProvider` — the display provider — owns the canvas, the camera and
+ * `projection`; swapping it is a reload. N observers (non-interactive consumers of the frame
+ * stream) are addable and removable at any time; an observer owns no canvas, no camera and no
+ * projection. This module holds the DISPLAY half of that rule and nothing else: there is no
+ * observer registry here, and adding one before its first real caller is the speculative
+ * registry §10 bans.
+ *
+ * ── What this slot is, and what it is NOT ───────────────────────────────────
+ *
+ * It is KNOWLEDGE, not ownership. The provider still creates and owns its own canvas in its
+ * own `init()` — the frozen §1 contract is untouched, and the literal canvas-element handoff
+ * was VETOED (one canvas owns one rendering context; p5 cannot adopt a foreign element). The
+ * slot records WHICH provider that is, so every consumer asks one place instead of reading a
+ * bare global that anything could assign.
+ *
+ * ── Why it lives in the RENDERER layer and not on the capture instrument ────
+ *
+ * The boot order forces it. The boot module (`experiments/_shared/boot.js`) sets it while the
+ * renderer boots, BEFORE the game layer constructs anything, and the three.js path registers
+ * ASYNC — later still. A slot that lived in a game-layer file would not exist when its one
+ * writer needs it. The RENDERER layer is also where
+ * `CANONICAL_STACK_DIAGRAM` already puts the renderer pluggable surface, so this is the
+ * authority table's own home rather than a new one. The capture instrument READS the slot
+ * (through its `providerGetter` binding); it does not own it — an instrument is per-runner
+ * and the display is per-process.
+ *
+ * ── The name chain (truth in labeling) ──────────────────────────────────────
+ *
+ * The boot authority's renderer NAME (`bootRealm({ renderer })` / `?renderer=`) heads ONE chain:
+ *   boot authority → `build.renderer` provenance
+ *   boot authority → this slot's `name()`
+ * The slot FERRIES the boot authority's name; it never re-derives one. A slot that could
+ * answer differently from `build.renderer` is the truth-in-labeling failure (dep-map rule 4),
+ * so `display-slot.test.mjs` gates `name()` against the booted renderer after a real boot.
+ *
+ * ── Boot-fixed is a SEMANTIC, not a write-once lock ─────────────────────────
+ *
+ * `set()` deliberately does NOT throw on a second call. The notebook realm switches a cell
+ * between p5 and three by re-invoking the boot module's `selectRenderer(name)` — that IS the
+ * reload the rule describes (a new renderer session, a new scene identity), not a hot swap of
+ * a live scene. Locking the slot would break the realm while proving nothing: what makes the
+ * display boot-fixed is that `projection` and `build.renderer` are SCENE-record fields, so a
+ * re-selection mints a new scene rather than silently re-parenting stills.
+ */
+
+
+    var _provider = null;   // the display RendererProvider instance, or null
+    var _name     = null;   // the boot authority's name it was registered under
+
+    /**
+     * Register the booted display provider. Called by whichever boot ran the selection
+     * (the boot module's `selectRenderer`, a test harness declaring a renderer the way a
+     * page does).
+     *
+     * @param {object} provider — the `RendererProvider` instance. The slot validates only
+     *   that there IS one: provider SHAPE has an authority already —
+     *   `renderer-provider-contract.js`'s `validateRendererProvider` on the BYO path — and a second
+     *   shape check here would be a second authority that could disagree with it (and would
+     *   silently tighten what the shipped providers are allowed to be).
+     * @param {string} [name] — the boot authority's renderer name,
+     *   FERRIED. Never re-derived here.
+     * @returns {object} the provider, so a caller can register and assign in one expression.
+     */
+    function set(provider, name) {
+        if (!provider || typeof provider !== 'object') {
+            throw new Error('[FrqtlDisplay.set] the display provider must be a ' +
+                'RendererProvider instance. Got: ' + String(provider) + '. (FAIL-LOUD — never ' +
+                'a display slot holding nothing while a page believes it has a renderer.)');
+        }
+        _provider = provider;
+        _name     = (name === undefined || name === null) ? null : String(name);
+        return provider;
+    }
+
+    /** @returns {object|null} the display provider, or null before boot completes. */
+    function get() { return _provider; }
+
+    /** @returns {string|null} the boot authority's name this provider was registered under. */
+    function name() { return _name; }
+
+    /**
+     * Empty the slot. For teardown ONLY (a test restoring its host, a realm disposing a
+     * session) — never a way to "unset" a display mid-scene.
+     */
+    function clear() { _provider = null; _name = null; }
+
+export { set, get, name, clear };

package/dist/frqtl/compat/renderer/lo-drawn-center.js

@@ -0,0 +1,231 @@
+/* Copyright 2023-2026 by Essam Abadir */
+
+/**
+ * lo-drawn-center.js — THE authority for where a LargeObject rect is DRAWN: its center point.
+ *
+ * Peer of `orbit-bag.js`: a shared contract-half with no geometry of its own beyond one rule, so
+ * the fact has ONE owner. Its consumers are the three.js provider (it places each LO mesh at this
+ * point and paints the shadow-surround from its volume) and `FrqtlApp` (the 3D mouse pick aims
+ * at the centre; the aim ray tests the volume). Two
+ * derivations of the one fact is the drift this file exists to make impossible — a pick aimed at
+ * a different point than the mesh is drawn at selects the wrong object silently.
+ *
+ * ── The rule ─────────────────────────────────────────────────────────────────
+ *
+ * An LO rect is corner-mode (`left`/`top` are the near corner, never a center — the LargeObject
+ * convention). A 6-element rect (`{left, top, z, w, h, d}`) also carries `z`, the NEAR-face corner
+ * on the z axis, so its z-center is `z + d/2`, with `d` defaulting to `w` exactly as the engine's
+ * z-capable rectangle does. A legacy 4-element rect has no `z`: it sits at z-center 0.
+ *
+ *   drawnCenter(rect) → [left + w/2, top + h/2, (z present) ? z + (d ?? w)/2 : 0]
+ *   hasZ(rect)        → whether the rect carries z — the ONE z-presence test (consumers never re-derive it)
+ *
+ * Its INVERSE places the same-sized rect at a centre (a grabbed wall carried by the camera):
+ *
+ *   rectAtCenter(rect, [cx, cy, cz]) → the WRITE-wire array, the rect's own form:
+ *     z present → [cx − w/2, cy − h/2, cz − D/2, w, h, D] with D = d ?? w STATED (so the written
+ *                 rect reads back through drawnCenter to the centre it was placed at);
+ *     z absent  → [cx − w/2, cy − h/2, w, h], and cz must be 0 — a z-less rect sits at z-centre
+ *                 0 by the rule above, so any other cz THROWS rather than being dropped.
+ *
+ * ── The drawn VOLUME and the center-ray hit (STUDIO's aim) ──────────────────────
+ *
+ * The same rect also owns the VOLUME the aim ray tests and the shadow-surround paints, so the
+ * thing you aim at, the thing that lights up and the mesh are one geometry:
+ *
+ *   drawnVolume({rect, orientationDeg?, pitchDeg?}) → a BOX: centre = drawnCenter(rect), half
+ *     extents [w/2, h/2, D/2] with D = the rect's z-extent (d ?? w when z is present — the same
+ *     default the centre uses — else 0, a flat legacy rect), turned by the shell's own rotation
+ *     (yaw about world z, then pitch about the plate's own long axis: Rz(yaw)·Ry(pitch), the
+ *     renderer's 'ZYX' order).
+ *   drawnVolume({center, radius}) → a SPHERE (a centre-only target, e.g. an emitter).
+ *   rayIntersect(origin, dir, volume, margin?) → the ENTRY ray parameter t ≥ 0 (0 when the
+ *     origin is inside), or null for a miss / a volume wholly behind the origin. `margin`
+ *     inflates the volume on every side first, so a thin wall is aimable.
+ *   firstHit(origin, dir, volumes, margin?) → {index, t} | null — THE hover rule: the nearest
+ *     entry wins, except that a smaller volume whose entry point lies inside the winner's
+ *     (a volume nested in another along the ray) wins over it.
+ *   volumeContains(volume, point, margin?) — the containment test firstHit uses.
+ *
+ * ── Layer 2: physics behaviour ───────────────────────────────────────────────
+ * ZERO physics. This reads a rect the engine already published; it moves no frame and no LO.
+ */
+
+
+/**
+ * hasZ(rect) — whether the rect carries a z (a z-capable / 6-element rect). THE one z-presence test
+ * every consumer asks (the carry's flat/z-held rule, a part's 6-on-flat refusal), never re-derived.
+ * @param {{z?:number}} rect @returns {boolean}
+ */
+function hasZ(rect) {
+    return typeof rect.z === 'number';
+}
+
+/**
+ * @param {{left:number, top:number, w:number, h:number, z?:number, d?:number}} rect
+ * @returns {number[]} `[cx, cy, cz]` — the center the renderer draws the rect's box at.
+ */
+function drawnCenter(rect) {
+    var cz = hasZ(rect)
+        ? rect.z + ((typeof rect.d === 'number') ? rect.d : rect.w) / 2
+        : 0;
+    return [rect.left + rect.w / 2, rect.top + rect.h / 2, cz];
+}
+
+/**
+ * @param {{left:number, top:number, w:number, h:number, z?:number, d?:number}} rect — the rect
+ *   being placed (its w/h and z-extent are kept).
+ * @param {number[]} center — `[cx, cy, cz]` (cz may be omitted for a z-less rect).
+ * @returns {number[]} the write-wire array `[l, t, z, w, h, d]` (z present) or `[l, t, w, h]`.
+ */
+function rectAtCenter(rect, center) {
+    var cz = (typeof center[2] === 'number') ? center[2] : 0;
+    if (hasZ(rect)) {
+        var D = _zExtent(rect);
+        return [center[0] - rect.w / 2, center[1] - rect.h / 2, cz - D / 2, rect.w, rect.h, D];
+    }
+    if (cz !== 0) {
+        throw new RangeError('[LoDrawnCenter.rectAtCenter] a z-less rect sits at z-centre 0 and cannot ' +
+            'be placed at z = ' + cz + ' — place it at cz 0, or give the rect an explicit z. (FAIL-LOUD.)');
+    }
+    return [center[0] - rect.w / 2, center[1] - rect.h / 2, rect.w, rect.h];
+}
+
+var DEG = Math.PI / 180;
+
+/** The rect's z-extent: d ?? w when it carries z (the engine's z-capable rectangle), else 0. */
+function _zExtent(rect) {
+    if (!hasZ(rect)) { return 0; }
+    return (typeof rect.d === 'number') ? rect.d : rect.w;
+}
+
+/**
+ * @param {{rect:object, orientationDeg?:number, pitchDeg?:number}|{center:number[], radius:number}} src
+ * @returns {{kind:'box', center:number[], half:number[], yawDeg:number, pitchDeg:number}
+ *          |{kind:'sphere', center:number[], radius:number}}
+ */
+function drawnVolume(src) {
+    if (src && src.rect) {
+        var r = src.rect;
+        return {
+            kind: 'box',
+            center: drawnCenter(r),
+            half: [r.w / 2, r.h / 2, _zExtent(r) / 2],
+            yawDeg: (typeof src.orientationDeg === 'number') ? src.orientationDeg : 0,
+            pitchDeg: (typeof src.pitchDeg === 'number') ? src.pitchDeg : 0
+        };
+    }
+    if (src && Array.isArray(src.center) && typeof src.radius === 'number') {
+        var c = src.center;
+        return { kind: 'sphere', center: [c[0], c[1], (typeof c[2] === 'number') ? c[2] : 0], radius: src.radius };
+    }
+    throw new TypeError('[LoDrawnCenter.drawnVolume] needs {rect} (an LO) or {center, radius} (a ' +
+        'centre-only target); got ' + JSON.stringify(src) + '. (FAIL-LOUD.)');
+}
+
+/** A world vector expressed in the box's local frame: Rᵀ·v with R = Rz(yaw)·Ry(pitch). */
+function _toLocal(box, v) {
+    var a = box.yawDeg * DEG, b = box.pitchDeg * DEG;
+    var ca = Math.cos(a), sa = Math.sin(a), cb = Math.cos(b), sb = Math.sin(b);
+    return [
+        ca * cb * v[0] + sa * cb * v[1] - sb * v[2],
+        -sa * v[0] + ca * v[1],
+        ca * sb * v[0] + sa * sb * v[1] + cb * v[2]
+    ];
+}
+
+function _sub(a, b) { return [a[0] - b[0], a[1] - b[1], a[2] - b[2]]; }
+
+/**
+ * @param {number[]} origin @param {number[]} dir (need not be unit; t is in units of |dir|)
+ * @param {object} volume — a drawnVolume result. @param {number} [margin=0] world px.
+ * @returns {number|null}
+ */
+function rayIntersect(origin, dir, volume, margin) {
+    var m = (typeof margin === 'number') ? margin : 0;
+    if (volume.kind === 'sphere') {
+        var R = volume.radius + m;
+        var oc = _sub(origin, volume.center);
+        var A = dir[0] * dir[0] + dir[1] * dir[1] + dir[2] * dir[2];
+        var B = 2 * (oc[0] * dir[0] + oc[1] * dir[1] + oc[2] * dir[2]);
+        var C = oc[0] * oc[0] + oc[1] * oc[1] + oc[2] * oc[2] - R * R;
+        var disc = B * B - 4 * A * C;
+        if (!(A > 0) || disc < 0) { return null; }
+        var sq = Math.sqrt(disc);
+        var t0 = (-B - sq) / (2 * A), t1 = (-B + sq) / (2 * A);
+        if (t1 < 0) { return null; }
+        return (t0 > 0) ? t0 : 0;
+    }
+    if (volume.kind === 'box') {
+        var o = _toLocal(volume, _sub(origin, volume.center));
+        var d = _toLocal(volume, dir);
+        var tNear = -Infinity, tFar = Infinity;
+        for (var i = 0; i < 3; i++) {
+            var h = volume.half[i] + m;
+            if (Math.abs(d[i]) < 1e-12) {
+                if (o[i] < -h || o[i] > h) { return null; }   // parallel to this slab, outside it
+                continue;
+            }
+            var ta = (-h - o[i]) / d[i], tb = (h - o[i]) / d[i];
+            if (ta > tb) { var tmp = ta; ta = tb; tb = tmp; }
+            if (ta > tNear) { tNear = ta; }
+            if (tb < tFar) { tFar = tb; }
+            if (tNear > tFar) { return null; }
+        }
+        if (tFar < 0) { return null; }
+        return (tNear > 0) ? tNear : 0;
+    }
+    throw new TypeError('[LoDrawnCenter.rayIntersect] unknown volume kind ' + String(volume && volume.kind) +
+        ' — volumes come from drawnVolume(). (FAIL-LOUD.)');
+}
+
+/** Whether `point` lies inside `volume` (inflated by `margin`). */
+function volumeContains(volume, point, margin) {
+    var m = (typeof margin === 'number') ? margin : 0;
+    var p = _sub(point, volume.center);
+    if (volume.kind === 'sphere') {
+        var R = volume.radius + m;
+        return p[0] * p[0] + p[1] * p[1] + p[2] * p[2] <= R * R + 1e-9;
+    }
+    var l = _toLocal(volume, p);
+    for (var i = 0; i < 3; i++) { if (Math.abs(l[i]) > volume.half[i] + m + 1e-9) { return false; } }
+    return true;
+}
+
+/** The inflated volume's size — the nested-volume tie-break compares it. */
+function _size(volume, m) {
+    if (volume.kind === 'sphere') { var R = volume.radius + m; return R * R * R * 4.18879; }
+    return 8 * (volume.half[0] + m) * (volume.half[1] + m) * (volume.half[2] + m);
+}
+
+/**
+ * @param {number[]} origin @param {number[]} dir @param {object[]} volumes @param {number} [margin=0]
+ * @returns {{index:number, t:number}|null}
+ */
+function firstHit(origin, dir, volumes, margin) {
+    var m = (typeof margin === 'number') ? margin : 0;
+    var hits = [];
+    for (var i = 0; i < volumes.length; i++) {
+        var t = rayIntersect(origin, dir, volumes[i], m);
+        if (t !== null) { hits.push({ index: i, t: t }); }
+    }
+    if (!hits.length) { return null; }
+    hits.sort(function (a, b) { return a.t - b.t; });
+    var best = hits[0];
+    for (var k = 1; k < hits.length; k++) {
+        var h = hits[k], vb = volumes[best.index], vh = volumes[h.index];
+        var entry = [origin[0] + dir[0] * h.t, origin[1] + dir[1] * h.t, origin[2] + dir[2] * h.t];
+        if (volumeContains(vb, entry, m) && _size(vh, m) < _size(vb, m)) { best = h; }
+    }
+    return best;
+}
+
+export {
+    drawnCenter,
+    rectAtCenter,
+    hasZ,
+    drawnVolume,
+    rayIntersect,
+    volumeContains,
+    firstHit
+};