@woosh/meep-engine 3.28.0 → 3.29.0

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_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"}

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,12 +1,14 @@
 /**
  * @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

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":"AAoHA;;;;;;;GAOG;AACH,uDAPW,YAAY,WACZ,UAAU,cACV,WAAW,UACX,CAAC,kBAAgB,IAAI,CAAC,EAAE,GAEtB,kBAAkB,CAiF9B;AA5LD;;;;;;;;;;;GAWG;AAEH;;;;;;;;;;;;;;GAcG;AACH,+BAFU,MAAM,EAAE,EAAE,CAEe;mCA9BA,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

@@ -117,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');
@@ -163,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.