@woosh/meep-engine 3.29.0 → 3.31.0

package/src/shade/renderer/geometry/geometry_obtain_attribute.js

@@ -0,0 +1,83 @@
+import { Attribute } from "./Attribute.js";
+import { StandardAttributes } from "./StandardAttributes.js";
+
+/**
+ * Get the backing array of one `f32` attribute of a geometry, sized for `count` items, creating the
+ * attribute or resizing it if it is not that size already.
+ *
+ * This is the write-side contract a procedural generator wants: it does not care whether the geometry
+ * has been built before, only that after the call there is an array of the right length to fill.
+ *
+ * One subtlety the shape carries, and the reason it is worth having once rather than three times: the
+ * fresh-creation branch does **not** bump {@link Attribute#version}, and the reuse branch does. A newly
+ * added attribute has no uploaded copy to invalidate; an existing one does. `data` and `count` are also
+ * assigned together, and they have to be — updating one without the other produces a short draw with no
+ * error anywhere.
+ *
+ * The array is **not** preserved across a resize. The caller is expected to write every element.
+ *
+ * @param {Geometry} geometry
+ * @param {string} name attribute name, e.g. one of {@link StandardAttributes}
+ * @param {number} item_size components per vertex
+ * @param {number} count number of vertices
+ * @returns {Float32Array} the attribute's data, to be written in full
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function geometry_obtain_attribute(geometry, name, item_size, count) {
+    const existing = geometry.getAttribute(name);
+
+    if (existing === undefined) {
+        const attribute = Attribute.from(new Float32Array(count * item_size), item_size, name);
+
+        geometry.addAttribute(attribute);
+
+        return attribute.data;
+    }
+
+    if (existing.count !== count) {
+        existing.data = new Float32Array(count * item_size);
+        existing.count = count;
+    }
+
+    existing.needsUpdate = true;
+
+    return existing.data;
+}
+
+/**
+ * Get the backing array of a geometry's index, sized for `count` indices, creating it or resizing it if
+ * it is not that size already. The `u32` counterpart of {@link geometry_obtain_attribute}, with the same
+ * contract, including that the contents are not preserved across a resize.
+ *
+ * `Geometry#index` is initialised to `null` where `getAttribute` falls off the end and returns
+ * `undefined`, which is why the two absence tests here read differently.
+ *
+ * @param {Geometry} geometry
+ * @param {number} count number of indices
+ * @returns {Uint32Array} the index's data, to be written in full
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function geometry_obtain_index(geometry, count) {
+    const existing = geometry.index;
+
+    if (existing === null) {
+        const attribute = Attribute.from(new Uint32Array(count), 1, StandardAttributes.Index);
+
+        geometry.index = attribute;
+
+        return attribute.data;
+    }
+
+    if (existing.count !== count) {
+        existing.data = new Uint32Array(count);
+        existing.count = count;
+    }
+
+    existing.needsUpdate = true;
+
+    return existing.data;
+}

package/src/shade/renderer/geometry/meshlet/GPUMeshletManager.d.ts

@@ -224,6 +224,18 @@ declare class MeshletBatchAllocationRecord {
      * @type {ArrayBuffer}
      */
     metadata_buffer_original: ArrayBuffer;
+    /**
+     * Whether the DEVICE's copy of this record's rows is the authority for `bounds_box`, rather
+     * than {@link metadata_buffer_original}.
+     *
+     * True for a clone: `shader_meshlet_bounds_scatter` and `_reduce` write the per-meshlet boxes
+     * of a skinned instance into its clone rows on the device every frame, and a clone shares its
+     * source's un-patched CPU bytes, which hold the source's REST pose. So a compaction that
+     * re-derives a clone's rows from those bytes throws the deformed boxes away.
+     *
+     * @type {boolean}
+     */
+    device_owns_bounds: boolean;
     /**
      *
      * @type {Signal<>}

package/src/shade/renderer/geometry/meshlet/GPUMeshletManager.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"GPUMeshletManager.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/geometry/meshlet/GPUMeshletManager.js"],"names":[],"mappings":"AAwDA;;;;;;GAMG;AACH,wCAFU,MAAM,CAE4B;AAE5C;;;;;GAKG;AACH,wCAFU,MAAM,CAEqC;AAErD;;;;GAIG;AACH,wCAFU,MAAM,CAE8B;AAE9C;;;;;;;;;;;GAWG;AACH,kDAFU,MAAM,CAE6C;AAE7D;;GAEG;AACH,iDAFU,MAAM,CAEsC;AAqGtD;IA8II;;;;;;;;OAQG;IACH;QAN8B,MAAM;QACR,qBAAqB,GAAtC,MAAM;QACW,yBAAyB,GAA1C,MAAM;QACW,gBAAgB,GAAjC,MAAM;OAuChB;IAxKD,6BAEC;IAOD,iCAEC;IAwED;;OAEG;IACH,8CAEC;IAkFD,gBAOC;IAED;;;;;;;;;;;;;;;;;;;;;OAqBG;IACH,sBAHW,MAAM,uBACN,MAAM,QA2HhB;IA8WD;;;;;;;;;;OAUG;IACH,qBAJW,4BAA4B,GAE1B,OAAO,CAmBnB;IAqED;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA4BG;IACH,eAFW,sBAAsB,QAqChC;IAiND;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACH,+BAHW,4BAA4B,GAC1B,4BAA4B,CAiCxC;IAED;;;;;;;;;;;;OAYG;IACH,gBAFW,sBAAsB,QA8GhC;IAED,gBAGC;IAED;;;;OAIG;IACH,iBAHW,YAAY,GACV,4BAA4B,CA6BxC;IAED,mCASC;IAED,wCAQC;IAED;;;;;;OAMG;IACH,wCAMC;IAED,+BAYC;;CACJ;yBAv/CY,OAAO,sDAAsD,EAAE,UAAU;qCACzE,OAAO,2CAA2C,EAAE,sBAAsB;2BAC1E,OAAO,mBAAmB,EAAE,YAAY;AAiFrD;;;;GAIG;AACH;IACI,gBAAY;IACZ,iBAAa;IACb,cAAU;IACV,qBAAiB;IACjB,yBAAqB;IACrB,yBAAqB;CACxB;AAmDD;IACI;;OAEG;IACH,UAFU,UAAU,CAEZ;IACR;;OAEG;IACH,MAFU,UAAU,CAEhB;IAEJ;;;OAGG;IACH,WAFU,MAAM,CAEF;IAEd;;;OAGG;IACH,eAFU,MAAM,CAEE;IAElB;;;OAGG;IACH,0BAFU,WAAW,CAEI;IAEzB;;;OAGG;IACH,aAAsB;CACzB"}
+{"version":3,"file":"GPUMeshletManager.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/geometry/meshlet/GPUMeshletManager.js"],"names":[],"mappings":"AAoEA;;;;;;GAMG;AACH,wCAFU,MAAM,CAE4B;AAE5C;;;;;GAKG;AACH,wCAFU,MAAM,CAEqC;AAErD;;;;GAIG;AACH,wCAFU,MAAM,CAE8B;AAE9C;;;;;;;;;;;GAWG;AACH,kDAFU,MAAM,CAE6C;AAE7D;;GAEG;AACH,iDAFU,MAAM,CAEsC;AAkHtD;IA8II;;;;;;;;OAQG;IACH;QAN8B,MAAM;QACR,qBAAqB,GAAtC,MAAM;QACW,yBAAyB,GAA1C,MAAM;QACW,gBAAgB,GAAjC,MAAM;OAuChB;IAxKD,6BAEC;IAOD,iCAEC;IAwED;;OAEG;IACH,8CAEC;IAkFD,gBAOC;IAED;;;;;;;;;;;;;;;;;;;;;OAqBG;IACH,sBAHW,MAAM,uBACN,MAAM,QA2HhB;IAkZD;;;;;;;;;;OAUG;IACH,qBAJW,4BAA4B,GAE1B,OAAO,CAmBnB;IAqED;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA4BG;IACH,eAFW,sBAAsB,QAqChC;IAiND;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACH,+BAHW,4BAA4B,GAC1B,4BAA4B,CAqCxC;IAED;;;;;;;;;;;;OAYG;IACH,gBAFW,sBAAsB,QA8GhC;IAED,gBAGC;IAED;;;;OAIG;IACH,iBAHW,YAAY,GACV,4BAA4B,CA6BxC;IAED,mCASC;IAED,wCAQC;IAED;;;;;;OAMG;IACH,wCAMC;IAED,+BAYC;;CACJ;yBAxjDY,OAAO,sDAAsD,EAAE,UAAU;qCACzE,OAAO,2CAA2C,EAAE,sBAAsB;2BAC1E,OAAO,mBAAmB,EAAE,YAAY;AA6FrD;;;;GAIG;AACH;IACI,gBAAY;IACZ,iBAAa;IACb,cAAU;IACV,qBAAiB;IACjB,yBAAqB;IACrB,yBAAqB;CACxB;AAmDD;IACI;;OAEG;IACH,UAFU,UAAU,CAEZ;IACR;;OAEG;IACH,MAFU,UAAU,CAEhB;IAEJ;;;OAGG;IACH,WAFU,MAAM,CAEF;IAEd;;;OAGG;IACH,eAFU,MAAM,CAEE;IAElB;;;OAGG;IACH,0BAFU,WAAW,CAEI;IAEzB;;;;;;;;;;OAUG;IACH,oBAFU,OAAO,CAEU;IAE3B;;;OAGG;IACH,aAAsB;CACzB"}

package/src/shade/renderer/geometry/meshlet/GPUMeshletManager.js

@@ -54,6 +54,18 @@ const ALLOCATION_LIMIT = 128 * 1024;
  */
 const METADATA_ROW_WORDS = MESHLET_METADATA_STRUCT.aligned_size >>> 2;
 
+/**
+ * Bytes one metadata row occupies on the device.
+ * @type {number}
+ */
+const METADATA_ROW_BYTES = MESHLET_METADATA_STRUCT.aligned_size;
+
+/** Where a row's `bounds_box` starts, in bytes. @type {number} */
+const METADATA_BOUNDS_BYTE_OFFSET = MESHLET_METADATA_STRUCT.fields.find(f => f.name === 'bounds_box').offset;
+
+/** How many bytes it occupies. @type {number} */
+const METADATA_BOUNDS_BYTES = MESHLET_METADATA_STRUCT.fields.find(f => f.name === 'bounds_box').type.size;
+
 /**
  * The most records one {@link GPUMeshletManager#sweep} moves. A move is an O(1) slide in the
  * allocator, four copy encodes, `meshlet_count` pairs in a patch table and one `changed`
@@ -189,6 +201,19 @@ class MeshletBatchAllocationRecord {
      */
     metadata_buffer_original;
 
+    /**
+     * Whether the DEVICE's copy of this record's rows is the authority for `bounds_box`, rather
+     * than {@link metadata_buffer_original}.
+     *
+     * True for a clone: `shader_meshlet_bounds_scatter` and `_reduce` write the per-meshlet boxes
+     * of a skinned instance into its clone rows on the device every frame, and a clone shares its
+     * source's un-patched CPU bytes, which hold the source's REST pose. So a compaction that
+     * re-derives a clone's rows from those bytes throws the deformed boxes away.
+     *
+     * @type {boolean}
+     */
+    device_owns_bounds = false;
+
     /**
      *
      * @type {Signal<>}
@@ -673,6 +698,42 @@ export class GPUMeshletManager {
                 new_buffer_metadata
             );
 
+            /*
+             C. ...and then, for a record whose bounds the DEVICE owns, put those back over the
+             rest-pose ones the upload above just wrote.
+
+             `metadata_buffer_original` is the batch's un-patched CPU bytes, and for a CLONE record
+             it is the SOURCE's, so the upload resets every clone's `bounds_box` to the source's
+             rest-pose per-meshlet box. `shader_meshlet_bounds_scatter` and `_reduce` are the only
+             writers of that field for clones and they run on the device — {@link sweep} copies
+             rows GPU to GPU rather than re-deriving them for exactly this reason and says so; it
+             can do that for every record because it is a copy-based path already, and this one is
+             not.
+
+             Without this the HZB meshlet filter tested a deforming mesh's meshlets against a box
+             that no longer contained them and culled things that were on screen: the unsafe
+             direction, on every skinned mesh in the scene at once, until the next bounds pass
+             closed the window a frame later. Compaction is the event that is supposed to be
+             invisible.
+
+             A copy per row, because the field is strided — and only for the records that need it,
+             because a rebuild of a few thousand ordinary batches should not pay per meshlet for a
+             field nothing but the upload ever wrote. On the encoder rather than as a queue write
+             so they ride the command buffer the data moves are already in, and they land after the
+             uploads: a queue write issued before a submit happens before it.
+            */
+            if (record.device_owns_bounds) {
+                for (let i = 0; i < record.meshlet_count; i++) {
+                    encoder.copyBufferToBuffer(
+                        old_buffer_metadata,
+                        (record.metadata.offset + i) * METADATA_ROW_BYTES + METADATA_BOUNDS_BYTE_OFFSET,
+                        new_buffer_metadata,
+                        (new_allocation_metadata.offset + i) * METADATA_ROW_BYTES + METADATA_BOUNDS_BYTE_OFFSET,
+                        METADATA_BOUNDS_BYTES
+                    );
+                }
+            }
+
             // update record
             record.data = new_allocation_data;
             record.metadata = new_allocation_metadata;
@@ -1316,6 +1377,10 @@ export class GPUMeshletManager {
         // the clone's metadata correctly under its new data offset.
         record.metadata_buffer_original = source.metadata_buffer_original;
 
+        // ...but those bytes hold the SOURCE's rest pose, and this record's boxes are written on
+        // the device by the skinning bounds chain every frame. See the field.
+        record.device_owns_bounds = true;
+
         this.#records.add(record);
 
         this.#arena_data.records.set(data.metadata, record);

package/src/shade/renderer/geometry/meshlet/build/geometry_to_meshlets_greedy.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"geometry_to_meshlets_greedy.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/geometry/meshlet/build/geometry_to_meshlets_greedy.js"],"names":[],"mappings":"AAIA;;;;;;;;;;;;GAYG;AACH,oHARW,MAAM,EAAE,qBACR,MAAM,gBACN,MAAM,yBACN,MAAM,2BACN,MAAM,sBACN,WAAW,qBACX,WAAW,QAqJrB"}
+{"version":3,"file":"geometry_to_meshlets_greedy.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/geometry/meshlet/build/geometry_to_meshlets_greedy.js"],"names":[],"mappings":"AAIA;;;;;;;;;;;;GAYG;AACH,oHARW,MAAM,EAAE,qBACR,MAAM,gBACN,MAAM,yBACN,MAAM,2BACN,MAAM,sBACN,WAAW,qBACX,WAAW,QAwJrB"}

package/src/shade/renderer/geometry/meshlet/build/geometry_to_meshlets_greedy.js

@@ -45,7 +45,10 @@ export function geometry_to_meshlets_greedy(
     let meshlet_triangle_count = 0;
     let meshlet_vertex_count = 0;
 
-    let meshlet_vertex_offset = 0;
+    // where writing actually begins, which is not the start of the buffer when the caller is
+    // appending — the documented use, and `startMeshlet` derives the same expression for every
+    // meshlet after the first
+    let meshlet_vertex_offset = result_data.position >>> 2;
     let meshlet_triangle_offset = 0;
 
     // Note that we don't need to clear this between meshlets.

package/src/shade/renderer/geometry/meshlet/build/meshoptimizer/geometry_to_meshlets_meshoptimizer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"geometry_to_meshlets_meshoptimizer.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/geometry/meshlet/build/meshoptimizer/geometry_to_meshlets_meshoptimizer.js"],"names":[],"mappings":"AAGA;;;;;;;;;GASG;AACH,2HAPW,MAAM,EAAE,qBACR,MAAM,gBACN,MAAM,oBACN,YAAY,yBACZ,MAAM,2BACN,MAAM,QA+ChB"}
+{"version":3,"file":"geometry_to_meshlets_meshoptimizer.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/geometry/meshlet/build/meshoptimizer/geometry_to_meshlets_meshoptimizer.js"],"names":[],"mappings":"AAGA;;;;;;;;;GASG;AACH,2HAPW,MAAM,EAAE,qBACR,MAAM,gBACN,MAAM,oBACN,YAAY,yBACZ,MAAM,2BACN,MAAM,QAkDhB"}

package/src/shade/renderer/geometry/meshlet/build/meshoptimizer/geometry_to_meshlets_meshoptimizer.js

@@ -35,7 +35,10 @@ export function geometry_to_meshlets_meshoptimizer(
         const output_vertex_offset = result_data.position >>> 2;
         const output_triangle_offset = output_vertex_offset + vertex_count;
 
-        result_metadata.writeRow(i, [
+        // at the end of the table, not at the meshoptimizer-side ordinal: the reservation above is
+        // `length + meshletCount`, an append, and `i` equals `length` only when the table arrived
+        // empty. The sibling greedy builder writes here too.
+        result_metadata.writeRow(result_metadata.length, [
             output_vertex_offset,
             output_triangle_offset,
             vertex_count,

package/src/shade/renderer/geometry/normals/encode_normals_to_octahedral_u32.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"encode_normals_to_octahedral_u32.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/geometry/normals/encode_normals_to_octahedral_u32.js"],"names":[],"mappings":"AAMA;;;;;;GAMG;AACH,yDALW,MAAM,EAAE,iBACR,MAAM,gBACN,MAAM,iBACN,MAAM,EAAE,QAmClB"}
+{"version":3,"file":"encode_normals_to_octahedral_u32.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/geometry/normals/encode_normals_to_octahedral_u32.js"],"names":[],"mappings":"AAMA;;;;;;GAMG;AACH,yDALW,MAAM,EAAE,iBACR,MAAM,gBACN,MAAM,iBACN,MAAM,EAAE,QAsClB"}

package/src/shade/renderer/geometry/normals/encode_normals_to_octahedral_u32.js

@@ -31,7 +31,10 @@ export function encode_normals_to_octahedral_u32(
         const ny = plain_normals[i3 + 1];
         const nz = plain_normals[i3 + 2];
 
-        //
+        // y and z are swapped on the way in, deliberately: encode_unit_to_octahedron folds on its second
+        // argument (y is the pole, output is (x, z)) while the GPU decoder this feeds,
+        // uv_octahedral_unit_decode, folds on z and emits (x, y). Passing (nx, nz, ny) is what puts the
+        // engine normal into the shader convention.
         encode_unit_to_octahedron(scratch_uv, 0, nx, nz, ny);
 
         const u = scratch_uv[0] * 0.5 + 0.5;

package/src/shade/renderer/geometry/normals/geometry_build_tangents.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"geometry_build_tangents.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/geometry/normals/geometry_build_tangents.js"],"names":[],"mappings":"AAMA;;;;;;;;;;GAUG;AACH,qDARW,MAAM,cACN,MAAM,EAAE,gBACR,MAAM,WACN,MAAM,EAAE,iBACR,MAAM,EAAE,eACR,MAAM,EAAE,gBACR,MAAM,EAAE,QAyJlB"}
+{"version":3,"file":"geometry_build_tangents.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/geometry/normals/geometry_build_tangents.js"],"names":[],"mappings":"AAaA;;;;;;;;;;GAUG;AACH,qDARW,MAAM,cACN,MAAM,EAAE,gBACR,MAAM,WACN,MAAM,EAAE,iBACR,MAAM,EAAE,eACR,MAAM,EAAE,gBACR,MAAM,EAAE,QAwLlB"}

package/src/shade/renderer/geometry/normals/geometry_build_tangents.js

@@ -4,6 +4,13 @@ import { v3_length } from "../../../../core/geom/vec3/v3_length.js";
 import { build_tangent_from_normal } from "./build_tangent_from_normal.js";
 import { compute_tangent_handedness } from "./compute_tangent_handedness.js";
 
+/**
+ * How much of the accumulated tangent has to survive the Gram-Schmidt projection for the result to
+ * mean anything, as a fraction of the tangent own length. Below this the direction is noise.
+ * @type {number}
+ */
+const TANGENT_MINIMUM_RESIDUAL = 1e-6;
+
 /**
  * Based on Eric Lengyel's article "Computing Tangent Space Basis Vectors for an Arbitrary Mesh"
  * @see http://www.terathon.com/code/tangent.html
@@ -145,7 +152,38 @@ export function geometry_build_tangents(
         let tmp_y = tangent_y - normal_y * n_dot_t;
         let tmp_z = tangent_z - normal_z * n_dot_t;
 
-        const tmp_norm = 1 / v3_length(tmp_x, tmp_y, tmp_z);
+        const residual = v3_length(tmp_x, tmp_y, tmp_z);
+
+        /*
+         The residual is what gets divided, and it is zero whenever the accumulated tangent is
+         PARALLEL to the smoothed normal — a different and strictly larger condition than the
+         all-zero tangent the guard above catches. A hard crease whose UV gradient projects onto
+         the vertex normal is exactly that.
+
+         Unchecked, 1 / 0 is Infinity, 0 * Infinity is NaN, and the vertex was written
+         (NaN, NaN, NaN, 1) — the handedness comes out 1 because NaN < 0 is false. The NaN then
+         survived into encode_tangents_to_u32, where Math.floor(NaN * 32767) & 0x7FFF is 0, so it
+         encoded a FIXED WRONG tangent instead of a detectable NaN and the wrongness was baked into
+         the meshlet payload, where nothing at runtime could explain it. The near-degenerate case is
+         worse still: a finite but arbitrary direction, amplified out of whatever noise the residual
+         had left.
+
+         Relative to the tangent, because the accumulated tangent is not normalised. The same
+         fallback the all-zero case takes: a basis built from the normal is arbitrary about its
+         rotation, which is all that is knowable here, and it is perpendicular to the normal, which
+         is what the shading needs.
+        */
+        if (!(residual > TANGENT_MINIMUM_RESIDUAL * v3_length(tangent_x, tangent_y, tangent_z))) {
+            build_tangent_from_normal(
+                normal_x, normal_y, normal_z,
+                i,
+                tangent_data
+            );
+
+            continue;
+        }
+
+        const tmp_norm = 1 / residual;
 
         tmp_x *= tmp_norm;
         tmp_y *= tmp_norm;

package/src/shade/renderer/geometry/util/geometry_merge.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"geometry_merge.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/geometry/util/geometry_merge.js"],"names":[],"mappings":"AAQA;;;;GAIG;AACH,8CAHW,QAAQ,GACN,QAAQ,CAgHpB;yBArHwB,gBAAgB"}
+{"version":3,"file":"geometry_merge.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/geometry/util/geometry_merge.js"],"names":[],"mappings":"AAQA;;;;GAIG;AACH,8CAHW,QAAQ,GACN,QAAQ,CAgIpB;yBArIwB,gBAAgB"}

package/src/shade/renderer/geometry/util/geometry_merge.js

@@ -87,7 +87,22 @@ export function geometry_merge(...geometries) {
 
             const attribute = geometry.getAttribute(attribute_spec.name);
 
-            out.data.set(attribute.data, vertex_offsets[j] * attribute_spec.itemSize);
+            /*
+             Only the elements the attribute CLAIMS, not its whole backing array.
+
+             The totals above come from getVertexCount() and index.count, and this used to copy
+             attribute.data entire — so the function disagreed with itself about which of .count
+             and .data.length is authoritative. They do differ: a buffer allocated generously and
+             never trimmed has elements past its count, which geometry_fix_index documents. The
+             copy then either overran the count-sized output with a RangeError or pushed the next
+             geometry vertices along, leaving stale ones in the merged mesh.
+            */
+            const element_count = attribute.count * attribute_spec.itemSize;
+
+            out.data.set(
+                attribute.data.subarray(0, element_count),
+                vertex_offsets[j] * attribute_spec.itemSize
+            );
         }
 
         out.count = total_vertex_count;
@@ -100,7 +115,8 @@ export function geometry_merge(...geometries) {
     index.spec = AttributeSpec.from(BinaryDataType.Uint32, 1, false);
     index.data = new Uint32Array(total_index_count);
 
-    index.data.set(geometries[0].index.data, 0);
+    // the same: the first geometry index contributes index.count elements, whatever its storage is
+    index.data.set(geometries[0].index.data.subarray(0, geometries[0].index.count), 0);
     index.count = total_index_count;
 
     for (let i = 1; i < geometries.length; i++) {

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

@@ -222,18 +222,99 @@ Distilled from the pixel-error musings
 
 Pinned:
 
-- **Error is an object-space distance from the *source* surface**, not a density heuristic
-  and not a sum of per-step deviations. It is measured before faceless vertices are cleaned
-  away, so that a patch consumed whole — which leaves nothing behind to be measured — still
-  costs what it cost. Vertex quadrics are built once from the source
-  triangles and carried through the entire build: a survivor absorbs its victim's quadric at
-  every collapse, at every round, so a vertex many rounds up still holds the planes of every
-  source triangle folded into it, and evaluating that quadric at its current position
-  measures deviation from what was authored. The quadric also carries its accumulated
-  **weight**, and the error is normalized by it before the square root — without that,
-  `evaluate` is a sum of squared distances whose scale grows with the number of planes in the
-  quadric, and its root is not a length. It remains a calibrated measure rather than a proven
-  Hausdorff bound (blind to tangential drift), hence the sampled-Hausdorff gate in §3.
+- **Error is an upper bound on the object-space distance from the *source* surface** — not an
+  estimate of it, and not a density heuristic. The threshold is a threshold, so wherever the
+  number reads low the cut draws a cluster it should have refined and nothing downstream can
+  tell it did.
+
+  **The quadric cannot be that number, and it is not a tuning question.** Evaluating a carried
+  quadric at a vertex's position gives the *mean* squared distance to the planes it stands for,
+  and a mean is never a bound: a vertex that destroyed one feature and stands for a thousand
+  planes it sits exactly on reports the feature divided by all of them. Measured against the
+  distance the surface had actually moved, sampled at the source vertices, the quadric reading
+  came back at `0.34` of it on a closed pyramid, `0.58` on an octahedron, `0.62` on a spike
+  standing off a plane, and `0.03`–`0.62` across a cone swept in height. Reading it at the
+  collapses rather than after the pass, and per endpoint rather than summed, narrows *when* it
+  is diluted and not *that* it is.
+
+  So the quadrics stay, and they decide **where** a collapse puts the vertex, which is what they
+  are good at. What it **cost** is a separate scalar carried per vertex, composed by the triangle
+  inequality at every collapse:
+
+  ```
+  bound[survivor] = max( bound[v1], bound[v2] ) + how far this collapse moved the surface
+  ```
+
+  Zero at the source, carried across levels beside the quadrics, combined across steps by
+  `max` — two steps sharing a pinned boundary vertex each produce a valid bound on what that
+  step folded into it, so it carries the larger. No gains-minus-results, which is a quadric
+  problem.
+
+- **The increment is how far the *surface* moved, not how far the vertices went.** A vertex
+  sliding within its own plane moves and the surface does not, and flat geometry is mostly
+  that — charging movement makes a flat wall refine forever, which is the one thing this metric
+  is not allowed to do (the flat-wall test below, that density heuristics were rejected on).
+  Measured, charging movement reported `15.9` where the surface had moved `0.98`, and `41.6`
+  on the same shape with a larger plane around it: the old dilution's mirror image, growing
+  with surface that never moved. So the increment is the distance from each endpoint's former
+  position to the survivor's one-ring — the geometry now standing where that surface was —
+  which the sliding case leaves sitting exactly on. With no one-ring left the patch was
+  consumed whole, there is nothing to measure against, and the movement is the only evidence
+  there is.
+
+  **Exactly zero, where it is zero.** A point nearer a triangle than the `float32` coordinates
+  can express is on it, and is reported as `0` rather than as the `1.6e-14` the closest-point
+  solve returns. Not pedantry: `project((s, 0)) === 0` is an explicit case and the
+  camera-inside-sphere `+∞` rule is conditioned on `r_e > 0`, so a flat cluster carrying
+  `1.6e-14` becomes undrawable at close range.
+
+  Measured against the surface's own movement: `1.00` on a closed pyramid and an octahedron,
+  `1.08` and `1.10` on a spike standing off a 13- and a 25-vertex plane — conservative
+  everywhere and within ten per cent of tight, and **not growing with the plane around it**.
+  Still sampled at vertices rather than over triangle interiors, so the sampled-Hausdorff gate
+  in §3 still earns its place.
+
+  **It costs nothing at a fixed budget.** The numbers rise — the arch primitive's root goes from
+  `3.786e-2` to `2.031e-1`, which is the old one having been that optimistic — so a given τ
+  buys a finer cut, and a caller who wants the old cluster count asks for a larger τ. At *equal
+  drawn cluster count* the picture is the same or better: `-9.3%`, `-6.7%`, `-6.4%`, `-3.1%`
+  of mean luminance against the old metric over a 16x range of cut depth. The ordering the cut
+  descends is preserved; what changed is what the number on it means.
+
+  Superseded: "a calibrated measure rather than a proven Hausdorff bound", and the whole of the
+  carried-quadric reading as the reported error. The carrying was right and stays; reading the
+  error off it was the mistake.
+- **Each pass reports what its own collapses cost**, and a caller carrying the bound across
+  passes carries it across them too (`vgeo_build_group_step` across its attempts, the frontier
+  across levels, the child-error floor below as a backstop). A vertex that arrives already
+  deviating needs no re-reading: it arrives carrying its own bound.
+
+  Superseded: sweeping the surviving vertices after the pass, "before faceless vertices are
+  cleaned away, so that a patch consumed whole still costs what it cost". The measurement point
+  was right about the faceless vertex — it is read at the collapse that consumed it now — and
+  the sweep threw away every sharper reading to get there.
+
+  **Open.** Whether τ converts *accurately* to conservative pixels is still not measured, only
+  the object-space half of it is. `container_diff` measures how different the picture looks,
+  which has no unit relationship to a pixel threshold; what would answer it is a readback of
+  world position at the cut and at LOD 0, projected, worst case in pixels against τ. Until that
+  exists, "conservative" here means the object-space bound above.
+- **A plane weighs the surface behind it, as a multiple of the mesh's mean triangle.** The
+  mean the error is read as has to be an average over the *surface*; over a plane count it is
+  an average over how the surface was cut, and a finely tessellated patch outvotes a coarse
+  one many times its size. Cutting one face in two along its own plane is the clean statement
+  of the defect — it adds no surface, and the metric heard the same plane twice. Weights are
+  ratios rather than areas because everything they are stated against is a ratio (the boundary
+  constraint is three *faces*; the attribute quadric summed with these weighs one per
+  triangle), and a slot holding square metres would make all of it depend on whether the asset
+  was authored in millimetres or kilometres. The reported error is a mean, which divides the
+  weights out again, so normalizing costs nothing there; it buys back every calibration.
+
+  This changes the quadric **matrix**, so it changes the placement solve and not only the
+  number — a behavioural change to simplification, landed on its own so it can be attributed.
+  `VGEO_DEFAULT_ATTRIBUTE_WEIGHT_RATIOS` was calibrated against the diluted reading and is
+  **not** re-tuned here; it needs re-tuning against this one, separately.
+
 - **Composition across levels does not happen**, and that is the point of carrying quadrics.
   The measured value is already deviation from the source; a step takes `max(measured, max(e
   of child groups))`, where the floor exists only to impose monotonicity — the accumulated

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

@@ -1,4 +1,94 @@
-# Wedges — plan, 2026-09-18
+# Wedges — plan, 2026-09-18 — **HALF OF IT REVERTED 2026-09-19**
+
+> **The partition stayed. The crease angle went.** This document was written as one idea and it is
+> two, and only one of them survived being measured in pixels.
+>
+> **What went: inferring a hard edge from an angle.** `VGEO_CREASE_ANGLE`, 45 degrees, applied
+> where the builder has to *synthesize* a normal because the source authored none. It made a
+> POSITION-only cube ship three normals at each corner instead of one that is 54.7 degrees wrong for
+> every face using it, which is a real improvement to look at. Measured against a true LOD 0
+> reference it bought nothing on any object tested, and on high-frequency relief it *cost*: the
+> attribute quadric's least-squares fit lands near the neighbourhood's mean normal, which is the
+> right filtered answer for a Lambertian surface, and bucketing each tile face on its own returns
+> that one face's normal exactly instead. It was also most of the price — on the pebble-scatter
+> geometry the wedge build cost +3.37% of asset bytes over pre-attribute with the threshold in and
+> +0.97% without it.
+>
+> **What stayed: carrying the shading frame a source actually authored.** `BtWedgeSet`,
+> `vgeo_mesh_wedges`, and the simplifier's wedge bookkeeping. The partition is decided by
+> `loop_data.record_equal()` — byte equality of what the source gave — so it needs no threshold and
+> makes no judgement about content. On a UE5 courtyard gate arch (188,180 triangles, authored
+> normals and UVs), taking it out costs, at **equal drawn cluster count**, mean luminance against
+> that build's own LOD 0:
+>
+> | ue_arch | τ=0.5 | τ=1 | τ=2 | τ=4 |
+> |---|---|---|---|---|
+> | without the partition | +1.18 | +6.50 | +6.91 | +8.82 |
+> | *same build, second page load* | −0.06 | +0.07 | +0.06 | +0.06 |
+>
+> That is 20–27% more error against a noise floor of 0.07, and it reproduces. At τ=0.5, 1 and 2 the
+> build without the partition is not even trading: it draws **more** clusters *and* errs more. Only
+> τ=4 is a real trade (−20% clusters for +27% error), and interpolated it sits on the same curve.
+>
+> **It is a normals result, not a UV one.** The playground binds one untextured grey
+> `StandardShadeMaterial` and samples no maps, so nothing in that table can come from texture
+> coordinates. Seams are carried by the same mechanism and that is worth having, but it is a
+> different question and it is not what was measured here.
+>
+> **And it helps where the frame is synthesized too**, now that the threshold is gone. Corners still
+> group, by connectivity rather than by angle: at a mesh boundary or a non-manifold fin there is no
+> second face to average with, so each side keeps its own normal instead of inventing a join the
+> mesh does not make. On the pebble scatter that costs +0.45% of bytes over having no partition at
+> all, and buys — again at equal drawn clusters, against pre-attribute —
+>
+> | mesh 1400 | τ=0.5 | τ=1 | τ=2 | τ=4 |
+> |---|---|---|---|---|
+> | no partition | +1.55 | +4.87 | +5.42 | +7.08 |
+> | partition, no threshold | +4.95 | **+4.03** | **−2.51** | **−5.30** |
+>
+> Pareto-dominant at τ=1, 2 and 4 — fewer clusters *and* less error — and at the two coarse cuts it
+> beats pre-attribute outright. The finest cut is worse, and that is the honest caveat.
+>
+> **The split is proved by byte identity, not only by pixels.** Built with the threshold removed,
+> the gate arch is byte-identical to the full wedge build (the whole win preserved, nothing else
+> changed), and a UE5 throne-room floor is byte-identical to a build with no wedge code at all.
+>
+> **What this does *not* claim.** Not that the N-dimensional attribute quadrics are themselves a
+> pixel win — measured the same way they are a wash-to-worse on three of five objects, and that
+> deserves its own investigation. Not that Zorah's normals are fine: on a POSITION-only source every
+> normal is synthesized by `vgeo_normalize_source`, area-weighted, after the weld, nothing pinned,
+> so a hard edge cannot exist at *any* level including the finest — that is the flat-looking tiled
+> surface, it is upstream of everything here, and the UE5 rebuild is what fixes it. And not that the
+> cut is free: on that floor, pre-attribute draws 80 clusters where both attribute builds draw 513
+> at the same τ, a 6x difference nobody asked for.
+>
+> **The pixel harness is the other thing worth keeping** (`container_diff.mjs`, scratchpad pattern).
+> Four ways it lied before it worked, each of which had already produced a confident wrong answer:
+>
+> 1. **TAA.** Two captures of one static camera differ by mean 4.0 with *not one pixel identical*.
+>    Pinning the jitter is necessary and insufficient — the resolve un-jitters against its own copy,
+>    so one run settles to 0.004 and an identical one plateaus at 0.153 forever. Average 16 frames.
+> 2. **Dilution.** The object covered 1–2% of the viewport, so every mean read 0.2–0.7 with p95 of
+>    exactly 0.0. Mask to lit pixels and print the coverage.
+> 3. **The stats panel**, which prints the file name and byte counts and so differs per build by
+>    construction — and the crop keeping it out was slicing through the object.
+> 4. **Cross-run image diffs are worthless.** The same build in two page loads, with identical
+>    `drawn` counts, differs by mean 15–17. Only a build's *own* LOD-0 curve is comparable.
+>
+> A whole scene has no reachable LOD 0 either: below about τ=0.25 the residency budget picks the cut
+> and at τ→0 the renderer stops producing frames, so single containers are the only honest reference.
+>
+> **Compare at equal drawn clusters, never at equal τ**, which is a request and not a price — the
+> wedge build drew 1,085 where pre-attribute drew 772 at the same number on the slider.
+>
+> **Choosing what to measure was half the work.** Three rounds of picking objects out of
+> `object_bounds` gave a pebble scatter, a bare tree and a set of beams, all nearly pure silhouette,
+> and the difference image is then an outline with black interiors — which says nothing about
+> shading, since attribute quadrics trade geometric accuracy for attribute accuracy. Manifest rows
+> are `(mesh, primitive)`; carry the primitive or you build a different object, as a row claiming
+> 289k triangles did when it built 2.04M. The UE5 rebuild's meshes have *names*, which is worth more
+> than any heuristic over bounds.
+
 
 `ATTRIBUTE_PLAN_2026_09_18.md` §7, taken up. That plan fixed *how a coarse vertex is given its
 shading values*; this one fixes the fact that a vertex can only hold **one set of them**, so every

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

@@ -81,19 +81,6 @@ export class VGeoBuildOptions {
      * @type {number}
      */
     weld_ratio: number;
-    /**
-     * How far two triangles may turn across a shared edge before a **synthesized** normal is split
-     * there rather than averaged, in degrees. See {@link VGEO_CREASE_ANGLE}, which is where the
-     * default and the measurement behind it live.
-     *
-     * A build option rather than only a constant because it is the one number in this work that is a
-     * judgement about content rather than a consequence of arithmetic: a source of hard-surface
-     * props and a source of organic scans want different answers, and a conversion should be able to
-     * say which it has.
-     *
-     * @type {number}
-     */
-    crease_angle: number;
     /**
      * Decoded bytes per page, as a **hard cap**: no page of the asset exceeds it, and the container
      * says so with a feature bit a runtime can require (`VGEO_FORMAT.md` §11.14). That is what makes

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

@@ -1 +1 @@
-{"version":3,"file":"VGeoBuildOptions.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/geometry/virtual/build/VGeoBuildOptions.js"],"names":[],"mappings":"AAOA;;;;;GAKG;AACH;IACI;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACH,OAFU,MAAM,CAEW;IAE3B;;;;;;;;;;;;;;;;;;OAkBG;IACH,aAFU,MAAM,CAEmB;IAEnC;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA4BG;IACH,YAFU,MAAM,CAEE;IAElB;;;;;;;;;;;OAWG;IACH,cAFU,MAAM,CAEiB;IAEjC;;;;;;;;;;;;;;OAcG;IACH,mBAFU,MAAM,CAE2B;IAE3C;;;;;;;;;;;;;;;;;;;OAmBG;IACH,yBAFU,MAAM,EAAE,CAEqD;IAEvE;;OAEG;IACH,eAFU,gBAAgB,CAEa;CAC1C;iCAjJgC,6BAA6B"}
+{"version":3,"file":"VGeoBuildOptions.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/geometry/virtual/build/VGeoBuildOptions.js"],"names":[],"mappings":"AAMA;;;;;GAKG;AACH;IACI;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACH,OAFU,MAAM,CAEW;IAE3B;;;;;;;;;;;;;;;;;;OAkBG;IACH,aAFU,MAAM,CAEmB;IAEnC;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA4BG;IACH,YAFU,MAAM,CAEE;IAElB;;;;;;;;;;;;;;OAcG;IACH,mBAFU,MAAM,CAE2B;IAE3C;;;;;;;;;;;;;;;;;;;OAmBG;IACH,yBAFU,MAAM,EAAE,CAEqD;IAEvE;;OAEG;IACH,eAFU,gBAAgB,CAEa;CAC1C;iCAnIgC,6BAA6B"}

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

@@ -1,4 +1,3 @@
-import { VGEO_CREASE_ANGLE } from "./mesh/VGEO_CREASE_ANGLE.js";
 import { LZ4_LEVEL } from "../../../../../core/binary/lz4/LZ4_LEVEL.js";
 import { VGEO_DEFAULT_ATTRIBUTE_WEIGHT_RATIOS } from "./mesh/VGEO_DEFAULT_ATTRIBUTE_WEIGHT_RATIOS.js";
 import { VGEO_CODEC_DEFLATE } from "../format/frame/VGEO_CODEC_DEFLATE.js";
@@ -91,20 +90,6 @@ export class VGeoBuildOptions {
      */
     weld_ratio = 1e-5;
 
-    /**
-     * How far two triangles may turn across a shared edge before a **synthesized** normal is split
-     * there rather than averaged, in degrees. See {@link VGEO_CREASE_ANGLE}, which is where the
-     * default and the measurement behind it live.
-     *
-     * A build option rather than only a constant because it is the one number in this work that is a
-     * judgement about content rather than a consequence of arithmetic: a source of hard-surface
-     * props and a source of organic scans want different answers, and a conversion should be able to
-     * say which it has.
-     *
-     * @type {number}
-     */
-    crease_angle = VGEO_CREASE_ANGLE;
-
     /**
      * Decoded bytes per page, as a **hard cap**: no page of the asset exceeds it, and the container
      * says so with a feature bit a runtime can require (`VGEO_FORMAT.md` §11.14). That is what makes

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

@@ -1 +1 @@
-{"version":3,"file":"gltf_collect_geometries.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/geometry/virtual/build/gltf/gltf_collect_geometries.js"],"names":[],"mappings":"AA0NA;;;;;;;;;;GAUG;AACH,mGAHa;IAAC,UAAU,EAAE,YAAY,EAAE,CAAC;IAAC,MAAM,EAAE,iBAAiB,CAAA;CAAC,CAqEnE;6BA7R4B,mBAAmB;kCADd,wBAAwB"}
+{"version":3,"file":"gltf_collect_geometries.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/geometry/virtual/build/gltf/gltf_collect_geometries.js"],"names":[],"mappings":"AAuPA;;;;;;;;;;GAUG;AACH,mGAHa;IAAC,UAAU,EAAE,YAAY,EAAE,CAAC;IAAC,MAAM,EAAE,iBAAiB,CAAA;CAAC,CAqEnE;6BA1T4B,mBAAmB;kCADd,wBAAwB"}