@woosh/meep-engine 3.24.0 → 3.26.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/loader/gltf/tiny-gltf.d.ts

@@ -13,7 +13,7 @@ export class TinyGltf {
      * @readonly
      * @type {TextureFormat}
      */
-    static readonly "__#237@#UNCOMPRESSED_TARGET": TextureFormat;
+    static readonly "__#240@#UNCOMPRESSED_TARGET": TextureFormat;
     /**
      * @param {AssetManager} assetManager
      * @param {AssetRequestScope} [scope]

package/src/shade/renderer/postprocess/nss/NSS.d.ts

@@ -53,7 +53,7 @@ export class NSS {
      * @returns {number}
      */
     static recommended_jitter_sequence_size(upscale_ratio: number): number;
-    static "__#170@#preprocess_tensor_descriptor"(render_w: any, render_h: any): TextureResourceDescriptor;
+    static "__#173@#preprocess_tensor_descriptor"(render_w: any, render_h: any): TextureResourceDescriptor;
     /**
      * @param {GraphicsContext} graphics
      */

package/src/shade/renderer/rasterize/bucket/prepare_meshlet_draw_commands_by_material.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"prepare_meshlet_draw_commands_by_material.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/rasterize/bucket/prepare_meshlet_draw_commands_by_material.js"],"names":[],"mappings":"AA2BA;;;;;;;;;;;;;;;GAeG;AACH,uKAJa;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,aAAa,EAAE,MAAM,CAAC;IAAC,kBAAkB,EAAE,MAAM,CAAC;IAAC,wBAAwB,EAAE,MAAM,CAAA;CAAC,CAuTnH"}
+{"version":3,"file":"prepare_meshlet_draw_commands_by_material.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/rasterize/bucket/prepare_meshlet_draw_commands_by_material.js"],"names":[],"mappings":"AA2BA;;;;;;;;;;;;;;;GAeG;AACH,uKAJa;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,aAAa,EAAE,MAAM,CAAC;IAAC,kBAAkB,EAAE,MAAM,CAAC;IAAC,wBAAwB,EAAE,MAAM,CAAA;CAAC,CAgUnH"}

package/src/shade/renderer/rasterize/bucket/prepare_meshlet_draw_commands_by_material.js

@@ -129,6 +129,15 @@ export function graph_prepare_meshlet_draw_commands_by_material({
         expected_output_size: meshlet_buffer_size,
     });
 
+    /*
+     No virtual-geometry seam here, and not for want of a place to put one. This path serves the
+     transparent and alpha-tested draws, and it is handed a `scene` and an optional camera
+     *resource* rather than a `GPUViewContext` — where a cut needs the camera's uniform buffer to
+     put each instance into object space. The deeper reason is that it would be the wrong thing to
+     add: `VIRTUAL_GEOMETRY_DESIGN.md` §9 scopes v1 to static opaque geometry, and the opaque paths
+     are where the seam lives.
+     */
+
     graph_record_stat(graph, limits.stats, RasterizationCollectionType.Meshlets, meshlets);
 
     if (hzb !== -1 && camera !== -1) {

package/src/shade/renderer/rasterize/fast/graph_rasterize_scene_fast.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"graph_rasterize_scene_fast.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/rasterize/fast/graph_rasterize_scene_fast.js"],"names":[],"mappings":"AAiBA;;;;;;;;;;GAUG;AACH;;;;;;;IAFa;IAAC,YAAY,EAAE,MAAM,CAAC;IAAC,aAAa,EAAE,MAAM,EAAE,CAAA;CAAC,CA0I3D;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH;IAJ+B,KAAK;IACC,GAAG;IACA,MAAM;SA8C7C"}
+{"version":3,"file":"graph_rasterize_scene_fast.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/rasterize/fast/graph_rasterize_scene_fast.js"],"names":[],"mappings":"AAkBA;;;;;;;;;;GAUG;AACH;;;;;;;IAFa;IAAC,YAAY,EAAE,MAAM,CAAC;IAAC,aAAa,EAAE,MAAM,EAAE,CAAA;CAAC,CAoJ3D;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH;IAJ+B,KAAK;IACC,GAAG;IACA,MAAM;SA8C7C"}

package/src/shade/renderer/rasterize/fast/graph_rasterize_scene_fast.js

@@ -9,6 +9,7 @@ import { rasterization_material_bucket } from "../expand/bucket/chunk_rasterizat
 import { graph_meshes_classify_buckets } from "../expand/bucket/mesh/graph_meshes_classify_buckets.js";
 import { graph_meshlets_rasterize } from "../expand/graph_meshlets_rasterize.js";
 import { graph_expand_meshes_to_meshlets } from "../expand/mesh/graph_expand_meshes_to_meshlets.js";
+import { graph_vgeo_expand_if_enabled } from "../../geometry/virtual/runtime/graph_vgeo_expand_if_enabled.js";
 import { RasterizationCollectionType } from "../expand/RasterizationCollectionType.js";
 import { construct_primitive_state } from "../bucket/construct_primitive_state.js";
 import { graph_mesh_frustum_cull } from "../compute/graph_mesh_frustum_cull.js";
@@ -91,7 +92,7 @@ export function graph_rasterize_scene_fast_raw({
                 limits,
             });
 
-            const gr_bucket_meshlets = graph_expand_meshes_to_meshlets({
+            let gr_bucket_meshlets = graph_expand_meshes_to_meshlets({
                 graph,
                 input_meshes: gr_bucket_meshes,
                 scene: scene_ctx,
@@ -99,6 +100,16 @@ export function graph_rasterize_scene_fast_raw({
                 limits,
             });
 
+            // the seam: this bucket's virtual-geometry instances select their cut and append it to
+            // the same collection, which is the whole of what the rest of this function is told
+            gr_bucket_meshlets = graph_vgeo_expand_if_enabled({
+                graph,
+                input_meshes: gr_bucket_meshes,
+                output_meshlets: gr_bucket_meshlets,
+                view: view_ctx,
+                limits,
+            });
+
             graph_record_stat(graph, limits.stats, RasterizationCollectionType.Meshlets, gr_bucket_meshlets);
 
             const primitive_state = construct_primitive_state(draw_mode, side, job.cull_policy);

package/src/shade/renderer/rasterize/standard/graph_rasterize_partial_opaque.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"graph_rasterize_partial_opaque.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/rasterize/standard/graph_rasterize_partial_opaque.js"],"names":[],"mappings":"AAuBA;;;;;;;;;;;;;;;GAeG;AACH,gMAFa;IAAC,eAAe,EAAC,MAAM,CAAC;IAAC,cAAc,EAAC,MAAM,CAAC;IAAC,KAAK,EAAC,MAAM,CAAC;IAAC,aAAa,EAAC,MAAM,EAAE,CAAA;CAAC,CA8LjG"}
+{"version":3,"file":"graph_rasterize_partial_opaque.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/rasterize/standard/graph_rasterize_partial_opaque.js"],"names":[],"mappings":"AAwBA;;;;;;;;;;;;;;;GAeG;AACH,gMAFa;IAAC,eAAe,EAAC,MAAM,CAAC;IAAC,cAAc,EAAC,MAAM,CAAC;IAAC,KAAK,EAAC,MAAM,CAAC;IAAC,aAAa,EAAC,MAAM,EAAE,CAAA;CAAC,CAwMjG"}

package/src/shade/renderer/rasterize/standard/graph_rasterize_partial_opaque.js

@@ -17,6 +17,7 @@ import {
 import { rasterization_material_bucket } from "../expand/bucket/chunk_rasterization_material_bucket.js";
 import { graph_meshlets_rasterize } from "../expand/graph_meshlets_rasterize.js";
 import { graph_expand_meshes_to_meshlets } from "../expand/mesh/graph_expand_meshes_to_meshlets.js";
+import { graph_vgeo_expand_if_enabled } from "../../geometry/virtual/runtime/graph_vgeo_expand_if_enabled.js";
 import { MeshletFilter2WayPassData, pass_filter_meshlets_2way } from "../expand/pass1/pass_filter_meshlets_2way.js";
 import { RasterizationCollectionType } from "../expand/RasterizationCollectionType.js";
 import { construct_primitive_state, CullPolicy } from "../bucket/construct_primitive_state.js";
@@ -166,7 +167,7 @@ export function graph_rasterize_partial_opaque({
 
             gr_instances_maybe = pass_data_instances_0.instances_maybe = pass_instances_0.write(gr_instances_maybe);
 
-            const meshlet_expansion_0 = graph_expand_meshes_to_meshlets({
+            let meshlet_expansion_0 = graph_expand_meshes_to_meshlets({
                 graph,
                 input_meshes: pass_data_instances_0.instances_positive,
                 scene: scene_ctx,
@@ -174,6 +175,16 @@ export function graph_rasterize_partial_opaque({
                 limits,
             });
 
+            // the seam. The instance sets of the two HZB passes are disjoint, so cutting each of
+            // them costs one cut per view in total and no instance is ever cut twice
+            meshlet_expansion_0 = graph_vgeo_expand_if_enabled({
+                graph,
+                input_meshes: pass_data_instances_0.instances_positive,
+                output_meshlets: meshlet_expansion_0,
+                view,
+                limits,
+            });
+
 
             graph_record_stat(graph, limits.stats, RasterizationCollectionType.Meshlets, meshlet_expansion_0);
 

package/src/shade/renderer/rasterize/standard/graph_rasterize_remaining_opaque.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"graph_rasterize_remaining_opaque.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/rasterize/standard/graph_rasterize_remaining_opaque.js"],"names":[],"mappings":"AAyFA;;;;;;;;;;;;;;;;;GAiBG;AACH,kOAFa;IAAC,KAAK,EAAC,MAAM,CAAC;IAAC,aAAa,EAAC,MAAM,EAAE,CAAA;CAAC,CAmGlD"}
+{"version":3,"file":"graph_rasterize_remaining_opaque.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/rasterize/standard/graph_rasterize_remaining_opaque.js"],"names":[],"mappings":"AA0FA;;;;;;;;;;;;;;;;;GAiBG;AACH,kOAFa;IAAC,KAAK,EAAC,MAAM,CAAC;IAAC,aAAa,EAAC,MAAM,EAAE,CAAA;CAAC,CA4GlD"}