@woosh/meep-engine 3.24.0 → 3.26.0

package/src/shade/renderer/geometry/virtual/format/read/VGeoPage.d.ts

@@ -104,6 +104,28 @@ export class VGeoPage {
      * @type {Uint32Array}
      */
     child_decoded_size: Uint32Array;
+    /**
+     * `4 · child_page_count` — the copy of each child page's own metric sphere (format §5, §6.2).
+     *
+     * It is a *copy*, which is the point: it is readable before that page is fetched, and §11.11
+     * requires it to equal the page's own header metric so that a traversal trusting it cannot skip
+     * a page it needed.
+     *
+     * The GPU cut does not read it, and `runtime/RUNTIME_PLAN.md` §4.8 says why — a want is emitted
+     * from a cluster that has already passed a strictly tighter test. What wants it is a prefetch,
+     * which has no cluster-level evidence to be tighter than.
+     *
+     * @type {Float32Array}
+     */
+    child_metric_sphere: Float32Array;
+    /**
+     * @type {Float32Array}
+     */
+    child_metric_min_self_error: Float32Array;
+    /**
+     * @type {Float32Array}
+     */
+    child_metric_max_parent_error: Float32Array;
     /**
      * Per group: index of its first cluster within this page.
      * @type {Uint16Array}
@@ -136,11 +158,32 @@ export class VGeoPage {
      * @type {Float32Array}
      */
     parent_error: Float32Array;
+    /**
+     * `4 · cluster_count` — the LOD-metric sphere of the step that *consumed* each cluster; a root's
+     * duplicates its own.
+     *
+     * Half the cut rule is `project(parent_sphere, parent_error) > τ`, and a traversal never has to
+     * evaluate it: arriving through the parent step is that test. An evaluator does, which is why
+     * this column exists at all and why nothing read it before the GPU runtime.
+     *
+     * @type {Float32Array}
+     */
+    parent_sphere: Float32Array;
     /**
      * `4 · cluster_count` — each cluster's own tight sphere, for culling and never for the cut test.
      * @type {Float32Array}
      */
     bounds_sphere: Float32Array;
+    /**
+     * `6 · cluster_count` — each cluster's object-space AABB, in `min xyz, max xyz` order.
+     *
+     * This is the meshlet metadata's `bounds_box` verbatim (format §8): the HZB filter and the
+     * small-primitive cull read it, so a VG cluster that reaches the raster path without it cannot
+     * be culled by anything downstream.
+     *
+     * @type {Float32Array}
+     */
+    aabb: Float32Array;
     /**
      * Index into {@link child_page_index}, or `VGEO_SAME_PAGE`, or `VGEO_NO_CHILD` for a leaf.
      * @type {Uint16Array}
@@ -160,6 +203,12 @@ export class VGeoPage {
      * @type {Uint32Array}
      */
     cluster_payload_offset: Uint32Array;
+    /**
+     * How many bytes each cluster's payload runs to — the length of the copy into the meshlet data
+     * pool, which format §8 makes a copy and nothing more.
+     * @type {Uint32Array}
+     */
+    cluster_payload_size: Uint32Array;
     /**
      * @type {Uint8Array}
      */
@@ -173,6 +222,57 @@ export class VGeoPage {
      * @type {Uint16Array}
      */
     group_of_cluster: Uint16Array;
+    /**
+     * `4 · node_count` — the sphere bounding everything under each node of this page's tree.
+     *
+     * The tree (format §6.1) is over **this page's groups and nothing else**: it arrives with the
+     * page, leaves with it, and can never name anything that is not here. Node 0 is the root, an
+     * interior node's children are a contiguous run at a strictly greater index, and the leaves
+     * partition the group table — so a walk starts at 0, never special-cases a single-group page,
+     * and needs no cycle check.
+     *
+     * @type {Float32Array}
+     */
+    node_sphere: Float32Array;
+    /**
+     * The finest error covered by each node. Ranks a prefetch; the cut does not read it.
+     * @type {Float32Array}
+     */
+    node_min_self_error: Float32Array;
+    /**
+     * The coarsest parent error covered by each node, `+∞` where the root is covered.
+     *
+     * The load-bearing one: a cluster draws only while `project(parent) > τ`, so a node whose
+     * *largest* parent error still projects to no more than τ has nothing drawable anywhere under
+     * it and the whole subtree can be skipped.
+     *
+     * @type {Float32Array}
+     */
+    node_max_parent_error: Float32Array;
+    /**
+     * First child of each node — a node index when interior, a **group** index when a leaf.
+     * @type {Uint16Array}
+     */
+    node_child_first: Uint16Array;
+    /**
+     * `1..4`.
+     * @type {Uint16Array}
+     */
+    node_child_count: Uint16Array;
+    /**
+     * Bit 0 ({@link VGEO_NODE_FLAG_LEAF}): the children are groups rather than nodes.
+     * @type {Uint16Array}
+     */
+    node_flags: Uint16Array;
+    /**
+     * This page's own traversal metric — sphere xyzw, then `min_self_error`, `max_parent_error`.
+     *
+     * Format §11.10 makes it equal to node 0's, which is why a traversal that always enters a page
+     * at node 0 never reads this and never has to reconcile the two.
+     *
+     * @type {Float32Array}
+     */
+    metric: Float32Array;
     /**
      * How many of this page's clusters store a normal per vertex rather than one constant-compressed
      * word for the whole cluster.

package/src/shade/renderer/geometry/virtual/format/read/VGeoPage.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"VGeoPage.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/geometry/virtual/format/read/VGeoPage.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AACH;IACI;;;OAGG;IACH,OAFU,MAAM,CAEN;IAEV;;;OAGG;IACH,cAFU,MAAM,CAEC;IAEjB;;OAEG;IACH,YAFU,MAAM,CAED;IAEf;;;;;OAKG;IACH,OAFU,MAAM,CAEN;IAEV;;;OAGG;IACH,aAFU,MAAM,CAEA;IAEhB;;;OAGG;IACH,cAFU,MAAM,CAEC;IAEjB;;;OAGG;IACH,OAFU,UAAU,CAEM;IAE1B;;;;;OAKG;IACH,MAFU,QAAQ,CAEsB;IAExC;;OAEG;IACH,WAFU,MAAM,CAEF;IAEd;;OAEG;IACH,WAFU,MAAM,CAEF;IAEd;;;OAGG;IACH,gBAFU,MAAM,CAEG;IAEnB;;OAEG;IACH,cAFU,MAAM,CAEC;IAEjB;;OAEG;IACH,YAFU,MAAM,CAED;IAEf;;;OAGG;IACH,kBAFU,WAAW,CAEiB;IAEtC;;;;;OAKG;IACH,oBAFU,YAAY,CAEmB;IAEzC;;OAEG;IACH,kBAFU,WAAW,CAEiB;IAEtC;;;OAGG;IACH,oBAFU,WAAW,CAEmB;IAExC;;;OAGG;IACH,qBAFU,WAAW,CAEoB;IAEzC;;OAEG;IACH,qBAFU,WAAW,CAEoB;IAEzC;;;;OAIG;IACH,oBAFU,WAAW,CAEmB;IAExC;;OAEG;IACH,eAFU,MAAM,CAEE;IAElB;;;OAGG;IACH,aAFU,YAAY,CAEY;IAElC;;OAEG;IACH,YAFU,YAAY,CAEW;IAEjC;;OAEG;IACH,cAFU,YAAY,CAEa;IAEnC;;;OAGG;IACH,eAFU,YAAY,CAEc;IAEpC;;;OAGG;IACH,WAFU,WAAW,CAEU;IAE/B;;;OAGG;IACH,aAFU,WAAW,CAEY;IAEjC;;OAEG;IACH,gBAFU,WAAW,CAEe;IAEpC;;;OAGG;IACH,wBAFU,WAAW,CAEuB;IAE5C;;OAEG;IACH,cAFU,UAAU,CAEa;IAEjC;;OAEG;IACH,gBAFU,UAAU,CAEe;IAEnC;;;OAGG;IACH,kBAFU,WAAW,CAEiB;IAEtC;;;;;;;;;;;;OAYG;IACH,iCAFU,MAAM,CAEoB;IAEpC;;;;;OAKG;IACH,oBAHW,MAAM,GACJ,MAAM,CAIlB;CACJ"}
+{"version":3,"file":"VGeoPage.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/geometry/virtual/format/read/VGeoPage.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AACH;IACI;;;OAGG;IACH,OAFU,MAAM,CAEN;IAEV;;;OAGG;IACH,cAFU,MAAM,CAEC;IAEjB;;OAEG;IACH,YAFU,MAAM,CAED;IAEf;;;;;OAKG;IACH,OAFU,MAAM,CAEN;IAEV;;;OAGG;IACH,aAFU,MAAM,CAEA;IAEhB;;;OAGG;IACH,cAFU,MAAM,CAEC;IAEjB;;;OAGG;IACH,OAFU,UAAU,CAEM;IAE1B;;;;;OAKG;IACH,MAFU,QAAQ,CAEsB;IAExC;;OAEG;IACH,WAFU,MAAM,CAEF;IAEd;;OAEG;IACH,WAFU,MAAM,CAEF;IAEd;;;OAGG;IACH,gBAFU,MAAM,CAEG;IAEnB;;OAEG;IACH,cAFU,MAAM,CAEC;IAEjB;;OAEG;IACH,YAFU,MAAM,CAED;IAEf;;;OAGG;IACH,kBAFU,WAAW,CAEiB;IAEtC;;;;;OAKG;IACH,oBAFU,YAAY,CAEmB;IAEzC;;OAEG;IACH,kBAFU,WAAW,CAEiB;IAEtC;;;OAGG;IACH,oBAFU,WAAW,CAEmB;IAExC;;;;;;;;;;;;OAYG;IACH,qBAFU,YAAY,CAEoB;IAE1C;;OAEG;IACH,6BAFU,YAAY,CAE4B;IAElD;;OAEG;IACH,+BAFU,YAAY,CAE8B;IAEpD;;;OAGG;IACH,qBAFU,WAAW,CAEoB;IAEzC;;OAEG;IACH,qBAFU,WAAW,CAEoB;IAEzC;;;;OAIG;IACH,oBAFU,WAAW,CAEmB;IAExC;;OAEG;IACH,eAFU,MAAM,CAEE;IAElB;;;OAGG;IACH,aAFU,YAAY,CAEY;IAElC;;OAEG;IACH,YAFU,YAAY,CAEW;IAEjC;;OAEG;IACH,cAFU,YAAY,CAEa;IAEnC;;;;;;;;;OASG;IACH,eAFU,YAAY,CAEc;IAEpC;;;OAGG;IACH,eAFU,YAAY,CAEc;IAEpC;;;;;;;;OAQG;IACH,MAFU,YAAY,CAEK;IAE3B;;;OAGG;IACH,WAFU,WAAW,CAEU;IAE/B;;;OAGG;IACH,aAFU,WAAW,CAEY;IAEjC;;OAEG;IACH,gBAFU,WAAW,CAEe;IAEpC;;;OAGG;IACH,wBAFU,WAAW,CAEuB;IAE5C;;;;OAIG;IACH,sBAFU,WAAW,CAEqB;IAE1C;;OAEG;IACH,cAFU,UAAU,CAEa;IAEjC;;OAEG;IACH,gBAFU,UAAU,CAEe;IAEnC;;;OAGG;IACH,kBAFU,WAAW,CAEiB;IAEtC;;;;;;;;;;OAUG;IACH,aAFU,YAAY,CAEY;IAElC;;;OAGG;IACH,qBAFU,YAAY,CAEoB;IAE1C;;;;;;;;OAQG;IACH,uBAFU,YAAY,CAEsB;IAE5C;;;OAGG;IACH,kBAFU,WAAW,CAEiB;IAEtC;;;OAGG;IACH,kBAFU,WAAW,CAEiB;IAEtC;;;OAGG;IACH,YAFU,WAAW,CAEW;IAEhC;;;;;;;OAOG;IACH,QAFU,YAAY,CAEO;IAE7B;;;;;;;;;;;;OAYG;IACH,iCAFU,MAAM,CAEoB;IAEpC;;;;;OAKG;IACH,oBAHW,MAAM,GACJ,MAAM,CAIlB;CACJ"}

package/src/shade/renderer/geometry/virtual/format/read/VGeoPage.js

@@ -121,6 +121,31 @@ export class VGeoPage {
      */
     child_decoded_size = new Uint32Array(0);
 
+    /**
+     * `4 · child_page_count` — the copy of each child page's own metric sphere (format §5, §6.2).
+     *
+     * It is a *copy*, which is the point: it is readable before that page is fetched, and §11.11
+     * requires it to equal the page's own header metric so that a traversal trusting it cannot skip
+     * a page it needed.
+     *
+     * The GPU cut does not read it, and `runtime/RUNTIME_PLAN.md` §4.8 says why — a want is emitted
+     * from a cluster that has already passed a strictly tighter test. What wants it is a prefetch,
+     * which has no cluster-level evidence to be tighter than.
+     *
+     * @type {Float32Array}
+     */
+    child_metric_sphere = new Float32Array(0);
+
+    /**
+     * @type {Float32Array}
+     */
+    child_metric_min_self_error = new Float32Array(0);
+
+    /**
+     * @type {Float32Array}
+     */
+    child_metric_max_parent_error = new Float32Array(0);
+
     /**
      * Per group: index of its first cluster within this page.
      * @type {Uint16Array}
@@ -160,12 +185,35 @@ export class VGeoPage {
      */
     parent_error = new Float32Array(0);
 
+    /**
+     * `4 · cluster_count` — the LOD-metric sphere of the step that *consumed* each cluster; a root's
+     * duplicates its own.
+     *
+     * Half the cut rule is `project(parent_sphere, parent_error) > τ`, and a traversal never has to
+     * evaluate it: arriving through the parent step is that test. An evaluator does, which is why
+     * this column exists at all and why nothing read it before the GPU runtime.
+     *
+     * @type {Float32Array}
+     */
+    parent_sphere = new Float32Array(0);
+
     /**
      * `4 · cluster_count` — each cluster's own tight sphere, for culling and never for the cut test.
      * @type {Float32Array}
      */
     bounds_sphere = new Float32Array(0);
 
+    /**
+     * `6 · cluster_count` — each cluster's object-space AABB, in `min xyz, max xyz` order.
+     *
+     * This is the meshlet metadata's `bounds_box` verbatim (format §8): the HZB filter and the
+     * small-primitive cull read it, so a VG cluster that reaches the raster path without it cannot
+     * be culled by anything downstream.
+     *
+     * @type {Float32Array}
+     */
+    aabb = new Float32Array(0);
+
     /**
      * Index into {@link child_page_index}, or `VGEO_SAME_PAGE`, or `VGEO_NO_CHILD` for a leaf.
      * @type {Uint16Array}
@@ -189,6 +237,13 @@ export class VGeoPage {
      */
     cluster_payload_offset = new Uint32Array(0);
 
+    /**
+     * How many bytes each cluster's payload runs to — the length of the copy into the meshlet data
+     * pool, which format §8 makes a copy and nothing more.
+     * @type {Uint32Array}
+     */
+    cluster_payload_size = new Uint32Array(0);
+
     /**
      * @type {Uint8Array}
      */
@@ -205,6 +260,64 @@ export class VGeoPage {
      */
     group_of_cluster = new Uint16Array(0);
 
+    /**
+     * `4 · node_count` — the sphere bounding everything under each node of this page's tree.
+     *
+     * The tree (format §6.1) is over **this page's groups and nothing else**: it arrives with the
+     * page, leaves with it, and can never name anything that is not here. Node 0 is the root, an
+     * interior node's children are a contiguous run at a strictly greater index, and the leaves
+     * partition the group table — so a walk starts at 0, never special-cases a single-group page,
+     * and needs no cycle check.
+     *
+     * @type {Float32Array}
+     */
+    node_sphere = new Float32Array(0);
+
+    /**
+     * The finest error covered by each node. Ranks a prefetch; the cut does not read it.
+     * @type {Float32Array}
+     */
+    node_min_self_error = new Float32Array(0);
+
+    /**
+     * The coarsest parent error covered by each node, `+∞` where the root is covered.
+     *
+     * The load-bearing one: a cluster draws only while `project(parent) > τ`, so a node whose
+     * *largest* parent error still projects to no more than τ has nothing drawable anywhere under
+     * it and the whole subtree can be skipped.
+     *
+     * @type {Float32Array}
+     */
+    node_max_parent_error = new Float32Array(0);
+
+    /**
+     * First child of each node — a node index when interior, a **group** index when a leaf.
+     * @type {Uint16Array}
+     */
+    node_child_first = new Uint16Array(0);
+
+    /**
+     * `1..4`.
+     * @type {Uint16Array}
+     */
+    node_child_count = new Uint16Array(0);
+
+    /**
+     * Bit 0 ({@link VGEO_NODE_FLAG_LEAF}): the children are groups rather than nodes.
+     * @type {Uint16Array}
+     */
+    node_flags = new Uint16Array(0);
+
+    /**
+     * This page's own traversal metric — sphere xyzw, then `min_self_error`, `max_parent_error`.
+     *
+     * Format §11.10 makes it equal to node 0's, which is why a traversal that always enters a page
+     * at node 0 never reads this and never has to reconcile the two.
+     *
+     * @type {Float32Array}
+     */
+    metric = new Float32Array(6);
+
     /**
      * How many of this page's clusters store a normal per vertex rather than one constant-compressed
      * word for the whole cluster.

package/src/shade/renderer/geometry/virtual/format/read/vgeo_read_header.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"vgeo_read_header.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/geometry/virtual/format/read/vgeo_read_header.js"],"names":[],"mappings":"AA2BA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wCATW,UAAU,GAER,mBAAmB,CA4G/B;AAED;;;;;;;;;;;;;;;GAeG;AACH,+CAJW,UAAU,GACR,MAAM,CA4BlB;AAlLD;;;;;;;GAOG;AACH,kCAFU,MAAM,CAEoC;oCAjBhB,0BAA0B"}
+{"version":3,"file":"vgeo_read_header.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/geometry/virtual/format/read/vgeo_read_header.js"],"names":[],"mappings":"AA2BA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wCATW,UAAU,GAER,mBAAmB,CAiH/B;AAED;;;;;;;;;;;;;;;GAeG;AACH,+CAJW,UAAU,GACR,MAAM,CA4BlB;AAvLD;;;;;;;GAOG;AACH,kCAFU,MAAM,CAEoC;oCAjBhB,0BAA0B"}

package/src/shade/renderer/geometry/virtual/format/read/vgeo_read_header.js

@@ -90,6 +90,11 @@ export function vgeo_read_header(bytes) {
         throw new Error(`the file requires feature flags 0x${required.toString(16)}`);
     }
 
+    // Ignorable by definition: §4 requires a reader to read on through bits it does not know, so
+    // nothing is rejected here. It is carried because one bit is defined — the page-size guarantee —
+    // and a runtime that allocates fixed-stride slots has to be able to ask for it.
+    result.feature_flags_ignorable = view.getUint32(VGEO_HEADER_OFFSET.FEATURE_FLAGS_IGNORABLE, LE);
+
     result.payload_encoding = view.getUint32(VGEO_HEADER_OFFSET.PAYLOAD_ENCODING, LE);
 
     if (result.payload_encoding !== VGEO_PAYLOAD_ENCODING_SHADE_MESHLET_V1) {

package/src/shade/renderer/geometry/virtual/format/read/vgeo_read_page.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"vgeo_read_page.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/geometry/virtual/format/read/vgeo_read_page.js"],"names":[],"mappings":"AAgCA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,4CAVW,UAAU,cACV,MAAM,GAEJ,QAAQ,CA+EpB;yBA9GwB,eAAe"}
+{"version":3,"file":"vgeo_read_page.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/geometry/virtual/format/read/vgeo_read_page.js"],"names":[],"mappings":"AAmCA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,4CAVW,UAAU,cACV,MAAM,GAEJ,QAAQ,CAgFpB;yBA/GwB,eAAe"}

package/src/shade/renderer/geometry/virtual/format/read/vgeo_read_page.js

@@ -11,6 +11,9 @@ import { VGEO_FRAME_HEADER_SIZE } from "../frame/VGEO_FRAME_HEADER_SIZE.js";
 import { VGEO_FRAME_OFFSET } from "../frame/VGEO_FRAME_OFFSET.js";
 import { vgeo_frame_decode_bound } from "../frame/vgeo_frame_decode_bound.js";
 import { VGEO_GROUP_RECORD_SIZE } from "../page/VGEO_GROUP_RECORD_SIZE.js";
+import { VGEO_METRIC_OFFSET } from "../page/VGEO_METRIC_OFFSET.js";
+import { VGEO_NODE_OFFSET } from "../page/VGEO_NODE_OFFSET.js";
+import { VGEO_NODE_RECORD_SIZE } from "../page/VGEO_NODE_RECORD_SIZE.js";
 import { VGEO_PAGE_HEADER_SIZE } from "../page/VGEO_PAGE_HEADER_SIZE.js";
 import { VGEO_PAGE_MAGIC } from "../frame/VGEO_PAGE_MAGIC.js";
 import { VGEO_PAGE_OFFSET } from "../page/VGEO_PAGE_OFFSET.js";
@@ -122,11 +125,34 @@ export function vgeo_read_page(frame_bytes, page_index) {
     read_child_table(result, frame_view, frame);
     read_page_header(result);
     read_group_table(result);
+    read_node_table(result);
     read_cluster_table(result);
 
     return result;
 }
 
+/**
+ * One traversal metric (§6.2) out of `view` at `offset`, into three parallel columns at `index`.
+ *
+ * The same 24 bytes appear in three places — a child-table entry, a page header, a node — which is
+ * what lets one reader serve all three and what §11.10/§11.11 cross-check against each other.
+ *
+ * @param {DataView} view
+ * @param {number} offset of the metric's first byte
+ * @param {Float32Array} sphere `4 · n`
+ * @param {Float32Array} min_self_error
+ * @param {Float32Array} max_parent_error
+ * @param {number} index
+ */
+function read_metric(view, offset, sphere, min_self_error, max_parent_error, index) {
+    for (let c = 0; c < 4; c++) {
+        sphere[index * 4 + c] = view.getFloat32(offset + VGEO_METRIC_OFFSET.SPHERE + c * 4, LE);
+    }
+
+    min_self_error[index] = view.getFloat32(offset + VGEO_METRIC_OFFSET.MIN_SELF_ERROR, LE);
+    max_parent_error[index] = view.getFloat32(offset + VGEO_METRIC_OFFSET.MAX_PARENT_ERROR, LE);
+}
+
 /**
  * The child table is plaintext inside the frame, never compressed — which is exactly what lets a
  * traversal read fetch ranges without decoding anything. So it is read from the frame's own bytes
@@ -143,6 +169,9 @@ function read_child_table(page, frame_view, frame) {
     page.child_frame_offset = new Float64Array(count);
     page.child_fetch_size = new Uint32Array(count);
     page.child_decoded_size = new Uint32Array(count);
+    page.child_metric_sphere = new Float32Array(count * 4);
+    page.child_metric_min_self_error = new Float32Array(count);
+    page.child_metric_max_parent_error = new Float32Array(count);
 
     for (let i = 0; i < count; i++) {
         const entry = VGEO_FRAME_HEADER_SIZE + i * VGEO_CHILD_TABLE_ENTRY_SIZE;
@@ -159,7 +188,74 @@ function read_child_table(page, frame_view, frame) {
 
         page.child_fetch_size[i] = frame_view.getUint32(entry + VGEO_CHILD_OFFSET.FETCH_SIZE, LE);
         page.child_decoded_size[i] = frame_view.getUint32(entry + VGEO_CHILD_OFFSET.DECODED_SIZE, LE);
+
+        read_metric(
+            frame_view, entry + VGEO_CHILD_OFFSET.METRIC,
+            page.child_metric_sphere,
+            page.child_metric_min_self_error,
+            page.child_metric_max_parent_error,
+            i
+        );
+    }
+}
+
+/**
+ * The tree over this page's groups (§6.1).
+ *
+ * Its extent is checked before it is walked for the same reason the cluster table's is: `node_count`
+ * and `node_table_offset` are file bytes, and a page that decoded short would otherwise be read
+ * past.
+ *
+ * @param {VGeoPage} page
+ */
+function read_node_table(page) {
+    const data = page.data;
+
+    const count = page.node_count;
+
+    const table = data.getUint32(VGEO_PAGE_OFFSET.NODE_TABLE_OFFSET, LE);
+
+    const end = table + count * VGEO_NODE_RECORD_SIZE;
+
+    if (end > page.bytes.byteLength) {
+        throw new Error(
+            `page ${page.index}: its ${count} node records end at ${end},`
+            + ` past the ${page.bytes.byteLength} bytes it decoded to`
+        );
     }
+
+    page.node_sphere = new Float32Array(count * 4);
+    page.node_min_self_error = new Float32Array(count);
+    page.node_max_parent_error = new Float32Array(count);
+    page.node_child_first = new Uint16Array(count);
+    page.node_child_count = new Uint16Array(count);
+    page.node_flags = new Uint16Array(count);
+
+    for (let i = 0; i < count; i++) {
+        const record = table + i * VGEO_NODE_RECORD_SIZE;
+
+        read_metric(
+            data, record + VGEO_NODE_OFFSET.METRIC,
+            page.node_sphere, page.node_min_self_error, page.node_max_parent_error, i
+        );
+
+        page.node_child_first[i] = data.getUint16(record + VGEO_NODE_OFFSET.CHILD_FIRST, LE);
+        page.node_child_count[i] = data.getUint16(record + VGEO_NODE_OFFSET.CHILD_COUNT, LE);
+        page.node_flags[i] = data.getUint16(record + VGEO_NODE_OFFSET.FLAGS, LE);
+    }
+
+    for (let c = 0; c < 4; c++) {
+        page.metric[c] = data.getFloat32(
+            VGEO_PAGE_OFFSET.METRIC + VGEO_METRIC_OFFSET.SPHERE + c * 4, LE
+        );
+    }
+
+    page.metric[4] = data.getFloat32(
+        VGEO_PAGE_OFFSET.METRIC + VGEO_METRIC_OFFSET.MIN_SELF_ERROR, LE
+    );
+    page.metric[5] = data.getFloat32(
+        VGEO_PAGE_OFFSET.METRIC + VGEO_METRIC_OFFSET.MAX_PARENT_ERROR, LE
+    );
 }
 
 /**
@@ -224,13 +320,16 @@ function read_cluster_table(page) {
     }
 
     page.self_sphere = new Float32Array(count * 4);
+    page.parent_sphere = new Float32Array(count * 4);
     page.bounds_sphere = new Float32Array(count * 4);
+    page.aabb = new Float32Array(count * 6);
     page.self_error = new Float32Array(count);
     page.parent_error = new Float32Array(count);
     page.child_ref = new Uint16Array(count);
     page.child_group = new Uint16Array(count);
     page.encoding_flags = new Uint32Array(count);
     page.cluster_payload_offset = new Uint32Array(count);
+    page.cluster_payload_size = new Uint32Array(count);
     page.vertex_count = new Uint8Array(count);
     page.triangle_count = new Uint8Array(count);
     page.group_of_cluster = new Uint16Array(count);
@@ -241,10 +340,17 @@ function read_cluster_table(page) {
         for (let c = 0; c < 4; c++) {
             page.self_sphere[i * 4 + c] =
                 data.getFloat32(record + VGEO_CLUSTER_OFFSET.SELF_SPHERE + c * 4, LE);
+            page.parent_sphere[i * 4 + c] =
+                data.getFloat32(record + VGEO_CLUSTER_OFFSET.PARENT_SPHERE + c * 4, LE);
             page.bounds_sphere[i * 4 + c] =
                 data.getFloat32(record + VGEO_CLUSTER_OFFSET.BOUNDS_SPHERE + c * 4, LE);
         }
 
+        for (let c = 0; c < 6; c++) {
+            page.aabb[i * 6 + c] =
+                data.getFloat32(record + VGEO_CLUSTER_OFFSET.AABB + c * 4, LE);
+        }
+
         page.self_error[i] = data.getFloat32(record + VGEO_CLUSTER_OFFSET.SELF_ERROR, LE);
         page.parent_error[i] = data.getFloat32(record + VGEO_CLUSTER_OFFSET.PARENT_ERROR, LE);
         page.child_ref[i] = data.getUint16(record + VGEO_CLUSTER_OFFSET.CHILD_REF, LE);
@@ -252,6 +358,8 @@ function read_cluster_table(page) {
         page.encoding_flags[i] = data.getUint32(record + VGEO_CLUSTER_OFFSET.ENCODING_FLAGS, LE);
         page.cluster_payload_offset[i] =
             data.getUint32(record + VGEO_CLUSTER_OFFSET.PAYLOAD_OFFSET, LE);
+        page.cluster_payload_size[i] =
+            data.getUint32(record + VGEO_CLUSTER_OFFSET.PAYLOAD_SIZE, LE);
         page.vertex_count[i] = data.getUint8(record + VGEO_CLUSTER_OFFSET.VERTEX_COUNT);
         page.triangle_count[i] = data.getUint8(record + VGEO_CLUSTER_OFFSET.TRIANGLE_COUNT);
 

package/src/shade/renderer/geometry/virtual/format/vgeo_validate_container.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"vgeo_validate_container.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/geometry/virtual/format/vgeo_validate_container.js"],"names":[],"mappings":"AA+/CA;;;;;GAKG;AACH,gDAHW,YAAY,GACV,UAAU,EAAE,CAkFxB;6BArlD4B,4CAA4C;2BA8C9C,iBAAiB"}
+{"version":3,"file":"vgeo_validate_container.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/geometry/virtual/format/vgeo_validate_container.js"],"names":[],"mappings":"AAshDA;;;;;GAKG;AACH,gDAHW,YAAY,GACV,UAAU,EAAE,CAkFxB;6BA5mD4B,4CAA4C;2BA+C9C,iBAAiB"}

package/src/shade/renderer/geometry/virtual/format/vgeo_validate_container.js

@@ -14,6 +14,7 @@ import { VGEO_DIRECTORY_FLAG_ROOT_PAGE } from "./directory/VGEO_DIRECTORY_FLAG_R
 import { VGEO_DIRECTORY_RECORD_SIZE } from "./directory/VGEO_DIRECTORY_RECORD_SIZE.js";
 import { vgeo_decode_frame_blob } from "./frame/vgeo_decode_frame_blob.js";
 import { VGEO_ENCODING_FLAGS_MASK } from "./payload/VGEO_ENCODING_FLAGS_MASK.js";
+import { VGEO_FEATURE_IGNORABLE_BOUNDED_PAGES } from "./header/VGEO_FEATURE_IGNORABLE_BOUNDED_PAGES.js";
 import { VGEO_FORMAT_VERSION } from "./header/VGEO_FORMAT_VERSION.js";
 import { VGEO_FRAME_ALIGNMENT } from "./frame/VGEO_FRAME_ALIGNMENT.js";
 import { vgeo_frame_decode_bound } from "./frame/vgeo_frame_decode_bound.js";
@@ -437,6 +438,24 @@ function check_frames(buffer, frames, out) {
         }
     }
 
+    buffer.position = VGEO_HEADER_OFFSET.FEATURE_FLAGS_IGNORABLE;
+
+    const feature_flags_ignorable = buffer.readUint32();
+
+    buffer.position = VGEO_HEADER_OFFSET.NOMINAL_PAGE_SIZE;
+
+    const nominal_page_size = buffer.readUint32();
+
+    // §11.14, and only when the file claims it. Unset, `nominal_page_size` is the advisory build
+    // parameter it has always been and there is nothing here to be wrong; set, it is a promise a
+    // reader is entitled to size fixed-stride page slots against, and one page past it is that
+    // reader's buffer overrun. Every *other* bit of this word is ignored, per §4.
+    const bounded_pages = (feature_flags_ignorable & VGEO_FEATURE_IGNORABLE_BOUNDED_PAGES) !== 0;
+
+    if (bounded_pages && nominal_page_size === 0) {
+        out.push(new VGeoDefect(VGEO_DEFECT.HEADER, 'the bounded-pages feature bit is set and nominal_page_size is 0, which no page can be within'));
+    }
+
     buffer.position = VGEO_HEADER_OFFSET.ASSET_ID;
 
     const asset_id_low = buffer.readUint64();
@@ -471,6 +490,10 @@ function check_frames(buffer, frames, out) {
             out.push(new VGeoDefect(VGEO_DEFECT.FRAME, `page ${frame.page_index}: decoded_size ${frame.decoded_size} is more than codec ${frame.codec} could produce from ${frame.stored_size} stored bytes`));
         }
 
+        if (bounded_pages && frame.decoded_size > nominal_page_size) {
+            out.push(new VGeoDefect(VGEO_DEFECT.FRAME, `page ${frame.page_index}: decoded_size ${frame.decoded_size} is past the ${nominal_page_size} byte page size this container guarantees`));
+        }
+
         if (frame.frame_offset % VGEO_FRAME_ALIGNMENT !== 0) {
             out.push(new VGeoDefect(VGEO_DEFECT.FRAME, `page ${frame.page_index}: frame_offset ${frame.frame_offset} is not ${VGEO_FRAME_ALIGNMENT}-aligned`));
         }

package/src/shade/renderer/geometry/virtual/format/vgeo_write_container.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"vgeo_write_container.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/geometry/virtual/format/vgeo_write_container.js"],"names":[],"mappings":"AAgRA;;;;;;;;GAQG;AACH,4CANW,qBAAqB,8BAGnB,YAAY,CA8MxB;6BAne4B,4CAA4C"}
+{"version":3,"file":"vgeo_write_container.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/geometry/virtual/format/vgeo_write_container.js"],"names":[],"mappings":"AAmTA;;;;;;;;GAQG;AACH,4CANW,qBAAqB,8BAGnB,YAAY,CAmNxB;6BA3gB4B,4CAA4C"}

package/src/shade/renderer/geometry/virtual/format/vgeo_write_container.js

@@ -12,6 +12,7 @@ import { vgeo_directory_block_count } from "./directory/vgeo_directory_block_cou
 import { VGEO_DIRECTORY_FLAG_ROOT_PAGE } from "./directory/VGEO_DIRECTORY_FLAG_ROOT_PAGE.js";
 import { VGEO_DIRECTORY_RECORD_SIZE } from "./directory/VGEO_DIRECTORY_RECORD_SIZE.js";
 import { vgeo_encode_frame_blob } from "./frame/vgeo_encode_frame_blob.js";
+import { VGEO_FEATURE_IGNORABLE_BOUNDED_PAGES } from "./header/VGEO_FEATURE_IGNORABLE_BOUNDED_PAGES.js";
 import { VGEO_FORMAT_VERSION } from "./header/VGEO_FORMAT_VERSION.js";
 import { VGEO_FRAME_ALIGNMENT } from "./frame/VGEO_FRAME_ALIGNMENT.js";
 import { VGEO_FRAME_HEADER_SIZE } from "./frame/VGEO_FRAME_HEADER_SIZE.js";
@@ -270,6 +271,40 @@ function build_page_blob(page, child_pages) {
     return buffer.raw_bytes;
 }
 
+/**
+ * Check the page-size bound the caller stated, and report the feature bits the header should carry.
+ *
+ * This is the one place in the pipeline that knows what a page actually costs decoded, so it is the
+ * one place that can honestly set {@link VGEO_FEATURE_IGNORABLE_BOUNDED_PAGES} — the bit that
+ * promises a reader every page fits `nominal_page_size`, and so lets a VRAM tier allocate
+ * fixed-stride page slots. The assembler already lays pages out against the cap; this refuses to
+ * write a file that claims a size it does not keep, however the page list was produced.
+ *
+ * A `nominal_page_size` of zero states no size at all — the synthetic containers the reader and
+ * residency specs write straight to this function do that — and then there is nothing to check and
+ * no promise to make.
+ *
+ * @param {PageBlob[]} blobs in page order
+ * @param {number} nominal_page_size
+ * @returns {number} `feature_flags_ignorable`
+ */
+function page_size_guarantee(blobs, nominal_page_size) {
+    if (nominal_page_size === 0) {
+        return 0;
+    }
+
+    blobs.forEach((blob, index) => {
+        if (blob.decoded_size > nominal_page_size) {
+            throw new Error(
+                `virtual geometry: page ${index} decodes to ${blob.decoded_size} bytes, past the`
+                + ` ${nominal_page_size} this container states as its page size (VGEO_FORMAT §11.14)`
+            );
+        }
+    });
+
+    return VGEO_FEATURE_IGNORABLE_BOUNDED_PAGES;
+}
+
 /**
  * Turn an assembled page list into the finished container.
  *
@@ -314,6 +349,8 @@ export function vgeo_write_container(pages, options) {
         return blob;
     });
 
+    const feature_flags_ignorable = page_size_guarantee(blobs, options.nominal_page_size);
+
     // The level table sits between the header and the root page, so that one fetch of the file's
     // head brings the header, the whole table, and the always-resident page together.
     const level_table_size = options.levels.length * VGEO_LEVEL_RECORD_SIZE;
@@ -355,6 +392,9 @@ export function vgeo_write_container(pages, options) {
     buffer.writeUint16(VGEO_HEADER_SIZE);
     buffer.writeUint8(VGEO_HASH_ALGO_XXH3);
 
+    buffer.position = VGEO_HEADER_OFFSET.FEATURE_FLAGS_IGNORABLE;
+    buffer.writeUint32(feature_flags_ignorable);
+
     buffer.position = VGEO_HEADER_OFFSET.PAYLOAD_ENCODING;
     buffer.writeUint32(VGEO_PAYLOAD_ENCODING_SHADE_MESHLET_V1);