@woosh/meep-engine 3.23.0 → 3.25.0

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

@@ -1,80 +1,17 @@
 /**
- * # 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
+ * Slots in {@link ClothStateresult } — what one step answers with.
  */
+export type ClothStepResult = number;
+export namespace ClothStepResult {
+    let SPEED: number;
+    let CONTACT_COUNT: number;
+    let SELF_PAIRS: number;
+}
+/**
+ * `Float64` words in {@link ClothState#result}.
+ * @type {number}
+ */
+export const CLOTH_STEP_RESULT_WORDS: number;
 export class ClothState {
     /**
      * Build a cloth from a rest configuration and its rows.
@@ -105,9 +42,14 @@ export class ClothState {
      * @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
+     * @param {boolean} [description.shared] back the buffer with a
+     *   {@link SharedArrayBuffer} so a worker can step it in place. Throws where
+     *   `SharedArrayBuffer` does not exist — a page that is not cross-origin
+     *   isolated is one where the worker path cannot run, and silently handing
+     *   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 }: {
+    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 }: {
         position: Float32Array | number[];
         mass_inverse: Float32Array | number[];
         stretch_particle?: Int32Array | number[];
@@ -122,12 +64,43 @@ export class ClothState {
         leash_radius?: Float32Array | number[];
         backstop_particle?: Int32Array | number[];
         backstop_radius?: Float32Array | number[];
+        shared?: boolean;
+    }): ClothState;
+    /**
+     * Attach to a state built on another thread. The views are cut by the same
+     * {@link allocate} the original ran, so the two objects see identical
+     * regions at identical offsets — no serialized layout to drift, because
+     * there is only one function that knows the layout.
+     *
+     * Build-time content (rows, adjacency, the colour permutation) is already in
+     * the buffer and is not rewritten; only the views are new.
+     *
+     * @param {{buffer: SharedArrayBuffer, particle_count: number, stretch_count: number,
+     *   bend_count: number, leash_count: number, backstop_count: number, colour_count: number}} descriptor
+     * @returns {ClothState}
+     */
+    static fromSharedDescriptor(descriptor: {
+        buffer: SharedArrayBuffer;
+        particle_count: number;
+        stretch_count: number;
+        bend_count: number;
+        leash_count: number;
+        backstop_count: number;
+        colour_count: number;
     }): ClothState;
     /**
-     * The single allocation every view below is cut from.
-     * @type {ArrayBuffer}
+     * The single allocation every view below is cut from. A
+     * {@link SharedArrayBuffer} when the cloth was built for a worker, and an
+     * ordinary one otherwise — nothing else about the layout changes, which is
+     * what makes the worker a deployment choice rather than a second format.
+     * @type {ArrayBuffer|SharedArrayBuffer}
      */
-    buffer: ArrayBuffer;
+    buffer: ArrayBuffer | SharedArrayBuffer;
+    /**
+     * What the last step answered — see {@link ClothStepResult}.
+     * @type {Float64Array}
+     */
+    result: Float64Array;
     /**
      * @type {number}
      */
@@ -410,6 +383,33 @@ export class ClothState {
      * @type {number}
      */
     contact_radius: number;
+    /**
+     * This step's colliders, packed, in the **cloth's own frame** —
+     * {@link CLOTH_COLLIDER_SLOTS} records of `CCR_STRIDE` floats, rewritten
+     * every step by `cloth_gather_colliders`.
+     *
+     * §12's table always listed the colliders as a region of the cloth's own
+     * area; M2 kept them on {@link ClothInstance} and grew the array on demand,
+     * on the grounds that the size is a property of the world rather than of the
+     * cloth. Both are true, and the one that decides is the worker: a region
+     * inside this buffer needs no second registration when the broadphase
+     * happens to return more.
+     * @type {Float32Array}
+     */
+    collider_table: Float32Array;
+    /**
+     * The index handle behind each record in {@link collider_table}. A record
+     * index is this step's; a handle is the collider's, and it is what a
+     * transient contact's multiplier is warm-started on.
+     * @type {Int32Array}
+     */
+    collider_key: Int32Array;
+    /**
+     * Live records in {@link collider_table}, at most
+     * {@link CLOTH_COLLIDER_SLOTS}.
+     * @type {number}
+     */
+    collider_count: number;
     /**
      * Which collider each contact slot holds, `CLOTH_CONTACT_SLOTS` per
      * particle. A **record index into the caller's packed collider table**, not
@@ -522,5 +522,60 @@ export class ClothState {
      * @type {Float32Array}
      */
     contact_anchor: Float32Array;
+    /**
+     * The air each particle sits in, 3 per particle, **in the cloth's own
+     * frame**, metres per second (§10).
+     *
+     * Written by the main thread — `cloth_sample_air` — and read by the step,
+     * which is the whole of M6's answer to "which side of the worker bridge does
+     * wind sampling run on". A fluid field is a hundred thousand floats rewritten
+     * every step by a solver that may itself be on another worker; the *answer*
+     * is three floats a particle. So the field stays where it is and the answer
+     * crosses — and it crosses for free, because this is a region of the cloth's
+     * own `SharedArrayBuffer` and the main thread writes exactly where the worker
+     * reads. `MEASUREMENTS.md` §45.
+     *
+     * Stale rather than absent when a cloth has no wind: the step skips the
+     * aerodynamic term entirely when its drag response is zero, so what this
+     * holds is whatever the last windy step left.
+     * @type {Float32Array}
+     */
+    air_velocity: Float32Array;
+    /**
+     * Gravity plus §10's aerodynamic drag, 3 per particle, cloth-local, m/s².
+     *
+     * Built once per step by `cloth_wind_accelerate` and read by `cloth_step`
+     * in place of its uniform gravity vector. It is in the buffer rather than in
+     * a module scratch for two reasons: §12's one-allocation-per-cloth property,
+     * which M5 spent a milestone making true; and the bit-parity gate, which
+     * compares this buffer byte for byte and therefore covers the derived
+     * acceleration rather than only its inputs.
+     * @type {Float32Array}
+     */
+    external_acceleration: Float32Array;
+    /**
+     * @returns {boolean} whether the buffer is shared with a worker.
+     */
+    isSharedMemory(): boolean;
+    /**
+     * Everything a second thread needs to cut the same views over the same
+     * bytes: the buffer, and the six counts the layout is a function of.
+     *
+     * Structured-cloneable, and the buffer inside it is *shared* rather than
+     * copied — which is the whole point, and is why {@link isSharedMemory} is
+     * asserted here rather than discovered on the far side.
+     *
+     * @returns {{buffer: SharedArrayBuffer, particle_count: number, stretch_count: number,
+     *   bend_count: number, leash_count: number, backstop_count: number, colour_count: number}}
+     */
+    getSharedDescriptor(): {
+        buffer: SharedArrayBuffer;
+        particle_count: number;
+        stretch_count: number;
+        bend_count: number;
+        leash_count: number;
+        backstop_count: number;
+        colour_count: number;
+    };
 }
 //# sourceMappingURL=ClothState.d.ts.map

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,5 +1,7 @@
 import { assert } from "../../../../core/assert.js";
+import { CCR_STRIDE } from "../collider/ClothColliderRecord.js";
 import { cloth_color_order, cloth_color_particles } from "./cloth_color_particles.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";
 
@@ -77,17 +79,80 @@ import { CLOTH_CONTACT_SLOTS } from "./constraint/cloth_contact_row.js";
  * 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.
  *
+ * ## The air is in here too, and it is the one region the main thread writes
+ *
+ * M6's wind (§10) samples a fluid field per particle per step, and a fluid field
+ * is not a thing that can cross to a cloth worker. So what crosses is the
+ * **sampled answer**: {@link ClothState#air_velocity}, written by the main
+ * thread into this buffer and read by the step on the far side of it. Every
+ * other region here is written by whichever thread runs the step; this one is
+ * the direction the buffer was already able to carry and nobody had used.
+ *
+ * ## The step's scalar results come back in the buffer too
+ *
+ * Everything above is state the step reads and writes. {@link ClothState#result}
+ * is the other direction and the reason it exists is the worker: a step that
+ * runs on another thread can only answer through memory both threads hold, and
+ * the three things a caller needs back from one — the largest speed left, which
+ * the sleep test reads, and the two diagnostic counts — are scalars rather than
+ * arrays. They sit in the buffer instead of on the object because a
+ * `ClothState` attached over shared memory in a worker is a *different object*
+ * over the *same bytes*, so a plain field on it is invisible to the main thread.
+ *
+ * `Float64` rather than `Float32`, at the head of the buffer where the
+ * alignment is free: the speed is compared against a sleep threshold, and an f32
+ * round on one side of that comparison and not the other is exactly the kind of
+ * divergence §12's bit-parity gate exists to forbid.
+ *
  * @author Alex Goldring
  * @copyright Company Named Limited (c) 2026
  */
+
+/**
+ * Slots in {@link ClothState#result} — what one step answers with.
+ *
+ * @readonly
+ * @enum {number}
+ */
+export const ClothStepResult = {
+    /**
+     * Largest particle speed after the velocity clamp, m/s. §7 P1's clamp
+     * reports it and §7 P5's sleep test reads it.
+     */
+    SPEED: 0,
+    /**
+     * Contact rows the step created. Diagnostic.
+     */
+    CONTACT_COUNT: 1,
+    /**
+     * Self-collision pairs the step found. Diagnostic.
+     */
+    SELF_PAIRS: 2
+};
+
+/**
+ * `Float64` words in {@link ClothState#result}.
+ * @type {number}
+ */
+export const CLOTH_STEP_RESULT_WORDS = 3;
+
 export class ClothState {
 
     /**
-     * The single allocation every view below is cut from.
-     * @type {ArrayBuffer}
+     * The single allocation every view below is cut from. A
+     * {@link SharedArrayBuffer} when the cloth was built for a worker, and an
+     * ordinary one otherwise — nothing else about the layout changes, which is
+     * what makes the worker a deployment choice rather than a second format.
+     * @type {ArrayBuffer|SharedArrayBuffer}
      */
     buffer = null;
 
+    /**
+     * What the last step answered — see {@link ClothStepResult}.
+     * @type {Float64Array}
+     */
+    result = null;
+
     /**
      * @type {number}
      */
@@ -415,6 +480,36 @@ export class ClothState {
      */
     contact_radius = 0;
 
+    /**
+     * This step's colliders, packed, in the **cloth's own frame** —
+     * {@link CLOTH_COLLIDER_SLOTS} records of `CCR_STRIDE` floats, rewritten
+     * every step by `cloth_gather_colliders`.
+     *
+     * §12's table always listed the colliders as a region of the cloth's own
+     * area; M2 kept them on {@link ClothInstance} and grew the array on demand,
+     * on the grounds that the size is a property of the world rather than of the
+     * cloth. Both are true, and the one that decides is the worker: a region
+     * inside this buffer needs no second registration when the broadphase
+     * happens to return more.
+     * @type {Float32Array}
+     */
+    collider_table = null;
+
+    /**
+     * The index handle behind each record in {@link collider_table}. A record
+     * index is this step's; a handle is the collider's, and it is what a
+     * transient contact's multiplier is warm-started on.
+     * @type {Int32Array}
+     */
+    collider_key = null;
+
+    /**
+     * Live records in {@link collider_table}, at most
+     * {@link CLOTH_COLLIDER_SLOTS}.
+     * @type {number}
+     */
+    collider_count = 0;
+
     /**
      * Which collider each contact slot holds, `CLOTH_CONTACT_SLOTS` per
      * particle. A **record index into the caller's packed collider table**, not
@@ -539,6 +634,39 @@ export class ClothState {
      */
     contact_anchor = null;
 
+    /**
+     * The air each particle sits in, 3 per particle, **in the cloth's own
+     * frame**, metres per second (§10).
+     *
+     * Written by the main thread — `cloth_sample_air` — and read by the step,
+     * which is the whole of M6's answer to "which side of the worker bridge does
+     * wind sampling run on". A fluid field is a hundred thousand floats rewritten
+     * every step by a solver that may itself be on another worker; the *answer*
+     * is three floats a particle. So the field stays where it is and the answer
+     * crosses — and it crosses for free, because this is a region of the cloth's
+     * own `SharedArrayBuffer` and the main thread writes exactly where the worker
+     * reads. `MEASUREMENTS.md` §45.
+     *
+     * Stale rather than absent when a cloth has no wind: the step skips the
+     * aerodynamic term entirely when its drag response is zero, so what this
+     * holds is whatever the last windy step left.
+     * @type {Float32Array}
+     */
+    air_velocity = null;
+
+    /**
+     * Gravity plus §10's aerodynamic drag, 3 per particle, cloth-local, m/s².
+     *
+     * Built once per step by `cloth_wind_accelerate` and read by `cloth_step`
+     * in place of its uniform gravity vector. It is in the buffer rather than in
+     * a module scratch for two reasons: §12's one-allocation-per-cloth property,
+     * which M5 spent a milestone making true; and the bit-parity gate, which
+     * compares this buffer byte for byte and therefore covers the derived
+     * acceleration rather than only its inputs.
+     * @type {Float32Array}
+     */
+    external_acceleration = null;
+
     /**
      * Build a cloth from a rest configuration and its rows.
      *
@@ -568,6 +696,11 @@ export class ClothState {
      * @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
+     * @param {boolean} [description.shared] back the buffer with a
+     *   {@link SharedArrayBuffer} so a worker can step it in place. Throws where
+     *   `SharedArrayBuffer` does not exist — a page that is not cross-origin
+     *   isolated is one where the worker path cannot run, and silently handing
+     *   back private memory would make both threads mutate copies of it.
      * @returns {ClothState}
      */
     static from({
@@ -584,7 +717,8 @@ export class ClothState {
         leash_particle = EMPTY_INT32,
         leash_radius = EMPTY_FLOAT32,
         backstop_particle = EMPTY_INT32,
-        backstop_radius = EMPTY_FLOAT32
+        backstop_radius = EMPTY_FLOAT32,
+        shared = false
     }) {
         const particle_count = mass_inverse.length;
         const stretch_count = stretch_rest.length;
@@ -617,7 +751,11 @@ export class ClothState {
 
         const state = new ClothState();
 
-        allocate(state, particle_count, stretch_count, bend_count, leash_count, backstop_count, colour_count);
+        allocate(
+            state,
+            particle_count, stretch_count, bend_count, leash_count, backstop_count, colour_count,
+            shared ? allocate_shared : allocate_private
+        );
 
         state.colour_offset.set(colour_offset);
         state.source_of_particle.set(order);
@@ -729,6 +867,95 @@ export class ClothState {
 
         return state;
     }
+
+    /**
+     * @returns {boolean} whether the buffer is shared with a worker.
+     */
+    isSharedMemory() {
+        return typeof SharedArrayBuffer === "function" && this.buffer instanceof SharedArrayBuffer;
+    }
+
+    /**
+     * Everything a second thread needs to cut the same views over the same
+     * bytes: the buffer, and the six counts the layout is a function of.
+     *
+     * Structured-cloneable, and the buffer inside it is *shared* rather than
+     * copied — which is the whole point, and is why {@link isSharedMemory} is
+     * asserted here rather than discovered on the far side.
+     *
+     * @returns {{buffer: SharedArrayBuffer, particle_count: number, stretch_count: number,
+     *   bend_count: number, leash_count: number, backstop_count: number, colour_count: number}}
+     */
+    getSharedDescriptor() {
+        assert.ok(this.isSharedMemory(), 'ClothState.getSharedDescriptor: the state is not shared-memory backed');
+
+        return {
+            buffer: this.buffer,
+            particle_count: this.particle_count,
+            stretch_count: this.stretch_count,
+            bend_count: this.bend_count,
+            leash_count: this.leash_count,
+            backstop_count: this.backstop_count,
+            colour_count: this.colour_count
+        };
+    }
+
+    /**
+     * Attach to a state built on another thread. The views are cut by the same
+     * {@link allocate} the original ran, so the two objects see identical
+     * regions at identical offsets — no serialized layout to drift, because
+     * there is only one function that knows the layout.
+     *
+     * Build-time content (rows, adjacency, the colour permutation) is already in
+     * the buffer and is not rewritten; only the views are new.
+     *
+     * @param {{buffer: SharedArrayBuffer, particle_count: number, stretch_count: number,
+     *   bend_count: number, leash_count: number, backstop_count: number, colour_count: number}} descriptor
+     * @returns {ClothState}
+     */
+    static fromSharedDescriptor(descriptor) {
+        const state = new ClothState();
+
+        allocate(
+            state,
+            descriptor.particle_count,
+            descriptor.stretch_count,
+            descriptor.bend_count,
+            descriptor.leash_count,
+            descriptor.backstop_count,
+            descriptor.colour_count,
+            () => descriptor.buffer
+        );
+
+        return state;
+    }
+}
+
+/**
+ * @param {number} byte_length
+ * @returns {ArrayBuffer}
+ * @private
+ */
+function allocate_private(byte_length) {
+    return new ArrayBuffer(byte_length);
+}
+
+/**
+ * @param {number} byte_length
+ * @returns {SharedArrayBuffer}
+ * @private
+ */
+function allocate_shared(byte_length) {
+    if (typeof SharedArrayBuffer !== "function") {
+        throw new Error(
+            "ClothState: SharedArrayBuffer is unavailable, so a worker-backed cloth cannot be built."
+            + " A WorkerClothSystem requires a cross-origin isolated page: serve with"
+            + " 'Cross-Origin-Opener-Policy: same-origin' and 'Cross-Origin-Embedder-Policy: require-corp',"
+            + " or use ClothSystem, which is the same solver on this thread."
+        );
+    }
+
+    return new SharedArrayBuffer(byte_length);
 }
 
 /**
@@ -744,23 +971,37 @@ const EMPTY_INT32 = new Int32Array(0);
 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.
+ * Cut every view out of one buffer, in declaration order. Sizes are counted in
+ * **4-byte elements**; the one `Float64` region sits first, where the buffer's
+ * own alignment already satisfies it, and costs two elements a word.
+ *
+ * The one function that knows the layout, deliberately: {@link
+ * ClothState.fromSharedDescriptor} attaches a second thread to the same bytes by
+ * running this again over the buffer it was handed, so there is no serialized
+ * description of the layout anywhere that could drift from the layout.
  *
  * @param {ClothState} state
  * @param {number} particle_count
  * @param {number} stretch_count
  * @param {number} bend_count
  * @param {number} leash_count
+ * @param {number} backstop_count
  * @param {number} colour_count
+ * @param {function(number): (ArrayBuffer|SharedArrayBuffer)} acquire given the
+ *   byte length, answers the buffer to cut — a fresh private one, a fresh shared
+ *   one, or an existing one being re-attached
  * @private
  */
-function allocate(state, particle_count, stretch_count, bend_count, leash_count, backstop_count, colour_count) {
+function allocate(
+    state,
+    particle_count, stretch_count, bend_count, leash_count, backstop_count, colour_count,
+    acquire
+) {
     const contact_count = particle_count * CLOTH_CONTACT_SLOTS;
     const self_capacity = particle_count * CLOTH_SELF_PAIRS_PER_PARTICLE;
 
     const sizes = [
+        CLOTH_STEP_RESULT_WORDS * 2,    // result — Float64, first for its alignment
         particle_count * 3,     // position
         particle_count * 3,     // position_previous
         particle_count * 3,     // velocity
@@ -799,6 +1040,8 @@ function allocate(state, particle_count, stretch_count, bend_count, leash_count,
         backstop_count,         // backstop_penalty
         particle_count + 1,     // backstop_adjacency_offset
         backstop_count,         // backstop_adjacency
+        CLOTH_COLLIDER_SLOTS * CCR_STRIDE,  // collider_table
+        CLOTH_COLLIDER_SLOTS,   // collider_key
         contact_count,          // contact_collider
         contact_count,          // contact_key
         contact_count,          // contact_lambda
@@ -808,7 +1051,9 @@ function allocate(state, particle_count, stretch_count, bend_count, leash_count,
         contact_count * 3,      // contact_anchor
         self_capacity * 2,      // self_pair
         particle_count * 3,     // self_force
-        particle_count * 6      // self_hessian
+        particle_count * 6,     // self_hessian
+        particle_count * 3,     // air_velocity
+        particle_count * 3      // external_acceleration
     ];
 
     let total = 0;
@@ -817,18 +1062,20 @@ function allocate(state, particle_count, stretch_count, bend_count, leash_count,
         total += sizes[i];
     }
 
-    const buffer = new ArrayBuffer(total * 4);
+    const buffer = acquire(total * 4);
+
+    assert.equal(buffer.byteLength, total * 4, 'ClothState buffer byte length');
 
     let cursor = 0;
 
     /**
-     * @param {Float32ArrayConstructor|Int32ArrayConstructor} type
+     * @param {Float32ArrayConstructor|Int32ArrayConstructor|Float64ArrayConstructor} type
      * @param {number} length
      */
     const cut = (type, length) => {
         const view = new type(buffer, cursor * 4, length);
 
-        cursor += length;
+        cursor += length * (type.BYTES_PER_ELEMENT / 4);
 
         return view;
     };
@@ -841,6 +1088,8 @@ function allocate(state, particle_count, stretch_count, bend_count, leash_count,
     state.backstop_count = backstop_count;
     state.colour_count = colour_count;
 
+    state.result = cut(Float64Array, CLOTH_STEP_RESULT_WORDS);
+
     state.position = cut(Float32Array, particle_count * 3);
     state.position_previous = cut(Float32Array, particle_count * 3);
     state.velocity = cut(Float32Array, particle_count * 3);
@@ -884,6 +1133,9 @@ function allocate(state, particle_count, stretch_count, bend_count, leash_count,
     state.backstop_adjacency_offset = cut(Int32Array, particle_count + 1);
     state.backstop_adjacency = cut(Int32Array, backstop_count);
 
+    state.collider_table = cut(Float32Array, CLOTH_COLLIDER_SLOTS * CCR_STRIDE);
+    state.collider_key = cut(Int32Array, CLOTH_COLLIDER_SLOTS);
+
     state.contact_collider = cut(Int32Array, contact_count);
     state.contact_key = cut(Int32Array, contact_count);
     state.contact_lambda = cut(Float32Array, contact_count);
@@ -896,6 +1148,15 @@ function allocate(state, particle_count, stretch_count, bend_count, leash_count,
     state.self_force = cut(Float32Array, particle_count * 3);
     state.self_hessian = cut(Float32Array, particle_count * 6);
 
+    // M6's two, last rather than beside the other per-particle regions, and the
+    // placement is the point. A cloth with no wind never touches them, so
+    // putting them between `inertia_blend` and the row tables would push
+    // twenty-four bytes a particle — twenty-four kilobytes on the §17 workload —
+    // between the sweep and the rows it reads, for a feature that step is not
+    // running. Cold regions go at the cold end.
+    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');
 }