@woosh/meep-engine 3.44.0 → 3.46.0

package/src/engine/physics/cloth/solver/cloth_particle_coupling.js

@@ -0,0 +1,133 @@
+import { assert } from "../../../../core/assert.js";
+import { csr_build_incidence } from "../../../../core/graph/csr/csr_build_incidence.js";
+
+/**
+ * The particle graph a cloth's rows imply: an edge between every two particles
+ * that share a row, as a sorted CSR adjacency.
+ *
+ * A stretch row couples its two endpoints; a bend stencil couples all six pairs
+ * of its four particles, since every one of them appears in the same row. Two
+ * build-time consumers want exactly this set — the colouring, where an edge is
+ * a pair that must not be updated at once (`cloth_color_particles.js`), and the
+ * self-collision exclusions, where it is a pair a row already governs
+ * (`cloth_self_find.js`) — and this is the one place it is built.
+ *
+ * The set is deduplicated, because a garment adds every hinge's shared edge
+ * once as a stretch row and again as a bend pair, so duplicates are the common
+ * case; and a row that names one particle twice couples nothing. Each particle's
+ * partners come out ascending, which is the contract the exclusion scans read.
+ *
+ * Build-time only: it allocates its result and a scratch the size of the
+ * half-edge list.
+ *
+ * @param {number} particle_count
+ * @param {Int32Array|number[]} stretch_particle particle index pairs, 2 per row
+ * @param {number} stretch_count
+ * @param {Int32Array|number[]} bend_particle particle index quads, 4 per row
+ * @param {number} bend_count
+ * @returns {{offset: Int32Array, partner: Int32Array}} `partner[offset[i] .. offset[i + 1])` are the
+ *   particles sharing a row with `i`, ascending, without `i` itself
+ */
+export function cloth_particle_coupling(
+    particle_count,
+    stretch_particle, stretch_count,
+    bend_particle, bend_count
+) {
+    assert.isNonNegativeInteger(particle_count, 'particle_count');
+    assert.isNonNegativeInteger(stretch_count, 'stretch_count');
+    assert.isNonNegativeInteger(bend_count, 'bend_count');
+
+    // Both directions of every coupled pair, duplicates and all.
+    const capacity = stretch_count * 2 + bend_count * 12;
+
+    const from = new Int32Array(capacity);
+    const to = new Int32Array(capacity);
+
+    let half_edge_count = 0;
+
+    for (let row = 0; row < stretch_count; row++) {
+        const a = stretch_particle[row * 2];
+        const b = stretch_particle[row * 2 + 1];
+
+        assert.ok(a >= 0 && a < particle_count, `stretch row ${row} particle 0 (=${a}) out of range`);
+        assert.ok(b >= 0 && b < particle_count, `stretch row ${row} particle 1 (=${b}) out of range`);
+
+        if (a !== b) {
+            from[half_edge_count] = a;
+            to[half_edge_count++] = b;
+            from[half_edge_count] = b;
+            to[half_edge_count++] = a;
+        }
+    }
+
+    for (let row = 0; row < bend_count; row++) {
+        const base = row * 4;
+
+        for (let i = 0; i < 4; i++) {
+            const a = bend_particle[base + i];
+
+            assert.ok(a >= 0 && a < particle_count, `bend row ${row} particle ${i} (=${a}) out of range`);
+
+            for (let j = i + 1; j < 4; j++) {
+                const b = bend_particle[base + j];
+
+                if (a !== b) {
+                    from[half_edge_count] = a;
+                    to[half_edge_count++] = b;
+                    from[half_edge_count] = b;
+                    to[half_edge_count++] = a;
+                }
+            }
+        }
+    }
+
+    const offset = new Int32Array(particle_count + 1);
+    const partner = new Int32Array(half_edge_count);
+
+    csr_build_incidence(offset, partner, from, half_edge_count, particle_count);
+
+    // half-edge index to the particle at its far end
+    for (let k = 0; k < half_edge_count; k++) {
+        partner[k] = to[partner[k]];
+    }
+
+    // Sort each particle's partners and drop the repeats, compacting in place.
+    // The write cursor never passes the read cursor, so an entry is always read
+    // before anything is written over it.
+    let written = 0;
+
+    for (let particle = 0; particle < particle_count; particle++) {
+        const start = offset[particle];
+        const end = offset[particle + 1];
+
+        offset[particle] = written;
+
+        const row_start = written;
+
+        for (let k = start; k < end; k++) {
+            const value = partner[k];
+
+            // insertion into the sorted run `[row_start, written)`, skipping a value already there
+            let j = written - 1;
+
+            while (j >= row_start && partner[j] > value) {
+                j--;
+            }
+
+            if (j >= row_start && partner[j] === value) {
+                continue;
+            }
+
+            for (let m = written; m > j + 1; m--) {
+                partner[m] = partner[m - 1];
+            }
+
+            partner[j + 1] = value;
+            written++;
+        }
+    }
+
+    offset[particle_count] = written;
+
+    return { offset, partner: partner.slice(0, written) };
+}

package/src/engine/physics/cloth/solver/cloth_particle_of_source.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Invert {@link ClothState#source_of_particle}: for every source vertex, the
+ * particle it became.
+ *
+ * `ClothState.from` permutes particles into colour order, so anything built
+ * against the source mesh — a triangle list, a joint layout, a node table —
+ * names the wrong particles until it is read through this map.
+ *
+ * @param {Int32Array} out particle of every source vertex, `particle_count` entries
+ * @param {Int32Array} source_of_particle source vertex of every particle, a permutation
+ *   of `[0, particle_count)`
+ * @param {number} particle_count
+ * @returns {void}
+ */
+export function cloth_particle_of_source(out: Int32Array, source_of_particle: Int32Array, particle_count: number): void;
+//# sourceMappingURL=cloth_particle_of_source.d.ts.map

package/src/engine/physics/cloth/solver/cloth_particle_of_source.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cloth_particle_of_source.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/cloth/solver/cloth_particle_of_source.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,8CANW,UAAU,sBACV,UAAU,kBAEV,MAAM,GACJ,IAAI,CAMhB"}

package/src/engine/physics/cloth/solver/cloth_particle_of_source.js

@@ -0,0 +1,19 @@
+/**
+ * Invert {@link ClothState#source_of_particle}: for every source vertex, the
+ * particle it became.
+ *
+ * `ClothState.from` permutes particles into colour order, so anything built
+ * against the source mesh — a triangle list, a joint layout, a node table —
+ * names the wrong particles until it is read through this map.
+ *
+ * @param {Int32Array} out particle of every source vertex, `particle_count` entries
+ * @param {Int32Array} source_of_particle source vertex of every particle, a permutation
+ *   of `[0, particle_count)`
+ * @param {number} particle_count
+ * @returns {void}
+ */
+export function cloth_particle_of_source(out, source_of_particle, particle_count) {
+    for (let particle = 0; particle < particle_count; particle++) {
+        out[source_of_particle[particle]] = particle;
+    }
+}

package/src/engine/physics/cloth/solver/cloth_self_find.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cloth_self_find.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/cloth/solver/cloth_self_find.js"],"names":[],"mappings":"AA4DA;;;;;GAKG;AACH,0DAFa;IAAC,MAAM,EAAE,UAAU,CAAC;IAAC,OAAO,EAAE,UAAU,CAAA;CAAC,CA0DrD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,4EANW;IAAC,MAAM,EAAE,UAAU,CAAC;IAAC,OAAO,EAAE,UAAU,CAAA;CAAC,UACzC,MAAM,GAGJ,MAAM,CAgHlB;AAED;;;;;;GAMG;AACH,+DAHW;IAAC,MAAM,EAAE,UAAU,CAAC;IAAC,OAAO,EAAE,UAAU,CAAA;CAAC,GACvC,MAAM,CAyJlB;AA1aD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AAEH;;;;;;;;;;;;;;;;;GAiBG;AACH,4CAFU,MAAM,CAE+B"}
+{"version":3,"file":"cloth_self_find.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/cloth/solver/cloth_self_find.js"],"names":[],"mappings":"AA6DA;;;;;GAKG;AACH,0DAFa;IAAC,MAAM,EAAE,UAAU,CAAC;IAAC,OAAO,EAAE,UAAU,CAAA;CAAC,CAQrD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,4EANW;IAAC,MAAM,EAAE,UAAU,CAAC;IAAC,OAAO,EAAE,UAAU,CAAA;CAAC,UACzC,MAAM,GAGJ,MAAM,CAgHlB;AAED;;;;;;GAMG;AACH,+DAHW;IAAC,MAAM,EAAE,UAAU,CAAC;IAAC,OAAO,EAAE,UAAU,CAAA;CAAC,GACvC,MAAM,CAyJlB;AAxXD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AAEH;;;;;;;;;;;;;;;;;GAiBG;AACH,4CAFU,MAAM,CAE+B"}

package/src/engine/physics/cloth/solver/cloth_self_find.js

@@ -1,4 +1,5 @@
 import { PointHashGrid3 } from "../../../../core/geom/3d/hash-grid/PointHashGrid3.js";
+import { cloth_particle_coupling } from "./cloth_particle_coupling.js";
 
 /**
  * # Finding the self-collision pairs, once per step
@@ -65,61 +66,11 @@ export const CLOTH_SELF_PAIRS_PER_PARTICLE = 8;
  * @returns {{offset: Int32Array, partner: Int32Array}} CSR, sorted within each particle
  */
 export function cloth_self_exclusions(state) {
-    const particle_count = state.particle_count;
-
-    /** @type {Set<number>[]} */
-    const sets = new Array(particle_count);
-
-    for (let i = 0; i < particle_count; i++) {
-        sets[i] = new Set();
-    }
-
-    /**
-     * @param {number} a
-     * @param {number} b
-     */
-    const link = (a, b) => {
-        if (a === b) {
-            return;
-        }
-
-        sets[a].add(b);
-        sets[b].add(a);
-    };
-
-    for (let row = 0; row < state.stretch_count; row++) {
-        link(state.stretch_particle[row * 2], state.stretch_particle[row * 2 + 1]);
-    }
-
-    for (let row = 0; row < state.bend_count; row++) {
-        const base = row * 4;
-
-        for (let a = 0; a < 4; a++) {
-            for (let b = a + 1; b < 4; b++) {
-                link(state.bend_particle[base + a], state.bend_particle[base + b]);
-            }
-        }
-    }
-
-    const offset = new Int32Array(particle_count + 1);
-
-    let total = 0;
-
-    for (let i = 0; i < particle_count; i++) {
-        total += sets[i].size;
-
-        offset[i + 1] = total;
-    }
-
-    const partner = new Int32Array(total);
-
-    for (let i = 0; i < particle_count; i++) {
-        const sorted = Array.from(sets[i]).sort((a, b) => a - b);
-
-        partner.set(sorted, offset[i]);
-    }
-
-    return { offset, partner };
+    return cloth_particle_coupling(
+        state.particle_count,
+        state.stretch_particle, state.stretch_count,
+        state.bend_particle, state.bend_count
+    );
 }
 
 /**

package/src/engine/physics/cloth/solver/cloth_solve_vertex.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cloth_solve_vertex.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/cloth/solver/cloth_solve_vertex.js"],"names":[],"mappings":"AAgFA;;;;;;;;;;;;;GAaG;AACH,gEANW,MAAM,qBACN,MAAM,mBACN,YAAY,GAAC,YAAY,GAAC,IAAI,QAgIxC"}
+{"version":3,"file":"cloth_solve_vertex.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/cloth/solver/cloth_solve_vertex.js"],"names":[],"mappings":"AAmFA;;;;;;;;;;;;;GAaG;AACH,gEANW,MAAM,qBACN,MAAM,mBACN,YAAY,GAAC,YAAY,GAAC,IAAI,QA0FxC"}

package/src/engine/physics/cloth/solver/cloth_solve_vertex.js

@@ -1,4 +1,5 @@
 import { assert } from "../../../../core/assert.js";
+import { matrix_symmetric_3x3_solve_ldlt } from "../../../../core/math/linalg/matrix_symmetric_3x3_solve_ldlt.js";
 import { cloth_backstop_accumulate } from "./constraint/cloth_backstop_row.js";
 import { cloth_bend_accumulate } from "./constraint/cloth_bend_row.js";
 import { cloth_contact_accumulate } from "./constraint/cloth_contact_row.js";
@@ -7,16 +8,11 @@ import { cloth_self_accumulate } from "./constraint/cloth_self_row.js";
 import { cloth_stretch_accumulate } from "./constraint/cloth_stretch_row.js";
 import {
     CVA_F_X,
-    CVA_F_Y,
-    CVA_F_Z,
     CVA_H_XX,
-    CVA_H_XY,
-    CVA_H_XZ,
-    CVA_H_YY,
     CVA_H_YZ,
-    CVA_H_ZZ,
     CVA_TRUST,
-    CVA_STRIDE
+    CVA_STRIDE,
+    cloth_vertex_accumulator_seed
 } from "./cloth_vertex_accumulator.js";
 
 /**
@@ -78,6 +74,13 @@ import {
  */
 const ACCUMULATOR = new Float64Array(CVA_STRIDE);
 
+/**
+ * The Newton step `H⁻¹f`, scratch for the same call.
+ * @type {Float64Array}
+ * @private
+ */
+const DELTA = new Float64Array(3);
+
 /**
  * Update one particle in place.
  *
@@ -104,24 +107,9 @@ export function cloth_solve_vertex(state, particle, inverse_h_squared, collider_
 
     const p = particle * 3;
 
-    // m/h², the inertial term's weight. Positive and finite whenever the
-    // particle has a mass at all, which is what makes `H` positive definite
-    // rather than merely semidefinite.
-    const mass_over_h_squared = inverse_h_squared / inverse_mass;
-
     const accumulator = ACCUMULATOR;
 
-    accumulator[CVA_F_X] = -mass_over_h_squared * (position[p] - inertial[p]);
-    accumulator[CVA_F_Y] = -mass_over_h_squared * (position[p + 1] - inertial[p + 1]);
-    accumulator[CVA_F_Z] = -mass_over_h_squared * (position[p + 2] - inertial[p + 2]);
-
-    accumulator[CVA_H_XX] = mass_over_h_squared;
-    accumulator[CVA_H_YY] = mass_over_h_squared;
-    accumulator[CVA_H_ZZ] = mass_over_h_squared;
-    accumulator[CVA_H_XY] = 0;
-    accumulator[CVA_H_XZ] = 0;
-    accumulator[CVA_H_YZ] = 0;
-    accumulator[CVA_TRUST] = Infinity;
+    cloth_vertex_accumulator_seed(accumulator, position, inertial, p, inverse_h_squared / inverse_mass);
 
     cloth_stretch_accumulate(accumulator, state, particle);
     cloth_bend_accumulate(accumulator, state, particle);
@@ -136,53 +124,30 @@ export function cloth_solve_vertex(state, particle, inverse_h_squared, collider_
         cloth_self_accumulate(accumulator, state, particle);
     }
 
-    const a = accumulator[CVA_H_XX];
-    const b = accumulator[CVA_H_XY];
-    const c = accumulator[CVA_H_XZ];
-    const d = accumulator[CVA_H_YY];
-    const e = accumulator[CVA_H_YZ];
-    const f = accumulator[CVA_H_ZZ];
-
-    // LDLᵀ of the symmetric matrix [[a,b,c],[b,d,e],[c,e,f]], not a cofactor
-    // inverse. The two agree in exact arithmetic and do not agree in Float64:
-    // a vertex with one very stiff row and a small mass term assembles an `H`
-    // with a condition number in the billions, and the cofactor determinant —
-    // a sum of triple products that has to cancel down by that ratio squared —
-    // comes out *negative* on a matrix whose eigenvalues are all positive. The
-    // factorisation never forms those products, so its pivots stay positive
-    // where the determinant does not, and their product is the determinant to
-    // full precision.
-    const pivot_x = a;
-    const lower_yx = b / pivot_x;
-    const lower_zx = c / pivot_x;
-
-    const pivot_y = d - lower_yx * b;
-    const lower_zy = (e - lower_zx * b) / pivot_y;
-
-    const pivot_z = f - lower_zx * c - lower_zy * lower_zy * pivot_y;
-
-    // The pivots of an SPD matrix are its `H` restricted to nested subspaces,
-    // so all three positive *is* positive definiteness — the same claim §5.3
-    // makes, checked where it is actually used. The message is built only when the check fails: as
-    // an argument it was a string of four numbers per vertex per iteration.
-    if (!(pivot_x > 0 && pivot_y > 0 && pivot_z > 0)) {
+    // LDLᵀ, not a cofactor inverse: a vertex with one very stiff row and a
+    // small mass term assembles an `H` with a condition number in the billions,
+    // whose cofactor determinant comes out negative though every eigenvalue is
+    // positive (the core function carries the argument). The `H` slots are laid
+    // out `[xx, yy, zz, xy, xz, yz]`, which is the packing it reads.
+    //
+    // Its pivot check — all three positive *is* positive definiteness — is the
+    // same claim §5.3 makes, checked where it is actually used. A shipped build
+    // strips the assert and leaves the particle where it is rather than moving
+    // it by a solve of an indefinite system.
+    if (!matrix_symmetric_3x3_solve_ldlt(DELTA, 0, accumulator, CVA_H_XX, accumulator, CVA_F_X)) {
+        // The message is built only when the check fails: as an argument it
+        // was a string of numbers per vertex per iteration.
         assert.ok(
             false,
-            `cloth vertex ${particle}: H is not positive definite (pivots ${pivot_x}, ${pivot_y}, ${pivot_z}) — the SPD-by-construction argument of §5.3 has been broken`
+            `cloth vertex ${particle}: H is not positive definite (H ${accumulator.subarray(CVA_H_XX, CVA_H_YZ + 1).join(', ')}) — the SPD-by-construction argument of §5.3 has been broken`
         );
-    }
 
-    const force_x = accumulator[CVA_F_X];
-    const force_y = accumulator[CVA_F_Y];
-    const force_z = accumulator[CVA_F_Z];
-
-    // Forward substitution through L, scale by D, back substitution through Lᵀ.
-    const forward_y = force_y - lower_yx * force_x;
-    const forward_z = force_z - lower_zx * force_x - lower_zy * forward_y;
+        return;
+    }
 
-    const delta_z = forward_z / pivot_z;
-    const delta_y = forward_y / pivot_y - lower_zy * delta_z;
-    const delta_x = force_x / pivot_x - lower_yx * delta_y - lower_zx * delta_z;
+    const delta_x = DELTA[0];
+    const delta_y = DELTA[1];
+    const delta_z = DELTA[2];
 
     // Trust region. `H⁻¹f` is a descent direction — that is what positive
     // definiteness buys — but a *full* Newton step is only a descent *step*

package/src/engine/physics/cloth/solver/cloth_step.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cloth_step.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/cloth/solver/cloth_step.js"],"names":[],"mappings":"AAgCA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgIG;AAEH;;;;;;;;;;;;;;;;;;GAkBG;AACH,kDAfW,MAAM,kBACN,MAAM,kBAEN,MAAM,kBACN,MAAM,YACN,MAAM,cACN,MAAM,mBACN,YAAY,GAAC,YAAY,GAAC,IAAI,mBAE9B,MAAM,WACN;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAC;IAAC,UAAU,CAAC,EAAE,MAAM,CAAA;CAAC,aAC3G,YAAY,GAAC,IAAI,QAkI3B"}
+{"version":3,"file":"cloth_step.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/cloth/solver/cloth_step.js"],"names":[],"mappings":"AAkCA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgIG;AAEH;;;;;;;;;;;;;;;;;;GAkBG;AACH,kDAfW,MAAM,kBACN,MAAM,kBAEN,MAAM,kBACN,MAAM,YACN,MAAM,cACN,MAAM,mBACN,YAAY,GAAC,YAAY,GAAC,IAAI,mBAE9B,MAAM,WACN;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAC;IAAC,UAAU,CAAC,EAAE,MAAM,CAAA;CAAC,aAC3G,YAAY,GAAC,IAAI,QAkI3B"}

package/src/engine/physics/cloth/solver/cloth_step.js

@@ -1,4 +1,6 @@
 import { assert } from "../../../../core/assert.js";
+import { array_compute_max } from "../../../../core/collection/array/array_compute_max.js";
+import { clamp01 } from "../../../../core/math/clamp01.js";
 import { cloth_collider_pose_at } from "../collider/cloth_collider_sdf.js";
 import { CLOTH_HOLD_LINE_WORDS, cloth_hold_line_fit, cloth_hold_line_turn } from "./cloth_hold_line.js";
 import { cloth_solve_vertex } from "./cloth_solve_vertex.js";
@@ -408,17 +410,9 @@ function cloth_held_velocity(state, p, inverse_h) {
  * @private
  */
 function max_inverse_mass(state) {
-    const mass_inverse = state.mass_inverse;
-
-    let worst = 0;
-
-    for (let i = 0; i < state.particle_count; i++) {
-        if (mass_inverse[i] > worst) {
-            worst = mass_inverse[i];
-        }
-    }
+    const worst = array_compute_max(state.mass_inverse, 0, state.particle_count);
 
-    // Every particle pinned: nothing can move, so the stiffness is unused and
+    // Every particle pinned, or no particles at all: nothing can move, so the stiffness is unused and
     // any finite value is as good as another.
     return worst > 0 ? worst : 1;
 }
@@ -622,15 +616,7 @@ function cloth_integrate(state, inverse_h, acceleration_x, acceleration_y, accel
             (next_y - velocity[p + 1]) * acceleration_y +
             (next_z - velocity[p + 2]) * acceleration_z;
 
-        let blend = realised * inverse_h * inverse_acceleration_squared;
-
-        if (blend < 0) {
-            blend = 0;
-        } else if (blend > 1) {
-            blend = 1;
-        }
-
-        inertia_blend[i] = blend;
+        inertia_blend[i] = clamp01(realised * inverse_h * inverse_acceleration_squared);
 
         velocity[p] = next_x;
         velocity[p + 1] = next_y;
@@ -694,15 +680,7 @@ function cloth_integrate_varying(state, inverse_h, external) {
             // {@link cloth_integrate} uses — the two differ in the last bit, and
             // a cloth whose external acceleration happens to be exactly gravity
             // should follow the same trajectory whichever loop stepped it.
-            let blend = realised * inverse_h * (1 / acceleration_squared);
-
-            if (blend < 0) {
-                blend = 0;
-            } else if (blend > 1) {
-                blend = 1;
-            }
-
-            inertia_blend[i] = blend;
+            inertia_blend[i] = clamp01(realised * inverse_h * (1 / acceleration_squared));
         } else {
             // No direction to project onto, so nothing to seed. The uniform
             // path reaches this for the whole cloth at once; here it is a

package/src/engine/physics/cloth/solver/cloth_step_instance.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cloth_step_instance.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/cloth/solver/cloth_step_instance.js"],"names":[],"mappings":"AA4IA;;;;;;;;;GASG;AACH,wEANW;IAAC,MAAM,EAAE,UAAU,CAAC;IAAC,OAAO,EAAE,UAAU,CAAA;CAAC,GAAC,IAAI,UAE9C,YAAY,UACZ,MAAM,GACJ,IAAI,CA6DhB;;;;6BAtJS,MAAM;;;;;;;;;;;;;;;;;;AA2EhB;;;GAGG;AACH,sCAFU,MAAM,CAE0B"}
+{"version":3,"file":"cloth_step_instance.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/cloth/solver/cloth_step_instance.js"],"names":[],"mappings":"AA6IA;;;;;;;;;GASG;AACH,wEANW;IAAC,MAAM,EAAE,UAAU,CAAC;IAAC,OAAO,EAAE,UAAU,CAAA;CAAC,GAAC,IAAI,UAE9C,YAAY,UACZ,MAAM,GACJ,IAAI,CA6DhB;;;;6BAtJS,MAAM;;;;;;;;;;;;;;;;;;AA2EhB;;;GAGG;AACH,sCAFU,MAAM,CAE0B"}

package/src/engine/physics/cloth/solver/cloth_step_instance.js

@@ -1,3 +1,4 @@
+import { vector_scale_offset } from "../../../../core/geom/vec/vector_scale_offset.js";
 import { cloth_contact_find } from "./cloth_contact_find.js";
 import { cloth_self_find } from "./cloth_self_find.js";
 import { cloth_step } from "./cloth_step.js";
@@ -229,9 +230,7 @@ function damp(state, retention) {
 
     const velocity = state.velocity;
 
-    for (let i = 0; i < velocity.length; i++) {
-        velocity[i] *= retention;
-    }
+    vector_scale_offset(velocity, 0, velocity, 0, velocity.length, retention);
 }
 
 /**

package/src/engine/physics/cloth/solver/cloth_stretch_residual.d.ts

@@ -0,0 +1,21 @@
+/**
+ * The worst relative error over a cloth's stretch rows, `max |C|/L₀` with
+ * `C = ‖x_a − x_b‖ − L₀` — §7 P2's rubber number. Zero when every row sits at
+ * its rest length; `0.1` when the worst one is ten percent off, long or short.
+ *
+ * A row of zero rest length has no relative error to speak of and is skipped,
+ * so a cloth with no rows, or only such rows, reads zero. A row with a NaN end
+ * reads NaN and so does the answer, whatever the other rows say: the callers
+ * gate on `Number.isFinite`, and a broken state must not read as converged.
+ *
+ * A diagnostic for specs, measurements and the playgrounds; nothing in the
+ * step reads it.
+ *
+ * @param {ClothState} state
+ * @returns {number} dimensionless
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function cloth_stretch_residual(state: ClothState): number;
+//# sourceMappingURL=cloth_stretch_residual.d.ts.map

package/src/engine/physics/cloth/solver/cloth_stretch_residual.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cloth_stretch_residual.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/cloth/solver/cloth_stretch_residual.js"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;GAkBG;AACH,2DALa,MAAM,CAoClB"}

package/src/engine/physics/cloth/solver/cloth_stretch_residual.js

@@ -0,0 +1,54 @@
+import { v3_length } from "../../../../core/geom/vec3/v3_length.js";
+import { max2_exact } from "../../../../core/math/max2_exact.js";
+
+/**
+ * The worst relative error over a cloth's stretch rows, `max |C|/L₀` with
+ * `C = ‖x_a − x_b‖ − L₀` — §7 P2's rubber number. Zero when every row sits at
+ * its rest length; `0.1` when the worst one is ten percent off, long or short.
+ *
+ * A row of zero rest length has no relative error to speak of and is skipped,
+ * so a cloth with no rows, or only such rows, reads zero. A row with a NaN end
+ * reads NaN and so does the answer, whatever the other rows say: the callers
+ * gate on `Number.isFinite`, and a broken state must not read as converged.
+ *
+ * A diagnostic for specs, measurements and the playgrounds; nothing in the
+ * step reads it.
+ *
+ * @param {ClothState} state
+ * @returns {number} dimensionless
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function cloth_stretch_residual(state) {
+    const stretch_count = state.stretch_count;
+
+    const stretch_particle = state.stretch_particle;
+    const stretch_rest = state.stretch_rest;
+    const position = state.position;
+
+    let worst = 0;
+
+    for (let row = 0; row < stretch_count; row++) {
+        const rest = stretch_rest[row];
+
+        if (!(rest > 0)) {
+            continue;
+        }
+
+        const a = stretch_particle[row * 2] * 3;
+        const b = stretch_particle[row * 2 + 1] * 3;
+
+        const length = v3_length(
+            position[a] - position[b],
+            position[a + 1] - position[b + 1],
+            position[a + 2] - position[b + 2]
+        );
+
+        const residual = Math.abs(length - rest) / rest;
+
+        worst = max2_exact(worst, residual);
+    }
+
+    return worst;
+}

package/src/engine/physics/cloth/solver/cloth_vertex_accumulator.d.ts

@@ -1,3 +1,18 @@
+/**
+ * Seed an accumulator with the inertial term alone, before any row adds to it:
+ * the force `−(m/h²)(x − y)`, the Hessian `(m/h²)·I`, and no trust bound yet.
+ *
+ * `m/h²` is positive and finite whenever the particle has a mass at all, which
+ * is what makes the assembled `H` positive definite rather than merely
+ * semidefinite.
+ *
+ * @param {Float64Array} accumulator {@link CVA_STRIDE} slots, overwritten
+ * @param {Float32Array} position particle positions, 3 per particle
+ * @param {Float32Array} inertial predicted positions `y`, 3 per particle
+ * @param {number} p the particle's first component index, `particle · 3`
+ * @param {number} mass_over_h_squared `m/h²`
+ */
+export function cloth_vertex_accumulator_seed(accumulator: Float64Array, position: Float32Array, inertial: Float32Array, p: number, mass_over_h_squared: number): void;
 /**
  * # The per-vertex `(f, H)` accumulator
  *

package/src/engine/physics/cloth/solver/cloth_vertex_accumulator.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cloth_vertex_accumulator.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/cloth/solver/cloth_vertex_accumulator.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,gBAAgB;AAChB,wBAAyB;AACzB,gBAAgB;AAChB,wBAAyB;AACzB,gBAAgB;AAChB,wBAAyB;AACzB,yBAAyB;AACzB,yBAA0B;AAC1B,yBAAyB;AACzB,yBAA0B;AAC1B,yBAAyB;AACzB,yBAA0B;AAC1B,mCAAmC;AACnC,yBAA0B;AAC1B,mCAAmC;AACnC,yBAA0B;AAC1B,mCAAmC;AACnC,yBAA0B;AAE1B;;;;;;;;;;GAUG;AACH,0BAA2B;AAE3B,gCAAgC;AAChC,4BAA6B"}
+{"version":3,"file":"cloth_vertex_accumulator.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/cloth/solver/cloth_vertex_accumulator.js"],"names":[],"mappings":"AAyDA;;;;;;;;;;;;;GAaG;AACH,2DANW,YAAY,YACZ,YAAY,YACZ,YAAY,KACZ,MAAM,uBACN,MAAM,QAchB;AAnFD;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,gBAAgB;AAChB,wBAAyB;AACzB,gBAAgB;AAChB,wBAAyB;AACzB,gBAAgB;AAChB,wBAAyB;AACzB,yBAAyB;AACzB,yBAA0B;AAC1B,yBAAyB;AACzB,yBAA0B;AAC1B,yBAAyB;AACzB,yBAA0B;AAC1B,mCAAmC;AACnC,yBAA0B;AAC1B,mCAAmC;AACnC,yBAA0B;AAC1B,mCAAmC;AACnC,yBAA0B;AAE1B;;;;;;;;;;GAUG;AACH,0BAA2B;AAE3B,gCAAgC;AAChC,4BAA6B"}

package/src/engine/physics/cloth/solver/cloth_vertex_accumulator.js

@@ -54,3 +54,31 @@ export const CVA_TRUST = 9;
 
 /** Slots in one accumulator. */
 export const CVA_STRIDE = 10;
+
+/**
+ * Seed an accumulator with the inertial term alone, before any row adds to it:
+ * the force `−(m/h²)(x − y)`, the Hessian `(m/h²)·I`, and no trust bound yet.
+ *
+ * `m/h²` is positive and finite whenever the particle has a mass at all, which
+ * is what makes the assembled `H` positive definite rather than merely
+ * semidefinite.
+ *
+ * @param {Float64Array} accumulator {@link CVA_STRIDE} slots, overwritten
+ * @param {Float32Array} position particle positions, 3 per particle
+ * @param {Float32Array} inertial predicted positions `y`, 3 per particle
+ * @param {number} p the particle's first component index, `particle · 3`
+ * @param {number} mass_over_h_squared `m/h²`
+ */
+export function cloth_vertex_accumulator_seed(accumulator, position, inertial, p, mass_over_h_squared) {
+    accumulator[CVA_F_X] = -mass_over_h_squared * (position[p] - inertial[p]);
+    accumulator[CVA_F_Y] = -mass_over_h_squared * (position[p + 1] - inertial[p + 1]);
+    accumulator[CVA_F_Z] = -mass_over_h_squared * (position[p + 2] - inertial[p + 2]);
+
+    accumulator[CVA_H_XX] = mass_over_h_squared;
+    accumulator[CVA_H_YY] = mass_over_h_squared;
+    accumulator[CVA_H_ZZ] = mass_over_h_squared;
+    accumulator[CVA_H_XY] = 0;
+    accumulator[CVA_H_XZ] = 0;
+    accumulator[CVA_H_YZ] = 0;
+    accumulator[CVA_TRUST] = Infinity;
+}

package/src/engine/physics/cloth/solver/cloth_worst_tether_ratio.d.ts

@@ -0,0 +1,30 @@
+/**
+ * How far the cloth has stretched away from its root, as the worst ratio over
+ * nodes of straight-line distance from node 0 to the fabric between them:
+ * `max ‖x_node − x_0‖ / d_geo(node)` over nodes `1 .. node_count − 1` — §7 P2's
+ * measure. At most 1 for a cloth that has not over-stretched anywhere, since no
+ * straight line is longer than the fabric it spans; `1.05` is a node five
+ * percent further out than the cloth reaches.
+ *
+ * Everything is measured from node 0, the root of the seeder's tree, which is
+ * where the rigs this was written for are held. A cloth held in several places
+ * wants each node measured from its own hold instead, and this is not that
+ * measure.
+ *
+ * A node at a NaN position reads NaN and so does the answer, whatever the other
+ * nodes say, so a broken state cannot pass for a well-behaved one.
+ *
+ * Takes the arrays rather than a `ClothInstance` so the solver side does not
+ * depend on the ECS one.
+ *
+ * @param {Float32Array|Float64Array} position 3 per particle
+ * @param {Int32Array|Uint32Array|number[]} particle_of_node particle index per node
+ * @param {Float32Array|Float64Array|number[]} geodesic fabric distance from node 0 per node, metres
+ * @param {number} node_count
+ * @returns {number} dimensionless; 0 for a cloth of fewer than two nodes
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function cloth_worst_tether_ratio(position: Float32Array | Float64Array, particle_of_node: Int32Array | Uint32Array | number[], geodesic: Float32Array | Float64Array | number[], node_count: number): number;
+//# sourceMappingURL=cloth_worst_tether_ratio.d.ts.map