@woosh/meep-engine 3.21.0 → 3.22.0

package/src/engine/physics/cloth/ecs/cloth_write_back.js

@@ -0,0 +1,449 @@
+import { quat3_multiply } from "../../../../core/geom/3d/quaternion/quat3_multiply.js";
+import { quat3_nlerp } from "../../../../core/geom/3d/quaternion/quat3_nlerp.js";
+import { quat3_shortest_arc } from "../../../../core/geom/3d/quaternion/quat3_shortest_arc.js";
+import { v3_quaternion_apply } from "../../../../core/geom/vec3/v3_quaternion_apply.js";
+import {
+    v3_quaternion_apply_inverse
+} from "../../../../core/geom/vec3/v3_quaternion_apply_inverse.js";
+import { t64_announce_change } from "../../../ecs/transform/t64_announce_change.js";
+import {
+    TRANSFORM64_ROTATION_OFFSET,
+    TRANSFORM64_TRANSLATION_OFFSET
+} from "../../../ecs/transform/Transform64.js";
+
+/**
+ * # Putting the answer back — §11.1
+ *
+ * Position directly, rotation derived from the direction to the child,
+ * interpolated between the parent-driven and the child-driven orientation —
+ * which is what keeps a two-link chain from looking hinged.
+ *
+ * ## Rotation is a swing on top of the animated orientation
+ *
+ * A particle has a position and no orientation, so an entity's rotation has to
+ * be reconstructed. The reconstruction here is the minimal rotation carrying
+ * the link's **animated** direction onto its **simulated** one, composed onto
+ * the animated orientation:
+ *
+ *     q_node = swing(d_animated → d_simulated) ⊗ q_animated
+ *
+ * Twist about the link is therefore inherited from the animation rather than
+ * invented, which is right: a chain of particles carries no twist degree of
+ * freedom and any twist this code produced would be a fabrication. And the
+ * whole thing degenerates correctly — at `blend = 0` the simulated direction
+ * *is* the animated one, the swing is the identity, and the write-back
+ * reproduces the authored pose exactly.
+ *
+ * A node with a parent and children has two links and two swings, and takes the
+ * half-way rotation between them. A leaf has only its parent's. That is
+ * §11.1's "interpolated between parent-driven and child-driven orientation",
+ * and without it every link points at its child and a two-link chain reads as a
+ * hinge with a corner in it.
+ *
+ * ## Both transforms are written, and that is what makes ordering harmless
+ *
+ * Each simulated node gets its **world** `Transform64` and its **local**
+ * `TransformAttachment#transform`, and the two agree. Writing only the world
+ * one is cheaper and is a trap: the attachment system recomposes a child from
+ * its local whenever the parent announces, so any announcement arriving after
+ * cloth had written would replace the simulated pose with the authored one for
+ * the rest of the frame — and where in the fixed step cloth ran would be a
+ * correctness question. With the local written too, **a recomposition
+ * reproduces exactly what cloth just wrote**, and cloth's placement costs at
+ * worst a shape one fixed step stale.
+ *
+ * That is also the shape of the engine's own precedent:
+ * `InverseKinematicsSystem` reads world transforms the hierarchy has composed
+ * and writes local ones back, and §11.2's rig path writes
+ * `Node3D.transform_local` for the same reason — a local transform is what a
+ * joint angle *is*.
+ *
+ * A node's local transform is its pose relative to its **parent's**, so this
+ * needs the parent's reconstructed rotation as well as its position — which is
+ * what {@link ClothInstance#blended_rotation} is for, and why the pass runs in
+ * the walk's breadth-first order.
+ *
+ * The authored pose is not lost by being overwritten: it was captured at seed
+ * and lives in the cloth (`cloth_seed_subtree.js`), which is what `blend = 0`
+ * returns to and what the leash centres are measured from.
+ *
+ * ## What is announced
+ *
+ * Nothing on a simulated node: every one of its simulated children has already
+ * been written by this same pass, so the cascade would recompute a pose that is
+ * already correct, once per level, quadratically for a chain. What *is*
+ * announced is each pruned boundary — the root of a `ClothExclude` subtree, or
+ * a nested `Cloth`'s anchor — which this pass poses by hand against the link it
+ * hangs from, so everything below the cut follows the simulation through the
+ * ordinary attachment cascade and nothing above it is disturbed.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+
+/**
+ * Scratch for one node's swing quaternions. Module-level: the write-back
+ * allocates nothing.
+ * @type {Float64Array}
+ * @private
+ */
+const SWING = new Float64Array(12);
+
+/** Where the parent-driven swing sits in {@link SWING}. @private */
+const SWING_PARENT = 0;
+/** Where the child-driven swing sits in {@link SWING}. @private */
+const SWING_CHILD = 4;
+/** Where the blended swing, and then the local rotation, sit. @private */
+const SWING_OUT = 8;
+
+/**
+ * @type {Float64Array}
+ * @private
+ */
+const DIRECTION = new Float64Array(12);
+
+/**
+ * Write one cloth's solved pose onto its subtree.
+ *
+ * @param {ClothInstance} instance
+ * @param {EntityComponentDataset} ecd
+ * @returns {void}
+ */
+export function cloth_write_back(instance, ecd) {
+    const node_count = instance.node_count;
+
+    const state = instance.state;
+    const particle_of_node = instance.particle_of_node;
+
+    const blended = instance.blended_position;
+    const animated = instance.animated_position;
+
+    let blend = instance.cloth.blend;
+
+    if (blend < 0) {
+        blend = 0;
+    } else if (blend > 1) {
+        blend = 1;
+    }
+
+    const position = state.position;
+
+    for (let node = 0; node < node_count; node++) {
+        const p = particle_of_node[node] * 3;
+        const n = node * 3;
+
+        blended[n] = animated[n] + blend * (position[p] - animated[n]);
+        blended[n + 1] = animated[n + 1] + blend * (position[p + 1] - animated[n + 1]);
+        blended[n + 2] = animated[n + 2] + blend * (position[p + 2] - animated[n + 2]);
+    }
+
+    const anchor = instance.node_transform[0];
+
+    const ax = anchor[TRANSFORM64_TRANSLATION_OFFSET];
+    const ay = anchor[TRANSFORM64_TRANSLATION_OFFSET + 1];
+    const az = anchor[TRANSFORM64_TRANSLATION_OFFSET + 2];
+
+    const aqx = anchor[TRANSFORM64_ROTATION_OFFSET];
+    const aqy = anchor[TRANSFORM64_ROTATION_OFFSET + 1];
+    const aqz = anchor[TRANSFORM64_ROTATION_OFFSET + 2];
+    const aqw = anchor[TRANSFORM64_ROTATION_OFFSET + 3];
+
+    const parent = instance.node_parent;
+    const rotation = instance.animated_rotation;
+
+    const local_rotation = instance.blended_rotation;
+
+    // The anchor is the origin of the frame it anchors, so its reconstructed
+    // rotation — which its children's local transforms are relative to — is the
+    // identity rather than anything read back off it.
+    local_rotation[0] = 0;
+    local_rotation[1] = 0;
+    local_rotation[2] = 0;
+    local_rotation[3] = 1;
+
+    for (let node = 1; node < node_count; node++) {
+        const transform = instance.node_transform[node];
+
+        const n = node * 3;
+
+        v3_quaternion_apply(
+            transform, TRANSFORM64_TRANSLATION_OFFSET,
+            blended[n], blended[n + 1], blended[n + 2],
+            aqx, aqy, aqz, aqw
+        );
+
+        transform[TRANSFORM64_TRANSLATION_OFFSET] += ax;
+        transform[TRANSFORM64_TRANSLATION_OFFSET + 1] += ay;
+        transform[TRANSFORM64_TRANSLATION_OFFSET + 2] += az;
+
+        const has_parent_swing = link_swing(instance, parent[node], node, SWING_PARENT);
+        const has_child_swing = children_swing(instance, node, SWING_CHILD);
+
+        let swing = SWING_OUT;
+
+        if (has_parent_swing && has_child_swing) {
+            quat3_nlerp(
+                SWING, SWING_OUT,
+                SWING[SWING_PARENT], SWING[SWING_PARENT + 1], SWING[SWING_PARENT + 2], SWING[SWING_PARENT + 3],
+                SWING[SWING_CHILD], SWING[SWING_CHILD + 1], SWING[SWING_CHILD + 2], SWING[SWING_CHILD + 3],
+                0.5
+            );
+        } else if (has_child_swing) {
+            swing = SWING_CHILD;
+        } else {
+            // A leaf, or a link so short its direction is meaningless — in
+            // which case `link_swing` left the identity there.
+            swing = SWING_PARENT;
+        }
+
+        // Animated orientation first, then the swing: the swing is expressed in
+        // the cloth's local frame, and the anchor's rotation carries the pair
+        // out to world.
+        quat3_multiply(
+            local_rotation, node * 4,
+            SWING[swing], SWING[swing + 1], SWING[swing + 2], SWING[swing + 3],
+            rotation[node * 4], rotation[node * 4 + 1], rotation[node * 4 + 2], rotation[node * 4 + 3]
+        );
+
+        quat3_multiply(
+            transform, TRANSFORM64_ROTATION_OFFSET,
+            aqx, aqy, aqz, aqw,
+            local_rotation[node * 4], local_rotation[node * 4 + 1],
+            local_rotation[node * 4 + 2], local_rotation[node * 4 + 3]
+        );
+
+        transform.updateMatrix();
+
+        write_local(instance, node, parent[node]);
+    }
+
+    pose_pruned(instance, ecd);
+}
+
+/**
+ * Express one node's solved pose relative to its parent's, and write it into
+ * the entity's `TransformAttachment`.
+ *
+ * Both poses are already in the cloth's own frame, so the parent's inverse is
+ * its reconstructed rotation conjugated — there is no matrix inverse here and
+ * no scale, which is the same rigid-pose convention the colliders use.
+ *
+ * @param {ClothInstance} instance
+ * @param {number} node
+ * @param {number} parent
+ * @private
+ */
+function write_local(instance, node, parent) {
+    const attachment = instance.node_attachment[node];
+
+    if (attachment === undefined || attachment === null) {
+        return;
+    }
+
+    const blended = instance.blended_position;
+    const rotation = instance.blended_rotation;
+
+    const local = attachment.transform;
+
+    const pqx = rotation[parent * 4];
+    const pqy = rotation[parent * 4 + 1];
+    const pqz = rotation[parent * 4 + 2];
+    const pqw = rotation[parent * 4 + 3];
+
+    v3_quaternion_apply_inverse(
+        local, TRANSFORM64_TRANSLATION_OFFSET,
+        blended[node * 3] - blended[parent * 3],
+        blended[node * 3 + 1] - blended[parent * 3 + 1],
+        blended[node * 3 + 2] - blended[parent * 3 + 2],
+        pqx, pqy, pqz, pqw
+    );
+
+    quat3_multiply(
+        local, TRANSFORM64_ROTATION_OFFSET,
+        -pqx, -pqy, -pqz, pqw,
+        rotation[node * 4], rotation[node * 4 + 1], rotation[node * 4 + 2], rotation[node * 4 + 3]
+    );
+
+    // `multiplyTransforms` reads the matrix, not the components, so a local
+    // transform that is not refreshed here composes the pose it had last time.
+    local.updateMatrix();
+}
+
+/**
+ * Swing of the link from `from` to `to`, into `SWING` at `out`.
+ *
+ * @param {ClothInstance} instance
+ * @param {number} from node
+ * @param {number} to node
+ * @param {number} out
+ * @returns {boolean} false when the link is too short to carry a direction, in
+ *   which case the identity was written
+ * @private
+ */
+function link_swing(instance, from, to, out) {
+    const animated = instance.animated_position;
+    const blended = instance.blended_position;
+
+    const a = from * 3;
+    const b = to * 3;
+
+    const has_animated = unit(DIRECTION, 0,
+        animated[b] - animated[a], animated[b + 1] - animated[a + 1], animated[b + 2] - animated[a + 2]);
+
+    const has_blended = unit(DIRECTION, 3,
+        blended[b] - blended[a], blended[b + 1] - blended[a + 1], blended[b + 2] - blended[a + 2]);
+
+    if (!has_animated || !has_blended) {
+        identity(out);
+
+        return false;
+    }
+
+    quat3_shortest_arc(
+        SWING, out,
+        DIRECTION[0], DIRECTION[1], DIRECTION[2],
+        DIRECTION[3], DIRECTION[4], DIRECTION[5]
+    );
+
+    return true;
+}
+
+/**
+ * Swing of a node's outgoing links, averaged over its simulated children.
+ *
+ * The average is over **unit** directions rather than over child positions, so
+ * a fork whose two branches are of different lengths is not dominated by the
+ * longer one.
+ *
+ * @param {ClothInstance} instance
+ * @param {number} node
+ * @param {number} out
+ * @returns {boolean}
+ * @private
+ */
+function children_swing(instance, node, out) {
+    const start = instance.node_child_offset[node];
+    const end = instance.node_child_offset[node + 1];
+
+    if (start === end) {
+        identity(out);
+
+        return false;
+    }
+
+    const animated = instance.animated_position;
+    const blended = instance.blended_position;
+    const child = instance.node_child;
+
+    const a = node * 3;
+
+    let anim_x = 0, anim_y = 0, anim_z = 0;
+    let sim_x = 0, sim_y = 0, sim_z = 0;
+
+    for (let i = start; i < end; i++) {
+        const b = child[i] * 3;
+
+        if (unit(DIRECTION, 6,
+            animated[b] - animated[a], animated[b + 1] - animated[a + 1], animated[b + 2] - animated[a + 2])) {
+            anim_x += DIRECTION[6];
+            anim_y += DIRECTION[7];
+            anim_z += DIRECTION[8];
+        }
+
+        if (unit(DIRECTION, 9,
+            blended[b] - blended[a], blended[b + 1] - blended[a + 1], blended[b + 2] - blended[a + 2])) {
+            sim_x += DIRECTION[9];
+            sim_y += DIRECTION[10];
+            sim_z += DIRECTION[11];
+        }
+    }
+
+    const has_animated = unit(DIRECTION, 0, anim_x, anim_y, anim_z);
+    const has_blended = unit(DIRECTION, 3, sim_x, sim_y, sim_z);
+
+    if (!has_animated || !has_blended) {
+        // Branches that cancel — a node with two children pointing opposite
+        // ways has no outgoing direction to speak of, and the parent link is a
+        // better answer than an arbitrary one.
+        identity(out);
+
+        return false;
+    }
+
+    quat3_shortest_arc(
+        SWING, out,
+        DIRECTION[0], DIRECTION[1], DIRECTION[2],
+        DIRECTION[3], DIRECTION[4], DIRECTION[5]
+    );
+
+    return true;
+}
+
+/**
+ * Pose the entities the walk pruned, and announce there.
+ *
+ * @param {ClothInstance} instance
+ * @param {EntityComponentDataset} ecd
+ * @private
+ */
+function pose_pruned(instance, ecd) {
+    const count = instance.pruned_count;
+
+    for (let i = 0; i < count; i++) {
+        const transform = instance.pruned_transform[i];
+        const attachment = instance.pruned_attachment[i];
+
+        if (transform === undefined || attachment === undefined) {
+            continue;
+        }
+
+        transform.multiplyTransforms(
+            instance.node_transform[instance.pruned_parent[i]],
+            attachment.transform
+        );
+
+        // The one announcement this pass makes. Everything below a pruned
+        // boundary is outside the cloth and reaches its new pose through the
+        // ordinary attachment cascade; everything above it has already been
+        // written by hand.
+        t64_announce_change(ecd, instance.pruned_entity[i]);
+    }
+}
+
+/**
+ * Normalise into `DIRECTION`, reporting whether there was a direction to find.
+ *
+ * @param {Float64Array} out
+ * @param {number} offset
+ * @param {number} x
+ * @param {number} y
+ * @param {number} z
+ * @returns {boolean}
+ * @private
+ */
+function unit(out, offset, x, y, z) {
+    const length_squared = x * x + y * y + z * z;
+
+    if (length_squared < 1e-24) {
+        return false;
+    }
+
+    const inverse = 1 / Math.sqrt(length_squared);
+
+    out[offset] = x * inverse;
+    out[offset + 1] = y * inverse;
+    out[offset + 2] = z * inverse;
+
+    return true;
+}
+
+/**
+ * @param {number} offset
+ * @private
+ */
+function identity(offset) {
+    SWING[offset] = 0;
+    SWING[offset + 1] = 0;
+    SWING[offset + 2] = 0;
+    SWING[offset + 3] = 1;
+}

package/src/engine/physics/cloth/playground/README.md

@@ -0,0 +1,185 @@
+# Cloth playgrounds
+
+```
+npm run dev --workspace @woosh/meep-engine
+```
+
+Two pages, one directory, one layer of the system each. (Vite takes the next
+free port if 5173 is busy — the terminal says which.)
+
+| | |
+|---|---|
+| [`index.html`](./index.html) | **the solver, M0.** `cloth_step` over a `ClothState`, no ECS at all. |
+| [`rig.html`](./rig.html) | **the entity subtree, M1.** A real `EntityManager`, real entities, `ClothSystem` walking and writing back. |
+
+Both are at
+`http://localhost:5173/src/engine/physics/cloth/playground/<page>`.
+
+---
+
+# The solver page — `index.html`
+
+## What it is
+
+A `while (true) { cloth_step(...) }` with a canvas attached. Every point on
+screen is a `Float32Array` position out of `ClothState`, projected by this page;
+every control writes straight into an argument `cloth_step` takes; the tripwire
+is the same `find_non_finite_cloth_state` the step asserts on. There is no ECS,
+no worker and no renderer between you and the solver, because at M0 none of
+those exist yet.
+
+It is here because M0's findings are behavioural. "A penalty stiffer than a few
+times `m/h²` sustains a limit cycle" is a sentence; watching a curtain breathe
+in and out forever while the energy trace refuses to fall is the thing itself.
+
+## Controls
+
+| | |
+|---|---|
+| drag a particle | pins it and pulls — the solver moves everything around it |
+| drag the background | orbit |
+| shift-drag, or right-drag | pan |
+| wheel | zoom |
+
+**Shape** and **Material** rebuild the cloth. **Budget**, **World** and the
+**Solver constants** are read fresh every step, so dragging one of those sliders
+while it runs changes the thing you are looking at.
+
+## The readout
+
+- **step** — milliseconds for one `cloth_step`, with the window minimum, against
+  §17's 2 ms budget as a bar. The minimum is the honest number; see
+  `MEASUREMENTS.md` §7.
+- **residual** — worst `|C|/L₀` across the stretch rows. §7 P2's rubber number.
+- **kinetic energy**, with a log trace beneath it — the single most informative
+  thing on the page. A cloth that is settling walks it off the bottom of the
+  graph. A cloth that is not, does not, and no amount of waiting changes that.
+- **colours** — how many the particle graph needed. §5.4 budgets 8–10 for a
+  garment; a regular sheet comes out at 4.
+- **finite** — the tripwire. If a solve goes non-finite, or a Hessian pivot
+  comes out non-positive, the page stops and shows what said so rather than
+  painting over it.
+
+## The presets, and what each one is for
+
+- **cape, hard rows** — the shipping configuration. Watch the energy trace fall
+  off the bottom and stay there.
+- **cape, soft rows** — the same cape with a 10 kN/m penalty, which is 740× its
+  own `m/h²`. It never rests, and the step is *adding* energy to it, not merely
+  failing to remove it. This is what makes a soft stretch row unusable for real
+  fabric stiffnesses.
+- **cape, soft and slack** — the same row at 100 N/m, which is 7× `m/h²` and
+  inside the dissipative band. It settles. The difference between this preset
+  and the one above is the whole finding.
+- **chain, 40 links** — depth is how far a constraint force travels in one
+  sweep. Drop `iterations` to 1 and watch the bottom lag.
+- **flag in the wind** — a gusting push, not §10's fluid coupling (that is M6).
+- **the §17 workload** — 1,024 particles at 2×4, the configuration the budget
+  was written against and missed by 1.75×.
+- **α·γ = 0.6** — past the divergence cliff. The tripwire fires within a second
+  or two, which is the point.
+- **one iteration** — §5.1's claim that the solver is stable at one iteration.
+  Softer, not broken.
+
+## What it does not do
+
+Collision, self-collision, slack, tethers, backstops, friction and wind-as-fluid
+are all rows the design has and M0 does not (§6, §17). Neither does damping:
+`ClothDynamics#damping` is M1, and its absence is why the soft presets behave as
+they do.
+
+## Notes
+
+The scene builder here is deliberately not the `__fixtures__` grid the specs and
+the measurement scripts share — `__fixtures__` is excluded from the published
+package and this page is not, so importing across that line would ship a broken
+module.
+
+`globalThis.cloth_playground` exposes `{ control, camera, rebuild, step_once,
+scene }` for a driver script. The browser pages in this tree get screenshot from
+headless Chrome about as often as they get looked at; note that
+`requestAnimationFrame` does not fire while the pane is hidden, so a driver
+should call `step_once` itself rather than waiting for frames.
+
+---
+
+# The rig page — `rig.html`
+
+## What it is
+
+The same idea one layer up. A real `EntityManager` with a
+`TransformAttachmentSystem` and a `ClothSystem` in it, entities carrying
+`TransformAttachment` and `Transform64`, and a `Cloth` component on top of the
+pile. Every point on screen is an entity's **world transform**, read back out
+of the component the system wrote it into — so what you are looking at is the
+write-back, not the solver.
+
+It exists because M1's claims are about a *hierarchy* rather than about an
+array. "Several hanging parts under one `Cloth` are one coupled solve" is a
+sentence; five strands moving together above a readout that says **1 cloth, 91
+particles, 3 colours** is the thing itself.
+
+## The rigs
+
+- **rope** — one strand. The simplest thing the subtree walk does.
+- **chain** — the `CHAIN` library entry, which is the deepest budget in the
+  library at 2×6. Drop `iterations` to 1 and watch the bottom lag.
+- **multi-strand rig** — five strands under **one** `Cloth`. §3.1's claim, and
+  the reason the readout counts cloths separately from particles.
+- **hanging sign** — two ropes off a crossbar, with the sign itself carrying a
+  `ClothExclude`. It is drawn in amber, it is not a particle, and it follows the
+  link it hangs from because the write-back poses it by hand and announces
+  there.
+- **nested cloths** — a rope with a second `Cloth` partway down. Two solves; the
+  outer one prunes the inner anchor and runs first, so the inner cloth reads an
+  anchor that is already where this step put it.
+
+## The readout
+
+- **cloths / particles** — the coupled-solve claim, as two numbers.
+- **rows s / b / leash** — the stretch table (which carries the link rows, the
+  strain limits and the chain's skip rows), the bend table, and M1's leash rows.
+- **worst |x−anchor| / d_geo** — §7 P2's rubber number. Above 1 is a cloth
+  reaching further than its own geometry allows.
+- **asleep** — §7 P5. A settled cloth stops being stepped *and* stops being
+  written back, which is what makes its pose bit-identical rather than merely
+  stable. Turn `never sleep` on to watch it settle instead of watching it stop.
+- **fixed step** — milliseconds for one `ClothSystem#fixedUpdate`. Treat it as
+  an indication only: browser `performance.now()` is deliberately coarse, and a
+  hidden pane throttles the page. `__fixtures__/cloth_library_bench.mjs` under
+  node is the number that means something.
+
+## Driving the anchor
+
+§7 P6 and P7 are both about what the *anchor* does, so that is what the
+**motion** control drives — and it is the only thing on the page that writes a
+transform the cloth does not own, standing in for whatever poses an anchor in a
+real scene.
+
+- **sprint** is P7's own profile: a square wave in velocity. Move `inertia` from
+  1 to 0 while it runs and the cloth stops feeling the locomotion entirely.
+- **teleport 1 km** is P6. With `TeleportKeep` off the cloth re-seeds at the
+  animated pose and the stabilisation window ramps its velocity limit back from
+  nothing; with it on, the shape comes across the jump — which in a frame
+  anchored to the cloth's own entity is the solver doing nothing at all.
+
+## The views
+
+- **links** — the entities and what connects them.
+- **animated pose** — the pose the cloth is leashed to, faint and blue. The gap
+  between the two lines is what `slack` bounds; drag `slack` to 0 and they
+  become one line, which is §3.4's "at `slack = 0` every particle is welded to
+  its animated position".
+- **frames** — the orientation the write-back reconstructed, as an axis triple
+  per entity. A particle has no orientation, so this is §11.1's swing: the
+  minimal rotation from the link's animated direction to its simulated one,
+  half-way between the parent-driven and child-driven answers.
+
+## Notes
+
+`globalThis.cloth_rig_playground` exposes `{ control, camera, ready, rebuild,
+step_once, render, scene }`. Two differences from the solver page and both are
+real: `rebuild` returns a promise, because `EntityManager#startup` does and an
+entity created before it resolves is never linked; and `render` is separate from
+`step_once`, because `requestAnimationFrame` does not fire in a hidden pane and
+everything on the page hangs off it.

package/src/engine/physics/cloth/playground/cloth_playground_build.d.ts

@@ -0,0 +1,58 @@
+/**
+ * # Building the playground's cloth
+ *
+ * Two shapes, because two shapes are what M0's rows can express between them: a
+ * triangulated sheet, which exercises stretch and bend together over a mesh
+ * eight colours wide, and a chain, which is the same stretch row at depth with
+ * no bending at all and is where a solver's convergence shows most plainly.
+ *
+ * This is playground code rather than the `__fixtures__` grid the specs and the
+ * measurement scripts share. It has to be: `__fixtures__` is excluded from the
+ * published package and this page is not, so importing across that line would
+ * ship a broken module. It also wants different things — several pinning
+ * modes, a chain, and a triangle list to draw.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+/**
+ * @typedef {object} ClothPlaygroundScene
+ * @property {ClothState} state
+ * @property {Int32Array} triangle vertex triples, in the state's own permuted
+ *   particle numbering, for drawing. Empty for a chain.
+ */
+/**
+ * @param {object} options
+ * @param {'sheet'|'chain'} options.shape
+ * @param {number} options.width particles across a sheet, or links along a chain
+ * @param {number} options.height particles down a sheet; ignored for a chain
+ * @param {number} options.spacing metres between adjacent particles
+ * @param {number} options.mass total mass of the whole cloth, kg
+ * @param {number} options.stretch_stiffness N/m, or `Infinity` for a hard row
+ * @param {number} options.bend_modulus
+ * @param {'top'|'corners'|'edges'|'none'} options.pinned
+ * @param {boolean} options.flat lay a sheet horizontally so it falls and swings,
+ *   rather than hanging in the vertical plane
+ * @returns {ClothPlaygroundScene}
+ */
+export function build_cloth_playground_scene({ shape, width, height, spacing, mass, stretch_stiffness, bend_modulus, pinned, flat }: {
+    shape: 'sheet' | 'chain';
+    width: number;
+    height: number;
+    spacing: number;
+    mass: number;
+    stretch_stiffness: number;
+    bend_modulus: number;
+    pinned: 'top' | 'corners' | 'edges' | 'none';
+    flat: boolean;
+}): ClothPlaygroundScene;
+export type ClothPlaygroundScene = {
+    state: ClothState;
+    /**
+     * vertex triples, in the state's own permuted
+     * particle numbering, for drawing. Empty for a chain.
+     */
+    triangle: Int32Array;
+};
+import { ClothState } from "../solver/ClothState.js";
+//# sourceMappingURL=cloth_playground_build.d.ts.map

package/src/engine/physics/cloth/playground/cloth_playground_build.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cloth_playground_build.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/cloth/playground/cloth_playground_build.js"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;GAgBG;AAEH;;;;;GAKG;AAEH;;;;;;;;;;;;;GAaG;AACH;IAZoC,KAAK,EAA9B,OAAO,GAAC,OAAO;IACC,KAAK,EAArB,MAAM;IACU,MAAM,EAAtB,MAAM;IACU,OAAO,EAAvB,MAAM;IACU,IAAI,EAApB,MAAM;IACU,iBAAiB,EAAjC,MAAM;IACU,YAAY,EAA5B,MAAM;IACkC,MAAM,EAA9C,KAAK,GAAC,SAAS,GAAC,OAAO,GAAC,MAAM;IACb,IAAI,EAArB,OAAO;IAEL,oBAAoB,CAgBhC;;WAjCa,UAAU;;;;;cACV,UAAU;;2BAxBG,yBAAyB"}