@woosh/meep-engine 3.26.0 → 3.27.0

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

@@ -17,6 +17,8 @@ import { VGEO_NODE_RECORD_SIZE } from "../page/VGEO_NODE_RECORD_SIZE.js";
 import { VGEO_PAGE_HEADER_SIZE } from "../page/VGEO_PAGE_HEADER_SIZE.js";
 import { VGEO_PAGE_MAGIC } from "../frame/VGEO_PAGE_MAGIC.js";
 import { VGEO_PAGE_OFFSET } from "../page/VGEO_PAGE_OFFSET.js";
+import { VGEO_PARENT_ENTRY_SIZE } from "../page/VGEO_PARENT_ENTRY_SIZE.js";
+import { VGEO_PARENT_PAGE_ENTRY_SIZE } from "../page/VGEO_PARENT_PAGE_ENTRY_SIZE.js";
 import { vgeo_read_frame_extent } from "../frame/vgeo_read_frame_extent.js";
 import { VGeoPage } from "./VGeoPage.js";
 
@@ -127,6 +129,7 @@ export function vgeo_read_page(frame_bytes, page_index) {
     read_group_table(result);
     read_node_table(result);
     read_cluster_table(result);
+    read_parent_tables(result);
 
     return result;
 }
@@ -290,6 +293,7 @@ function read_group_table(page) {
     page.group_cluster_first = new Uint16Array(count);
     page.group_cluster_count = new Uint16Array(count);
     page.group_parent_count = new Uint16Array(count);
+    page.group_parent_first = new Uint32Array(count);
 
     for (let i = 0; i < count; i++) {
         const record = VGEO_PAGE_HEADER_SIZE + i * VGEO_GROUP_RECORD_SIZE;
@@ -297,6 +301,57 @@ function read_group_table(page) {
         page.group_cluster_first[i] = data.getUint16(record, LE);
         page.group_cluster_count[i] = data.getUint16(record + 2, LE);
         page.group_parent_count[i] = data.getUint16(record + 4, LE);
+        page.group_parent_first[i] = data.getUint16(record + 6, LE);
+    }
+}
+
+/**
+ * The parent-page table and the group-parent table, in that order, from `parent_table_offset`.
+ *
+ * **A zero offset is a container without an upward edge**, not a malformed one: those bytes were
+ * reserved before `format_version` 4 and written as zero, so every container built earlier says
+ * so about itself, and this leaves the arrays empty rather than reading the payload as a table.
+ * Nothing downstream has to ask what version it is holding.
+ *
+ * @param {VGeoPage} page
+ * @throws {Error} when the tables run past the decoded page
+ */
+function read_parent_tables(page) {
+    const data = page.data;
+
+    const table = data.getUint32(VGEO_PAGE_OFFSET.PARENT_TABLE_OFFSET, LE);
+
+    if (table === 0) {
+        return;
+    }
+
+    const page_count = data.getUint16(VGEO_PAGE_OFFSET.PARENT_PAGE_COUNT, LE);
+    const entry_count = data.getUint16(VGEO_PAGE_OFFSET.PARENT_ENTRY_COUNT, LE);
+
+    const entries = table + page_count * VGEO_PARENT_PAGE_ENTRY_SIZE;
+    const end = entries + entry_count * VGEO_PARENT_ENTRY_SIZE;
+
+    if (end > page.bytes.byteLength) {
+        throw new Error(
+            `virtual geometry: page ${page.index} parent tables end at ${end}, past the`
+            + ` ${page.bytes.byteLength} bytes it decoded to`
+        );
+    }
+
+    page.parent_page_index = new Uint32Array(page_count);
+
+    for (let i = 0; i < page_count; i++) {
+        page.parent_page_index[i] = data.getUint32(table + i * VGEO_PARENT_PAGE_ENTRY_SIZE, LE);
+    }
+
+    page.parent_ref = new Uint16Array(entry_count);
+    page.parent_cluster = new Uint16Array(entry_count);
+
+    for (let i = 0; i < entry_count; i++) {
+        const record = entries + i * VGEO_PARENT_ENTRY_SIZE;
+
+        page.parent_ref[i] = data.getUint16(record, LE);
+        page.parent_cluster[i] = data.getUint16(record + 2, LE);
     }
 }
 

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

@@ -1 +1 @@
-{"version":3,"file":"vgeo_validate_container.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/geometry/virtual/format/vgeo_validate_container.js"],"names":[],"mappings":"AAshDA;;;;;GAKG;AACH,gDAHW,YAAY,GACV,UAAU,EAAE,CAkFxB;6BA5mD4B,4CAA4C;2BA+C9C,iBAAiB"}
+{"version":3,"file":"vgeo_validate_container.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/geometry/virtual/format/vgeo_validate_container.js"],"names":[],"mappings":"AAgtDA;;;;;GAKG;AACH,gDAHW,YAAY,GACV,UAAU,EAAE,CAqFxB;6BAzyD4B,4CAA4C;2BAkD9C,iBAAiB"}

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

@@ -30,7 +30,10 @@ import { VGEO_MAX_CHILD_REF } from "./cluster/VGEO_MAX_CHILD_REF.js";
 import { VGEO_MAX_CLUSTER_TRIANGLE_COUNT } from "./cluster/VGEO_MAX_CLUSTER_TRIANGLE_COUNT.js";
 import { VGEO_MAX_CLUSTER_VERTEX_COUNT } from "./cluster/VGEO_MAX_CLUSTER_VERTEX_COUNT.js";
 import { VGEO_MAX_GROUP_CLUSTER_COUNT } from "./page/VGEO_MAX_GROUP_CLUSTER_COUNT.js";
+import { VGEO_MAX_PARENT_REF } from "./page/VGEO_MAX_PARENT_REF.js";
 import { VGEO_MIN_READER_VERSION } from "./header/VGEO_MIN_READER_VERSION.js";
+import { VGEO_PARENT_ENTRY_SIZE } from "./page/VGEO_PARENT_ENTRY_SIZE.js";
+import { VGEO_PARENT_PAGE_ENTRY_SIZE } from "./page/VGEO_PARENT_PAGE_ENTRY_SIZE.js";
 import { VGEO_NO_CHILD } from "./cluster/VGEO_NO_CHILD.js";
 import { VGEO_NO_GROUP } from "./cluster/VGEO_NO_GROUP.js";
 import { VGEO_NODE_FANOUT } from "./page/VGEO_NODE_FANOUT.js";
@@ -114,12 +117,42 @@ class DecodedPage {
     payload_offset = 0;
     payload_size = 0;
 
+    /**
+     * Start of the parent section — the parent-page table, then the group-parent table. Zero on a
+     * page written before `format_version` 4, which carries neither.
+     * @type {number}
+     */
+    parent_table_offset = 0;
+
+    /**
+     * @type {number}
+     */
+    parent_entry_count = 0;
+
+    /**
+     * @type {number}
+     */
+    parent_page_count = 0;
+
     /**
      * `[page_index, ...]` in child-table order.
      * @type {number[]}
      */
     child_pages = [];
 
+    /**
+     * `[page_index, ...]` in parent-page-table order.
+     * @type {number[]}
+     */
+    parent_pages = [];
+
+    /**
+     * The group-parent table, flat: `[parent_ref, parent_cluster, ...]` in table order, which the
+     * groups' `parent_first` slices.
+     * @type {number[]}
+     */
+    parent_entries = [];
+
     /**
      * Position `buffer` at a page-relative offset.
      * @param {number} offset
@@ -617,13 +650,9 @@ function decode_page(buffer, frame, level_count, out) {
     page.payload_size = decoded.readUint32();
     page.node_table_offset = decoded.readUint32();
 
-    for (let offset = 24; offset < VGEO_PAGE_OFFSET.METRIC; offset++) {
-        if (decoded.raw_bytes[page.base + offset] !== 0) {
-            out.push(new VGeoDefect(VGEO_DEFECT.PAGE_LAYOUT, `page ${frame.page_index}: reserved byte at ${offset} in the page header is not zero`));
-
-            break;
-        }
-    }
+    page.parent_table_offset = decoded.readUint32();
+    page.parent_entry_count = decoded.readUint16();
+    page.parent_page_count = decoded.readUint16();
 
     page.seek(VGEO_PAGE_OFFSET.METRIC);
 
@@ -674,7 +703,22 @@ function decode_page(buffer, frame, level_count, out) {
         return undefined;
     }
 
-    const expected_payload_offset = page.cluster_table_offset + page.cluster_count * VGEO_CLUSTER_RECORD_SIZE;
+    const expected_parent_table_offset = page.cluster_table_offset
+        + page.cluster_count * VGEO_CLUSTER_RECORD_SIZE;
+
+    if (page.parent_table_offset !== expected_parent_table_offset) {
+        out.push(new VGeoDefect(VGEO_DEFECT.PAGE_LAYOUT, `page ${frame.page_index}: parent_table_offset is ${page.parent_table_offset}, expected ${expected_parent_table_offset}`));
+
+        return undefined;
+    }
+
+    if (page.parent_page_count > page.parent_entry_count) {
+        out.push(new VGeoDefect(VGEO_DEFECT.PAGE_LAYOUT, `page ${frame.page_index}: parent_page_count is ${page.parent_page_count}, above the ${page.parent_entry_count} entries that could name a page`));
+    }
+
+    const expected_payload_offset = page.parent_table_offset
+        + page.parent_page_count * VGEO_PARENT_PAGE_ENTRY_SIZE
+        + page.parent_entry_count * VGEO_PARENT_ENTRY_SIZE;
 
     if (page.payload_offset !== expected_payload_offset) {
         out.push(new VGeoDefect(VGEO_DEFECT.PAGE_LAYOUT, `page ${frame.page_index}: payload_offset is ${page.payload_offset}, expected ${expected_payload_offset}`));
@@ -1016,7 +1060,7 @@ function check_child_tables(buffer, frames, pages, out) {
 /**
  * @param {DecodedPage} page
  * @param {VGeoDefect[]} out
- * @returns {{cluster_first:number, cluster_count:number, parent_cluster_count:number}[]}
+ * @returns {{cluster_first:number, cluster_count:number, parent_cluster_count:number, parent_first:number}[]}
  */
 function read_groups(page, out) {
     const result = [];
@@ -1024,6 +1068,7 @@ function read_groups(page, out) {
     const buffer = page.buffer;
 
     let expected_first = 0;
+    let expected_parent_first = 0;
 
     for (let g = 0; g < page.group_count; g++) {
         page.seek(VGEO_PAGE_HEADER_SIZE + g * VGEO_GROUP_RECORD_SIZE);
@@ -1032,12 +1077,9 @@ function read_groups(page, out) {
             cluster_first: buffer.readUint16(),
             cluster_count: buffer.readUint16(),
             parent_cluster_count: buffer.readUint16(),
+            parent_first: buffer.readUint16(),
         };
 
-        if (buffer.readUint16() !== 0) {
-            out.push(new VGeoDefect(VGEO_DEFECT.GROUP, `page ${page.page_index} group ${g}: reserved is not zero`));
-        }
-
         if (group.cluster_count < 1 || group.cluster_count > VGEO_MAX_GROUP_CLUSTER_COUNT) {
             out.push(new VGeoDefect(VGEO_DEFECT.GROUP, `page ${page.page_index} group ${g}: cluster_count ${group.cluster_count} is outside [1, ${VGEO_MAX_GROUP_CLUSTER_COUNT}]`));
         }
@@ -1048,6 +1090,12 @@ function read_groups(page, out) {
 
         expected_first = group.cluster_first + group.cluster_count;
 
+        if (group.parent_first !== expected_parent_first) {
+            out.push(new VGeoDefect(VGEO_DEFECT.GROUP, `page ${page.page_index} group ${g}: parent_first ${group.parent_first}, expected ${expected_parent_first}; a page's groups must tile its group-parent table in order`));
+        }
+
+        expected_parent_first = group.parent_first + group.parent_cluster_count;
+
         result.push(group);
     }
 
@@ -1055,9 +1103,147 @@ function read_groups(page, out) {
         out.push(new VGeoDefect(VGEO_DEFECT.GROUP, `page ${page.page_index}: groups cover ${expected_first} clusters, the page holds ${page.cluster_count}`));
     }
 
+    if (expected_parent_first !== page.parent_entry_count) {
+        out.push(new VGeoDefect(VGEO_DEFECT.GROUP, `page ${page.page_index}: groups cover ${expected_parent_first} parent entries, the page's table holds ${page.parent_entry_count}`));
+    }
+
     return result;
 }
 
+/**
+ * Read the two parent tables onto the page, and check the shape of what they hold before anything
+ * tries to resolve it.
+ *
+ * @param {DecodedPage} page
+ * @param {VGeoDefect[]} out
+ */
+function read_parent_tables(page, out) {
+    const buffer = page.buffer;
+
+    page.seek(page.parent_table_offset);
+
+    for (let i = 0; i < page.parent_page_count; i++) {
+        page.parent_pages.push(buffer.readUint32());
+    }
+
+    // Ascending and distinct, so that a parent page resolves to one reference and the refine-side
+    // election in a runtime reading this table is deterministic.
+    for (let i = 1; i < page.parent_pages.length; i++) {
+        if (page.parent_pages[i] <= page.parent_pages[i - 1]) {
+            out.push(new VGeoDefect(VGEO_DEFECT.PAGE_LAYOUT, `page ${page.page_index} parent page entry ${i}: page index ${page.parent_pages[i]} does not follow ${page.parent_pages[i - 1]}; the table is ascending and deduplicated`));
+
+            break;
+        }
+    }
+
+    for (const parent_page of page.parent_pages) {
+        if (parent_page === page.page_index) {
+            out.push(new VGeoDefect(VGEO_DEFECT.PAGE_LAYOUT, `page ${page.page_index}: its own index is in its parent-page table, where SAME_PAGE belongs`));
+
+            break;
+        }
+    }
+
+    page.seek(page.parent_table_offset + page.parent_page_count * VGEO_PARENT_PAGE_ENTRY_SIZE);
+
+    for (let i = 0; i < page.parent_entry_count; i++) {
+        const parent_ref = buffer.readUint16();
+        const parent_cluster = buffer.readUint16();
+
+        if (parent_ref !== VGEO_SAME_PAGE
+            && (parent_ref > VGEO_MAX_PARENT_REF || parent_ref >= page.parent_page_count)) {
+            out.push(new VGeoDefect(VGEO_DEFECT.GROUP, `page ${page.page_index} parent entry ${i}: parent_ref ${parent_ref} is outside the ${page.parent_page_count}-entry parent-page table`));
+        }
+
+        page.parent_entries.push(parent_ref, parent_cluster);
+    }
+}
+
+/**
+ * The upward edge, checked against the downward one it mirrors — format §11.16.
+ *
+ * Every parent reference must resolve to a cluster that really does name this group as its child,
+ * and each group's list must be sorted and free of repeats. The first is what makes a coarsen legal
+ * at all; the second is what lets a runtime elect one appender out of a group's parents by taking
+ * the first entry of the list, rather than carrying a bitmask sized by instances times groups.
+ *
+ * It is checked by rebuilding the lists from the cluster records and comparing, rather than by
+ * resolving each reference on its own: the downward edge is already validated by {@link check_dag},
+ * so rebuilding from it catches a *missing* parent as well as a wrong one.
+ *
+ * @param {DecodedPage[]} pages
+ * @param {object[][]} page_groups
+ * @param {object[][]} page_clusters
+ * @param {VGeoDefect[]} out
+ */
+function check_parent_tables(pages, page_groups, page_clusters, out) {
+    /**
+     * `page:group` to the parents the cluster records say it has, in the order §11.16 requires.
+     * @type {Map<string, {page: number, cluster: number}[]>}
+     */
+    const expected = new Map();
+
+    for (const page of pages) {
+        for (const cluster of page_clusters[page.page_index]) {
+            if (cluster.child_ref === VGEO_NO_CHILD) {
+                continue;
+            }
+
+            const child_page = cluster.child_ref === VGEO_SAME_PAGE
+                ? page.page_index
+                : page.child_pages[cluster.child_ref];
+
+            if (child_page === undefined) {
+                // a broken child reference, which check_dag reports; nothing to mirror
+                continue;
+            }
+
+            const id = `${child_page}:${cluster.child_group}`;
+
+            let list = expected.get(id);
+
+            if (list === undefined) {
+                expected.set(id, list = []);
+            }
+
+            list.push({ page: page.page_index, cluster: cluster.index });
+        }
+    }
+
+    for (const list of expected.values()) {
+        list.sort((a, b) => a.page - b.page || a.cluster - b.cluster);
+    }
+
+    for (const page of pages) {
+        page_groups[page.page_index].forEach((group, group_index) => {
+            const want = expected.get(`${page.page_index}:${group_index}`) ?? [];
+
+            if (group.parent_first + group.parent_cluster_count > page.parent_entry_count) {
+                out.push(new VGeoDefect(VGEO_DEFECT.GROUP, `page ${page.page_index} group ${group_index}: parents ${group.parent_first}..${group.parent_first + group.parent_cluster_count} run past the ${page.parent_entry_count}-entry table`));
+
+                return;
+            }
+
+            for (let i = 0; i < group.parent_cluster_count && i < want.length; i++) {
+                const base = (group.parent_first + i) * 2;
+
+                const parent_ref = page.parent_entries[base];
+                const parent_cluster = page.parent_entries[base + 1];
+
+                const named_page = parent_ref === VGEO_SAME_PAGE
+                    ? page.page_index
+                    : page.parent_pages[parent_ref];
+
+                if (named_page !== want[i].page || parent_cluster !== want[i].cluster) {
+                    out.push(new VGeoDefect(VGEO_DEFECT.GROUP, `page ${page.page_index} group ${group_index} parent ${i}: names page ${named_page} cluster ${parent_cluster}, but the ${i}th cluster refining into this group is page ${want[i].page} cluster ${want[i].cluster}`));
+
+                    break;
+                }
+            }
+        });
+    }
+}
+
 /**
  * Decode a cluster's local positions from its payload — the only way to check that the culling
  * bounds actually bound anything.
@@ -1617,6 +1803,8 @@ export function vgeo_validate_container(buffer) {
         const groups = read_groups(page, out);
         const clusters = read_clusters(page, out);
 
+        read_parent_tables(page, out);
+
         page_groups.push(groups);
         page_clusters.push(clusters);
 
@@ -1637,6 +1825,7 @@ export function vgeo_validate_container(buffer) {
     }
 
     check_page_nodes(pages, page_groups, page_clusters, out);
+    check_parent_tables(pages, page_groups, page_clusters, out);
 
     check_dag(pages, page_groups, page_clusters, level_count, out);
     check_directory(buffer, frames, pages, out);

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

@@ -1 +1 @@
-{"version":3,"file":"vgeo_write_container.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/geometry/virtual/format/vgeo_write_container.js"],"names":[],"mappings":"AAmTA;;;;;;;;GAQG;AACH,4CANW,qBAAqB,8BAGnB,YAAY,CAmNxB;6BA3gB4B,4CAA4C"}
+{"version":3,"file":"vgeo_write_container.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/geometry/virtual/format/vgeo_write_container.js"],"names":[],"mappings":"AA4bA;;;;;;;;GAQG;AACH,4CANW,qBAAqB,8BAGnB,YAAY,CAmNxB;6BAppB4B,4CAA4C"}

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

@@ -24,6 +24,8 @@ import { VGEO_HEADER_SIZE } from "./header/VGEO_HEADER_SIZE.js";
 import { VGEO_LEVEL_RECORD_SIZE } from "./header/VGEO_LEVEL_RECORD_SIZE.js";
 import { VGEO_MAGIC } from "./header/VGEO_MAGIC.js";
 import { VGEO_MAX_CHILD_REF } from "./cluster/VGEO_MAX_CHILD_REF.js";
+import { VGEO_MAX_PARENT_ENTRY_COUNT } from "./page/VGEO_MAX_PARENT_ENTRY_COUNT.js";
+import { VGEO_MAX_PARENT_REF } from "./page/VGEO_MAX_PARENT_REF.js";
 import { VGEO_MIN_READER_VERSION } from "./header/VGEO_MIN_READER_VERSION.js";
 import { VGEO_NO_CHILD } from "./cluster/VGEO_NO_CHILD.js";
 import { VGEO_NO_GROUP } from "./cluster/VGEO_NO_GROUP.js";
@@ -32,7 +34,10 @@ import { VGEO_NODE_RECORD_SIZE } from "./page/VGEO_NODE_RECORD_SIZE.js";
 import { VGEO_PAGE_HEADER_SIZE } from "./page/VGEO_PAGE_HEADER_SIZE.js";
 import { VGEO_PAGE_MAGIC } from "./frame/VGEO_PAGE_MAGIC.js";
 import { VGEO_PAGE_OFFSET } from "./page/VGEO_PAGE_OFFSET.js";
+import { VGEO_PARENT_ENTRY_SIZE } from "./page/VGEO_PARENT_ENTRY_SIZE.js";
+import { VGEO_PARENT_PAGE_ENTRY_SIZE } from "./page/VGEO_PARENT_PAGE_ENTRY_SIZE.js";
 import { VGEO_PAYLOAD_ENCODING_SHADE_MESHLET_V1 } from "./header/VGEO_PAYLOAD_ENCODING_SHADE_MESHLET_V1.js";
+import { VGEO_SAME_PAGE } from "./cluster/VGEO_SAME_PAGE.js";
 import { vgeo_scan_frames } from "./frame/vgeo_scan_frames.js";
 
 /**
@@ -98,28 +103,84 @@ class PageBlob {
 }
 
 /**
- * Count how many clusters name each group, and index the groups within their pages. Both are
- * derived, so recomputing them here keeps a caller from having to maintain them.
+ * Count how many clusters name each group, index the groups and clusters within their pages, and
+ * build the upward edge. All of it is derived, so recomputing it here keeps a caller from having to
+ * maintain any of it.
+ *
+ * The upward edge is the one piece that cannot be resolved while a single page is written: a
+ * group's parents live in whichever pages happen to refine into it, so the map is built across the
+ * whole page set once and then read per page.
  *
  * @param {VirtualGeometryPage[]} pages
+ * @returns {Map<VirtualGeometryGroup, {page: number, cluster: number}[]>} each group's parents,
+ *     sorted by (page index, cluster index) — the order format §11.16 requires, and the order the
+ *     runtime's refine-side election depends on being deterministic
  */
 function resolve_group_references(pages) {
     for (const page of pages) {
+        let cluster_index = 0;
+
         page.groups.forEach((group, index) => {
             group.index_in_page = index;
             group.parent_cluster_count = 0;
+
+            for (const cluster of group.clusters) {
+                cluster.index_in_page = cluster_index;
+                cluster_index++;
+            }
         });
     }
 
+    /** @type {Map<VirtualGeometryGroup, {page: number, cluster: number}[]>} */
+    const parents = new Map();
+
     for (const page of pages) {
         for (const group of page.groups) {
             for (const cluster of group.clusters) {
-                if (cluster.child_group !== undefined) {
-                    cluster.child_group.parent_cluster_count++;
+                const child = cluster.child_group;
+
+                if (child === undefined) {
+                    continue;
                 }
+
+                child.parent_cluster_count++;
+
+                let list = parents.get(child);
+
+                if (list === undefined) {
+                    parents.set(child, list = []);
+                }
+
+                list.push({ page: page.index, cluster: cluster.index_in_page });
+            }
+        }
+    }
+
+    for (const list of parents.values()) {
+        list.sort((a, b) => a.page - b.page || a.cluster - b.cluster);
+    }
+
+    return parents;
+}
+
+/**
+ * @param {VirtualGeometryPage} page
+ * @param {Map<VirtualGeometryGroup, {page: number, cluster: number}[]>} parents
+ * @returns {number[]} distinct indices of *other* pages holding a parent of one of this page's
+ *     groups, ascending; a parent in this page is named by `VGEO_SAME_PAGE` and is not here
+ */
+function collect_parent_pages(page, parents) {
+    const seen = new Set();
+
+    for (const group of page.groups) {
+        for (const parent of parents.get(group) ?? []) {
+            if (parent.page !== page.index) {
+                seen.add(parent.page);
             }
         }
     }
+
+    return Array.from(seen).sort((a, b) => a - b);
 }
 
 /**
@@ -149,9 +210,10 @@ function collect_child_pages(page) {
 /**
  * @param {VirtualGeometryPage} page
  * @param {number[]} child_pages
+ * @param {Map<VirtualGeometryGroup, {page: number, cluster: number}[]>} parents
  * @returns {Uint8Array} the decoded page
  */
-function build_page_blob(page, child_pages) {
+function build_page_blob(page, child_pages, parents) {
     const clusters = [];
 
     for (const group of page.groups) {
@@ -160,9 +222,41 @@ function build_page_blob(page, child_pages) {
         }
     }
 
+    const parent_pages = collect_parent_pages(page, parents);
+
+    let parent_entry_count = 0;
+
+    for (const group of page.groups) {
+        parent_entry_count += (parents.get(group) ?? []).length;
+    }
+
+    assert.lessThanOrEqual(
+        parent_entry_count, VGEO_MAX_PARENT_ENTRY_COUNT,
+        'page group-parent table must stay within what parent_first can index (format §11.15)'
+    );
+
+    assert.lessThanOrEqual(
+        parent_pages.length, VGEO_MAX_PARENT_REF + 1,
+        'page parent-page table must stay within what parent_ref can index'
+    );
+
     const node_table_offset = VGEO_PAGE_HEADER_SIZE + page.groups.length * VGEO_GROUP_RECORD_SIZE;
     const cluster_table_offset = node_table_offset + page.nodes.length * VGEO_NODE_RECORD_SIZE;
-    const payload_offset = cluster_table_offset + clusters.length * VGEO_CLUSTER_RECORD_SIZE;
+
+    /*
+     The parent section sits between the cluster records and the payload rather than beside the
+     group table, which keeps `node_table_offset`'s "= 56 + 8·group_count" true and leaves every
+     offset a reader before format 4 computed exactly where it was. Both tables hold 4-byte entries
+     and the sections above them are all multiples of four, so the payload stays word-aligned —
+     format §11.8's promise, which the meshlet batch divides by four without rounding.
+    */
+    const parent_table_offset = cluster_table_offset + clusters.length * VGEO_CLUSTER_RECORD_SIZE;
+
+    const group_parent_table_offset = parent_table_offset
+        + parent_pages.length * VGEO_PARENT_PAGE_ENTRY_SIZE;
+
+    const payload_offset = group_parent_table_offset
+        + parent_entry_count * VGEO_PARENT_ENTRY_SIZE;
 
     let payload_size = 0;
 
@@ -185,6 +279,9 @@ function build_page_blob(page, child_pages) {
     buffer.writeUint32(payload_offset);
     buffer.writeUint32(payload_size);
     buffer.writeUint32(node_table_offset);
+    buffer.writeUint32(parent_table_offset);
+    buffer.writeUint16(parent_entry_count);
+    buffer.writeUint16(parent_pages.length);
 
     // The page's own metric, so an installed page can be re-tested from itself rather than from
     // whichever of its parents happened to reference it.
@@ -216,16 +313,56 @@ function build_page_blob(page, child_pages) {
         child_ref_of_page.set(page_index, index);
     });
 
+    /**
+     * `page_index -> parent-page-table index`. The same shape as above and resolved the same way;
+     * a parent inside this page is `VGEO_SAME_PAGE` and is not in the table at all.
+     * @type {Map<number, number>}
+     */
+    const parent_ref_of_page = new Map();
+
+    parent_pages.forEach((page_index, index) => {
+        assert.lessThanOrEqual(index, VGEO_MAX_PARENT_REF, 'parent table index must stay below the sentinel range');
+
+        parent_ref_of_page.set(page_index, index);
+    });
+
+    parent_pages.forEach((page_index, index) => {
+        buffer.position = parent_table_offset + index * VGEO_PARENT_PAGE_ENTRY_SIZE;
+
+        buffer.writeUint32(page_index);
+    });
+
     let cluster_index = 0;
     let cursor = 0;
 
+    let parent_first = 0;
+
     page.groups.forEach((group, group_index) => {
+        const group_parents = parents.get(group) ?? [];
+
+        assert.equal(
+            group_parents.length, group.parent_cluster_count,
+            'a group\'s parent list and its parent_cluster_count are the same fact twice'
+        );
+
+        group_parents.forEach((parent, index) => {
+            buffer.position = group_parent_table_offset
+                + (parent_first + index) * VGEO_PARENT_ENTRY_SIZE;
+
+            buffer.writeUint16(
+                parent.page === page.index ? VGEO_SAME_PAGE : parent_ref_of_page.get(parent.page)
+            );
+            buffer.writeUint16(parent.cluster);
+        });
+
         buffer.position = VGEO_PAGE_HEADER_SIZE + group_index * VGEO_GROUP_RECORD_SIZE;
 
         buffer.writeUint16(cluster_index);
         buffer.writeUint16(group.clusters.length);
         buffer.writeUint16(group.parent_cluster_count);
-        buffer.writeUint16(0);
+        buffer.writeUint16(parent_first);
+
+        parent_first += group_parents.length;
 
         for (const cluster of group.clusters) {
             const offset = cluster_table_offset + cluster_index * VGEO_CLUSTER_RECORD_SIZE;
@@ -322,19 +459,19 @@ export function vgeo_write_container(pages, options) {
         assert.equal(page.index, index, `page ${index} carries index ${page.index}`);
     });
 
-    resolve_group_references(pages);
+    const parents = resolve_group_references(pages);
 
     const blobs = pages.map((page) => {
         const blob = new PageBlob();
 
         blob.child_pages = collect_child_pages(page);
 
-        const decoded = build_page_blob(page, blob.child_pages);
+        const decoded = build_page_blob(page, blob.child_pages, parents);
 
         // Compression happens here, before a single offset is known, and that is what keeps the
         // layout non-circular: a frame's extent follows from its *stored* size and its child count,
         // and neither depends on any offset value, because the child table is plaintext.
-        const encoded = vgeo_encode_frame_blob(decoded, options.codec);
+        const encoded = vgeo_encode_frame_blob(decoded, options.codec, options.codec_level);
 
         blob.codec = encoded.codec;
         blob.stored = encoded.bytes;