@woosh/meep-engine 3.27.0 → 3.29.0

package/src/shade/renderer/geometry/virtual/VGEO_FORMAT.md

@@ -28,8 +28,10 @@ consumer reads it, and `runtime/RUNTIME_PLAN.md` §4.8 says why: at the moment a
 per-cluster test the cut has already passed is strictly tighter than any page-level test, so the
 page-level one can never reject anything. Its consumer is prefetch, which is a later campaign.
 
-`shade/playground/vgeo_viewer/` drives the reader end to end, and its `select_cut.js` is a CPU
-reference traversal of the cut rule this format was shaped around.
+`shade/playground/vgeo_runtime/` and `shade/playground/vgeo_scene/` drive the reader end to end
+against a device, and `runtime/cut/__fixtures__/vgeo_select_cut.js` is a CPU reference traversal of the
+cut rule this format was shaped around — the oracle the GPU cut is held to, and the only traversal
+of it that is not a kernel.
 
 ## 1. Design constraints (inherited, binding)
 
@@ -116,8 +118,8 @@ All u64/u128 fields are naturally 8-byte aligned.
 | offset | type      | field                    | notes |
 |-------:|-----------|--------------------------|-------|
 | 0      | u32       | magic                    | `'VGEO'` = 0x4F454756 |
-| 4      | u16       | format_version           | 4 today; breaking layout changes only |
-| 6      | u16       | min_reader_version       | 3 today; reader MUST reject if its version is lower |
+| 4      | u16       | format_version           | 6 today; breaking layout changes only |
+| 6      | u16       | min_reader_version       | 6 today; reader MUST reject if its version is lower |
 | 8      | u16       | header_size              | = 256 |
 | 10     | u8        | hash_algo                | 0 = xxHash3; readers MUST reject unknown values |
 | 11     | u8        | reserved                 | |
@@ -136,8 +138,7 @@ All u64/u128 fields are naturally 8-byte aligned.
 | 88     | u64       | dir_block_checksums_offset | `ceil(total_pages / 128)` × u64 |
 | 96     | u32       | nominal_page_size        | bytes a decoded page may come to; a **hard bound** when bit 0 of `feature_flags_ignorable` is set (§11.14), advisory otherwise |
 | 100    | u16       | reserved                 | |
-| 102    | u8        | level_count              | levels `0..level_count-1` |
-| 103    | u8        | reserved                 | |
+| 102    | u16       | level_count              | levels `0..level_count-1`; ≤ 65,535. A `u8` through version 5, and the byte above it was reserved and written as zero — so little-endian makes this field read identically through either width for any container of 255 levels or fewer |
 | 104    | u64       | source_vertex_count      | vertices of the normalized source mesh (post-weld) the leaves represent |
 | 112    | u64       | source_face_count        | triangles of the normalized source mesh |
 | 120    | [f32; 4]  | object_sphere            | object-space minimal bounding sphere (center xyz, radius) of the whole geometry |
@@ -154,12 +155,35 @@ version-4 file correctly by ignoring them. In the other direction a version-4 re
 which is true — so neither direction needs a version test, and nothing has to be rebuilt to stay
 readable.
 
+**5 moved both**, which is the pair working the other way. It put `subtree_aabb` in the cluster
+record (§7) over the bytes `bounds_sphere` and `cone_reserved` held, so every field from offset 40
+on shifted: a version-4 reader would take a version-5 `child_ref` out of the middle of a bounding
+box and descend into whatever group that named. There is no ignoring it and no partial reading of
+it, so `min_reader_version` moved with the version, which is what that field is for. A version-5
+reader still reads version-4 records — it branches on the version it is holding — so nothing has to
+be rebuilt to stay readable, only to be culled tightly.
+
+**6 widened the level ordinal to `u16`** in all three places it is written down: `level_count`
+here, the page band in the page header (§6.1), and the page band in the directory record (§9). 255
+was a ceiling a real asset reached — the 2026-09-14 Zorah conversion refused a three-million-triangle
+bush at exactly 255 levels with 39 clusters still unmerged, while the other 2,974 geometries of that
+scene, one of them 27 million triangles, converged by 149 — and a ceiling an asset can touch is a
+ceiling in the wrong place. Two of the three cost nothing: this header and the directory record both
+had reserved bytes lying beside the field. The page header had none, and rather than grow the page
+this spends `node_table_offset`, which only ever restated `56 + 8·group_count`. So **a page header
+is still 56 bytes and every other field of every page ever written is still at its old offset** —
+but bytes 4..8 and 20..24 of it now mean different things, and there is no partial reading of that,
+so `min_reader_version` moved. A version-6 reader keeps the older page layout as it keeps the older
+cluster layout, so again nothing has to be rebuilt to stay readable.
+
 ### 4.1 Level table (`level_count` × 32 B, immediately after the header)
 
 Statistics per level, at `256 + 32·i`, ending where the root page frame begins. Small —
-a hundred levels is 3.2 KB — so a single fetch of the file's head brings the header, the
-whole table, and the always-resident root page together, and the table is available before
-any page has been decoded.
+a hundred levels is 3.2 KB, and the deepest container yet converted is 149 — so a single
+fetch of the file's head brings the header, the whole table, and the always-resident root
+page together, and the table is available before any page has been decoded. That is a
+statement about what builds produce and not a bound: `level_count` is a `u16`, and a
+reader sizing a head fetch must take the number it finds rather than assume this one.
 
 | offset | type | field             | notes |
 |-------:|------|-------------------|-------|
@@ -217,7 +241,7 @@ Every page — root included — is stored as a self-delimiting frame:
 | offset | type | field            | notes |
 |-------:|------|------------------|-------|
 | 0      | u32  | magic            | `'VGPG'` = 0x47504756 |
-| 4      | u8   | codec            | 0 = raw, 1 = one LZ4 block; applies to the blob only; readers MUST reject unknown values |
+| 4      | u8   | codec            | 0 = raw, 1 = one LZ4 block, 2 = one raw DEFLATE stream; applies to the blob only; readers MUST reject unknown values |
 | 5      | u8   | flags            | 0 |
 | 6      | u16  | child_page_count | entries in the child table; 0 for all-leaf pages |
 | 8      | u32  | stored_size      | bytes of blob (after the child table) |
@@ -256,26 +280,64 @@ terminator.
 and an asset may carry a mixture, so a reader that handles the defined codecs handles
 any file without asking what it was written with. That is what makes "compress unless it
 would not shrink" expressible — the LZ4 worst case is about one byte in 255 plus a
-token, and paying it to store bytes verbatim is a straight loss, so a page that does not
-compress is written raw and says so.
+token, deflate's is a stored block that is never smaller than its input, and paying
+either to store bytes verbatim is a straight loss, so a page that does not compress is
+written raw and says so.
 
 A new codec id is a **per-asset capability gate, not a format break**, exactly as a new
 `payload_encoding` is: an older reader meets a codec it has no decoder for and refuses
 the asset instead of misreading it. `format_version` moves only when the container
-layout itself changes, and adding a codec does not change it.
+layout itself changes, and adding a codec does not change it — `2` went in without
+touching `format_version` or `min_reader_version`.
 
-`1` is a **bare LZ4 block**, not an LZ4 frame: LZ4's own framing carries a magic, a
-checksum and a content size that this frame already carries better, and `decoded_size`
-is what the block is decoded against. Blocks are independent — no match reaches outside
-the page — so a page decodes from its own bytes with no other page involved, which is
-the same property residency already needs.
+`1` is a **bare LZ4 block**, not an LZ4 frame, and `2` is a **bare DEFLATE stream**
+(RFC 1951), not a zlib or gzip member. Both wrappers carry a magic, a checksum and a
+content size that this frame already carries better, and `decoded_size` is what the blob
+is decoded against. Both codecs are independent per blob — no match reaches outside the
+page — so a page decodes from its own bytes with no other page involved, which is the
+same property residency already needs.
 
 `decoded_size` is untrusted input, and readers allocate against it before anything can
 contradict it. It MUST therefore be checked against what `stored_size` bytes could
 physically produce under `codec` — exactly `stored_size` for raw, at most
-`255·stored_size + 19` for LZ4 — *before* the allocation. A block that then decodes to
-anything other than `decoded_size` MUST be rejected: a page truncated to a plausible
-prefix is the one corruption that reads as a valid page with geometry missing.
+`255·stored_size + 19` for LZ4, at most `1032·stored_size` for deflate — *before* the
+allocation. A blob that then decodes to anything other than `decoded_size` MUST be
+rejected: a page truncated to a plausible prefix is the one corruption that reads as a
+valid page with geometry missing.
+
+Those ceilings are what the *format* permits, and neither compressing one is anything
+like what a page looks like, so a length check alone is a weak guard — deflate's 1032:1 admits a 256 KB blob claiming 264
+MB. A decoder MUST therefore bound its own output as it produces it rather than
+comparing lengths once it is done: the LZ4 decoder is given the end of the page as its
+write limit, and the deflate decoder stops at the first chunk that would pass it. A blob
+that expands further than its header admits then costs one chunk rather than the whole
+expansion.
+
+**Which codec, and why deflate is the default.** Measured over the 44 pages of a
+240×120 torus: LZ4 stores them at **1.295x** and deflate at **1.369x**, and decoding
+every page costs **3.8 ms** under LZ4 against **16.9 ms** under deflate — 562 MB/s of
+decoded output against 126. Deflate buys about seven points of ratio for four and a half
+times the decode.
+
+**The builder and the converter write deflate**, because the two sides of that trade are
+not paid the same number of times: an asset is built once and fetched forever, and the
+bytes deflate saves are saved on every fetch of every page by every client. LZ4 is the
+deliberate setting for a container whose pages arrive while someone is looking at it —
+there the decode is a page's *arrival* cost on the residency path, and 126 MB/s is what
+that costs. Neither is a property of the file format: `codec` is a frame field and a
+reader that handles the defined codecs reads either without being told.
+
+A *default* codec is a statement about readers rather than about bytes. Under the gate
+above, a container written with deflate opens only in a reader that carries the deflate
+decoder, so the default is what decides which builds of this engine can open a freshly
+converted asset. `format_version` still does not move, and an older reader still refuses
+rather than misreads.
+
+Deflate is also the *hosted* codec: `CompressionStream`/`DecompressionStream` are the
+platform's own zlib, so it costs no bytes of library — and the platform offers it only
+as a stream, which is why everything in this reader from the blob decode upwards is
+asynchronous. Nothing in the format requires that; a synchronous inflate would read the
+same files.
 
 **What it is worth, measured.** LZ4 over the pages of the Stanford models comes to
 **1.12x on the bunny, 1.18x on the dragon and 1.14x on the 27M-triangle lucy** — pages
@@ -290,10 +352,11 @@ is worth writing down because it says where the next win is rather than here:
 The tables compress, and there are not enough of them to matter. The payload does not,
 because under `SHADE_MESHLET_V1` it is float32 positions and packed attribute words —
 high-entropy at the byte level, with no repetition for an LZ matcher to find. For
-reference, on the same bytes `gzip -9` reaches 1.22x and `xz -9` 1.63x, so this is the
-data resisting rather than the codec failing; an entropy coder buys a little more for a
-lot more time. **The lever is `payload_encoding`, not `codec`** — quantized positions
-(§12) shrink those bytes directly and leave the residue far more compressible.
+reference, on the same bytes `gzip -9` reaches 1.22x — codec `2`'s algorithm, at a level
+the platform API does not expose — and `xz -9` 1.63x, so this is the data resisting
+rather than the codec failing; an entropy coder buys a little more for a lot more time. **The lever is `payload_encoding`, not
+`codec`** — quantized positions (§12) shrink those bytes directly and leave the residue
+far more compressible.
 
 What the reader pays is one block decode per page installed, into the buffer the page was
 going to be copied into anyway: ~350–500 MB/s of decoded output from the JS decoder, so
@@ -307,9 +370,9 @@ about 0.6 ms for a 256 KB page.
 ```
 
 The two parent tables sit between the cluster records and the payload, and that placement is the
-reason `min_reader_version` did not move (§4): `node_table_offset`'s `= 56 + 8·group_count` stays
-true, every earlier offset is where it was, and both tables hold 4-byte entries over sections that
-are already multiples of four, so §11.8's word-aligned payload survives.
+reason `min_reader_version` did not move when version 4 added them (§4): the node table's `= 56 +
+8·group_count` stays true, every earlier offset is where it was, and both tables hold 4-byte entries
+over sections that are already multiples of four, so §11.8's word-aligned payload survives.
 
 PageHeader:
 
@@ -317,13 +380,13 @@ PageHeader:
 |-------:|------|-----------------------|-------|
 | 0      | u16  | group_count           | ≥ 1; group table immediately follows the header |
 | 2      | u16  | cluster_count         | ≥ 1 |
-| 4      | u8   | min_level             | page band; non-root pages span one contiguous band |
-| 5      | u8   | max_level             | |
-| 6      | u16  | node_count            | ≥ 1; ≤ 2·`group_count` (§6.1) |
+| 4      | u16  | min_level             | page band; non-root pages span one contiguous band. A `u8` at 4 and another at 5 through version 5 |
+| 6      | u16  | max_level             | |
 | 8      | u32  | cluster_table_offset  | |
 | 12     | u32  | payload_offset        | |
 | 16     | u32  | payload_size          | |
-| 20     | u32  | node_table_offset     | = `56 + 8·group_count`; the node table follows the group table |
+| 20     | u16  | node_count            | ≥ 1; ≤ 2·`group_count` (§6.1). At 6 through version 5 |
+| 22     | u16  | reserved              | what version 5 spent on `node_table_offset`, which said only `56 + 8·group_count` — the group table follows the header and the node table follows the group table, so a reader derives it. MUST be zero |
 | 24     | u32  | parent_table_offset   | start of the parent section — the parent-page table, then the group-parent table. **0 means the page carries neither**, which is what every container written before `format_version` 4 says about itself |
 | 28     | u16  | parent_entry_count    | entries in the group-parent table (§6.3) = Σ `parent_cluster_count` over this page's groups |
 | 30     | u16  | parent_page_count     | entries in the parent-page table (§6.4) |
@@ -433,11 +496,13 @@ decode it. Being a copy, it can drift; §11.11 requires it to match the page's o
 ## 7. Cluster record (112 bytes)
 
 Everything the runtime cut rule, culling, wants, and upload need — denormalized per
-cluster so selection reads one record. Two kinds of spheres, deliberately distinct: the
+cluster so selection reads one record. Three kinds of bounds, deliberately distinct: the
 **LOD-metric pair** (`self_sphere`/`parent_sphere` — shared per group step so all
-siblings project identical values, monotonically inflated, never a tight fit) and the
-**culling bounds** (`bounds_sphere`/`aabb` — this cluster's own tight fits, never used
-in the cut test):
+siblings project identical values, monotonically inflated, never a tight fit), the
+**cluster's own box** (`aabb` — its tight fit, the meshlet metadata's `bounds_box`, culled
+downstream by the HZB), and the **subtree box** (`subtree_aabb` — this cluster's geometry and
+everything reachable below it, and the only one of the three the cut's per-cluster frustum test
+can use, because culling a cluster takes its whole child group out of the descent):
 
 | offset | type     | field           | notes |
 |-------:|----------|-----------------|-------|
@@ -445,18 +510,23 @@ in the cut test):
 | 16     | f32      | self_error      | object-space `r_e`; leaves: 0 |
 | 20     | f32      | parent_error    | error of the step that consumed it; roots: +∞ |
 | 24     | [f32; 4] | parent_sphere   | LOD-metric sphere of the consuming step; roots: duplicate of self_sphere |
-| 40     | [f32; 4] | bounds_sphere   | this cluster's own minimal bounding sphere (miniball), object-space — culling |
-| 56     | [f32; 6] | aabb            | this cluster's object-space AABB — culling, GPU metadata `bounds_box`, and the (future) dequantization grid |
-| 80     | u16      | child_ref       | index into this frame's child table; `SAME_PAGE` when the child group is in this page; `NO_CHILD` for leaves |
-| 82     | u16      | child_group     | group index within the child page (or this page, for `SAME_PAGE`); `NO_GROUP` for leaves |
-| 84     | u32      | cone_reserved   | reserved — **write 0**. Named for a backface-cone cull pass that is now **declined outright** (design §9, plan §5), so no sub-encoding will ever be pinned here. Kept rather than reclaimed: removing it moves `format_version`, a constant-zero column costs nothing after the page codec, and there are ten more reserved bytes beside it at 102 and 104 anyway. A candidate to rename and reuse the next time the version moves for some other reason |
-| 88     | u32      | encoding_flags  | frozen bit table in §8 |
-| 92     | u32      | payload_offset  | into this page's payload section; ≡ 0 (mod 4) |
-| 96     | u32      | payload_size    | bytes; ≡ 0 (mod 4) |
-| 100    | u8       | vertex_count    | 3 ≤ n ≤ 128 |
-| 101    | u8       | triangle_count  | 1 ≤ n ≤ 128 |
-| 102    | u16      | reserved        | |
-| 104    | u64      | reserved        | |
+| 40     | [f32; 6] | subtree_aabb    | object-space AABB of this cluster's vertices **and of every cluster reachable below it** through child groups (§11.17); leaves: equals `aabb`. What the runtime's per-cluster frustum cull reads |
+| 64     | [f32; 6] | aabb            | this cluster's own object-space AABB — GPU metadata `bounds_box`, the downstream culls, and the (future) dequantization grid |
+| 88     | u16      | child_ref       | index into this frame's child table; `SAME_PAGE` when the child group is in this page; `NO_CHILD` for leaves |
+| 90     | u16      | child_group     | group index within the child page (or this page, for `SAME_PAGE`); `NO_GROUP` for leaves |
+| 92     | u32      | encoding_flags  | frozen bit table in §8 |
+| 96     | u32      | payload_offset  | into this page's payload section; ≡ 0 (mod 4) |
+| 100    | u32      | payload_size    | bytes; ≡ 0 (mod 4) |
+| 104    | u8       | vertex_count    | 3 ≤ n ≤ 128 |
+| 105    | u8       | triangle_count  | 1 ≤ n ≤ 128 |
+| 106    | [u8; 6]  | reserved        | **write 0** |
+
+**What version 5 spent to fit `subtree_aabb` in the same 112 bytes.** `bounds_sphere`, the cluster's
+own miniball, which no runtime ever read — the cut tests the LOD sphere, the HZB and the small-primitive
+cull test `bounds_box`, and the builder keeps its own copy of the sphere for the object bounds and the
+group centroids. And `cone_reserved`, four bytes held for a backface-cone cull that is **declined
+outright** (design §9, plan §5): the earlier note kept it because reclaiming four bytes was not worth
+moving `format_version`, and moving it for twenty-four was.
 
 Monotonicity (`parent_error ≥ self_error`, `parent_sphere ⊇ self_sphere`) is a build
 invariant, not a reader concern. A single-cluster asset is valid: one root page, one
@@ -520,12 +590,12 @@ derivable from the frames (§3) — standard runtime traversal never reads it.
 | 0      | u64  | frame_offset   | absolute; frame per §5 |
 | 8      | u32  | fetch_size     | as in the child table: the exact byte range to fetch is `[frame_offset, frame_offset + fetch_size)` |
 | 12     | u32  | decoded_size   | MUST equal the frame's |
-| 16     | u8   | min_level      | |
-| 17     | u8   | max_level      | |
-| 18     | u16  | flags          | bit 0: root page |
-| 20     | u16  | group_count    | |
-| 22     | u16  | cluster_count  | |
-| 24     | u64  | reserved       | |
+| 16     | u16  | min_level      | a `u8` here and another at 17 through version 5, which is what moved the three fields below by two — into bytes this record has always held in reserve |
+| 18     | u16  | max_level      | |
+| 20     | u16  | flags          | bit 0: root page |
+| 22     | u16  | group_count    | |
+| 24     | u16  | cluster_count  | |
+| 26     | [u8; 6] | reserved    | |
 
 **Directory integrity**: `dir_block_checksums` holds one xxh3-64 per 128 directory
 records (one 4 KB block), seed = `asset_id_high64 XOR block_index`. Readers that use
@@ -746,8 +816,10 @@ clustering and simplification dominate regardless.
    one, and it is in page 0. Several parentless clusters would be several entry points,
    and the cut only ever enters at one; it is also what an unconverged build leaves
    behind, which is the likelier cause. All floats NaN-free.
-   `bounds_sphere` and `aabb` contain the cluster's decoded vertices; the header's
-   `object_sphere` and `object_bounds` contain the normalized source mesh.
+   `self_sphere`, `aabb` and `subtree_aabb` contain the cluster's decoded vertices; the header's
+   `object_sphere` and `object_bounds` contain the normalized source mesh. The `self_sphere` half is
+   what makes the LOD sphere usable as a conservative bound at all — the runtime's first frustum test
+   is on it, and a reader meeting a pre-5 container stands its cube in for `subtree_aabb`.
 8. Payload offsets and sizes are 4-byte multiples; every payload decodes/uploads
    against `payload_encoding` with no external state beyond its own cluster record.
    A leaf's `self_error` of 0 is only as honest as the simplifier's metric — see design
@@ -762,18 +834,23 @@ clustering and simplification dominate regardless.
    and the leaves partition the group table — each group reached through exactly one leaf. Each
    node's metric bounds its whole subtree: its sphere contains every child's, its `min_self_error`
    is no greater than any child's, its `max_parent_error` no less. The page header's metric equals
-   the root node's.
+   the root node's. The table begins at `56 + 8·group_count` — derived, because the page header
+   carries no offset for it since version 6 — and the `u16` at 22 that its offset used to occupy is
+   zero.
 11. Every child-table entry's metric equals the header metric of the page it names. It is a copy
    read before that page is fetched, so nothing else can catch it having drifted — and a traversal
    that trusts a stale one skips a page it needed and leaves a hole.
 12. Every frame names a defined `codec` (§5); a raw frame's `stored_size` equals its
    `decoded_size`; and no frame's `decoded_size` exceeds what its codec could produce from
-   `stored_size` bytes. Every blob decodes to exactly `decoded_size` — a short decode is a
-   truncated page, and a page truncated to a plausible prefix is the one corruption that reads
-   as valid geometry with pieces missing.
+   `stored_size` bytes. Every blob decodes to exactly `decoded_size` — neither short nor long. A
+   short decode is a truncated page, and a page truncated to a plausible prefix is the one
+   corruption that reads as valid geometry with pieces missing; a long one is a blob that would
+   write past what the reader allocated from `decoded_size`, and is stopped while it is producing
+   rather than measured afterwards.
 13. `root_page_offset = align16(256 + 32 · level_count)`; the level table's `cluster_count` and
    `group_count` columns sum to `total_clusters` and `total_groups`; every level holds at least
-   one cluster and one group; `min_error ≤ max_error`, both finite and ≥ 0.
+   one cluster and one group; `min_error ≤ max_error`, both finite and ≥ 0. `level_count ≥ 1`,
+   and no page's `max_level` reaches it.
 14. **Page size is a bound.** When bit 0 of `feature_flags_ignorable` is set, every page's
    `decoded_size` is ≤ `nominal_page_size`, and `nominal_page_size` is non-zero. The bit is what a
    reader checks; unset, `nominal_page_size` is the advisory build parameter it used to be and
@@ -802,13 +879,29 @@ clustering and simplification dominate regardless.
     the run, rather than carrying a dedup bitmask sized by instances × groups — so the order is
     load-bearing and not presentation.
 
+17. **`subtree_aabb` bounds the subtree.** It contains the cluster's own `aabb` and, for every
+    cluster of the group the cluster refines into, that cluster's `subtree_aabb` — so by induction
+    it contains every vertex anywhere below the cluster in the DAG. A leaf's equals its `aabb`.
+
+    **Exact, on the stored values, with no tolerance.** A union of float32 extremes is a float32
+    extreme, so unlike the spheres there is nothing here for rounding to eat and nothing to inflate
+    against it. That is half of why the runtime cull is a box: the other half is that a subtree of a
+    surface is a flat patch, and its AABB is a fraction of the volume of any sphere around it.
+
+    **Why the subtree and not the cluster.** The runtime's per-cluster frustum test decides whether
+    a cluster refines into its child group, so culling it removes that whole group — and everything
+    under it — from the cut. A step consumes one group and produces several parents, each naming the
+    *whole* consumed group, so what is reachable below a cluster carries its siblings' surface too
+    and grows with depth. A bound that covered only the cluster would cull a parent with on-screen
+    descendants, and a culled subtree leaves a hole with nothing standing in over it.
+
 ## 12. Open
 
-- Page codec ids beyond raw and LZ4 (§5). LZ4 is the default and is where the cheap
-  ratio is; a slower, denser codec (meshopt-style over the payload, deflate-family over
-  the tables) is a per-frame `codec` id away and costs no reader that already handles a
-  mixture. The quantized-position `payload_encoding` is the other half of the same
-  question, and would take most of what LZ4 currently finds.
+- ~~Page codec ids beyond raw and LZ4~~ — `2` is raw DEFLATE through the platform's own zlib (§5)
+  and is what the builder writes by default: 1.369x against LZ4's 1.295x on the same pages, for four
+  and a half times the decode. Still open is a codec that knows what it is compressing —
+  meshopt-style over the payload rather than an LZ matcher over its bytes. The quantized-position `payload_encoding` is the other half of the same
+  question, and would take most of what either general-purpose codec currently finds.
 - ~~Default `nominal_page_size`~~ — 64 KiB, `VGEO_DEFAULT_PAGE_SIZE`: one page size rather than
   Nanite's two, set between hiding fetch latency and paying for it in response time and in VRAM per
   resident page on a low-end device, with a floor at the largest group a build produces. Provisional

package/src/shade/renderer/geometry/virtual/VIRTUAL_GEOMETRY_DESIGN.md

@@ -15,12 +15,14 @@ RAM tier's budget, and `runtime/` is everything §7 describes — the selection
 pass, the VRAM page pool, the feedback loop, and the seam through which VG instances enter the
 meshlet pipeline ([runtime/RUNTIME_PLAN.md](./runtime/RUNTIME_PLAN.md)).
 
-Two playgrounds prove two different things and it is worth not confusing them.
-`shade/playground/vgeo_viewer/` puts a clamped **CPU** cut of a streaming container on screen
-through Shade's direct geometry path — it proves the DAG, the format and the clamp, and by
-construction it proves nothing about the engine. `shade/playground/vgeo_runtime/` puts an ordinary
-`Mesh` in an ordinary `Scene` and draws it entirely from a **GPU** cut through the meshlet
-pipeline — it proves the seam and nothing about the DAG. §10 says which milestone that leaves us
+`shade/playground/vgeo_runtime/` puts an ordinary `Mesh` in an ordinary `Scene` and draws it
+entirely from a **GPU** cut through the meshlet pipeline — it proves the engine seam, and
+`shade/playground/vgeo_scene/` opens a whole converted set at once, where the claim about a *scene*
+is measured. What proves the DAG, the format and the clamp is not a page at all: it is
+`runtime/cut/__fixtures__/vgeo_select_cut.js`, a CPU traversal of the same rule that every cut
+spec is held to. A third playground once drew that traversal on screen through Shade's direct
+geometry path, with its own renderer and its own streaming loop; once the GPU page could show
+everything it showed, it was a second runtime for no gain, and it was retired. §10 says which milestone that leaves us
 in, and the order the work actually arrived in.
 
 ## 1. What and why
@@ -83,7 +85,7 @@ hands-off principle argues for anyway.
   possible and matter (§3).
 - **Bounds**: `Miniball` (minimal bounding sphere, iteration-capped). That is the whole list —
   **normal cones are not part of this design**. Backface cone culling is declined outright (§9,
-  plan §5), so `cone_reserved` stays zero, and
+  plan §5), so `cone_reserved` was reclaimed by `format_version` 5 (format §7), and
   `bt_face_cluster_compute_normal_bounding_cone` — the `BinaryTopology` port of the old
   `TopoMesh` cone builder — has no consumer and no prospect of one.
 - **Renderer formats (the real seam)**: meshlets capped at 128 triangles / 128 vertices
@@ -138,8 +140,9 @@ Pinned:
   spanning an order of magnitude of error when the cut it takes is a *threshold* on error.
   The minimum share is not optional: on error spread thinly and continuously — a UV
   sphere, poles against equator — an octave alone holds a handful of clusters, and the
-  round count then scales with the cluster count rather than its logarithm, which a u8
-  `level_count` cannot survive. Measured on a 98k-triangle sphere against a sweep: growth
+  round count then scales with the cluster count rather than its logarithm, which no
+  `level_count` can survive and which a build refuses outright past
+  `VGeoLevelOptions.max_levels`. Measured on a 98k-triangle sphere against a sweep: growth
   4 cuts clusters-dragged-up by 38% for one extra level; growth 2 cuts it 60% for seven.
   On geometry of uniform error the band is the whole frontier and this *is* the sweep.
 - **A level is an ordinal, not a generation.** A group's band ordinal is what orders pages;
@@ -162,6 +165,19 @@ Pinned:
   group. A build that cannot reach one root **throws** — the runtime starts its cut at the
   root, and several parentless clusters is not a shape it can start from. The validator
   enforces it from the bytes: exactly one cluster with `parent_error = +∞`, in page 0.
+- **A step aims at a cluster count, and a cluster is bounded by two numbers.** What the
+  simplifier is handed is a triangle target, but a cluster is capped at 128 triangles *and*
+  128 vertices, and on geometry that has come apart — seams, small separate parts, the
+  patches a collapse leaves behind once it has eaten the connective tissue — there are two
+  or three vertices per triangle rather than a half. Halving the triangles then does not
+  halve the vertices, the re-cut needs as many clusters as the group consumed, and the step
+  is worth nothing to the round. So the re-cut is *measured* and the target tightened on
+  whichever of the two ceilings the attempt broke, until the step strictly shrinks its
+  group — tightened by the overshoot rather than by the cluster ratio, because what it
+  costs is fidelity and the overshoot is the least it can pay. Measured on the Zorah
+  sample: 187 of its 3,163 primitives reached a frontier no grouping could shrink, every
+  one of them this, and a 188th ran out of `VGeoLevelOptions.max_levels` inching forward a
+  merge a round — the same refusal to merge, spent on depth rather than on a stall.
 - **Islands merge by proximity, once adjacency has nothing left to offer.** A cluster alone
   in its connected component can never be coarsened — halving its triangles leaves one
   cluster where there was one — so a mesh of separate shells has no root at all under
@@ -280,7 +296,7 @@ Pinned:
   *before* it is fetched. Below page granularity, each page carries a tree over its own groups
   (format §6.1–6.2). Cost, measured: 0.3%–1.6% of asset size.
 
-  *What exists.* `playground/vgeo_viewer/select_cut.js` is this rule on the CPU, against a
+  *What exists.* `runtime/cut/__fixtures__/vgeo_select_cut.js` is this rule on the CPU, against a
   partially resident container: descend from the root's parentless groups, refine where
   `project(parent) > τ`, take the cluster where it does not, and stop where the child group is
   not selectable — recording the want that would unblock it. It is the reference the GPU pass
@@ -356,16 +372,19 @@ Pinned:
   in the file (coarse-first order is topological); non-root pages hold clusters of a
   single level band. Build-validated.
 - **Compression must not break random access.** Transparent HTTP compression does not
-  compose with range requests, so compression is per-page *inside* the container. Two codecs
-  are defined and both shipped — `raw` and a bare LZ4 block — chosen **per frame** rather than
-  per file, so a page that would not shrink is stored verbatim and says so. Measured, LZ4 is
-  worth 1.12x–1.18x on the Stanford models, and the reason it is not more is the reason to stop
-  here: the payload is float32 positions and packed attribute words, and it does not compress.
-  Quantization (§2) is the lever, not the codec.
+  compose with range requests, so compression is per-page *inside* the container. Three codecs
+  are defined and all three shipped — `raw`, a bare LZ4 block, and a bare DEFLATE stream through
+  the platform's own zlib — chosen **per frame** rather than per file, so a page that would not
+  shrink is stored verbatim and says so. Measured, LZ4 is worth 1.12x–1.18x on the Stanford
+  models and deflate about seven points more for four and a half times the decode; deflate is what
+  the builder writes, because a build happens once and a fetch happens forever. The reason neither
+  is worth more is the reason to stop here: the payload is float32 positions and packed attribute
+  words, and it does not compress. Quantization (§2) is the lever, not the codec.
 - **Coarse-first layout**: pages ordered so a plain prefix read of the file yields a
   complete coarse asset — progressive load without a feedback loop.
 
-Open: a denser page codec than LZ4, if quantization leaves one worth having;
+Open: a page codec that knows what it is compressing — meshopt-style over the payload rather
+than an LZ matcher over its bytes — if quantization leaves one worth having;
 per-attribute quantization widths (cluster-local grids); relationship to
 `MeshletGeometrySerializationAdapter` (extend vs parallel).
 
@@ -545,7 +564,7 @@ Pinned:
   `bt_mesh_validate` → level-0 clustering (+ CC split) → the §3 round loop → per-cluster
   encode → page assignment (level-banded, DAG + spatial locality, acyclicity check) →
   container emit. The encode is the miniball sphere, the AABB, and `SHADE_MESHLET_V1`
-  attributes at their shipped widths (format §8): `cone_reserved` is zero because cone culling
+  attributes at their shipped widths (format §8): there is no cone field because cone culling
   is declined (§9), and positions are raw float32 because quantization is a `payload_encoding`
   that does not exist yet.
 - **The weld tolerance is scale-relative**, a fraction of each geometry's bounding-box
@@ -591,8 +610,8 @@ canonicalizing them is a preprocessor's job).
 
 - **Backface normal-cone culling — declined outright, not deferred.** The two-pass HZB already
   rejects what a cone would, on evidence rather than on a bound; see plan §5 for the mechanism
-  and the reports behind it. `cone_reserved` stays a zeroed reserved field (format §7). This is
-  the one entry here that is not a "v1" qualifier.
+  and the reports behind it. `cone_reserved` was a zeroed reserved field until `format_version` 5
+  spent it on `subtree_aabb` (format §7). This is the one entry here that is not a "v1" qualifier.
 - Skinned / morphing / WPO meshes through the VG path (static geometry only).
 - **Non-opaque VG instances.** The cut runs beside the mesh→meshlet expansion of the *opaque*
   rasterization paths, and the transparent and alpha-tested bucket path
@@ -629,7 +648,7 @@ is the piece still missing, and M1 is where the work now starts.
   Acceptance: crack-free under τ sweep and flythrough (incl. group-boundary polyline and
   flip validation); drawn-triangle count tracks resolution, not source size; §3 build
   validations green.
-  **Done**: the builder; a CPU cut (`playground/vgeo_viewer/select_cut.js`) that is a traversal
+  **Done**: the builder; a CPU cut (`runtime/cut/__fixtures__/vgeo_select_cut.js`) that is a traversal
   rather than the flat pass planned here, and that runs against a partially resident container,
   which was M2's job; τ-sweep watertightness as a spec (`build/vgeo_cut.spec.js` counts edges
   used by one triangle instead of two, at a spread of thresholds, and wants zero); the

package/src/shade/renderer/geometry/virtual/VIRTUAL_GEOMETRY_PLAN.md

@@ -33,7 +33,7 @@ accepted-and-waiting one.
 - **Cluster-count simplification target** `[M §2.2]`, and a minimum cluster fill through the
   generalized leaf repack `[V §3.3]`.
 - **Compactness-weighted cluster adjacency** `[M §2.3]` — `compactness()` in
-  `build/vgeo_build_levels.js`.
+  `build/level/vgeo_build_levels.js`.
 - **Speculative groups, rejected individually** `[M §2.4]`.
 - **Per-level summary table in the file head** `[V §4.1, §6.1]` — VGEO_FORMAT §4.1.
 - **A traversal metric on the page DAG, and a group tree inside each page** `[V §2.1, §6.3]` —
@@ -72,12 +72,13 @@ accepted-and-waiting one.
   362 non-root groups have split parents: 355 of 576 camera positions double-drew, up to 10.7%
   of drawn triangles, before. Zero after. It reads as corrupt geometry rather than as a missing
   page, which is why the tool that found it could not name it.
-- **A CPU cut against a partially resident container** — `playground/vgeo_viewer/`.
-  `select_cut.js` is the runtime's rule rather than a debug approximation of it; the viewer is
-  what makes clamping, streaming and eviction watchable, and `__state()` is what makes it
-  assertable from a headless browser. It draws through Shade's direct geometry path, not the
-  meshlet pipeline — so it proves the DAG and the format, and proves nothing about the engine
-  seam.
+- **A CPU cut against a partially resident container** —
+  `runtime/cut/__fixtures__/vgeo_select_cut.js`. It is the runtime's rule rather than a debug
+  approximation of it, and `vgeo_select_cut.spec.js` holds it to the format's guarantees. A
+  `vgeo_viewer` playground used to draw it on screen through Shade's direct geometry path, which is
+  what made clamping, streaming and eviction watchable; once `playground/vgeo_runtime/` could show
+  all of that through the meshlet pipeline, the page was a second renderer and a second streaming
+  loop for no gain, and it was retired. The traversal stayed, because it is the oracle.
 
 - **The GPU runtime** — `runtime/`, and [runtime/RUNTIME_PLAN.md](./runtime/RUNTIME_PLAN.md) for the
   design and the adversarial review that reshaped it. The cut is a wavefront BFS over the page DAG
@@ -95,7 +96,7 @@ accepted-and-waiting one.
     evaluator does not. §6 states the fact without stating it as a term of the rule, because §4 was
     written for a traversal.
   - **Page size decides whether that state is even reachable.** At the 8 KB pages
-    `select_cut.spec.js` uses, a torus puts exactly one group in every page — so a blocked group is
+    `vgeo_select_cut.spec.js` uses, a torus puts exactly one group in every page — so a blocked group is
     a blocked page, no page is ever mixed, and no page is ever entered twice. Measured: 40 pages
     withheld one at a time and 60 random residency subsets produced *no* mixed page. At 64 KB the
     median page holds eight groups and it is ordinary. A spec for anything about mixed selectability
@@ -120,7 +121,7 @@ prefetch.
 ### 2.1 A partitioning fallback for when METIS fails `[M §3.3]`, `[V §3.2]` — LANDED
 
 `core/graph/graph_partition_spectral.js` — recursive spectral bisection over CSR, matrix-free,
-signature-compatible with `metis_partition_kway`. `build/vgeo_partition_graph.js` tries METIS
+signature-compatible with `metis_partition_kway`. `build/partition/vgeo_partition_graph.js` tries METIS
 and falls back to it; both of the builder's partitioning sites go through that wrapper.
 
 Notes worth keeping:
@@ -212,7 +213,7 @@ installed page can be re-tested without walking back to its parent.
 width at the top. This one has *no* paging question by construction: it is inside a page, it
 ships and evicts with it, and it cannot dangle.
 
-Both landed together; VGEO_FORMAT §6.1–6.2 specifies them, `build/vgeo_build_page_nodes.js`
+Both landed together; VGEO_FORMAT §6.1–6.2 specifies them, `build/page/vgeo_build_page_nodes.js`
 builds them. Notes worth keeping:
 
 - The tree needs no partitioner. A page's groups arrive in Morton order of their centroid, so
@@ -243,7 +244,7 @@ for the first few bands, which are also the cheapest to walk.
 LOD-metric sphere and error range (VGEO_FORMAT §5, §6.2), and every page carries a fanout-4 tree
 over its own groups (§6.1). The writer emits them, `vgeo_validate_container` checks them
 (§11.10–11.11) with corruption tests behind both checks, and **nothing reads either**.
-`VGeoPage` records `node_count` and stops; `select_cut.js` descends group by group.
+`VGeoPage` records `node_count` and stops; `vgeo_select_cut` descends group by group.
 
 This is not a defect to fix on its own account. Building a consumer for its own sake would fix
 the interface before the pass that has to live with it, and the CPU traversal does not need the
@@ -451,9 +452,9 @@ attacked:
   library exposing cone data, and Remedy report the same for Northlight. Taken together with
   the mechanism above, there is nothing left to measure.
 
-  Consequences, so that nobody re-derives them: `cone_reserved` stays a zeroed reserved u32
-  (format §7) — reclaiming 4 bytes of 112 is not worth a `format_version` move, and the page
-  codec compresses a constant-zero column away. `bt_face_cluster_compute_normal_bounding_cone`
+  Consequences, so that nobody re-derives them: `cone_reserved` was a zeroed reserved u32 until
+  `format_version` 5 (format §7) — reclaiming 4 bytes of 112 was never worth a version move on its
+  own, and it went when `subtree_aabb` needed 24 and the version moved anyway. `bt_face_cluster_compute_normal_bounding_cone`
   has no consumer and no prospect of one.
 - **Fixed-size residency slots** `[M §2.5]`. Micron gives every resident patch one slot of
   `MICRON_PATCH_SIZE_MAX × 3` vertices with occupancy in a BitSet: no allocator, no