@woosh/meep-engine 3.27.0 → 3.29.0

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

@@ -1 +1 @@
-{"version":3,"file":"VGEO_CODEC_LZ4.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/geometry/virtual/format/frame/VGEO_CODEC_LZ4.js"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,6BAFU,MAAM,CAEgB"}
+{"version":3,"file":"VGEO_CODEC_LZ4.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/geometry/virtual/format/frame/VGEO_CODEC_LZ4.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,6BAFU,MAAM,CAEgB"}

package/src/shade/renderer/geometry/virtual/format/frame/VGEO_CODEC_LZ4.js

@@ -6,6 +6,11 @@
  * its identity-seeded `checksum` covers the stored bytes. So the blob is the bare block, and the
  * frame header is what tells a decoder how much to expect out of it.
  *
+ * Not the builder's default — {@link VGEO_CODEC_DEFLATE} is, because it stores a container in fewer
+ * bytes and a build happens once where a fetch happens forever. This is what to set for a container
+ * whose pages arrive during play: it decodes at 562 MB/s against deflate's 126, and that decode is
+ * a page's arrival cost on the residency path.
+ *
  * @type {number}
  */
 export const VGEO_CODEC_LZ4 = 1;

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

@@ -1 +1 @@
-{"version":3,"file":"vgeo_codec_name.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/geometry/virtual/format/frame/vgeo_codec_name.js"],"names":[],"mappings":"AAGA;;;;;;;;;;;;GAYG;AACH,uCANW,MAAM,GACJ,MAAM,CAelB"}
+{"version":3,"file":"vgeo_codec_name.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/geometry/virtual/format/frame/vgeo_codec_name.js"],"names":[],"mappings":"AAIA;;;;;;;;;;;;GAYG;AACH,uCANW,MAAM,GACJ,MAAM,CAmBlB"}

package/src/shade/renderer/geometry/virtual/format/frame/vgeo_codec_name.js

@@ -1,3 +1,4 @@
+import { VGEO_CODEC_DEFLATE } from "./VGEO_CODEC_DEFLATE.js";
 import { VGEO_CODEC_LZ4 } from "./VGEO_CODEC_LZ4.js";
 import { VGEO_CODEC_RAW } from "./VGEO_CODEC_RAW.js";
 
@@ -23,5 +24,9 @@ export function vgeo_codec_name(codec) {
         return 'lz4';
     }
 
+    if (codec === VGEO_CODEC_DEFLATE) {
+        return 'deflate';
+    }
+
     return `codec ${codec}`;
 }

package/src/shade/renderer/geometry/virtual/format/frame/vgeo_decode_frame_blob.d.ts

@@ -9,18 +9,25 @@
  *
  * A blob that does not decode to exactly `decoded_size` bytes is refused rather than accepted short
  * — a page truncated to a plausible prefix is the one corruption that reads as a valid page with
- * missing geometry, and there is no later check that would notice.
+ * missing geometry, and there is no later check that would notice. Neither decoder is allowed to
+ * *overrun* it either: the LZ4 one is handed the end of the page as its limit, and the deflate one
+ * is stopped at the first chunk that would pass it, so a blob that expands further than its header
+ * admits costs one chunk rather than the whole expansion.
+ *
+ * This is asynchronous because {@link VGEO_CODEC_DEFLATE} is: `DecompressionStream` is the
+ * platform's zlib and the platform only offers it as a stream. The raw and LZ4 paths still finish
+ * in the caller's turn, so awaiting them costs a microtask and nothing else.
  *
  * @param {Uint8Array} destination at least `decoded_size` bytes free at `destination_offset`
  * @param {number} destination_offset where the decoded page starts
  * @param {Uint8Array} source the file, indexed from its first byte — the offsets on `frame` are
  *     absolute
  * @param {VGeoFrameExtent} frame
- * @returns {number} the offset just past the last byte written
+ * @returns {Promise<number>} the offset just past the last byte written
  * @throws {Error} on a codec with no decoder here, or a blob that does not decode as its header says
  *
  * @author Alex Goldring
  * @copyright Company Named Limited (c) 2026
  */
-export function vgeo_decode_frame_blob(destination: Uint8Array, destination_offset: number, source: Uint8Array, frame: VGeoFrameExtent): number;
+export function vgeo_decode_frame_blob(destination: Uint8Array, destination_offset: number, source: Uint8Array, frame: VGeoFrameExtent): Promise<number>;
 //# sourceMappingURL=vgeo_decode_frame_blob.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"vgeo_decode_frame_blob.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/geometry/virtual/format/frame/vgeo_decode_frame_blob.js"],"names":[],"mappings":"AAOA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,oDAXW,UAAU,sBACV,MAAM,UACN,UAAU,2BAGR,MAAM,CA0DlB"}
+{"version":3,"file":"vgeo_decode_frame_blob.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/geometry/virtual/format/frame/vgeo_decode_frame_blob.js"],"names":[],"mappings":"AASA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,oDAXW,UAAU,sBACV,MAAM,UACN,UAAU,2BAGR,QAAQ,MAAM,CAAC,CAmF3B"}

package/src/shade/renderer/geometry/virtual/format/frame/vgeo_decode_frame_blob.js

@@ -1,6 +1,8 @@
 import { assert } from "../../../../../../core/assert.js";
+import { decompress_bytes_into } from "../../../../../../core/binary/compression/decompress_bytes_into.js";
 import { lz4_decompress_block } from "../../../../../../core/binary/lz4/lz4_decompress_block.js";
 import { VGEO_CHILD_TABLE_ENTRY_SIZE } from "./VGEO_CHILD_TABLE_ENTRY_SIZE.js";
+import { VGEO_CODEC_DEFLATE } from "./VGEO_CODEC_DEFLATE.js";
 import { VGEO_CODEC_LZ4 } from "./VGEO_CODEC_LZ4.js";
 import { VGEO_CODEC_RAW } from "./VGEO_CODEC_RAW.js";
 import { VGEO_FRAME_HEADER_SIZE } from "./VGEO_FRAME_HEADER_SIZE.js";
@@ -16,20 +18,27 @@ import { VGEO_FRAME_HEADER_SIZE } from "./VGEO_FRAME_HEADER_SIZE.js";
  *
  * A blob that does not decode to exactly `decoded_size` bytes is refused rather than accepted short
  * — a page truncated to a plausible prefix is the one corruption that reads as a valid page with
- * missing geometry, and there is no later check that would notice.
+ * missing geometry, and there is no later check that would notice. Neither decoder is allowed to
+ * *overrun* it either: the LZ4 one is handed the end of the page as its limit, and the deflate one
+ * is stopped at the first chunk that would pass it, so a blob that expands further than its header
+ * admits costs one chunk rather than the whole expansion.
+ *
+ * This is asynchronous because {@link VGEO_CODEC_DEFLATE} is: `DecompressionStream` is the
+ * platform's zlib and the platform only offers it as a stream. The raw and LZ4 paths still finish
+ * in the caller's turn, so awaiting them costs a microtask and nothing else.
  *
  * @param {Uint8Array} destination at least `decoded_size` bytes free at `destination_offset`
  * @param {number} destination_offset where the decoded page starts
  * @param {Uint8Array} source the file, indexed from its first byte — the offsets on `frame` are
  *     absolute
  * @param {VGeoFrameExtent} frame
- * @returns {number} the offset just past the last byte written
+ * @returns {Promise<number>} the offset just past the last byte written
  * @throws {Error} on a codec with no decoder here, or a blob that does not decode as its header says
  *
  * @author Alex Goldring
  * @copyright Company Named Limited (c) 2026
  */
-export function vgeo_decode_frame_blob(destination, destination_offset, source, frame) {
+export async function vgeo_decode_frame_blob(destination, destination_offset, source, frame) {
     assert.isNonNegativeInteger(destination_offset, 'destination_offset');
     assert.lessThanOrEqual(
         destination_offset + frame.decoded_size, destination.length,
@@ -80,5 +89,30 @@ export function vgeo_decode_frame_blob(destination, destination_offset, source,
         return end;
     }
 
+    if (frame.codec === VGEO_CODEC_DEFLATE) {
+        let written;
+
+        try {
+            written = await decompress_bytes_into(
+                destination, destination_offset, frame.decoded_size,
+                [source.subarray(blob, blob + frame.stored_size)], 'deflate-raw'
+            );
+        } catch (error) {
+            // The platform's own words for a malformed stream vary by host and say nothing about
+            // which page it was, which is the one thing a reader reporting this needs. The original
+            // is kept as the cause, because which host said what is the next question after that.
+            throw new Error(`page ${frame.page_index}: ${error.message}`, { cause: error });
+        }
+
+        if (written !== frame.decoded_size) {
+            throw new Error(
+                `page ${frame.page_index}: the deflate stream decoded to ${written}`
+                + ` bytes, its frame header says ${frame.decoded_size}`
+            );
+        }
+
+        return end;
+    }
+
     throw new Error(`page ${frame.page_index}: codec ${frame.codec} has no decoder here`);
 }

package/src/shade/renderer/geometry/virtual/format/frame/vgeo_encode_frame_blob.d.ts

@@ -3,29 +3,37 @@
  *
  * A compressing codec is a *request*, not a promise: what comes back is whichever of the two is
  * smaller, with the codec that describes it. That is what makes turning compression on safe to do
- * unconditionally — a page of incompressible bytes costs the LZ4 worst case, about one byte in 255
- * plus a token, and paying that to store bytes verbatim is a straight loss. Declining is per page,
- * because `codec` is a frame field: one asset can carry both, and a reader that handles the two
- * codecs handles any mixture of them without knowing there was a decision.
+ * unconditionally — a page of incompressible bytes costs the compressor's worst case, about one
+ * byte in 255 plus a token for LZ4 and five bytes per 64 KB stored block for deflate, and paying
+ * that to store bytes verbatim is a straight loss. Declining is per page, because `codec` is a
+ * frame field: one asset can carry a mixture, and a reader that handles the codecs handles any
+ * mixture of them without knowing there was a decision.
  *
- * The blob is the bare LZ4 block. It carries no length of its own, and none is needed — the frame
- * header's `decoded_size` is what {@link vgeo_decode_frame_blob} decodes against, and the frame's
- * checksum is what proves the stored bytes arrived intact.
+ * The blob is the bare LZ4 block or the bare DEFLATE stream. Neither carries a length of its own
+ * and neither needs to — the frame header's `decoded_size` is what {@link vgeo_decode_frame_blob}
+ * decodes against, and the frame's checksum is what proves the stored bytes arrived intact.
  *
- * The level is how hard the encoder looks for matches, and nothing else: every level writes the
+ * This is asynchronous because {@link VGEO_CODEC_DEFLATE} is: `CompressionStream` is the platform's
+ * zlib and the platform only offers it as a stream. The raw and LZ4 paths still finish in the
+ * caller's turn, so awaiting them costs a microtask and nothing else.
+ *
+ * The LZ4 level is how hard the encoder looks for matches, and nothing else: every level writes the
  * same LZ4 block format, so it is a build-time decision with no reader consequence at all. What it
  * buys on a page of encoded geometry is about 2.5% over the fast encoder, almost all of which is
  * already there at level 3; what it costs is roughly an order of magnitude of encoder throughput,
- * which over a whole conversion comes to a couple of percent of the build.
+ * which over a whole conversion comes to a couple of percent of the build. **Deflate ignores it** —
+ * `CompressionStream` exposes no level, so the host's zlib default is the only setting there is.
  *
  * @param {Uint8Array} bytes the decoded page
- * @param {number} codec the codec to attempt, one of {@link VGEO_CODEC_RAW} or {@link VGEO_CODEC_LZ4}
- * @param {number} [level] how hard to look, one of {@link LZ4_LEVEL}'s; the raw codec ignores it
- * @returns {VGeoFrameBlob}
+ * @param {number} codec the codec to attempt, one of {@link VGEO_CODEC_RAW},
+ *     {@link VGEO_CODEC_LZ4} or {@link VGEO_CODEC_DEFLATE}
+ * @param {number} [level] how hard to look, one of {@link LZ4_LEVEL}'s; the raw and deflate codecs
+ *     ignore it
+ * @returns {Promise<VGeoFrameBlob>}
  *
  * @author Alex Goldring
  * @copyright Company Named Limited (c) 2026
  */
-export function vgeo_encode_frame_blob(bytes: Uint8Array, codec: number, level?: number): VGeoFrameBlob;
+export function vgeo_encode_frame_blob(bytes: Uint8Array, codec: number, level?: number): Promise<VGeoFrameBlob>;
 import { VGeoFrameBlob } from "./VGeoFrameBlob.js";
 //# sourceMappingURL=vgeo_encode_frame_blob.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"vgeo_encode_frame_blob.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/geometry/virtual/format/frame/vgeo_encode_frame_blob.js"],"names":[],"mappings":"AAQA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,8CARW,UAAU,SACV,MAAM,UACN,MAAM,GACJ,aAAa,CAgCzB;8BAzD6B,oBAAoB"}
+{"version":3,"file":"vgeo_encode_frame_blob.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/geometry/virtual/format/frame/vgeo_encode_frame_blob.js"],"names":[],"mappings":"AAUA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,8CAVW,UAAU,SACV,MAAM,UAEN,MAAM,GAEJ,QAAQ,aAAa,CAAC,CA8ClC;8BA/E6B,oBAAoB"}

package/src/shade/renderer/geometry/virtual/format/frame/vgeo_encode_frame_blob.js

@@ -1,7 +1,9 @@
 import { assert } from "../../../../../../core/assert.js";
+import { compress_bytes } from "../../../../../../core/binary/compression/compress_bytes.js";
 import { LZ4_LEVEL } from "../../../../../../core/binary/lz4/LZ4_LEVEL.js";
 import { lz4_compress_block_at_level } from "../../../../../../core/binary/lz4/lz4_compress_block_at_level.js";
 import { lz4_compress_bound } from "../../../../../../core/binary/lz4/lz4_compress_bound.js";
+import { VGEO_CODEC_DEFLATE } from "./VGEO_CODEC_DEFLATE.js";
 import { VGEO_CODEC_LZ4 } from "./VGEO_CODEC_LZ4.js";
 import { VGEO_CODEC_RAW } from "./VGEO_CODEC_RAW.js";
 import { VGeoFrameBlob } from "./VGeoFrameBlob.js";
@@ -11,30 +13,38 @@ import { VGeoFrameBlob } from "./VGeoFrameBlob.js";
  *
  * A compressing codec is a *request*, not a promise: what comes back is whichever of the two is
  * smaller, with the codec that describes it. That is what makes turning compression on safe to do
- * unconditionally — a page of incompressible bytes costs the LZ4 worst case, about one byte in 255
- * plus a token, and paying that to store bytes verbatim is a straight loss. Declining is per page,
- * because `codec` is a frame field: one asset can carry both, and a reader that handles the two
- * codecs handles any mixture of them without knowing there was a decision.
+ * unconditionally — a page of incompressible bytes costs the compressor's worst case, about one
+ * byte in 255 plus a token for LZ4 and five bytes per 64 KB stored block for deflate, and paying
+ * that to store bytes verbatim is a straight loss. Declining is per page, because `codec` is a
+ * frame field: one asset can carry a mixture, and a reader that handles the codecs handles any
+ * mixture of them without knowing there was a decision.
  *
- * The blob is the bare LZ4 block. It carries no length of its own, and none is needed — the frame
- * header's `decoded_size` is what {@link vgeo_decode_frame_blob} decodes against, and the frame's
- * checksum is what proves the stored bytes arrived intact.
+ * The blob is the bare LZ4 block or the bare DEFLATE stream. Neither carries a length of its own
+ * and neither needs to — the frame header's `decoded_size` is what {@link vgeo_decode_frame_blob}
+ * decodes against, and the frame's checksum is what proves the stored bytes arrived intact.
  *
- * The level is how hard the encoder looks for matches, and nothing else: every level writes the
+ * This is asynchronous because {@link VGEO_CODEC_DEFLATE} is: `CompressionStream` is the platform's
+ * zlib and the platform only offers it as a stream. The raw and LZ4 paths still finish in the
+ * caller's turn, so awaiting them costs a microtask and nothing else.
+ *
+ * The LZ4 level is how hard the encoder looks for matches, and nothing else: every level writes the
  * same LZ4 block format, so it is a build-time decision with no reader consequence at all. What it
  * buys on a page of encoded geometry is about 2.5% over the fast encoder, almost all of which is
  * already there at level 3; what it costs is roughly an order of magnitude of encoder throughput,
- * which over a whole conversion comes to a couple of percent of the build.
+ * which over a whole conversion comes to a couple of percent of the build. **Deflate ignores it** —
+ * `CompressionStream` exposes no level, so the host's zlib default is the only setting there is.
  *
  * @param {Uint8Array} bytes the decoded page
- * @param {number} codec the codec to attempt, one of {@link VGEO_CODEC_RAW} or {@link VGEO_CODEC_LZ4}
- * @param {number} [level] how hard to look, one of {@link LZ4_LEVEL}'s; the raw codec ignores it
- * @returns {VGeoFrameBlob}
+ * @param {number} codec the codec to attempt, one of {@link VGEO_CODEC_RAW},
+ *     {@link VGEO_CODEC_LZ4} or {@link VGEO_CODEC_DEFLATE}
+ * @param {number} [level] how hard to look, one of {@link LZ4_LEVEL}'s; the raw and deflate codecs
+ *     ignore it
+ * @returns {Promise<VGeoFrameBlob>}
  *
  * @author Alex Goldring
  * @copyright Company Named Limited (c) 2026
  */
-export function vgeo_encode_frame_blob(bytes, codec, level = LZ4_LEVEL.HC_DEFAULT) {
+export async function vgeo_encode_frame_blob(bytes, codec, level = LZ4_LEVEL.HC_DEFAULT) {
     assert.defined(bytes, 'bytes');
 
     const result = new VGeoFrameBlob();
@@ -46,6 +56,20 @@ export function vgeo_encode_frame_blob(bytes, codec, level = LZ4_LEVEL.HC_DEFAUL
         return result;
     }
 
+    if (codec === VGEO_CODEC_DEFLATE) {
+        const stream = await compress_bytes([bytes], 'deflate-raw');
+
+        if (stream.length < bytes.length) {
+            result.codec = VGEO_CODEC_DEFLATE;
+            result.bytes = stream;
+        } else {
+            result.codec = VGEO_CODEC_RAW;
+            result.bytes = bytes;
+        }
+
+        return result;
+    }
+
     assert.equal(codec, VGEO_CODEC_LZ4, 'codec must be one of the codecs this encoder writes');
 
     const scratch = new Uint8Array(lz4_compress_bound(bytes.length));

package/src/shade/renderer/geometry/virtual/format/frame/vgeo_frame_decode_bound.d.ts

@@ -9,8 +9,14 @@
  * So it is checked against what the stored bytes could physically produce first. The stored size is
  * itself bounded by the file, so this is a bound a reader has before it trusts anything.
  *
- * @param {number} codec one of {@link VGEO_CODEC_RAW} or {@link VGEO_CODEC_LZ4}; anything else has
- *     no decoder and must be refused before this is asked
+ * The bound loosens sharply with the codec — 255x for LZ4, 1032x for deflate — because both numbers
+ * are what the *format* allows and neither is what a page looks like. That is as far as a length
+ * field alone can be checked, and it is why the decoders bound their own output as well rather than
+ * comparing lengths once the decode is over.
+ *
+ * @param {number} codec one of {@link VGEO_CODEC_RAW}, {@link VGEO_CODEC_LZ4} or
+ *     {@link VGEO_CODEC_DEFLATE}; anything else has no decoder and must be refused before this is
+ *     asked
  * @param {number} stored_size bytes of blob
  * @returns {number}
  *

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

@@ -1 +1 @@
-{"version":3,"file":"vgeo_frame_decode_bound.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/geometry/virtual/format/frame/vgeo_frame_decode_bound.js"],"names":[],"mappings":"AAKA;;;;;;;;;;;;;;;;;;GAkBG;AACH,+CARW,MAAM,eAEN,MAAM,GACJ,MAAM,CAelB"}
+{"version":3,"file":"vgeo_frame_decode_bound.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/geometry/virtual/format/frame/vgeo_frame_decode_bound.js"],"names":[],"mappings":"AAOA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,+CATW,MAAM,eAGN,MAAM,GACJ,MAAM,CAmBlB"}

package/src/shade/renderer/geometry/virtual/format/frame/vgeo_frame_decode_bound.js

@@ -1,5 +1,7 @@
 import { assert } from "../../../../../../core/assert.js";
+import { deflate_decompress_bound } from "../../../../../../core/binary/compression/deflate_decompress_bound.js";
 import { lz4_decompress_bound } from "../../../../../../core/binary/lz4/lz4_decompress_bound.js";
+import { VGEO_CODEC_DEFLATE } from "./VGEO_CODEC_DEFLATE.js";
 import { VGEO_CODEC_LZ4 } from "./VGEO_CODEC_LZ4.js";
 import { VGEO_CODEC_RAW } from "./VGEO_CODEC_RAW.js";
 
@@ -14,8 +16,14 @@ import { VGEO_CODEC_RAW } from "./VGEO_CODEC_RAW.js";
  * So it is checked against what the stored bytes could physically produce first. The stored size is
  * itself bounded by the file, so this is a bound a reader has before it trusts anything.
  *
- * @param {number} codec one of {@link VGEO_CODEC_RAW} or {@link VGEO_CODEC_LZ4}; anything else has
- *     no decoder and must be refused before this is asked
+ * The bound loosens sharply with the codec — 255x for LZ4, 1032x for deflate — because both numbers
+ * are what the *format* allows and neither is what a page looks like. That is as far as a length
+ * field alone can be checked, and it is why the decoders bound their own output as well rather than
+ * comparing lengths once the decode is over.
+ *
+ * @param {number} codec one of {@link VGEO_CODEC_RAW}, {@link VGEO_CODEC_LZ4} or
+ *     {@link VGEO_CODEC_DEFLATE}; anything else has no decoder and must be refused before this is
+ *     asked
  * @param {number} stored_size bytes of blob
  * @returns {number}
  *
@@ -29,6 +37,10 @@ export function vgeo_frame_decode_bound(codec, stored_size) {
         return stored_size;
     }
 
+    if (codec === VGEO_CODEC_DEFLATE) {
+        return deflate_decompress_bound(stored_size);
+    }
+
     assert.equal(codec, VGEO_CODEC_LZ4, 'codec must be one this reader has a decoder for');
 
     return lz4_decompress_bound(stored_size);

package/src/shade/renderer/geometry/virtual/format/header/VGEO_FORMAT_VERSION.d.ts

@@ -10,6 +10,24 @@
  * `parent_table_offset` zero and takes the same absence as "this container has no upward edge",
  * which is true.
  *
+ * **5 put `subtree_aabb` in the cluster record and moved `min_reader_version` with it**, which is
+ * the pair working the other way. The box took the bytes of `bounds_sphere` and `cone_reserved`
+ * (§7), so every field from offset 40 on shifted and there is no reading of a version-5 record by
+ * version-4 offsets that is merely incomplete — it is wrong. This reader keeps both layouts and
+ * branches on the container's own version ({@link VGEO_CLUSTER_OFFSET_V4}); an older reader is
+ * refused by `min_reader_version`, which is what that field is for.
+ *
+ * **6 widened the level ordinal to `u16`** — `level_count` in the header (§4), the page band in
+ * the page header (§6.1) and in the directory record (§9) — because 255 was a ceiling a real asset
+ * reached ({@link VGEO_MAX_LEVEL_COUNT}). Two of the three cost nothing: both the header and the
+ * directory record had reserved bytes beside the fields. The page header had none, and rather than
+ * grow it the change spends `node_table_offset`, which was `VGEO_PAGE_HEADER_SIZE + 8 *
+ * group_count` written down — so a page is the same 56 bytes and every other field of it, in every
+ * container ever written, is still at the offset it was. `min_reader_version` moved with this one:
+ * a version-5 reader would take `max_level` for `node_count` and `node_count` for an offset, which
+ * is not a partial reading of the page but a wrong one. The reader keeps the old layout ({@link
+ * VGEO_PAGE_OFFSET_V5}), so nothing has to be rebuilt to stay readable.
+ *
  * @type {number}
  */
 export const VGEO_FORMAT_VERSION: number;

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

@@ -1 +1 @@
-{"version":3,"file":"VGEO_FORMAT_VERSION.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/geometry/virtual/format/header/VGEO_FORMAT_VERSION.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,kCAFU,MAAM,CAEqB"}
+{"version":3,"file":"VGEO_FORMAT_VERSION.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/geometry/virtual/format/header/VGEO_FORMAT_VERSION.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,kCAFU,MAAM,CAEqB"}

package/src/shade/renderer/geometry/virtual/format/header/VGEO_FORMAT_VERSION.js

@@ -10,6 +10,24 @@
  * `parent_table_offset` zero and takes the same absence as "this container has no upward edge",
  * which is true.
  *
+ * **5 put `subtree_aabb` in the cluster record and moved `min_reader_version` with it**, which is
+ * the pair working the other way. The box took the bytes of `bounds_sphere` and `cone_reserved`
+ * (§7), so every field from offset 40 on shifted and there is no reading of a version-5 record by
+ * version-4 offsets that is merely incomplete — it is wrong. This reader keeps both layouts and
+ * branches on the container's own version ({@link VGEO_CLUSTER_OFFSET_V4}); an older reader is
+ * refused by `min_reader_version`, which is what that field is for.
+ *
+ * **6 widened the level ordinal to `u16`** — `level_count` in the header (§4), the page band in
+ * the page header (§6.1) and in the directory record (§9) — because 255 was a ceiling a real asset
+ * reached ({@link VGEO_MAX_LEVEL_COUNT}). Two of the three cost nothing: both the header and the
+ * directory record had reserved bytes beside the fields. The page header had none, and rather than
+ * grow it the change spends `node_table_offset`, which was `VGEO_PAGE_HEADER_SIZE + 8 *
+ * group_count` written down — so a page is the same 56 bytes and every other field of it, in every
+ * container ever written, is still at the offset it was. `min_reader_version` moved with this one:
+ * a version-5 reader would take `max_level` for `node_count` and `node_count` for an offset, which
+ * is not a partial reading of the page but a wrong one. The reader keeps the old layout ({@link
+ * VGEO_PAGE_OFFSET_V5}), so nothing has to be rebuilt to stay readable.
+ *
  * @type {number}
  */
-export const VGEO_FORMAT_VERSION = 4;
+export const VGEO_FORMAT_VERSION = 6;

package/src/shade/renderer/geometry/virtual/format/header/VGEO_HEADER_OFFSET.js

@@ -22,6 +22,12 @@ export const VGEO_HEADER_OFFSET = {
     DIRECTORY_OFFSET: 80,
     DIR_BLOCK_CHECKSUMS_OFFSET: 88,
     NOMINAL_PAGE_SIZE: 96,
+    /**
+     * `u16` since `format_version` 6, over the byte that followed it and was written as zero.
+     * Little-endian puts the low byte first, so this field reads the same through a version-5
+     * reader's `u8` for every container that has 255 levels or fewer — which is every container
+     * written before 6 and almost every one written after.
+     */
     LEVEL_COUNT: 102,
     SOURCE_VERTEX_COUNT: 104,
     SOURCE_FACE_COUNT: 112,

package/src/shade/renderer/geometry/virtual/format/header/VGEO_MAX_LEVEL_COUNT.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Levels a container can name — the format's ceiling, not a build's.
+ *
+ * `level_count` is a `u16` in the header and a page band is a pair of them, so this is what those
+ * fields can say and nothing about it is a judgement on what a build should produce. The number a
+ * build refuses to go past is {@link VGeoLevelOptions.max_levels}, which is a sanity bound set an
+ * order of magnitude below this.
+ *
+ * It was a `u8` through `format_version` 5, and the byte was reachable: the 2026-09-14 Zorah
+ * conversion put one geometry — three million triangles of foliage, whose leaf cards are thousands
+ * of disconnected components — at 255 levels with 39 clusters still unmerged, while the other 2,974
+ * geometries of the same scene converged by 149. A ceiling a real asset can touch is a ceiling in
+ * the wrong place.
+ *
+ * @type {number}
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export const VGEO_MAX_LEVEL_COUNT: number;
+//# sourceMappingURL=VGEO_MAX_LEVEL_COUNT.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"VGEO_MAX_LEVEL_COUNT.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/geometry/virtual/format/header/VGEO_MAX_LEVEL_COUNT.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AACH,mCALU,MAAM,CAK0B"}

package/src/shade/renderer/geometry/virtual/format/header/VGEO_MAX_LEVEL_COUNT.js

@@ -0,0 +1,20 @@
+/**
+ * Levels a container can name — the format's ceiling, not a build's.
+ *
+ * `level_count` is a `u16` in the header and a page band is a pair of them, so this is what those
+ * fields can say and nothing about it is a judgement on what a build should produce. The number a
+ * build refuses to go past is {@link VGeoLevelOptions.max_levels}, which is a sanity bound set an
+ * order of magnitude below this.
+ *
+ * It was a `u8` through `format_version` 5, and the byte was reachable: the 2026-09-14 Zorah
+ * conversion put one geometry — three million triangles of foliage, whose leaf cards are thousands
+ * of disconnected components — at 255 levels with 39 clusters still unmerged, while the other 2,974
+ * geometries of the same scene converged by 149. A ceiling a real asset can touch is a ceiling in
+ * the wrong place.
+ *
+ * @type {number}
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export const VGEO_MAX_LEVEL_COUNT = 65535;

package/src/shade/renderer/geometry/virtual/format/header/VGEO_MIN_READER_VERSION.d.ts

@@ -1,5 +1,14 @@
 /**
  * A reader older than this must refuse the file.
+ *
+ * 6 since the page header's level ordinals widened to `u16` ({@link VGEO_FORMAT_VERSION}): four
+ * bytes at offset 4 and four at offset 20 changed meaning, so a version-5 reader would take
+ * `max_level` for `node_count`, believe a page holds tens of thousands of nodes, and read its node
+ * table out of an offset that is now two reserved bytes. There is no partial reading of that.
+ *
+ * It also doubles as the version this reader *is*, which is what lets it keep reading version-4 and
+ * version-5 containers while writing version-6 ones.
+ *
  * @type {number}
  */
 export const VGEO_MIN_READER_VERSION: number;

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

@@ -1 +1 @@
-{"version":3,"file":"VGEO_MIN_READER_VERSION.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/geometry/virtual/format/header/VGEO_MIN_READER_VERSION.js"],"names":[],"mappings":"AAAA;;;GAGG;AACH,sCAFU,MAAM,CAEyB"}
+{"version":3,"file":"VGEO_MIN_READER_VERSION.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/geometry/virtual/format/header/VGEO_MIN_READER_VERSION.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,sCAFU,MAAM,CAEyB"}

package/src/shade/renderer/geometry/virtual/format/header/VGEO_MIN_READER_VERSION.js

@@ -1,5 +1,14 @@
 /**
  * A reader older than this must refuse the file.
+ *
+ * 6 since the page header's level ordinals widened to `u16` ({@link VGEO_FORMAT_VERSION}): four
+ * bytes at offset 4 and four at offset 20 changed meaning, so a version-5 reader would take
+ * `max_level` for `node_count`, believe a page holds tens of thousands of nodes, and read its node
+ * table out of an offset that is now two reserved bytes. There is no partial reading of that.
+ *
+ * It also doubles as the version this reader *is*, which is what lets it keep reading version-4 and
+ * version-5 containers while writing version-6 ones.
+ *
  * @type {number}
  */
-export const VGEO_MIN_READER_VERSION = 3;
+export const VGEO_MIN_READER_VERSION = 6;

package/src/shade/renderer/geometry/virtual/format/page/VGEO_GROUP_OFFSET.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Group record field offsets, relative to the record's own start.
+ *
+ * The record is `VGEO_GROUP_RECORD_SIZE` bytes and `VGEO_FORMAT.md` §6.2 is where the layout is
+ * stated; this is that statement in code, so the writer, the reader and the audit address the same
+ * bytes by the same names rather than each counting them out again.
+ */
+export type VGEO_GROUP_OFFSET = number;
+export namespace VGEO_GROUP_OFFSET {
+    let CLUSTER_FIRST: number;
+    let CLUSTER_COUNT: number;
+    let PARENT_CLUSTER_COUNT: number;
+    let PARENT_FIRST: number;
+}
+//# sourceMappingURL=VGEO_GROUP_OFFSET.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"VGEO_GROUP_OFFSET.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/geometry/virtual/format/page/VGEO_GROUP_OFFSET.js"],"names":[],"mappings":";;;;;;;gCAOU,MAAM"}

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

@@ -0,0 +1,15 @@
+/**
+ * Group record field offsets, relative to the record's own start.
+ *
+ * The record is `VGEO_GROUP_RECORD_SIZE` bytes and `VGEO_FORMAT.md` §6.2 is where the layout is
+ * stated; this is that statement in code, so the writer, the reader and the audit address the same
+ * bytes by the same names rather than each counting them out again.
+ *
+ * @enum {number}
+ */
+export const VGEO_GROUP_OFFSET = {
+    CLUSTER_FIRST: 0,
+    CLUSTER_COUNT: 2,
+    PARENT_CLUSTER_COUNT: 4,
+    PARENT_FIRST: 6,
+};

package/src/shade/renderer/geometry/virtual/format/page/VGEO_PAGE_OFFSET.d.ts

@@ -7,11 +7,10 @@ export namespace VGEO_PAGE_OFFSET {
     let CLUSTER_COUNT: number;
     let MIN_LEVEL: number;
     let MAX_LEVEL: number;
-    let NODE_COUNT: number;
     let CLUSTER_TABLE_OFFSET: number;
     let PAYLOAD_OFFSET: number;
     let PAYLOAD_SIZE: number;
-    let NODE_TABLE_OFFSET: number;
+    let NODE_COUNT: number;
     let PARENT_TABLE_OFFSET: number;
     let PARENT_ENTRY_COUNT: number;
     let PARENT_PAGE_COUNT: number;

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

@@ -5,13 +5,20 @@
 export const VGEO_PAGE_OFFSET = {
     GROUP_COUNT: 0,
     CLUSTER_COUNT: 2,
+    /**
+     * The page's band, `u16` since `format_version` 6 ({@link VGEO_PAGE_OFFSET_V5} is where they
+     * were a byte each). The four bytes come from `node_table_offset`, which said only what
+     * `VGEO_PAGE_HEADER_SIZE + 8 * group_count` says: the group table follows the header and the
+     * node table follows the group table, both by construction, and the reader derives it. What the
+     * stored copy was really cross-checking — that `group_count` agrees with the layout — is still
+     * checked, because `cluster_table_offset` is stored and must equal the derived node table's end.
+     */
     MIN_LEVEL: 4,
-    MAX_LEVEL: 5,
-    NODE_COUNT: 6,
+    MAX_LEVEL: 6,
     CLUSTER_TABLE_OFFSET: 8,
     PAYLOAD_OFFSET: 12,
     PAYLOAD_SIZE: 16,
-    NODE_TABLE_OFFSET: 20,
+    NODE_COUNT: 20,
     /**
      * Start of this page's parent section, which is the parent-page table immediately followed by
      * the group-parent table. Zero means the page carries neither, which is what every container

package/src/shade/renderer/geometry/virtual/format/page/VGEO_PAGE_OFFSET_V5.d.ts

@@ -0,0 +1,20 @@
+/**
+ * *
+ */
+export type VGEO_PAGE_OFFSET_V5 = number;
+export namespace VGEO_PAGE_OFFSET_V5 {
+    let GROUP_COUNT: number;
+    let CLUSTER_COUNT: number;
+    let MIN_LEVEL: number;
+    let MAX_LEVEL: number;
+    let NODE_COUNT: number;
+    let CLUSTER_TABLE_OFFSET: number;
+    let PAYLOAD_OFFSET: number;
+    let PAYLOAD_SIZE: number;
+    let NODE_TABLE_OFFSET: number;
+    let PARENT_TABLE_OFFSET: number;
+    let PARENT_ENTRY_COUNT: number;
+    let PARENT_PAGE_COUNT: number;
+    let METRIC: number;
+}
+//# sourceMappingURL=VGEO_PAGE_OFFSET_V5.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"VGEO_PAGE_OFFSET_V5.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/geometry/virtual/format/page/VGEO_PAGE_OFFSET_V5.js"],"names":[],"mappings":";;;kCAmBU,MAAM"}