@woosh/meep-engine 3.27.0 → 3.29.0

package/src/shade/renderer/geometry/virtual/build/level/VGeoContribution.d.ts

@@ -0,0 +1,40 @@
+/**
+ * One cluster's geometry expressed against the frontier it came out of, which is what lets the next
+ * frontier be stitched from a mixture of freshly simplified clusters and untouched ones.
+ *
+ * Produced by `vgeo_try_repack`, `vgeo_build_group_step` and `vgeo_build_levels` — the last for
+ * the clusters a round left alone — and consumed by `vgeo_stitch_frontier`, which is the only
+ * thing that ever reads one.
+ */
+type VGeoContribution = {
+    positions: Float32Array;
+    /**
+     * local to {@link positions }
+     */
+    indices: Uint32Array;
+    /**
+     * ids in the mesh {@link topology } belongs to; not
+     * unique, because there is one entry per *wedge* and a seam vertex is several
+     */
+    local_vertex_ids: Uint32Array;
+    /**
+     * the same vertices, named in the frontier's mesh
+     */
+    source_vertex_ids: Uint32Array;
+    /**
+     * one corner of {@link topology } per entry, which is where
+     * that entry's appearance is read from — a vertex alone does not address it
+     */
+    attribute_ids: Uint32Array;
+    /**
+     * the wedge each entry is, named in the frontier's mesh,
+     * which is how its accumulated attribute quadric follows it across the seam
+     */
+    source_wedge_ids: Uint32Array;
+    /**
+     * the mesh {@link local_vertex_ids } name vertices of, whose
+     * loop data block holds their attributes
+     */
+    topology: BinaryTopology;
+};
+//# sourceMappingURL=VGeoContribution.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"VGeoContribution.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/geometry/virtual/build/level/VGeoContribution.js"],"names":[],"mappings":";;;;;;;;;eASc,YAAY;;;;aACZ,WAAW;;;;;sBACX,WAAW;;;;uBAEX,WAAW;;;;;mBACX,WAAW;;;;;sBAEX,WAAW"}

package/src/shade/renderer/geometry/virtual/build/level/VGeoContribution.js

@@ -0,0 +1,24 @@
+/**
+ * One cluster's geometry expressed against the frontier it came out of, which is what lets the next
+ * frontier be stitched from a mixture of freshly simplified clusters and untouched ones.
+ *
+ * Produced by `vgeo_try_repack`, `vgeo_build_group_step` and `vgeo_build_levels` — the last for
+ * the clusters a round left alone — and consumed by `vgeo_stitch_frontier`, which is the only
+ * thing that ever reads one.
+ *
+ * @typedef {object} VGeoContribution
+ * @property {Float32Array} positions
+ * @property {Uint32Array} indices local to {@link positions}
+ * @property {Uint32Array} local_vertex_ids ids in the mesh {@link topology} belongs to; not
+ *     unique, because there is one entry per *wedge* and a seam vertex is several
+ * @property {Uint32Array} source_vertex_ids the same vertices, named in the frontier's mesh
+ * @property {Uint32Array} attribute_ids one corner of {@link topology} per entry, which is where
+ *     that entry's appearance is read from — a vertex alone does not address it
+ * @property {Uint32Array} source_wedge_ids the wedge each entry is, named in the frontier's mesh,
+ *     which is how its accumulated attribute quadric follows it across the seam
+ * @property {BinaryTopology} topology the mesh {@link local_vertex_ids} name vertices of, whose
+ *     loop data block holds their attributes
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */

package/src/shade/renderer/geometry/virtual/build/level/VGeoFrontier.d.ts

@@ -0,0 +1,91 @@
+/**
+ * Every cluster nothing has merged yet, and the geometry they currently stand for.
+ *
+ * One mesh holds the whole frontier so that a group can be extracted with its surroundings intact —
+ * the lock set is "every vertex a face outside this group touches", and that question has no answer
+ * in a mesh that holds the group alone.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class VGeoFrontier {
+    /**
+     * @type {VirtualGeometryMesh}
+     */
+    mesh: VirtualGeometryMesh;
+    /**
+     * @type {VirtualGeometryCluster[]}
+     */
+    clusters: VirtualGeometryCluster[];
+    /**
+     * `cluster_faces[i]` are the faces of {@link mesh} that cluster `i` owns.
+     * @type {number[][]}
+     */
+    cluster_faces: number[][];
+    /**
+     * One accumulated quadric per vertex of {@link mesh}, carried unbroken from the source mesh.
+     *
+     * This is what makes the error mean "how far this is from the geometry the artist authored"
+     * rather than "how far this is from the frontier it was simplified out of". A survivor absorbs
+     * its victim's quadric at every collapse, at every round, so a vertex twelve rounds up still
+     * carries the planes of every source triangle that was ever folded into it, and evaluating its
+     * quadric at its current position measures the deviation from the source directly. Composing
+     * per-round residuals instead only *bounds* that, by the triangle inequality, and the bound
+     * loosens with every round: measured on a unit sphere, the same ninety-triangle root read 0.36
+     * built from 3k source triangles and 13.3 built from 24k, where it is the same approximation and
+     * reads 0.0315 either way once the quadrics are carried.
+     *
+     * @type {Quadric3[]}
+     */
+    quadrics: Quadric3[];
+    /**
+     * Which of the mesh's channels travel through a collapse, and where each one sits in
+     * {@link attribute_values}. Constant for a whole build — the channel set is the source's.
+     * @type {{components: number, channels: {attribute: number, offset: number, count: number}[]}}
+     */
+    attribute_layout: {
+        components: number;
+        channels: {
+            attribute: number;
+            offset: number;
+            count: number;
+        }[];
+    };
+    /**
+     * What a full unit of each component of {@link attribute_values} is worth in object-space
+     * position error. Resolved once, off the source's bounds, by
+     * {@link vgeo_resolve_attribute_weights}.
+     * @type {Float64Array}
+     */
+    attribute_weights: Float64Array;
+    /**
+     * The attribute quadric of every vertex of {@link mesh}, indexed by vertex id at a stride of
+     * `quadric_attribute_size(attribute_layout.components)`.
+     *
+     * Carried the way {@link quadrics} is and for the same reason: built once from the source
+     * triangles and accumulated onto survivors ever after, so a vertex twelve rounds up still holds
+     * the fields of every source triangle folded into it and the value fitted from them is a
+     * statement about what was authored rather than about the round before.
+     *
+     * One flat buffer rather than an object per vertex — which is what `quadric3_*`'s own
+     * documentation offers, and at `11 + 4m` doubles each over a million-vertex primitive it is the
+     * difference between a round allocating nothing and allocating a million short-lived objects.
+     *
+     * Empty where the mesh carries no travelling channel at all.
+     * @type {Float64Array}
+     */
+    attribute_quadrics: Float64Array;
+    /**
+     * Which corners of {@link mesh} shade as one, and so which of them {@link attribute_quadrics}
+     * and the carried values are indexed by.
+     *
+     * A vertex has one position and the topology says so; it does not have one appearance, and a
+     * hard edge or a texture seam is exactly a vertex whose corners disagree. Rebuilt with the
+     * frontier every round rather than carried, because the frontier's mesh is rebuilt too — what
+     * carries across is the accumulated quadric of each wedge, the same way it is for each vertex.
+     *
+     * @type {BtWedgeSet}
+     */
+    wedges: BtWedgeSet;
+}
+//# sourceMappingURL=VGeoFrontier.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"VGeoFrontier.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/geometry/virtual/build/level/VGeoFrontier.js"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH;IACI;;OAEG;IACH,0BAAY;IAEZ;;OAEG;IACH,UAFU,wBAAwB,CAEpB;IAEd;;;OAGG;IACH,eAFU,MAAM,EAAE,EAAE,CAED;IAEnB;;;;;;;;;;;;;;OAcG;IACH,UAFU,UAAU,CAEN;IAEd;;;;OAIG;IACH,kBAFU;QAAC,UAAU,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE;YAAC,SAAS,EAAE,MAAM,CAAC;YAAC,MAAM,EAAE,MAAM,CAAC;YAAC,KAAK,EAAE,MAAM,CAAA;SAAC,EAAE,CAAA;KAAC,CAE3C;IAEnD;;;;;OAKG;IACH,mBAFU,YAAY,CAEkB;IAExC;;;;;;;;;;;;;;;OAeG;IACH,oBAFU,YAAY,CAEmB;IAEzC;;;;;;;;;;OAUG;IACH,mBAAc;CAEjB"}

package/src/shade/renderer/geometry/virtual/build/level/VGeoFrontier.js

@@ -0,0 +1,91 @@
+/**
+ * Every cluster nothing has merged yet, and the geometry they currently stand for.
+ *
+ * One mesh holds the whole frontier so that a group can be extracted with its surroundings intact —
+ * the lock set is "every vertex a face outside this group touches", and that question has no answer
+ * in a mesh that holds the group alone.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class VGeoFrontier {
+    /**
+     * @type {VirtualGeometryMesh}
+     */
+    mesh = null;
+
+    /**
+     * @type {VirtualGeometryCluster[]}
+     */
+    clusters = [];
+
+    /**
+     * `cluster_faces[i]` are the faces of {@link mesh} that cluster `i` owns.
+     * @type {number[][]}
+     */
+    cluster_faces = [];
+
+    /**
+     * One accumulated quadric per vertex of {@link mesh}, carried unbroken from the source mesh.
+     *
+     * This is what makes the error mean "how far this is from the geometry the artist authored"
+     * rather than "how far this is from the frontier it was simplified out of". A survivor absorbs
+     * its victim's quadric at every collapse, at every round, so a vertex twelve rounds up still
+     * carries the planes of every source triangle that was ever folded into it, and evaluating its
+     * quadric at its current position measures the deviation from the source directly. Composing
+     * per-round residuals instead only *bounds* that, by the triangle inequality, and the bound
+     * loosens with every round: measured on a unit sphere, the same ninety-triangle root read 0.36
+     * built from 3k source triangles and 13.3 built from 24k, where it is the same approximation and
+     * reads 0.0315 either way once the quadrics are carried.
+     *
+     * @type {Quadric3[]}
+     */
+    quadrics = [];
+
+    /**
+     * Which of the mesh's channels travel through a collapse, and where each one sits in
+     * {@link attribute_values}. Constant for a whole build — the channel set is the source's.
+     * @type {{components: number, channels: {attribute: number, offset: number, count: number}[]}}
+     */
+    attribute_layout = { components: 0, channels: [] };
+
+    /**
+     * What a full unit of each component of {@link attribute_values} is worth in object-space
+     * position error. Resolved once, off the source's bounds, by
+     * {@link vgeo_resolve_attribute_weights}.
+     * @type {Float64Array}
+     */
+    attribute_weights = new Float64Array(0);
+
+    /**
+     * The attribute quadric of every vertex of {@link mesh}, indexed by vertex id at a stride of
+     * `quadric_attribute_size(attribute_layout.components)`.
+     *
+     * Carried the way {@link quadrics} is and for the same reason: built once from the source
+     * triangles and accumulated onto survivors ever after, so a vertex twelve rounds up still holds
+     * the fields of every source triangle folded into it and the value fitted from them is a
+     * statement about what was authored rather than about the round before.
+     *
+     * One flat buffer rather than an object per vertex — which is what `quadric3_*`'s own
+     * documentation offers, and at `11 + 4m` doubles each over a million-vertex primitive it is the
+     * difference between a round allocating nothing and allocating a million short-lived objects.
+     *
+     * Empty where the mesh carries no travelling channel at all.
+     * @type {Float64Array}
+     */
+    attribute_quadrics = new Float64Array(0);
+
+    /**
+     * Which corners of {@link mesh} shade as one, and so which of them {@link attribute_quadrics}
+     * and the carried values are indexed by.
+     *
+     * A vertex has one position and the topology says so; it does not have one appearance, and a
+     * hard edge or a texture seam is exactly a vertex whose corners disagree. Rebuilt with the
+     * frontier every round rather than carried, because the frontier's mesh is rebuilt too — what
+     * carries across is the accumulated quadric of each wedge, the same way it is for each vertex.
+     *
+     * @type {BtWedgeSet}
+     */
+    wedges = null;
+
+}

package/src/shade/renderer/geometry/virtual/build/level/VGeoGroupRepack.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Several leaves re-cut into one, with nothing simplified — see {@link vgeo_try_repack}.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class VGeoGroupRepack {
+    /**
+     * The leaves this removes from the DAG.
+     * @type {VirtualGeometryCluster[]}
+     */
+    replaced: VirtualGeometryCluster[];
+    /**
+     * The leaves that take their place -- always fewer.
+     * @type {VirtualGeometryCluster[]}
+     */
+    clusters: VirtualGeometryCluster[];
+    /**
+     * Parallel to {@link clusters}.
+     * @type {VGeoContribution[]}
+     */
+    geometry: VGeoContribution[];
+}
+//# sourceMappingURL=VGeoGroupRepack.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"VGeoGroupRepack.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/geometry/virtual/build/level/VGeoGroupRepack.js"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH;IACI;;;OAGG;IACH,UAFU,wBAAwB,CAEpB;IAEd;;;OAGG;IACH,UAFU,wBAAwB,CAEpB;IAEd;;;OAGG;IACH,UAFU,gBAAgB,EAAE,CAEd;CACjB"}

package/src/shade/renderer/geometry/virtual/build/level/VGeoGroupRepack.js

@@ -0,0 +1,25 @@
+/**
+ * Several leaves re-cut into one, with nothing simplified — see {@link vgeo_try_repack}.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class VGeoGroupRepack {
+    /**
+     * The leaves this removes from the DAG.
+     * @type {VirtualGeometryCluster[]}
+     */
+    replaced = [];
+
+    /**
+     * The leaves that take their place -- always fewer.
+     * @type {VirtualGeometryCluster[]}
+     */
+    clusters = [];
+
+    /**
+     * Parallel to {@link clusters}.
+     * @type {VGeoContribution[]}
+     */
+    geometry = [];
+}

package/src/shade/renderer/geometry/virtual/build/level/VGeoGroupStep.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Everything one group step produced, before it is committed. Kept separate so that a round which
+ * fails to make progress can be discarded without having mutated the frontier.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class VGeoGroupStep {
+    /**
+     * The frontier clusters this group holds.
+     * @type {VirtualGeometryCluster[]}
+     */
+    child_clusters: VirtualGeometryCluster[];
+    /**
+     * @type {VirtualGeometryCluster[]}
+     */
+    parent_clusters: VirtualGeometryCluster[];
+    /**
+     * Parallel to {@link parent_clusters}: the geometry each parent was cut from, in terms of the
+     * frontier, so the next frontier can be stitched back together.
+     * @type {VGeoContribution[]}
+     */
+    parent_geometry: VGeoContribution[];
+    /**
+     * The value both sides of this step store: the object-space distance from the *source* surface
+     * that this step's geometry now stands at, floored by what its children already carried.
+     * @type {number}
+     */
+    error: number;
+    /**
+     * `frontier vertex id -> that vertex's quadric after this step`, for every vertex that survived
+     * it. Held rather than written straight back because a step is speculative until the round
+     * accepts it, and because two steps sharing a pinned boundary vertex must have their gains
+     * combined rather than one overwriting the other.
+     * @type {Map<number, Quadric3>}
+     */
+    quadrics: Map<number, Quadric3>;
+    /**
+     * Every attribute quadric this step's collapses left behind, indexed by the **wedge's** id
+     * *within the step's own submesh* at a stride of `quadric_attribute_size(components)`.
+     *
+     * One buffer rather than an entry per wedge: it is the array the simplifier was handed and
+     * finished with, kept whole. {@link attribute_source_wedge_ids} is what turns a position in it
+     * back into a frontier wedge, and {@link live_wedges} is what says which of them are still
+     * alive.
+     *
+     * Liveness cannot be read off {@link quadrics} the way it once was. A collapse can leave a
+     * victim's wedge standing — adopted by the survivor, carrying corners of its own — so a wedge
+     * outlives the vertex it started on, and the vertex map would have called it dead.
+     *
+     * The *results*, not the gains. `vgeo_build_levels` recovers the gain by subtracting what the
+     * frontier already held, because two steps sharing a pinned boundary vertex each began from that
+     * vertex's quadric and adding both results whole would count the source under it twice.
+     *
+     * Empty where the mesh carries no travelling channel at all.
+     * @type {Float64Array}
+     */
+    attribute_quadrics: Float64Array;
+    /**
+     * For every wedge of this step's submesh, the frontier wedge it came from — which is what
+     * {@link attribute_quadrics} is read through.
+     * @type {Uint32Array}
+     */
+    attribute_source_wedge_ids: Uint32Array;
+    /**
+     * Which of those wedges are still their own root, and so still stand for something. A wedge that
+     * merged into another gave that one its quadric and has nothing left to fold back.
+     * @type {Set<number>}
+     */
+    live_wedges: Set<number>;
+    /**
+     * The LOD-metric sphere both sides of this step store.
+     * @type {Float32Array}
+     */
+    sphere: Float32Array;
+}
+//# sourceMappingURL=VGeoGroupStep.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"VGeoGroupStep.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/geometry/virtual/build/level/VGeoGroupStep.js"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH;IACI;;;OAGG;IACH,gBAFU,wBAAwB,CAEd;IAEpB;;OAEG;IACH,iBAFU,wBAAwB,CAEb;IAErB;;;;OAIG;IACH,iBAFU,gBAAgB,EAAE,CAEP;IAErB;;;;OAIG;IACH,OAFU,MAAM,CAEN;IAEV;;;;;;OAMG;IACH,UAFU,IAAI,MAAM,WAAW,CAEV;IAErB;;;;;;;;;;;;;;;;;;;OAmBG;IACH,oBAFU,YAAY,CAEmB;IAEzC;;;;OAIG;IACH,4BAFU,WAAW,CAE2B;IAEhD;;;;OAIG;IACH,aAFU,IAAI,MAAM,CAAC,CAEG;IAExB;;;OAGG;IACH,QAFU,YAAY,CAEO;CAChC"}

package/src/shade/renderer/geometry/virtual/build/level/VGeoGroupStep.js

@@ -0,0 +1,84 @@
+/**
+ * Everything one group step produced, before it is committed. Kept separate so that a round which
+ * fails to make progress can be discarded without having mutated the frontier.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class VGeoGroupStep {
+    /**
+     * The frontier clusters this group holds.
+     * @type {VirtualGeometryCluster[]}
+     */
+    child_clusters = [];
+
+    /**
+     * @type {VirtualGeometryCluster[]}
+     */
+    parent_clusters = [];
+
+    /**
+     * Parallel to {@link parent_clusters}: the geometry each parent was cut from, in terms of the
+     * frontier, so the next frontier can be stitched back together.
+     * @type {VGeoContribution[]}
+     */
+    parent_geometry = [];
+
+    /**
+     * The value both sides of this step store: the object-space distance from the *source* surface
+     * that this step's geometry now stands at, floored by what its children already carried.
+     * @type {number}
+     */
+    error = 0;
+
+    /**
+     * `frontier vertex id -> that vertex's quadric after this step`, for every vertex that survived
+     * it. Held rather than written straight back because a step is speculative until the round
+     * accepts it, and because two steps sharing a pinned boundary vertex must have their gains
+     * combined rather than one overwriting the other.
+     * @type {Map<number, Quadric3>}
+     */
+    quadrics = new Map();
+
+    /**
+     * Every attribute quadric this step's collapses left behind, indexed by the **wedge's** id
+     * *within the step's own submesh* at a stride of `quadric_attribute_size(components)`.
+     *
+     * One buffer rather than an entry per wedge: it is the array the simplifier was handed and
+     * finished with, kept whole. {@link attribute_source_wedge_ids} is what turns a position in it
+     * back into a frontier wedge, and {@link live_wedges} is what says which of them are still
+     * alive.
+     *
+     * Liveness cannot be read off {@link quadrics} the way it once was. A collapse can leave a
+     * victim's wedge standing — adopted by the survivor, carrying corners of its own — so a wedge
+     * outlives the vertex it started on, and the vertex map would have called it dead.
+     *
+     * The *results*, not the gains. `vgeo_build_levels` recovers the gain by subtracting what the
+     * frontier already held, because two steps sharing a pinned boundary vertex each began from that
+     * vertex's quadric and adding both results whole would count the source under it twice.
+     *
+     * Empty where the mesh carries no travelling channel at all.
+     * @type {Float64Array}
+     */
+    attribute_quadrics = new Float64Array(0);
+
+    /**
+     * For every wedge of this step's submesh, the frontier wedge it came from — which is what
+     * {@link attribute_quadrics} is read through.
+     * @type {Uint32Array}
+     */
+    attribute_source_wedge_ids = new Uint32Array(0);
+
+    /**
+     * Which of those wedges are still their own root, and so still stand for something. A wedge that
+     * merged into another gave that one its quadric and has nothing left to fold back.
+     * @type {Set<number>}
+     */
+    live_wedges = new Set();
+
+    /**
+     * The LOD-metric sphere both sides of this step store.
+     * @type {Float32Array}
+     */
+    sphere = new Float32Array(4);
+}

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

@@ -0,0 +1 @@
+{"version":3,"file":"VGeoLevel.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/geometry/virtual/build/level/VGeoLevel.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH;IACI;;;OAGG;IACH,OAFU,MAAM,CAEN;IAEV;;;OAGG;IACH,UAFU,wBAAwB,CAEpB;IAEd;;;;OAIG;IACH,QAFU,sBAAsB,CAEpB;CACf"}

package/src/shade/renderer/geometry/virtual/build/{VGeoLevelOptions.d.ts → level/VGeoLevelOptions.d.ts}

@@ -42,16 +42,29 @@ export class VGeoLevelOptions {
      * The octave alone offers no guarantee of progress: geometry whose error is spread thinly and
      * continuously — a UV sphere, whose poles carry triangles a fraction of the size of its
      * equator's — puts only a handful of clusters in any one octave, and the build inches forward a
-     * few merges per round. That is not merely slow, it is unbounded: `level_count` is a u8, and a
-     * round loop whose count scales with the cluster count rather than its logarithm will run out of
-     * levels on a real asset. Widening the band until it holds a fixed share of the frontier bounds
-     * the depth logarithmically, and costs error uniformity only where the octave had nothing.
+     * few merges per round. That is not merely slow, it is unbounded: a round loop whose count
+     * scales with the cluster count rather than its logarithm will run out of levels on a real
+     * asset, and has. Widening the band until it holds a fixed share of the frontier bounds the
+     * depth logarithmically, and costs error uniformity only where the octave had nothing.
      * @type {number}
      */
     error_band_min_fraction: number;
     /**
-     * Refuse to build past this many levels. `level_count` is a u8 in the container, and a build
-     * that has not converged by then has something else wrong with it.
+     * Refuse to build past this many levels.
+     *
+     * A sanity bound on the round loop and nothing more. It used to be 255 because `level_count`
+     * was a byte, which conflated two different questions and let the format answer the one it had
+     * no business answering: the 2026-09-14 Zorah conversion refused a three-million-triangle bush
+     * at exactly 255 with 39 clusters still unmerged, while the other 2,974 geometries of that scene
+     * — one of them 27 million triangles — converged by 149. The container now names up to {@link
+     * VGEO_MAX_LEVEL_COUNT} levels and this is free to be what it claims to be.
+     *
+     * 4,096: an order of magnitude past the deepest build ever measured here and an order of
+     * magnitude short of the format's ceiling. A round only continues while it is strictly shrinking
+     * the frontier, so this is not what stops a stalled build — {@link vgeo_run_round} returning
+     * nothing is. What it stops is a build that converges so slowly that finishing it would be
+     * worse than refusing it, and the DAG it would hand the runtime is one the cut pays for by
+     * depth on every frame.
      * @type {number}
      */
     max_levels: number;

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

@@ -0,0 +1 @@
+{"version":3,"file":"VGeoLevelOptions.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/geometry/virtual/build/level/VGeoLevelOptions.js"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH;IACI;;;;;OAKG;IACH,YAFU,MAAM,CAED;IAEf;;;;;;;;;;OAUG;IACH,sBAFU,MAAM,CAEW;IAE3B;;;;;;;;;;OAUG;IACH,mBAFU,MAAM,CAEM;IAEtB;;;;;;;;;;;OAWG;IACH,yBAFU,MAAM,CAEe;IAE/B;;;;;;;;;;;;;;;;;OAiBG;IACH,YAFU,MAAM,CAEE;CACrB"}

package/src/shade/renderer/geometry/virtual/build/{VGeoLevelOptions.js → level/VGeoLevelOptions.js}

@@ -45,18 +45,31 @@ export class VGeoLevelOptions {
      * The octave alone offers no guarantee of progress: geometry whose error is spread thinly and
      * continuously — a UV sphere, whose poles carry triangles a fraction of the size of its
      * equator's — puts only a handful of clusters in any one octave, and the build inches forward a
-     * few merges per round. That is not merely slow, it is unbounded: `level_count` is a u8, and a
-     * round loop whose count scales with the cluster count rather than its logarithm will run out of
-     * levels on a real asset. Widening the band until it holds a fixed share of the frontier bounds
-     * the depth logarithmically, and costs error uniformity only where the octave had nothing.
+     * few merges per round. That is not merely slow, it is unbounded: a round loop whose count
+     * scales with the cluster count rather than its logarithm will run out of levels on a real
+     * asset, and has. Widening the band until it holds a fixed share of the frontier bounds the
+     * depth logarithmically, and costs error uniformity only where the octave had nothing.
      * @type {number}
      */
     error_band_min_fraction = 0.25;
 
     /**
-     * Refuse to build past this many levels. `level_count` is a u8 in the container, and a build
-     * that has not converged by then has something else wrong with it.
+     * Refuse to build past this many levels.
+     *
+     * A sanity bound on the round loop and nothing more. It used to be 255 because `level_count`
+     * was a byte, which conflated two different questions and let the format answer the one it had
+     * no business answering: the 2026-09-14 Zorah conversion refused a three-million-triangle bush
+     * at exactly 255 with 39 clusters still unmerged, while the other 2,974 geometries of that scene
+     * — one of them 27 million triangles — converged by 149. The container now names up to {@link
+     * VGEO_MAX_LEVEL_COUNT} levels and this is free to be what it claims to be.
+     *
+     * 4,096: an order of magnitude past the deepest build ever measured here and an order of
+     * magnitude short of the format's ceiling. A round only continues while it is strictly shrinking
+     * the frontier, so this is not what stops a stalled build — {@link vgeo_run_round} returning
+     * nothing is. What it stops is a build that converges so slowly that finishing it would be
+     * worse than refusing it, and the DAG it would hand the runtime is one the cut pays for by
+     * depth on every frame.
      * @type {number}
      */
-    max_levels = 255;
+    max_levels = 4096;
 }

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

@@ -0,0 +1 @@
+{"version":3,"file":"VGeoLevelSummary.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/geometry/virtual/build/level/VGeoLevelSummary.js"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH;IACI,cAAU;IAEV;;;OAGG;IACH,eAFU,MAAM,CAEE;IAElB;;;OAGG;IACH,aAFU,MAAM,CAEA;IAEhB,uBAAmB;IACnB,qBAAiB;IAEjB;;;OAGG;IACH,WAFU,MAAM,CAEF;IAEd;;;;;OAKG;IACH,WAFU,MAAM,CAEF;IAEd;;;OAGG;IACH,mBAFU,MAAM,CAEM;CACzB"}

package/src/shade/renderer/geometry/virtual/build/level/vgeo_build_cluster.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Build a cluster out of a face set: gather it, bound it, encode its payload.
+ *
+ * @param {VirtualGeometryMesh} mesh
+ * @param {number[]} face_ids
+ * @param {number} level
+ * @param {BtWedgeSet} wedges which corners of each vertex shade as one — one output vertex each,
+ *     which is where a seam is paid for
+ * @returns {{cluster: VirtualGeometryCluster, gathered: VGeoGatheredFaces}}
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function vgeo_build_cluster(mesh: VirtualGeometryMesh, face_ids: number[], level: number, wedges: BtWedgeSet): {
+    cluster: VirtualGeometryCluster;
+    gathered: VGeoGatheredFaces;
+};
+import { VirtualGeometryCluster } from "../../format/dag/VirtualGeometryCluster.js";
+//# sourceMappingURL=vgeo_build_cluster.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"vgeo_build_cluster.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/geometry/virtual/build/level/vgeo_build_cluster.js"],"names":[],"mappings":"AAwCA;;;;;;;;;;;;GAYG;AACH,wEATW,MAAM,EAAE,SACR,MAAM,uBAGJ;IAAC,OAAO,EAAE,sBAAsB,CAAC;IAAC,QAAQ,oBAAmB;CAAC,CAS1E;uCAxDsC,4CAA4C"}

package/src/shade/renderer/geometry/virtual/build/level/vgeo_build_cluster.js

@@ -0,0 +1,58 @@
+import { aabb3_from_v3_array } from "../../../../../../core/geom/3d/aabb/aabb3_from_v3_array.js";
+import { VirtualGeometryCluster } from "../../format/dag/VirtualGeometryCluster.js";
+import { vgeo_encode_cluster_payload } from "../../format/payload/vgeo_encode_cluster_payload.js";
+import { vgeo_bounding_sphere } from "../sphere/vgeo_bounding_sphere.js";
+import { vgeo_gather_faces } from "../submesh/vgeo_gather_faces.js";
+import { vgeo_narrow_indices } from "../submesh/vgeo_narrow_indices.js";
+
+/**
+ * Encode a gathered face set into a cluster record.
+ *
+ * @param {VGeoGatheredFaces} gathered already within both meshlet caps
+ * @param {number} level
+ * @param {(BinaryDataLayer|null)[]} layers of the mesh it was gathered from
+ * @returns {VirtualGeometryCluster}
+ */
+function cluster_from_gathered(gathered, level, layers) {
+    const payload = vgeo_encode_cluster_payload(
+        gathered.positions,
+        vgeo_narrow_indices(gathered),
+        gathered.attribute_ids,
+        layers
+    );
+
+    const cluster = new VirtualGeometryCluster();
+
+    cluster.level = level;
+    cluster.vertex_count = gathered.vertex_ids.length;
+    cluster.triangle_count = gathered.indices.length / 3;
+    cluster.encoding_flags = payload.encoding_flags;
+    cluster.payload = payload.bytes;
+    cluster.bounds_sphere = vgeo_bounding_sphere(gathered.positions);
+
+    // the box needs no inflation, unlike the sphere above: the extremes are float32 values already,
+    // so min and max of them are exactly representable and the stored box contains the stored
+    // points by construction
+    aabb3_from_v3_array(cluster.aabb, gathered.positions, gathered.positions.length);
+
+    return cluster;
+}
+
+/**
+ * Build a cluster out of a face set: gather it, bound it, encode its payload.
+ *
+ * @param {VirtualGeometryMesh} mesh
+ * @param {number[]} face_ids
+ * @param {number} level
+ * @param {BtWedgeSet} wedges which corners of each vertex shade as one — one output vertex each,
+ *     which is where a seam is paid for
+ * @returns {{cluster: VirtualGeometryCluster, gathered: VGeoGatheredFaces}}
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function vgeo_build_cluster(mesh, face_ids, level, wedges) {
+    const gathered = vgeo_gather_faces(mesh, face_ids, wedges);
+
+    return { cluster: cluster_from_gathered(gathered, level, mesh.layers), gathered };
+}