@woosh/meep-engine 3.26.0 → 3.28.0

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

@@ -1,3 +1,6 @@
+/**
+ * @typedef {import("./header/VGeoLevelRecord.js").VGeoLevelRecord} VGeoLevelRecord
+ */
 /**
  * Everything the `.vgeo` header carries that the page list does not.
  *
@@ -17,6 +20,24 @@ export class VGeoWriteOptions {
      * @type {number}
      */
     codec: number;
+    /**
+     * How hard the codec looks for matches, from {@link LZ4_LEVEL}. Nine by default, which is the
+     * top of the reference's hash-chain levels.
+     *
+     * **It changes nothing about the file.** Every level writes the same LZ4 block format, so a
+     * container built at any of them reads in every build of the reader that exists; the level is
+     * how long the *encoder* spent, and that is all.
+     *
+     * Nine rather than twelve because the ladder above it is not worth its time on this payload:
+     * measured over 2,718 real pages, the whole run from 3 to 12 is 0.077 percentage points of
+     * ratio, and 10 to 12 cost 15-40% more time for the last thousandth of it. Nine rather than
+     * three for the same reason in the other direction — it is 0.077 points smaller for about 5%
+     * more time. Nine rather than one because the fast encoder gives up 2.5% of every page to save
+     * compression time that is a couple of percent of a build.
+     *
+     * @type {number}
+     */
+    codec_level: number;
     /**
      * One per level, coarsest last. `level_count` is its length.
      * @type {VGeoLevelRecord[]}
@@ -60,4 +81,5 @@ export class VGeoWriteOptions {
      */
     nominal_page_size: number;
 }
+export type VGeoLevelRecord = import("./header/VGeoLevelRecord.js").VGeoLevelRecord;
 //# sourceMappingURL=VGeoWriteOptions.d.ts.map

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;;;;;;;;;;OAUG;IACH,mBAFU,MAAM,CAEM;CACzB"}
+{"version":3,"file":"VGeoWriteOptions.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/geometry/virtual/format/VGeoWriteOptions.js"],"names":[],"mappings":"AAGA;;GAEG;AAEH;;;;;GAKG;AACH;IACI;;;;;;;;;;OAUG;IACH,OAFU,MAAM,CAEO;IAEvB;;;;;;;;;;;;;;;;OAgBG;IACH,aAFU,MAAM,CAEmB;IAEnC;;;OAGG;IACH,QAFU,eAAe,EAAE,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;8BA1FY,OAAO,6BAA6B,EAAE,eAAe"}

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

@@ -1,5 +1,10 @@
+import { LZ4_LEVEL } from "../../../../../core/binary/lz4/LZ4_LEVEL.js";
 import { VGEO_CODEC_LZ4 } from "./frame/VGEO_CODEC_LZ4.js";
 
+/**
+ * @typedef {import("./header/VGeoLevelRecord.js").VGeoLevelRecord} VGeoLevelRecord
+ */
+
 /**
  * Everything the `.vgeo` header carries that the page list does not.
  *
@@ -20,6 +25,25 @@ export class VGeoWriteOptions {
      */
     codec = VGEO_CODEC_LZ4;
 
+    /**
+     * How hard the codec looks for matches, from {@link LZ4_LEVEL}. Nine by default, which is the
+     * top of the reference's hash-chain levels.
+     *
+     * **It changes nothing about the file.** Every level writes the same LZ4 block format, so a
+     * container built at any of them reads in every build of the reader that exists; the level is
+     * how long the *encoder* spent, and that is all.
+     *
+     * Nine rather than twelve because the ladder above it is not worth its time on this payload:
+     * measured over 2,718 real pages, the whole run from 3 to 12 is 0.077 percentage points of
+     * ratio, and 10 to 12 cost 15-40% more time for the last thousandth of it. Nine rather than
+     * three for the same reason in the other direction — it is 0.077 points smaller for about 5%
+     * more time. Nine rather than one because the fast encoder gives up 2.5% of every page to save
+     * compression time that is a couple of percent of a build.
+     *
+     * @type {number}
+     */
+    codec_level = LZ4_LEVEL.HC_DEFAULT;
+
     /**
      * One per level, coarsest last. `level_count` is its length.
      * @type {VGeoLevelRecord[]}

package/src/shade/renderer/geometry/virtual/format/attribute/vgeo_attributes_read.d.ts

@@ -1,7 +1,13 @@
 /**
  * Read one vertex's value for one channel, falling back to the format's default for a channel this
- * geometry does not carry — which is exactly what the container does with it, since the payload
- * never omits a section and constant-compresses the missing ones to the same values.
+ * geometry does not carry.
+ *
+ * These are the **unencoded** defaults, for a caller that is going to encode what it reads.
+ * `vgeo_encode_cluster_payload` never reaches them: a channel the geometry lacks takes its
+ * `ENCODED_DEFAULTS` path instead, which emits Shade's encoded constant directly. The two are not
+ * everywhere the same value — colour's encoded default carries an alpha byte that
+ * `encode_colors_to_u32` does not write — so which of the two a caller wants is a real question,
+ * and the answer is: this one only when the value is about to be encoded from scratch.
  *
  * @param {Float32Array|number[]} target
  * @param {number} target_offset

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

@@ -1 +1 @@
-{"version":3,"file":"vgeo_attributes_read.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/geometry/virtual/format/attribute/vgeo_attributes_read.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;GAaG;AACH,6CATW,YAAY,GAAC,MAAM,EAAE,iBACrB,MAAM,UACN,CAAC,kBAAgB,IAAI,CAAC,EAAE,aACxB,MAAM,UACN,MAAM,QAmBhB"}
+{"version":3,"file":"vgeo_attributes_read.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/geometry/virtual/format/attribute/vgeo_attributes_read.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,6CATW,YAAY,GAAC,MAAM,EAAE,iBACrB,MAAM,UACN,CAAC,kBAAgB,IAAI,CAAC,EAAE,aACxB,MAAM,UACN,MAAM,QAmBhB"}

package/src/shade/renderer/geometry/virtual/format/attribute/vgeo_attributes_read.js

@@ -2,8 +2,14 @@ import { VGEO_ATTRIBUTES } from "./VGEO_ATTRIBUTES.js";
 
 /**
  * Read one vertex's value for one channel, falling back to the format's default for a channel this
- * geometry does not carry — which is exactly what the container does with it, since the payload
- * never omits a section and constant-compresses the missing ones to the same values.
+ * geometry does not carry.
+ *
+ * These are the **unencoded** defaults, for a caller that is going to encode what it reads.
+ * `vgeo_encode_cluster_payload` never reaches them: a channel the geometry lacks takes its
+ * `ENCODED_DEFAULTS` path instead, which emits Shade's encoded constant directly. The two are not
+ * everywhere the same value — colour's encoded default carries an alpha byte that
+ * `encode_colors_to_u32` does not write — so which of the two a caller wants is a real question,
+ * and the answer is: this one only when the value is about to be encoded from scratch.
  *
  * @param {Float32Array|number[]} target
  * @param {number} target_offset

package/src/shade/renderer/geometry/virtual/format/dag/VirtualGeometryCluster.d.ts

@@ -49,6 +49,18 @@ export class VirtualGeometryCluster {
      * @type {VirtualGeometryGroup|undefined}
      */
     child_group: VirtualGeometryGroup | undefined;
+    /**
+     * Index of this cluster within its page's cluster table, assigned at write time.
+     *
+     * A cluster is named from two directions and the second one is why this exists: its own page
+     * addresses it by position, and every group it refines into names it back through the
+     * group-parent table (format §6.3). The count that table is sized by is a property of the
+     * *other* page, so the number has to be resolved once across the whole page set rather than
+     * rediscovered while a page is being written.
+     *
+     * @type {number}
+     */
+    index_in_page: number;
     /**
      * @type {number}
      */

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

@@ -1 +1 @@
-{"version":3,"file":"VirtualGeometryCluster.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/geometry/virtual/format/dag/VirtualGeometryCluster.js"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH;IACI;;;OAGG;IACH,OAFU,MAAM,CAEN;IAEV;;;;OAIG;IACH,aAFU,YAAY,CAEY;IAElC;;;OAGG;IACH,YAFU,MAAM,CAED;IAEf;;;;OAIG;IACH,eAFU,YAAY,CAEc;IAEpC;;;OAGG;IACH,cAFU,MAAM,CAEwB;IAExC;;;OAGG;IACH,eAFU,YAAY,CAEc;IAEpC;;;OAGG;IACH,MAFU,YAAY,CAEK;IAE3B;;;;OAIG;IACH,aAFU,uBAAqB,SAAS,CAEhB;IAExB;;OAEG;IACH,cAFU,MAAM,CAEC;IAEjB;;OAEG;IACH,gBAFU,MAAM,CAEG;IAEnB;;;OAGG;IACH,gBAFU,MAAM,CAEG;IAEnB;;;OAGG;IACH,SAFU,UAAU,CAEQ;CAC/B"}
+{"version":3,"file":"VirtualGeometryCluster.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/geometry/virtual/format/dag/VirtualGeometryCluster.js"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH;IACI;;;OAGG;IACH,OAFU,MAAM,CAEN;IAEV;;;;OAIG;IACH,aAFU,YAAY,CAEY;IAElC;;;OAGG;IACH,YAFU,MAAM,CAED;IAEf;;;;OAIG;IACH,eAFU,YAAY,CAEc;IAEpC;;;OAGG;IACH,cAFU,MAAM,CAEwB;IAExC;;;OAGG;IACH,eAFU,YAAY,CAEc;IAEpC;;;OAGG;IACH,MAFU,YAAY,CAEK;IAE3B;;;;OAIG;IACH,aAFU,uBAAqB,SAAS,CAEhB;IAExB;;;;;;;;;;OAUG;IACH,eAFU,MAAM,CAEE;IAElB;;OAEG;IACH,cAFU,MAAM,CAEC;IAEjB;;OAEG;IACH,gBAFU,MAAM,CAEG;IAEnB;;;OAGG;IACH,gBAFU,MAAM,CAEG;IAEnB;;;OAGG;IACH,SAFU,UAAU,CAEQ;CAC/B"}

package/src/shade/renderer/geometry/virtual/format/dag/VirtualGeometryCluster.js

@@ -57,6 +57,19 @@ export class VirtualGeometryCluster {
      */
     child_group = undefined;
 
+    /**
+     * Index of this cluster within its page's cluster table, assigned at write time.
+     *
+     * A cluster is named from two directions and the second one is why this exists: its own page
+     * addresses it by position, and every group it refines into names it back through the
+     * group-parent table (format §6.3). The count that table is sized by is a property of the
+     * *other* page, so the number has to be resolved once across the whole page set rather than
+     * rediscovered while a page is being written.
+     *
+     * @type {number}
+     */
+    index_in_page = 0;
+
     /**
      * @type {number}
      */

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

@@ -12,13 +12,20 @@
  * header's `decoded_size` is what {@link vgeo_decode_frame_blob} decodes against, and the frame's
  * checksum is what proves the stored bytes arrived intact.
  *
+ * The level is how hard the encoder looks for matches, and nothing else: every level writes the
+ * same LZ4 block format, so it is a build-time decision with no reader consequence at all. What it
+ * buys on a page of encoded geometry is about 2.5% over the fast encoder, almost all of which is
+ * already there at level 3; what it costs is roughly an order of magnitude of encoder throughput,
+ * which over a whole conversion comes to a couple of percent of the build.
+ *
  * @param {Uint8Array} bytes the decoded page
  * @param {number} codec the codec to attempt, one of {@link VGEO_CODEC_RAW} or {@link VGEO_CODEC_LZ4}
+ * @param {number} [level] how hard to look, one of {@link LZ4_LEVEL}'s; the raw codec ignores it
  * @returns {VGeoFrameBlob}
  *
  * @author Alex Goldring
  * @copyright Company Named Limited (c) 2026
  */
-export function vgeo_encode_frame_blob(bytes: Uint8Array, codec: number): VGeoFrameBlob;
+export function vgeo_encode_frame_blob(bytes: Uint8Array, codec: number, level?: number): VGeoFrameBlob;
 import { VGeoFrameBlob } from "./VGeoFrameBlob.js";
 //# sourceMappingURL=vgeo_encode_frame_blob.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"vgeo_encode_frame_blob.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/geometry/virtual/format/frame/vgeo_encode_frame_blob.js"],"names":[],"mappings":"AAOA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,8CAPW,UAAU,SACV,MAAM,GACJ,aAAa,CAgCzB;8BAlD6B,oBAAoB"}
+{"version":3,"file":"vgeo_encode_frame_blob.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/geometry/virtual/format/frame/vgeo_encode_frame_blob.js"],"names":[],"mappings":"AAQA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,8CARW,UAAU,SACV,MAAM,UACN,MAAM,GACJ,aAAa,CAgCzB;8BAzD6B,oBAAoB"}

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

@@ -1,5 +1,6 @@
 import { assert } from "../../../../../../core/assert.js";
-import { lz4_compress_block } from "../../../../../../core/binary/lz4/lz4_compress_block.js";
+import { LZ4_LEVEL } from "../../../../../../core/binary/lz4/LZ4_LEVEL.js";
+import { lz4_compress_block_at_level } from "../../../../../../core/binary/lz4/lz4_compress_block_at_level.js";
 import { lz4_compress_bound } from "../../../../../../core/binary/lz4/lz4_compress_bound.js";
 import { VGEO_CODEC_LZ4 } from "./VGEO_CODEC_LZ4.js";
 import { VGEO_CODEC_RAW } from "./VGEO_CODEC_RAW.js";
@@ -19,14 +20,21 @@ import { VGeoFrameBlob } from "./VGeoFrameBlob.js";
  * header's `decoded_size` is what {@link vgeo_decode_frame_blob} decodes against, and the frame's
  * checksum is what proves the stored bytes arrived intact.
  *
+ * The level is how hard the encoder looks for matches, and nothing else: every level writes the
+ * same LZ4 block format, so it is a build-time decision with no reader consequence at all. What it
+ * buys on a page of encoded geometry is about 2.5% over the fast encoder, almost all of which is
+ * already there at level 3; what it costs is roughly an order of magnitude of encoder throughput,
+ * which over a whole conversion comes to a couple of percent of the build.
+ *
  * @param {Uint8Array} bytes the decoded page
  * @param {number} codec the codec to attempt, one of {@link VGEO_CODEC_RAW} or {@link VGEO_CODEC_LZ4}
+ * @param {number} [level] how hard to look, one of {@link LZ4_LEVEL}'s; the raw codec ignores it
  * @returns {VGeoFrameBlob}
  *
  * @author Alex Goldring
  * @copyright Company Named Limited (c) 2026
  */
-export function vgeo_encode_frame_blob(bytes, codec) {
+export function vgeo_encode_frame_blob(bytes, codec, level = LZ4_LEVEL.HC_DEFAULT) {
     assert.defined(bytes, 'bytes');
 
     const result = new VGeoFrameBlob();
@@ -42,7 +50,7 @@ export function vgeo_encode_frame_blob(bytes, codec) {
 
     const scratch = new Uint8Array(lz4_compress_bound(bytes.length));
 
-    const end = lz4_compress_block(scratch, 0, scratch.length, bytes, 0, bytes.length);
+    const end = lz4_compress_block_at_level(scratch, 0, scratch.length, bytes, 0, bytes.length, level);
 
     if (end < bytes.length) {
         result.codec = VGEO_CODEC_LZ4;

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

@@ -1,6 +1,15 @@
 /**
  * Bumped only when the container layout itself changes. A new payload encoding is a per-asset
  * capability gate instead, so it does not move this.
+ *
+ * 4 added the parent tables (§6.3, §6.4) — the format's first upward edge. {@link
+ * VGEO_MIN_READER_VERSION} deliberately did **not** move with it: the tables occupy bytes that were
+ * reserved and written as zero, and they sit between the cluster records and the payload, so every
+ * offset a version-3 reader computes still lands where it did and such a reader reads a version-4
+ * file correctly by ignoring them. A version-4 reader meeting a version-3 file finds
+ * `parent_table_offset` zero and takes the same absence as "this container has no upward edge",
+ * which is true.
+ *
  * @type {number}
  */
 export const VGEO_FORMAT_VERSION: number;

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

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

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

@@ -1,6 +1,15 @@
 /**
  * Bumped only when the container layout itself changes. A new payload encoding is a per-asset
  * capability gate instead, so it does not move this.
+ *
+ * 4 added the parent tables (§6.3, §6.4) — the format's first upward edge. {@link
+ * VGEO_MIN_READER_VERSION} deliberately did **not** move with it: the tables occupy bytes that were
+ * reserved and written as zero, and they sit between the cluster records and the payload, so every
+ * offset a version-3 reader computes still lands where it did and such a reader reads a version-4
+ * file correctly by ignoring them. A version-4 reader meeting a version-3 file finds
+ * `parent_table_offset` zero and takes the same absence as "this container has no upward edge",
+ * which is true.
+ *
  * @type {number}
  */
-export const VGEO_FORMAT_VERSION = 3;
+export const VGEO_FORMAT_VERSION = 4;

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

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

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

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

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

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

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

@@ -0,0 +1,18 @@
+/**
+ * Most entries one page's group-parent table may hold, and therefore the largest `parent_first` the
+ * u16 in a group record can name.
+ *
+ * The cap exists because the arithmetic does not forbid overflow on its own: `parent_entry_count` is
+ * the sum of `parent_cluster_count` over a page's groups and `group_count` is itself a u16, so a
+ * dense enough page could in principle run past what `parent_first` can index. `child_ref` has no
+ * such problem — it indexes distinct child *pages*.
+ *
+ * It is a cap rather than a wider field because the measured distance is not close. Across 8,899
+ * pages of 30 converted Zorah containers the worst page carries **26** parent entries against a mean
+ * of 17.4, and the most parents any one group has is 5 — so this bound stands 2,521x above the worst
+ * real page, and paying a u32 for it would cost the group record its 8-byte size.
+ *
+ * @type {number}
+ */
+export const VGEO_MAX_PARENT_ENTRY_COUNT: number;
+//# sourceMappingURL=VGEO_MAX_PARENT_ENTRY_COUNT.d.ts.map

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

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

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

@@ -0,0 +1,17 @@
+/**
+ * Most entries one page's group-parent table may hold, and therefore the largest `parent_first` the
+ * u16 in a group record can name.
+ *
+ * The cap exists because the arithmetic does not forbid overflow on its own: `parent_entry_count` is
+ * the sum of `parent_cluster_count` over a page's groups and `group_count` is itself a u16, so a
+ * dense enough page could in principle run past what `parent_first` can index. `child_ref` has no
+ * such problem — it indexes distinct child *pages*.
+ *
+ * It is a cap rather than a wider field because the measured distance is not close. Across 8,899
+ * pages of 30 converted Zorah containers the worst page carries **26** parent entries against a mean
+ * of 17.4, and the most parents any one group has is 5 — so this bound stands 2,521x above the worst
+ * real page, and paying a u32 for it would cost the group record its 8-byte size.
+ *
+ * @type {number}
+ */
+export const VGEO_MAX_PARENT_ENTRY_COUNT = 0xFFFF;

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

@@ -0,0 +1,8 @@
+/**
+ * Largest legal parent-page-table index, one below {@link VGEO_SAME_PAGE}, which a parent reference
+ * spends the same sentinel on that a child reference does.
+ *
+ * @type {number}
+ */
+export const VGEO_MAX_PARENT_REF: number;
+//# sourceMappingURL=VGEO_MAX_PARENT_REF.d.ts.map

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

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

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

@@ -0,0 +1,7 @@
+/**
+ * Largest legal parent-page-table index, one below {@link VGEO_SAME_PAGE}, which a parent reference
+ * spends the same sentinel on that a child reference does.
+ *
+ * @type {number}
+ */
+export const VGEO_MAX_PARENT_REF = 0xFFFD;

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

@@ -12,6 +12,9 @@ export namespace VGEO_PAGE_OFFSET {
     let PAYLOAD_OFFSET: number;
     let PAYLOAD_SIZE: number;
     let NODE_TABLE_OFFSET: number;
+    let PARENT_TABLE_OFFSET: number;
+    let PARENT_ENTRY_COUNT: number;
+    let PARENT_PAGE_COUNT: number;
     let METRIC: number;
 }
 //# sourceMappingURL=VGEO_PAGE_OFFSET.d.ts.map

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

@@ -12,5 +12,21 @@ export const VGEO_PAGE_OFFSET = {
     PAYLOAD_OFFSET: 12,
     PAYLOAD_SIZE: 16,
     NODE_TABLE_OFFSET: 20,
+    /**
+     * Start of this page's parent section, which is the parent-page table immediately followed by
+     * the group-parent table. Zero means the page carries neither, which is what every container
+     * written before `format_version` 4 says: those bytes were reserved and written as zero, so the
+     * absence is self-describing and no version test is needed to read it.
+     */
+    PARENT_TABLE_OFFSET: 24,
+    /**
+     * Entries in the group-parent table — the sum of `parent_cluster_count` over this page's
+     * groups, and the bound every `parent_first` plus its count must stay within.
+     */
+    PARENT_ENTRY_COUNT: 28,
+    /**
+     * Entries in the parent-page table, which the group-parent table's `parent_ref` indexes.
+     */
+    PARENT_PAGE_COUNT: 30,
     METRIC: 32,
 };

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

@@ -0,0 +1,14 @@
+/**
+ * Bytes of one entry in a decoded page's group-parent table: `parent_ref u16`, then
+ * `parent_cluster u16`.
+ *
+ * Four rather than the child table's 48, because the two references are not symmetric. A child
+ * reference has to carry a fetch range and a metric, since the child may be absent and the decision
+ * to fetch it is made before it arrives. A parent of a group in the cut is resident already —
+ * `VGEO_GROUP_FLAG_SELECTABLE` is exactly "every parent reference is live" — so a parent reference
+ * has nothing to decide and needs only to say where.
+ *
+ * @type {number}
+ */
+export const VGEO_PARENT_ENTRY_SIZE: number;
+//# sourceMappingURL=VGEO_PARENT_ENTRY_SIZE.d.ts.map

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

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

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

@@ -0,0 +1,13 @@
+/**
+ * Bytes of one entry in a decoded page's group-parent table: `parent_ref u16`, then
+ * `parent_cluster u16`.
+ *
+ * Four rather than the child table's 48, because the two references are not symmetric. A child
+ * reference has to carry a fetch range and a metric, since the child may be absent and the decision
+ * to fetch it is made before it arrives. A parent of a group in the cut is resident already —
+ * `VGEO_GROUP_FLAG_SELECTABLE` is exactly "every parent reference is live" — so a parent reference
+ * has nothing to decide and needs only to say where.
+ *
+ * @type {number}
+ */
+export const VGEO_PARENT_ENTRY_SIZE = 4;

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

@@ -0,0 +1,11 @@
+/**
+ * Bytes of one entry in a decoded page's parent-page table: `page_index u32`, the global frame
+ * ordinal of a page holding a parent of one of this page's groups.
+ *
+ * Deduplicated, so the group-parent table's `parent_ref` is an index into this and a page named by
+ * several groups is stored once — the same shape the child table has, for the same reason.
+ *
+ * @type {number}
+ */
+export const VGEO_PARENT_PAGE_ENTRY_SIZE: number;
+//# sourceMappingURL=VGEO_PARENT_PAGE_ENTRY_SIZE.d.ts.map

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

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

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

@@ -0,0 +1,10 @@
+/**
+ * Bytes of one entry in a decoded page's parent-page table: `page_index u32`, the global frame
+ * ordinal of a page holding a parent of one of this page's groups.
+ *
+ * Deduplicated, so the group-parent table's `parent_ref` is an index into this and a page named by
+ * several groups is stored once — the same shape the child table has, for the same reason.
+ *
+ * @type {number}
+ */
+export const VGEO_PARENT_PAGE_ENTRY_SIZE = 4;

package/src/shade/renderer/geometry/virtual/format/payload/vgeo_encode_cluster_payload.d.ts

@@ -7,5 +7,33 @@
  * @returns {VGeoEncodedPayload}
  */
 export function vgeo_encode_cluster_payload(positions: Float32Array, indices: Uint8Array, vertex_ids: Uint32Array, layers: (BinaryDataLayer | null)[]): VGeoEncodedPayload;
+/**
+ * Encode one cluster's geometry into a `SHADE_MESHLET_V1` payload: the local index section, then
+ * every attribute section in the frozen order, each either one value per vertex or — when every
+ * vertex agrees, or the source simply lacks the attribute — a single constant-compressed value.
+ *
+ * The encoders themselves are Shade's, unmodified. That is the whole point of the encoding's
+ * "byte-compatible with the data pool" claim: uploading a payload is a copy, so it has to be the
+ * same bits Shade's own encoder would have produced.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+/**
+ * The encoded word a section carries when the source lacks the attribute — Shade's
+ * `ENCODED_ATTRIBUTE_DEFAULT_VALUES`, in this format's own attribute order, so that a `.vgeo`
+ * payload and a `MeshletBatch` payload of the same geometry differ nowhere.
+ *
+ * Colour's default is opaque white with its alpha byte set, while `encode_colors_to_u32` writes only
+ * three channels and leaves alpha zero. That asymmetry is Shade's, and matching it is the point.
+ *
+ * Exported so that `vgeo_encode_cluster_payload.spec.js` can hold it against Shade's own table
+ * rather than against nothing — it is the fourth of the four tables the byte-compatibility claim
+ * rests on, and was for a long time the only one no test compared.
+ *
+ * @readonly
+ * @type {number[][]}
+ */
+export const ENCODED_DEFAULTS: number[][];
 import { VGeoEncodedPayload } from "./VGeoEncodedPayload.js";
 //# sourceMappingURL=vgeo_encode_cluster_payload.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"vgeo_encode_cluster_payload.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/geometry/virtual/format/payload/vgeo_encode_cluster_payload.js"],"names":[],"mappings":"AAgHA;;;;;;;GAOG;AACH,uDAPW,YAAY,WACZ,UAAU,cACV,WAAW,UACX,CAAC,kBAAgB,IAAI,CAAC,EAAE,GAEtB,kBAAkB,CAiF9B;mCA1LkC,yBAAyB"}
+{"version":3,"file":"vgeo_encode_cluster_payload.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/geometry/virtual/format/payload/vgeo_encode_cluster_payload.js"],"names":[],"mappings":"AAoHA;;;;;;;GAOG;AACH,uDAPW,YAAY,WACZ,UAAU,cACV,WAAW,UACX,CAAC,kBAAgB,IAAI,CAAC,EAAE,GAEtB,kBAAkB,CAiF9B;AA5LD;;;;;;;;;;;GAWG;AAEH;;;;;;;;;;;;;;GAcG;AACH,+BAFU,MAAM,EAAE,EAAE,CAEe;mCA9BA,yBAAyB"}

package/src/shade/renderer/geometry/virtual/format/payload/vgeo_encode_cluster_payload.js

@@ -28,16 +28,20 @@ import { VGeoEncodedPayload } from "./VGeoEncodedPayload.js";
 
 /**
  * The encoded word a section carries when the source lacks the attribute — Shade's
- * `ENCODED_ATTRIBUTE_DEFAULT_VALUES`, reproduced so that a `.vgeo` payload and a `MeshletBatch`
- * payload of the same geometry differ nowhere.
+ * `ENCODED_ATTRIBUTE_DEFAULT_VALUES`, in this format's own attribute order, so that a `.vgeo`
+ * payload and a `MeshletBatch` payload of the same geometry differ nowhere.
  *
  * Colour's default is opaque white with its alpha byte set, while `encode_colors_to_u32` writes only
  * three channels and leaves alpha zero. That asymmetry is Shade's, and matching it is the point.
  *
+ * Exported so that `vgeo_encode_cluster_payload.spec.js` can hold it against Shade's own table
+ * rather than against nothing — it is the fourth of the four tables the byte-compatibility claim
+ * rests on, and was for a long time the only one no test compared.
+ *
  * @readonly
  * @type {number[][]}
  */
-const ENCODED_DEFAULTS = [];
+export const ENCODED_DEFAULTS = [];
 
 {
     const normal = new Uint32Array(1);

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

@@ -82,6 +82,26 @@ export class VGeoByteSource {
      * @type {number}
      */
     bytes_read: number;
+    /**
+     * What another thread needs to open this source again: a URL with its length, a Blob, or the
+     * bytes. Set by the three constructors below and by `vgeo_fetch_byte_source`; `undefined` for
+     * a source built by hand, which then stays on the thread that built it.
+     *
+     * @type {{kind: 'url', url: string, byte_length: number, init?: object}
+     *     | {kind: 'blob', blob: Blob} | {kind: 'memory', bytes: Uint8Array} | undefined}
+     */
+    descriptor: {
+        kind: 'url';
+        url: string;
+        byte_length: number;
+        init?: object;
+    } | {
+        kind: 'blob';
+        blob: Blob;
+    } | {
+        kind: 'memory';
+        bytes: Uint8Array;
+    } | undefined;
     /**
      * @returns {string}
      */

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

@@ -1 +1 @@
-{"version":3,"file":"VGeoByteSource.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/geometry/virtual/format/read/VGeoByteSource.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH;IA8GI;;;;;;;;;;OAUG;IACH,iBAJW,UAAU,GAAC,WAAW,SACtB,MAAM,GACJ,cAAc,CAU1B;IAED;;;;;;;;;;;;;;;OAeG;IACH,uBAJW,IAAI,SACJ,MAAM,GACJ,cAAc,CAU1B;IA5HD;;;;;;OAMG;IACH,yBANW,MAAM,eACG,MAAM,QAAE,MAAM,QAAE,WAAW,iBAAI,QAAQ,UAAU,CAAC,SAG3D,MAAM,EAUhB;IA7CD;;;OAGG;IACH,aAFU,MAAM,CAEA;IAEhB;;;OAGG;IACH,eAFU,MAAM,CAEE;IAElB;;;;OAIG;IACH,YAFU,MAAM,CAED;IA8Bf;;OAEG;IACH,mBAEC;IAED;;;;;OAKG;IACH,uBAGC;IAED;;;;;;;OAOG;IACH,kBAPW,MAAM,eACN,MAAM,WACN,WAAW,GACT,QAAQ,UAAU,CAAC,CAsC/B;;CAgDJ"}
+{"version":3,"file":"VGeoByteSource.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/geometry/virtual/format/read/VGeoByteSource.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH;IAwHI;;;;;;;;;;OAUG;IACH,iBAJW,UAAU,GAAC,WAAW,SACtB,MAAM,GACJ,cAAc,CAc1B;IAED;;;;;;;;;;;;;;;OAeG;IACH,uBAJW,IAAI,SACJ,MAAM,GACJ,cAAc,CAc1B;IApID;;;;;;OAMG;IACH,yBANW,MAAM,eACG,MAAM,QAAE,MAAM,QAAE,WAAW,iBAAI,QAAQ,UAAU,CAAC,SAG3D,MAAM,EAUhB;IAvDD;;;OAGG;IACH,aAFU,MAAM,CAEA;IAEhB;;;OAGG;IACH,eAFU,MAAM,CAEE;IAElB;;;;OAIG;IACH,YAFU,MAAM,CAED;IAEf;;;;;;;OAOG;IACH,YAHU;QAAC,IAAI,EAAE,KAAK,CAAC;QAAC,GAAG,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAC,GAC/D;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,IAAI,CAAA;KAAC,GAAG;QAAC,IAAI,EAAE,QAAQ,CAAC;QAAC,KAAK,EAAE,UAAU,CAAA;KAAC,GAAG,SAAS,CAE9D;IA8BvB;;OAEG;IACH,mBAEC;IAED;;;;;OAKG;IACH,uBAGC;IAED;;;;;;;OAOG;IACH,kBAPW,MAAM,eACN,MAAM,WACN,WAAW,GACT,QAAQ,UAAU,CAAC,CAsC/B;;CAwDJ"}

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

@@ -50,6 +50,16 @@ export class VGeoByteSource {
      */
     bytes_read = 0;
 
+    /**
+     * What another thread needs to open this source again: a URL with its length, a Blob, or the
+     * bytes. Set by the three constructors below and by `vgeo_fetch_byte_source`; `undefined` for
+     * a source built by hand, which then stays on the thread that built it.
+     *
+     * @type {{kind: 'url', url: string, byte_length: number, init?: object}
+     *     | {kind: 'blob', blob: Blob} | {kind: 'memory', bytes: Uint8Array} | undefined}
+     */
+    descriptor = undefined;
+
     /**
      * @type {function(number, number, AbortSignal=): Promise<Uint8Array>}
      */
@@ -154,11 +164,15 @@ export class VGeoByteSource {
     static of(bytes, name = 'a buffer in memory') {
         const array = bytes instanceof Uint8Array ? bytes : new Uint8Array(bytes);
 
-        return new VGeoByteSource(
+        const source = new VGeoByteSource(
             array.byteLength,
             async (offset, length) => array.subarray(offset, offset + length),
             name
         );
+
+        source.descriptor = { kind: 'memory', bytes: array };
+
+        return source;
     }
 
     /**
@@ -178,12 +192,16 @@ export class VGeoByteSource {
      * @returns {VGeoByteSource}
      */
     static from_blob(blob, name = blob.name ?? 'a blob') {
-        return new VGeoByteSource(
+        const source = new VGeoByteSource(
             blob.size,
             async (offset, length) => new Uint8Array(
                 await blob.slice(offset, offset + length).arrayBuffer()
             ),
             name
         );
+
+        source.descriptor = { kind: 'blob', blob };
+
+        return source;
     }
 }