@woosh/meep-engine 3.28.0 → 3.30.0

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

@@ -17,6 +17,14 @@ import { vgeo_split_face_set } from "./vgeo_split_face_set.js";
  * has already been chosen for proximity, so packing inside one cannot reach further than the group
  * does.
  *
+ * The merge is two passes, and the caps decide which one is used rather than taste. The first walks
+ * the curve, so every cluster it makes is a run of it holding pieces that were beside each other —
+ * and over a real asset that is almost always all it takes: across a build of the Zorah sample it
+ * lands on the fewest clusters both caps allow in 97.6% of the re-cuts. The second pass is for the
+ * rest. Where the curve costs a whole extra cluster, the pieces are offered again largest first,
+ * into whichever cluster still has room. Reaching past a neighbour widens what a cluster carries, so
+ * it has to buy something; one cluster fewer is the price at which it does.
+ *
  * @author Alex Goldring
  * @copyright Company Named Limited (c) 2026
  */
@@ -25,22 +33,30 @@ const scratch_triangle = new Uint32Array(3);
 const scratch_coordinate = new Float32Array(3);
 
 /**
- * The mesh vertices a set of dense face-graph vertices touches, deduplicated.
+ * The **wedges** a set of dense face-graph vertices touches, deduplicated.
+ *
+ * Wedges and not mesh vertices, because a bin is a meshlet and a meshlet carries one record per
+ * wedge — see {@link VGeoFaceGraph#count_unique_wedges}, which is the same question asked of a
+ * whole part rather than of a piece being packed into one. The set is kept rather than counted here
+ * because the packer needs to know how much two pieces *overlap*, not only how big each is.
  *
  * @param {VGeoFaceGraph} face_graph
  * @param {number[]} members
  * @returns {Set<number>}
  */
-function unique_vertices(face_graph, members) {
+function unique_wedges(face_graph, members) {
     const result = new Set();
 
+    const mesh = face_graph.mesh;
+    const wedges = face_graph.wedges;
+
     for (const member of members) {
-        bt_face_read_triangle_vertices(
-            scratch_triangle, face_graph.mesh, face_graph.vertex_face_ids[member]
-        );
+        let loop = mesh.face_read_loop(face_graph.vertex_face_ids[member]);
 
-        for (let i = 0; i < 3; i++) {
-            result.add(scratch_triangle[i]);
+        for (let corner = 0; corner < 3; corner++) {
+            result.add(wedges.find(wedges.of_loop[loop]));
+
+            loop = mesh.loop_read_next(loop);
         }
     }
 
@@ -84,26 +100,13 @@ function piece_centroid(result, result_offset, face_graph, members) {
 }
 
 /**
- * Merge under-filled pieces into shared clusters, walking them in Morton order so that whatever ends
- * up together was near each other to begin with.
- *
- * Next-fit rather than best-fit: the curve already put spatial neighbours side by side, and letting a
- * piece jump backwards to top up an earlier bin would pull distant geometry into it for the sake of
- * a few triangles of fill.
+ * The pieces in Morton order of their centroids, so that neighbours in it were neighbours in space.
  *
  * @param {VGeoFaceGraph} face_graph
- * @param {number[][]} pieces each already within both caps
- * @param {number} max_faces
- * @param {number} max_vertices
- * @returns {number[][]}
+ * @param {number[][]} pieces
+ * @returns {number[]} indices into `pieces`
  */
-function pack_pieces(face_graph, pieces, max_faces, max_vertices) {
-
-    if (pieces.length < 2) {
-        // nothing to merge, pass through
-        return pieces;
-    }
-
+function curve_order(face_graph, pieces) {
     const centroids = new Float32Array(pieces.length * 3);
 
     pieces.forEach((piece, index) => piece_centroid(centroids, index * 3, face_graph, piece));
@@ -125,61 +128,213 @@ function pack_pieces(face_graph, pieces, max_faces, max_vertices) {
 
     order.sort((a, b) => (codes[a] - codes[b]) || (pieces[a][0] - pieces[b][0]));
 
-    /**
-     *
-     * @type {number[][]}
-     */
+    return order;
+}
+
+/**
+ * A cluster under construction: which pieces are in it, and both of the numbers it is capped on.
+ *
+ * @param {number} index of the piece it starts from
+ * @param {number[]} piece
+ * @param {Set<number>} vertices the piece touches
+ * @returns {{pieces: number[], faces: number, vertices: Set<number>}}
+ */
+function open_bin(index, piece, vertices) {
+    return { pieces: [index], faces: piece.length, vertices: new Set(vertices) };
+}
+
+/**
+ * Whether a piece can go into a bin without breaking either cap.
+ *
+ * The vertex side is a union rather than a sum: two pieces cut out of the same component share the
+ * vertices along the cut, and charging for those twice would refuse a merge that fits.
+ *
+ * @param {{faces: number, vertices: Set<number>}} bin
+ * @param {number[]} piece
+ * @param {Set<number>} vertices the piece touches
+ * @param {number} max_faces
+ * @param {number} max_vertices
+ * @returns {boolean}
+ */
+function bin_accepts(bin, piece, vertices, max_faces, max_vertices) {
+    if (bin.faces + piece.length > max_faces) {
+        return false;
+    }
+
+    let added = 0;
+
+    for (const vertex of vertices) {
+        if (!bin.vertices.has(vertex)) {
+            added++;
+        }
+    }
+
+    return bin.vertices.size + added <= max_vertices;
+}
+
+/**
+ * @param {{pieces: number[], faces: number, vertices: Set<number>}} bin
+ * @param {number} index of the piece
+ * @param {number[]} piece
+ * @param {Set<number>} vertices the piece touches
+ */
+function bin_add(bin, index, piece, vertices) {
+    bin.pieces.push(index);
+    bin.faces += piece.length;
+
+    for (const vertex of vertices) {
+        bin.vertices.add(vertex);
+    }
+}
+
+/**
+ * Walk the curve, opening a new cluster whenever the next piece does not fit in the one already
+ * open.
+ *
+ * Next-fit rather than best-fit: the curve already put spatial neighbours side by side, and letting a
+ * piece jump backwards to top up an earlier bin would pull distant geometry into it for the sake of
+ * a few triangles of fill. Every cluster this produces is a contiguous run of the curve.
+ *
+ * @param {number[][]} pieces
+ * @param {Set<number>[]} piece_vertices one entry per piece
+ * @param {number[]} order indices into `pieces`, along the curve
+ * @param {number} max_faces
+ * @param {number} max_vertices
+ * @returns {{pieces: number[], faces: number, vertices: Set<number>}[]}
+ */
+function fill_along_curve(pieces, piece_vertices, order, max_faces, max_vertices) {
     const result = [];
 
+    for (const index of order) {
+        const bin = result[result.length - 1];
+
+        if (
+            bin !== undefined
+            && bin_accepts(bin, pieces[index], piece_vertices[index], max_faces, max_vertices)
+        ) {
+            bin_add(bin, index, pieces[index], piece_vertices[index]);
+
+            continue;
+        }
+
+        result.push(open_bin(index, pieces[index], piece_vertices[index]));
+    }
+
+    return result;
+}
+
+/**
+ * Offer the pieces largest first, each into the first cluster that will take it.
+ *
+ * Largest first is the whole of the difference, and for the usual reason: a cluster already topped up
+ * with small pieces has no room left for a big one, so the big ones have to choose first. Two 66s and
+ * a 40 and a 34 are two clusters when the 66s choose first and three when they do not, and no walk of
+ * the curve finds the pairing because the pieces that belong together are not neighbours on it.
+ *
+ * The clusters are still tried in the curve's order, so a piece lands in the earliest — nearest —
+ * one that can hold it.
+ *
+ * @param {number[][]} pieces
+ * @param {Set<number>[]} piece_vertices one entry per piece
+ * @param {number[]} order indices into `pieces`, along the curve
+ * @param {number} max_faces
+ * @param {number} max_vertices
+ * @returns {{pieces: number[], faces: number, vertices: Set<number>}[]}
+ */
+function fill_largest_first(pieces, piece_vertices, order, max_faces, max_vertices) {
     /**
-     *
-     * @type {number[]|undefined}
-     */
-    let bin = undefined;
-    /**
-     *
-     * @type {Set<number>|undefined}
+     * `piece -> its place on the curve`, so that pieces of the same size keep the curve's order and
+     * the pack stays a function of the geometry rather than of the sort's own tie-breaking.
+     * @type {Int32Array}
      */
-    let bin_vertices = undefined;
+    const place = new Int32Array(pieces.length);
 
-    for (const index of order) {
-        const piece = pieces[index];
+    order.forEach((index, position) => {
+        place[index] = position;
+    });
 
-        if (bin !== undefined && (bin.length + piece.length) <= max_faces) {
-            const piece_vertices = unique_vertices(face_graph, piece);
+    // How much of a cluster a piece costs, on whichever of the two caps it loads most.
+    const load = (index) => Math.max(
+        pieces[index].length / max_faces, piece_vertices[index].size / max_vertices
+    );
 
-            let added = 0;
+    const by_size = order.slice();
 
-            for (const vertex of piece_vertices) {
-                if (!bin_vertices.has(vertex)) {
-                    added++;
-                }
-            }
+    by_size.sort((a, b) => (load(b) - load(a)) || (place[a] - place[b]));
 
-            if (bin_vertices.size + added <= max_vertices) {
-                for (const member of piece) {
-                    bin.push(member);
-                }
+    const result = [];
 
-                for (const vertex of piece_vertices) {
-                    bin_vertices.add(vertex);
-                }
+    for (const index of by_size) {
+        let placed = false;
 
+        for (const bin of result) {
+            if (!bin_accepts(bin, pieces[index], piece_vertices[index], max_faces, max_vertices)) {
                 continue;
             }
+
+            bin_add(bin, index, pieces[index], piece_vertices[index]);
+
+            placed = true;
+
+            break;
         }
 
-        bin = piece.slice();
-        bin_vertices = unique_vertices(face_graph, piece);
+        if (!placed) {
+            result.push(open_bin(index, pieces[index], piece_vertices[index]));
+        }
+    }
 
-        result.push(bin);
+    return result;
+}
+
+/**
+ * Merge under-filled pieces into shared clusters.
+ *
+ * @param {VGeoFaceGraph} face_graph
+ * @param {number[][]} pieces each already within both caps
+ * @param {number} max_faces
+ * @param {number} max_vertices
+ * @param {number} floor fewest clusters both caps allow for the set as a whole
+ * @returns {number[][]}
+ */
+function pack_pieces(face_graph, pieces, max_faces, max_vertices, floor) {
+
+    if (pieces.length < 2) {
+        // nothing to merge, pass through
+        return pieces;
     }
 
-    for (const packed of result) {
-        packed.sort((a, b) => a - b);
+    const piece_vertices = pieces.map((piece) => unique_wedges(face_graph, piece));
+
+    const order = curve_order(face_graph, pieces);
+
+    let bins = fill_along_curve(pieces, piece_vertices, order, max_faces, max_vertices);
+
+    if (bins.length > floor) {
+        // The caps would have held this in fewer clusters and walking the curve did not find how.
+        // Nothing local says which pieces belong together, so the only way to learn whether the
+        // extra cluster was necessary is to pack again with size deciding instead of position, and
+        // to keep that only if it turns out it was not.
+        const by_size = fill_largest_first(pieces, piece_vertices, order, max_faces, max_vertices);
+
+        if (by_size.length < bins.length) {
+            bins = by_size;
+        }
     }
 
-    return result;
+    return bins.map((bin) => {
+        const packed = [];
+
+        for (const index of bin.pieces) {
+            for (const member of pieces[index]) {
+                packed.push(member);
+            }
+        }
+
+        packed.sort((a, b) => a - b);
+
+        return packed;
+    });
 }
 
 /**
@@ -196,9 +351,18 @@ function pack_pieces(face_graph, pieces, max_faces, max_vertices) {
  * @returns {number[][]} clusters within both caps, ordered by their lowest member
  */
 export function vgeo_split_face_set_packed(face_graph, members, max_faces, max_vertices) {
+    // What a perfect packing of this set would come back with. It is a bound and not always a
+    // reachable one — indivisible pieces need not add up to it — but it is the only thing that says
+    // whether the merge left a cluster on the table, and so the only thing that can decide whether
+    // the merge is worth attempting a second way.
+    const floor = Math.max(
+        Math.ceil(members.length / max_faces),
+        Math.ceil(face_graph.count_unique_wedges(members) / max_vertices)
+    );
+
     const packed = pack_pieces(
         face_graph, vgeo_split_face_set(face_graph, members, max_faces, max_vertices),
-        max_faces, max_vertices
+        max_faces, max_vertices, floor
     );
 
     packed.sort((a, b) => a[0] - b[0]);

package/src/shade/renderer/geometry/virtual/build/submesh/VGeoGatheredFaces.d.ts

@@ -17,8 +17,23 @@ export class VGeoGatheredFaces {
     indices: Uint32Array;
     /**
      * Vertex ids in the mesh this was pulled out of, one per local vertex, in first-use order.
+     *
+     * **Not unique.** One entry per *wedge*, so a vertex whose corners shade two ways appears twice
+     * — which is what a seam has always cost, in any renderer, and is where it is paid.
      * @type {Uint32Array}
      */
     vertex_ids: Uint32Array;
+    /**
+     * The wedge each local vertex is, named in the mesh this was pulled out of. Parallel to
+     * {@link vertex_ids}, and unique where that is not.
+     * @type {Uint32Array}
+     */
+    wedge_ids: Uint32Array;
+    /**
+     * One corner per output vertex — the loop it was first seen at — for the appearance channels to
+     * be read through. They live on corners, so a vertex alone does not address them.
+     * @type {Uint32Array}
+     */
+    attribute_ids: Uint32Array;
 }
 //# sourceMappingURL=VGeoGatheredFaces.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"VGeoGatheredFaces.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/geometry/virtual/build/submesh/VGeoGatheredFaces.js"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH;IACI;;;OAGG;IACH,WAFU,YAAY,CAEU;IAEhC;;;OAGG;IACH,SAFU,WAAW,CAEQ;IAE7B;;;OAGG;IACH,YAFU,WAAW,CAEW;CACnC"}
+{"version":3,"file":"VGeoGatheredFaces.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/geometry/virtual/build/submesh/VGeoGatheredFaces.js"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH;IACI;;;OAGG;IACH,WAFU,YAAY,CAEU;IAEhC;;;OAGG;IACH,SAFU,WAAW,CAEQ;IAE7B;;;;;;OAMG;IACH,YAFU,WAAW,CAEW;IAEhC;;;;OAIG;IACH,WAFU,WAAW,CAEU;IAE/B;;;;OAIG;IACH,eAFU,WAAW,CAEc;CACtC"}

package/src/shade/renderer/geometry/virtual/build/submesh/VGeoGatheredFaces.js

@@ -19,7 +19,24 @@ export class VGeoGatheredFaces {
 
     /**
      * Vertex ids in the mesh this was pulled out of, one per local vertex, in first-use order.
+     *
+     * **Not unique.** One entry per *wedge*, so a vertex whose corners shade two ways appears twice
+     * — which is what a seam has always cost, in any renderer, and is where it is paid.
      * @type {Uint32Array}
      */
     vertex_ids = new Uint32Array(0);
+
+    /**
+     * The wedge each local vertex is, named in the mesh this was pulled out of. Parallel to
+     * {@link vertex_ids}, and unique where that is not.
+     * @type {Uint32Array}
+     */
+    wedge_ids = new Uint32Array(0);
+
+    /**
+     * One corner per output vertex — the loop it was first seen at — for the appearance channels to
+     * be read through. They live on corners, so a vertex alone does not address them.
+     * @type {Uint32Array}
+     */
+    attribute_ids = new Uint32Array(0);
 }

package/src/shade/renderer/geometry/virtual/build/submesh/VGeoSubmesh.d.ts

@@ -16,5 +16,22 @@ export class VGeoSubmesh {
      * @type {Uint32Array}
      */
     source_vertex_ids: Uint32Array;
+    /**
+     * Which corners of {@link mesh} shade as one, in ids local to it. Mutated by the simplifier as
+     * they merge, which is why a local id is what the carried values and quadrics are indexed by.
+     * @type {BtWedgeSet}
+     */
+    wedges: BtWedgeSet;
+    /**
+     * `source_wedge_ids[local wedge] = wedge id in the mesh this was extracted from`, the companion
+     * of {@link source_vertex_ids} and what carries an accumulated attribute quadric across the
+     * seam.
+     *
+     * Survives simplification the way the vertex map does, and for a sharper reason: **a collapse
+     * only ever merges wedges, never splits one**, so a local id that is still its own root after a
+     * step names exactly the source wedge it always did.
+     * @type {Uint32Array}
+     */
+    source_wedge_ids: Uint32Array;
 }
 //# sourceMappingURL=VGeoSubmesh.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"VGeoSubmesh.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/geometry/virtual/build/submesh/VGeoSubmesh.js"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH;IACI;;OAEG;IACH,0BAAY;IAEZ;;;;;OAKG;IACH,mBAFU,WAAW,CAEkB;CAC1C"}
+{"version":3,"file":"VGeoSubmesh.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/geometry/virtual/build/submesh/VGeoSubmesh.js"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH;IACI;;OAEG;IACH,0BAAY;IAEZ;;;;;OAKG;IACH,mBAFU,WAAW,CAEkB;IAEvC;;;;OAIG;IACH,mBAAc;IAEd;;;;;;;;;OASG;IACH,kBAFU,WAAW,CAEiB;CACzC"}

package/src/shade/renderer/geometry/virtual/build/submesh/VGeoSubmesh.js

@@ -17,4 +17,23 @@ export class VGeoSubmesh {
      * @type {Uint32Array}
      */
     source_vertex_ids = new Uint32Array(0);
+
+    /**
+     * Which corners of {@link mesh} shade as one, in ids local to it. Mutated by the simplifier as
+     * they merge, which is why a local id is what the carried values and quadrics are indexed by.
+     * @type {BtWedgeSet}
+     */
+    wedges = null;
+
+    /**
+     * `source_wedge_ids[local wedge] = wedge id in the mesh this was extracted from`, the companion
+     * of {@link source_vertex_ids} and what carries an accumulated attribute quadric across the
+     * seam.
+     *
+     * Survives simplification the way the vertex map does, and for a sharper reason: **a collapse
+     * only ever merges wedges, never splits one**, so a local id that is still its own root after a
+     * step names exactly the source wedge it always did.
+     * @type {Uint32Array}
+     */
+    source_wedge_ids = new Uint32Array(0);
 }

package/src/shade/renderer/geometry/virtual/build/submesh/vgeo_extract_submesh.d.ts

@@ -1,14 +1,23 @@
 /**
  * Extract a face set into a standalone mesh, attributes and all.
  *
+ * **Wedges are not vertices here.** The gather deduped on the wedge, because that is what a cluster
+ * payload's vertices are; a mesh's are not. Two wedges of one vertex are one point and one piece of
+ * connectivity, and giving them a vertex each would shred face adjacency along every seam — which
+ * is the move `WEDGE_PLAN_2026_09_18.md` §8 rejects and the reason the weld exists at all. So the
+ * gather's output is folded back onto one vertex per position and the wedges travel on the corners,
+ * where they belong.
+ *
  * @param {VirtualGeometryMesh} source
  * @param {number[]} face_ids
+ * @param {BtWedgeSet} source_wedges which corners of `source` shade as one
  * @returns {VGeoSubmesh}
  *
  * @author Alex Goldring
  * @copyright Company Named Limited (c) 2026
  */
-export function vgeo_extract_submesh(source: VirtualGeometryMesh, face_ids: number[]): VGeoSubmesh;
+export function vgeo_extract_submesh(source: VirtualGeometryMesh, face_ids: number[], source_wedges: BtWedgeSet): VGeoSubmesh;
 import { VirtualGeometryMesh } from "../mesh/VirtualGeometryMesh.js";
+import { BtWedgeSet } from "../../../../../../core/geom/3d/topology/struct/binary/BtWedgeSet.js";
 import { VGeoSubmesh } from "./VGeoSubmesh.js";
 //# sourceMappingURL=vgeo_extract_submesh.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"vgeo_extract_submesh.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/geometry/virtual/build/submesh/vgeo_extract_submesh.js"],"names":[],"mappings":"AAUA;;;;;;;;;GASG;AACH,6CAPW,mBAAmB,YACnB,MAAM,EAAE,GACN,WAAW,CAyBvB;oCAhCmC,gCAAgC;4BADxC,kBAAkB"}
+{"version":3,"file":"vgeo_extract_submesh.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/geometry/virtual/build/submesh/vgeo_extract_submesh.js"],"names":[],"mappings":"AAaA;;;;;;;;;;;;;;;;;GAiBG;AACH,6CARW,mBAAmB,YACnB,MAAM,EAAE,iBACR,UAAU,GACR,WAAW,CA4GvB;oCA3HmC,gCAAgC;2BARzC,qEAAqE;4BAOpE,kBAAkB"}

package/src/shade/renderer/geometry/virtual/build/submesh/vgeo_extract_submesh.js

@@ -1,8 +1,11 @@
-import { BinaryTopology } from "../../../../../../core/geom/3d/topology/struct/binary/BinaryTopology.js";
+import {
+    BinaryTopology, NULL_POINTER
+} from "../../../../../../core/geom/3d/topology/struct/binary/BinaryTopology.js";
+import { BtWedgeSet } from "../../../../../../core/geom/3d/topology/struct/binary/BtWedgeSet.js";
 import {
     bt_mesh_from_indexed_geometry
 } from "../../../../../../core/geom/3d/topology/struct/binary/io/bt_mesh_from_indexed_geometry.js";
-import { vgeo_layers_copy_vertex } from "../../format/attribute/vgeo_layers_copy_vertex.js";
+import { vgeo_layers_copy_corner } from "../../format/attribute/vgeo_layers_copy_corner.js";
 import { vgeo_layers_like } from "../../format/attribute/vgeo_layers_like.js";
 import { vgeo_gather_faces } from "./vgeo_gather_faces.js";
 import { VGeoSubmesh } from "./VGeoSubmesh.js";
@@ -11,31 +14,122 @@ import { VirtualGeometryMesh } from "../mesh/VirtualGeometryMesh.js";
 /**
  * Extract a face set into a standalone mesh, attributes and all.
  *
+ * **Wedges are not vertices here.** The gather deduped on the wedge, because that is what a cluster
+ * payload's vertices are; a mesh's are not. Two wedges of one vertex are one point and one piece of
+ * connectivity, and giving them a vertex each would shred face adjacency along every seam — which
+ * is the move `WEDGE_PLAN_2026_09_18.md` §8 rejects and the reason the weld exists at all. So the
+ * gather's output is folded back onto one vertex per position and the wedges travel on the corners,
+ * where they belong.
+ *
  * @param {VirtualGeometryMesh} source
  * @param {number[]} face_ids
+ * @param {BtWedgeSet} source_wedges which corners of `source` shade as one
  * @returns {VGeoSubmesh}
  *
  * @author Alex Goldring
  * @copyright Company Named Limited (c) 2026
  */
-export function vgeo_extract_submesh(source, face_ids) {
-    const gathered = vgeo_gather_faces(source, face_ids);
+export function vgeo_extract_submesh(source, face_ids, source_wedges) {
+    const gathered = vgeo_gather_faces(source, face_ids, source_wedges);
+
+    const wedge_count = gathered.wedge_ids.length;
+
+    /**
+     * `source vertex id -> local vertex id`.
+     * @type {Map<number, number>}
+     */
+    const local_of_vertex = new Map();
+
+    /**
+     * The local vertex each gathered wedge sits at.
+     * @type {Uint32Array}
+     */
+    const vertex_of_wedge = new Uint32Array(wedge_count);
+
+    const source_vertex_ids = [];
+    const positions = [];
+
+    gathered.vertex_ids.forEach((vertex, wedge) => {
+        let local = local_of_vertex.get(vertex);
+
+        if (local === undefined) {
+            local = source_vertex_ids.length;
+
+            local_of_vertex.set(vertex, local);
+            source_vertex_ids.push(vertex);
+
+            positions.push(
+                gathered.positions[wedge * 3],
+                gathered.positions[wedge * 3 + 1],
+                gathered.positions[wedge * 3 + 2]
+            );
+        }
+
+        vertex_of_wedge[wedge] = local;
+    });
 
     const topology = new BinaryTopology();
 
     // Before the vertices, so no record has to be widened. See {@link VirtualGeometryMesh.from_geometry}.
     const layers = vgeo_layers_like(topology, source.layers);
 
-    bt_mesh_from_indexed_geometry(topology, gathered.indices, gathered.positions);
+    bt_mesh_from_indexed_geometry(
+        topology,
+        Uint32Array.from(gathered.indices, (wedge) => vertex_of_wedge[wedge]),
+        Float32Array.from(positions)
+    );
 
-    gathered.vertex_ids.forEach((source_vertex, local) => {
-        vgeo_layers_copy_vertex(topology, source.topology, source_vertex, local);
-    });
+    if (topology.faces.count() !== face_ids.length) {
+        // The corner walk below reads face `t` as the `t`th triangle of the index list, so a builder
+        // that dropped or reordered one would silently hand every corner the wrong appearance. A
+        // thrown build beats a wrong asset, and this cannot be an `assert` for exactly that reason:
+        // asserts are stripped from what ships.
+        throw new Error(
+            `extracting ${face_ids.length} faces produced ${topology.faces.count()}, so the corners `
+            + `of the result cannot be matched to the corners they came from`
+        );
+    }
+
+    const wedges = new BtWedgeSet();
+
+    wedges.count = wedge_count;
+    wedges.parent = Uint32Array.from({ length: wedge_count }, (_, wedge) => wedge);
+    wedges.next_of_wedge = new Uint32Array(wedge_count).fill(NULL_POINTER);
+    wedges.first_of_vertex = new Uint32Array(topology.vertices.size).fill(NULL_POINTER);
+    wedges.of_loop = new Uint32Array(topology.loops.size).fill(NULL_POINTER);
+
+    for (let wedge = 0; wedge < wedge_count; wedge++) {
+        wedges.attach(wedge, vertex_of_wedge[wedge]);
+    }
+
+    /*
+     Corner by corner, through the wedge each one names — which is the copy §6.1 could not make.
+     Going through the *vertex* was exact only while every corner of a vertex agreed; it does not
+     agree any more, and that is the point. The two meshes' loops are matched up here because the
+     faces were built from this very index list, in this order.
+     */
+    for (let face = 0; face < face_ids.length; face++) {
+        let loop = topology.face_read_loop(face);
+
+        for (let corner = 0; corner < 3; corner++) {
+            const wedge = gathered.indices[face * 3 + corner];
+
+            wedges.of_loop[loop] = wedge;
+
+            vgeo_layers_copy_corner(
+                topology, source.topology, gathered.attribute_ids[wedge], loop
+            );
+
+            loop = topology.loop_read_next(loop);
+        }
+    }
 
     const result = new VGeoSubmesh();
 
     result.mesh = new VirtualGeometryMesh(topology, layers);
-    result.source_vertex_ids = gathered.vertex_ids;
+    result.source_vertex_ids = Uint32Array.from(source_vertex_ids);
+    result.wedges = wedges;
+    result.source_wedge_ids = gathered.wedge_ids;
 
     return result;
 }

package/src/shade/renderer/geometry/virtual/build/submesh/vgeo_gather_faces.d.ts

@@ -1,12 +1,24 @@
 /**
- * Gather a face set: unique vertices in first-use order, local indices, coordinates copied out.
+ * Gather a face set: unique **wedges** in first-use order, local indices, coordinates copied out,
+ * and one corner per output vertex for the appearance to be read through.
+ *
+ * A wedge, not a vertex, and that is the whole of what a seam costs. Two corners of one vertex that
+ * shade differently cannot share an output vertex: the payload carries one value per vertex, so a
+ * hard edge or a texture chart boundary has to be two of them. It costs exactly what it has always
+ * cost anywhere else — a seam is an extra vertex in every renderer ever written — and it costs it
+ * *here*, at the gather, rather than in the topology, where splitting would shred face adjacency
+ * (`WEDGE_PLAN_2026_09_18.md` §8).
+ *
+ * A mesh with no seams has one wedge per vertex, every corner of a vertex resolves to it, and this
+ * dedupes on the vertex exactly as it always did.
  *
  * First-use order is what makes the result depend only on the face list, not on the pool's history.
  *
  * @param {VirtualGeometryMesh} mesh
  * @param {number[]} face_ids allocated triangular faces
+ * @param {BtWedgeSet} wedges which corners of each vertex shade as one
  * @returns {VGeoGatheredFaces}
  */
-export function vgeo_gather_faces(mesh: VirtualGeometryMesh, face_ids: number[]): VGeoGatheredFaces;
+export function vgeo_gather_faces(mesh: VirtualGeometryMesh, face_ids: number[], wedges: BtWedgeSet): VGeoGatheredFaces;
 import { VGeoGatheredFaces } from "./VGeoGatheredFaces.js";
 //# sourceMappingURL=vgeo_gather_faces.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"vgeo_gather_faces.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/geometry/virtual/build/submesh/vgeo_gather_faces.js"],"names":[],"mappings":"AAcA;;;;;;;;GAQG;AACH,uEAHW,MAAM,EAAE,GACN,iBAAiB,CAiD7B;kCAlEiC,wBAAwB"}
+{"version":3,"file":"vgeo_gather_faces.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/geometry/virtual/build/submesh/vgeo_gather_faces.js"],"names":[],"mappings":"AAWA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,uEAJW,MAAM,EAAE,uBAEN,iBAAiB,CAgE7B;kCA5FiC,wBAAwB"}