@woosh/meep-engine 3.28.0 → 3.29.0

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

@@ -0,0 +1,27 @@
+/**
+ * Read a mesh's wedges off the values its corners already carry.
+ *
+ * **The values are the wedge.** A wedge is a set of corners at one vertex that shade the same, so
+ * the partition is not an extra fact to be stored and kept in step — it is a fact about the records,
+ * recoverable from them, and this is the one place in the builder that recovers it. Everywhere else
+ * wedges travel by provenance, because everywhere else the answer is already known and re-deriving
+ * it would be re-deciding it.
+ *
+ * Here is where the source gets to decide. A hard edge and a texture-chart boundary reach the
+ * builder as exactly this — corners of one vertex holding different records — and the weld in
+ * {@link vgeo_normalize_source} deliberately no longer flattens them.
+ *
+ * Grouped on **byte equality of the whole record**, which makes the partition an equivalence
+ * relation and so independent of the order corners are visited in. A tolerance would not be: it is
+ * not transitive, and two runs over one mesh could disagree about the same vertex. Tolerance belongs
+ * where a *decision* is made — the collapse — and not where a fact is read.
+ *
+ * @param {BinaryTopology} topology
+ * @returns {BtWedgeSet}
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function vgeo_mesh_wedges(topology: BinaryTopology): BtWedgeSet;
+import { BtWedgeSet } from "../../../../../../core/geom/3d/topology/struct/binary/BtWedgeSet.js";
+//# sourceMappingURL=vgeo_mesh_wedges.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"vgeo_mesh_wedges.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/geometry/virtual/format/attribute/vgeo_mesh_wedges.js"],"names":[],"mappings":"AAMA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,4DALa,UAAU,CAuEtB;2BA/F0B,qEAAqE"}

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

@@ -0,0 +1,97 @@
+import { NULL_POINTER } from "../../../../../../core/geom/3d/topology/struct/binary/BinaryTopology.js";
+import { BtWedgeSet } from "../../../../../../core/geom/3d/topology/struct/binary/BtWedgeSet.js";
+import {
+    bt_wedges_per_vertex
+} from "../../../../../../core/geom/3d/topology/struct/binary/io/bt_wedges_per_vertex.js";
+
+/**
+ * Read a mesh's wedges off the values its corners already carry.
+ *
+ * **The values are the wedge.** A wedge is a set of corners at one vertex that shade the same, so
+ * the partition is not an extra fact to be stored and kept in step — it is a fact about the records,
+ * recoverable from them, and this is the one place in the builder that recovers it. Everywhere else
+ * wedges travel by provenance, because everywhere else the answer is already known and re-deriving
+ * it would be re-deciding it.
+ *
+ * Here is where the source gets to decide. A hard edge and a texture-chart boundary reach the
+ * builder as exactly this — corners of one vertex holding different records — and the weld in
+ * {@link vgeo_normalize_source} deliberately no longer flattens them.
+ *
+ * Grouped on **byte equality of the whole record**, which makes the partition an equivalence
+ * relation and so independent of the order corners are visited in. A tolerance would not be: it is
+ * not transitive, and two runs over one mesh could disagree about the same vertex. Tolerance belongs
+ * where a *decision* is made — the collapse — and not where a fact is read.
+ *
+ * @param {BinaryTopology} topology
+ * @returns {BtWedgeSet}
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function vgeo_mesh_wedges(topology) {
+    const loop_data = topology.loop_data;
+
+    if (loop_data === null) {
+        // Position and nothing else: there is no record to disagree about, so every vertex shades
+        // one way and the degenerate set is the whole answer.
+        return bt_wedges_per_vertex(topology);
+    }
+
+    const loop_pool = topology.loops;
+    const vertex_pool = topology.vertices;
+
+    const of_loop = new Uint32Array(loop_pool.size).fill(NULL_POINTER);
+    const first_of_vertex = new Uint32Array(vertex_pool.size).fill(NULL_POINTER);
+
+    /**
+     * One representative corner per wedge, which is what a candidate is compared against.
+     * @type {number[]}
+     */
+    const corner_of_wedge = [];
+
+    const parent = [];
+    const next_of_wedge = [];
+
+    for (let loop = 0; loop < loop_pool.size; loop++) {
+        if (!loop_pool.is_allocated(loop)) {
+            continue;
+        }
+
+        const vertex = topology.loop_read_vertex(loop);
+
+        let wedge = first_of_vertex[vertex];
+
+        while (wedge !== NULL_POINTER) {
+            if (loop_data.record_equal(corner_of_wedge[wedge], loop)) {
+                break;
+            }
+
+            wedge = next_of_wedge[wedge];
+        }
+
+        if (wedge === NULL_POINTER) {
+            // A scan of the vertex's wedges rather than a hash of the record: on smooth geometry
+            // that list has one entry, on a crease two or three, and a key built per corner would
+            // cost more than the comparison it saves.
+            wedge = parent.length;
+
+            parent.push(wedge);
+            corner_of_wedge.push(loop);
+
+            next_of_wedge.push(first_of_vertex[vertex]);
+            first_of_vertex[vertex] = wedge;
+        }
+
+        of_loop[loop] = wedge;
+    }
+
+    const wedges = new BtWedgeSet();
+
+    wedges.count = parent.length;
+    wedges.parent = Uint32Array.from(parent);
+    wedges.next_of_wedge = Uint32Array.from(next_of_wedge);
+    wedges.first_of_vertex = first_of_vertex;
+    wedges.of_loop = of_loop;
+
+    return wedges;
+}

package/src/shade/renderer/geometry/virtual/format/cluster/VGEO_CLUSTER_OFFSET.d.ts

@@ -1,5 +1,10 @@
 /**
- * Cluster record field offsets, relative to the record's own start.
+ * Cluster record field offsets, relative to the record's own start — `format_version` 5.
+ *
+ * {@link VGEO_CLUSTER_OFFSET_V4 } is what this was, and every field from offset 40 on has moved:
+ * `subtree_aabb` took the twenty-four bytes that `bounds_sphere` and `cone_reserved` were spending
+ * on a sphere nothing at runtime read and a column that was always zero. The record is still 112
+ * bytes.
  */
 export type VGEO_CLUSTER_OFFSET = number;
 export namespace VGEO_CLUSTER_OFFSET {
@@ -7,11 +12,10 @@ export namespace VGEO_CLUSTER_OFFSET {
     let SELF_ERROR: number;
     let PARENT_ERROR: number;
     let PARENT_SPHERE: number;
-    let BOUNDS_SPHERE: number;
+    let SUBTREE_AABB: number;
     let AABB: number;
     let CHILD_REF: number;
     let CHILD_GROUP: number;
-    let CONE_RESERVED: number;
     let ENCODING_FLAGS: number;
     let PAYLOAD_OFFSET: number;
     let PAYLOAD_SIZE: number;

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

@@ -1 +1 @@
-{"version":3,"file":"VGEO_CLUSTER_OFFSET.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/geometry/virtual/format/cluster/VGEO_CLUSTER_OFFSET.js"],"names":[],"mappings":";;;kCAEU,MAAM"}
+{"version":3,"file":"VGEO_CLUSTER_OFFSET.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/geometry/virtual/format/cluster/VGEO_CLUSTER_OFFSET.js"],"names":[],"mappings":";;;;;;;;kCAQU,MAAM"}

package/src/shade/renderer/geometry/virtual/format/cluster/VGEO_CLUSTER_OFFSET.js

@@ -1,5 +1,11 @@
 /**
- * Cluster record field offsets, relative to the record's own start.
+ * Cluster record field offsets, relative to the record's own start — `format_version` 5.
+ *
+ * {@link VGEO_CLUSTER_OFFSET_V4} is what this was, and every field from offset 40 on has moved:
+ * `subtree_aabb` took the twenty-four bytes that `bounds_sphere` and `cone_reserved` were spending
+ * on a sphere nothing at runtime read and a column that was always zero. The record is still 112
+ * bytes.
+ *
  * @enum {number}
  */
 export const VGEO_CLUSTER_OFFSET = {
@@ -7,14 +13,18 @@ export const VGEO_CLUSTER_OFFSET = {
     SELF_ERROR: 16,
     PARENT_ERROR: 20,
     PARENT_SPHERE: 24,
-    BOUNDS_SPHERE: 40,
-    AABB: 56,
-    CHILD_REF: 80,
-    CHILD_GROUP: 82,
-    CONE_RESERVED: 84,
-    ENCODING_FLAGS: 88,
-    PAYLOAD_OFFSET: 92,
-    PAYLOAD_SIZE: 96,
-    VERTEX_COUNT: 100,
-    TRIANGLE_COUNT: 101,
+    /**
+     * Object-space AABB of this cluster's own vertices **and of every cluster reachable below it**
+     * through child groups — what the cut's per-cluster frustum test needs, because culling a
+     * cluster removes its whole subtree from the descent (CULL_PLAN_2026_09_16 §3.1).
+     */
+    SUBTREE_AABB: 40,
+    AABB: 64,
+    CHILD_REF: 88,
+    CHILD_GROUP: 90,
+    ENCODING_FLAGS: 92,
+    PAYLOAD_OFFSET: 96,
+    PAYLOAD_SIZE: 100,
+    VERTEX_COUNT: 104,
+    TRIANGLE_COUNT: 105,
 };

package/src/shade/renderer/geometry/virtual/format/cluster/VGEO_CLUSTER_OFFSET_V4.d.ts

@@ -0,0 +1,21 @@
+/**
+ * *
+ */
+export type VGEO_CLUSTER_OFFSET_V4 = number;
+export namespace VGEO_CLUSTER_OFFSET_V4 {
+    let SELF_SPHERE: number;
+    let SELF_ERROR: number;
+    let PARENT_ERROR: number;
+    let PARENT_SPHERE: number;
+    let BOUNDS_SPHERE: number;
+    let AABB: number;
+    let CHILD_REF: number;
+    let CHILD_GROUP: number;
+    let CONE_RESERVED: number;
+    let ENCODING_FLAGS: number;
+    let PAYLOAD_OFFSET: number;
+    let PAYLOAD_SIZE: number;
+    let VERTEX_COUNT: number;
+    let TRIANGLE_COUNT: number;
+}
+//# sourceMappingURL=VGEO_CLUSTER_OFFSET_V4.d.ts.map

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

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

package/src/shade/renderer/geometry/virtual/format/cluster/VGEO_CLUSTER_OFFSET_V4.js

@@ -0,0 +1,41 @@
+/**
+ * Cluster record field offsets as `format_version` 4 and earlier laid them out, kept so that the
+ * reader can still take the containers that exist.
+ *
+ * Version 5 dropped `bounds_sphere` and `cone_reserved` and put {@link
+ * VGEO_CLUSTER_OFFSET.SUBTREE_AABB} in their place, which moved every field from offset 40 on. A
+ * version-4 record read by the version-5 sequence hands back a `child_ref` taken out of the middle
+ * of a bounding box, so the decoder branches on the container's version rather than trusting one
+ * layout — and this is the other branch. Nothing but {@link vgeo_read_page} should need it.
+ *
+ * The writer and the validator have no such branch: one writes the current version and the other
+ * refuses anything else.
+ *
+ * @enum {number}
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export const VGEO_CLUSTER_OFFSET_V4 = {
+    SELF_SPHERE: 0,
+    SELF_ERROR: 16,
+    PARENT_ERROR: 20,
+    PARENT_SPHERE: 24,
+    /**
+     * The cluster's own miniball. Version 5 has no such field: nothing at runtime read it, and the
+     * builder keeps its own copy.
+     */
+    BOUNDS_SPHERE: 40,
+    AABB: 56,
+    CHILD_REF: 80,
+    CHILD_GROUP: 82,
+    /**
+     * Always zero, for a cone cull that was declined outright. Version 5 reclaimed it.
+     */
+    CONE_RESERVED: 84,
+    ENCODING_FLAGS: 88,
+    PAYLOAD_OFFSET: 92,
+    PAYLOAD_SIZE: 96,
+    VERTEX_COUNT: 100,
+    TRIANGLE_COUNT: 101,
+};

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

@@ -34,7 +34,13 @@ export class VirtualGeometryCluster {
      */
     parent_error: number;
     /**
-     * This cluster's own tight bounding sphere — culling only, never the cut test.
+     * This cluster's own tight bounding sphere.
+     *
+     * **Build-time only — the container does not carry it.** Nothing at runtime ever read it, and
+     * `format_version` 5 spent its bytes on {@link subtree_aabb}. It stays here because the build
+     * does use it: the header's `object_sphere`, the page assembler's group centroids, the cluster
+     * adjacency graph and a leaf's own `self_sphere` are all built from it.
+     *
      * @type {Float32Array}
      */
     bounds_sphere: Float32Array;
@@ -43,6 +49,18 @@ export class VirtualGeometryCluster {
      * @type {Float32Array}
      */
     aabb: Float32Array;
+    /**
+     * {@link aabb} unioned with the `subtree_aabb` of every cluster of this one's child group, so it
+     * contains every vertex anywhere below this cluster in the DAG.
+     *
+     * It is what the cut's per-cluster frustum test reads, and the reason it has to bound the whole
+     * subtree rather than this cluster is that culling a cluster removes everything under it from the
+     * descent — the child group is only ever reached *through* it (CULL_PLAN_2026_09_16 §1, §3.1).
+     * A leaf's equals its {@link aabb}.
+     *
+     * @type {Float32Array}
+     */
+    subtree_aabb: Float32Array;
     /**
      * The group this cluster refines into, or `undefined` when it is a leaf and refines into
      * nothing.

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;;;;;;;;;;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"}
+{"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;;;;;;;;;OASG;IACH,eAFU,YAAY,CAEc;IAEpC;;;OAGG;IACH,MAFU,YAAY,CAEK;IAE3B;;;;;;;;;;OAUG;IACH,cAFU,YAAY,CAEa;IAEnC;;;;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

@@ -39,7 +39,13 @@ export class VirtualGeometryCluster {
     parent_error = Number.POSITIVE_INFINITY;
 
     /**
-     * This cluster's own tight bounding sphere — culling only, never the cut test.
+     * This cluster's own tight bounding sphere.
+     *
+     * **Build-time only — the container does not carry it.** Nothing at runtime ever read it, and
+     * `format_version` 5 spent its bytes on {@link subtree_aabb}. It stays here because the build
+     * does use it: the header's `object_sphere`, the page assembler's group centroids, the cluster
+     * adjacency graph and a leaf's own `self_sphere` are all built from it.
+     *
      * @type {Float32Array}
      */
     bounds_sphere = new Float32Array(4);
@@ -50,6 +56,19 @@ export class VirtualGeometryCluster {
      */
     aabb = new Float32Array(6);
 
+    /**
+     * {@link aabb} unioned with the `subtree_aabb` of every cluster of this one's child group, so it
+     * contains every vertex anywhere below this cluster in the DAG.
+     *
+     * It is what the cut's per-cluster frustum test reads, and the reason it has to bound the whole
+     * subtree rather than this cluster is that culling a cluster removes everything under it from the
+     * descent — the child group is only ever reached *through* it (CULL_PLAN_2026_09_16 §1, §3.1).
+     * A leaf's equals its {@link aabb}.
+     *
+     * @type {Float32Array}
+     */
+    subtree_aabb = new Float32Array(6);
+
     /**
      * The group this cluster refines into, or `undefined` when it is a leaf and refines into
      * nothing.

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

@@ -0,0 +1,25 @@
+/**
+ * `codec` value for a blob stored as one raw DEFLATE stream (RFC 1951), no zlib or gzip wrapper.
+ *
+ * Bare for the same reason {@link VGEO_CODEC_LZ4} is a bare block: both wrappers carry a magic, a
+ * length and a checksum that the frame header already carries better — `decoded_size` is what the
+ * stream is decoded against and the identity-seeded `checksum` is what proves the stored bytes
+ * arrived. A zlib header would be two bytes of restating and a gzip one eighteen.
+ *
+ * This is the hosted codec: `CompressionStream`/`DecompressionStream` are the platform's own zlib,
+ * so it costs no bytes of library and runs off the JS thread — and it is *asynchronous*, which is
+ * why everything from {@link vgeo_decode_frame_blob} up to {@link vgeo_build} is.
+ *
+ * What it is worth, measured over the 44 pages of a 240x120 torus: **1.369x** against LZ4's 1.295x
+ * on the same pages, for a decode of every page that cost 16.9 ms against LZ4's 3.8 ms — 126 MB/s
+ * of decoded output against 562.
+ *
+ * **This is what the builder and the converter write by default.** An asset is built once and
+ * fetched forever, so the denser side of that trade is the one worth taking without being asked;
+ * {@link VGEO_CODEC_LZ4} is a deliberate choice for a container whose pages arrive while someone is
+ * looking at it, where the decode is a page's arrival cost rather than a build's.
+ *
+ * @type {number}
+ */
+export const VGEO_CODEC_DEFLATE: number;
+//# sourceMappingURL=VGEO_CODEC_DEFLATE.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"VGEO_CODEC_DEFLATE.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/geometry/virtual/format/frame/VGEO_CODEC_DEFLATE.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,iCAFU,MAAM,CAEoB"}

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

@@ -0,0 +1,24 @@
+/**
+ * `codec` value for a blob stored as one raw DEFLATE stream (RFC 1951), no zlib or gzip wrapper.
+ *
+ * Bare for the same reason {@link VGEO_CODEC_LZ4} is a bare block: both wrappers carry a magic, a
+ * length and a checksum that the frame header already carries better — `decoded_size` is what the
+ * stream is decoded against and the identity-seeded `checksum` is what proves the stored bytes
+ * arrived. A zlib header would be two bytes of restating and a gzip one eighteen.
+ *
+ * This is the hosted codec: `CompressionStream`/`DecompressionStream` are the platform's own zlib,
+ * so it costs no bytes of library and runs off the JS thread — and it is *asynchronous*, which is
+ * why everything from {@link vgeo_decode_frame_blob} up to {@link vgeo_build} is.
+ *
+ * What it is worth, measured over the 44 pages of a 240x120 torus: **1.369x** against LZ4's 1.295x
+ * on the same pages, for a decode of every page that cost 16.9 ms against LZ4's 3.8 ms — 126 MB/s
+ * of decoded output against 562.
+ *
+ * **This is what the builder and the converter write by default.** An asset is built once and
+ * fetched forever, so the denser side of that trade is the one worth taking without being asked;
+ * {@link VGEO_CODEC_LZ4} is a deliberate choice for a container whose pages arrive while someone is
+ * looking at it, where the decode is a page's arrival cost rather than a build's.
+ *
+ * @type {number}
+ */
+export const VGEO_CODEC_DEFLATE = 2;

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

@@ -6,6 +6,11 @@
  * its identity-seeded `checksum` covers the stored bytes. So the blob is the bare block, and the
  * frame header is what tells a decoder how much to expect out of it.
  *
+ * Not the builder's default — {@link VGEO_CODEC_DEFLATE} is, because it stores a container in fewer
+ * bytes and a build happens once where a fetch happens forever. This is what to set for a container
+ * whose pages arrive during play: it decodes at 562 MB/s against deflate's 126, and that decode is
+ * a page's arrival cost on the residency path.
+ *
  * @type {number}
  */
 export const VGEO_CODEC_LZ4: number;

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

@@ -1 +1 @@
-{"version":3,"file":"VGEO_CODEC_LZ4.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/geometry/virtual/format/frame/VGEO_CODEC_LZ4.js"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,6BAFU,MAAM,CAEgB"}
+{"version":3,"file":"VGEO_CODEC_LZ4.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/geometry/virtual/format/frame/VGEO_CODEC_LZ4.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,6BAFU,MAAM,CAEgB"}

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

@@ -6,6 +6,11 @@
  * its identity-seeded `checksum` covers the stored bytes. So the blob is the bare block, and the
  * frame header is what tells a decoder how much to expect out of it.
  *
+ * Not the builder's default — {@link VGEO_CODEC_DEFLATE} is, because it stores a container in fewer
+ * bytes and a build happens once where a fetch happens forever. This is what to set for a container
+ * whose pages arrive during play: it decodes at 562 MB/s against deflate's 126, and that decode is
+ * a page's arrival cost on the residency path.
+ *
  * @type {number}
  */
 export const VGEO_CODEC_LZ4 = 1;

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

@@ -1 +1 @@
-{"version":3,"file":"vgeo_codec_name.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/geometry/virtual/format/frame/vgeo_codec_name.js"],"names":[],"mappings":"AAGA;;;;;;;;;;;;GAYG;AACH,uCANW,MAAM,GACJ,MAAM,CAelB"}
+{"version":3,"file":"vgeo_codec_name.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/geometry/virtual/format/frame/vgeo_codec_name.js"],"names":[],"mappings":"AAIA;;;;;;;;;;;;GAYG;AACH,uCANW,MAAM,GACJ,MAAM,CAmBlB"}

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

@@ -1,3 +1,4 @@
+import { VGEO_CODEC_DEFLATE } from "./VGEO_CODEC_DEFLATE.js";
 import { VGEO_CODEC_LZ4 } from "./VGEO_CODEC_LZ4.js";
 import { VGEO_CODEC_RAW } from "./VGEO_CODEC_RAW.js";
 
@@ -23,5 +24,9 @@ export function vgeo_codec_name(codec) {
         return 'lz4';
     }
 
+    if (codec === VGEO_CODEC_DEFLATE) {
+        return 'deflate';
+    }
+
     return `codec ${codec}`;
 }

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

@@ -9,18 +9,25 @@
  *
  * A blob that does not decode to exactly `decoded_size` bytes is refused rather than accepted short
  * — a page truncated to a plausible prefix is the one corruption that reads as a valid page with
- * missing geometry, and there is no later check that would notice.
+ * missing geometry, and there is no later check that would notice. Neither decoder is allowed to
+ * *overrun* it either: the LZ4 one is handed the end of the page as its limit, and the deflate one
+ * is stopped at the first chunk that would pass it, so a blob that expands further than its header
+ * admits costs one chunk rather than the whole expansion.
+ *
+ * This is asynchronous because {@link VGEO_CODEC_DEFLATE} is: `DecompressionStream` is the
+ * platform's zlib and the platform only offers it as a stream. The raw and LZ4 paths still finish
+ * in the caller's turn, so awaiting them costs a microtask and nothing else.
  *
  * @param {Uint8Array} destination at least `decoded_size` bytes free at `destination_offset`
  * @param {number} destination_offset where the decoded page starts
  * @param {Uint8Array} source the file, indexed from its first byte — the offsets on `frame` are
  *     absolute
  * @param {VGeoFrameExtent} frame
- * @returns {number} the offset just past the last byte written
+ * @returns {Promise<number>} the offset just past the last byte written
  * @throws {Error} on a codec with no decoder here, or a blob that does not decode as its header says
  *
  * @author Alex Goldring
  * @copyright Company Named Limited (c) 2026
  */
-export function vgeo_decode_frame_blob(destination: Uint8Array, destination_offset: number, source: Uint8Array, frame: VGeoFrameExtent): number;
+export function vgeo_decode_frame_blob(destination: Uint8Array, destination_offset: number, source: Uint8Array, frame: VGeoFrameExtent): Promise<number>;
 //# sourceMappingURL=vgeo_decode_frame_blob.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"vgeo_decode_frame_blob.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/geometry/virtual/format/frame/vgeo_decode_frame_blob.js"],"names":[],"mappings":"AAOA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,oDAXW,UAAU,sBACV,MAAM,UACN,UAAU,2BAGR,MAAM,CA0DlB"}
+{"version":3,"file":"vgeo_decode_frame_blob.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/geometry/virtual/format/frame/vgeo_decode_frame_blob.js"],"names":[],"mappings":"AASA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,oDAXW,UAAU,sBACV,MAAM,UACN,UAAU,2BAGR,QAAQ,MAAM,CAAC,CAmF3B"}

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

@@ -1,6 +1,8 @@
 import { assert } from "../../../../../../core/assert.js";
+import { decompress_bytes_into } from "../../../../../../core/binary/compression/decompress_bytes_into.js";
 import { lz4_decompress_block } from "../../../../../../core/binary/lz4/lz4_decompress_block.js";
 import { VGEO_CHILD_TABLE_ENTRY_SIZE } from "./VGEO_CHILD_TABLE_ENTRY_SIZE.js";
+import { VGEO_CODEC_DEFLATE } from "./VGEO_CODEC_DEFLATE.js";
 import { VGEO_CODEC_LZ4 } from "./VGEO_CODEC_LZ4.js";
 import { VGEO_CODEC_RAW } from "./VGEO_CODEC_RAW.js";
 import { VGEO_FRAME_HEADER_SIZE } from "./VGEO_FRAME_HEADER_SIZE.js";
@@ -16,20 +18,27 @@ import { VGEO_FRAME_HEADER_SIZE } from "./VGEO_FRAME_HEADER_SIZE.js";
  *
  * A blob that does not decode to exactly `decoded_size` bytes is refused rather than accepted short
  * — a page truncated to a plausible prefix is the one corruption that reads as a valid page with
- * missing geometry, and there is no later check that would notice.
+ * missing geometry, and there is no later check that would notice. Neither decoder is allowed to
+ * *overrun* it either: the LZ4 one is handed the end of the page as its limit, and the deflate one
+ * is stopped at the first chunk that would pass it, so a blob that expands further than its header
+ * admits costs one chunk rather than the whole expansion.
+ *
+ * This is asynchronous because {@link VGEO_CODEC_DEFLATE} is: `DecompressionStream` is the
+ * platform's zlib and the platform only offers it as a stream. The raw and LZ4 paths still finish
+ * in the caller's turn, so awaiting them costs a microtask and nothing else.
  *
  * @param {Uint8Array} destination at least `decoded_size` bytes free at `destination_offset`
  * @param {number} destination_offset where the decoded page starts
  * @param {Uint8Array} source the file, indexed from its first byte — the offsets on `frame` are
  *     absolute
  * @param {VGeoFrameExtent} frame
- * @returns {number} the offset just past the last byte written
+ * @returns {Promise<number>} the offset just past the last byte written
  * @throws {Error} on a codec with no decoder here, or a blob that does not decode as its header says
  *
  * @author Alex Goldring
  * @copyright Company Named Limited (c) 2026
  */
-export function vgeo_decode_frame_blob(destination, destination_offset, source, frame) {
+export async function vgeo_decode_frame_blob(destination, destination_offset, source, frame) {
     assert.isNonNegativeInteger(destination_offset, 'destination_offset');
     assert.lessThanOrEqual(
         destination_offset + frame.decoded_size, destination.length,
@@ -80,5 +89,30 @@ export function vgeo_decode_frame_blob(destination, destination_offset, source,
         return end;
     }
 
+    if (frame.codec === VGEO_CODEC_DEFLATE) {
+        let written;
+
+        try {
+            written = await decompress_bytes_into(
+                destination, destination_offset, frame.decoded_size,
+                [source.subarray(blob, blob + frame.stored_size)], 'deflate-raw'
+            );
+        } catch (error) {
+            // The platform's own words for a malformed stream vary by host and say nothing about
+            // which page it was, which is the one thing a reader reporting this needs. The original
+            // is kept as the cause, because which host said what is the next question after that.
+            throw new Error(`page ${frame.page_index}: ${error.message}`, { cause: error });
+        }
+
+        if (written !== frame.decoded_size) {
+            throw new Error(
+                `page ${frame.page_index}: the deflate stream decoded to ${written}`
+                + ` bytes, its frame header says ${frame.decoded_size}`
+            );
+        }
+
+        return end;
+    }
+
     throw new Error(`page ${frame.page_index}: codec ${frame.codec} has no decoder here`);
 }

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

@@ -3,29 +3,37 @@
  *
  * A compressing codec is a *request*, not a promise: what comes back is whichever of the two is
  * smaller, with the codec that describes it. That is what makes turning compression on safe to do
- * unconditionally — a page of incompressible bytes costs the LZ4 worst case, about one byte in 255
- * plus a token, and paying that to store bytes verbatim is a straight loss. Declining is per page,
- * because `codec` is a frame field: one asset can carry both, and a reader that handles the two
- * codecs handles any mixture of them without knowing there was a decision.
+ * unconditionally — a page of incompressible bytes costs the compressor's worst case, about one
+ * byte in 255 plus a token for LZ4 and five bytes per 64 KB stored block for deflate, and paying
+ * that to store bytes verbatim is a straight loss. Declining is per page, because `codec` is a
+ * frame field: one asset can carry a mixture, and a reader that handles the codecs handles any
+ * mixture of them without knowing there was a decision.
  *
- * The blob is the bare LZ4 block. It carries no length of its own, and none is needed — the frame
- * header's `decoded_size` is what {@link vgeo_decode_frame_blob} decodes against, and the frame's
- * checksum is what proves the stored bytes arrived intact.
+ * The blob is the bare LZ4 block or the bare DEFLATE stream. Neither carries a length of its own
+ * and neither needs to — the frame header's `decoded_size` is what {@link vgeo_decode_frame_blob}
+ * decodes against, and the frame's checksum is what proves the stored bytes arrived intact.
  *
- * The level is how hard the encoder looks for matches, and nothing else: every level writes the
+ * This is asynchronous because {@link VGEO_CODEC_DEFLATE} is: `CompressionStream` is the platform's
+ * zlib and the platform only offers it as a stream. The raw and LZ4 paths still finish in the
+ * caller's turn, so awaiting them costs a microtask and nothing else.
+ *
+ * The LZ4 level is how hard the encoder looks for matches, and nothing else: every level writes the
  * same LZ4 block format, so it is a build-time decision with no reader consequence at all. What it
  * buys on a page of encoded geometry is about 2.5% over the fast encoder, almost all of which is
  * already there at level 3; what it costs is roughly an order of magnitude of encoder throughput,
- * which over a whole conversion comes to a couple of percent of the build.
+ * which over a whole conversion comes to a couple of percent of the build. **Deflate ignores it** —
+ * `CompressionStream` exposes no level, so the host's zlib default is the only setting there is.
  *
  * @param {Uint8Array} bytes the decoded page
- * @param {number} codec the codec to attempt, one of {@link VGEO_CODEC_RAW} or {@link VGEO_CODEC_LZ4}
- * @param {number} [level] how hard to look, one of {@link LZ4_LEVEL}'s; the raw codec ignores it
- * @returns {VGeoFrameBlob}
+ * @param {number} codec the codec to attempt, one of {@link VGEO_CODEC_RAW},
+ *     {@link VGEO_CODEC_LZ4} or {@link VGEO_CODEC_DEFLATE}
+ * @param {number} [level] how hard to look, one of {@link LZ4_LEVEL}'s; the raw and deflate codecs
+ *     ignore it
+ * @returns {Promise<VGeoFrameBlob>}
  *
  * @author Alex Goldring
  * @copyright Company Named Limited (c) 2026
  */
-export function vgeo_encode_frame_blob(bytes: Uint8Array, codec: number, level?: number): VGeoFrameBlob;
+export function vgeo_encode_frame_blob(bytes: Uint8Array, codec: number, level?: number): Promise<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":"AAQA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,8CARW,UAAU,SACV,MAAM,UACN,MAAM,GACJ,aAAa,CAgCzB;8BAzD6B,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":"AAUA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,8CAVW,UAAU,SACV,MAAM,UAEN,MAAM,GAEJ,QAAQ,aAAa,CAAC,CA8ClC;8BA/E6B,oBAAoB"}