@woosh/meep-engine 3.23.0 → 3.25.0

package/src/shade/renderer/geometry/virtual/runtime/layout/VGEO_QUEUE_ITEM_WORDS.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Words in one traversal queue item: `instance slot`, `page row`, `target`, `first cluster`.
+ *
+ * `target` is a node index, or a group index with {@link VGEO_QUEUE_TARGET_GROUP_BIT} set. One
+ * queue, one kernel, two shapes — which is what lets a node leaf hand off its clusters in bounded
+ * chunks rather than walking up to four groups of four thousand in the lane that popped it.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ * @type {number}
+ */
+export const VGEO_QUEUE_ITEM_WORDS: number;
+//# sourceMappingURL=VGEO_QUEUE_ITEM_WORDS.d.ts.map

package/src/shade/renderer/geometry/virtual/runtime/layout/VGEO_QUEUE_ITEM_WORDS.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"VGEO_QUEUE_ITEM_WORDS.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/geometry/virtual/runtime/layout/VGEO_QUEUE_ITEM_WORDS.js"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,oCAFU,MAAM,CAEuB"}

package/src/shade/renderer/geometry/virtual/runtime/layout/VGEO_QUEUE_ITEM_WORDS.js

@@ -0,0 +1,12 @@
+/**
+ * Words in one traversal queue item: `instance slot`, `page row`, `target`, `first cluster`.
+ *
+ * `target` is a node index, or a group index with {@link VGEO_QUEUE_TARGET_GROUP_BIT} set. One
+ * queue, one kernel, two shapes — which is what lets a node leaf hand off its clusters in bounded
+ * chunks rather than walking up to four groups of four thousand in the lane that popped it.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ * @type {number}
+ */
+export const VGEO_QUEUE_ITEM_WORDS = 4;

package/src/shade/renderer/geometry/virtual/runtime/layout/VGEO_QUEUE_TARGET_GROUP_BIT.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Set in a queue item's `target` when it names a group to evaluate rather than a node to descend.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ * @type {number}
+ */
+export const VGEO_QUEUE_TARGET_GROUP_BIT: number;
+//# sourceMappingURL=VGEO_QUEUE_TARGET_GROUP_BIT.d.ts.map

package/src/shade/renderer/geometry/virtual/runtime/layout/VGEO_QUEUE_TARGET_GROUP_BIT.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"VGEO_QUEUE_TARGET_GROUP_BIT.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/geometry/virtual/runtime/layout/VGEO_QUEUE_TARGET_GROUP_BIT.js"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,0CAFU,MAAM,CAEsC"}

package/src/shade/renderer/geometry/virtual/runtime/layout/VGEO_QUEUE_TARGET_GROUP_BIT.js

@@ -0,0 +1,8 @@
+/**
+ * Set in a queue item's `target` when it names a group to evaluate rather than a node to descend.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ * @type {number}
+ */
+export const VGEO_QUEUE_TARGET_GROUP_BIT = 0x80000000;

package/src/shade/renderer/geometry/virtual/runtime/layout/VGEO_WANT_WORDS.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Words in one want record: `source page row`, `child ref`, `child page index`, `priority bits`.
+ *
+ * The **source** page row is in there on purpose. A want that named only the page wanted would
+ * leave `VGEO_FORMAT.md` §10's in-flight pin unclosable — "a fetch discovered through parent page
+ * P pins P until the child installs" needs somebody to say which P, and the format deliberately
+ * stores parent *counts* rather than parent references, so nothing but the cut can. It also
+ * resolves the byte range without a directory: the source page's child table holds
+ * `frame_offset`, `fetch_size` and `decoded_size` at exactly `child ref`.
+ *
+ * `priority bits` is the clamped cluster's projected error as an f32 bit pattern — pixels past the
+ * threshold, and therefore comparable across assets by construction, which is what
+ * `VGeoResidencyManager`'s single global queue needs and what no per-reader queue could claim.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ * @type {number}
+ */
+export const VGEO_WANT_WORDS: number;
+//# sourceMappingURL=VGEO_WANT_WORDS.d.ts.map

package/src/shade/renderer/geometry/virtual/runtime/layout/VGEO_WANT_WORDS.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"VGEO_WANT_WORDS.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/geometry/virtual/runtime/layout/VGEO_WANT_WORDS.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AACH,8BAFU,MAAM,CAEiB"}

package/src/shade/renderer/geometry/virtual/runtime/layout/VGEO_WANT_WORDS.js

@@ -0,0 +1,19 @@
+/**
+ * Words in one want record: `source page row`, `child ref`, `child page index`, `priority bits`.
+ *
+ * The **source** page row is in there on purpose. A want that named only the page wanted would
+ * leave `VGEO_FORMAT.md` §10's in-flight pin unclosable — "a fetch discovered through parent page
+ * P pins P until the child installs" needs somebody to say which P, and the format deliberately
+ * stores parent *counts* rather than parent references, so nothing but the cut can. It also
+ * resolves the byte range without a directory: the source page's child table holds
+ * `frame_offset`, `fetch_size` and `decoded_size` at exactly `child ref`.
+ *
+ * `priority bits` is the clamped cluster's projected error as an f32 bit pattern — pixels past the
+ * threshold, and therefore comparable across assets by construction, which is what
+ * `VGeoResidencyManager`'s single global queue needs and what no per-reader queue could claim.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ * @type {number}
+ */
+export const VGEO_WANT_WORDS = 4;

package/src/shade/renderer/geometry/virtual/runtime/vgeo_runtime_meshlet_batch.d.ts

@@ -0,0 +1,23 @@
+/**
+ * A decoded page, as the meshlet pool takes it.
+ *
+ * `VGEO_FORMAT.md` §8 pins the bargain this function collects on: the payload block is
+ * **byte-compatible** with `GPUMeshletManager`'s data pool, so residency is a copy and the 40-byte
+ * metadata rows are a pack step — `aabb` becomes `bounds_box`, the u8 counts widen to u32,
+ * `encoding_flags` passes through, and `address` is the cluster's payload offset in words, which
+ * the manager then biases by wherever it put the data.
+ *
+ * The one real cost is that copy. `writeBuffer` takes an `ArrayBuffer` and the payload is a window
+ * into the page's decoded bytes, so a page install allocates and copies its payload section once.
+ * That is the same order of work the decode already did, and the alternative — handing the manager
+ * a view and asking it to honour the offset — is a change to a class four other paths share.
+ *
+ * @param {VGeoPage} page
+ * @returns {MeshletBatch} ready for `GPUMeshletManager.add_batch`
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function vgeo_runtime_meshlet_batch(page: VGeoPage): MeshletBatch;
+import { MeshletBatch } from "../../meshlet/MeshletBatch.js";
+//# sourceMappingURL=vgeo_runtime_meshlet_batch.d.ts.map

package/src/shade/renderer/geometry/virtual/runtime/vgeo_runtime_meshlet_batch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vgeo_runtime_meshlet_batch.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/geometry/virtual/runtime/vgeo_runtime_meshlet_batch.js"],"names":[],"mappings":"AASA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,4DALa,YAAY,CA6CxB;6BA9D4B,+BAA+B"}

package/src/shade/renderer/geometry/virtual/runtime/vgeo_runtime_meshlet_batch.js

@@ -0,0 +1,70 @@
+import { assert } from "../../../../../core/assert.js";
+import { BinaryBuffer } from "../../../../../core/binary/BinaryBuffer.js";
+import { platform_compute_endianness } from "../../../../../core/binary/platform_compute_endianness.js";
+import { write_wgsl_type_value } from "../../../shader/type/serde/write_gpu_typed_buffer.js";
+import {
+    MESHLET_METADATA_STRUCT
+} from "../../meshlet/encoding/MESHLET_METADATA_STRUCT.js";
+import { MeshletBatch } from "../../meshlet/MeshletBatch.js";
+
+/**
+ * A decoded page, as the meshlet pool takes it.
+ *
+ * `VGEO_FORMAT.md` §8 pins the bargain this function collects on: the payload block is
+ * **byte-compatible** with `GPUMeshletManager`'s data pool, so residency is a copy and the 40-byte
+ * metadata rows are a pack step — `aabb` becomes `bounds_box`, the u8 counts widen to u32,
+ * `encoding_flags` passes through, and `address` is the cluster's payload offset in words, which
+ * the manager then biases by wherever it put the data.
+ *
+ * The one real cost is that copy. `writeBuffer` takes an `ArrayBuffer` and the payload is a window
+ * into the page's decoded bytes, so a page install allocates and copies its payload section once.
+ * That is the same order of work the decode already did, and the alternative — handing the manager
+ * a view and asking it to honour the offset — is a change to a class four other paths share.
+ *
+ * @param {VGeoPage} page
+ * @returns {MeshletBatch} ready for `GPUMeshletManager.add_batch`
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function vgeo_runtime_meshlet_batch(page) {
+    assert.defined(page, 'page');
+
+    const count = page.cluster_count;
+
+    const batch = new MeshletBatch();
+
+    batch.count = count;
+
+    batch.data_buffer = page.bytes.buffer.slice(
+        page.bytes.byteOffset + page.payload_offset,
+        page.bytes.byteOffset + page.payload_offset + page.payload_size
+    );
+
+    const metadata = BinaryBuffer.fromEndianness(platform_compute_endianness());
+
+    metadata.setCapacity(count * MESHLET_METADATA_STRUCT.size);
+
+    for (let cluster = 0; cluster < count; cluster++) {
+        write_wgsl_type_value({
+            bounds_box: page.aabb.subarray(cluster * 6, cluster * 6 + 6),
+            /*
+             Words, and relative to the page's payload section — `GPUMeshletManager` adds the
+             allocation's own offset when it uploads. Format §11.8 makes every payload offset a
+             multiple of four, so this division is exact rather than rounded.
+             */
+            address: page.cluster_payload_offset[cluster] >>> 2,
+            primitive_count: page.triangle_count[cluster],
+            vertex_count: page.vertex_count[cluster],
+            flags: page.encoding_flags[cluster],
+        }, metadata, MESHLET_METADATA_STRUCT);
+    }
+
+    // `BinaryBuffer.data` is the ArrayBuffer itself, and `setCapacity` may have rounded it up;
+    // `add_batch` reads exactly `count` records out of it, so the slice is for clarity rather than
+    // for correctness — a metadata buffer whose length says something other than what it holds is
+    // the kind of thing that is read once, wrongly, years later.
+    batch.metadata_buffer = metadata.data.slice(0, count * MESHLET_METADATA_STRUCT.size);
+
+    return batch;
+}

package/src/shade/renderer/geometry/virtual/runtime/vgeo_runtime_page_block_words.d.ts

@@ -0,0 +1,18 @@
+/**
+ * How many arena words one page's block runs to.
+ *
+ * A page is **one allocation** — `[node rows][group rows][cluster rows]`, back to back — so this is
+ * the whole of what installing it costs the arena and the whole of what evicting it returns. Every
+ * base inside the block is a count away from the block's own start, which is why a page row carries
+ * three counts and one offset and nothing can move inside a resident page.
+ *
+ * @param {number} node_count
+ * @param {number} group_count
+ * @param {number} cluster_count
+ * @returns {number} words
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function vgeo_runtime_page_block_words(node_count: number, group_count: number, cluster_count: number): number;
+//# sourceMappingURL=vgeo_runtime_page_block_words.d.ts.map

package/src/shade/renderer/geometry/virtual/runtime/vgeo_runtime_page_block_words.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vgeo_runtime_page_block_words.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/geometry/virtual/runtime/vgeo_runtime_page_block_words.js"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;GAeG;AACH,0DARW,MAAM,eACN,MAAM,iBACN,MAAM,GACJ,MAAM,CASlB"}

package/src/shade/renderer/geometry/virtual/runtime/vgeo_runtime_page_block_words.js

@@ -0,0 +1,25 @@
+import { VGEO_CLUSTER_ROW_WORDS } from "./layout/VGEO_CLUSTER_ROW_WORDS.js";
+import { VGEO_GROUP_ROW_WORDS } from "./layout/VGEO_GROUP_ROW_WORDS.js";
+import { VGEO_NODE_ROW_WORDS } from "./layout/VGEO_NODE_ROW_WORDS.js";
+
+/**
+ * How many arena words one page's block runs to.
+ *
+ * A page is **one allocation** — `[node rows][group rows][cluster rows]`, back to back — so this is
+ * the whole of what installing it costs the arena and the whole of what evicting it returns. Every
+ * base inside the block is a count away from the block's own start, which is why a page row carries
+ * three counts and one offset and nothing can move inside a resident page.
+ *
+ * @param {number} node_count
+ * @param {number} group_count
+ * @param {number} cluster_count
+ * @returns {number} words
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function vgeo_runtime_page_block_words(node_count, group_count, cluster_count) {
+    return node_count * VGEO_NODE_ROW_WORDS
+        + group_count * VGEO_GROUP_ROW_WORDS
+        + cluster_count * VGEO_CLUSTER_ROW_WORDS;
+}

package/src/shade/renderer/geometry/virtual/runtime/vgeo_runtime_page_slot_words.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Words of arena one page slot holds, for a tier built at `page_size`.
+ *
+ * The stride has to hold the widest legal page's runtime rows, and "legal" and "widest observed"
+ * are a factor of fifteen apart, so the number here is a **choice** rather than a derivation and it
+ * is worth writing down which.
+ *
+ * **The provable bound is about half the page size.** A page's decoded bytes are
+ * `56 + 32·nodes + 8·groups + 112·clusters + payload`, and its runtime rows are
+ * `32·nodes + 16·groups + 52·clusters`. Every group holds at least one cluster (format §11.1) and
+ * the node tree over `g` groups has at most `(g+2)/2` nodes, so the runtime side is at most
+ * `84·clusters + 32` against a decoded side of at least `56 + 112·clusters` — a ratio of 0.75, or
+ * 0.53 once a cluster's minimum payload is counted. A stride sized that way is correct for every
+ * container the format admits and wastes an order of magnitude on every container anyone builds.
+ *
+ * **The measured maximum is 3.9%.** A 160×80 torus built at 16, 32, 64 and 128 KB pages put its
+ * widest page's rows at 3.7%, 3.9%, 3.4% and 3.5% of the page size respectively, because a page is
+ * overwhelmingly payload: 38 clusters in a 64 KB page is 4.5 KB of records against 59 KB of
+ * vertices and indices.
+ *
+ * So this takes **an eighth of the page**, which is 3.2× the widest measured page at the tightest
+ * page size, and an install that does not fit is **refused and counted** rather than overrunning
+ * its slot — the same direction `register` takes for a container built at the wrong page size, and
+ * for the same reason: a tier that silently reconciles a size it was not built for is a tier whose
+ * pages point into each other. A caller holding an asset this refuses raises `page_slot_words`,
+ * and the refusal names the number.
+ *
+ * @param {number} page_size bytes, the container's `nominal_page_size`
+ * @returns {number} words
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function vgeo_runtime_page_slot_words(page_size: number): number;
+//# sourceMappingURL=vgeo_runtime_page_slot_words.d.ts.map

package/src/shade/renderer/geometry/virtual/runtime/vgeo_runtime_page_slot_words.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vgeo_runtime_page_slot_words.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/geometry/virtual/runtime/vgeo_runtime_page_slot_words.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,wDANW,MAAM,GACJ,MAAM,CAUlB"}

package/src/shade/renderer/geometry/virtual/runtime/vgeo_runtime_page_slot_words.js

@@ -0,0 +1,41 @@
+import { assert } from "../../../../../core/assert.js";
+
+/**
+ * Words of arena one page slot holds, for a tier built at `page_size`.
+ *
+ * The stride has to hold the widest legal page's runtime rows, and "legal" and "widest observed"
+ * are a factor of fifteen apart, so the number here is a **choice** rather than a derivation and it
+ * is worth writing down which.
+ *
+ * **The provable bound is about half the page size.** A page's decoded bytes are
+ * `56 + 32·nodes + 8·groups + 112·clusters + payload`, and its runtime rows are
+ * `32·nodes + 16·groups + 52·clusters`. Every group holds at least one cluster (format §11.1) and
+ * the node tree over `g` groups has at most `(g+2)/2` nodes, so the runtime side is at most
+ * `84·clusters + 32` against a decoded side of at least `56 + 112·clusters` — a ratio of 0.75, or
+ * 0.53 once a cluster's minimum payload is counted. A stride sized that way is correct for every
+ * container the format admits and wastes an order of magnitude on every container anyone builds.
+ *
+ * **The measured maximum is 3.9%.** A 160×80 torus built at 16, 32, 64 and 128 KB pages put its
+ * widest page's rows at 3.7%, 3.9%, 3.4% and 3.5% of the page size respectively, because a page is
+ * overwhelmingly payload: 38 clusters in a 64 KB page is 4.5 KB of records against 59 KB of
+ * vertices and indices.
+ *
+ * So this takes **an eighth of the page**, which is 3.2× the widest measured page at the tightest
+ * page size, and an install that does not fit is **refused and counted** rather than overrunning
+ * its slot — the same direction `register` takes for a container built at the wrong page size, and
+ * for the same reason: a tier that silently reconciles a size it was not built for is a tier whose
+ * pages point into each other. A caller holding an asset this refuses raises `page_slot_words`,
+ * and the refusal names the number.
+ *
+ * @param {number} page_size bytes, the container's `nominal_page_size`
+ * @returns {number} words
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function vgeo_runtime_page_slot_words(page_size) {
+    assert.isPositiveInteger(page_size, 'page_size');
+
+    // a multiple of four words, so a slot boundary is also a 16-byte boundary
+    return Math.ceil(page_size / 128) * 4;
+}

package/src/shade/renderer/geometry/virtual/runtime/vgeo_runtime_write_page_block.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Lay one decoded page's node, group and cluster rows into the arena.
+ *
+ * This is the whole of what a page install writes besides its payload, and it is deliberately a
+ * free function over two views rather than a method: the pool calls it against a mapped GPU upload
+ * range, and the agreement spec calls it against a plain array, and neither should have to own the
+ * other's machinery.
+ *
+ * **What it resolves, and why here.** A cluster's `child_ref` is an index into its page's child
+ * table, with two sentinels — `VGEO_SAME_PAGE` when the child group is in this very page, and
+ * `VGEO_NO_CHILD` for a leaf. The kernel does not see any of that: this writes a *global container
+ * page index* into every row, using the page's own index for `SAME_PAGE`, so the traversal's lookup
+ * path is uniform and there is no `SAME_PAGE` branch in the shader at all. `SAME_PAGE` then
+ * resolves to a page that is trivially resident — itself — and falls straight through to the
+ * selectability question, which is the only one it was ever really asking.
+ *
+ * Group selectability is **not** written here. It changes after install, as the reader's activation
+ * cascades run, and it is the one field of a resident page that moves.
+ *
+ * @param {Uint32Array} words arena as u32, indexed from its own element 0
+ * @param {Float32Array} floats the same memory as f32 — one view each rather than a DataView per
+ *     field, because this runs per cluster of every page that arrives
+ * @param {number} base word offset of the page's block
+ * @param {VGeoPage} page
+ * @returns {number} clusters whose `child_ref` named an entry outside the page's child table — zero
+ *     for any container the validator accepts
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function vgeo_runtime_write_page_block(words: Uint32Array, floats: Float32Array, base: number, page: VGeoPage): number;
+//# sourceMappingURL=vgeo_runtime_write_page_block.d.ts.map

package/src/shade/renderer/geometry/virtual/runtime/vgeo_runtime_write_page_block.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vgeo_runtime_write_page_block.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/geometry/virtual/runtime/vgeo_runtime_write_page_block.js"],"names":[],"mappings":"AAaA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,qDAXW,WAAW,UACX,YAAY,QAEZ,MAAM,mBAEJ,MAAM,CAoGlB"}

package/src/shade/renderer/geometry/virtual/runtime/vgeo_runtime_write_page_block.js

@@ -0,0 +1,138 @@
+import { assert } from "../../../../../core/assert.js";
+import { VGEO_NO_CHILD } from "../format/cluster/VGEO_NO_CHILD.js";
+import { VGEO_SAME_PAGE } from "../format/cluster/VGEO_SAME_PAGE.js";
+import { VGEO_NODE_FLAG_LEAF } from "../format/page/VGEO_NODE_FLAG_LEAF.js";
+import { VGEO_CLUSTER_ROW_OFFSET } from "./layout/VGEO_CLUSTER_ROW_OFFSET.js";
+import { VGEO_CLUSTER_ROW_WORDS } from "./layout/VGEO_CLUSTER_ROW_WORDS.js";
+import { VGEO_GROUP_ROW_OFFSET } from "./layout/VGEO_GROUP_ROW_OFFSET.js";
+import { VGEO_GROUP_ROW_WORDS } from "./layout/VGEO_GROUP_ROW_WORDS.js";
+import { VGEO_NODE_ROW_LEAF_BIT } from "./layout/VGEO_NODE_ROW_LEAF_BIT.js";
+import { VGEO_NODE_ROW_OFFSET } from "./layout/VGEO_NODE_ROW_OFFSET.js";
+import { VGEO_NODE_ROW_WORDS } from "./layout/VGEO_NODE_ROW_WORDS.js";
+import { VGEO_NO_CHILD_PAGE } from "./layout/VGEO_NO_CHILD_PAGE.js";
+
+/**
+ * Lay one decoded page's node, group and cluster rows into the arena.
+ *
+ * This is the whole of what a page install writes besides its payload, and it is deliberately a
+ * free function over two views rather than a method: the pool calls it against a mapped GPU upload
+ * range, and the agreement spec calls it against a plain array, and neither should have to own the
+ * other's machinery.
+ *
+ * **What it resolves, and why here.** A cluster's `child_ref` is an index into its page's child
+ * table, with two sentinels — `VGEO_SAME_PAGE` when the child group is in this very page, and
+ * `VGEO_NO_CHILD` for a leaf. The kernel does not see any of that: this writes a *global container
+ * page index* into every row, using the page's own index for `SAME_PAGE`, so the traversal's lookup
+ * path is uniform and there is no `SAME_PAGE` branch in the shader at all. `SAME_PAGE` then
+ * resolves to a page that is trivially resident — itself — and falls straight through to the
+ * selectability question, which is the only one it was ever really asking.
+ *
+ * Group selectability is **not** written here. It changes after install, as the reader's activation
+ * cascades run, and it is the one field of a resident page that moves.
+ *
+ * @param {Uint32Array} words arena as u32, indexed from its own element 0
+ * @param {Float32Array} floats the same memory as f32 — one view each rather than a DataView per
+ *     field, because this runs per cluster of every page that arrives
+ * @param {number} base word offset of the page's block
+ * @param {VGeoPage} page
+ * @returns {number} clusters whose `child_ref` named an entry outside the page's child table — zero
+ *     for any container the validator accepts
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function vgeo_runtime_write_page_block(words, floats, base, page) {
+    assert.isNonNegativeInteger(base, 'base');
+    assert.defined(page, 'page');
+
+    const node_count = page.node_count;
+    const group_count = page.group_cluster_first.length;
+    const cluster_count = page.cluster_count;
+
+    const group_base = base + node_count * VGEO_NODE_ROW_WORDS;
+    const cluster_base = group_base + group_count * VGEO_GROUP_ROW_WORDS;
+
+    let broken_child_refs = 0;
+
+    for (let node = 0; node < node_count; node++) {
+        const row = base + node * VGEO_NODE_ROW_WORDS;
+
+        for (let c = 0; c < 4; c++) {
+            floats[row + VGEO_NODE_ROW_OFFSET.SPHERE + c] = page.node_sphere[node * 4 + c];
+        }
+
+        floats[row + VGEO_NODE_ROW_OFFSET.MAX_PARENT_ERROR] = page.node_max_parent_error[node];
+
+        words[row + VGEO_NODE_ROW_OFFSET.CHILD_FIRST] = page.node_child_first[node];
+
+        const leaf = (page.node_flags[node] & VGEO_NODE_FLAG_LEAF) !== 0;
+
+        words[row + VGEO_NODE_ROW_OFFSET.CHILD_COUNT_AND_FLAGS] =
+            page.node_child_count[node] | (leaf ? VGEO_NODE_ROW_LEAF_BIT : 0);
+    }
+
+    for (let group = 0; group < group_count; group++) {
+        const row = group_base + group * VGEO_GROUP_ROW_WORDS;
+
+        words[row + VGEO_GROUP_ROW_OFFSET.CLUSTER_FIRST] = page.group_cluster_first[group];
+        words[row + VGEO_GROUP_ROW_OFFSET.CLUSTER_COUNT] = page.group_cluster_count[group];
+
+        /*
+         How many clusters anywhere in the container refine into this group. It travels with the
+         page so that this tier can run its **own** activation rule over its **own** residency —
+         see VGEO_GROUP_ROW_OFFSET.PARENT_COUNT, and REVIEW_LEDGER C1 for what publishing another
+         tier's answer costs.
+         */
+        words[row + VGEO_GROUP_ROW_OFFSET.PARENT_COUNT] = page.group_parent_count[group];
+
+        // not selectable until activation says so; a page installs drawing nothing. Any other
+        // default draws a group before the ancestors it hangs off have arrived.
+        words[row + VGEO_GROUP_ROW_OFFSET.FLAGS] = 0;
+    }
+
+    for (let cluster = 0; cluster < cluster_count; cluster++) {
+        const row = cluster_base + cluster * VGEO_CLUSTER_ROW_WORDS;
+
+        for (let c = 0; c < 4; c++) {
+            floats[row + VGEO_CLUSTER_ROW_OFFSET.SELF_SPHERE + c] =
+                page.self_sphere[cluster * 4 + c];
+            floats[row + VGEO_CLUSTER_ROW_OFFSET.PARENT_SPHERE + c] =
+                page.parent_sphere[cluster * 4 + c];
+        }
+
+        floats[row + VGEO_CLUSTER_ROW_OFFSET.SELF_ERROR] = page.self_error[cluster];
+        floats[row + VGEO_CLUSTER_ROW_OFFSET.PARENT_ERROR] = page.parent_error[cluster];
+
+        const child_ref = page.child_ref[cluster];
+
+        let child_page_index;
+
+        if (child_ref === VGEO_NO_CHILD) {
+            child_page_index = VGEO_NO_CHILD_PAGE;
+        } else if (child_ref === VGEO_SAME_PAGE) {
+            child_page_index = page.index;
+        } else if (child_ref < page.child_page_index.length) {
+            child_page_index = page.child_page_index[child_ref];
+        } else {
+            /*
+             A `child_ref` outside this page's child table. Impossible in a container the validator
+             accepts, and reachable because validation is off by default — so it is counted and the
+             cluster becomes a leaf, which is what `vgeo_select_cut` does with the same input.
+
+             The alternative is what this used to do: index past the child table, take `undefined`,
+             and store it as **zero** in a `Uint32Array`. Zero is the root page, which is pinned and
+             therefore always resident, so the cluster silently descended into whatever group of the
+             root carried that index instead of being drawn.
+             */
+            child_page_index = VGEO_NO_CHILD_PAGE;
+
+            broken_child_refs++;
+        }
+
+        words[row + VGEO_CLUSTER_ROW_OFFSET.CHILD_PAGE_INDEX] = child_page_index;
+        words[row + VGEO_CLUSTER_ROW_OFFSET.CHILD_GROUP] = page.child_group[cluster];
+        words[row + VGEO_CLUSTER_ROW_OFFSET.CHILD_REF] = child_ref;
+    }
+
+    return broken_child_refs;
+}

package/src/shade/renderer/global_illumination/brick4/cpu/brick4_bake_for_scene.d.ts

@@ -1,7 +1,7 @@
 /**
  * Requires a fairly beefy GPU to run, confirmed to work on RTX 4090.
  * @param {Object} options
- * @param {Scene} options.scene
+ * @param {Scene} options.scene the scene the renderer holds a context for — what is baked
  * @param {Renderer} options.renderer
  * @param {number} [options.cell_size=0.5] desired cell size for the voxel grid
  * @param {number} [options.max_memory_usage_bytes] maximum memory usage in bytes, default is 16MB

package/src/shade/renderer/global_illumination/brick4/cpu/brick4_bake_for_scene.js

@@ -9,7 +9,7 @@ import { brick4_to_gpu_structure } from "./brick4_to_gpu_structure.js";
 /**
  * Requires a fairly beefy GPU to run, confirmed to work on RTX 4090.
  * @param {Object} options
- * @param {Scene} options.scene
+ * @param {Scene} options.scene the scene the renderer holds a context for — what is baked
  * @param {Renderer} options.renderer
  * @param {number} [options.cell_size=0.5] desired cell size for the voxel grid
  * @param {number} [options.max_memory_usage_bytes] maximum memory usage in bytes, default is 16MB
@@ -22,8 +22,10 @@ export async function brick4_bake_for_scene({
                                                 max_memory_usage_bytes = 16 * MEGABYTE,
                                             }) {
 
+    const scene_ctx = renderer.scenes.obtain(scene);
+
     const bvh = new StaticSceneBVH();
-    bvh.build(scene);
+    bvh.build(scene_ctx);
 
     let _cell_size = cell_size;
 
@@ -50,8 +52,6 @@ export async function brick4_bake_for_scene({
 
     console.log(brick4);
 
-    const scene_ctx = renderer.scenes.obtain(scene);
-
     const probe_data = await brick4_bake_basic({
         brick4,
         graphics: renderer.graphics,

package/src/shade/renderer/global_illumination/brick4/cpu/brick4_generate_tree_from_scene.d.ts

@@ -2,13 +2,11 @@
  * Generate a "brick" tree, where each node is a 4x4x4 probe volume.
  *
  * @param {Object} options
- * @param {Scene} options.scene
  * @param {StaticSceneBVH} options.bvh
  * @param {number} [options.cell_size] size of the smallest cell in world units
  * @param {number} [options.max_memory_usage_bytes] upper limit of how much total memory the entire tree will take up, including probe data
  */
-export function brick4_generate_tree_from_scene({ scene, bvh, cell_size, max_memory_usage_bytes, }: {
-    scene: Scene;
+export function brick4_generate_tree_from_scene({ bvh, cell_size, max_memory_usage_bytes, }: {
     bvh: StaticSceneBVH;
     cell_size?: number;
     max_memory_usage_bytes?: number;

package/src/shade/renderer/global_illumination/brick4/cpu/brick4_generate_tree_from_scene.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"brick4_generate_tree_from_scene.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/global_illumination/brick4/cpu/brick4_generate_tree_from_scene.js"],"names":[],"mappings":"AAyKA;;;;;;;;GAQG;AACH;IAL0B,KAAK;IACI,GAAG,EAA3B,cAAc;IACG,SAAS,GAA1B,MAAM;IACW,sBAAsB,GAAvC,MAAM;2BAobhB;+BA1lB8B,sCAAsC;uCAS9B,6BAA6B"}
+{"version":3,"file":"brick4_generate_tree_from_scene.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/global_illumination/brick4/cpu/brick4_generate_tree_from_scene.js"],"names":[],"mappings":"AAyKA;;;;;;;GAOG;AACH;IAJmC,GAAG,EAA3B,cAAc;IACG,SAAS,GAA1B,MAAM;IACW,sBAAsB,GAAvC,MAAM;2BAsbhB;+BA3lB8B,sCAAsC;uCAS9B,6BAA6B"}

package/src/shade/renderer/global_illumination/brick4/cpu/brick4_generate_tree_from_scene.js

@@ -171,19 +171,17 @@ function purge_partial_depths(root, expansion_candidates) {
  * Generate a "brick" tree, where each node is a 4x4x4 probe volume.
  *
  * @param {Object} options
- * @param {Scene} options.scene
  * @param {StaticSceneBVH} options.bvh
  * @param {number} [options.cell_size] size of the smallest cell in world units
  * @param {number} [options.max_memory_usage_bytes] upper limit of how much total memory the entire tree will take up, including probe data
  */
 export function brick4_generate_tree_from_scene({
-                                                    scene,
                                                     bvh,
                                                     cell_size = 0.2,
                                                     max_memory_usage_bytes = 30 * MEGABYTE,
                                                 }) {
 
-    assert.defined(scene, 'scene');
+    assert.defined(bvh, 'bvh');
     assert.isNumber(cell_size, 'cell_size');
     assert.greaterThan(cell_size, 0, 'cell_size must be positive');
 
@@ -191,7 +189,10 @@ export function brick4_generate_tree_from_scene({
     // used to produce better dispersion and break ties
     const random = seededRandom(1337);
 
-    const scene_bounds = scene.instances.bounding_box;
+    // the box around everything in the tree: its root's
+    const scene_bounds = new AABB3();
+
+    bvh.instance_bvh.node_get_aabb(bvh.instance_bvh.root, scene_bounds);
 
     // Memory tracking is done from the GPU's perspective
 

package/src/shade/renderer/global_illumination/brick4/gpu/bake/brick4_bake_basic.js

@@ -86,7 +86,7 @@ export async function brick4_bake_basic({
 
         graphics.update();
 
-        r_materials.ensure_scene_materials(scene.scene);
+        r_materials.ensure_scene_materials(scene);
         r_materials.update();
     }
 

package/src/shade/renderer/global_illumination/lpv/bake/GPULightProbeVolumeRenderer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"GPULightProbeVolumeRenderer.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/global_illumination/lpv/bake/GPULightProbeVolumeRenderer.js"],"names":[],"mappings":"AAqBA;;;GAGG;AAEH;IA+GI;;;;OAIG;IACH,sBAHW,eAAe,SACf,eAAe,QAQzB;IAhCD;;;;OAIG;IACH,sBAHW,eAAe,SACf,eAAe,EAgBzB;IAtFD;;;OAGG;IACH,sCAEC;IAdD;;;OAGG;IACH,qCAEC;IAoCD;;;OAGG;IACH,6BAEC;IAYD;;;OAGG;IACH,0CASC;IAyDD;;;OAGG;IACH,gCAFW,MAAM,wEAahB;IAED;;;;;OAKG;IACH,qBAJW,sBAAsB,gBACtB,MAAM,qBACN,MAAM,QA6ChB;IAED,aAgGC;IAED;;;OAGG;IACH,sCAFW,MAAM,QA8ChB;IAED;;;OAGG;IACH,eAFY,MAAM,CAUjB;IAED,gBACC;;CACJ;8BA7XY,OAAO,6BAA6B,EAAE,eAAe;8BACrD,OAAO,mCAAmC,EAAE,eAAe;kCAZtC,uCAAuC;uCAFlC,8CAA8C"}
+{"version":3,"file":"GPULightProbeVolumeRenderer.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/global_illumination/lpv/bake/GPULightProbeVolumeRenderer.js"],"names":[],"mappings":"AAqBA;;;GAGG;AAEH;IA+GI;;;;OAIG;IACH,sBAHW,eAAe,SACf,eAAe,QAQzB;IAhCD;;;;OAIG;IACH,sBAHW,eAAe,SACf,eAAe,EAgBzB;IAtFD;;;OAGG;IACH,sCAEC;IAdD;;;OAGG;IACH,qCAEC;IAoCD;;;OAGG;IACH,6BAEC;IAYD;;;OAGG;IACH,0CASC;IAyDD;;;OAGG;IACH,gCAFW,MAAM,wEAUhB;IAED;;;;;OAKG;IACH,qBAJW,sBAAsB,gBACtB,MAAM,qBACN,MAAM,QA6ChB;IAED,aAgGC;IAED;;;OAGG;IACH,sCAFW,MAAM,QA8ChB;IAED;;;OAGG;IACH,eAFY,MAAM,CAUjB;IAED,gBACC;;CACJ;8BA1XY,OAAO,6BAA6B,EAAE,eAAe;8BACrD,OAAO,mCAAmC,EAAE,eAAe;kCAZtC,uCAAuC;uCAFlC,8CAA8C"}

package/src/shade/renderer/global_illumination/lpv/bake/GPULightProbeVolumeRenderer.js

@@ -174,9 +174,6 @@ export class GPULightProbeVolumeRenderer {
      * @param {number} resolution
      */
     async generate_locations(resolution = 2) {
-        // this.#scene.light_probe_volume.source.build_grid(this.#scene.scene.instances.bounding_box, new Vector3(resolution, resolution, resolution));
-        // return this.#scene;
-
         await graph_generate_probe_locations({
             scene: this.#scene,
             graphics: this.#graphics,
@@ -261,7 +258,7 @@ export class GPULightProbeVolumeRenderer {
 
         const r_materials = this.#materials;
 
-        r_materials.ensure_scene_materials(this.#scene.scene);
+        r_materials.ensure_scene_materials(this.#scene);
         r_materials.update();
 
         const command_ctx = ShadeGPUCommandContext.create(