@woosh/meep-engine 3.27.0 → 3.29.0

package/src/shade/renderer/geometry/virtual/build/mesh/vgeo_resolve_attribute_weights.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Turn the per-channel weight *ratios* an asset is built with into the per-component weights the
+ * simplifier's metric needs, against this mesh's own size.
+ *
+ * ## Why there is a weight at all
+ *
+ * An attribute quadric's gradient carries units of *attribute per length*, so what it evaluates to
+ * is dimensionless, while the geometric quadric beside it evaluates to a squared length. Summing
+ * those without saying how a unit of one compares with a unit of the other is meaningless — the
+ * answer would depend on nothing but the arbitrary range the channel happens to use. The weight is
+ * that statement: how many object-space units of position error a full unit of this channel is
+ * worth.
+ *
+ * ## Why it is a ratio
+ *
+ * For the same reason {@link VGeoBuildOptions#weld_ratio} is. A conversion is many geometries at
+ * many sizes, and a fixed distance that is right for a doorknob is wrong for a cathedral; a fraction
+ * of the geometry's own diagonal is right for both.
+ *
+ * **Resolve it once, off the source, before any pass has removed anything**, and hand the result
+ * down — every level of the DAG has to be built against the same statement, and the mesh shrinks as
+ * the build goes on.
+ *
+ * The result is indexed by *component of the attribute vector*, not by channel: a normal's three
+ * components share one ratio because they are one direction, and the simplifier wants the number
+ * beside the value it multiplies.
+ *
+ * @param {VirtualGeometryMesh} mesh
+ * @param {ArrayLike<number>} ratios one per {@link VGEO_ATTRIBUTES} entry; see
+ *     {@link VGeoBuildOptions#attribute_weight_ratios}
+ * @returns {Float64Array} one weight per component of {@link vgeo_attribute_vector_layout}'s vector;
+ *     empty where the mesh carries no travelling channel at all
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function vgeo_resolve_attribute_weights(mesh: VirtualGeometryMesh, ratios: ArrayLike<number>): Float64Array;
+//# sourceMappingURL=vgeo_resolve_attribute_weights.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"vgeo_resolve_attribute_weights.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/geometry/virtual/build/mesh/vgeo_resolve_attribute_weights.js"],"names":[],"mappings":"AAYA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,kFARW,UAAU,MAAM,CAAC,GAEf,YAAY,CAsCxB"}

package/src/shade/renderer/geometry/virtual/build/mesh/vgeo_resolve_attribute_weights.js

@@ -0,0 +1,81 @@
+import { assert } from "../../../../../../core/assert.js";
+import { AABB3 } from "../../../../../../core/geom/3d/aabb/AABB3.js";
+import {
+    bt_mesh_compute_bounding_box
+} from "../../../../../../core/geom/3d/topology/struct/binary/query/bt_mesh_compute_bounding_box.js";
+import { vgeo_attribute_vector_layout } from "./vgeo_attribute_vector_layout.js";
+
+/**
+ * @type {AABB3}
+ */
+const scratch_bounds = new AABB3();
+
+/**
+ * Turn the per-channel weight *ratios* an asset is built with into the per-component weights the
+ * simplifier's metric needs, against this mesh's own size.
+ *
+ * ## Why there is a weight at all
+ *
+ * An attribute quadric's gradient carries units of *attribute per length*, so what it evaluates to
+ * is dimensionless, while the geometric quadric beside it evaluates to a squared length. Summing
+ * those without saying how a unit of one compares with a unit of the other is meaningless — the
+ * answer would depend on nothing but the arbitrary range the channel happens to use. The weight is
+ * that statement: how many object-space units of position error a full unit of this channel is
+ * worth.
+ *
+ * ## Why it is a ratio
+ *
+ * For the same reason {@link VGeoBuildOptions#weld_ratio} is. A conversion is many geometries at
+ * many sizes, and a fixed distance that is right for a doorknob is wrong for a cathedral; a fraction
+ * of the geometry's own diagonal is right for both.
+ *
+ * **Resolve it once, off the source, before any pass has removed anything**, and hand the result
+ * down — every level of the DAG has to be built against the same statement, and the mesh shrinks as
+ * the build goes on.
+ *
+ * The result is indexed by *component of the attribute vector*, not by channel: a normal's three
+ * components share one ratio because they are one direction, and the simplifier wants the number
+ * beside the value it multiplies.
+ *
+ * @param {VirtualGeometryMesh} mesh
+ * @param {ArrayLike<number>} ratios one per {@link VGEO_ATTRIBUTES} entry; see
+ *     {@link VGeoBuildOptions#attribute_weight_ratios}
+ * @returns {Float64Array} one weight per component of {@link vgeo_attribute_vector_layout}'s vector;
+ *     empty where the mesh carries no travelling channel at all
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function vgeo_resolve_attribute_weights(mesh, ratios) {
+    const layout = vgeo_attribute_vector_layout(mesh.layers);
+
+    const result = new Float64Array(layout.components);
+
+    if (layout.components === 0) {
+        return result;
+    }
+
+    bt_mesh_compute_bounding_box(scratch_bounds, mesh.topology);
+
+    const diagonal = Math.hypot(
+        scratch_bounds.width, scratch_bounds.height, scratch_bounds.depth
+    );
+
+    assert.greaterThan(
+        diagonal, 0,
+        'the mesh has no extent for an attribute weight to be a fraction of: every vertex is one point'
+    );
+
+    for (const channel of layout.channels) {
+        const weight = ratios[channel.attribute] * diagonal;
+
+        // A weight of zero makes the channel's whole contribution vanish from the metric and then
+        // divides the fit by it, which reaches the asset as a silently infinite value rather than as
+        // a channel that does not matter.
+        assert.greaterThan(weight, 0, `weight of attribute ${channel.attribute}`);
+
+        result.fill(weight, channel.offset, channel.offset + channel.count);
+    }
+
+    return result;
+}

package/src/shade/renderer/geometry/virtual/build/{vgeo_assemble_pages.d.ts → page/vgeo_assemble_pages.d.ts}

@@ -9,5 +9,5 @@
  * @returns {VirtualGeometryPage[]} in file order, root page first
  */
 export function vgeo_assemble_pages(groups_by_level: VirtualGeometryGroup[][], object_bounds: Float32Array, nominal_page_size: number): VirtualGeometryPage[];
-import { VirtualGeometryPage } from "../format/dag/VirtualGeometryPage.js";
+import { VirtualGeometryPage } from "../../format/dag/VirtualGeometryPage.js";
 //# sourceMappingURL=vgeo_assemble_pages.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"vgeo_assemble_pages.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/geometry/virtual/build/page/vgeo_assemble_pages.js"],"names":[],"mappings":"AAwMA;;;;;;;;;GASG;AACH,qDAPW,sBAAsB,EAAE,iBAExB,YAAY,qBACZ,MAAM,GAEJ,mBAAmB,EAAE,CAiIjC;oCAzUmC,yCAAyC"}

package/src/shade/renderer/geometry/virtual/build/{vgeo_assemble_pages.js → page/vgeo_assemble_pages.js}

@@ -1,12 +1,12 @@
-import { assert } from "../../../../../core/assert.js";
-import { v3_morton_encode_bounded } from "../../../../../core/geom/3d/morton/v3_morton_encode_bounded.js";
-import { VGEO_CLUSTER_RECORD_SIZE } from "../format/cluster/VGEO_CLUSTER_RECORD_SIZE.js";
-import { VGEO_GROUP_RECORD_SIZE } from "../format/page/VGEO_GROUP_RECORD_SIZE.js";
-import { VGEO_NODE_RECORD_SIZE } from "../format/page/VGEO_NODE_RECORD_SIZE.js";
-import { VGEO_PAGE_HEADER_SIZE } from "../format/page/VGEO_PAGE_HEADER_SIZE.js";
-import { VGEO_PARENT_ENTRY_SIZE } from "../format/page/VGEO_PARENT_ENTRY_SIZE.js";
-import { VGEO_PARENT_PAGE_ENTRY_SIZE } from "../format/page/VGEO_PARENT_PAGE_ENTRY_SIZE.js";
-import { VirtualGeometryPage } from "../format/dag/VirtualGeometryPage.js";
+import { assert } from "../../../../../../core/assert.js";
+import { v3_morton_encode_bounded } from "../../../../../../core/geom/3d/morton/v3_morton_encode_bounded.js";
+import { VGEO_CLUSTER_RECORD_SIZE } from "../../format/cluster/VGEO_CLUSTER_RECORD_SIZE.js";
+import { VGEO_GROUP_RECORD_SIZE } from "../../format/page/VGEO_GROUP_RECORD_SIZE.js";
+import { VGEO_NODE_RECORD_SIZE } from "../../format/page/VGEO_NODE_RECORD_SIZE.js";
+import { VGEO_PAGE_HEADER_SIZE } from "../../format/page/VGEO_PAGE_HEADER_SIZE.js";
+import { VGEO_PARENT_ENTRY_SIZE } from "../../format/page/VGEO_PARENT_ENTRY_SIZE.js";
+import { VGEO_PARENT_PAGE_ENTRY_SIZE } from "../../format/page/VGEO_PARENT_PAGE_ENTRY_SIZE.js";
+import { VirtualGeometryPage } from "../../format/dag/VirtualGeometryPage.js";
 import { vgeo_build_page_nodes } from "./vgeo_build_page_nodes.js";
 import { vgeo_page_node_count } from "./vgeo_page_node_count.js";
 

package/src/shade/renderer/geometry/virtual/build/{vgeo_build_page_nodes.d.ts → page/vgeo_build_page_nodes.d.ts}

@@ -9,5 +9,5 @@
  * @returns {VirtualGeometryPageNode[]} the tree, root first; never empty
  */
 export function vgeo_build_page_nodes(page: VirtualGeometryPage): VirtualGeometryPageNode[];
-import { VirtualGeometryPageNode } from "../format/dag/VirtualGeometryPageNode.js";
+import { VirtualGeometryPageNode } from "../../format/dag/VirtualGeometryPageNode.js";
 //# sourceMappingURL=vgeo_build_page_nodes.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"vgeo_build_page_nodes.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/geometry/virtual/build/page/vgeo_build_page_nodes.js"],"names":[],"mappings":"AAsDA;;;;;;;;;GASG;AACH,kEAFa,uBAAuB,EAAE,CA8FrC;wCAvJuC,6CAA6C"}

package/src/shade/renderer/geometry/virtual/build/{vgeo_build_page_nodes.js → page/vgeo_build_page_nodes.js}

@@ -1,9 +1,9 @@
-import { assert } from "../../../../../core/assert.js";
+import { assert } from "../../../../../../core/assert.js";
 import {
     sphere_compute_bounding_of_2_spheres
-} from "../../../../../core/geom/3d/sphere/sphere_compute_bounding_of_2_spheres.js";
-import { VGEO_NODE_FANOUT } from "../format/page/VGEO_NODE_FANOUT.js";
-import { VirtualGeometryPageNode } from "../format/dag/VirtualGeometryPageNode.js";
+} from "../../../../../../core/geom/3d/sphere/sphere_compute_bounding_of_2_spheres.js";
+import { VGEO_NODE_FANOUT } from "../../format/page/VGEO_NODE_FANOUT.js";
+import { VirtualGeometryPageNode } from "../../format/dag/VirtualGeometryPageNode.js";
 
 /**
  * Build a page's group tree, and the page's own metric with it.

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

@@ -0,0 +1 @@
+{"version":3,"file":"vgeo_page_node_count.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/geometry/virtual/build/page/vgeo_page_node_count.js"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;GAeG;AAEH;;;GAGG;AACH,kDAHW,MAAM,GACJ,MAAM,CA8BlB"}

package/src/shade/renderer/geometry/virtual/build/{vgeo_page_node_count.js → page/vgeo_page_node_count.js}

@@ -1,5 +1,5 @@
-import { assert } from "../../../../../core/assert.js";
-import { VGEO_NODE_FANOUT } from "../format/page/VGEO_NODE_FANOUT.js";
+import { assert } from "../../../../../../core/assert.js";
+import { VGEO_NODE_FANOUT } from "../../format/page/VGEO_NODE_FANOUT.js";
 
 /**
  * How many nodes {@link vgeo_build_page_nodes} will put over a page holding `group_count` groups.

package/src/shade/renderer/geometry/virtual/build/{VGeoFaceGraph.d.ts → partition/VGeoFaceGraph.d.ts}

@@ -1,9 +1,17 @@
+/**
+ * A face-adjacency graph together with the mesh it came from, kept so that repeated splits over the
+ * same level do not rebuild it.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
 export class VGeoFaceGraph {
     /**
      * @param {BinaryTopology} mesh
      * @param {BinaryTopologyFaceGraph} face_graph
+     * @param {BtWedgeSet} wedges
      */
-    constructor(mesh: BinaryTopology, face_graph: BinaryTopologyFaceGraph);
+    constructor(mesh: BinaryTopology, face_graph: BinaryTopologyFaceGraph, wedges: BtWedgeSet);
     /**
      * @type {BinaryTopology}
      */
@@ -19,10 +27,15 @@ export class VGeoFaceGraph {
      */
     vertex_face_ids: Uint32Array;
     /**
-     * Scratch stamp for unique-vertex counting, one entry per mesh vertex slot.
+     * Which corners of each vertex shade as one, because that is what a cluster's vertices are.
+     * @type {BtWedgeSet}
+     */
+    wedges: BtWedgeSet;
+    /**
+     * Scratch stamp for unique-wedge counting, one entry per wedge id.
      * @type {Int32Array}
      */
-    vertex_stamp: Int32Array;
+    wedge_stamp: Int32Array;
     /**
      * Monotonic stamp value, so the scratch never needs clearing.
      * @type {number}
@@ -42,11 +55,16 @@ export class VGeoFaceGraph {
      */
     member_index: Uint32Array;
     /**
-     * How many distinct mesh vertices a set of dense face-graph vertices touches.
+     * How many distinct **wedges** a set of dense face-graph vertices touches.
+     *
+     * Wedges and not vertices, because the ceiling this feeds is the meshlet's vertex limit and a
+     * meshlet carries one record per wedge: two corners of a vertex that shade differently are two
+     * of its vertices. Counting the mesh's instead reads low at every crease and every chart
+     * boundary — measured, on a scene of separate hard-edged parts, at 240 against a cap of 128.
      *
      * @param {number[]|Int32Array} members dense face-graph vertices
      * @returns {number}
      */
-    count_unique_vertices(members: number[] | Int32Array): number;
+    count_unique_wedges(members: number[] | Int32Array): number;
 }
 //# sourceMappingURL=VGeoFaceGraph.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"VGeoFaceGraph.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/geometry/virtual/build/partition/VGeoFaceGraph.js"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH;IAkDI;;;;OAIG;IACH,2FAOC;IA7DD;;OAEG;IACH,qBAAY;IAEZ;;;OAGG;IACH,kBAAa;IAEb;;;OAGG;IACH,iBAFU,WAAW,CAEE;IAEvB;;;OAGG;IACH,mBAAc;IAEd;;;OAGG;IACH,aAFU,UAAU,CAED;IAEnB;;;OAGG;IACH,OAFU,MAAM,CAEN;IAEV;;;;;;;;;;;OAWG;IACH,cAFU,WAAW,CAED;IAgBpB;;;;;;;;;;OAUG;IACH,6BAHW,MAAM,EAAE,GAAC,UAAU,GACjB,MAAM,CA4BlB;CACJ"}

package/src/shade/renderer/geometry/virtual/build/{VGeoFaceGraph.js → partition/VGeoFaceGraph.js}

@@ -1,7 +1,3 @@
-import {
-    bt_face_read_triangle_vertices
-} from "../../../../../core/geom/3d/topology/struct/binary/query/bt_face_read_triangle.js";
-
 /**
  * A face-adjacency graph together with the mesh it came from, kept so that repeated splits over the
  * same level do not rebuild it.
@@ -9,9 +5,6 @@ import {
  * @author Alex Goldring
  * @copyright Company Named Limited (c) 2026
  */
-
-const scratch_triangle = new Uint32Array(3);
-
 export class VGeoFaceGraph {
     /**
      * @type {BinaryTopology}
@@ -31,10 +24,16 @@ export class VGeoFaceGraph {
     vertex_face_ids = null;
 
     /**
-     * Scratch stamp for unique-vertex counting, one entry per mesh vertex slot.
+     * Which corners of each vertex shade as one, because that is what a cluster's vertices are.
+     * @type {BtWedgeSet}
+     */
+    wedges = null;
+
+    /**
+     * Scratch stamp for unique-wedge counting, one entry per wedge id.
      * @type {Int32Array}
      */
-    vertex_stamp = null;
+    wedge_stamp = null;
 
     /**
      * Monotonic stamp value, so the scratch never needs clearing.
@@ -59,42 +58,50 @@ export class VGeoFaceGraph {
     /**
      * @param {BinaryTopology} mesh
      * @param {BinaryTopologyFaceGraph} face_graph
+     * @param {BtWedgeSet} wedges
      */
-    constructor(mesh, face_graph) {
+    constructor(mesh, face_graph, wedges) {
         this.mesh = mesh;
         this.graph = face_graph.graph;
         this.vertex_face_ids = face_graph.vertex_face_ids;
-        this.vertex_stamp = new Int32Array(mesh.vertices.size).fill(-1);
+        this.wedges = wedges;
+        this.wedge_stamp = new Int32Array(wedges.parent.length).fill(-1);
         this.member_index = new Uint32Array(face_graph.graph.vertex_count);
     }
 
     /**
-     * How many distinct mesh vertices a set of dense face-graph vertices touches.
+     * How many distinct **wedges** a set of dense face-graph vertices touches.
+     *
+     * Wedges and not vertices, because the ceiling this feeds is the meshlet's vertex limit and a
+     * meshlet carries one record per wedge: two corners of a vertex that shade differently are two
+     * of its vertices. Counting the mesh's instead reads low at every crease and every chart
+     * boundary — measured, on a scene of separate hard-edged parts, at 240 against a cap of 128.
      *
      * @param {number[]|Int32Array} members dense face-graph vertices
      * @returns {number}
      */
-    count_unique_vertices(members) {
+    count_unique_wedges(members) {
         const stamp = this.stamp++;
 
         let count = 0;
 
         const vertex_face_ids = this.vertex_face_ids;
         const mesh = this.mesh;
-        const vertex_stamp = this.vertex_stamp;
+        const wedges = this.wedges;
+        const wedge_stamp = this.wedge_stamp;
 
         for (const member of members) {
+            let loop = mesh.face_read_loop(vertex_face_ids[member]);
 
-            const face = vertex_face_ids[member];
-            bt_face_read_triangle_vertices(scratch_triangle, mesh, face);
+            for (let corner = 0; corner < 3; corner++) {
+                const wedge = wedges.find(wedges.of_loop[loop]);
 
-            for (let i = 0; i < 3; i++) {
-                const vertex = scratch_triangle[i];
-
-                if (vertex_stamp[vertex] !== stamp) {
-                    vertex_stamp[vertex] = stamp;
+                if (wedge_stamp[wedge] !== stamp) {
+                    wedge_stamp[wedge] = stamp;
                     count++;
                 }
+
+                loop = mesh.loop_read_next(loop);
             }
         }
 

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

@@ -0,0 +1 @@
+{"version":3,"file":"vgeo_graph_components.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/geometry/virtual/build/partition/vgeo_graph_components.js"],"names":[],"mappings":"AA6CA;;;;;;;;;;;GAWG;AACH,sDARW,WAAW,aACX,WAAW,WACX,MAAM,EAAE,cACR,UAAU,SAEV,MAAM,GACJ,MAAM,EAAE,EAAE,CAmEtB"}

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

@@ -0,0 +1 @@
+{"version":3,"file":"vgeo_partition_graph.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/geometry/virtual/build/partition/vgeo_partition_graph.js"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;GAiBG;AAEH;;;;;;;;GAQG;AACH,mDARW,MAAM,mBACN,MAAM,kBACN,WAAW,aACX,WAAW,gBACX,YAAY,QACZ,MAAM,GACJ,WAAW,CA0BvB"}

package/src/shade/renderer/geometry/virtual/build/{vgeo_partition_graph.js → partition/vgeo_partition_graph.js}

@@ -1,5 +1,5 @@
-import { graph_partition_spectral } from "../../../../../core/graph/graph_partition_spectral.js";
-import { metis_partition_kway } from "../../../../../core/graph/metis/native/metis_partition_kway.js";
+import { graph_partition_spectral } from "../../../../../../core/graph/graph_partition_spectral.js";
+import { metis_partition_kway } from "../../../../../../core/graph/metis/native/metis_partition_kway.js";
 
 /**
  * Partition a graph, and keep the build alive if the partitioner cannot.

package/src/shade/renderer/geometry/virtual/build/partition/vgeo_partition_subgraph.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Partition the subgraph a CSR induces on a member set.
+ *
+ * Both places the builder partitions something want this, and for the same reason the components
+ * pass beside it exists: METIS takes a graph, not a graph and a mask, so the members have to be
+ * renumbered into a dense local graph first and the assignment scattered back afterwards. That is
+ * forty lines of the same bookkeeping either side of one call, and it was written twice — once for
+ * splitting faces into clusters, once for grouping clusters into groups.
+ *
+ * The two copies had already drifted on the point one of them documents at length: the face side
+ * keeps a dense `Uint32Array` scratch because a `Map` cannot answer this at all past 2^24 entries
+ * and the leaf cut runs over every face of the mesh at once, while the cluster side had reached for
+ * a `Map`. Taking the scratch as a parameter is what makes that a property of this function rather
+ * than of whoever last copied it.
+ *
+ * Edge weights are carried through unchanged; a caller that wants them shaped — the group pass
+ * scales by compactness — does that when it builds the CSR.
+ *
+ * @param {{edge_addresses: Uint32Array, adjacency: Uint32Array, edge_weights: Float32Array}} graph
+ *     CSR over the whole vertex set
+ * @param {number[]} members vertices of the subgraph to partition
+ * @param {Int32Array} membership one entry per graph vertex; an entry equal to `token` marks a
+ *     member, which is what keeps a nested split from following an edge that leaves its subset
+ * @param {number} token
+ * @param {number} part_count at least 2
+ * @param {number} seed fixed by the caller, so the same subgraph always splits the same way
+ * @param {Uint32Array} local_index scratch, one entry per graph vertex. Only the members' entries
+ *     are written or read, so it never needs clearing between calls
+ * @returns {number[][]} the non-empty parts, in part order. **May be a single part** — METIS
+ *     balances what it is asked for but is not obliged to fill every bin, and a caller that needs
+ *     to make progress has to say what it does about that
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function vgeo_partition_subgraph(graph: {
+    edge_addresses: Uint32Array;
+    adjacency: Uint32Array;
+    edge_weights: Float32Array;
+}, members: number[], membership: Int32Array, token: number, part_count: number, seed: number, local_index: Uint32Array): number[][];
+//# sourceMappingURL=vgeo_partition_subgraph.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"vgeo_partition_subgraph.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/geometry/virtual/build/partition/vgeo_partition_subgraph.js"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,+CAjBW;IAAC,cAAc,EAAE,WAAW,CAAC;IAAC,SAAS,EAAE,WAAW,CAAC;IAAC,YAAY,EAAE,YAAY,CAAA;CAAC,WAEjF,MAAM,EAAE,cACR,UAAU,SAEV,MAAM,cACN,MAAM,QACN,MAAM,eACN,WAAW,GAET,MAAM,EAAE,EAAE,CA4DtB"}

package/src/shade/renderer/geometry/virtual/build/partition/vgeo_partition_subgraph.js

@@ -0,0 +1,92 @@
+import { assert } from "../../../../../../core/assert.js";
+import { vgeo_partition_graph } from "./vgeo_partition_graph.js";
+
+/**
+ * Partition the subgraph a CSR induces on a member set.
+ *
+ * Both places the builder partitions something want this, and for the same reason the components
+ * pass beside it exists: METIS takes a graph, not a graph and a mask, so the members have to be
+ * renumbered into a dense local graph first and the assignment scattered back afterwards. That is
+ * forty lines of the same bookkeeping either side of one call, and it was written twice — once for
+ * splitting faces into clusters, once for grouping clusters into groups.
+ *
+ * The two copies had already drifted on the point one of them documents at length: the face side
+ * keeps a dense `Uint32Array` scratch because a `Map` cannot answer this at all past 2^24 entries
+ * and the leaf cut runs over every face of the mesh at once, while the cluster side had reached for
+ * a `Map`. Taking the scratch as a parameter is what makes that a property of this function rather
+ * than of whoever last copied it.
+ *
+ * Edge weights are carried through unchanged; a caller that wants them shaped — the group pass
+ * scales by compactness — does that when it builds the CSR.
+ *
+ * @param {{edge_addresses: Uint32Array, adjacency: Uint32Array, edge_weights: Float32Array}} graph
+ *     CSR over the whole vertex set
+ * @param {number[]} members vertices of the subgraph to partition
+ * @param {Int32Array} membership one entry per graph vertex; an entry equal to `token` marks a
+ *     member, which is what keeps a nested split from following an edge that leaves its subset
+ * @param {number} token
+ * @param {number} part_count at least 2
+ * @param {number} seed fixed by the caller, so the same subgraph always splits the same way
+ * @param {Uint32Array} local_index scratch, one entry per graph vertex. Only the members' entries
+ *     are written or read, so it never needs clearing between calls
+ * @returns {number[][]} the non-empty parts, in part order. **May be a single part** — METIS
+ *     balances what it is asked for but is not obliged to fill every bin, and a caller that needs
+ *     to make progress has to say what it does about that
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function vgeo_partition_subgraph(
+    graph, members, membership, token, part_count, seed, local_index
+) {
+    assert.greaterThanOrEqual(part_count, 2, 'part_count');
+    assert.greaterThanOrEqual(local_index.length, membership.length, 'local_index.length');
+
+    const edge_addresses = graph.edge_addresses;
+    const adjacency = graph.adjacency;
+    const edge_weights = graph.edge_weights;
+
+    members.forEach((member, index) => { local_index[member] = index; });
+
+    const local_addresses = new Uint32Array(members.length + 1);
+    const local_adjacency = [];
+    const local_weights = [];
+
+    members.forEach((member, index) => {
+        local_addresses[index] = local_adjacency.length;
+
+        for (let i = edge_addresses[member]; i < edge_addresses[member + 1]; i++) {
+            const other = adjacency[i];
+
+            if (membership[other] !== token) {
+                continue;
+            }
+
+            local_adjacency.push(local_index[other]);
+            local_weights.push(edge_weights[i]);
+        }
+    });
+
+    local_addresses[members.length] = local_adjacency.length;
+
+    const assignment = vgeo_partition_graph(
+        members.length,
+        part_count,
+        local_addresses,
+        Uint32Array.from(local_adjacency),
+        Float32Array.from(local_weights),
+        seed
+    );
+
+    const parts = [];
+
+    for (let i = 0; i < part_count; i++) {
+        parts.push([]);
+    }
+
+    members.forEach((member, index) => {
+        parts[assignment[index]].push(member);
+    });
+
+    return parts.filter((part) => part.length > 0);
+}

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

@@ -0,0 +1 @@
+{"version":3,"file":"vgeo_split_face_set.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/geometry/virtual/build/partition/vgeo_split_face_set.js"],"names":[],"mappings":"AA6EA;;;;;;;GAOG;AACH,wEANW,MAAM,EAAE,aACR,MAAM,gBACN,MAAM,GACJ,MAAM,EAAE,EAAE,CA6DtB"}

package/src/shade/renderer/geometry/virtual/build/{vgeo_split_face_set.js → partition/vgeo_split_face_set.js}

@@ -1,6 +1,6 @@
-import { assert } from "../../../../../core/assert.js";
+import { assert } from "../../../../../../core/assert.js";
 import { vgeo_graph_components } from "./vgeo_graph_components.js";
-import { vgeo_partition_graph } from "./vgeo_partition_graph.js";
+import { vgeo_partition_subgraph } from "./vgeo_partition_subgraph.js";
 
 /**
  * Cut a set of faces into clusters that each satisfy Shade's meshlet limits.
@@ -42,6 +42,9 @@ const SPLIT_SEED = 0xC10D;
  * what keeps clusters well filled: METIS balances what it is asked for, so `ceil(n / 128)` parts land
  * near the ceiling, while a chain of bisections lands wherever the powers of two happen to fall.
  *
+ * What this adds to {@link vgeo_partition_subgraph} is the fallback, and only this caller needs it:
+ * the recursion here has to shrink its input every time or it does not terminate.
+ *
  * @param {VGeoFaceGraph} face_graph
  * @param {number[]} members
  * @param {Int32Array} membership one entry per graph vertex; an entry equal to `token` marks a member
@@ -50,62 +53,16 @@ const SPLIT_SEED = 0xC10D;
  * @returns {number[][]} non-empty parts; at least two of them
  */
 function partition(face_graph, members, membership, token, part_count) {
-    const graph = face_graph.graph;
-
-    const edge_addresses = graph.edge_addresses;
-    const adjacency = graph.adjacency;
-    const edge_weights = graph.edge_weights;
-
-    /**
-     * `local_index[global] = position in members`, valid only for members.
-     * @type {Uint32Array}
-     */
-    const local_index = face_graph.member_index;
-
-    members.forEach((member, index) => { local_index[member] = index; });
-
-    const local_addresses = new Uint32Array(members.length + 1);
-    const local_adjacency = [];
-    const local_weights = [];
-
-    members.forEach((member, index) => {
-        local_addresses[index] = local_adjacency.length;
-
-        for (let i = edge_addresses[member]; i < edge_addresses[member + 1]; i++) {
-            const other = adjacency[i];
-
-            if (membership[other] !== token) {
-                continue;
-            }
-
-            local_adjacency.push(local_index[other]);
-            local_weights.push(edge_weights[i]);
-        }
-    });
-
-    local_addresses[members.length] = local_adjacency.length;
-
-    const assignment = vgeo_partition_graph(
-        members.length,
+    const populated = vgeo_partition_subgraph(
+        face_graph.graph,
+        members,
+        membership,
+        token,
         part_count,
-        local_addresses,
-        Uint32Array.from(local_adjacency),
-        Float32Array.from(local_weights),
-        SPLIT_SEED
+        SPLIT_SEED,
+        face_graph.member_index
     );
 
-    const parts = [];
-
-    for (let i = 0; i < part_count; i++) {
-        parts.push([]);
-    }
-
-    members.forEach((member, index) => {
-        parts[assignment[index]].push(member);
-    });
-
-    const populated = parts.filter((part) => part.length > 0);
-
     if (populated.length >= 2) {
         return populated;
     }
@@ -158,7 +115,7 @@ export function vgeo_split_face_set(face_graph, members, max_faces, max_vertices
         for (const component of components) {
             if (
                 component.length <= max_faces
-                && face_graph.count_unique_vertices(component) <= max_vertices
+                && face_graph.count_unique_wedges(component) <= max_vertices
             ) {
                 result.push(component);
 

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

@@ -0,0 +1 @@
+{"version":3,"file":"vgeo_split_face_set_packed.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/geometry/virtual/build/partition/vgeo_split_face_set_packed.js"],"names":[],"mappings":"AAmVA;;;;;;;;;;;;GAYG;AACH,+EALW,MAAM,EAAE,aACR,MAAM,gBACN,MAAM,GACJ,MAAM,EAAE,EAAE,CAoBtB"}