@woosh/meep-engine 3.27.0 → 3.29.0

package/src/shade/renderer/geometry/virtual/format/page/VGEO_PAGE_OFFSET_V5.js

@@ -0,0 +1,43 @@
+/**
+ * Page header field offsets as `format_version` 5 and earlier laid them out, kept so that the
+ * reader can still take the containers that exist.
+ *
+ * Version 6 widened the page band to `u16` ({@link VGEO_PAGE_OFFSET}) and paid for it by dropping
+ * `node_table_offset`, which was only ever `VGEO_PAGE_HEADER_SIZE + 8 * group_count` restated. So
+ * four bytes changed meaning at offset 4 and four more at offset 20, and everything else — the
+ * table offsets, the parent section, the metric — sits exactly where it did. A version-5 page read
+ * by the version-6 sequence takes `max_level` out of `node_count` and `node_count` out of an
+ * offset, which is why the decoder branches on the container's version rather than trusting one
+ * layout. Nothing but {@link vgeo_read_page} should need this.
+ *
+ * It serves every version below 6, not just 5: the parent fields at 24..32 were reserved and
+ * written as zero before version 4, and `parent_table_offset === 0` is already how the reader
+ * spells that absence.
+ *
+ * The writer and the validator have no such branch: one writes the current version and the other
+ * refuses anything else.
+ *
+ * @enum {number}
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export const VGEO_PAGE_OFFSET_V5 = {
+    GROUP_COUNT: 0,
+    CLUSTER_COUNT: 2,
+    MIN_LEVEL: 4,
+    MAX_LEVEL: 5,
+    NODE_COUNT: 6,
+    CLUSTER_TABLE_OFFSET: 8,
+    PAYLOAD_OFFSET: 12,
+    PAYLOAD_SIZE: 16,
+    /**
+     * Stored, and required to equal `VGEO_PAGE_HEADER_SIZE + 8 * group_count`. Version 6 derives it
+     * instead and spends these four bytes on `node_count` and two reserved.
+     */
+    NODE_TABLE_OFFSET: 20,
+    PARENT_TABLE_OFFSET: 24,
+    PARENT_ENTRY_COUNT: 28,
+    PARENT_PAGE_COUNT: 30,
+    METRIC: 32,
+};

package/src/shade/renderer/geometry/virtual/format/payload/vgeo_encode_cluster_payload.d.ts

@@ -1,11 +1,41 @@
 /**
  * @param {Float32Array} positions `vertex_count * 3` cluster-local coordinates
  * @param {Uint8Array} indices `triangle_count * 3` cluster-local vertex indices
- * @param {Uint32Array} vertex_ids `vertex_count` source vertex ids, for the attribute lookup
+ * @param {Uint32Array} attribute_ids `vertex_count` ids into `layers`, one per output vertex. What
+ *     they are ids *of* is the layers' business and not this function's — today they are corners,
+ *     because that is where an appearance can differ from its neighbour's across a seam.
  * @param {(BinaryDataLayer|null)[]} layers one slot per {@link VGEO_ATTRIBUTES} entry, null where
  *     the geometry does not carry that channel
  * @returns {VGeoEncodedPayload}
  */
-export function vgeo_encode_cluster_payload(positions: Float32Array, indices: Uint8Array, vertex_ids: Uint32Array, layers: (BinaryDataLayer | null)[]): VGeoEncodedPayload;
+export function vgeo_encode_cluster_payload(positions: Float32Array, indices: Uint8Array, attribute_ids: Uint32Array, layers: (BinaryDataLayer | null)[]): VGeoEncodedPayload;
+/**
+ * Encode one cluster's geometry into a `SHADE_MESHLET_V1` payload: the local index section, then
+ * every attribute section in the frozen order, each either one value per vertex or — when every
+ * vertex agrees, or the source simply lacks the attribute — a single constant-compressed value.
+ *
+ * The encoders themselves are Shade's, unmodified. That is the whole point of the encoding's
+ * "byte-compatible with the data pool" claim: uploading a payload is a copy, so it has to be the
+ * same bits Shade's own encoder would have produced.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+/**
+ * The encoded word a section carries when the source lacks the attribute — Shade's
+ * `ENCODED_ATTRIBUTE_DEFAULT_VALUES`, in this format's own attribute order, so that a `.vgeo`
+ * payload and a `MeshletBatch` payload of the same geometry differ nowhere.
+ *
+ * Colour's default is opaque white with its alpha byte set, while `encode_colors_to_u32` writes only
+ * three channels and leaves alpha zero. That asymmetry is Shade's, and matching it is the point.
+ *
+ * Exported so that `vgeo_encode_cluster_payload.spec.js` can hold it against Shade's own table
+ * rather than against nothing — it is the fourth of the four tables the byte-compatibility claim
+ * rests on, and was for a long time the only one no test compared.
+ *
+ * @readonly
+ * @type {number[][]}
+ */
+export const ENCODED_DEFAULTS: number[][];
 import { VGeoEncodedPayload } from "./VGeoEncodedPayload.js";
 //# sourceMappingURL=vgeo_encode_cluster_payload.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"vgeo_encode_cluster_payload.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/geometry/virtual/format/payload/vgeo_encode_cluster_payload.js"],"names":[],"mappings":"AAgHA;;;;;;;GAOG;AACH,uDAPW,YAAY,WACZ,UAAU,cACV,WAAW,UACX,CAAC,kBAAgB,IAAI,CAAC,EAAE,GAEtB,kBAAkB,CAiF9B;mCA1LkC,yBAAyB"}
+{"version":3,"file":"vgeo_encode_cluster_payload.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/geometry/virtual/format/payload/vgeo_encode_cluster_payload.js"],"names":[],"mappings":"AAoHA;;;;;;;;;GASG;AACH,uDATW,YAAY,WACZ,UAAU,iBACV,WAAW,UAGX,CAAC,kBAAgB,IAAI,CAAC,EAAE,GAEtB,kBAAkB,CAmF9B;AAhMD;;;;;;;;;;;GAWG;AAEH;;;;;;;;;;;;;;GAcG;AACH,+BAFU,MAAM,EAAE,EAAE,CAEe;mCA9BA,yBAAyB"}

package/src/shade/renderer/geometry/virtual/format/payload/vgeo_encode_cluster_payload.js

@@ -28,16 +28,20 @@ import { VGeoEncodedPayload } from "./VGeoEncodedPayload.js";
 
 /**
  * The encoded word a section carries when the source lacks the attribute — Shade's
- * `ENCODED_ATTRIBUTE_DEFAULT_VALUES`, reproduced so that a `.vgeo` payload and a `MeshletBatch`
- * payload of the same geometry differ nowhere.
+ * `ENCODED_ATTRIBUTE_DEFAULT_VALUES`, in this format's own attribute order, so that a `.vgeo`
+ * payload and a `MeshletBatch` payload of the same geometry differ nowhere.
  *
  * Colour's default is opaque white with its alpha byte set, while `encode_colors_to_u32` writes only
  * three channels and leaves alpha zero. That asymmetry is Shade's, and matching it is the point.
  *
+ * Exported so that `vgeo_encode_cluster_payload.spec.js` can hold it against Shade's own table
+ * rather than against nothing — it is the fourth of the four tables the byte-compatibility claim
+ * rests on, and was for a long time the only one no test compared.
+ *
  * @readonly
  * @type {number[][]}
  */
-const ENCODED_DEFAULTS = [];
+export const ENCODED_DEFAULTS = [];
 
 {
     const normal = new Uint32Array(1);
@@ -113,13 +117,15 @@ function is_constant(encoded, words, vertex_count) {
 /**
  * @param {Float32Array} positions `vertex_count * 3` cluster-local coordinates
  * @param {Uint8Array} indices `triangle_count * 3` cluster-local vertex indices
- * @param {Uint32Array} vertex_ids `vertex_count` source vertex ids, for the attribute lookup
+ * @param {Uint32Array} attribute_ids `vertex_count` ids into `layers`, one per output vertex. What
+ *     they are ids *of* is the layers' business and not this function's — today they are corners,
+ *     because that is where an appearance can differ from its neighbour's across a seam.
  * @param {(BinaryDataLayer|null)[]} layers one slot per {@link VGEO_ATTRIBUTES} entry, null where
  *     the geometry does not carry that channel
  * @returns {VGeoEncodedPayload}
  */
-export function vgeo_encode_cluster_payload(positions, indices, vertex_ids, layers) {
-    const vertex_count = vertex_ids.length;
+export function vgeo_encode_cluster_payload(positions, indices, attribute_ids, layers) {
+    const vertex_count = attribute_ids.length;
     const triangle_count = indices.length / 3;
 
     assert.isPositiveInteger(triangle_count, 'triangle_count');
@@ -159,7 +165,9 @@ export function vgeo_encode_cluster_payload(positions, indices, vertex_ids, laye
             plain.set(positions);
         } else {
             for (let vertex = 0; vertex < vertex_count; vertex++) {
-                vgeo_attributes_read(plain, vertex * components, layers, attribute, vertex_ids[vertex]);
+                vgeo_attributes_read(
+                    plain, vertex * components, layers, attribute, attribute_ids[vertex]
+                );
             }
         }
 

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

@@ -1 +1 @@
-{"version":3,"file":"VGeoContainerReader.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/geometry/virtual/format/read/VGeoContainerReader.js"],"names":[],"mappings":"AA+BA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AACH;IA8PI;;;;;;;;OAQG;IACH,oBANW,cAAc,YACd,eAAe,GACb,QAAQ,mBAAmB,CAAC,CAUxC;IAhJD;;;OAGG;IACH,oBAHW,cAAc,YACd,eAAe,EAOzB;IArID;;OAEG;IACH,QAFU,mBAAmB,CAEV;IAEnB;;;;OAIG;IACH,WAFU,aAAa,GAAC,SAAS,CAEX;IA6HtB;;OAEG;IACH,2DAEC;IAED;;OAEG;IACH,+BAEC;IAED;;OAEG;IACH,kCAEC;IAED;;;;;;;;;;;;;OAaG;IACH,6BAEC;IAED;;OAEG;IACH,iCAEC;IAED;;;;;;;;;OASG;IACH,2CAEC;IAED;;;;;OAKG;IACH,yBAEC;IAED;;;OAGG;IACH,qCAEC;IAED;;;;;;;;;;;;OAYG;IACH,6CAEC;IAED;;;;;;;;;OASG;IACH,gDAEC;IAED;;;;OAIG;IACH,kBAFa,iBAAiB,QAAQ,CAAC,CAItC;IA0FD;;;;;;;;OAQG;IACH,iBAHW,MAAM,GACJ,QAAQ,GAAC,SAAS,CAI9B;IAED;;;OAGG;IACH,wBAHW,MAAM,GACJ,OAAO,CAInB;IAED;;;;;;;;;;;OAWG;IACH,iCAHW,MAAM,GACJ,MAAM,CAoBlB;IAED;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,0BAJW,MAAM,SACN,MAAM,GACJ,OAAO,CAUnB;IAoOD;;;;;OAKG;IACH,2BAHW,MAAM,GACJ,OAAO,CAInB;IAED;;;;;;;;;OASG;IACH,8BAHW,MAAM,GACJ,MAAM,GAAC,SAAS,CAI5B;IAED;;;OAGG;IACH,cAFa,iBAAiB,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAI9C;IAED;;;;;;;;;;;;OAYG;IACH,8BAHW,MAAM,GACJ,MAAM,CAYlB;IAED;;;;;;;;;;;;OAYG;IACH,oBAPW,MAAM,gBACN,MAAM,cACN,MAAM,GACJ,QAAQ,QAAQ,CAAC,CAoC7B;IAED;;;;;;;;;;;;;;;;OAgBG;IACH,mBAHW,MAAM,GACJ,OAAO,CAYnB;IAED;;;OAGG;IACH,cAFa,MAAM,CAYlB;IA6CD;;;;;;;;;OASG;IACH,YAHW,QAAQ,GACN,QAAQ,CAqBpB;IAED;;;;;;;OAOG;IACH,4BAJW,MAAM,UACN,MAAM,GACJ,IAAI,CAMhB;IACD;;;;;OAKG;IACH,mBAHW,YAAY,GACV,QAAQ,QAAQ,CAAC,CAI7B;IAED;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACH,qBANW,YAAY,EAAE,UACd,MAAM,WAEN,WAAW,GACT,QAAQ,QAAQ,EAAE,CAAC,CA+D/B;IAED;;;;;;;;;;OAUG;IACH,kBAHW,MAAM,GACJ,OAAO,CAsDnB;IAED;;;;OAIG;IACH,aAFa,MAAM,CAYlB;IAED;;;;;;;;OAQG;IACH,kBAFa,QAAQ,aAAa,CAAC,CAkBlC;IAED;;;;;;;;OAQG;IACH,uCAHoB,MAAM,QAAE,MAAM,KAAG,IAAI,GAC5B,QAAQ,IAAI,CAAC,CAMzB;IAED;;;;;;;;;OASG;IACH,YAFa,QAAQ,UAAU,EAAE,CAAC,CAYjC;IAiCD;;;;;;;;;OASG;IACH,gBAFa,MAAM,CAQlB;;CA6BJ;6BAvvCY,OAAO,qBAAqB,EAAE,cAAc;kCAC5C,OAAO,0BAA0B,EAAE,mBAAmB;yBACtD,OAAO,kBAAkB,EAAE,UAAU;4BACrC,OAAO,oBAAoB,EAAE,aAAa;uBAC1C,OAAO,eAAe,EAAE,QAAQ;2BAChC,OAAO,mBAAmB,EAAE,YAAY;gCAXrB,sBAAsB"}
+{"version":3,"file":"VGeoContainerReader.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/geometry/virtual/format/read/VGeoContainerReader.js"],"names":[],"mappings":"AA8BA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AACH;IA8PI;;;;;;;;OAQG;IACH,oBANW,cAAc,YACd,eAAe,GACb,QAAQ,mBAAmB,CAAC,CAUxC;IAhJD;;;OAGG;IACH,oBAHW,cAAc,YACd,eAAe,EAOzB;IArID;;OAEG;IACH,QAFU,mBAAmB,CAEV;IAEnB;;;;OAIG;IACH,WAFU,aAAa,GAAC,SAAS,CAEX;IA6HtB;;OAEG;IACH,2DAEC;IAED;;OAEG;IACH,+BAEC;IAED;;OAEG;IACH,kCAEC;IAED;;;;;;;;;;;;;OAaG;IACH,6BAEC;IAED;;OAEG;IACH,iCAEC;IAED;;;;;;;;;OASG;IACH,2CAEC;IAED;;;;;OAKG;IACH,yBAEC;IAED;;;OAGG;IACH,qCAEC;IAED;;;;;;;;;;;;OAYG;IACH,6CAEC;IAED;;;;;;;;;OASG;IACH,gDAEC;IAED;;;;OAIG;IACH,kBAFa,iBAAiB,QAAQ,CAAC,CAItC;IA0FD;;;;;;;;OAQG;IACH,iBAHW,MAAM,GACJ,QAAQ,GAAC,SAAS,CAI9B;IAED;;;OAGG;IACH,wBAHW,MAAM,GACJ,OAAO,CAInB;IAED;;;;;;;;;;;OAWG;IACH,iCAHW,MAAM,GACJ,MAAM,CAoBlB;IAED;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,0BAJW,MAAM,SACN,MAAM,GACJ,OAAO,CAUnB;IAoOD;;;;;OAKG;IACH,2BAHW,MAAM,GACJ,OAAO,CAInB;IAED;;;;;;;;;OASG;IACH,8BAHW,MAAM,GACJ,MAAM,GAAC,SAAS,CAI5B;IAED;;;OAGG;IACH,cAFa,iBAAiB,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAI9C;IAED;;;;;;;;;;;;OAYG;IACH,8BAHW,MAAM,GACJ,MAAM,CAYlB;IAED;;;;;;;;;;;;OAYG;IACH,oBAPW,MAAM,gBACN,MAAM,cACN,MAAM,GACJ,QAAQ,QAAQ,CAAC,CAoC7B;IAED;;;;;;;;;;;;;;;;OAgBG;IACH,mBAHW,MAAM,GACJ,OAAO,CAYnB;IAED;;;OAGG;IACH,cAFa,MAAM,CAYlB;IA8CD;;;;;;;;;OASG;IACH,YAHW,QAAQ,GACN,QAAQ,CAqBpB;IAED;;;;;;;OAOG;IACH,4BAJW,MAAM,UACN,MAAM,GACJ,IAAI,CAMhB;IACD;;;;;OAKG;IACH,mBAHW,YAAY,GACV,QAAQ,QAAQ,CAAC,CAI7B;IAED;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACH,qBANW,YAAY,EAAE,UACd,MAAM,WAEN,WAAW,GACT,QAAQ,QAAQ,EAAE,CAAC,CA+D/B;IAED;;;;;;;;;;OAUG;IACH,kBAHW,MAAM,GACJ,OAAO,CAsDnB;IAED;;;;OAIG;IACH,aAFa,MAAM,CAYlB;IAED;;;;;;;;OAQG;IACH,kBAFa,QAAQ,aAAa,CAAC,CAkBlC;IAED;;;;;;;;OAQG;IACH,uCAHoB,MAAM,QAAE,MAAM,KAAG,IAAI,GAC5B,QAAQ,IAAI,CAAC,CAMzB;IAED;;;;;;;;;OASG;IACH,YAFa,QAAQ,UAAU,EAAE,CAAC,CAYjC;IAiCD;;;;;;;;;OASG;IACH,gBAFa,MAAM,CAQlB;;CA6BJ;6BAxvCY,OAAO,qBAAqB,EAAE,cAAc;kCAC5C,OAAO,0BAA0B,EAAE,mBAAmB;yBACtD,OAAO,kBAAkB,EAAE,UAAU;4BACrC,OAAO,oBAAoB,EAAE,aAAa;uBAC1C,OAAO,eAAe,EAAE,QAAQ;2BAChC,OAAO,mBAAmB,EAAE,YAAY;gCAXrB,sBAAsB"}

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

@@ -1,7 +1,6 @@
 import { assert } from "../../../../../../core/assert.js";
 import { VGEO_NO_CHILD } from "../cluster/VGEO_NO_CHILD.js";
 import { VGEO_SAME_PAGE } from "../cluster/VGEO_SAME_PAGE.js";
-import { vgeo_read_frame_extent } from "../frame/vgeo_read_frame_extent.js";
 import { VGeoPageFetcherCore } from "./VGeoPageFetcherCore.js";
 import { VGeoReadOptions } from "./VGeoReadOptions.js";
 import { vgeo_read_directory } from "./vgeo_read_directory.js";
@@ -885,6 +884,7 @@ export class VGeoContainerReader {
             this.#core = new VGeoPageFetcherCore({
                 read: (offset, length, signal) => this.#read(offset, length, signal),
                 asset_id_low64: () => this.header.asset_id_low64,
+                format_version: () => this.header.format_version,
                 verify_frames: this.#options.verify_frames,
                 fetch_retries: this.#options.fetch_retries,
                 fetch_retry_backoff_ms: this.#options.fetch_retry_backoff_ms,
@@ -1162,7 +1162,7 @@ export class VGeoContainerReader {
 
         const bytes = await this.#read(header.directory_offset, end - header.directory_offset);
 
-        this.directory = vgeo_read_directory(bytes, header.total_pages);
+        this.directory = vgeo_read_directory(bytes, header.total_pages, header.format_version);
 
         return this.directory;
     }

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

@@ -34,13 +34,15 @@ export class VGeoDirectory {
      */
     decoded_size: Uint32Array;
     /**
-     * @type {Uint8Array}
+     * The page's band. A byte each in the record through `format_version` 5 and a `u16` each from
+     * 6 on, but one array either way — the reader takes the container's version and this does not.
+     * @type {Uint16Array}
      */
-    min_level: Uint8Array;
+    min_level: Uint16Array;
     /**
-     * @type {Uint8Array}
+     * @type {Uint16Array}
      */
-    max_level: Uint8Array;
+    max_level: Uint16Array;
     /**
      * Bit 0 is `VGEO_DIRECTORY_FLAG_ROOT_PAGE`.
      * @type {Uint16Array}

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

@@ -1 +1 @@
-{"version":3,"file":"VGeoDirectory.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/geometry/virtual/format/read/VGeoDirectory.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH;IACI;;OAEG;IACH,YAFU,MAAM,CAED;IAEf;;;;OAIG;IACH,cAFU,YAAY,CAEa;IAEnC;;;OAGG;IACH,YAFU,WAAW,CAEW;IAEhC;;OAEG;IACH,cAFU,WAAW,CAEa;IAElC;;OAEG;IACH,WAFU,UAAU,CAEU;IAE9B;;OAEG;IACH,WAFU,UAAU,CAEU;IAE9B;;;OAGG;IACH,OAFU,WAAW,CAEM;IAE3B;;OAEG;IACH,aAFU,WAAW,CAEY;IAEjC;;OAEG;IACH,eAFU,WAAW,CAEc;IAEnC;;;;OAIG;IACH,kCAQC;CACJ"}
+{"version":3,"file":"VGeoDirectory.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/geometry/virtual/format/read/VGeoDirectory.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH;IACI;;OAEG;IACH,YAFU,MAAM,CAED;IAEf;;;;OAIG;IACH,cAFU,YAAY,CAEa;IAEnC;;;OAGG;IACH,YAFU,WAAW,CAEW;IAEhC;;OAEG;IACH,cAFU,WAAW,CAEa;IAElC;;;;OAIG;IACH,WAFU,WAAW,CAEU;IAE/B;;OAEG;IACH,WAFU,WAAW,CAEU;IAE/B;;;OAGG;IACH,OAFU,WAAW,CAEM;IAE3B;;OAEG;IACH,aAFU,WAAW,CAEY;IAEjC;;OAEG;IACH,eAFU,WAAW,CAEc;IAEnC;;;;OAIG;IACH,kCAQC;CACJ"}

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

@@ -38,14 +38,16 @@ export class VGeoDirectory {
     decoded_size = new Uint32Array(0);
 
     /**
-     * @type {Uint8Array}
+     * The page's band. A byte each in the record through `format_version` 5 and a `u16` each from
+     * 6 on, but one array either way — the reader takes the container's version and this does not.
+     * @type {Uint16Array}
      */
-    min_level = new Uint8Array(0);
+    min_level = new Uint16Array(0);
 
     /**
-     * @type {Uint8Array}
+     * @type {Uint16Array}
      */
-    max_level = new Uint8Array(0);
+    max_level = new Uint16Array(0);
 
     /**
      * Bit 0 is `VGEO_DIRECTORY_FLAG_ROOT_PAGE`.

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

@@ -210,10 +210,21 @@ export class VGeoPage {
      */
     parent_sphere: Float32Array;
     /**
-     * `4 · cluster_count` — each cluster's own tight sphere, for culling and never for the cut test.
+     * `6 · cluster_count` — each cluster's AABB unioned with every AABB reachable below it through
+     * child groups, in `min xyz, max xyz` order.
+     *
+     * The cut's per-cluster frustum test reads it, and it has to bound the subtree rather than the
+     * cluster because culling a cluster takes its whole child group out of the descent
+     * (`CULL_PLAN_2026_09_16` §1). A leaf's equals its {@link aabb}.
+     *
+     * A container written before `format_version` 5 carries no such field, and the decoder stands
+     * the cube around `self_sphere` in for it: that sphere contains every vertex below the cluster
+     * (format §11.7), so the cube is a conservative subtree bound and culls nothing the sphere test
+     * beside it would not.
+     *
      * @type {Float32Array}
      */
-    bounds_sphere: Float32Array;
+    subtree_aabb: Float32Array;
     /**
      * `6 · cluster_count` — each cluster's object-space AABB, in `min xyz, max xyz` order.
      *

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;;;;;;;;;;;;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;;;;;;;;;OASG;IACH,oBAFU,WAAW,CAEmB;IAExC;;;;;;;;;;;OAWG;IACH,YAFU,WAAW,CAEW;IAEhC;;;OAGG;IACH,gBAFU,WAAW,CAEe;IAEpC;;;;;;;;;OASG;IACH,mBAFU,WAAW,CAEkB;IAEvC;;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"}
+{"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;;;;;;;;;OASG;IACH,oBAFU,WAAW,CAEmB;IAExC;;;;;;;;;;;OAWG;IACH,YAFU,WAAW,CAEW;IAEhC;;;OAGG;IACH,gBAFU,WAAW,CAEe;IAEpC;;;;;;;;;OASG;IACH,mBAFU,WAAW,CAEkB;IAEvC;;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;;;;;;;;;;;;;;OAcG;IACH,cAFU,YAAY,CAEa;IAEnC;;;;;;;;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

@@ -242,10 +242,21 @@ export class VGeoPage {
     parent_sphere = new Float32Array(0);
 
     /**
-     * `4 · cluster_count` — each cluster's own tight sphere, for culling and never for the cut test.
+     * `6 · cluster_count` — each cluster's AABB unioned with every AABB reachable below it through
+     * child groups, in `min xyz, max xyz` order.
+     *
+     * The cut's per-cluster frustum test reads it, and it has to bound the subtree rather than the
+     * cluster because culling a cluster takes its whole child group out of the descent
+     * (`CULL_PLAN_2026_09_16` §1). A leaf's equals its {@link aabb}.
+     *
+     * A container written before `format_version` 5 carries no such field, and the decoder stands
+     * the cube around `self_sphere` in for it: that sphere contains every vertex below the cluster
+     * (format §11.7), so the cube is a conservative subtree bound and culls nothing the sphere test
+     * beside it would not.
+     *
      * @type {Float32Array}
      */
-    bounds_sphere = new Float32Array(0);
+    subtree_aabb = new Float32Array(0);
 
     /**
      * `6 · cluster_count` — each cluster's object-space AABB, in `min xyz, max xyz` order.

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

@@ -44,13 +44,17 @@ export class VGeoPageFetcherCore {
      * @param {bigint|function(): bigint} options.asset_id_low64 what frames are checksummed against;
      *     a function when the header is read after construction
      * @param {boolean} [options.verify_frames]
+     * @param {number|function(): number} [options.format_version] the container's, which decides
+     *     how a cluster record is laid out (§7); a function when the header is read after
+     *     construction, as with `asset_id_low64`. A worker is told it with the descriptor.
      * @param {number} [options.fetch_retries] attempts after the first
      * @param {number} [options.fetch_retry_backoff_ms] doubled per attempt
      */
-    constructor({ read, asset_id_low64, verify_frames, fetch_retries, fetch_retry_backoff_ms, }: {
+    constructor({ read, asset_id_low64, verify_frames, format_version, fetch_retries, fetch_retry_backoff_ms, }: {
         read: (arg0: number, arg1: number, arg2: AbortSignal | undefined) => Promise<Uint8Array>;
         asset_id_low64: bigint | (() => bigint);
         verify_frames?: boolean;
+        format_version?: number | (() => number);
         fetch_retries?: number;
         fetch_retry_backoff_ms?: number;
     });

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

@@ -1 +1 @@
-{"version":3,"file":"VGeoPageFetcherCore.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/geometry/virtual/format/read/VGeoPageFetcherCore.js"],"names":[],"mappings":"AAaA;;;;;;GAMG;AACH;IAYI;;;;OAIG;IACH,qBAJW,MAAM,cACN,OAAO,UACP,MAAM,EAQhB;IAtBD;;OAEG;IACH,YAFU,OAAO,CAEN;IAEX;;;OAGG;IACH,QAFU,MAAM,CAET;CAcV;AAED;;;;;;;;;;;;;GAaG;AACH;IA0BI;;;;;;;;;OASG;IACH;QARgF,IAAI,SAAhE,MAAM,QAAE,MAAM,QAAE,WAAW,iBAAI,QAAQ,UAAU,CAAC;QAExB,cAAc,EAAjD,MAAM,UAAa,MAAM,CAAA;QAEP,aAAa,GAA/B,OAAO;QACU,aAAa,GAA9B,MAAM;QACW,sBAAsB,GAAvC,MAAM;OAkBhB;IAED;;;;;;;OAOG;IACH,kBAPW,MAAM,gBACN,MAAM,cACN,MAAM,WACN,WAAW,GACT,QAAQ,QAAQ,CAAC,CA4B7B;;CAuDJ;uBAlMY,OAAO,eAAe,EAAE,QAAQ"}
+{"version":3,"file":"VGeoPageFetcherCore.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/geometry/virtual/format/read/VGeoPageFetcherCore.js"],"names":[],"mappings":"AAcA;;;;;;GAMG;AACH;IAYI;;;;OAIG;IACH,qBAJW,MAAM,cACN,OAAO,UACP,MAAM,EAQhB;IAtBD;;OAEG;IACH,YAFU,OAAO,CAEN;IAEX;;;OAGG;IACH,QAFU,MAAM,CAET;CAcV;AAED;;;;;;;;;;;;;GAaG;AACH;IA+BI;;;;;;;;;;;;OAYG;IACH;QAXgF,IAAI,SAAhE,MAAM,QAAE,MAAM,QAAE,WAAW,iBAAI,QAAQ,UAAU,CAAC;QAExB,cAAc,EAAjD,MAAM,UAAa,MAAM,CAAA;QAEP,aAAa,GAA/B,OAAO;QAC6B,cAAc,GAAlD,MAAM,UAAa,MAAM,CAAA;QAGR,aAAa,GAA9B,MAAM;QACW,sBAAsB,GAAvC,MAAM;OAoBhB;IAED;;;;;;;OAOG;IACH,kBAPW,MAAM,gBACN,MAAM,cACN,MAAM,WACN,WAAW,GACT,QAAQ,QAAQ,CAAC,CA4B7B;;CAyDJ;uBA9MY,OAAO,eAAe,EAAE,QAAQ"}

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

@@ -1,6 +1,7 @@
 import { assert } from "../../../../../../core/assert.js";
 import { BinaryBuffer } from "../../../../../../core/binary/BinaryBuffer.js";
 import { vgeo_compute_frame_checksum } from "../checksum/vgeo_compute_frame_checksum.js";
+import { VGEO_FORMAT_VERSION } from "../header/VGEO_FORMAT_VERSION.js";
 import { VGEO_FRAME_OFFSET } from "../frame/VGEO_FRAME_OFFSET.js";
 import { vgeo_read_frame_extent } from "../frame/vgeo_read_frame_extent.js";
 import { vgeo_read_page } from "./vgeo_read_page.js";
@@ -74,6 +75,11 @@ export class VGeoPageFetcherCore {
      */
     #verify_frames;
 
+    /**
+     * @type {number|function(): number}
+     */
+    #format_version;
+
     /**
      * @type {number}
      */
@@ -91,6 +97,9 @@ export class VGeoPageFetcherCore {
      * @param {bigint|function(): bigint} options.asset_id_low64 what frames are checksummed against;
      *     a function when the header is read after construction
      * @param {boolean} [options.verify_frames]
+     * @param {number|function(): number} [options.format_version] the container's, which decides
+     *     how a cluster record is laid out (§7); a function when the header is read after
+     *     construction, as with `asset_id_low64`. A worker is told it with the descriptor.
      * @param {number} [options.fetch_retries] attempts after the first
      * @param {number} [options.fetch_retry_backoff_ms] doubled per attempt
      */
@@ -98,6 +107,7 @@ export class VGeoPageFetcherCore {
                     read,
                     asset_id_low64,
                     verify_frames = false,
+                    format_version = VGEO_FORMAT_VERSION,
                     fetch_retries = 2,
                     fetch_retry_backoff_ms = 50,
                 }) {
@@ -108,6 +118,7 @@ export class VGeoPageFetcherCore {
         this.#read = read;
         this.#asset_id_low64 = asset_id_low64;
         this.#verify_frames = verify_frames;
+        this.#format_version = format_version;
         this.#fetch_retries = fetch_retries;
         this.#fetch_retry_backoff_ms = fetch_retry_backoff_ms;
     }
@@ -161,7 +172,9 @@ export class VGeoPageFetcherCore {
             this.#verify_frame(bytes, page_index);
         }
 
-        const page = vgeo_read_page(bytes, page_index);
+        const page = await vgeo_read_page(bytes, page_index, typeof this.#format_version === 'function'
+            ? this.#format_version()
+            : this.#format_version);
 
         page.frame_offset = frame_offset;
 

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

@@ -1 +1 @@
-{"version":3,"file":"vgeo_page_worker_serve.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/geometry/virtual/format/read/vgeo_page_worker_serve.js"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;GAgBG;AACH,6CANW;IAAC,SAAS,EAAE,WAAS,IAAI,CAAC;IAAC,WAAW,SAAW,MAAM,QAAE,WAAW,EAAE,iBAAI,IAAI,CAAA;CAAC,GAC7E,IAAI,CA+EhB"}
+{"version":3,"file":"vgeo_page_worker_serve.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/geometry/virtual/format/read/vgeo_page_worker_serve.js"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;GAgBG;AACH,6CANW;IAAC,SAAS,EAAE,WAAS,IAAI,CAAC;IAAC,WAAW,SAAW,MAAM,QAAE,WAAW,EAAE,iBAAI,IAAI,CAAA;CAAC,GAC7E,IAAI,CAgFhB"}

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

@@ -62,6 +62,7 @@ export function vgeo_page_worker_serve(port) {
             core = new VGeoPageFetcherCore({
                 read: (offset, length, signal) => source.read(offset, length, signal),
                 asset_id_low64: data.asset_id_low64,
+                format_version: data.format_version,
                 verify_frames: data.verify_frames,
                 fetch_retries: data.fetch_retries,
                 fetch_retry_backoff_ms: data.fetch_retry_backoff_ms,

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

@@ -12,12 +12,15 @@
  *
  * @param {Uint8Array} bytes the directory region, from its first byte
  * @param {number} page_count `total_pages` from the header
+ * @param {number} [format_version] the container header's, which decides where a record keeps
+ *     everything from `min_level` on (§9). Defaults to the current version, which is what a caller
+ *     holding no header should assume.
  * @returns {VGeoDirectory}
  * @throws {Error} when the bytes are shorter than the records the header says are there
  *
  * @author Alex Goldring
  * @copyright Company Named Limited (c) 2026
  */
-export function vgeo_read_directory(bytes: Uint8Array, page_count: number): VGeoDirectory;
+export function vgeo_read_directory(bytes: Uint8Array, page_count: number, format_version?: number): VGeoDirectory;
 import { VGeoDirectory } from "./VGeoDirectory.js";
 //# sourceMappingURL=vgeo_read_directory.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"vgeo_read_directory.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/geometry/virtual/format/read/vgeo_read_directory.js"],"names":[],"mappings":"AAwBA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,2CARW,UAAU,cACV,MAAM,GACJ,aAAa,CA4CzB;8BAjF6B,oBAAoB"}
+{"version":3,"file":"vgeo_read_directory.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/geometry/virtual/format/read/vgeo_read_directory.js"],"names":[],"mappings":"AAoDA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,2CAXW,UAAU,cACV,MAAM,mBACN,MAAM,GAGJ,aAAa,CAuDzB;8BA1H6B,oBAAoB"}

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

@@ -1,4 +1,5 @@
 import { VGEO_DIRECTORY_RECORD_SIZE } from "../directory/VGEO_DIRECTORY_RECORD_SIZE.js";
+import { VGEO_FORMAT_VERSION } from "../header/VGEO_FORMAT_VERSION.js";
 import { VGeoDirectory } from "./VGeoDirectory.js";
 
 /**
@@ -12,6 +13,33 @@ const LE = true;
  * @enum {number}
  */
 const RECORD = {
+    FRAME_OFFSET: 0,
+    FETCH_SIZE: 8,
+    DECODED_SIZE: 12,
+    /**
+     * A byte each through `format_version` 5, a `u16` each from 6 on — which is what moved
+     * everything below them by two, into the eight bytes this record has always kept reserved. The
+     * record is still 32 bytes and the directory is still `32 * page_count`.
+     */
+    MIN_LEVEL: 16,
+    MAX_LEVEL: 18,
+    FLAGS: 20,
+    GROUP_COUNT: 22,
+    CLUSTER_COUNT: 24,
+};
+
+/**
+ * The same record as `format_version` 5 and earlier laid it out.
+ *
+ * The first three fields did not move, which is why a reader can size and place every fetch in the
+ * file from an old directory without knowing the version. Everything from `min_level` on did, so
+ * reading one of those records by the current offsets hands back a `min_level` with `max_level` in
+ * its high byte and a `cluster_count` taken out of reserved bytes — wrong, quietly, in derived data
+ * that nothing else cross-checks at read time.
+ *
+ * @enum {number}
+ */
+const RECORD_V5 = {
     FRAME_OFFSET: 0,
     FETCH_SIZE: 8,
     DECODED_SIZE: 12,
@@ -36,13 +64,16 @@ const RECORD = {
  *
  * @param {Uint8Array} bytes the directory region, from its first byte
  * @param {number} page_count `total_pages` from the header
+ * @param {number} [format_version] the container header's, which decides where a record keeps
+ *     everything from `min_level` on (§9). Defaults to the current version, which is what a caller
+ *     holding no header should assume.
  * @returns {VGeoDirectory}
  * @throws {Error} when the bytes are shorter than the records the header says are there
  *
  * @author Alex Goldring
  * @copyright Company Named Limited (c) 2026
  */
-export function vgeo_read_directory(bytes, page_count) {
+export function vgeo_read_directory(bytes, page_count, format_version = VGEO_FORMAT_VERSION) {
     const needed = page_count * VGEO_DIRECTORY_RECORD_SIZE;
 
     if (bytes.byteLength < needed) {
@@ -54,14 +85,18 @@ export function vgeo_read_directory(bytes, page_count) {
 
     const data = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
 
+    const legacy = format_version < 6;
+
+    const offsets = legacy ? RECORD_V5 : RECORD;
+
     const result = new VGeoDirectory();
 
     result.page_count = page_count;
     result.frame_offset = new Float64Array(page_count);
     result.fetch_size = new Uint32Array(page_count);
     result.decoded_size = new Uint32Array(page_count);
-    result.min_level = new Uint8Array(page_count);
-    result.max_level = new Uint8Array(page_count);
+    result.min_level = new Uint16Array(page_count);
+    result.max_level = new Uint16Array(page_count);
     result.flags = new Uint16Array(page_count);
     result.group_count = new Uint16Array(page_count);
     result.cluster_count = new Uint16Array(page_count);
@@ -69,14 +104,21 @@ export function vgeo_read_directory(bytes, page_count) {
     for (let i = 0; i < page_count; i++) {
         const record = i * VGEO_DIRECTORY_RECORD_SIZE;
 
-        result.frame_offset[i] = Number(data.getBigUint64(record + RECORD.FRAME_OFFSET, LE));
-        result.fetch_size[i] = data.getUint32(record + RECORD.FETCH_SIZE, LE);
-        result.decoded_size[i] = data.getUint32(record + RECORD.DECODED_SIZE, LE);
-        result.min_level[i] = data.getUint8(record + RECORD.MIN_LEVEL);
-        result.max_level[i] = data.getUint8(record + RECORD.MAX_LEVEL);
-        result.flags[i] = data.getUint16(record + RECORD.FLAGS, LE);
-        result.group_count[i] = data.getUint16(record + RECORD.GROUP_COUNT, LE);
-        result.cluster_count[i] = data.getUint16(record + RECORD.CLUSTER_COUNT, LE);
+        result.frame_offset[i] = Number(data.getBigUint64(record + offsets.FRAME_OFFSET, LE));
+        result.fetch_size[i] = data.getUint32(record + offsets.FETCH_SIZE, LE);
+        result.decoded_size[i] = data.getUint32(record + offsets.DECODED_SIZE, LE);
+
+        result.min_level[i] = legacy
+            ? data.getUint8(record + offsets.MIN_LEVEL)
+            : data.getUint16(record + offsets.MIN_LEVEL, LE);
+
+        result.max_level[i] = legacy
+            ? data.getUint8(record + offsets.MAX_LEVEL)
+            : data.getUint16(record + offsets.MAX_LEVEL, LE);
+
+        result.flags[i] = data.getUint16(record + offsets.FLAGS, LE);
+        result.group_count[i] = data.getUint16(record + offsets.GROUP_COUNT, LE);
+        result.cluster_count[i] = data.getUint16(record + offsets.CLUSTER_COUNT, LE);
     }
 
     return result;

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,CAiH/B;AAED;;;;;;;;;;;;;;;GAeG;AACH,+CAJW,UAAU,GACR,MAAM,CA4BlB;AAvLD;;;;;;;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,CAqH/B;AAED;;;;;;;;;;;;;;;GAeG;AACH,+CAJW,UAAU,GACR,MAAM,CA4BlB;AA3LD;;;;;;;GAOG;AACH,kCAFU,MAAM,CAEoC;oCAjBhB,0BAA0B"}

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

@@ -128,7 +128,11 @@ export function vgeo_read_header(bytes) {
         result.object_bounds[i] = view.getFloat32(VGEO_HEADER_OFFSET.OBJECT_BOUNDS + i * 4, LE);
     }
 
-    const level_count = view.getUint8(VGEO_HEADER_OFFSET.LEVEL_COUNT);
+    /*
+     A `u16` since `format_version` 6, over a byte that was reserved and written as zero — so this
+     reads every earlier container correctly as well, and no version test is needed for it.
+    */
+    const level_count = view.getUint16(VGEO_HEADER_OFFSET.LEVEL_COUNT, LE);
 
     const table_end = VGEO_HEADER_SIZE + level_count * VGEO_LEVEL_RECORD_SIZE;
 
@@ -188,8 +192,8 @@ export function vgeo_resident_head_size(bytes) {
         );
     }
 
-    const table_end =
-        VGEO_HEADER_SIZE + view.getUint8(VGEO_HEADER_OFFSET.LEVEL_COUNT) * VGEO_LEVEL_RECORD_SIZE;
+    const table_end = VGEO_HEADER_SIZE
+        + view.getUint16(VGEO_HEADER_OFFSET.LEVEL_COUNT, LE) * VGEO_LEVEL_RECORD_SIZE;
 
     const root_end = Number(view.getBigUint64(VGEO_HEADER_OFFSET.ROOT_PAGE_OFFSET, LE))
         + view.getUint32(VGEO_HEADER_OFFSET.ROOT_PAGE_FETCH_SIZE, LE);

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

@@ -11,16 +11,26 @@
  * `decoded_size` is four bytes of untrusted file, and honouring one that no block of that length
  * could produce turns corruption into an out-of-memory throw rather than a rejected file.
  *
+ * It is asynchronous because {@link VGEO_CODEC_DEFLATE} is — the platform only offers its zlib as a
+ * stream — and a reader that could not read a deflate page would be refusing assets over an
+ * implementation detail. Everything after the decode is the same synchronous walk of the page's own
+ * tables it has always been, and a raw or LZ4 page never leaves the caller's turn.
+ *
  * @param {Uint8Array} frame_bytes the frame's exact range, from its first byte
  * @param {number} page_index the frame ordinal this range was fetched as — the caller knows it from
  *     the child-table entry or the directory record that named the range
- * @returns {VGeoPage}
+ * @param {number} [format_version] the container header's, which decides how a cluster record
+ *     (§7) and a page header (§6.1) are laid out: version 5 put `subtree_aabb` at offset 40 and
+ *     moved everything after it, and version 6 widened the page band to `u16` over
+ *     `node_table_offset`. Defaults to the current version, which is what a caller holding no
+ *     header should assume — the frame itself does not carry one.
+ * @returns {Promise<VGeoPage>}
  * @throws {Error} when the range is not a frame, uses a codec with no decoder here, or does not
  *     decode as its own header says
  *
  * @author Alex Goldring
  * @copyright Company Named Limited (c) 2026
  */
-export function vgeo_read_page(frame_bytes: Uint8Array, page_index: number): VGeoPage;
+export function vgeo_read_page(frame_bytes: Uint8Array, page_index: number, format_version?: number): Promise<VGeoPage>;
 import { VGeoPage } from "./VGeoPage.js";
 //# sourceMappingURL=vgeo_read_page.d.ts.map

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":"AAqCA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,4CAVW,UAAU,cACV,MAAM,GAEJ,QAAQ,CAiFpB;yBAhHwB,eAAe"}
+{"version":3,"file":"vgeo_read_page.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/geometry/virtual/format/read/vgeo_read_page.js"],"names":[],"mappings":"AA0CA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,4CAfW,UAAU,cACV,MAAM,mBAEN,MAAM,GAKJ,QAAQ,QAAQ,CAAC,CA+F7B;yBAxIwB,eAAe"}