@woosh/meep-engine 3.28.0 → 3.29.0

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

@@ -1,7 +1,5 @@
 import { assert } from "../../../../../../core/assert.js";
-import {
-    bt_face_read_triangle_vertices
-} from "../../../../../../core/geom/3d/topology/struct/binary/query/bt_face_read_triangle.js";
+import { NULL_POINTER } from "../../../../../../core/geom/3d/topology/struct/binary/BinaryTopology.js";
 import { VGeoGatheredFaces } from "./VGeoGatheredFaces.js";
 
 /**
@@ -9,53 +7,79 @@ import { VGeoGatheredFaces } from "./VGeoGatheredFaces.js";
  * @copyright Company Named Limited (c) 2026
  */
 
-const scratch_triangle = new Uint32Array(3);
 const scratch_coordinate = new Float32Array(3);
 
 /**
- * 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, face_ids) {
+export function vgeo_gather_faces(mesh, face_ids, wedges) {
     const topology = mesh.topology;
 
     /**
+     * `wedge -> local`, over wedge *roots*: a merged wedge answers to the one it merged into, and
+     * two corners that resolve to the same root are one output vertex.
      * @type {Map<number, number>}
      */
-    const local_of_source = new Map();
+    const local_of_wedge = new Map();
 
     const vertex_ids = [];
+    const wedge_ids = [];
+    const attribute_ids = [];
     const indices = new Uint32Array(face_ids.length * 3);
 
     face_ids.forEach((face, face_index) => {
-        const read = bt_face_read_triangle_vertices(scratch_triangle, topology, face);
+        const first_loop = topology.face_read_loop(face);
+
+        assert.notEqual(first_loop, NULL_POINTER, `face ${face} has no loop`);
 
-        assert.equal(read, true, `face ${face} is not an allocated triangle`);
+        let loop = first_loop;
 
         for (let i = 0; i < 3; i++) {
-            const vertex = scratch_triangle[i];
+            const wedge = wedges.find(wedges.of_loop[loop]);
 
-            let local = local_of_source.get(vertex);
+            let local = local_of_wedge.get(wedge);
 
             if (local === undefined) {
-                local = vertex_ids.length;
+                local = wedge_ids.length;
 
-                local_of_source.set(vertex, local);
-                vertex_ids.push(vertex);
+                local_of_wedge.set(wedge, local);
+
+                wedge_ids.push(wedge);
+                vertex_ids.push(topology.loop_read_vertex(loop));
+                attribute_ids.push(loop);
             }
 
             indices[face_index * 3 + i] = local;
+
+            loop = topology.loop_read_next(loop);
         }
+
+        assert.equal(loop, first_loop, `face ${face} is not an allocated triangle`);
     });
 
     const result = new VGeoGatheredFaces();
 
     result.vertex_ids = Uint32Array.from(vertex_ids);
+    result.wedge_ids = Uint32Array.from(wedge_ids);
+    result.attribute_ids = Uint32Array.from(attribute_ids);
     result.indices = indices;
     result.positions = new Float32Array(vertex_ids.length * 3);
 

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

@@ -13,10 +13,14 @@
  * geometry that arrives without them is given them by normalization, off the welded mesh — see
  * {@link vgeo_normalize_source}.
  *
+ * It is asynchronous only because the writer is, and the writer is because a page codec can be —
+ * {@link VGEO_CODEC_DEFLATE} is the platform's zlib and the platform only offers it as a stream.
+ * Every other step below is the same synchronous pipeline it has always been.
+ *
  * @param {Geometry} geometry the source, in object space
  * @param {VGeoBuildOptions} options
- * @returns {VGeoBuildResult}
+ * @returns {Promise<VGeoBuildResult>}
  */
-export function vgeo_build(geometry: Geometry, options: VGeoBuildOptions): VGeoBuildResult;
+export function vgeo_build(geometry: Geometry, options: VGeoBuildOptions): Promise<VGeoBuildResult>;
 import { VGeoBuildResult } from "./VGeoBuildResult.js";
 //# sourceMappingURL=vgeo_build.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"vgeo_build.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/geometry/virtual/build/vgeo_build.js"],"names":[],"mappings":"AA4GA;;;;;;;;;;;;;;;;;;GAkBG;AACH,2EAFa,eAAe,CAyE3B;gCA3L+B,sBAAsB"}
+{"version":3,"file":"vgeo_build.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/geometry/virtual/build/vgeo_build.js"],"names":[],"mappings":"AA8GA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,2EAFa,QAAQ,eAAe,CAAC,CA0FpC;gCAhN+B,sBAAsB"}

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

@@ -9,6 +9,8 @@ import { vgeo_build_levels } from "./level/vgeo_build_levels.js";
 import { vgeo_build_root_group } from "./level/vgeo_build_root_group.js";
 import { vgeo_containing_sphere } from "./sphere/vgeo_containing_sphere.js";
 import { vgeo_normalize_source } from "./mesh/vgeo_normalize_source.js";
+import { vgeo_resolve_attribute_weights } from "./mesh/vgeo_resolve_attribute_weights.js";
+import { vgeo_subtree_bounds } from "./vgeo_subtree_bounds.js";
 import { VGeoBuildResult } from "./VGeoBuildResult.js";
 import { VGeoLevelSummary } from "./level/VGeoLevelSummary.js";
 import { VirtualGeometryMesh } from "./mesh/VirtualGeometryMesh.js";
@@ -121,17 +123,21 @@ function level_summary_to_record(summary) {
  * geometry that arrives without them is given them by normalization, off the welded mesh — see
  * {@link vgeo_normalize_source}.
  *
+ * It is asynchronous only because the writer is, and the writer is because a page codec can be —
+ * {@link VGEO_CODEC_DEFLATE} is the platform's zlib and the platform only offers it as a stream.
+ * Every other step below is the same synchronous pipeline it has always been.
+ *
  * @param {Geometry} geometry the source, in object space
  * @param {VGeoBuildOptions} options
- * @returns {VGeoBuildResult}
+ * @returns {Promise<VGeoBuildResult>}
  */
-export function vgeo_build(geometry, options) {
+export async function vgeo_build(geometry, options) {
     assert.greaterThan(options.weld_ratio, 0, 'options.weld_ratio');
     assert.isPositiveInteger(options.nominal_page_size, 'options.nominal_page_size');
 
     const mesh = VirtualGeometryMesh.from_geometry(geometry);
 
-    const weld_distance = vgeo_normalize_source(mesh, options.weld_ratio);
+    const weld_distance = vgeo_normalize_source(mesh, options.weld_ratio, options.crease_angle);
 
     const source_face_count = mesh.topology.faces.count();
     const source_vertex_count = mesh.topology.vertices.count();
@@ -139,7 +145,18 @@ export function vgeo_build(geometry, options) {
     assert.greaterThan(source_face_count, 0, 'the source mesh has no faces left after normalization');
     assert.greaterThanOrEqual(source_vertex_count, 3, 'source vertex count');
 
-    const levels = vgeo_build_levels(mesh, options.level_options);
+    /*
+     Resolved here, off the normalized source and before the level loop, for the same reason the weld
+     distance is a fraction of the source's own size: a conversion is many geometries at many sizes
+     and no single number is right for all of them. Once, so every level of the DAG is built against
+     the same statement of what a unit of each channel is worth -- the mesh shrinks as the build goes
+     on, and a weight re-derived per level would drift with it.
+     */
+    const levels = vgeo_build_levels(
+        mesh,
+        options.level_options,
+        vgeo_resolve_attribute_weights(mesh, options.attribute_weight_ratios)
+    );
 
     const top = levels[levels.length - 1];
 
@@ -153,6 +170,12 @@ export function vgeo_build(geometry, options) {
 
     top.groups = [vgeo_build_root_group(root, top.index)];
 
+    /*
+     After the root's own fields and before anything reads a cluster: the page assembler and the
+     writer both take clusters as they are, and this is the last thing the DAG gains.
+    */
+    vgeo_subtree_bounds(levels);
+
     const object = compute_object_bounds(levels);
 
     const pages = vgeo_assemble_pages(
@@ -183,7 +206,7 @@ export function vgeo_build(geometry, options) {
 
     const result = new VGeoBuildResult();
 
-    result.buffer = vgeo_write_container(pages, write_options);
+    result.buffer = await vgeo_write_container(pages, write_options);
     result.page_count = pages.length;
     result.source_vertex_count = source_vertex_count;
     result.source_face_count = source_face_count;

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

@@ -0,0 +1,32 @@
+/**
+ * Give every cluster of a built DAG the AABB of its own geometry and of everything reachable below
+ * it, which is the bound the runtime cut culls on (`CULL_PLAN_2026_09_16` §3.1, FORMAT §11.17).
+ *
+ * **Why the subtree and not the cluster.** A simplification step consumes one group and produces
+ * several parents, and each parent's `child_group` is the *whole* consumed group — so a cluster's
+ * subtree carries its siblings' surface as well as its own, and doubles per level. The cut's
+ * per-cluster test decides whether to descend into that group at all, so a bound that covers only
+ * the cluster would cull a parent whose descendants are on screen, and a culled subtree is a hole.
+ *
+ * **Why a memoised walk rather than a pass by level.** A round leaves unmerged clusters in the
+ * frontier, so a group formed at round L can hold members created at any lower level, and
+ * `group.level` records where the group was formed rather than where its members were. Following
+ * `child_group` instead needs no such assumption. The DAG is acyclic (format §11.3) and a group is
+ * shared by its several parents, so memoising on the cluster makes this O(clusters + edges) with the
+ * shared work done once.
+ *
+ * Recursion is explicit: these DAGs run to forty levels but a page's group can hold thousands of
+ * clusters, and a native stack deep in the fine levels of a billion-triangle build is not worth the
+ * elegance.
+ *
+ * The union is of float32 extremes, so every bound it produces is exactly representable and
+ * contains what it was built from with no inflation — unlike a sphere, which is why the validator
+ * can check this one exactly.
+ *
+ * @param {VGeoLevel[]} levels as {@link vgeo_build_levels} leaves them
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function vgeo_subtree_bounds(levels: VGeoLevel[]): void;
+//# sourceMappingURL=vgeo_subtree_bounds.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"vgeo_subtree_bounds.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/geometry/virtual/build/vgeo_subtree_bounds.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,4CALW,WAAW,QAiErB"}

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

@@ -0,0 +1,93 @@
+import { aabb3_array_combine } from "../../../../../core/geom/3d/aabb/aabb3_array_combine.js";
+
+/**
+ * Give every cluster of a built DAG the AABB of its own geometry and of everything reachable below
+ * it, which is the bound the runtime cut culls on (`CULL_PLAN_2026_09_16` §3.1, FORMAT §11.17).
+ *
+ * **Why the subtree and not the cluster.** A simplification step consumes one group and produces
+ * several parents, and each parent's `child_group` is the *whole* consumed group — so a cluster's
+ * subtree carries its siblings' surface as well as its own, and doubles per level. The cut's
+ * per-cluster test decides whether to descend into that group at all, so a bound that covers only
+ * the cluster would cull a parent whose descendants are on screen, and a culled subtree is a hole.
+ *
+ * **Why a memoised walk rather than a pass by level.** A round leaves unmerged clusters in the
+ * frontier, so a group formed at round L can hold members created at any lower level, and
+ * `group.level` records where the group was formed rather than where its members were. Following
+ * `child_group` instead needs no such assumption. The DAG is acyclic (format §11.3) and a group is
+ * shared by its several parents, so memoising on the cluster makes this O(clusters + edges) with the
+ * shared work done once.
+ *
+ * Recursion is explicit: these DAGs run to forty levels but a page's group can hold thousands of
+ * clusters, and a native stack deep in the fine levels of a billion-triangle build is not worth the
+ * elegance.
+ *
+ * The union is of float32 extremes, so every bound it produces is exactly representable and
+ * contains what it was built from with no inflation — unlike a sphere, which is why the validator
+ * can check this one exactly.
+ *
+ * @param {VGeoLevel[]} levels as {@link vgeo_build_levels} leaves them
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function vgeo_subtree_bounds(levels) {
+    /**
+     * Clusters whose `subtree_aabb` is final.
+     * @type {Set<VirtualGeometryCluster>}
+     */
+    const done = new Set();
+
+    /**
+     * Cluster, then the mark that says its children have been visited already.
+     * @type {(VirtualGeometryCluster|boolean)[]}
+     */
+    const stack = [];
+
+    for (const level of levels) {
+        for (const root of level.clusters) {
+            if (done.has(root)) {
+                continue;
+            }
+
+            stack.push(root, false);
+
+            while (stack.length > 0) {
+                const expanded = stack.pop();
+                const cluster = stack.pop();
+
+                if (done.has(cluster)) {
+                    continue;
+                }
+
+                const group = cluster.child_group;
+
+                if (group !== undefined && !expanded) {
+                    // come back to this one once its children are final
+                    stack.push(cluster, true);
+
+                    for (const child of group.clusters) {
+                        if (!done.has(child)) {
+                            stack.push(child, false);
+                        }
+                    }
+
+                    continue;
+                }
+
+                cluster.subtree_aabb.set(cluster.aabb);
+
+                if (group !== undefined) {
+                    for (const child of group.clusters) {
+                        aabb3_array_combine(
+                            cluster.subtree_aabb, 0,
+                            cluster.subtree_aabb, 0,
+                            child.subtree_aabb, 0
+                        );
+                    }
+                }
+
+                done.add(cluster);
+            }
+        }
+    }
+}

package/src/shade/renderer/geometry/virtual/format/VGeoWriteOptions.d.ts

@@ -9,20 +9,33 @@
  */
 export class VGeoWriteOptions {
     /**
-     * Which codec to store page blobs under. On by default because a page is a table of records and
-     * a payload of encoded words, and both repeat heavily — see the format's §5 note on what it
-     * comes to. It costs the reader an LZ4 block decode per page, which runs at gigabytes a second
-     * and lands on the page it was going to copy anyway.
+     * Which codec to store page blobs under — {@link VGEO_CODEC_RAW}, {@link VGEO_CODEC_LZ4} or
+     * {@link VGEO_CODEC_DEFLATE}. Compressed by default because a page is a table of records and a
+     * payload of encoded words, and both repeat heavily — see the format's §5 note on what it comes
+     * to. It costs the reader one block decode per page, which lands on the page it was going to
+     * copy anyway.
      *
      * It is a request rather than a promise: {@link vgeo_encode_frame_blob} stores a page raw when
      * compressing it would not make it smaller, so this can never grow a file.
      *
+     * Deflate by default, matching {@link VGeoBuildOptions}. Nothing exercises this value today —
+     * `vgeo_build` sets it from the build options and the specs that drive the writer directly set
+     * it too — so it is here to agree with the builder rather than to decide anything, and two
+     * adjacent defaults that disagreed would be a trap for whoever wrote the next caller.
+     *
+     * Deflate is the denser of the two compressing codecs, 1.369x against LZ4's 1.295x over the
+     * pages of a 240x120 torus, for about four and a half times the decode: 126 MB/s of decoded
+     * output against 562. {@link VGEO_CODEC_LZ4} is the setting for a container whose pages arrive
+     * while someone is looking at it, because that decode is a page's arrival cost.
+     *
      * @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.
+     * top of the reference's hash-chain levels. **LZ4 only, and the default codec is not LZ4** —
+     * `CompressionStream` exposes no level, so this does nothing at all unless {@link codec} was
+     * set to {@link VGEO_CODEC_LZ4}.
      *
      * **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
@@ -39,7 +52,8 @@ export class VGeoWriteOptions {
      */
     codec_level: number;
     /**
-     * One per level, coarsest last. `level_count` is its length.
+     * One per level, coarsest last. `level_count` is its length, and the header can name up to
+     * {@link VGEO_MAX_LEVEL_COUNT} of them.
      * @type {VGeoLevelRecord[]}
      */
     levels: VGeoLevelRecord[];

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

@@ -1 +1 @@
-{"version":3,"file":"VGeoWriteOptions.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/geometry/virtual/format/VGeoWriteOptions.js"],"names":[],"mappings":"AAGA;;GAEG;AAEH;;;;;GAKG;AACH;IACI;;;;;;;;;;OAUG;IACH,OAFU,MAAM,CAEO;IAEvB;;;;;;;;;;;;;;;;OAgBG;IACH,aAFU,MAAM,CAEmB;IAEnC;;;OAGG;IACH,QAFU,eAAe,EAAE,CAEf;IAEZ;;;OAGG;IACH,qBAFU,MAAM,CAEQ;IAExB;;;OAGG;IACH,mBAFU,MAAM,CAEM;IAEtB;;;OAGG;IACH,eAFU,YAAY,CAEc;IAEpC;;;OAGG;IACH,eAFU,YAAY,CAEc;IAEpC;;;OAGG;IACH,uBAFU,MAAM,CAEU;IAE1B;;;;;;;;;;OAUG;IACH,mBAFU,MAAM,CAEM;CACzB;8BA1FY,OAAO,6BAA6B,EAAE,eAAe"}
+{"version":3,"file":"VGeoWriteOptions.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/geometry/virtual/format/VGeoWriteOptions.js"],"names":[],"mappings":"AAGA;;GAEG;AAEH;;;;;GAKG;AACH;IACI;;;;;;;;;;;;;;;;;;;;;OAqBG;IACH,OAFU,MAAM,CAEW;IAE3B;;;;;;;;;;;;;;;;;;OAkBG;IACH,aAFU,MAAM,CAEmB;IAEnC;;;;OAIG;IACH,QAFU,eAAe,EAAE,CAEf;IAEZ;;;OAGG;IACH,qBAFU,MAAM,CAEQ;IAExB;;;OAGG;IACH,mBAFU,MAAM,CAEM;IAEtB;;;OAGG;IACH,eAFU,YAAY,CAEc;IAEpC;;;OAGG;IACH,eAFU,YAAY,CAEc;IAEpC;;;OAGG;IACH,uBAFU,MAAM,CAEU;IAE1B;;;;;;;;;;OAUG;IACH,mBAFU,MAAM,CAEM;CACzB;8BAxGY,OAAO,6BAA6B,EAAE,eAAe"}

package/src/shade/renderer/geometry/virtual/format/VGeoWriteOptions.js

@@ -1,5 +1,5 @@
 import { LZ4_LEVEL } from "../../../../../core/binary/lz4/LZ4_LEVEL.js";
-import { VGEO_CODEC_LZ4 } from "./frame/VGEO_CODEC_LZ4.js";
+import { VGEO_CODEC_DEFLATE } from "./frame/VGEO_CODEC_DEFLATE.js";
 
 /**
  * @typedef {import("./header/VGeoLevelRecord.js").VGeoLevelRecord} VGeoLevelRecord
@@ -13,21 +13,34 @@ import { VGEO_CODEC_LZ4 } from "./frame/VGEO_CODEC_LZ4.js";
  */
 export class VGeoWriteOptions {
     /**
-     * Which codec to store page blobs under. On by default because a page is a table of records and
-     * a payload of encoded words, and both repeat heavily — see the format's §5 note on what it
-     * comes to. It costs the reader an LZ4 block decode per page, which runs at gigabytes a second
-     * and lands on the page it was going to copy anyway.
+     * Which codec to store page blobs under — {@link VGEO_CODEC_RAW}, {@link VGEO_CODEC_LZ4} or
+     * {@link VGEO_CODEC_DEFLATE}. Compressed by default because a page is a table of records and a
+     * payload of encoded words, and both repeat heavily — see the format's §5 note on what it comes
+     * to. It costs the reader one block decode per page, which lands on the page it was going to
+     * copy anyway.
      *
      * It is a request rather than a promise: {@link vgeo_encode_frame_blob} stores a page raw when
      * compressing it would not make it smaller, so this can never grow a file.
      *
+     * Deflate by default, matching {@link VGeoBuildOptions}. Nothing exercises this value today —
+     * `vgeo_build` sets it from the build options and the specs that drive the writer directly set
+     * it too — so it is here to agree with the builder rather than to decide anything, and two
+     * adjacent defaults that disagreed would be a trap for whoever wrote the next caller.
+     *
+     * Deflate is the denser of the two compressing codecs, 1.369x against LZ4's 1.295x over the
+     * pages of a 240x120 torus, for about four and a half times the decode: 126 MB/s of decoded
+     * output against 562. {@link VGEO_CODEC_LZ4} is the setting for a container whose pages arrive
+     * while someone is looking at it, because that decode is a page's arrival cost.
+     *
      * @type {number}
      */
-    codec = VGEO_CODEC_LZ4;
+    codec = VGEO_CODEC_DEFLATE;
 
     /**
      * 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.
+     * top of the reference's hash-chain levels. **LZ4 only, and the default codec is not LZ4** —
+     * `CompressionStream` exposes no level, so this does nothing at all unless {@link codec} was
+     * set to {@link VGEO_CODEC_LZ4}.
      *
      * **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
@@ -45,7 +58,8 @@ export class VGeoWriteOptions {
     codec_level = LZ4_LEVEL.HC_DEFAULT;
 
     /**
-     * One per level, coarsest last. `level_count` is its length.
+     * One per level, coarsest last. `level_count` is its length, and the header can name up to
+     * {@link VGEO_MAX_LEVEL_COUNT} of them.
      * @type {VGeoLevelRecord[]}
      */
     levels = [];

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

@@ -0,0 +1,16 @@
+/**
+ * Copy one corner's every channel between two meshes declared from the same template.
+ *
+ * One run of bytes, not one call per channel: the channels of a corner are one interleaved record,
+ * and {@link vgeo_layers_like} is what guarantees the two records line up.
+ *
+ * @param {BinaryTopology} target
+ * @param {BinaryTopology} source
+ * @param {number} source_loop
+ * @param {number} target_loop
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function vgeo_layers_copy_corner(target: BinaryTopology, source: BinaryTopology, source_loop: number, target_loop: number): void;
+//# sourceMappingURL=vgeo_layers_copy_corner.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"vgeo_layers_copy_corner.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/geometry/virtual/format/attribute/vgeo_layers_copy_corner.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;GAaG;AACH,qGANW,MAAM,eACN,MAAM,QAoBhB"}

package/src/shade/renderer/geometry/virtual/format/attribute/{vgeo_layers_copy_vertex.js → vgeo_layers_copy_corner.js}

@@ -1,23 +1,23 @@
 import { assert } from "../../../../../../core/assert.js";
 
 /**
- * Copy one vertex's every channel between two meshes declared from the same template.
+ * Copy one corner's every channel between two meshes declared from the same template.
  *
- * One run of bytes, not one call per channel: the channels of a vertex are one interleaved record,
+ * One run of bytes, not one call per channel: the channels of a corner are one interleaved record,
  * and {@link vgeo_layers_like} is what guarantees the two records line up.
  *
  * @param {BinaryTopology} target
  * @param {BinaryTopology} source
- * @param {number} source_vertex
- * @param {number} target_vertex
+ * @param {number} source_loop
+ * @param {number} target_loop
  *
  * @author Alex Goldring
  * @copyright Company Named Limited (c) 2026
  */
-export function vgeo_layers_copy_vertex(target, source, source_vertex, target_vertex) {
-    const target_data = target.vertex_data;
+export function vgeo_layers_copy_corner(target, source, source_loop, target_loop) {
+    const target_data = target.loop_data;
 
-    const source_data = source.vertex_data;
+    const source_data = source.loop_data;
 
     if (target_data === null) {
         // a geometry with position and nothing else — there is no record to move
@@ -28,5 +28,5 @@ export function vgeo_layers_copy_vertex(target, source, source_vertex, target_ve
 
     assert.notNull(source_data, 'target was declared with channels the source does not carry');
 
-    target_data.copy_record(target_vertex, source_data, source_vertex);
+    target_data.copy_record(target_loop, source_data, source_loop);
 }

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

@@ -1,14 +1,25 @@
 /**
- * Declare vertex data layers on a topology for the channels `carried` marks.
+ * Declare loop data layers on a topology for the channels `carried` marks.
  *
- * The vertex attributes a `.vgeo` carries live as vertex data layers on the `BinaryTopology` the
- * builder simplifies, rather than beside it, because that is the only place a per-vertex value can
- * survive what the builder does to a mesh: an edge collapse frees vertices, and the topology is
- * what knows when. A layer is addressed by vertex id and sized by the vertex pool, so a channel is
- * never a slot short of the mesh it describes and never has to be resized by hand.
+ * The attributes a `.vgeo` carries live on the `BinaryTopology` the builder simplifies rather than
+ * beside it, because that is the only place a value can survive what the builder does to a mesh: a
+ * collapse frees vertices and kills faces, and the topology is what knows when. A layer is sized by
+ * its pool, so a channel is never a slot short of the mesh it describes and never has to be resized
+ * by hand.
+ *
+ * **On loops — corners — and not on vertices.** A vertex has one position and the surface has one
+ * shape there, but it does not have one *appearance*: a hard edge and a texture seam are both a
+ * single geometric vertex that shades two ways, and a per-vertex record cannot hold that. Welding
+ * the position is what the clusterer needs and splitting the appearance is what the artist authored,
+ * and those are different questions (`WEDGE_PLAN_2026_09_18.md` §2). `bt_loop_uv` reached the same
+ * place for the same reason, and `bt_mesh_compact` already compacts loop data with everything else.
+ *
+ * What a *loop* is rather than a vertex costs is duplication — three records per triangle against
+ * roughly one per two — and buys the only representation a seam has.
  *
  * Position is not among them. It lives in the topology's own vertex record, where the quadric solve
- * moves it; keeping a second copy here would only be a copy to keep in step.
+ * moves it — and it is the one value that genuinely is the vertex's, which is the whole distinction
+ * this storage is drawn along.
  *
  * The returned *channel set* is an array with one slot per {@link VGEO_ATTRIBUTES} entry, holding
  * that channel's layer or null where the geometry does not carry it — the format has a fixed,

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

@@ -1 +1 @@
-{"version":3,"file":"vgeo_layers_declare.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/geometry/virtual/format/attribute/vgeo_layers_declare.js"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,uEANW,OAAO,EAAE,GACP,CAAC,kBAAgB,IAAI,CAAC,EAAE,CAmBpC"}
+{"version":3,"file":"vgeo_layers_declare.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/geometry/virtual/format/attribute/vgeo_layers_declare.js"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,uEANW,OAAO,EAAE,GACP,CAAC,kBAAgB,IAAI,CAAC,EAAE,CAmBpC"}

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

@@ -3,16 +3,27 @@ import { VGEO_ATTRIBUTE } from "./VGEO_ATTRIBUTE.js";
 import { VGEO_ATTRIBUTES } from "./VGEO_ATTRIBUTES.js";
 
 /**
- * Declare vertex data layers on a topology for the channels `carried` marks.
+ * Declare loop data layers on a topology for the channels `carried` marks.
  *
- * The vertex attributes a `.vgeo` carries live as vertex data layers on the `BinaryTopology` the
- * builder simplifies, rather than beside it, because that is the only place a per-vertex value can
- * survive what the builder does to a mesh: an edge collapse frees vertices, and the topology is
- * what knows when. A layer is addressed by vertex id and sized by the vertex pool, so a channel is
- * never a slot short of the mesh it describes and never has to be resized by hand.
+ * The attributes a `.vgeo` carries live on the `BinaryTopology` the builder simplifies rather than
+ * beside it, because that is the only place a value can survive what the builder does to a mesh: a
+ * collapse frees vertices and kills faces, and the topology is what knows when. A layer is sized by
+ * its pool, so a channel is never a slot short of the mesh it describes and never has to be resized
+ * by hand.
+ *
+ * **On loops — corners — and not on vertices.** A vertex has one position and the surface has one
+ * shape there, but it does not have one *appearance*: a hard edge and a texture seam are both a
+ * single geometric vertex that shades two ways, and a per-vertex record cannot hold that. Welding
+ * the position is what the clusterer needs and splitting the appearance is what the artist authored,
+ * and those are different questions (`WEDGE_PLAN_2026_09_18.md` §2). `bt_loop_uv` reached the same
+ * place for the same reason, and `bt_mesh_compact` already compacts loop data with everything else.
+ *
+ * What a *loop* is rather than a vertex costs is duplication — three records per triangle against
+ * roughly one per two — and buys the only representation a seam has.
  *
  * Position is not among them. It lives in the topology's own vertex record, where the quadric solve
- * moves it; keeping a second copy here would only be a copy to keep in step.
+ * moves it — and it is the one value that genuinely is the vertex's, which is the whole distinction
+ * this storage is drawn along.
  *
  * The returned *channel set* is an array with one slot per {@link VGEO_ATTRIBUTES} entry, holding
  * that channel's layer or null where the geometry does not carry it — the format has a fixed,
@@ -37,7 +48,7 @@ export function vgeo_layers_declare(topology, carried) {
             continue;
         }
 
-        result[attribute] = topology.vertex_data_add_layer(
+        result[attribute] = topology.loop_data_add_layer(
             BinaryDataType.Float32, VGEO_ATTRIBUTES[attribute].components
         );
     }

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

@@ -1,9 +1,9 @@
 /**
  * Declare the same channels `template` holds on another topology.
  *
- * Used wherever the builder rebuilds a vertex set — extracting a group, stitching a level — and
- * needs somewhere to copy the old values into. Because the declarations are the same, in the same
- * order, the two blocks share a record layout and a vertex can be moved across as one run of bytes.
+ * Used wherever the builder rebuilds a mesh — extracting a group, stitching a level — and needs
+ * somewhere to copy the old values into. Because the declarations are the same, in the same order,
+ * the two blocks share a record layout and a corner can be moved across as one run of bytes.
  *
  * @param {BinaryTopology} topology receives the layers
  * @param {(BinaryDataLayer|null)[]} template channel set to mirror

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

@@ -3,9 +3,9 @@ import { vgeo_layers_declare } from "./vgeo_layers_declare.js";
 /**
  * Declare the same channels `template` holds on another topology.
  *
- * Used wherever the builder rebuilds a vertex set — extracting a group, stitching a level — and
- * needs somewhere to copy the old values into. Because the declarations are the same, in the same
- * order, the two blocks share a record layout and a vertex can be moved across as one run of bytes.
+ * Used wherever the builder rebuilds a mesh — extracting a group, stitching a level — and needs
+ * somewhere to copy the old values into. Because the declarations are the same, in the same order,
+ * the two blocks share a record layout and a corner can be moved across as one run of bytes.
  *
  * @param {BinaryTopology} topology receives the layers
  * @param {(BinaryDataLayer|null)[]} template channel set to mirror