@woosh/meep-engine 3.28.0 → 3.29.0

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":"AAsCA;;;;;;;;;;;;;;;;;;;;;;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"}

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

@@ -3,10 +3,13 @@ import { VGEO_ATTRIBUTES } from "../attribute/VGEO_ATTRIBUTES.js";
 import { VGEO_CHILD_OFFSET } from "../frame/VGEO_CHILD_OFFSET.js";
 import { VGEO_CHILD_TABLE_ENTRY_SIZE } from "../frame/VGEO_CHILD_TABLE_ENTRY_SIZE.js";
 import { VGEO_CLUSTER_OFFSET } from "../cluster/VGEO_CLUSTER_OFFSET.js";
+import { VGEO_CLUSTER_OFFSET_V4 } from "../cluster/VGEO_CLUSTER_OFFSET_V4.js";
 import { VGEO_CLUSTER_RECORD_SIZE } from "../cluster/VGEO_CLUSTER_RECORD_SIZE.js";
+import { VGEO_CODEC_DEFLATE } from "../frame/VGEO_CODEC_DEFLATE.js";
 import { VGEO_CODEC_LZ4 } from "../frame/VGEO_CODEC_LZ4.js";
 import { VGEO_CODEC_RAW } from "../frame/VGEO_CODEC_RAW.js";
 import { vgeo_decode_frame_blob } from "../frame/vgeo_decode_frame_blob.js";
+import { VGEO_FORMAT_VERSION } from "../header/VGEO_FORMAT_VERSION.js";
 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";
@@ -18,6 +21,7 @@ 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";
+import { VGEO_PAGE_OFFSET_V5 } from "../page/VGEO_PAGE_OFFSET_V5.js";
 import { VGEO_PARENT_ENTRY_SIZE } from "../page/VGEO_PARENT_ENTRY_SIZE.js";
 import { VGEO_PARENT_PAGE_ENTRY_SIZE } from "../page/VGEO_PARENT_PAGE_ENTRY_SIZE.js";
 import { vgeo_read_frame_extent } from "../frame/vgeo_read_frame_extent.js";
@@ -49,17 +53,27 @@ const NORMAL_COMPRESSION_FLAG = VGEO_ATTRIBUTES[VGEO_ATTRIBUTE.NORMAL].compressi
  * `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, page_index) {
+export async function vgeo_read_page(frame_bytes, page_index, format_version = VGEO_FORMAT_VERSION) {
     const frame_view = new DataView(
         frame_bytes.buffer, frame_bytes.byteOffset, frame_bytes.byteLength
     );
@@ -89,10 +103,15 @@ export function vgeo_read_page(frame_bytes, page_index) {
     // decoder indexes `frame_bytes` with, and the caller keeps the absolute one.
     const frame = vgeo_read_frame_extent(frame_view, 0, page_index);
 
-    if (frame.codec !== VGEO_CODEC_RAW && frame.codec !== VGEO_CODEC_LZ4) {
+    if (
+        frame.codec !== VGEO_CODEC_RAW
+        && frame.codec !== VGEO_CODEC_LZ4
+        && frame.codec !== VGEO_CODEC_DEFLATE
+    ) {
         throw new Error(
             `page ${page_index} uses codec ${frame.codec};`
-            + ` this reader decodes ${VGEO_CODEC_RAW} (raw) and ${VGEO_CODEC_LZ4} (lz4)`
+            + ` this reader decodes ${VGEO_CODEC_RAW} (raw), ${VGEO_CODEC_LZ4} (lz4)`
+            + ` and ${VGEO_CODEC_DEFLATE} (deflate)`
         );
     }
 
@@ -120,16 +139,25 @@ export function vgeo_read_page(frame_bytes, page_index) {
 
     const bytes = new Uint8Array(frame.decoded_size);
 
-    vgeo_decode_frame_blob(bytes, 0, frame_bytes, frame);
+    await vgeo_decode_frame_blob(bytes, 0, frame_bytes, frame);
 
     result.bytes = bytes;
     result.data = new DataView(bytes.buffer);
 
+    /*
+     Version 6 widened `min_level` and `max_level` to `u16` and spent `node_table_offset` on the
+     four bytes, so the page header's fields at offsets 4..8 and 20..24 mean different things either
+     side of it. Everything else in a page — the group table's base, the other table offsets, the
+     parent section, the metric — is where it always was, which is why only these two readers take
+     the flag.
+    */
+    const legacy_page = format_version < 6;
+
     read_child_table(result, frame_view, frame);
-    read_page_header(result);
+    read_page_header(result, legacy_page);
     read_group_table(result);
-    read_node_table(result);
-    read_cluster_table(result);
+    read_node_table(result, legacy_page);
+    read_cluster_table(result, format_version);
     read_parent_tables(result);
 
     return result;
@@ -211,13 +239,23 @@ function read_child_table(page, frame_view, frame) {
  * past.
  *
  * @param {VGeoPage} page
+ * @param {boolean} legacy the container is `format_version` 5 or older
  */
-function read_node_table(page) {
+function read_node_table(page, legacy) {
     const data = page.data;
 
     const count = page.node_count;
 
-    const table = data.getUint32(VGEO_PAGE_OFFSET.NODE_TABLE_OFFSET, LE);
+    /*
+     Stored through version 5, derived from 6 on, and the same number either way: the group table
+     follows the page header and the node table follows the group table, both by construction
+     (§6.1). What stands between a `group_count` that is wrong and a read past the page is the
+     extent check below, and that stood there when the offset was stored too.
+    */
+    const table = legacy
+        ? data.getUint32(VGEO_PAGE_OFFSET_V5.NODE_TABLE_OFFSET, LE)
+        : VGEO_PAGE_HEADER_SIZE
+            + data.getUint16(VGEO_PAGE_OFFSET.GROUP_COUNT, LE) * VGEO_GROUP_RECORD_SIZE;
 
     const end = table + count * VGEO_NODE_RECORD_SIZE;
 
@@ -264,8 +302,9 @@ function read_node_table(page) {
 
 /**
  * @param {VGeoPage} page
+ * @param {boolean} legacy the container is `format_version` 5 or older
  */
-function read_page_header(page) {
+function read_page_header(page, legacy) {
     const data = page.data;
 
     if (page.bytes.byteLength < VGEO_PAGE_HEADER_SIZE) {
@@ -276,9 +315,17 @@ function read_page_header(page) {
     }
 
     page.cluster_count = data.getUint16(VGEO_PAGE_OFFSET.CLUSTER_COUNT, LE);
-    page.min_level = data.getUint8(VGEO_PAGE_OFFSET.MIN_LEVEL);
-    page.max_level = data.getUint8(VGEO_PAGE_OFFSET.MAX_LEVEL);
-    page.node_count = data.getUint16(VGEO_PAGE_OFFSET.NODE_COUNT, LE);
+
+    if (legacy) {
+        page.min_level = data.getUint8(VGEO_PAGE_OFFSET_V5.MIN_LEVEL);
+        page.max_level = data.getUint8(VGEO_PAGE_OFFSET_V5.MAX_LEVEL);
+        page.node_count = data.getUint16(VGEO_PAGE_OFFSET_V5.NODE_COUNT, LE);
+    } else {
+        page.min_level = data.getUint16(VGEO_PAGE_OFFSET.MIN_LEVEL, LE);
+        page.max_level = data.getUint16(VGEO_PAGE_OFFSET.MAX_LEVEL, LE);
+        page.node_count = data.getUint16(VGEO_PAGE_OFFSET.NODE_COUNT, LE);
+    }
+
     page.payload_offset = data.getUint32(VGEO_PAGE_OFFSET.PAYLOAD_OFFSET, LE);
     page.payload_size = data.getUint32(VGEO_PAGE_OFFSET.PAYLOAD_SIZE, LE);
 }
@@ -362,10 +409,21 @@ function read_parent_tables(page) {
 
 /**
  * @param {VGeoPage} page
+ * @param {number} format_version of the container this page came out of
  */
-function read_cluster_table(page) {
+function read_cluster_table(page, format_version) {
     const data = page.data;
 
+    /*
+     Version 5 replaced `bounds_sphere` and `cone_reserved` with `subtree_aabb`, which moved every
+     field from offset 40 on, so reading an older record by the current offsets does not lose a
+     field — it takes `child_ref` out of the middle of a box. The fifty gigabytes of converted
+     version-4 containers are why this branch exists rather than a refusal.
+    */
+    const legacy = format_version < 5;
+
+    const offsets = legacy ? VGEO_CLUSTER_OFFSET_V4 : VGEO_CLUSTER_OFFSET;
+
     const count = page.cluster_count;
 
     const table = data.getUint32(VGEO_PAGE_OFFSET.CLUSTER_TABLE_OFFSET, LE);
@@ -381,7 +439,7 @@ 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.subtree_aabb = new Float32Array(count * 6);
     page.aabb = new Float32Array(count * 6);
     page.self_error = new Float32Array(count);
     page.parent_error = new Float32Array(count);
@@ -399,29 +457,49 @@ 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);
+                data.getFloat32(record + offsets.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);
+                data.getFloat32(record + offsets.PARENT_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.aabb[i * 6 + c] = data.getFloat32(record + offsets.AABB + c * 4, LE);
+        }
+
+        if (legacy) {
+            /*
+             The cube around `self_sphere`, which format §11.7 makes contain every vertex below the
+             cluster — so it is a conservative subtree bound, which is the whole of what the cut's
+             test asks of this column. It is looser than the box a version-5 build computes, and
+             looser in exactly the way the sphere the kernel also tests already is.
+            */
+            const cx = page.self_sphere[i * 4];
+            const cy = page.self_sphere[i * 4 + 1];
+            const cz = page.self_sphere[i * 4 + 2];
+            const r = page.self_sphere[i * 4 + 3];
+
+            page.subtree_aabb[i * 6] = cx - r;
+            page.subtree_aabb[i * 6 + 1] = cy - r;
+            page.subtree_aabb[i * 6 + 2] = cz - r;
+            page.subtree_aabb[i * 6 + 3] = cx + r;
+            page.subtree_aabb[i * 6 + 4] = cy + r;
+            page.subtree_aabb[i * 6 + 5] = cz + r;
+        } else {
+            for (let c = 0; c < 6; c++) {
+                page.subtree_aabb[i * 6 + c] =
+                    data.getFloat32(record + offsets.SUBTREE_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);
-        page.child_group[i] = data.getUint16(record + VGEO_CLUSTER_OFFSET.CHILD_GROUP, LE);
-        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);
+        page.self_error[i] = data.getFloat32(record + offsets.SELF_ERROR, LE);
+        page.parent_error[i] = data.getFloat32(record + offsets.PARENT_ERROR, LE);
+        page.child_ref[i] = data.getUint16(record + offsets.CHILD_REF, LE);
+        page.child_group[i] = data.getUint16(record + offsets.CHILD_GROUP, LE);
+        page.encoding_flags[i] = data.getUint32(record + offsets.ENCODING_FLAGS, LE);
+        page.cluster_payload_offset[i] = data.getUint32(record + offsets.PAYLOAD_OFFSET, LE);
+        page.cluster_payload_size[i] = data.getUint32(record + offsets.PAYLOAD_SIZE, LE);
+        page.vertex_count[i] = data.getUint8(record + offsets.VERTEX_COUNT);
+        page.triangle_count[i] = data.getUint8(record + offsets.TRIANGLE_COUNT);
 
         if ((page.encoding_flags[i] & NORMAL_COMPRESSION_FLAG) === 0) {
             page.per_vertex_normal_cluster_count++;

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

@@ -1,10 +1,14 @@
 /**
  * Audit a `.vgeo` file.
  *
+ * It is asynchronous for the one reason the reader is: {@link VGEO_CODEC_DEFLATE} decodes through
+ * the platform's streaming zlib, and a validator that could not decode a deflate page would pass
+ * every file it could not read.
+ *
  * @param {BinaryBuffer} buffer the whole file, with `capacity` equal to its length
- * @returns {VGeoDefect[]} in discovery order; empty when the file satisfies every invariant
+ * @returns {Promise<VGeoDefect[]>} in discovery order; empty when the file satisfies every invariant
  */
-export function vgeo_validate_container(buffer: BinaryBuffer): VGeoDefect[];
+export function vgeo_validate_container(buffer: BinaryBuffer): Promise<VGeoDefect[]>;
 import { BinaryBuffer } from "../../../../../core/binary/BinaryBuffer.js";
 import { VGeoDefect } from "./VGeoDefect.js";
 //# sourceMappingURL=vgeo_validate_container.d.ts.map

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":"AA6tDA;;;;;GAKG;AACH,gDAHW,YAAY,GACV,UAAU,EAAE,CAqFxB;6BAtzD4B,4CAA4C;2BAmD9C,iBAAiB"}
+{"version":3,"file":"vgeo_validate_container.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/geometry/virtual/format/vgeo_validate_container.js"],"names":[],"mappings":"AA+xDA;;;;;;;;;GASG;AACH,gDAHW,YAAY,GACV,QAAQ,UAAU,EAAE,CAAC,CAqFjC;6BA53D4B,4CAA4C;2BAoD9C,iBAAiB"}