@woosh/meep-engine 3.43.0 → 3.45.0

package/src/engine/physics/cloth/playground/wind_main.js

@@ -1,6 +1,7 @@
 import { EntityComponentDataset } from "../../../ecs/EntityComponentDataset.js";
 import { FluidComponent } from "../../fluid/ecs/FluidComponent.js";
 import { fluid_build_world_to_grid } from "../../fluid/ecs/fluid_build_world_to_grid.js";
+import { fluid_sample_velocity_world_mps } from "../../fluid/ecs/fluid_sample_velocity_world_mps.js";
 import { CLOTH_DYNAMICS_BY_NAME } from "../ecs/cloth_dynamics_library.js";
 import { cloth_bend_ratio, cloth_drag_response } from "../ecs/cloth_dynamics_map.js";
 import { cloth_step } from "../solver/cloth_step.js";
@@ -389,14 +390,14 @@ function draw_field() {
                 continue;
             }
 
-            component.sampleVelocityAtWorld(sample, x, y, z);
+            // In metres a second, as `ClothFluidWind` reads it.
+            fluid_sample_velocity_world_mps(sample, 0, component, x, y, z);
 
-            // Cells a second to metres a second, the same conversion
-            // `ClothFluidWind` makes and for the same reason.
-            const vx = sample[0] * cell_size;
-            const vz = sample[2] * cell_size;
+            const vx = sample[0];
+            const vy = sample[1];
+            const vz = sample[2];
 
-            const speed = Math.hypot(vx, sample[1] * cell_size, vz);
+            const speed = Math.hypot(vx, vy, vz);
 
             if (speed < 1e-3) {
                 continue;
@@ -406,7 +407,7 @@ function draw_field() {
 
             const depth = project(from, camera, x, y, z, width, height);
 
-            project(to, camera, x + vx * scale, y + sample[1] * cell_size * scale, z + vz * scale, width, height);
+            project(to, camera, x + vx * scale, y + vy * scale, z + vz * scale, width, height);
 
             if (depth <= 0) {
                 continue;

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

@@ -39,6 +39,8 @@ export class ClothState {
      * @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.leash_source] source particle per leash row, `−1`
+     *   for a row whose centre the caller writes outright; default all `−1`
      * @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
@@ -49,7 +51,7 @@ export class ClothState {
      *   back private memory would make both threads mutate copies of it.
      * @returns {ClothState}
      */
-    static from({ position, mass_inverse, stretch_particle, stretch_rest, stretch_stiffness, stretch_force_min, stretch_force_max, bend_particle, bend_weight, bend_stiffness, leash_particle, leash_radius, backstop_particle, backstop_radius, shared }: {
+    static from({ position, mass_inverse, stretch_particle, stretch_rest, stretch_stiffness, stretch_force_min, stretch_force_max, bend_particle, bend_weight, bend_stiffness, leash_particle, leash_radius, leash_source, backstop_particle, backstop_radius, shared }: {
         position: Float32Array | number[];
         mass_inverse: Float32Array | number[];
         stretch_particle?: Int32Array | number[];
@@ -62,6 +64,7 @@ export class ClothState {
         bend_stiffness?: Float32Array | number[];
         leash_particle?: Int32Array | number[];
         leash_radius?: Float32Array | number[];
+        leash_source?: Int32Array | number[];
         backstop_particle?: Int32Array | number[];
         backstop_radius?: Float32Array | number[];
         shared?: boolean;
@@ -278,15 +281,36 @@ export class ClothState {
      * 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.
+     * **Written per step by the caller, not baked** — or, for a row with a
+     * {@link leash_source}, per substep by the step itself. A slack row's centre
+     * is the particle's animated position and a tether row's is the held
+     * particle it hangs from, 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: Float32Array;
+    /**
+     * The particle each leash row is measured from, or `−1` for a row whose
+     * centre the caller writes outright.
+     *
+     * **A held particle moves inside a step** — it is carried an equal share of
+     * the way to where its holder will have it at each substep — so a centre
+     * written once per step is a step behind the particle it is supposed to sit
+     * on, and a hard row measured from a stale point fights the hold it hangs
+     * from. A row with a source is re-centred at every substep, after the held
+     * particles have moved, at `position[source] + leash_offset`.
+     * @type {Int32Array}
+     */
+    leash_source: Int32Array;
+    /**
+     * Where a sourced leash row's centre sits relative to its source particle,
+     * 3 per row, cloth-local. Zero for a tether; the animated pose's offset from
+     * the held particle for a slack row. Written by the caller per step.
+     * @type {Float32Array}
+     */
+    leash_offset: Float32Array;
     /**
      * 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
@@ -541,6 +565,20 @@ export class ClothState {
      * @type {Float32Array}
      */
     air_velocity: Float32Array;
+    /**
+     * Where each **held** particle — inverse mass zero — is to be at the end of
+     * the step, 3 per particle, cloth-local.
+     *
+     * Written by the caller; read by the predict, which carries a held particle
+     * an equal share of the remaining way at every substep so that it arrives
+     * here exactly at the last one. That is how a holder that moves relative to
+     * the cloth's frame moves its particles *through* the step rather than at
+     * its start, which is the same thing §8.2 does for colliders — and Chaos
+     * Cloth does for its kinematic particles. Seeded at the rest position, so a
+     * held particle nobody writes a target for stays where it is, bit for bit.
+     * @type {Float32Array}
+     */
+    kinematic_target: Float32Array;
     /**
      * Gravity plus §10's aerodynamic drag, 3 per particle, cloth-local, m/s².
      *

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

@@ -1 +1 @@
-{"version":3,"file":"ClothState.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/cloth/solver/ClothState.js"],"names":[],"mappings":"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"}
+{"version":3,"file":"ClothState.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/cloth/solver/ClothState.js"],"names":[],"mappings":"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"}

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

@@ -1,6 +1,8 @@
 import { assert } from "../../../../core/assert.js";
+import { csr_build_incidence } from "../../../../core/graph/csr/csr_build_incidence.js";
 import { CCR_STRIDE } from "../collider/ClothColliderRecord.js";
 import { cloth_color_order, cloth_color_particles } from "./cloth_color_particles.js";
+import { cloth_particle_of_source } from "./cloth_particle_of_source.js";
 import { CLOTH_COLLIDER_SLOTS } from "./cloth_solver_constants.js";
 import { CLOTH_SELF_PAIRS_PER_PARTICLE } from "./cloth_self_find.js";
 import { CLOTH_CONTACT_SLOTS } from "./constraint/cloth_contact_row.js";
@@ -360,16 +362,39 @@ export class ClothState {
      * 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.
+     * **Written per step by the caller, not baked** — or, for a row with a
+     * {@link leash_source}, per substep by the step itself. A slack row's centre
+     * is the particle's animated position and a tether row's is the held
+     * particle it hangs from, 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;
 
+    /**
+     * The particle each leash row is measured from, or `−1` for a row whose
+     * centre the caller writes outright.
+     *
+     * **A held particle moves inside a step** — it is carried an equal share of
+     * the way to where its holder will have it at each substep — so a centre
+     * written once per step is a step behind the particle it is supposed to sit
+     * on, and a hard row measured from a stale point fights the hold it hangs
+     * from. A row with a source is re-centred at every substep, after the held
+     * particles have moved, at `position[source] + leash_offset`.
+     * @type {Int32Array}
+     */
+    leash_source = null;
+
+    /**
+     * Where a sourced leash row's centre sits relative to its source particle,
+     * 3 per row, cloth-local. Zero for a tether; the animated pose's offset from
+     * the held particle for a slack row. Written by the caller per step.
+     * @type {Float32Array}
+     */
+    leash_offset = 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
@@ -654,6 +679,21 @@ export class ClothState {
      */
     air_velocity = null;
 
+    /**
+     * Where each **held** particle — inverse mass zero — is to be at the end of
+     * the step, 3 per particle, cloth-local.
+     *
+     * Written by the caller; read by the predict, which carries a held particle
+     * an equal share of the remaining way at every substep so that it arrives
+     * here exactly at the last one. That is how a holder that moves relative to
+     * the cloth's frame moves its particles *through* the step rather than at
+     * its start, which is the same thing §8.2 does for colliders — and Chaos
+     * Cloth does for its kinematic particles. Seeded at the rest position, so a
+     * held particle nobody writes a target for stays where it is, bit for bit.
+     * @type {Float32Array}
+     */
+    kinematic_target = null;
+
     /**
      * Gravity plus §10's aerodynamic drag, 3 per particle, cloth-local, m/s².
      *
@@ -693,6 +733,8 @@ export class ClothState {
      * @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.leash_source] source particle per leash row, `−1`
+     *   for a row whose centre the caller writes outright; default all `−1`
      * @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
@@ -716,6 +758,7 @@ export class ClothState {
         bend_stiffness = EMPTY_FLOAT32,
         leash_particle = EMPTY_INT32,
         leash_radius = EMPTY_FLOAT32,
+        leash_source = undefined,
         backstop_particle = EMPTY_INT32,
         backstop_radius = EMPTY_FLOAT32,
         shared = false
@@ -732,6 +775,7 @@ export class ClothState {
         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.ok(leash_source === undefined || leash_source.length === leash_count, 'leash_source.length');
         assert.equal(backstop_particle.length, backstop_count, 'backstop_particle.length');
 
         const colors = cloth_color_particles(
@@ -745,9 +789,7 @@ export class ClothState {
         // `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;
-        }
+        cloth_particle_of_source(particle_of_source, order, particle_count);
 
         const state = new ClothState();
 
@@ -774,6 +816,7 @@ export class ClothState {
         // and the first step's `v = (x − x_prev)/h` reads zero.
         state.position_previous.set(state.position);
         state.inertial.set(state.position);
+        state.kinematic_target.set(state.position);
 
         for (let row = 0; row < stretch_count; row++) {
             state.stretch_particle[row * 2] = particle_of_source[stretch_particle[row * 2]];
@@ -809,9 +852,15 @@ export class ClothState {
             state.bend_penalty[row] = stiffness < Infinity ? stiffness : 0;
         }
 
-        build_adjacency(
+        // Grouping the flat particle table gives the flat index `row·2 + slot`,
+        // which is the packed `(row << 1) | slot` the stretch accumulation
+        // decodes, already in ascending row order within each particle — so the
+        // row tables are walked forwards during a sweep even though the
+        // particles are in colour order. The bend table below is the same with
+        // `(row << 2) | slot`.
+        csr_build_incidence(
             state.stretch_adjacency_offset, state.stretch_adjacency,
-            state.stretch_particle, stretch_count, 2, particle_count
+            state.stretch_particle, stretch_count * 2, particle_count
         );
 
         for (let row = 0; row < leash_count; row++) {
@@ -828,14 +877,19 @@ export class ClothState {
             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];
+
+            state.leash_source[row] = leash_source === undefined || leash_source[row] < 0
+                ? -1
+                : particle_of_source[leash_source[row]];
         }
 
-        build_adjacency(
+        csr_build_incidence(
             state.bend_adjacency_offset, state.bend_adjacency,
-            state.bend_particle, bend_count, 4, particle_count
+            state.bend_particle, bend_count * 4, particle_count
         );
 
-        build_unary_adjacency(
+        // A unary row kind's flat index is its row index: nothing to unpack.
+        csr_build_incidence(
             state.leash_adjacency_offset, state.leash_adjacency,
             state.leash_particle, leash_count, particle_count
         );
@@ -857,7 +911,7 @@ export class ClothState {
             state.backstop_plane[row * 6 + 4] = 1;
         }
 
-        build_unary_adjacency(
+        csr_build_incidence(
             state.backstop_adjacency_offset, state.backstop_adjacency,
             state.backstop_particle, backstop_count, particle_count
         );
@@ -1028,6 +1082,8 @@ function allocate(
         bend_count * 4,         // bend_adjacency
         leash_count,            // leash_particle
         leash_count * 3,        // leash_target
+        leash_count,            // leash_source
+        leash_count * 3,        // leash_offset
         leash_count,            // leash_radius
         leash_count,            // leash_lambda
         leash_count,            // leash_penalty
@@ -1053,7 +1109,8 @@ function allocate(
         particle_count * 3,     // self_force
         particle_count * 6,     // self_hessian
         particle_count * 3,     // air_velocity
-        particle_count * 3      // external_acceleration
+        particle_count * 3,     // external_acceleration
+        particle_count * 3      // kinematic_target
     ];
 
     let total = 0;
@@ -1119,6 +1176,8 @@ function allocate(
 
     state.leash_particle = cut(Int32Array, leash_count);
     state.leash_target = cut(Float32Array, leash_count * 3);
+    state.leash_source = cut(Int32Array, leash_count);
+    state.leash_offset = 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);
@@ -1157,72 +1216,9 @@ function allocate(
     state.air_velocity = cut(Float32Array, particle_count * 3);
     state.external_acceleration = cut(Float32Array, particle_count * 3);
 
-    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];
+    // Held particles only, and a cloth whose holders ride its frame never
+    // changes it: the cold end.
+    state.kinematic_target = cut(Float32Array, particle_count * 3);
 
-            adjacency[cursor[particle]++] = (row << shift) | slot;
-        }
-    }
+    assert.equal(cursor, total, 'buffer cursor at end of allocation');
 }

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

@@ -19,17 +19,19 @@
  * against 76 for its 14,802 tetrahedra — the same asymmetry, and the reason
  * this design colours vertices rather than constraints.
  *
- * This runs **once**, at build time, on a `Graph` object. The runtime never
- * sees a graph: {@link ClothState} bakes the result into a permuted particle
- * order plus a range per colour, so the sweep is a pair of nested counted
- * loops over contiguous indices.
+ * This runs **once**, at build time, on the sorted CSR adjacency
+ * {@link cloth_particle_coupling} builds — the same edge set the
+ * self-collision exclusions are. The runtime never sees a graph:
+ * {@link ClothState} bakes the result into a permuted particle order plus a
+ * range per colour, so the sweep is a pair of nested counted loops over
+ * contiguous indices.
  *
  * The greedy colouriser is fed a largest-degree-first order (Welsh–Powell),
  * which is the cheap heuristic that gets a regular triangulated sheet down to
- * the 8–10 colours §5.4 predicts. The result is checked with the engine's own
- * {@link validateGraphColoring} behind `assert.*`, so a colouring that would
- * let two coupled particles race is caught in a dev build and compiles out of
- * a shipped one.
+ * the 8–10 colours §5.4 predicts. The result is checked with
+ * {@link csr_graph_validate_coloring} behind `assert.*`, so a colouring that
+ * would let two coupled particles race is caught in a dev build and compiles
+ * out of a shipped one.
  *
  * @author Alex Goldring
  * @copyright Company Named Limited (c) 2026

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

@@ -1 +1 @@
-{"version":3,"file":"cloth_color_particles.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/cloth/solver/cloth_color_particles.js"],"names":[],"mappings":"AAKA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AAEH;;;;;;;;;GASG;AACH,sDAPW,MAAM,oBACN,UAAU,GAAC,MAAM,EAAE,iBACnB,MAAM,iBACN,UAAU,GAAC,MAAM,EAAE,cACnB,MAAM,GACJ,WAAW,CAyFvB;AAmCD;;;;;;;;;;;;;GAaG;AACH,0CANW,WAAW,kBACX,MAAM,GACJ;IAAC,YAAY,EAAE,MAAM,CAAC;IAAC,aAAa,EAAE,UAAU,CAAC;IAAC,KAAK,EAAE,UAAU,CAAA;CAAC,CAmChF"}
+{"version":3,"file":"cloth_color_particles.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/cloth/solver/cloth_color_particles.js"],"names":[],"mappings":"AAMA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AAEH;;;;;;;;;GASG;AACH,sDAPW,MAAM,oBACN,UAAU,GAAC,MAAM,EAAE,iBACnB,MAAM,iBACN,UAAU,GAAC,MAAM,EAAE,cACnB,MAAM,GACJ,WAAW,CA+BvB;AA8BD;;;;;;;;;;;;;GAaG;AACH,0CANW,WAAW,kBACX,MAAM,GACJ;IAAC,YAAY,EAAE,MAAM,CAAC;IAAC,aAAa,EAAE,UAAU,CAAC;IAAC,KAAK,EAAE,UAAU,CAAA;CAAC,CAuBhF"}

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

@@ -1,7 +1,8 @@
 import { assert } from "../../../../core/assert.js";
-import { colorizeGraphGreedy } from "../../../../core/graph/coloring/colorizeGraphGreedy.js";
-import { validateGraphColoring } from "../../../../core/graph/coloring/validateGraphColoring.js";
-import { Graph } from "../../../../core/graph/v2/Graph.js";
+import { csr_build_incidence } from "../../../../core/graph/csr/csr_build_incidence.js";
+import { csr_graph_color_greedy } from "../../../../core/graph/csr/csr_graph_color_greedy.js";
+import { csr_graph_validate_coloring } from "../../../../core/graph/csr/csr_graph_validate_coloring.js";
+import { cloth_particle_coupling } from "./cloth_particle_coupling.js";
 
 /**
  * # Particle-graph colouring for the cloth solver
@@ -24,17 +25,19 @@ import { Graph } from "../../../../core/graph/v2/Graph.js";
  * against 76 for its 14,802 tetrahedra — the same asymmetry, and the reason
  * this design colours vertices rather than constraints.
  *
- * This runs **once**, at build time, on a `Graph` object. The runtime never
- * sees a graph: {@link ClothState} bakes the result into a permuted particle
- * order plus a range per colour, so the sweep is a pair of nested counted
- * loops over contiguous indices.
+ * This runs **once**, at build time, on the sorted CSR adjacency
+ * {@link cloth_particle_coupling} builds — the same edge set the
+ * self-collision exclusions are. The runtime never sees a graph:
+ * {@link ClothState} bakes the result into a permuted particle order plus a
+ * range per colour, so the sweep is a pair of nested counted loops over
+ * contiguous indices.
  *
  * The greedy colouriser is fed a largest-degree-first order (Welsh–Powell),
  * which is the cheap heuristic that gets a regular triangulated sheet down to
- * the 8–10 colours §5.4 predicts. The result is checked with the engine's own
- * {@link validateGraphColoring} behind `assert.*`, so a colouring that would
- * let two coupled particles race is caught in a dev build and compiles out of
- * a shipped one.
+ * the 8–10 colours §5.4 predicts. The result is checked with
+ * {@link csr_graph_validate_coloring} behind `assert.*`, so a colouring that
+ * would let two coupled particles race is caught in a dev build and compiles
+ * out of a shipped one.
  *
  * @author Alex Goldring
  * @copyright Company Named Limited (c) 2026
@@ -56,83 +59,25 @@ export function cloth_color_particles(
     bend_particle, bend_count
 ) {
     assert.isNonNegativeInteger(particle_count, 'particle_count');
-    assert.isNonNegativeInteger(stretch_count, 'stretch_count');
-    assert.isNonNegativeInteger(bend_count, 'bend_count');
 
-    if (particle_count === 0) {
-        return new Uint32Array(0);
-    }
-
-    const graph = new Graph();
-
-    // Nodes are the particle indices themselves, inserted in order, so the
-    // colouriser's node array is the identity permutation and `colors[i]` is
-    // the colour of particle `i` without a second lookup.
-    for (let i = 0; i < particle_count; i++) {
-        graph.addNode(i);
-    }
-
-    // `Graph#hasEdge` is identity-based, so the same pair added twice becomes
-    // two edges and shows up twice in a neighbour list. A garment adds every
-    // hinge's shared edge once as a stretch row and again as a bend pair, so
-    // the duplicates are the common case rather than the exception; they cost
-    // the colouriser a linear `indexOf` each. Fold them here instead.
-    const seen = new Set();
-
-    /**
-     * @param {number} a
-     * @param {number} b
-     */
-    const couple = (a, b) => {
-        if (a === b) {
-            return;
-        }
-
-        const key = a < b ? a * particle_count + b : b * particle_count + a;
+    const colors = new Uint32Array(particle_count);
 
-        if (seen.has(key)) {
-            return;
-        }
-
-        seen.add(key);
-
-        graph.createEdge(a, b);
-    };
-
-    // A stretch row couples its two endpoints.
-    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`);
-
-        couple(a, b);
+    if (particle_count === 0) {
+        return colors;
     }
 
-    // A bend stencil couples all six pairs of its four particles — every one
-    // of them appears in the same row, so any two of them writing at once is
-    // the race the colouring exists to prevent.
-    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++) {
-                couple(a, bend_particle[base + j]);
-            }
-        }
-    }
+    const { offset, partner } = cloth_particle_coupling(
+        particle_count,
+        stretch_particle, stretch_count,
+        bend_particle, bend_count
+    );
 
-    const order = order_by_descending_degree(graph, particle_count);
+    const order = order_by_descending_degree(offset, particle_count);
 
-    const colors = colorizeGraphGreedy(graph, order);
+    csr_graph_color_greedy(colors, offset, partner, order, particle_count);
 
     assert.ok(
-        validateGraphColoring(colors, graph),
+        csr_graph_validate_coloring(colors, offset, partner, particle_count),
         'cloth particle colouring is invalid — two coupled particles share a colour'
     );
 
@@ -147,18 +92,13 @@ export function cloth_color_particles(
  * Ties are broken by particle index so the ordering — and therefore the whole
  * baked layout — is a deterministic function of the topology alone.
  *
- * @param {Graph<number>} graph
+ * @param {Int32Array} offset CSR offsets of the deduplicated particle graph, so
+ *   a row's length is the particle's degree
  * @param {number} particle_count
  * @returns {Uint32Array}
  * @private
  */
-function order_by_descending_degree(graph, particle_count) {
-    const degree = new Int32Array(particle_count);
-
-    for (let i = 0; i < particle_count; i++) {
-        degree[i] = graph.getNeighbours(i).length;
-    }
-
+function order_by_descending_degree(offset, particle_count) {
     const order = new Uint32Array(particle_count);
 
     for (let i = 0; i < particle_count; i++) {
@@ -167,7 +107,7 @@ function order_by_descending_degree(graph, particle_count) {
 
     // `Array#sort` over a typed array is a numeric sort already; the comparator
     // is here for the tie-break, not for the ordering of the degrees.
-    order.sort((a, b) => (degree[b] - degree[a]) || (a - b));
+    order.sort((a, b) => ((offset[b + 1] - offset[b]) - (offset[a + 1] - offset[a])) || (a - b));
 
     return order;
 }
@@ -200,21 +140,9 @@ export function cloth_color_order(colors, particle_count) {
     }
 
     const colour_offset = new Int32Array(colour_count + 1);
-
-    for (let i = 0; i < particle_count; i++) {
-        colour_offset[colors[i] + 1]++;
-    }
-
-    for (let c = 0; c < colour_count; c++) {
-        colour_offset[c + 1] += colour_offset[c];
-    }
-
-    const cursor = colour_offset.slice(0, colour_count);
     const order = new Int32Array(particle_count);
 
-    for (let i = 0; i < particle_count; i++) {
-        order[cursor[colors[i]]++] = i;
-    }
+    csr_build_incidence(colour_offset, order, colors, particle_count, colour_count);
 
     return { colour_count, colour_offset, order };
 }