@woosh/meep-engine 3.26.0 → 3.28.0

package/src/shade/renderer/geometry/virtual/VIRTUAL_GEOMETRY_PLAN.md

@@ -33,7 +33,7 @@ accepted-and-waiting one.
 - **Cluster-count simplification target** `[M §2.2]`, and a minimum cluster fill through the
   generalized leaf repack `[V §3.3]`.
 - **Compactness-weighted cluster adjacency** `[M §2.3]` — `compactness()` in
-  `build/vgeo_build_levels.js`.
+  `build/level/vgeo_build_levels.js`.
 - **Speculative groups, rejected individually** `[M §2.4]`.
 - **Per-level summary table in the file head** `[V §4.1, §6.1]` — VGEO_FORMAT §4.1.
 - **A traversal metric on the page DAG, and a group tree inside each page** `[V §2.1, §6.3]` —
@@ -72,12 +72,13 @@ accepted-and-waiting one.
   362 non-root groups have split parents: 355 of 576 camera positions double-drew, up to 10.7%
   of drawn triangles, before. Zero after. It reads as corrupt geometry rather than as a missing
   page, which is why the tool that found it could not name it.
-- **A CPU cut against a partially resident container** — `playground/vgeo_viewer/`.
-  `select_cut.js` is the runtime's rule rather than a debug approximation of it; the viewer is
-  what makes clamping, streaming and eviction watchable, and `__state()` is what makes it
-  assertable from a headless browser. It draws through Shade's direct geometry path, not the
-  meshlet pipeline — so it proves the DAG and the format, and proves nothing about the engine
-  seam.
+- **A CPU cut against a partially resident container** —
+  `runtime/cut/__fixtures__/vgeo_select_cut.js`. It is the runtime's rule rather than a debug
+  approximation of it, and `vgeo_select_cut.spec.js` holds it to the format's guarantees. A
+  `vgeo_viewer` playground used to draw it on screen through Shade's direct geometry path, which is
+  what made clamping, streaming and eviction watchable; once `playground/vgeo_runtime/` could show
+  all of that through the meshlet pipeline, the page was a second renderer and a second streaming
+  loop for no gain, and it was retired. The traversal stayed, because it is the oracle.
 
 - **The GPU runtime** — `runtime/`, and [runtime/RUNTIME_PLAN.md](./runtime/RUNTIME_PLAN.md) for the
   design and the adversarial review that reshaped it. The cut is a wavefront BFS over the page DAG
@@ -95,7 +96,7 @@ accepted-and-waiting one.
     evaluator does not. §6 states the fact without stating it as a term of the rule, because §4 was
     written for a traversal.
   - **Page size decides whether that state is even reachable.** At the 8 KB pages
-    `select_cut.spec.js` uses, a torus puts exactly one group in every page — so a blocked group is
+    `vgeo_select_cut.spec.js` uses, a torus puts exactly one group in every page — so a blocked group is
     a blocked page, no page is ever mixed, and no page is ever entered twice. Measured: 40 pages
     withheld one at a time and 60 random residency subsets produced *no* mixed page. At 64 KB the
     median page holds eight groups and it is ordinary. A spec for anything about mixed selectability
@@ -120,7 +121,7 @@ prefetch.
 ### 2.1 A partitioning fallback for when METIS fails `[M §3.3]`, `[V §3.2]` — LANDED
 
 `core/graph/graph_partition_spectral.js` — recursive spectral bisection over CSR, matrix-free,
-signature-compatible with `metis_partition_kway`. `build/vgeo_partition_graph.js` tries METIS
+signature-compatible with `metis_partition_kway`. `build/partition/vgeo_partition_graph.js` tries METIS
 and falls back to it; both of the builder's partitioning sites go through that wrapper.
 
 Notes worth keeping:
@@ -212,7 +213,7 @@ installed page can be re-tested without walking back to its parent.
 width at the top. This one has *no* paging question by construction: it is inside a page, it
 ships and evicts with it, and it cannot dangle.
 
-Both landed together; VGEO_FORMAT §6.1–6.2 specifies them, `build/vgeo_build_page_nodes.js`
+Both landed together; VGEO_FORMAT §6.1–6.2 specifies them, `build/page/vgeo_build_page_nodes.js`
 builds them. Notes worth keeping:
 
 - The tree needs no partitioner. A page's groups arrive in Morton order of their centroid, so
@@ -243,7 +244,7 @@ for the first few bands, which are also the cheapest to walk.
 LOD-metric sphere and error range (VGEO_FORMAT §5, §6.2), and every page carries a fanout-4 tree
 over its own groups (§6.1). The writer emits them, `vgeo_validate_container` checks them
 (§11.10–11.11) with corruption tests behind both checks, and **nothing reads either**.
-`VGeoPage` records `node_count` and stops; `select_cut.js` descends group by group.
+`VGeoPage` records `node_count` and stops; `vgeo_select_cut` descends group by group.
 
 This is not a defect to fix on its own account. Building a consumer for its own sake would fix
 the interface before the pass that has to live with it, and the CPU traversal does not need the
@@ -339,9 +340,11 @@ several cuts per frame for exactly this reason.
 
 So the plan is **a cut per view**, with the setup shared rather than the result: the traversal
 kernel, the residency state, and the page working set are all view-independent, and only the
-projection and threshold differ. And where a view does not justify a cut at all — a distant
-cascade, a low-resolution reflection — it should be able to take a proxy (§3.2) instead. That
-choice belongs to the view, not to the geometry.
+projection and threshold differ. That half is built — a cut runs per expansion site per view, and
+what it costs is measured in CUT_PLAN_2026_09_14 §0, which also plans to keep each view's cut
+between frames rather than re-walking it from the root. And where a view does not justify a cut
+at all — a distant cascade, a low-resolution reflection — it should be able to take a proxy
+(§3.2) instead. That choice belongs to the view, not to the geometry.
 
 ### 3.4 GPU-driven allocation `[V §4.3]`
 

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

@@ -17,6 +17,24 @@ export class VGeoBuildOptions {
      * @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;
     /**
      * How close two source vertices have to be to count as one point, as a fraction of the
      * geometry's own bounding-box diagonal. **Leave it alone.** It is the one knob here that can
@@ -68,5 +86,5 @@ export class VGeoBuildOptions {
      */
     level_options: VGeoLevelOptions;
 }
-import { VGeoLevelOptions } from "./VGeoLevelOptions.js";
+import { VGeoLevelOptions } from "./level/VGeoLevelOptions.js";
 //# sourceMappingURL=VGeoBuildOptions.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"VGeoBuildOptions.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/geometry/virtual/build/VGeoBuildOptions.js"],"names":[],"mappings":"AAIA;;;;;GAKG;AACH;IACI;;;;;;;;;;OAUG;IACH,OAFU,MAAM,CAEO;IAEvB;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA4BG;IACH,YAFU,MAAM,CAEE;IAElB;;;;;;;;;;;;;;OAcG;IACH,mBAFU,MAAM,CAE2B;IAE3C;;OAEG;IACH,eAFU,gBAAgB,CAEa;CAC1C;iCA1EgC,uBAAuB"}
+{"version":3,"file":"VGeoBuildOptions.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/geometry/virtual/build/VGeoBuildOptions.js"],"names":[],"mappings":"AAKA;;;;;GAKG;AACH;IACI;;;;;;;;;;OAUG;IACH,OAFU,MAAM,CAEO;IAEvB;;;;;;;;;;;;;;;;OAgBG;IACH,aAFU,MAAM,CAEmB;IAEnC;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA4BG;IACH,YAFU,MAAM,CAEE;IAElB;;;;;;;;;;;;;;OAcG;IACH,mBAFU,MAAM,CAE2B;IAE3C;;OAEG;IACH,eAFU,gBAAgB,CAEa;CAC1C;iCA7FgC,6BAA6B"}

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

@@ -1,6 +1,7 @@
+import { LZ4_LEVEL } from "../../../../../core/binary/lz4/LZ4_LEVEL.js";
 import { VGEO_CODEC_LZ4 } from "../format/frame/VGEO_CODEC_LZ4.js";
 import { VGEO_DEFAULT_PAGE_SIZE } from "../format/page/VGEO_DEFAULT_PAGE_SIZE.js";
-import { VGeoLevelOptions } from "./VGeoLevelOptions.js";
+import { VGeoLevelOptions } from "./level/VGeoLevelOptions.js";
 
 /**
  * Knobs the builder pipeline exposes.
@@ -22,6 +23,25 @@ export class VGeoBuildOptions {
      */
     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;
+
     /**
      * How close two source vertices have to be to count as one point, as a fraction of the
      * geometry's own bounding-box diagonal. **Leave it alone.** It is the one knob here that can

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

@@ -1 +1 @@
-{"version":3,"file":"gltf_open_document.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/geometry/virtual/build/gltf/gltf_open_document.js"],"names":[],"mappings":"AA6EA;;;;;;;;;;GAUG;AACH,8CARW,cAAc,yBACL,MAAM,KAAG,cAAc,4CAK9B,YAAY,CA+ExB;+BA1J8B,qBAAqB;6BACvB,mBAAmB"}
+{"version":3,"file":"gltf_open_document.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/geometry/virtual/build/gltf/gltf_open_document.js"],"names":[],"mappings":"AAyEA;;;;;;;;;;GAUG;AACH,8CARW,cAAc,yBACL,MAAM,KAAG,cAAc,4CAK9B,YAAY,CA+ExB;+BArJ8B,qBAAqB;6BACvB,mBAAmB"}

package/src/shade/renderer/geometry/virtual/build/gltf/gltf_open_document.js

@@ -1,4 +1,5 @@
 import { assert } from "../../../../../../core/assert.js";
+import { Base64 } from "../../../../../../core/binary/base64/Base64.js";
 import {
     GLTF_BUFFER_VIEW_EXTENSIONS
 } from "../../../../../../format/scene/gltf/ext/gltf_buffer_view_extensions.js";
@@ -26,6 +27,9 @@ import { GltfDocument } from "./GltfDocument.js";
 /**
  * Decode a `data:` URI's payload.
  *
+ * Through {@link Base64} rather than `atob`: the decode is the engine's own, so the builder runs
+ * the same one everywhere and does not need a `atob` to exist on whatever it is running under.
+ *
  * @param {string} uri
  * @returns {Uint8Array}
  * @throws {Error} for an encoding other than base64, which is the only one glTF defines
@@ -39,15 +43,7 @@ function read_data_uri(uri) {
         throw new Error(`unsupported data URI encoding in '${header}'`);
     }
 
-    const binary = atob(uri.slice(comma + 1));
-
-    const result = new Uint8Array(binary.length);
-
-    for (let i = 0; i < binary.length; i++) {
-        result[i] = binary.charCodeAt(i);
-    }
-
-    return result;
+    return new Uint8Array(Base64.decode(uri.slice(comma + 1)));
 }
 
 /**

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

@@ -0,0 +1,32 @@
+/**
+ * One band of the DAG.
+ *
+ * A level is an ordinal, not a generation: `clusters` are the clusters the round of that index
+ * created, while `groups` are the groups the round *above* consumed — and those groups may hold
+ * clusters from any level at or below their own, because a cluster no round could use waits in the
+ * frontier until one can. What the ordinal guarantees is the only thing the format needs from it:
+ * every group sits strictly below the group holding its parents, so laying pages out by descending
+ * level makes every child reference point forward in the file.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class VGeoLevel {
+    /**
+     * `0` = leaves.
+     * @type {number}
+     */
+    index: number;
+    /**
+     * The clusters this level's round created.
+     * @type {VirtualGeometryCluster[]}
+     */
+    clusters: VirtualGeometryCluster[];
+    /**
+     * The groups that sit in this level's band — the ones the round above consumed. Empty for the
+     * top level until the caller assigns its root group.
+     * @type {VirtualGeometryGroup[]}
+     */
+    groups: VirtualGeometryGroup[];
+}
+//# sourceMappingURL=VGeoLevel.d.ts.map

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/level/VGeoLevelOptions.d.ts

@@ -0,0 +1,59 @@
+/**
+ * How the round loop of {@link vgeo_build_levels} is allowed to behave.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class VGeoLevelOptions {
+    /**
+     * Clusters a group starts out holding. Grows when a round fails to make progress — small groups
+     * starve the simplifier (the locked perimeter dominates), large ones lock a big spatial
+     * footprint into LOD lockstep.
+     * @type {number}
+     */
+    group_size: number;
+    /**
+     * Fraction of a group's *clusters* the step above it should come to. The design's halving,
+     * stated as the thing the DAG is actually for.
+     *
+     * A triangle ratio is a means and this is the end, and asking directly is what keeps parents
+     * full: the simplifier is given the triangle count that many clusters hold, rather than half of
+     * whatever the children happened to contain. Where the children are already full the two are the
+     * same number. Where they are not, this asks for less destruction, because the reduction is
+     * available from packing the geometry better instead.
+     * @type {number}
+     */
+    simplification_ratio: number;
+    /**
+     * How much error a single round is allowed to span, as a multiple of the band's floor. `1` would
+     * admit only the exact minimum and turn every distinct error value into its own round; a large
+     * value admits the whole frontier every time and is the level sweep this replaced.
+     *
+     * Four, measured. On a 98k-triangle sphere against a full sweep: 31% fewer clusters merged into
+     * groups more than twice as coarse as themselves, and 8% fewer at four times, for one extra
+     * level. Two is tighter on the first count — 41% fewer — but costs fourteen levels, and every
+     * level is a page band and a dependent fetch on the way down.
+     * @type {number}
+     */
+    error_band_growth: number;
+    /**
+     * Least share of the frontier a round is allowed to work on, whatever the octave says.
+     *
+     * 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.
+     * @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.
+     * @type {number}
+     */
+    max_levels: number;
+}
+//# sourceMappingURL=VGeoLevelOptions.d.ts.map

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;;;;OAIG;IACH,YAFU,MAAM,CAEC;CACpB"}

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

@@ -0,0 +1,44 @@
+/**
+ * What one band of the DAG came to.
+ *
+ * The counts are not a frontier size and do not have to fall monotonically: `cluster_count` is what
+ * the round of this index *created*, and a round merges a band of comparable error rather than the
+ * whole frontier, so a later round can produce fewer clusters than an earlier one — or more, when it
+ * finally reaches geometry that had been waiting.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class VGeoLevelSummary {
+    level: number;
+    /**
+     * Clusters the round of this index created.
+     * @type {number}
+     */
+    cluster_count: number;
+    /**
+     * Groups sitting in this band — the ones the round above consumed.
+     * @type {number}
+     */
+    group_count: number;
+    triangle_count: number;
+    vertex_count: number;
+    /**
+     * Smallest object-space `r_e` any cluster of this level carries.
+     * @type {number}
+     */
+    min_error: number;
+    /**
+     * Largest object-space `r_e` any cluster of this level carries. The root's is the ceiling for
+     * the whole asset; between two levels there is no ordering, for the same reason the counts have
+     * none.
+     * @type {number}
+     */
+    max_error: number;
+    /**
+     * Largest LOD-metric sphere radius at this level.
+     * @type {number}
+     */
+    max_sphere_radius: number;
+}
+//# sourceMappingURL=VGeoLevelSummary.d.ts.map

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_levels.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Build the whole DAG, from a source mesh to a single root.
+ *
+ * @param {VirtualGeometryMesh} mesh the normalized source; consumed, not copied
+ * @param {VGeoLevelOptions} options
+ * @returns {VGeoLevel[]} leaves first; the last level holds exactly one cluster, the root
+ */
+export function vgeo_build_levels(mesh: VirtualGeometryMesh, options: VGeoLevelOptions): VGeoLevel[];
+/**
+ * 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.
+ */
+export type VGeoContribution = {
+    positions: Float32Array;
+    /**
+     * local to {@link positions }
+     */
+    indices: Uint32Array;
+    /**
+     * ids in the mesh {@link topology } belongs to
+     */
+    local_vertex_ids: Uint32Array;
+    /**
+     * the same vertices, named in the frontier's mesh
+     */
+    source_vertex_ids: Uint32Array;
+    /**
+     * the mesh {@link local_vertex_ids } name vertices of, whose
+     * vertex data block holds their attributes
+     */
+    topology: BinaryTopology;
+};
+import { VirtualGeometryMesh } from "../mesh/VirtualGeometryMesh.js";
+import { VGeoLevel } from "./VGeoLevel.js";
+import { BinaryTopology } from "../../../../../../core/geom/3d/topology/struct/binary/BinaryTopology.js";
+//# sourceMappingURL=vgeo_build_levels.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"vgeo_build_levels.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/geometry/virtual/build/level/vgeo_build_levels.js"],"names":[],"mappings":"AAqiDA;;;;;;GAMG;AACH,wCAJW,mBAAmB,8BAEjB,SAAS,EAAE,CA6KvB;;;;;;eAtgDa,YAAY;;;;aACZ,WAAW;;;;sBACX,WAAW;;;;uBACX,WAAW;;;;;cACX,cAAc;;oCA5KQ,gCAAgC;0BAD1C,gBAAgB;+BAjCI,yEAAyE"}

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

@@ -1,45 +1,45 @@
-import { assert } from "../../../../../core/assert.js";
-import { aabb3_from_v3_array } from "../../../../../core/geom/3d/aabb/aabb3_from_v3_array.js";
-import { v3_morton_encode_bounded } from "../../../../../core/geom/3d/morton/v3_morton_encode_bounded.js";
-import { Quadric3 } from "../../../../../core/geom/3d/quadric/Quadric3.js";
+import { assert } from "../../../../../../core/assert.js";
+import { aabb3_from_v3_array } from "../../../../../../core/geom/3d/aabb/aabb3_from_v3_array.js";
+import { v3_morton_encode_bounded } from "../../../../../../core/geom/3d/morton/v3_morton_encode_bounded.js";
+import { Quadric3 } from "../../../../../../core/geom/3d/quadric/Quadric3.js";
 import {
     sphere_compute_bounding_of_2_spheres
-} from "../../../../../core/geom/3d/sphere/sphere_compute_bounding_of_2_spheres.js";
-import { BinaryTopology, NULL_POINTER, } from "../../../../../core/geom/3d/topology/struct/binary/BinaryTopology.js";
+} from "../../../../../../core/geom/3d/sphere/sphere_compute_bounding_of_2_spheres.js";
+import { BinaryTopology, NULL_POINTER, } from "../../../../../../core/geom/3d/topology/struct/binary/BinaryTopology.js";
 import {
     bt_mesh_compute_vertex_quadrics
-} from "../../../../../core/geom/3d/topology/struct/binary/io/bt_mesh_compute_vertex_quadrics.js";
+} from "../../../../../../core/geom/3d/topology/struct/binary/io/bt_mesh_compute_vertex_quadrics.js";
 import {
     bt_mesh_from_indexed_geometry
-} from "../../../../../core/geom/3d/topology/struct/binary/io/bt_mesh_from_indexed_geometry.js";
+} from "../../../../../../core/geom/3d/topology/struct/binary/io/bt_mesh_from_indexed_geometry.js";
 import {
     bt_mesh_simplify_with_quadrics
-} from "../../../../../core/geom/3d/topology/struct/binary/io/bt_mesh_simplify.js";
-import { bt_edge_get } from "../../../../../core/geom/3d/topology/struct/binary/query/bt_edge_get.js";
-import { bt_mesh_validate } from "../../../../../core/geom/3d/topology/struct/binary/query/bt_mesh_validate.js";
-import { bt_mesh_build_face_graph } from "../../../../../core/graph/metis/bt_mesh_build_face_graph.js";
-import { vgeo_encode_cluster_payload } from "../format/payload/vgeo_encode_cluster_payload.js";
-import { vgeo_layers_copy_vertex } from "../format/attribute/vgeo_layers_copy_vertex.js";
-import { vgeo_layers_like } from "../format/attribute/vgeo_layers_like.js";
-import { VGEO_MAX_CLUSTER_TRIANGLE_COUNT } from "../format/cluster/VGEO_MAX_CLUSTER_TRIANGLE_COUNT.js";
-import { VGEO_MAX_CLUSTER_VERTEX_COUNT } from "../format/cluster/VGEO_MAX_CLUSTER_VERTEX_COUNT.js";
-import { VGEO_MAX_GROUP_CLUSTER_COUNT } from "../format/page/VGEO_MAX_GROUP_CLUSTER_COUNT.js";
-import { VirtualGeometryCluster } from "../format/dag/VirtualGeometryCluster.js";
-import { VirtualGeometryGroup } from "../format/dag/VirtualGeometryGroup.js";
-import { vgeo_bounding_sphere } from "./vgeo_bounding_sphere.js";
-import { vgeo_compute_vertex_normals } from "./vgeo_compute_vertex_normals.js";
-import { vgeo_compute_vertex_tangents } from "./vgeo_compute_vertex_tangents.js";
-import { vgeo_containing_sphere } from "./vgeo_containing_sphere.js";
-import { vgeo_extract_submesh } from "./vgeo_extract_submesh.js";
-import { vgeo_gather_faces } from "./vgeo_gather_faces.js";
-import { vgeo_graph_components } from "./vgeo_graph_components.js";
-import { vgeo_narrow_indices } from "./vgeo_narrow_indices.js";
-import { vgeo_partition_graph } from "./vgeo_partition_graph.js";
-import { vgeo_split_face_set } from "./vgeo_split_face_set.js";
-import { vgeo_split_face_set_packed } from "./vgeo_split_face_set_packed.js";
-import { VGeoFaceGraph } from "./VGeoFaceGraph.js";
+} from "../../../../../../core/geom/3d/topology/struct/binary/io/bt_mesh_simplify.js";
+import { bt_edge_get } from "../../../../../../core/geom/3d/topology/struct/binary/query/bt_edge_get.js";
+import { bt_mesh_validate } from "../../../../../../core/geom/3d/topology/struct/binary/query/bt_mesh_validate.js";
+import { bt_mesh_build_face_graph } from "../../../../../../core/graph/metis/bt_mesh_build_face_graph.js";
+import { vgeo_encode_cluster_payload } from "../../format/payload/vgeo_encode_cluster_payload.js";
+import { vgeo_layers_copy_vertex } from "../../format/attribute/vgeo_layers_copy_vertex.js";
+import { vgeo_layers_like } from "../../format/attribute/vgeo_layers_like.js";
+import { VGEO_MAX_CLUSTER_TRIANGLE_COUNT } from "../../format/cluster/VGEO_MAX_CLUSTER_TRIANGLE_COUNT.js";
+import { VGEO_MAX_CLUSTER_VERTEX_COUNT } from "../../format/cluster/VGEO_MAX_CLUSTER_VERTEX_COUNT.js";
+import { VGEO_MAX_GROUP_CLUSTER_COUNT } from "../../format/page/VGEO_MAX_GROUP_CLUSTER_COUNT.js";
+import { VirtualGeometryCluster } from "../../format/dag/VirtualGeometryCluster.js";
+import { VirtualGeometryGroup } from "../../format/dag/VirtualGeometryGroup.js";
+import { vgeo_bounding_sphere } from "../sphere/vgeo_bounding_sphere.js";
+import { vgeo_compute_vertex_normals } from "../mesh/vgeo_compute_vertex_normals.js";
+import { vgeo_compute_vertex_tangents } from "../mesh/vgeo_compute_vertex_tangents.js";
+import { vgeo_containing_sphere } from "../sphere/vgeo_containing_sphere.js";
+import { vgeo_extract_submesh } from "../submesh/vgeo_extract_submesh.js";
+import { vgeo_gather_faces } from "../submesh/vgeo_gather_faces.js";
+import { vgeo_graph_components } from "../partition/vgeo_graph_components.js";
+import { vgeo_narrow_indices } from "../submesh/vgeo_narrow_indices.js";
+import { vgeo_partition_subgraph } from "../partition/vgeo_partition_subgraph.js";
+import { vgeo_split_face_set } from "../partition/vgeo_split_face_set.js";
+import { vgeo_split_face_set_packed } from "../partition/vgeo_split_face_set_packed.js";
+import { VGeoFaceGraph } from "../partition/VGeoFaceGraph.js";
 import { VGeoLevel } from "./VGeoLevel.js";
-import { VirtualGeometryMesh } from "./VirtualGeometryMesh.js";
+import { VirtualGeometryMesh } from "../mesh/VirtualGeometryMesh.js";
 
 /**
  * Build the cluster DAG: leaves out of the source mesh, then merge steps until one cluster is left.
@@ -434,30 +434,32 @@ function bundle_loose_clusters(frontier, loose, group_size) {
         return [];
     }
 
-    const bounds = new Float32Array([
-        Number.POSITIVE_INFINITY, Number.POSITIVE_INFINITY, Number.POSITIVE_INFINITY,
-        Number.NEGATIVE_INFINITY, Number.NEGATIVE_INFINITY, Number.NEGATIVE_INFINITY,
-    ]);
+    // Gathered rather than read through the cluster list twice: the bounds and the codes are the
+    // same points, and this is the shape `vgeo_split_face_set_packed` already packs in.
+    const centres = new Float32Array(loose.length * 3);
 
-    for (const cluster of loose) {
-        const centre = frontier.clusters[cluster].bounds_sphere;
+    loose.forEach((cluster, index) => {
+        const sphere = frontier.clusters[cluster].bounds_sphere;
 
-        for (let axis = 0; axis < 3; axis++) {
-            bounds[axis] = Math.min(bounds[axis], centre[axis]);
-            bounds[axis + 3] = Math.max(bounds[axis + 3], centre[axis]);
-        }
-    }
+        centres[index * 3] = sphere[0];
+        centres[index * 3 + 1] = sphere[1];
+        centres[index * 3 + 2] = sphere[2];
+    });
+
+    const bounds = new Float32Array(6);
+
+    aabb3_from_v3_array(bounds, centres, centres.length);
 
     /**
      * @type {Map<number, number>}
      */
     const codes = new Map();
 
-    for (const cluster of loose) {
-        const centre = frontier.clusters[cluster].bounds_sphere;
-
-        codes.set(cluster, v3_morton_encode_bounded(centre[0], centre[1], centre[2], bounds));
-    }
+    loose.forEach((cluster, index) => {
+        codes.set(cluster, v3_morton_encode_bounded(
+            centres[index * 3], centres[index * 3 + 1], centres[index * 3 + 2], bounds
+        ));
+    });
 
     const order = loose.slice();
 
@@ -621,6 +623,14 @@ function absorb_singleton_pieces(pieces, cluster_graph) {
 function partition_into_groups(frontier, band, cluster_graph, group_size) {
     const membership = new Int32Array(frontier.clusters.length).fill(-1);
 
+    /**
+     * Dense rather than a `Map`, and hoisted out of the component loop so it is one allocation per
+     * level. See {@link vgeo_partition_subgraph} for why the density is load-bearing rather than a
+     * micro-optimisation.
+     * @type {Uint32Array}
+     */
+    const local_index = new Uint32Array(frontier.clusters.length);
+
     for (const cluster of band) {
         membership[cluster] = 0;
     }
@@ -692,55 +702,11 @@ function partition_into_groups(frontier, band, cluster_graph, group_size) {
             membership[cluster] = token;
         }
 
-        const local_index = new Map();
-
-        component.forEach((cluster, index) => local_index.set(cluster, index));
-
-        const local_addresses = new Uint32Array(component.length + 1);
-        const local_adjacency = [];
-        const local_weights = [];
-
-        component.forEach((cluster, index) => {
-            local_addresses[index] = local_adjacency.length;
-
-            for (let i = cluster_graph.edge_addresses[cluster]; i < cluster_graph.edge_addresses[cluster + 1]; i++) {
-                const other = cluster_graph.adjacency[i];
-
-                if (membership[other] !== token) {
-                    continue;
-                }
-
-                local_adjacency.push(local_index.get(other));
-                local_weights.push(cluster_graph.edge_weights[i]);
-            }
-        });
-
-        local_addresses[component.length] = local_adjacency.length;
-
-        const assignment = vgeo_partition_graph(
-            component.length,
-            part_count,
-            local_addresses,
-            Uint32Array.from(local_adjacency),
-            Float32Array.from(local_weights),
-            GROUP_SEED
+        const parts = vgeo_partition_subgraph(
+            cluster_graph, component, membership, token, part_count, GROUP_SEED, local_index
         );
 
-        const parts = [];
-
-        for (let i = 0; i < part_count; i++) {
-            parts.push([]);
-        }
-
-        component.forEach((cluster, index) => {
-            parts[assignment[index]].push(cluster);
-        });
-
         for (const part of parts) {
-            if (part.length === 0) {
-                continue;
-            }
-
             token++;
 
             for (const cluster of part) {

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

@@ -0,0 +1,19 @@
+/**
+ * The root cluster has no simplification step above it, so nothing grouped it, and the format still
+ * wants every cluster in exactly one group. It gets a group of its own: the always-selectable entry
+ * point the runtime starts its cut from.
+ *
+ * There is exactly one of these because the DAG has exactly one root — a build that ends with
+ * several parentless clusters has not finished, and bundling them into a synthetic group would only
+ * hide that (see `vgeo_build_levels`).
+ *
+ * @param {VirtualGeometryCluster} cluster the root
+ * @param {number} level
+ * @returns {VirtualGeometryGroup}
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function vgeo_build_root_group(cluster: VirtualGeometryCluster, level: number): VirtualGeometryGroup;
+import { VirtualGeometryGroup } from "../../format/dag/VirtualGeometryGroup.js";
+//# sourceMappingURL=vgeo_build_root_group.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"vgeo_build_root_group.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/geometry/virtual/build/level/vgeo_build_root_group.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;GAeG;AACH,8EANW,MAAM,GACJ,oBAAoB,CAYhC;qCAzBoC,0CAA0C"}

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

@@ -1,4 +1,4 @@
-import { VirtualGeometryGroup } from "../format/dag/VirtualGeometryGroup.js";
+import { VirtualGeometryGroup } from "../../format/dag/VirtualGeometryGroup.js";
 
 /**
  * The root cluster has no simplification step above it, so nothing grouped it, and the format still