@woosh/meep-engine 3.30.0 → 3.32.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

@@ -1,4 +1,9 @@
 /**
+ * Needs meshoptimizer's WASM, which instantiates asynchronously at import. A build before it has
+ * fails inside the vendored module, on an instance that is not there yet, with a message about
+ * `exports` that names nothing the caller did — so await `MeshoptClusterizer.ready` before the
+ * first call.
+ *
  * @param {RowFirstTable} result_metadata
  * @param {BinaryBuffer} result_data
  * @param {number[]} input_index Index array

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":"AAgBA;;;;;;;;;;;;;;GAcG;AACH,2HAPW,MAAM,EAAE,qBACR,MAAM,gBACN,MAAM,oBACN,YAAY,yBACZ,MAAM,2BACN,MAAM,QAmDhB"}

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

@@ -1,7 +1,25 @@
+import { assert } from "../../../../../../core/assert.js";
 import { MeshoptClusterizer } from "./meshopt_clusterizer.js";
 import { meshopt_optimizeMeshlet } from "./meshopt_optimizeMeshlet.js";
 
 /**
+ * Whether meshoptimizer's WASM has landed. The vendored module instantiates it asynchronously at
+ * import and exposes only the promise, so this holds the promise's outcome for the assertion below.
+ *
+ * @type {boolean}
+ */
+let clusterizer_ready = false;
+
+MeshoptClusterizer.ready?.then(() => {
+    clusterizer_ready = true;
+});
+
+/**
+ * Needs meshoptimizer's WASM, which instantiates asynchronously at import. A build before it has
+ * fails inside the vendored module, on an instance that is not there yet, with a message about
+ * `exports` that names nothing the caller did — so await `MeshoptClusterizer.ready` before the
+ * first call.
+ *
  * @param {RowFirstTable} result_metadata
  * @param {BinaryBuffer} result_data
  * @param {number[]} input_index Index array
@@ -21,6 +39,7 @@ export function geometry_to_meshlets_meshoptimizer(
     meshlet_vertex_limit = 64,
     meshlet_triangle_limit = 64,
 ) {
+    assert.ok(clusterizer_ready, 'meshoptimizer is not ready; await MeshoptClusterizer.ready');
 
     const meshlets = MeshoptClusterizer.buildMeshlets(input_index, vertex_positions, 3, meshlet_vertex_limit, meshlet_triangle_limit, 0.0);
 
@@ -35,7 +54,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,45 +222,83 @@ 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. 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.
-- **It is read at the collapses, per endpoint, and kept as a running maximum** — not as one
-  sweep of the surviving vertices at the end of a pass. The weight that makes the number a
-  length is also a divisor that grows every time a vertex absorbs another, so a vertex that
-  destroyed a feature and then spent the rest of the pass swallowing surface it sits exactly
-  on has that feature divided by all of it. The dilution therefore deepens with the DAG, and
-  understates most at the coarse levels where the cut spends its budget: measured on a unit
-  spike at the centre of a pinned grid, the same spike came back at `0.64` on a 7-vertex grid
-  and at `0.040` on a 33-vertex one. Read at each collapse the same spike reads `0.65`–`0.71`
-  at every size. Reading the two endpoints apart rather than summed is the same argument one
-  collapse at a time — the sum's reading is the weighted mean of the two, which averages a
-  small victim's residual into a large survivor's untouched history.
-
-  Nothing is given up by no longer sweeping the survivors, and it is a domination rather than
-  a coincidence. What the sweep reads off a survivor is its *merged* quadric at the placement
-  its last collapse chose, and a merged quadric's reading is the weight-weighted mean of its two
-  parts' readings at the same point — so it can never exceed the larger of the two already taken
-  there. Every value the sweep could report is one this maximum has seen or beaten, and the
-  maximum holds the earlier and sharper readings besides. A patch consumed whole, which leaves
-  behind a faceless vertex the cleanup then sweeps away, is likewise read at the collapse that
-  consumed it.
-
-  Each pass therefore reports what *its own* collapses cost, and a caller carrying quadrics
-  across passes carries the maximum across them too (`vgeo_build_group_step` across its
-  attempts, and the child floor below across levels). A vertex that arrives already deviating
-  needs no re-reading: that reading is what the pass which placed it there already returned.
-
-  Superseded: measuring 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 and wrong about everything the sweep threw away to get there.
+- **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

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"}

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

@@ -139,11 +139,12 @@ function select_meshes(gltf, selection, selected_nodes) {
 }
 
 /**
+ * @param {object} gltf resolved
  * @param {object} primitive
  * @param {GltfCollectReport} report
  * @returns {boolean} whether this primitive is a geometry the builder can convert
  */
-function primitive_is_usable(primitive, report) {
+function primitive_is_usable(gltf, primitive, report) {
     if ((primitive.mode ?? GLTF_PRIMITIVE_MODE_DEFAULT) !== GLTF_PRIMITIVE_MODE.TRIANGLES) {
         report.skip('primitive is not a triangle list');
 
@@ -175,6 +176,34 @@ function primitive_is_usable(primitive, report) {
         }
     }
 
+    /*
+     glTF §3.7.2.1: every attribute accessor of a primitive has the same count. A document that
+     breaks it — a truncated export, or normals re-exported after a weld — reads as far as POSITION
+     says and past the end of every shorter channel, and an index past a Float32Array is undefined,
+     which stores INTO a Float32Array as NaN. A NaN normal survives everything after it:
+     `v3_normalize_array` leaves it alone, `vgeo_normalize_source` does not re-derive the channel
+     because the channel WAS carried, and the collapse touches attribute channels only in the
+     shading-frame recompute for vertices that are not pinned — so it reaches the payload encoder,
+     octahedral-encodes to a garbage word, and the asset validates and ships.
+
+     Refused like every other primitive this cannot read, on the same (mesh, primitive) list, rather
+     than drawn wrongly.
+    */
+    const position_count = gltf.accessors[primitive.attributes.POSITION].count;
+
+    for (const name of Object.keys(primitive.attributes)) {
+        const accessor = gltf.accessors[primitive.attributes[name]];
+
+        if (accessor === undefined || accessor.count !== position_count) {
+            report.skip(
+                `primitive's ${name} accessor holds ${accessor?.count} elements`
+                + ` against POSITION's ${position_count}`
+            );
+
+            return false;
+        }
+    }
+
     return true;
 }
 
@@ -251,7 +280,7 @@ export function gltf_collect_geometries(document, selection) {
         const mesh = meshes[mesh_index];
 
         mesh.primitives.forEach((primitive, primitive_index) => {
-            if (!primitive_is_usable(primitive, report)) {
+            if (!primitive_is_usable(gltf, primitive, report)) {
                 return;
             }
 

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

@@ -38,6 +38,24 @@ export class VGeoFrontier {
      * @type {Quadric3[]}
      */
     quadrics: Quadric3[];
+    /**
+     * How far each vertex of {@link mesh} already sits from the source surface, carried unbroken
+     * from it the way {@link quadrics} is — and for the opposite reason.
+     *
+     * The quadric is what the placement is chosen by, and it is a *mean* over the planes a vertex
+     * stands for, so it is not a bound on anything: a vertex that destroyed one feature and stands
+     * for a thousand planes it sits exactly on reports the feature divided by all of them. This is
+     * the bound, composed at every collapse by the triangle inequality, and it is the number the
+     * cut's threshold is a threshold on.
+     *
+     * Combined across steps by **max**, not by the gains-minus-results the quadrics need. Two steps
+     * sharing a pinned boundary vertex leave it exactly where it is, so neither adds movement to it
+     * — and where both fold victims into it, each result is separately a valid bound on what that
+     * step folded in, so the vertex has to carry the larger.
+     *
+     * @type {Float64Array}
+     */
+    bounds: Float64Array;
     /**
      * Which of the mesh's channels travel through a collapse, and where each one sits in
      * {@link attribute_values}. Constant for a whole build — the channel set is the source's.

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

@@ -1 +1 @@
-{"version":3,"file":"VGeoFrontier.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/geometry/virtual/build/level/VGeoFrontier.js"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH;IACI;;OAEG;IACH,0BAAY;IAEZ;;OAEG;IACH,UAFU,wBAAwB,CAEpB;IAEd;;;OAGG;IACH,eAFU,MAAM,EAAE,EAAE,CAED;IAEnB;;;;;;;;;;;;;;OAcG;IACH,UAFU,UAAU,CAEN;IAEd;;;;OAIG;IACH,kBAFU;QAAC,UAAU,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE;YAAC,SAAS,EAAE,MAAM,CAAC;YAAC,MAAM,EAAE,MAAM,CAAC;YAAC,KAAK,EAAE,MAAM,CAAA;SAAC,EAAE,CAAA;KAAC,CAE3C;IAEnD;;;;;OAKG;IACH,mBAFU,YAAY,CAEkB;IAExC;;;;;;;;;;;;;;;OAeG;IACH,oBAFU,YAAY,CAEmB;IAEzC;;;;;;;;;;OAUG;IACH,mBAAc;CAEjB"}
+{"version":3,"file":"VGeoFrontier.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/geometry/virtual/build/level/VGeoFrontier.js"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH;IACI;;OAEG;IACH,0BAAY;IAEZ;;OAEG;IACH,UAFU,wBAAwB,CAEpB;IAEd;;;OAGG;IACH,eAFU,MAAM,EAAE,EAAE,CAED;IAEnB;;;;;;;;;;;;;;OAcG;IACH,UAFU,UAAU,CAEN;IAEd;;;;;;;;;;;;;;;;OAgBG;IACH,QAFU,YAAY,CAEO;IAE7B;;;;OAIG;IACH,kBAFU;QAAC,UAAU,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE;YAAC,SAAS,EAAE,MAAM,CAAC;YAAC,MAAM,EAAE,MAAM,CAAC;YAAC,KAAK,EAAE,MAAM,CAAA;SAAC,EAAE,CAAA;KAAC,CAE3C;IAEnD;;;;;OAKG;IACH,mBAFU,YAAY,CAEkB;IAExC;;;;;;;;;;;;;;;OAeG;IACH,oBAFU,YAAY,CAEmB;IAEzC;;;;;;;;;;OAUG;IACH,mBAAc;CAEjB"}