@woosh/meep-engine 3.24.0 → 3.25.0

package/src/shade/renderer/geometry/virtual/build/vgeo_assemble_pages.d.ts

@@ -4,8 +4,8 @@
  * @param {VirtualGeometryGroup[][]} groups_by_level indexed by level; every group of every level,
  *     including the root level's
  * @param {Float32Array} object_bounds `[min xyz, max xyz]` of the whole geometry, for the Morton grid
- * @param {number} nominal_page_size target decoded bytes per page; a single indivisible group is
- *     allowed to exceed it
+ * @param {number} nominal_page_size decoded bytes per page, as a hard cap: no returned page decodes
+ *     to more, and a group that cannot fit one on its own throws
  * @returns {VirtualGeometryPage[]} in file order, root page first
  */
 export function vgeo_assemble_pages(groups_by_level: VirtualGeometryGroup[][], object_bounds: Float32Array, nominal_page_size: number): VirtualGeometryPage[];

package/src/shade/renderer/geometry/virtual/build/vgeo_assemble_pages.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"vgeo_assemble_pages.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/geometry/virtual/build/vgeo_assemble_pages.js"],"names":[],"mappings":"AAkEA;;;;;;;;;GASG;AACH,qDAPW,sBAAsB,EAAE,iBAExB,YAAY,qBACZ,MAAM,GAEJ,mBAAmB,EAAE,CAkGjC;oCAvKmC,sCAAsC"}
+{"version":3,"file":"vgeo_assemble_pages.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/geometry/virtual/build/vgeo_assemble_pages.js"],"names":[],"mappings":"AA2JA;;;;;;;;;GASG;AACH,qDAPW,sBAAsB,EAAE,iBAExB,YAAY,qBACZ,MAAM,GAEJ,mBAAmB,EAAE,CA+HjC;oCA5RmC,sCAAsC"}

package/src/shade/renderer/geometry/virtual/build/vgeo_assemble_pages.js

@@ -2,9 +2,11 @@ import { assert } from "../../../../../core/assert.js";
 import { v3_morton_encode_bounded } from "../../../../../core/geom/3d/morton/v3_morton_encode_bounded.js";
 import { VGEO_CLUSTER_RECORD_SIZE } from "../format/cluster/VGEO_CLUSTER_RECORD_SIZE.js";
 import { VGEO_GROUP_RECORD_SIZE } from "../format/page/VGEO_GROUP_RECORD_SIZE.js";
+import { VGEO_NODE_RECORD_SIZE } from "../format/page/VGEO_NODE_RECORD_SIZE.js";
 import { VGEO_PAGE_HEADER_SIZE } from "../format/page/VGEO_PAGE_HEADER_SIZE.js";
 import { VirtualGeometryPage } from "../format/dag/VirtualGeometryPage.js";
 import { vgeo_build_page_nodes } from "./vgeo_build_page_nodes.js";
+import { vgeo_page_node_count } from "./vgeo_page_node_count.js";
 
 /**
  * Lay the DAG's groups out into pages, in the coarse-first file order the format requires.
@@ -18,6 +20,13 @@ import { vgeo_build_page_nodes } from "./vgeo_build_page_nodes.js";
  * adjacent wanted pages into one range, so what the order buys is that pages near each other in the
  * file are near each other in space.
  *
+ * **`nominal_page_size` is a cap, not a target.** No page this function returns decodes to more than
+ * it — that is format invariant §11.14, and it is what lets a VRAM tier address pages as fixed-stride
+ * slots with a multiply instead of an allocator. The two rules above leave exactly one way for a page
+ * to want more than the cap: a single group too large for a page of its own. Nothing can be done
+ * about that here — §11.1 makes a group atomic to its page — so the build refuses, and names the page
+ * size that would work.
+ *
  * @author Alex Goldring
  * @copyright Company Named Limited (c) 2026
  */
@@ -64,20 +73,102 @@ function group_centroid(group) {
     return result;
 }
 
+/**
+ * What a page of `group_count` groups holding `content` bytes of group, cluster and payload records
+ * comes to decoded — exactly what {@link vgeo_write_container} will lay out, node table included.
+ *
+ * The node table is the part that is easy to forget and impossible to leave out: it is written into
+ * the page between the group and cluster tables, it is sized from the group count rather than from
+ * anything already counted, and a fill loop that ignores it overshoots the cap by 32 bytes a node.
+ *
+ * @param {number} group_count
+ * @param {number} content bytes of group records, cluster records and payloads
+ * @returns {number}
+ */
+function page_decoded_size(group_count, content) {
+    return VGEO_PAGE_HEADER_SIZE
+        + vgeo_page_node_count(group_count) * VGEO_NODE_RECORD_SIZE
+        + content;
+}
+
+/**
+ * The smallest `nominal_page_size` a group could ever be laid out under: its own bytes in a page of
+ * its own, which is one group and therefore one node.
+ *
+ * @param {VirtualGeometryGroup} group
+ * @returns {number}
+ */
+function group_minimum_page_size(group) {
+    return page_decoded_size(1, group_size_in_page(group));
+}
+
+/**
+ * Refuse a page size no layout could satisfy, before laying anything out.
+ *
+ * Up front, and over every group rather than stopping at the first offender, so that the size the
+ * message names is one the whole build would actually succeed at — a caller told about the first
+ * group that did not fit would raise the page size, run the build again, and meet the next one.
+ *
+ * @param {VirtualGeometryGroup[][]} groups_by_level
+ * @param {number} nominal_page_size
+ */
+function reject_groups_larger_than_a_page(groups_by_level, nominal_page_size) {
+    let worst = undefined;
+    let worst_level = 0;
+    let worst_index = 0;
+    let worst_needs = 0;
+
+    let over_count = 0;
+    let total_count = 0;
+
+    groups_by_level.forEach((groups, level) => {
+        groups.forEach((group, index) => {
+            total_count++;
+
+            const needs = group_minimum_page_size(group);
+
+            if (needs > nominal_page_size) {
+                over_count++;
+            }
+
+            if (needs > worst_needs) {
+                worst = group;
+                worst_level = level;
+                worst_index = index;
+                worst_needs = needs;
+            }
+        });
+    });
+
+    if (worst_needs <= nominal_page_size) {
+        return;
+    }
+
+    throw new Error(
+        `virtual geometry: group ${worst_index} of level ${worst_level} holds ${worst.clusters.length}`
+        + ` clusters and needs a page of ${worst_needs} bytes, but nominal_page_size is`
+        + ` ${nominal_page_size}. A group never spans pages (VGEO_FORMAT §11.1) and a page never`
+        + ` exceeds nominal_page_size (§11.14), so ${over_count} of this build's ${total_count} groups`
+        + ` cannot be placed. Build with nominal_page_size of at least ${worst_needs}.`
+    );
+}
+
 /**
  * Assign groups to pages.
  *
  * @param {VirtualGeometryGroup[][]} groups_by_level indexed by level; every group of every level,
  *     including the root level's
  * @param {Float32Array} object_bounds `[min xyz, max xyz]` of the whole geometry, for the Morton grid
- * @param {number} nominal_page_size target decoded bytes per page; a single indivisible group is
- *     allowed to exceed it
+ * @param {number} nominal_page_size decoded bytes per page, as a hard cap: no returned page decodes
+ *     to more, and a group that cannot fit one on its own throws
  * @returns {VirtualGeometryPage[]} in file order, root page first
  */
 export function vgeo_assemble_pages(groups_by_level, object_bounds, nominal_page_size) {
     assert.isPositiveInteger(nominal_page_size, 'nominal_page_size');
     assert.greaterThan(groups_by_level.length, 0, 'groups_by_level.length');
 
+    reject_groups_larger_than_a_page(groups_by_level, nominal_page_size);
+
     const pages = [];
 
     const top_level = groups_by_level.length - 1;
@@ -118,8 +209,26 @@ export function vgeo_assemble_pages(groups_by_level, object_bounds, nominal_page
             // header alone.
             const page = open_page(level);
 
+            let content = 0;
+
             for (const group of groups) {
                 place(page, group);
+
+                content += group_size_in_page(group);
+            }
+
+            // The cap has no exception, and this is the one page the fill rule below does not get to
+            // decide the contents of. A converged build puts a single root group here (§11.7), so
+            // reaching this needs a topmost level of several groups that together outgrow a page.
+            const size = page_decoded_size(page.groups.length, content);
+
+            if (size > nominal_page_size) {
+                throw new Error(
+                    `virtual geometry: the topmost level's ${groups.length} groups come to ${size}`
+                    + ` bytes and the root page must hold all of them (VGEO_FORMAT §11.4), but`
+                    + ` nominal_page_size is ${nominal_page_size}. Build with nominal_page_size of at`
+                    + ` least ${size}.`
+                );
             }
 
             continue;
@@ -138,24 +247,28 @@ export function vgeo_assemble_pages(groups_by_level, object_bounds, nominal_page
         keyed.sort((a, b) => (a.code - b.code) || (a.index - b.index));
 
         let page = undefined;
-        let page_size = 0;
+        let content = 0;
 
         for (const entry of keyed) {
             const size = group_size_in_page(entry.group);
 
-            if (page !== undefined && page_size + size > nominal_page_size) {
+            // What the page would come to *with* this group, node table and all — not what it came
+            // to without it. The node table grows with the group count, so a page measured before
+            // the group lands is measured under a smaller tree than the one it will be written with.
+            if (page !== undefined
+                && page_decoded_size(page.groups.length + 1, content + size) > nominal_page_size) {
                 page = undefined;
             }
 
             if (page === undefined) {
                 page = open_page(level);
 
-                page_size = VGEO_PAGE_HEADER_SIZE;
+                content = 0;
             }
 
             place(page, entry.group);
 
-            page_size += size;
+            content += size;
         }
     }
 
@@ -167,6 +280,11 @@ export function vgeo_assemble_pages(groups_by_level, object_bounds, nominal_page
     // settled once every group has found its page.
     for (const page of pages) {
         page.nodes = vgeo_build_page_nodes(page);
+
+        assert.equal(
+            page.nodes.length, vgeo_page_node_count(page.groups.length),
+            `page ${page.index}: the tree came to a different size than the fill loop budgeted for`
+        );
     }
 
     return pages;

package/src/shade/renderer/geometry/virtual/build/vgeo_page_node_count.d.ts

@@ -0,0 +1,22 @@
+/**
+ * How many nodes {@link vgeo_build_page_nodes} will put over a page holding `group_count` groups.
+ *
+ * The tree's shape is a function of the group *count* alone — every node covers a contiguous run of
+ * the page's Morton order and splits it into as-near-equal parts as integers allow — so the node
+ * table's size is known before the tree exists. Which is what the page assembler needs: the node
+ * table is part of the decoded page, and a page whose size is a hard bound has to be measured with
+ * it included, while the tree itself cannot be built until the page's last group has arrived.
+ *
+ * This duplicates the recurrence in {@link vgeo_build_page_nodes} rather than sharing it, because
+ * the two want different things from it — one wants the ranges and one wants only how many there
+ * are — and the cost of the duplication is a spec that runs both and compares.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+/**
+ * @param {number} group_count
+ * @returns {number} nodes, at least one
+ */
+export function vgeo_page_node_count(group_count: number): number;
+//# sourceMappingURL=vgeo_page_node_count.d.ts.map

package/src/shade/renderer/geometry/virtual/build/vgeo_page_node_count.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vgeo_page_node_count.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/geometry/virtual/build/vgeo_page_node_count.js"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;GAeG;AAEH;;;GAGG;AACH,kDAHW,MAAM,GACJ,MAAM,CA8BlB"}

package/src/shade/renderer/geometry/virtual/build/vgeo_page_node_count.js

@@ -0,0 +1,53 @@
+import { assert } from "../../../../../core/assert.js";
+import { VGEO_NODE_FANOUT } from "../format/page/VGEO_NODE_FANOUT.js";
+
+/**
+ * How many nodes {@link vgeo_build_page_nodes} will put over a page holding `group_count` groups.
+ *
+ * The tree's shape is a function of the group *count* alone — every node covers a contiguous run of
+ * the page's Morton order and splits it into as-near-equal parts as integers allow — so the node
+ * table's size is known before the tree exists. Which is what the page assembler needs: the node
+ * table is part of the decoded page, and a page whose size is a hard bound has to be measured with
+ * it included, while the tree itself cannot be built until the page's last group has arrived.
+ *
+ * This duplicates the recurrence in {@link vgeo_build_page_nodes} rather than sharing it, because
+ * the two want different things from it — one wants the ranges and one wants only how many there
+ * are — and the cost of the duplication is a spec that runs both and compares.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+
+/**
+ * @param {number} group_count
+ * @returns {number} nodes, at least one
+ */
+export function vgeo_page_node_count(group_count) {
+    assert.isPositiveInteger(group_count, 'group_count');
+
+    /**
+     * Node spans in breadth-first order; the walk appends to it as it goes, which is the same order
+     * the builder allocates nodes in.
+     * @type {number[]}
+     */
+    const spans = [group_count];
+
+    for (let index = 0; index < spans.length; index++) {
+        const span = spans[index];
+
+        if (span <= VGEO_NODE_FANOUT) {
+            continue;
+        }
+
+        const child_count = Math.min(VGEO_NODE_FANOUT, Math.ceil(span / VGEO_NODE_FANOUT));
+
+        for (let child = 0; child < child_count; child++) {
+            spans.push(
+                Math.floor((span * (child + 1)) / child_count)
+                - Math.floor((span * child) / child_count)
+            );
+        }
+    }
+
+    return spans.length;
+}

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

@@ -48,7 +48,14 @@ export class VGeoWriteOptions {
      */
     vertex_attribute_mask: number;
     /**
-     * The page size the assembler aimed at. Informational; readers must not assume it.
+     * The page size the assembler laid pages out against, and the bound the written file will
+     * promise its readers: {@link vgeo_write_container} refuses a page list that exceeds it, and
+     * marks the container with the bounded-pages feature bit when it does not (§11.14).
+     *
+     * Zero states no page size, and then neither happens. That is for a caller that builds a page
+     * list by hand and has no such size to state — the reader and residency specs' synthetic
+     * containers — and not something a real build does.
+     *
      * @type {number}
      */
     nominal_page_size: number;

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

@@ -1 +1 @@
-{"version":3,"file":"VGeoWriteOptions.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/geometry/virtual/format/VGeoWriteOptions.js"],"names":[],"mappings":"AAEA;;;;;GAKG;AACH;IACI;;;;;;;;;;OAUG;IACH,OAFU,MAAM,CAEO;IAEvB;;;OAGG;IACH,QAFU,iBAAiB,CAEf;IAEZ;;;OAGG;IACH,qBAFU,MAAM,CAEQ;IAExB;;;OAGG;IACH,mBAFU,MAAM,CAEM;IAEtB;;;OAGG;IACH,eAFU,YAAY,CAEc;IAEpC;;;OAGG;IACH,eAFU,YAAY,CAEc;IAEpC;;;OAGG;IACH,uBAFU,MAAM,CAEU;IAE1B;;;OAGG;IACH,mBAFU,MAAM,CAEM;CACzB"}
+{"version":3,"file":"VGeoWriteOptions.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/geometry/virtual/format/VGeoWriteOptions.js"],"names":[],"mappings":"AAEA;;;;;GAKG;AACH;IACI;;;;;;;;;;OAUG;IACH,OAFU,MAAM,CAEO;IAEvB;;;OAGG;IACH,QAFU,iBAAiB,CAEf;IAEZ;;;OAGG;IACH,qBAFU,MAAM,CAEQ;IAExB;;;OAGG;IACH,mBAFU,MAAM,CAEM;IAEtB;;;OAGG;IACH,eAFU,YAAY,CAEc;IAEpC;;;OAGG;IACH,eAFU,YAAY,CAEc;IAEpC;;;OAGG;IACH,uBAFU,MAAM,CAEU;IAE1B;;;;;;;;;;OAUG;IACH,mBAFU,MAAM,CAEM;CACzB"}

package/src/shade/renderer/geometry/virtual/format/VGeoWriteOptions.js

@@ -57,7 +57,14 @@ export class VGeoWriteOptions {
     vertex_attribute_mask = 1;
 
     /**
-     * The page size the assembler aimed at. Informational; readers must not assume it.
+     * The page size the assembler laid pages out against, and the bound the written file will
+     * promise its readers: {@link vgeo_write_container} refuses a page list that exceeds it, and
+     * marks the container with the bounded-pages feature bit when it does not (§11.14).
+     *
+     * Zero states no page size, and then neither happens. That is for a caller that builds a page
+     * list by hand and has no such size to state — the reader and residency specs' synthetic
+     * containers — and not something a real build does.
+     *
      * @type {number}
      */
     nominal_page_size = 0;

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

@@ -0,0 +1,16 @@
+/**
+ * `feature_flags_ignorable` bit 0: **every page of this container decodes to no more than
+ * `nominal_page_size` bytes** (VGEO_FORMAT §11.14).
+ *
+ * It sits in the *ignorable* word rather than the required one on purpose. The bit adds a promise
+ * and takes nothing away, so a reader that has never heard of it reads the file exactly as it read
+ * the ones before — which is what §4 means by ignorable, and is why this needs no format version.
+ * A reader that *does* care — one allocating fixed-stride page slots, where a single over-size page
+ * is a buffer overrun rather than a waste — requires the bit and refuses a container built before
+ * it, which is a clean refusal instead of a silent one.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export const VGEO_FEATURE_IGNORABLE_BOUNDED_PAGES: 1;
+//# sourceMappingURL=VGEO_FEATURE_IGNORABLE_BOUNDED_PAGES.d.ts.map

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

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

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

@@ -0,0 +1,15 @@
+/**
+ * `feature_flags_ignorable` bit 0: **every page of this container decodes to no more than
+ * `nominal_page_size` bytes** (VGEO_FORMAT §11.14).
+ *
+ * It sits in the *ignorable* word rather than the required one on purpose. The bit adds a promise
+ * and takes nothing away, so a reader that has never heard of it reads the file exactly as it read
+ * the ones before — which is what §4 means by ignorable, and is why this needs no format version.
+ * A reader that *does* care — one allocating fixed-stride page slots, where a single over-size page
+ * is a buffer overrun rather than a waste — requires the bit and refuses a container built before
+ * it, which is a clean refusal instead of a silent one.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export const VGEO_FEATURE_IGNORABLE_BOUNDED_PAGES = 1;

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

@@ -0,0 +1,54 @@
+/**
+ * The page size a build targets, and the one a runtime expects, when neither is told otherwise.
+ *
+ * One constant rather than two defaults because the two ends have to agree exactly: a page size is a
+ * hard bound (`VGEO_FORMAT.md` §11.14), and a VRAM tier sizing fixed-stride slots against a
+ * different number than the builder laid pages out to refuses every container it is handed. Moving
+ * this moves both ends together.
+ *
+ * **64 KiB, and the reason is that there is only one of it.** Nanite carries two page sizes — 128 KB
+ * and 32 KB — for different purposes. We do not want two page types: one size is what makes a slot
+ * address a multiply and a residency budget a page count, and every structure downstream of the
+ * bound gets simpler for there being a single number. So the question is which single number, and it
+ * is pulled three ways:
+ *
+ * - **Bigger hides network latency.** A page is one HTTP range request, and a round trip costs the
+ *   same whatever it carries.
+ * - **Bigger costs response time.** Nothing in a page is usable until all of it has arrived, so the
+ *   larger the page the longer the wait between asking for detail and drawing it.
+ * - **Bigger exhausts the GPU sooner**, and unevenly: a fixed stride means VRAM per resident page
+ *   whether the page is full or not, and the device that runs out first is the low-end one this has
+ *   to keep working on.
+ *
+ * Against that, 32 KiB is too near the floor — a page has to hold a useful number of clusters in the
+ * **worst** case, and the worst case is a payload the encoder could not compress at all. 128 KiB is
+ * more than the latency argument buys once the other two are paid. 64 KiB sits between them.
+ *
+ * Measured fill agrees, which is corroboration rather than the reason. Decoded page sizes read back
+ * from two built tori, `waste` being what a fixed stride leaves unused:
+ *
+ * | page size | 640×320 torus | | | 320×160 torus | | |
+ * |---|---:|---:|---:|---:|---:|---:|
+ * | | pages | mean fill | waste | pages | mean fill | waste |
+ * | 16 KiB | 1,253 | 74% | 5.06 MiB | 317 | 73% | 1.33 MiB |
+ * | **64 KiB** | **254** | **91%** | **1.42 MiB** | **69** | **84%** | **0.71 MiB** |
+ * | 256 KiB | 69 | 84% | 2.80 MiB | 23 | 63% | 2.15 MiB |
+ *
+ * Small pages pay the per-page header and node table on more pages and cut bands finer. Large pages
+ * are worse than their mean: a band's remainder goes in its last page, so with few pages to a band
+ * that remainder dominates — at 256 KiB the tenth-percentile page is 24% and 4% full on these two,
+ * against 86% and 32% at 64 KiB.
+ *
+ * One floor is hard rather than a matter of taste: a group is atomic to its page, so the size has to
+ * clear the largest group a build produces or the build is refused outright. The largest here needs
+ * about 12 KiB, which is the other reason 32 KiB is uncomfortably close.
+ *
+ * **Provisional.** Nothing above is a measurement of the thing that will actually decide it — page
+ * size against fetch latency and VRAM pressure on a real device under a real camera — and
+ * quantization will move what a cluster costs and the fill curve with it.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export const VGEO_DEFAULT_PAGE_SIZE: number;
+//# sourceMappingURL=VGEO_DEFAULT_PAGE_SIZE.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"VGEO_DEFAULT_PAGE_SIZE.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/geometry/virtual/format/page/VGEO_DEFAULT_PAGE_SIZE.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmDG;AACH,4CAAgD"}

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

@@ -0,0 +1,53 @@
+/**
+ * The page size a build targets, and the one a runtime expects, when neither is told otherwise.
+ *
+ * One constant rather than two defaults because the two ends have to agree exactly: a page size is a
+ * hard bound (`VGEO_FORMAT.md` §11.14), and a VRAM tier sizing fixed-stride slots against a
+ * different number than the builder laid pages out to refuses every container it is handed. Moving
+ * this moves both ends together.
+ *
+ * **64 KiB, and the reason is that there is only one of it.** Nanite carries two page sizes — 128 KB
+ * and 32 KB — for different purposes. We do not want two page types: one size is what makes a slot
+ * address a multiply and a residency budget a page count, and every structure downstream of the
+ * bound gets simpler for there being a single number. So the question is which single number, and it
+ * is pulled three ways:
+ *
+ * - **Bigger hides network latency.** A page is one HTTP range request, and a round trip costs the
+ *   same whatever it carries.
+ * - **Bigger costs response time.** Nothing in a page is usable until all of it has arrived, so the
+ *   larger the page the longer the wait between asking for detail and drawing it.
+ * - **Bigger exhausts the GPU sooner**, and unevenly: a fixed stride means VRAM per resident page
+ *   whether the page is full or not, and the device that runs out first is the low-end one this has
+ *   to keep working on.
+ *
+ * Against that, 32 KiB is too near the floor — a page has to hold a useful number of clusters in the
+ * **worst** case, and the worst case is a payload the encoder could not compress at all. 128 KiB is
+ * more than the latency argument buys once the other two are paid. 64 KiB sits between them.
+ *
+ * Measured fill agrees, which is corroboration rather than the reason. Decoded page sizes read back
+ * from two built tori, `waste` being what a fixed stride leaves unused:
+ *
+ * | page size | 640×320 torus | | | 320×160 torus | | |
+ * |---|---:|---:|---:|---:|---:|---:|
+ * | | pages | mean fill | waste | pages | mean fill | waste |
+ * | 16 KiB | 1,253 | 74% | 5.06 MiB | 317 | 73% | 1.33 MiB |
+ * | **64 KiB** | **254** | **91%** | **1.42 MiB** | **69** | **84%** | **0.71 MiB** |
+ * | 256 KiB | 69 | 84% | 2.80 MiB | 23 | 63% | 2.15 MiB |
+ *
+ * Small pages pay the per-page header and node table on more pages and cut bands finer. Large pages
+ * are worse than their mean: a band's remainder goes in its last page, so with few pages to a band
+ * that remainder dominates — at 256 KiB the tenth-percentile page is 24% and 4% full on these two,
+ * against 86% and 32% at 64 KiB.
+ *
+ * One floor is hard rather than a matter of taste: a group is atomic to its page, so the size has to
+ * clear the largest group a build produces or the build is refused outright. The largest here needs
+ * about 12 KiB, which is the other reason 32 KiB is uncomfortably close.
+ *
+ * **Provisional.** Nothing above is a measurement of the thing that will actually decide it — page
+ * size against fetch latency and VRAM pressure on a real device under a real camera — and
+ * quantization will move what a cluster costs and the fill curve with it.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export const VGEO_DEFAULT_PAGE_SIZE = 64 * 1024;

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

@@ -26,6 +26,14 @@ export class VGeoContainerHeader {
      * @type {number}
      */
     payload_encoding: number;
+    /**
+     * The header's `feature_flags_ignorable` word, verbatim. Bits a reader does not know are to be
+     * ignored rather than refused (§4), which is why the whole word is kept rather than a decoded
+     * set of booleans: the only bit defined so far is
+     * {@link VGEO_FEATURE_IGNORABLE_BOUNDED_PAGES}, and a reader that needs it tests for it.
+     * @type {number}
+     */
+    feature_flags_ignorable: number;
     /**
      * Hex, as the 16 asset-id bytes stand in the file. In a streamed deployment this is also the
      * file's name, which is what makes same-URL version skew impossible.
@@ -83,8 +91,11 @@ export class VGeoContainerHeader {
      */
     dir_block_checksums_offset: number;
     /**
-     * The build parameter, informational. A reader must never assume it: per-page sizes come from
-     * child tables, frames, or the directory.
+     * Bytes a decoded page may come to. A **hard bound** when
+     * {@link VGEO_FEATURE_IGNORABLE_BOUNDED_PAGES} is set in {@link feature_flags_ignorable}: no
+     * page of the container exceeds it, which is what a fixed-stride page slot is sized against.
+     * Without that bit it is the advisory build parameter it used to be, and a reader must take
+     * per-page sizes from child tables, frames, or the directory as it always has.
      * @type {number}
      */
     nominal_page_size: number;

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

@@ -1 +1 @@
-{"version":3,"file":"VGeoContainerHeader.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/geometry/virtual/format/read/VGeoContainerHeader.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH;IACI;;OAEG;IACH,gBAFU,MAAM,CAEG;IAEnB;;;;OAIG;IACH,oBAFU,MAAM,CAEO;IAEvB;;OAEG;IACH,kBAFU,MAAM,CAEK;IAErB;;;;OAIG;IACH,UAFU,MAAM,CAEF;IAEd;;;;;OAKG;IACH,gBAFU,MAAM,CAEI;IAEpB;;;;OAIG;IACH,uBAFU,MAAM,CAEU;IAE1B;;OAEG;IACH,aAFU,MAAM,CAEA;IAEhB;;OAEG;IACH,gBAFU,MAAM,CAEG;IAEnB;;OAEG;IACH,cAFU,MAAM,CAEC;IAEjB;;;OAGG;IACH,kBAFU,MAAM,CAEK;IAErB;;;;OAIG;IACH,sBAFU,MAAM,CAES;IAEzB;;;OAGG;IACH,wBAFU,MAAM,CAEW;IAE3B;;;OAGG;IACH,kBAFU,MAAM,CAEK;IAErB;;OAEG;IACH,4BAFU,MAAM,CAEe;IAE/B;;;;OAIG;IACH,mBAFU,MAAM,CAEM;IAEtB;;;OAGG;IACH,qBAFU,MAAM,CAEQ;IAExB;;OAEG;IACH,mBAFU,MAAM,CAEM;IAEtB;;;OAGG;IACH,eAFU,YAAY,CAEc;IAEpC;;;OAGG;IACH,eAFU,YAAY,CAEc;IAEpC;;;OAGG;IACH,QAFU,iBAAiB,CAEf;IAEZ;;;;OAIG;IACH,wBAEC;CACJ"}
+{"version":3,"file":"VGeoContainerHeader.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/geometry/virtual/format/read/VGeoContainerHeader.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH;IACI;;OAEG;IACH,gBAFU,MAAM,CAEG;IAEnB;;;;OAIG;IACH,oBAFU,MAAM,CAEO;IAEvB;;OAEG;IACH,kBAFU,MAAM,CAEK;IAErB;;;;;;OAMG;IACH,yBAFU,MAAM,CAEY;IAE5B;;;;OAIG;IACH,UAFU,MAAM,CAEF;IAEd;;;;;OAKG;IACH,gBAFU,MAAM,CAEI;IAEpB;;;;OAIG;IACH,uBAFU,MAAM,CAEU;IAE1B;;OAEG;IACH,aAFU,MAAM,CAEA;IAEhB;;OAEG;IACH,gBAFU,MAAM,CAEG;IAEnB;;OAEG;IACH,cAFU,MAAM,CAEC;IAEjB;;;OAGG;IACH,kBAFU,MAAM,CAEK;IAErB;;;;OAIG;IACH,sBAFU,MAAM,CAES;IAEzB;;;OAGG;IACH,wBAFU,MAAM,CAEW;IAE3B;;;OAGG;IACH,kBAFU,MAAM,CAEK;IAErB;;OAEG;IACH,4BAFU,MAAM,CAEe;IAE/B;;;;;;;OAOG;IACH,mBAFU,MAAM,CAEM;IAEtB;;;OAGG;IACH,qBAFU,MAAM,CAEQ;IAExB;;OAEG;IACH,mBAFU,MAAM,CAEM;IAEtB;;;OAGG;IACH,eAFU,YAAY,CAEc;IAEpC;;;OAGG;IACH,eAFU,YAAY,CAEc;IAEpC;;;OAGG;IACH,QAFU,iBAAiB,CAEf;IAEZ;;;;OAIG;IACH,wBAEC;CACJ"}

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

@@ -29,6 +29,15 @@ export class VGeoContainerHeader {
      */
     payload_encoding = 0;
 
+    /**
+     * The header's `feature_flags_ignorable` word, verbatim. Bits a reader does not know are to be
+     * ignored rather than refused (§4), which is why the whole word is kept rather than a decoded
+     * set of booleans: the only bit defined so far is
+     * {@link VGEO_FEATURE_IGNORABLE_BOUNDED_PAGES}, and a reader that needs it tests for it.
+     * @type {number}
+     */
+    feature_flags_ignorable = 0;
+
     /**
      * Hex, as the 16 asset-id bytes stand in the file. In a streamed deployment this is also the
      * file's name, which is what makes same-URL version skew impossible.
@@ -97,8 +106,11 @@ export class VGeoContainerHeader {
     dir_block_checksums_offset = 0;
 
     /**
-     * The build parameter, informational. A reader must never assume it: per-page sizes come from
-     * child tables, frames, or the directory.
+     * Bytes a decoded page may come to. A **hard bound** when
+     * {@link VGEO_FEATURE_IGNORABLE_BOUNDED_PAGES} is set in {@link feature_flags_ignorable}: no
+     * page of the container exceeds it, which is what a fixed-stride page slot is sized against.
+     * Without that bit it is the advisory build parameter it used to be, and a reader must take
+     * per-page sizes from child tables, frames, or the directory as it always has.
      * @type {number}
      */
     nominal_page_size = 0;