@woosh/meep-engine 3.21.0 → 3.23.0

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

@@ -0,0 +1,967 @@
+import { assert } from "../../../../core/assert.js";
+import { cloth_color_order, cloth_color_particles } from "./cloth_color_particles.js";
+import { CLOTH_SELF_PAIRS_PER_PARTICLE } from "./cloth_self_find.js";
+import { CLOTH_CONTACT_SLOTS } from "./constraint/cloth_contact_row.js";
+
+/**
+ * # ClothState — the whole simulated cloth, SoA, over one buffer
+ *
+ * Every array the step touches is a view into a single `ArrayBuffer`: particle
+ * state, the constraint tables, the per-particle incidence lists, and the
+ * duals. One allocation per cloth, one object to hand across a worker boundary
+ * (§12 puts a region per instance inside one shared buffer; this is that region
+ * with its views already cut), and no object dereference anywhere in the step.
+ * `SolverBodyState` is the same idea for rigid bodies and reads the same way.
+ *
+ * `Float32` throughout, per §12: the simulation runs in the cloth's local
+ * frame, so coordinates are garment-sized rather than world-sized and f32 has
+ * ample precision, and the payoff is half the bandwidth in the loop that
+ * dominates. JavaScript arithmetic is f64 regardless — only the *storage* is
+ * narrow, so a vertex update computes in double and rounds once on the way
+ * out.
+ *
+ * ## Particles are stored in colour order
+ *
+ * The sweep is "for each colour, for each particle in it" (§5.4). Rather than
+ * indirect through a colour membership list every iteration, {@link from}
+ * **permutes the particles** so each colour is a contiguous span, rewrites
+ * every row's particle indices into the new numbering, and stores one offset
+ * per colour. The sweep is then a pair of counted loops over adjacent indices
+ * and the runtime never sees a graph. {@link source_of_particle} carries the
+ * inverse permutation for a caller that has to map back to the mesh vertex it
+ * came from.
+ *
+ * ## Rows are stored per kind, and reached from the particle
+ *
+ * §6's row model is one table of `(C, f_min, f_max, stiffness)`, but the rows
+ * are *visited from the particle side* — a vertex update needs every row that
+ * touches particle `i`, not every row. So each kind carries a CSR incidence
+ * list: `*_adjacency_offset[i] .. [i + 1]` indexes into `*_adjacency`, whose
+ * entries pack the row index together with which slot of that row the particle
+ * occupies. Keeping the kinds in separate lists rather than one polymorphic
+ * table is what lets each accumulation loop stay monomorphic; a new row type
+ * is a new module and a new pair of arrays, not a branch inside the old loop.
+ *
+ * M0 carried the two persistent kinds the solver core is proved on — stretch
+ * and bend. M1 adds the third, the **leash**: §6's slack row and its tether
+ * row, which have the same `C` and differ only in where their centre and
+ * radius come from (`cloth_leash_row.js`). §6's strain-limit row needed no new
+ * storage at all — it is a stretch row with a longer rest length and a
+ * one-sided clamp, which the stretch table already carries. M2 adds the
+ * **backstop**, which is a leash against a plane rather than a point.
+ *
+ * ## Contacts are transient, and they live here anyway
+ *
+ * §5.4 says contact rows "never enter this structure" and are kept in a
+ * per-particle scratch applied Jacobi-style. Half of that is right and half of
+ * it is a solution to a problem a *collider* contact does not have.
+ *
+ * A contact against a collider is **unary** — one particle against a surface
+ * that is fixed for the substep — so it couples no two particles, so there is
+ * no Gauss-Seidel/Jacobi distinction to make and nothing to keep out of the
+ * colouring. It accumulates in the vertex update exactly like a leash row, in
+ * colour order, deterministically. What M4's particle-particle rows need is a
+ * different question and §9 is where it is answered.
+ *
+ * What *is* true is that a contact comes and goes, so it cannot be a CSR table
+ * sized at build time. It is instead a fixed **{@link CLOTH_CONTACT_SLOTS}
+ * slots per particle**, allocated once inside this buffer and rebuilt each
+ * step: an occupied slot names a collider, an empty one holds `-1`. That keeps
+ * §12's one-allocation property, bounds the worst case — a particle inside
+ * thirty colliders gets rows against the four nearest, which is the four that
+ * matter — and makes the accumulation a counted loop over adjacent slots
+ * rather than an indirection.
+ *
+ * A leash row is **unary** — one particle against a point — which has two
+ * pleasant consequences. It adds no edge to the particle graph, so the
+ * colouring is untouched by however many leashes a cloth carries. And its
+ * incidence list needs no slot bits: an entry is a row index and nothing else.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class ClothState {
+
+    /**
+     * The single allocation every view below is cut from.
+     * @type {ArrayBuffer}
+     */
+    buffer = null;
+
+    /**
+     * @type {number}
+     */
+    particle_count = 0;
+
+    /**
+     * @type {number}
+     */
+    stretch_count = 0;
+
+    /**
+     * @type {number}
+     */
+    bend_count = 0;
+
+    /**
+     * @type {number}
+     */
+    leash_count = 0;
+
+    /**
+     * @type {number}
+     */
+    colour_count = 0;
+
+    /**
+     * Current particle positions, cloth-local, 3 per particle. This is the
+     * variable the descent moves.
+     * @type {Float32Array}
+     */
+    position = null;
+
+    /**
+     * Position at the start of the current substep. `v = (x − x_prev)/h` is
+     * the whole of the integration step (§5.2), which is what makes every
+     * position constraint an implicit velocity constraint for free.
+     * @type {Float32Array}
+     */
+    position_previous = null;
+
+    /**
+     * @type {Float32Array}
+     */
+    velocity = null;
+
+    /**
+     * The inertial target `y = x + h·v + h²·a_ext`. The mass term of the
+     * per-vertex energy pulls towards this and nothing else; every other force
+     * in the system is a row.
+     * @type {Float32Array}
+     */
+    inertial = null;
+
+    /**
+     * Inverse mass, one per particle. **Zero pins the particle**: it is an
+     * immovable anchor that still exerts its rows on its neighbours, and the
+     * sweep skips it entirely rather than dividing by zero.
+     * @type {Float32Array}
+     */
+    mass_inverse = null;
+
+    /**
+     * VBD's adaptive-initialisation scale, one per particle, in `[0, 1]`.
+     * Written at integration from how much of the last step's acceleration was
+     * the external one: `1` means the particle was in free fall and the next
+     * step should be seeded with the full `h²·a_ext`, `0` means it was held
+     * (resting on a constraint) and seeding it with gravity would only make
+     * the first iteration undo it. §5.2.
+     * @type {Float32Array}
+     */
+    inertia_blend = null;
+
+    /**
+     * Start of each colour in the permuted particle order, `colour_count + 1`
+     * entries. Colour `c` is `[colour_offset[c], colour_offset[c + 1])`.
+     * @type {Int32Array}
+     */
+    colour_offset = null;
+
+    /**
+     * Mesh vertex each particle came from, before the colour permutation.
+     * Build-time provenance — the step never reads it.
+     * @type {Int32Array}
+     */
+    source_of_particle = null;
+
+    /**
+     * Endpoint particle indices, 2 per stretch row.
+     * @type {Int32Array}
+     */
+    stretch_particle = null;
+
+    /**
+     * Rest length `L₀`, one per stretch row.
+     * @type {Float32Array}
+     */
+    stretch_rest = null;
+
+    /**
+     * Material stiffness cap, one per stretch row — the value the `β` ramp
+     * drives the penalty towards, subject to the global `k_max`.
+     * @type {Float32Array}
+     */
+    stretch_stiffness = null;
+
+    /**
+     * Lower force clamp, one per stretch row. `−Infinity` for the bilateral
+     * fabric row; `0` would make it push-only. §6.
+     * @type {Float32Array}
+     */
+    stretch_force_min = null;
+
+    /**
+     * Upper force clamp, one per stretch row. `+Infinity` for the bilateral
+     * fabric row; `0` makes it pull-only, which with `L_max` in
+     * {@link stretch_rest} is exactly §6's strain-limit row.
+     * @type {Float32Array}
+     */
+    stretch_force_max = null;
+
+    /**
+     * Augmented-Lagrangian multiplier, one per stretch row, carried across
+     * steps and decayed at warm start.
+     * @type {Float32Array}
+     */
+    stretch_lambda = null;
+
+    /**
+     * Penalty stiffness `k_c`, one per stretch row. Ramps by `β·|C|` towards
+     * `min(k_max, stiffness)` and decays by `γ` at warm start.
+     * @type {Float32Array}
+     */
+    stretch_penalty = null;
+
+    /**
+     * CSR offsets into {@link stretch_adjacency}, `particle_count + 1` entries.
+     * @type {Int32Array}
+     */
+    stretch_adjacency_offset = null;
+
+    /**
+     * Packed `(row << 1) | slot` — the stretch rows touching each particle and
+     * which endpoint it is. Two entries per row.
+     * @type {Int32Array}
+     */
+    stretch_adjacency = null;
+
+    /**
+     * Stencil particle indices, 4 per bend row: the two ends of the shared
+     * edge followed by the two opposite wing vertices.
+     * @type {Int32Array}
+     */
+    bend_particle = null;
+
+    /**
+     * Quadratic bending stencil weights, 4 per bend row, precomputed from the
+     * rest shape. `C = Σ w_k·x_k` is linear in `x`, so these *are* the
+     * gradient — §6's reason bending costs almost nothing per iteration.
+     * @type {Float32Array}
+     */
+    bend_weight = null;
+
+    /**
+     * Material stiffness cap, one per bend row.
+     * @type {Float32Array}
+     */
+    bend_stiffness = null;
+
+    /**
+     * Augmented-Lagrangian multiplier, **3 per bend row**. `C` for a bending
+     * stencil is a vector — the discrete mean-curvature vector — so its
+     * multiplier is one too. The row is bilateral in each component, so no
+     * clamp is stored: a bending moment has no sign to be one-sided about.
+     * @type {Float32Array}
+     */
+    bend_lambda = null;
+
+    /**
+     * Penalty stiffness `k_c`, one per bend row, shared by the three
+     * components.
+     * @type {Float32Array}
+     */
+    bend_penalty = null;
+
+    /**
+     * CSR offsets into {@link bend_adjacency}, `particle_count + 1` entries.
+     * @type {Int32Array}
+     */
+    bend_adjacency_offset = null;
+
+    /**
+     * Packed `(row << 2) | slot` — the bend rows touching each particle and
+     * which stencil position it occupies. Four entries per row.
+     * @type {Int32Array}
+     */
+    bend_adjacency = null;
+
+    /**
+     * Particle each leash row holds, one per row.
+     * @type {Int32Array}
+     */
+    leash_particle = null;
+
+    /**
+     * The point each leash row is measured from, 3 per row, in the cloth's own
+     * local frame.
+     *
+     * **Written per step by the caller, not baked.** A slack row's centre is
+     * the particle's animated position and a tether row's is the anchor's, and
+     * neither is a property of the rest shape. Storing a point per row rather
+     * than an index into a shared table costs three floats a row and removes an
+     * indirection from the inner loop, which is the trade this structure makes
+     * everywhere else too.
+     * @type {Float32Array}
+     */
+    leash_target = null;
+
+    /**
+     * Leash radius, one per row: `slack·d_geo,i` for a slack row, `d_geo,i` for
+     * a tether. Zero is a weld (§3.4 — the pin is a leash of no radius, not a
+     * separate row).
+     * @type {Float32Array}
+     */
+    leash_radius = null;
+
+    /**
+     * Augmented-Lagrangian multiplier, one per leash row. Every leash row is
+     * hard, so unlike the stretch table there is no soft branch to skip: each
+     * one carries a multiplier and each one is enforced almost exactly at one
+     * iteration.
+     * @type {Float32Array}
+     */
+    leash_lambda = null;
+
+    /**
+     * Penalty stiffness `k_c`, one per leash row.
+     * @type {Float32Array}
+     */
+    leash_penalty = null;
+
+    /**
+     * CSR offsets into {@link leash_adjacency}, `particle_count + 1` entries.
+     * @type {Int32Array}
+     */
+    leash_adjacency_offset = null;
+
+    /**
+     * Row indices — no slot bits, because a leash row has one particle.
+     * @type {Int32Array}
+     */
+    leash_adjacency = null;
+
+    /**
+     * @type {number}
+     */
+    backstop_count = 0;
+
+    /**
+     * Particle each backstop row holds, one per row.
+     * @type {Int32Array}
+     */
+    backstop_particle = null;
+
+    /**
+     * The backstop plane per row: origin `b` then unit normal `n`, 6 per row,
+     * in the cloth's own local frame.
+     *
+     * **Written per step by the caller, not baked**, for the same reason
+     * {@link leash_target} is: a backstop is anchored to the *animated* pose —
+     * a point just inside the body with the surface normal there — and neither
+     * is a property of the rest shape. §6's row is
+     * `C = r_b − (x_i − b_i)·n_i`, so the row holds the particle at least
+     * {@link backstop_radius} out along its own normal from that point, which
+     * is what "never inside the body" means when the body is a shape the cloth
+     * does not have a collider for.
+     * @type {Float32Array}
+     */
+    backstop_plane = null;
+
+    /**
+     * Backstop radius, one per row.
+     * @type {Float32Array}
+     */
+    backstop_radius = null;
+
+    /**
+     * Augmented-Lagrangian multiplier, one per backstop row. Hard, like a leash.
+     * @type {Float32Array}
+     */
+    backstop_lambda = null;
+
+    /**
+     * Penalty stiffness `k_c`, one per backstop row.
+     * @type {Float32Array}
+     */
+    backstop_penalty = null;
+
+    /**
+     * CSR offsets into {@link backstop_adjacency}, `particle_count + 1` entries.
+     * @type {Int32Array}
+     */
+    backstop_adjacency_offset = null;
+
+    /**
+     * Row indices — unary, like a leash.
+     * @type {Int32Array}
+     */
+    backstop_adjacency = null;
+
+    /**
+     * Particle radius, metres — `ClothDynamics#thickness`, written by the
+     * caller before each step.
+     *
+     * A scalar rather than the per-particle array §12's table names, because
+     * nothing produces a proxy whose particles differ in size: a garment's
+     * thickness is a property of its fabric. A per-particle radius is what a
+     * decimated proxy with a strongly varying edge length would want, and the
+     * shape of that change is one array and one indexed read.
+     *
+     * It sits outside the buffer because it is a *parameter* rather than state
+     * — the same class of thing as `substeps`, which §12 sends across the
+     * worker boundary through the command region and not through the shared
+     * region.
+     * @type {number}
+     */
+    contact_radius = 0;
+
+    /**
+     * Which collider each contact slot holds, `CLOTH_CONTACT_SLOTS` per
+     * particle. A **record index into the caller's packed collider table**, not
+     * a handle, and `-1` for an empty slot.
+     * @type {Int32Array}
+     */
+    contact_collider = null;
+
+    /**
+     * The collider's stable identity for each occupied slot — its handle in the
+     * `ClothColliderIndex`, which unlike the record index survives the table
+     * being rebuilt from a different query. This is the key §12 warm-starts a
+     * transient row on, and a collider that leaves the index drops its slot and
+     * its contacts start cold, which is correct.
+     * @type {Int32Array}
+     */
+    contact_key = null;
+
+    /**
+     * Normal-force multiplier per contact slot, carried across steps.
+     * @type {Float32Array}
+     */
+    contact_lambda = null;
+
+    /**
+     * Normal-force penalty per contact slot.
+     * @type {Float32Array}
+     */
+    contact_penalty = null;
+
+    /**
+     * Friction multiplier per contact slot — the magnitude of the tangential
+     * force, because §6's friction row measures the *magnitude* of the slip and
+     * a magnitude has no sign to be clamped either side of.
+     * @type {Float32Array}
+     */
+    contact_friction_lambda = null;
+
+    /**
+     * Friction penalty per contact slot.
+     * @type {Float32Array}
+     */
+    contact_friction_penalty = null;
+
+    /**
+     * The radius a self-collision row holds two particles apart at, metres —
+     * **not** {@link contact_radius}, and M4 got that wrong before it measured
+     * its way out.
+     *
+     * §6 writes the row as `‖x_i − x_j‖ − (r_i + r_j)` with the same `r` a
+     * collider contact uses, which is `ClothDynamics#thickness`. A garment's
+     * fabric is 4 to 20 mm thick and a proxy's particles are 2 to 8 cm apart, so
+     * two layers of a fold are almost never within a fabric thickness of each
+     * other — their particles would have to line up, and nothing makes them.
+     *
+     * The radius that works is the **proxy's own resolution**: half the shortest
+     * row, so the row's diameter is one particle spacing. The pairs this row
+     * acts on are by construction the ones no fabric row governs, and the
+     * nearest of those is two hops away — so a diameter of one hop is the
+     * largest that cannot contradict a stretch row. Measured on a folding sheet
+     * at 2 cm spacing and 6 mm thickness, with only the radius moved: at the
+     * fabric's own 6 mm the row removes **21%** of the sheet's
+     * self-intersections, and at half the shortest row **82%**.
+     * `MEASUREMENTS.md` §31.
+     * @type {number}
+     */
+    self_radius = 0;
+
+    /**
+     * Self-collision pairs, 2 per pair, rebuilt every step (§9).
+     *
+     * A **pair** rather than a slot per particle, which is the difference from
+     * the contact table above and follows from the row being binary: a pair is
+     * stored once, with `i < j`, and contributes to both of its particles when
+     * the Jacobi scratch is built. Storing it on each side would double the
+     * memory to save an addition.
+     *
+     * The region is sized at build time — `CLOTH_SELF_PAIRS_PER_PARTICLE` per
+     * particle — and `self_count` says how much of it is live. A garment that
+     * crumples past that keeps what it found first and drops the rest, which is
+     * bounded and visible rather than an allocation per frame.
+     * @type {Int32Array}
+     */
+    self_pair = null;
+
+    /**
+     * Live pairs in {@link self_pair}.
+     * @type {number}
+     */
+    self_count = 0;
+
+    /**
+     * The Jacobi scratch's force, 3 per particle — every self-collision row
+     * touching that particle, summed once per iteration from the positions the
+     * previous iteration left.
+     *
+     * §5.4's per-particle scratch, and this is the row kind it was written for:
+     * a pair is what the colouring cannot pre-partition, so applying it inside
+     * the sweep would make the answer depend on the order the sweep was split
+     * in. `MEASUREMENTS.md` §18 has why a *collider* contact needs none of this.
+     * @type {Float32Array}
+     */
+    self_force = null;
+
+    /**
+     * The Jacobi scratch's Hessian, 6 per particle — the symmetric 3×3 in the
+     * same order {@link cloth_vertex_accumulator} uses: xx, yy, zz, xy, xz, yz.
+     * @type {Float32Array}
+     */
+    self_hessian = null;
+
+    /**
+     * Where the particle last stuck to the collider, 3 per contact slot, in the
+     * **collider's own local frame**.
+     *
+     * That frame rather than the cloth's is the whole of what makes a sliding
+     * collider drag cloth with it: the anchor is stored where the collider will
+     * always agree it is, and read back wherever the collider has moved to. In
+     * the cloth's frame it would be a point in space and the friction row would
+     * hold the cloth still while the body slid out from under it.
+     * @type {Float32Array}
+     */
+    contact_anchor = null;
+
+    /**
+     * Build a cloth from a rest configuration and its rows.
+     *
+     * Colours the particle graph, permutes the particles into colour order,
+     * rewrites the rows into that numbering, builds the incidence lists and
+     * cuts every view from one buffer. Nothing here runs per step.
+     *
+     * Rest lengths and bending weights are taken from the caller rather than
+     * derived, because a proxy bakes them (§11.3) and a rest length is not
+     * always the distance between the rest positions — a garment authored
+     * pre-stretched wants the authored value.
+     *
+     * @param {object} description
+     * @param {Float32Array|number[]} description.position rest positions, 3 per particle
+     * @param {Float32Array|number[]} description.mass_inverse inverse mass per particle, 0 pins
+     * @param {Int32Array|number[]} [description.stretch_particle] endpoint pairs
+     * @param {Float32Array|number[]} [description.stretch_rest] rest length per stretch row
+     * @param {Float32Array|number[]} [description.stretch_stiffness] material stiffness per stretch row
+     * @param {Float32Array|number[]} [description.stretch_force_min] lower clamp per stretch row, default `−Infinity`
+     * @param {Float32Array|number[]} [description.stretch_force_max] upper clamp per stretch row, default `+Infinity`
+     * @param {Int32Array|number[]} [description.bend_particle] stencil quads
+     * @param {Float32Array|number[]} [description.bend_weight] stencil weights, 4 per bend row
+     * @param {Float32Array|number[]} [description.bend_stiffness] material stiffness per bend row
+     * @param {Int32Array|number[]} [description.leash_particle] the particle each leash row holds
+     * @param {Float32Array|number[]} [description.leash_radius] leash radius per row; its length is
+     *   the row count, and the leash centres are written per step rather than here
+     * @param {Int32Array|number[]} [description.backstop_particle] the particle each backstop row holds
+     * @param {Float32Array|number[]} [description.backstop_radius] backstop radius per row; the planes
+     *   themselves are written per step rather than here
+     * @returns {ClothState}
+     */
+    static from({
+        position,
+        mass_inverse,
+        stretch_particle = EMPTY_INT32,
+        stretch_rest = EMPTY_FLOAT32,
+        stretch_stiffness = EMPTY_FLOAT32,
+        stretch_force_min = undefined,
+        stretch_force_max = undefined,
+        bend_particle = EMPTY_INT32,
+        bend_weight = EMPTY_FLOAT32,
+        bend_stiffness = EMPTY_FLOAT32,
+        leash_particle = EMPTY_INT32,
+        leash_radius = EMPTY_FLOAT32,
+        backstop_particle = EMPTY_INT32,
+        backstop_radius = EMPTY_FLOAT32
+    }) {
+        const particle_count = mass_inverse.length;
+        const stretch_count = stretch_rest.length;
+        const bend_count = bend_stiffness.length;
+        const leash_count = leash_radius.length;
+        const backstop_count = backstop_radius.length;
+
+        assert.equal(position.length, particle_count * 3, 'position.length');
+        assert.equal(stretch_particle.length, stretch_count * 2, 'stretch_particle.length');
+        assert.equal(stretch_stiffness.length, stretch_count, 'stretch_stiffness.length');
+        assert.equal(bend_particle.length, bend_count * 4, 'bend_particle.length');
+        assert.equal(bend_weight.length, bend_count * 4, 'bend_weight.length');
+        assert.equal(leash_particle.length, leash_count, 'leash_particle.length');
+        assert.equal(backstop_particle.length, backstop_count, 'backstop_particle.length');
+
+        const colors = cloth_color_particles(
+            particle_count,
+            stretch_particle, stretch_count,
+            bend_particle, bend_count
+        );
+
+        const { colour_count, colour_offset, order } = cloth_color_order(colors, particle_count);
+
+        // `order` maps permuted → source; the rows need source → permuted.
+        const particle_of_source = new Int32Array(particle_count);
+
+        for (let i = 0; i < particle_count; i++) {
+            particle_of_source[order[i]] = i;
+        }
+
+        const state = new ClothState();
+
+        allocate(state, particle_count, stretch_count, bend_count, leash_count, backstop_count, colour_count);
+
+        state.colour_offset.set(colour_offset);
+        state.source_of_particle.set(order);
+
+        for (let i = 0; i < particle_count; i++) {
+            const source = order[i];
+
+            state.position[i * 3] = position[source * 3];
+            state.position[i * 3 + 1] = position[source * 3 + 1];
+            state.position[i * 3 + 2] = position[source * 3 + 2];
+
+            state.mass_inverse[i] = mass_inverse[source];
+        }
+
+        // Nothing has moved yet, so the previous position is the current one
+        // and the first step's `v = (x − x_prev)/h` reads zero.
+        state.position_previous.set(state.position);
+        state.inertial.set(state.position);
+
+        for (let row = 0; row < stretch_count; row++) {
+            state.stretch_particle[row * 2] = particle_of_source[stretch_particle[row * 2]];
+            state.stretch_particle[row * 2 + 1] = particle_of_source[stretch_particle[row * 2 + 1]];
+
+            const stiffness = stretch_stiffness[row];
+
+            state.stretch_rest[row] = stretch_rest[row];
+            state.stretch_stiffness[row] = stiffness;
+            state.stretch_force_min[row] = stretch_force_min === undefined ? -Infinity : stretch_force_min[row];
+            state.stretch_force_max[row] = stretch_force_max === undefined ? Infinity : stretch_force_max[row];
+
+            // A soft row's penalty is its material stiffness and stays there;
+            // a hard row's is `Infinity`, which is a statement about the
+            // material rather than a number the solve can use, so it starts at
+            // zero and the warm start puts it in the band before the first
+            // iteration reads it. Seeding a hard row at its own stiffness
+            // instead leaves `Infinity` in the table for any row the warm start
+            // skips — an edge between two pinned particles — and that is a
+            // non-finite value sitting in live state.
+            state.stretch_penalty[row] = stiffness < Infinity ? stiffness : 0;
+        }
+
+        for (let row = 0; row < bend_count; row++) {
+            for (let slot = 0; slot < 4; slot++) {
+                state.bend_particle[row * 4 + slot] = particle_of_source[bend_particle[row * 4 + slot]];
+                state.bend_weight[row * 4 + slot] = bend_weight[row * 4 + slot];
+            }
+
+            const stiffness = bend_stiffness[row];
+
+            state.bend_stiffness[row] = stiffness;
+            state.bend_penalty[row] = stiffness < Infinity ? stiffness : 0;
+        }
+
+        build_adjacency(
+            state.stretch_adjacency_offset, state.stretch_adjacency,
+            state.stretch_particle, stretch_count, 2, particle_count
+        );
+
+        for (let row = 0; row < leash_count; row++) {
+            const particle = particle_of_source[leash_particle[row]];
+
+            state.leash_particle[row] = particle;
+            state.leash_radius[row] = leash_radius[row];
+
+            // A leash centre is written per step, but a row read before the
+            // first write would otherwise measure from the origin — which for a
+            // cloth-local frame is the anchor, and would look like a plausible
+            // answer rather than an uninitialised one. Seed it at the particle,
+            // where `C` is `−radius` and the row is inactive.
+            state.leash_target[row * 3] = state.position[particle * 3];
+            state.leash_target[row * 3 + 1] = state.position[particle * 3 + 1];
+            state.leash_target[row * 3 + 2] = state.position[particle * 3 + 2];
+        }
+
+        build_adjacency(
+            state.bend_adjacency_offset, state.bend_adjacency,
+            state.bend_particle, bend_count, 4, particle_count
+        );
+
+        build_unary_adjacency(
+            state.leash_adjacency_offset, state.leash_adjacency,
+            state.leash_particle, leash_count, particle_count
+        );
+
+        for (let row = 0; row < backstop_count; row++) {
+            const particle = particle_of_source[backstop_particle[row]];
+
+            state.backstop_particle[row] = particle;
+            state.backstop_radius[row] = backstop_radius[row];
+
+            // Seeded at the particle with an upward normal, where `C` is
+            // `radius` and the row is *violated* rather than inactive — so an
+            // unwritten backstop is visible as a row doing something, rather
+            // than as a plane through the origin that looks plausible. The
+            // caller writes the real plane before the first step.
+            state.backstop_plane[row * 6] = state.position[particle * 3];
+            state.backstop_plane[row * 6 + 1] = state.position[particle * 3 + 1];
+            state.backstop_plane[row * 6 + 2] = state.position[particle * 3 + 2];
+            state.backstop_plane[row * 6 + 4] = 1;
+        }
+
+        build_unary_adjacency(
+            state.backstop_adjacency_offset, state.backstop_adjacency,
+            state.backstop_particle, backstop_count, particle_count
+        );
+
+        state.contact_collider.fill(-1);
+        state.contact_key.fill(-1);
+
+        return state;
+    }
+}
+
+/**
+ * @type {Int32Array}
+ * @private
+ */
+const EMPTY_INT32 = new Int32Array(0);
+
+/**
+ * @type {Float32Array}
+ * @private
+ */
+const EMPTY_FLOAT32 = new Float32Array(0);
+
+/**
+ * Cut every view out of one buffer, in declaration order. Each region is a
+ * whole number of 4-byte elements and both element types are 4 bytes wide, so
+ * a running element cursor is all the alignment bookkeeping this needs.
+ *
+ * @param {ClothState} state
+ * @param {number} particle_count
+ * @param {number} stretch_count
+ * @param {number} bend_count
+ * @param {number} leash_count
+ * @param {number} colour_count
+ * @private
+ */
+function allocate(state, particle_count, stretch_count, bend_count, leash_count, backstop_count, colour_count) {
+    const contact_count = particle_count * CLOTH_CONTACT_SLOTS;
+    const self_capacity = particle_count * CLOTH_SELF_PAIRS_PER_PARTICLE;
+
+    const sizes = [
+        particle_count * 3,     // position
+        particle_count * 3,     // position_previous
+        particle_count * 3,     // velocity
+        particle_count * 3,     // inertial
+        particle_count,         // mass_inverse
+        particle_count,         // inertia_blend
+        colour_count + 1,       // colour_offset
+        particle_count,         // source_of_particle
+        stretch_count * 2,      // stretch_particle
+        stretch_count,          // stretch_rest
+        stretch_count,          // stretch_stiffness
+        stretch_count,          // stretch_force_min
+        stretch_count,          // stretch_force_max
+        stretch_count,          // stretch_lambda
+        stretch_count,          // stretch_penalty
+        particle_count + 1,     // stretch_adjacency_offset
+        stretch_count * 2,      // stretch_adjacency
+        bend_count * 4,         // bend_particle
+        bend_count * 4,         // bend_weight
+        bend_count,             // bend_stiffness
+        bend_count * 3,         // bend_lambda
+        bend_count,             // bend_penalty
+        particle_count + 1,     // bend_adjacency_offset
+        bend_count * 4,         // bend_adjacency
+        leash_count,            // leash_particle
+        leash_count * 3,        // leash_target
+        leash_count,            // leash_radius
+        leash_count,            // leash_lambda
+        leash_count,            // leash_penalty
+        particle_count + 1,     // leash_adjacency_offset
+        leash_count,            // leash_adjacency
+        backstop_count,         // backstop_particle
+        backstop_count * 6,     // backstop_plane
+        backstop_count,         // backstop_radius
+        backstop_count,         // backstop_lambda
+        backstop_count,         // backstop_penalty
+        particle_count + 1,     // backstop_adjacency_offset
+        backstop_count,         // backstop_adjacency
+        contact_count,          // contact_collider
+        contact_count,          // contact_key
+        contact_count,          // contact_lambda
+        contact_count,          // contact_penalty
+        contact_count,          // contact_friction_lambda
+        contact_count,          // contact_friction_penalty
+        contact_count * 3,      // contact_anchor
+        self_capacity * 2,      // self_pair
+        particle_count * 3,     // self_force
+        particle_count * 6      // self_hessian
+    ];
+
+    let total = 0;
+
+    for (let i = 0; i < sizes.length; i++) {
+        total += sizes[i];
+    }
+
+    const buffer = new ArrayBuffer(total * 4);
+
+    let cursor = 0;
+
+    /**
+     * @param {Float32ArrayConstructor|Int32ArrayConstructor} type
+     * @param {number} length
+     */
+    const cut = (type, length) => {
+        const view = new type(buffer, cursor * 4, length);
+
+        cursor += length;
+
+        return view;
+    };
+
+    state.buffer = buffer;
+    state.particle_count = particle_count;
+    state.stretch_count = stretch_count;
+    state.bend_count = bend_count;
+    state.leash_count = leash_count;
+    state.backstop_count = backstop_count;
+    state.colour_count = colour_count;
+
+    state.position = cut(Float32Array, particle_count * 3);
+    state.position_previous = cut(Float32Array, particle_count * 3);
+    state.velocity = cut(Float32Array, particle_count * 3);
+    state.inertial = cut(Float32Array, particle_count * 3);
+    state.mass_inverse = cut(Float32Array, particle_count);
+    state.inertia_blend = cut(Float32Array, particle_count);
+    state.colour_offset = cut(Int32Array, colour_count + 1);
+    state.source_of_particle = cut(Int32Array, particle_count);
+
+    state.stretch_particle = cut(Int32Array, stretch_count * 2);
+    state.stretch_rest = cut(Float32Array, stretch_count);
+    state.stretch_stiffness = cut(Float32Array, stretch_count);
+    state.stretch_force_min = cut(Float32Array, stretch_count);
+    state.stretch_force_max = cut(Float32Array, stretch_count);
+    state.stretch_lambda = cut(Float32Array, stretch_count);
+    state.stretch_penalty = cut(Float32Array, stretch_count);
+    state.stretch_adjacency_offset = cut(Int32Array, particle_count + 1);
+    state.stretch_adjacency = cut(Int32Array, stretch_count * 2);
+
+    state.bend_particle = cut(Int32Array, bend_count * 4);
+    state.bend_weight = cut(Float32Array, bend_count * 4);
+    state.bend_stiffness = cut(Float32Array, bend_count);
+    state.bend_lambda = cut(Float32Array, bend_count * 3);
+    state.bend_penalty = cut(Float32Array, bend_count);
+    state.bend_adjacency_offset = cut(Int32Array, particle_count + 1);
+    state.bend_adjacency = cut(Int32Array, bend_count * 4);
+
+    state.leash_particle = cut(Int32Array, leash_count);
+    state.leash_target = cut(Float32Array, leash_count * 3);
+    state.leash_radius = cut(Float32Array, leash_count);
+    state.leash_lambda = cut(Float32Array, leash_count);
+    state.leash_penalty = cut(Float32Array, leash_count);
+    state.leash_adjacency_offset = cut(Int32Array, particle_count + 1);
+    state.leash_adjacency = cut(Int32Array, leash_count);
+
+    state.backstop_particle = cut(Int32Array, backstop_count);
+    state.backstop_plane = cut(Float32Array, backstop_count * 6);
+    state.backstop_radius = cut(Float32Array, backstop_count);
+    state.backstop_lambda = cut(Float32Array, backstop_count);
+    state.backstop_penalty = cut(Float32Array, backstop_count);
+    state.backstop_adjacency_offset = cut(Int32Array, particle_count + 1);
+    state.backstop_adjacency = cut(Int32Array, backstop_count);
+
+    state.contact_collider = cut(Int32Array, contact_count);
+    state.contact_key = cut(Int32Array, contact_count);
+    state.contact_lambda = cut(Float32Array, contact_count);
+    state.contact_penalty = cut(Float32Array, contact_count);
+    state.contact_friction_lambda = cut(Float32Array, contact_count);
+    state.contact_friction_penalty = cut(Float32Array, contact_count);
+    state.contact_anchor = cut(Float32Array, contact_count * 3);
+
+    state.self_pair = cut(Int32Array, self_capacity * 2);
+    state.self_force = cut(Float32Array, particle_count * 3);
+    state.self_hessian = cut(Float32Array, particle_count * 6);
+
+    assert.equal(cursor, total, 'buffer cursor at end of allocation');
+}
+
+/**
+ * The {@link build_adjacency} of a **unary** row kind: one particle per row, so
+ * an entry is a bare row index rather than a packed `(row, slot)` pair and
+ * there is nothing to shift.
+ *
+ * @param {Int32Array} offset out, `particle_count + 1`
+ * @param {Int32Array} adjacency out, `row_count`
+ * @param {Int32Array} row_particle particle index per row
+ * @param {number} row_count
+ * @param {number} particle_count
+ * @private
+ */
+function build_unary_adjacency(offset, adjacency, row_particle, row_count, particle_count) {
+    for (let row = 0; row < row_count; row++) {
+        offset[row_particle[row] + 1]++;
+    }
+
+    for (let i = 0; i < particle_count; i++) {
+        offset[i + 1] += offset[i];
+    }
+
+    const cursor = offset.slice(0, particle_count);
+
+    for (let row = 0; row < row_count; row++) {
+        adjacency[cursor[row_particle[row]]++] = row;
+    }
+}
+
+/**
+ * Counting sort of `(particle, row, slot)` incidences into CSR, with the slot
+ * folded into the low bits of each entry so the accumulation loop reads one
+ * word per row it touches.
+ *
+ * Entries within a particle come out in ascending row order, which keeps the
+ * row tables walked forwards during a sweep even though the particles are in
+ * colour order.
+ *
+ * @param {Int32Array} offset out, `particle_count + 1`
+ * @param {Int32Array} adjacency out, `row_count * arity`
+ * @param {Int32Array} row_particle particle indices, `arity` per row
+ * @param {number} row_count
+ * @param {number} arity 2 for stretch, 4 for bend
+ * @param {number} particle_count
+ * @private
+ */
+function build_adjacency(offset, adjacency, row_particle, row_count, arity, particle_count) {
+    const shift = arity === 2 ? 1 : 2;
+
+    for (let i = 0; i < row_count * arity; i++) {
+        offset[row_particle[i] + 1]++;
+    }
+
+    for (let i = 0; i < particle_count; i++) {
+        offset[i + 1] += offset[i];
+    }
+
+    const cursor = offset.slice(0, particle_count);
+
+    for (let row = 0; row < row_count; row++) {
+        for (let slot = 0; slot < arity; slot++) {
+            const particle = row_particle[row * arity + slot];
+
+            adjacency[cursor[particle]++] = (row << shift) | slot;
+        }
+    }
+}