@woosh/meep-engine 3.21.0 → 3.23.0

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

@@ -0,0 +1,448 @@
+import { PointHashGrid3 } from "../../../../core/geom/3d/hash-grid/PointHashGrid3.js";
+
+/**
+ * # Finding the self-collision pairs, once per step
+ *
+ * A uniform hash grid over the particles in the cloth's own frame, then for each
+ * particle the ones near it that are not already governed by a row. Rebuilt
+ * whole every step, exactly like the contact set (`cloth_contact_find.js`) and
+ * for the same reasons: one pass in a fixed order, so the step is deterministic.
+ *
+ * ## Adjacent pairs are excluded, and "adjacent" means "shares a row"
+ *
+ * §9: "Pairs sharing a triangle or an edge are excluded, since they are already
+ * governed by stretch and bend rows and would otherwise fight them." The exact
+ * form of that here is **sharing any row at all** — a stretch row, a bend
+ * stencil, or a chain's skip row, which is a stretch row too. Two particles a
+ * stretch row already holds at 5 cm do not also need a repulsion telling them to
+ * be 8 mm apart, and a bend stencil's four particles are a fold the bend row is
+ * the model of.
+ *
+ * The exclusion set is built **once, at seed**, from the row tables the state
+ * already carries: `cloth_self_exclusions` walks them and produces a sorted CSR
+ * list per particle. Testing a candidate is then a short scan over a handful of
+ * neighbours, which at typical garment topology is 16.8 entries a particle
+ * (`MEASUREMENTS.md` §8) — small enough that a scan beats a hash.
+ *
+ * ## The cell is the row's own diameter, and that fixes the neighbourhood
+ *
+ * Two particles interact when they are closer than `2·self_radius`, so a cell of
+ * exactly that makes the 27-cell walk necessary and sufficient. A larger cell
+ * would visit more candidates for nothing; a smaller one would need a wider
+ * walk, which is the same candidates through more buckets.
+ *
+ * **That radius is the proxy's resolution rather than the fabric's thickness**,
+ * and `ClothState#self_radius` carries why.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+
+/**
+ * Pairs one particle may **originate**, before the rest are dropped.
+ *
+ * A particle in a fold has a few neighbours across the fold and a few along it;
+ * eight is generous for a garment and is what bounds the pair list so a cloth
+ * that crumples into a ball cannot allocate its way out of a frame budget. A
+ * particle at the limit keeps the eight it found first in grid order, which is
+ * arbitrary among equals — and they are equals, because every one of them is
+ * inside the same radius.
+ *
+ * **"Originate", not "is in".** The search emits a pair once, from its lower
+ * index, so this caps how many pairs a particle starts and not how many it ends
+ * up in: a particle can be the *higher* index of any number of them. What the
+ * cap does bound exactly — and the only thing `ClothState` needs it to — is the
+ * length of the whole list, at this many per particle, because every pair is
+ * charged to exactly one of its two ends.
+ * @type {number}
+ */
+export const CLOTH_SELF_PAIRS_PER_PARTICLE = 8;
+
+/**
+ * Build the exclusion lists from a state's persistent rows.
+ *
+ * @param {ClothState} state
+ * @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 };
+}
+
+/**
+ * The closest two particles get **without a row between them**, in whatever pose
+ * the state is in.
+
+ * This is the length that decides how wide a self-collision row may be written,
+ * and it has to be measured rather than assumed. On a triangulated sheet it is
+ * two hops — one hop is a stretch row, the mesh diagonal is a stretch row, and
+ * the two vertices across a diagonal are a bend stencil — so it comes out at
+ * twice the shortest row and the analytic answer and this one agree.
+ *
+ * **A rigged garment is not a sheet and the two do not agree.** Its proxy is a
+ * set of *strips*, and nothing connects one strip to the next: every pair across
+ * the gap between two strips is ungoverned, at whatever distance the artist
+ * placed the joints. That distance has nothing to do with the link length along
+ * a strip, which is what `shortest_row` measures. On the playground's cape they
+ * differ by a factor of two — 8.5 cm across the gap against the 16 cm a sheet's
+ * topology would predict — and a ceiling derived from the link length instead of
+ * measured left the settled cape with three permanently active pairs.
+ * `MEASUREMENTS.md` §37.
+ *
+ * Pinned particles are skipped, exactly as {@link cloth_self_find} skips them,
+ * so this measures the pairs the row can actually act on and nothing else.
+ *
+ * @param {ClothState} state
+ * @param {{offset: Int32Array, partner: Int32Array}} exclusions from {@link cloth_self_exclusions}
+ * @param {number} search only pairs closer than this are looked for; the walk is
+ *   bounded by it, and a proxy with nothing that close gets `Infinity` — which is
+ *   the right answer, because then no radius inside the bound can touch anything
+ * @returns {number} metres, or `Infinity`
+ */
+export function cloth_self_closest_free_pair(state, exclusions, search) {
+    const particle_count = state.particle_count;
+
+    if (!(search > 0) || particle_count < 2) {
+        return Infinity;
+    }
+
+    GRID.build(state.position, particle_count, search);
+
+    const position = state.position;
+    const mass_inverse = state.mass_inverse;
+
+    const offset = exclusions.offset;
+    const partner = exclusions.partner;
+
+    const grid_offset = GRID.offset;
+    const grid_point = GRID.point;
+
+    const inverse = 1 / search;
+
+    // The walk is a *maybe*: two cells can hash into one bucket, so a bucket can
+    // hand back a point from anywhere. Without this the answer would be the
+    // closest ungoverned pair the table happened to collide into view, which is
+    // a real distance but not the one `search` was asked for.
+    let closest_squared = search * search;
+
+    for (let i = 0; i < particle_count; i++) {
+        if (mass_inverse[i] === 0) {
+            continue;
+        }
+
+        const a = i * 3;
+
+        const x = position[a];
+        const y = position[a + 1];
+        const z = position[a + 2];
+
+        const cx = Math.floor(x * inverse);
+        const cy = Math.floor(y * inverse);
+        const cz = Math.floor(z * inverse);
+
+        const exclude_start = offset[i];
+        const exclude_end = offset[i + 1];
+
+        let visited = 0;
+
+        for (let dz = -1; dz <= 1; dz++) {
+            for (let dy = -1; dy <= 1; dy++) {
+                for (let dx = -1; dx <= 1; dx++) {
+                    const bucket = GRID.bucketOf(cx + dx, cy + dy, cz + dz);
+
+                    let seen = false;
+
+                    for (let v = 0; v < visited; v++) {
+                        if (VISITED[v] === bucket) {
+                            seen = true;
+
+                            break;
+                        }
+                    }
+
+                    if (seen) {
+                        continue;
+                    }
+
+                    VISITED[visited++] = bucket;
+
+                    const end = grid_offset[bucket + 1];
+
+                    for (let at = grid_offset[bucket]; at < end; at++) {
+                        const j = grid_point[at];
+
+                        if (j <= i || mass_inverse[j] === 0) {
+                            continue;
+                        }
+
+                        const b = j * 3;
+
+                        const ddx = x - position[b];
+                        const ddy = y - position[b + 1];
+                        const ddz = z - position[b + 2];
+
+                        const distance_squared = ddx * ddx + ddy * ddy + ddz * ddz;
+
+                        if (distance_squared >= closest_squared) {
+                            continue;
+                        }
+
+                        let excluded = false;
+
+                        for (let e = exclude_start; e < exclude_end; e++) {
+                            if (partner[e] === j) {
+                                excluded = true;
+
+                                break;
+                            }
+
+                            if (partner[e] > j) {
+                                break;
+                            }
+                        }
+
+                        if (excluded) {
+                            continue;
+                        }
+
+                        closest_squared = distance_squared;
+                    }
+                }
+            }
+        }
+    }
+
+    return closest_squared === search * search ? Infinity : Math.sqrt(closest_squared);
+}
+
+/**
+ * Rebuild the pair list.
+ *
+ * @param {ClothState} state pairs written into `self_pair`, count into `self_count`
+ * @param {{offset: Int32Array, partner: Int32Array}} exclusions from {@link cloth_self_exclusions}
+ * @returns {number} how many pairs were found
+ */
+export function cloth_self_find(state, exclusions) {
+    const particle_count = state.particle_count;
+
+    const radius = state.self_radius * 2;
+
+    if (radius <= 0) {
+        state.self_count = 0;
+
+        return 0;
+    }
+
+    GRID.build(state.position, particle_count, radius);
+
+    const position = state.position;
+    const mass_inverse = state.mass_inverse;
+
+    const pair = state.self_pair;
+
+    const capacity = pair.length / 2;
+
+    const offset = exclusions.offset;
+    const partner = exclusions.partner;
+
+    let count = 0;
+
+    const grid_offset = GRID.offset;
+    const grid_point = GRID.point;
+
+    const inverse = 1 / radius;
+
+    const radius_squared = radius * radius;
+
+    for (let i = 0; i < particle_count; i++) {
+        if (mass_inverse[i] === 0) {
+            // A pinned particle cannot be pushed, so a pair on it is a force
+            // assembled and thrown away for one end and doubled for the other.
+            continue;
+        }
+
+        const a = i * 3;
+
+        const x = position[a];
+        const y = position[a + 1];
+        const z = position[a + 2];
+
+        const cx = Math.floor(x * inverse);
+        const cy = Math.floor(y * inverse);
+        const cz = Math.floor(z * inverse);
+
+        const exclude_start = offset[i];
+        const exclude_end = offset[i + 1];
+
+        let found = 0;
+
+        let visited = 0;
+
+        for (let dz = -1; dz <= 1 && found < CLOTH_SELF_PAIRS_PER_PARTICLE; dz++) {
+            for (let dy = -1; dy <= 1 && found < CLOTH_SELF_PAIRS_PER_PARTICLE; dy++) {
+                for (let dx = -1; dx <= 1 && found < CLOTH_SELF_PAIRS_PER_PARTICLE; dx++) {
+                    const bucket = GRID.bucketOf(cx + dx, cy + dy, cz + dz);
+
+                    let seen = false;
+
+                    for (let v = 0; v < visited; v++) {
+                        if (VISITED[v] === bucket) {
+                            seen = true;
+
+                            break;
+                        }
+                    }
+
+                    if (seen) {
+                        continue;
+                    }
+
+                    VISITED[visited++] = bucket;
+
+                    const end = grid_offset[bucket + 1];
+
+                    for (let at = grid_offset[bucket]; at < end; at++) {
+                        const j = grid_point[at];
+
+                        // Each pair once, and never a particle against itself.
+                        // The `j > i` test is what halves the work and it is also
+                        // what makes the list order a function of the particle
+                        // numbering rather than of the grid's.
+                        if (j <= i) {
+                            continue;
+                        }
+
+                        if (mass_inverse[j] === 0) {
+                            continue;
+                        }
+
+                        const b = j * 3;
+
+                        const ddx = x - position[b];
+                        const ddy = y - position[b + 1];
+                        const ddz = z - position[b + 2];
+
+                        if (ddx * ddx + ddy * ddy + ddz * ddz >= radius_squared) {
+                            continue;
+                        }
+
+                        let excluded = false;
+
+                        for (let e = exclude_start; e < exclude_end; e++) {
+                            if (partner[e] === j) {
+                                excluded = true;
+
+                                break;
+                            }
+
+                            if (partner[e] > j) {
+                                // Sorted, so nothing further can match.
+                                break;
+                            }
+                        }
+
+                        if (excluded) {
+                            continue;
+                        }
+
+                        if (count >= capacity) {
+                            // The list is full. Dropping the rest is bounded and
+                            // visible — `ClothInstance#self_count` against the
+                            // capacity says so — and is the alternative to a
+                            // crumpled garment growing an allocation per frame.
+                            state.self_count = count;
+
+                            return count;
+                        }
+
+                        pair[count * 2] = i;
+                        pair[count * 2 + 1] = j;
+
+                        count++;
+                        found++;
+
+                        if (found >= CLOTH_SELF_PAIRS_PER_PARTICLE) {
+                            break;
+                        }
+                    }
+                }
+            }
+        }
+    }
+
+    state.self_count = count;
+
+    return count;
+}
+
+/**
+ * The grid, module-level and reused across every cloth and by both of the walks
+ * in this file. One cloth is stepped at a time and neither walk outlives its own
+ * call — {@link cloth_self_find} runs before the step and
+ * {@link cloth_self_closest_free_pair} runs once at seed — so a grid per instance
+ * would be one allocation per garment for no benefit. Neither may call the other.
+ * @type {PointHashGrid3}
+ * @private
+ */
+const GRID = new PointHashGrid3();
+
+/**
+ * Buckets the 27-cell walk has already visited, shared by both walks for the
+ * same reason {@link GRID} is: at most 27, never nested.
+ * @type {Int32Array}
+ * @private
+ */
+const VISITED = new Int32Array(27);

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

@@ -0,0 +1,16 @@
+/**
+ * Update one particle in place.
+ *
+ * A particle with zero inverse mass is pinned: it is an immovable anchor whose
+ * rows still act on its neighbours, and it is skipped here rather than divided
+ * by.
+ *
+ * @param {ClothState} state
+ * @param {number} particle
+ * @param {number} inverse_h_squared `1/h²` for the substep in progress
+ * @param {Float32Array|Float64Array|null} [collider_table] packed colliders in
+ *   the cloth's own frame, posed at this substep. `null` — the M0 and M1 case —
+ *   skips the contact rows entirely rather than looping over empty slots.
+ */
+export function cloth_solve_vertex(state: ClothState, particle: number, inverse_h_squared: number, collider_table?: Float32Array | Float64Array | null): void;
+//# sourceMappingURL=cloth_solve_vertex.d.ts.map

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

@@ -0,0 +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,QA6HxC"}

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

@@ -0,0 +1,216 @@
+import { assert } from "../../../../core/assert.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";
+import { cloth_leash_accumulate } from "./constraint/cloth_leash_row.js";
+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
+} from "./cloth_vertex_accumulator.js";
+
+/**
+ * # The vertex update — one 3×3 block of the descent
+ *
+ * The whole solver is this function run over every particle, colour by colour,
+ * `iterations` times a substep. It minimises the implicit-Euler variational
+ * energy with respect to one particle's position while every other particle is
+ * held fixed:
+ *
+ *     E_i(x) = (m/2h²)‖x − y‖² + Σ_c Ψ_c(C_c(x))
+ *
+ * — an inertial term pulling towards the predicted position `y`, plus one
+ * augmented-Lagrangian term per row. The step is Newton's:
+ *
+ *     f = −∇E_i = −(m/h²)(x − y) − Σ_c fc_c·g_c
+ *     H =  (m/h²)·I + Σ_tension (fc_c/L_c)(I − g_c g_cᵀ) + Σ_{active c} k_c·(g_c g_cᵀ)
+ *     x ← x + H⁻¹f
+ *
+ * ## Why the update never explodes
+ *
+ * The mass term `(m/h²)·I` is positive definite, every `k_c·g gᵀ` is a positive
+ * semidefinite rank-one term, and every `(fc/L)·(I − g gᵀ)` kept above is
+ * positive semidefinite too — that is precisely the test each row applies
+ * before adding one. So **`H` is symmetric positive definite by construction**
+ * — for any topology, any parameter values, any degenerate configuration, and
+ * regardless of how many rows are clamped out. The 3×3 solve therefore never
+ * divides by zero and `H⁻¹f` is always a descent direction. That is a
+ * structural property of the assembled matrix, not an empirical observation,
+ * and it is the whole of §5.3's stability argument.
+ *
+ * **Half of the geometric-stiffness term `fc·∂²C/∂x²` is kept, not all of it
+ * and not none of it.** For a distance row `∂²C/∂x² = (I − ggᵀ)/L`, which is
+ * positive semidefinite exactly when the row is in tension, so the tension
+ * half goes in without touching the argument above and the compression half —
+ * the indefinite one — stays out. An earlier draft of this file dropped the
+ * whole term, and `MEASUREMENTS.md` §5.1 is what that cost: the update
+ * overshoots sideways once `fc/L` passes `m/h²`, raising the vertex energy by
+ * 22% at a ratio of 4 and by a factor of 40 at 7e4. Do not drop it again to
+ * "restore" the SPD claim; the claim never needed it dropped.
+ *
+ * ## Order within a colour does not matter
+ *
+ * Colouring guarantees no row touches two particles of one colour, so every
+ * particle in a colour reads only positions no other particle in that colour
+ * writes. The sweep is Gauss-Seidel across colours and order-independent
+ * within one, which is what lets a worker split a colour across threads and
+ * still produce the main thread's bits (§12).
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+
+/**
+ * The `(f, H)` scratch. Module-level and reused: a vertex update allocates
+ * nothing, and the accumulator's life is strictly inside one call.
+ * @type {Float64Array}
+ * @private
+ */
+const ACCUMULATOR = new Float64Array(CVA_STRIDE);
+
+/**
+ * Update one particle in place.
+ *
+ * A particle with zero inverse mass is pinned: it is an immovable anchor whose
+ * rows still act on its neighbours, and it is skipped here rather than divided
+ * by.
+ *
+ * @param {ClothState} state
+ * @param {number} particle
+ * @param {number} inverse_h_squared `1/h²` for the substep in progress
+ * @param {Float32Array|Float64Array|null} [collider_table] packed colliders in
+ *   the cloth's own frame, posed at this substep. `null` — the M0 and M1 case —
+ *   skips the contact rows entirely rather than looping over empty slots.
+ */
+export function cloth_solve_vertex(state, particle, inverse_h_squared, collider_table = null) {
+    const inverse_mass = state.mass_inverse[particle];
+
+    if (inverse_mass === 0) {
+        return;
+    }
+
+    const position = state.position;
+    const inertial = state.inertial;
+
+    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_stretch_accumulate(accumulator, state, particle);
+    cloth_bend_accumulate(accumulator, state, particle);
+    cloth_leash_accumulate(accumulator, state, particle);
+    cloth_backstop_accumulate(accumulator, state, particle);
+
+    if (collider_table !== null) {
+        cloth_contact_accumulate(accumulator, state, particle, collider_table);
+    }
+
+    if (state.self_count > 0) {
+        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.
+    assert.ok(
+        pivot_x > 0 && pivot_y > 0 && pivot_z > 0,
+        `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`
+    );
+
+    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;
+
+    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;
+
+    // Trust region. `H⁻¹f` is a descent direction — that is what positive
+    // definiteness buys — but a *full* Newton step is only a descent *step*
+    // while the model it was built from still resembles the energy. For a
+    // distance row the model's gradient is the direction to a neighbour, and
+    // that direction is meaningless once the step is comparable to how far
+    // away the neighbour is: a particle sitting a hair from its neighbour with
+    // a large multiplier assembles a perfectly good SPD system and solves it
+    // for a step a thousand times the separation, which climbs.
+    //
+    // So the step is bounded by the shortest row the particle sits on. The
+    // radius is the mesh's own geometry rather than a tuned constant, it is
+    // already in hand from the accumulation, and for cloth in any ordinary
+    // motion it never binds — a step that moves a particle further than its
+    // own edge length in one iteration is already outside what one
+    // linearisation can be asked to describe.
+    const trust = accumulator[CVA_TRUST];
+
+    const length_squared = delta_x * delta_x + delta_y * delta_y + delta_z * delta_z;
+
+    if (length_squared > trust * trust) {
+        const scale = trust / Math.sqrt(length_squared);
+
+        position[p] += delta_x * scale;
+        position[p + 1] += delta_y * scale;
+        position[p + 2] += delta_z * scale;
+
+        return;
+    }
+
+    position[p] += delta_x;
+    position[p + 1] += delta_y;
+    position[p + 2] += delta_z;
+}