@woosh/meep-engine 3.22.0 → 3.23.0

package/src/engine/physics/cloth/PLAN.md

@@ -1,1581 +1,1967 @@
-# Cloth — Design
-
-> Design document. Written 2026-09-10; **M0 and M1 are implemented**, and every place they contradicted
-> it has been corrected in place with the measurement named beside it. §17 says what is done and what
-> is not; `MEASUREMENTS.md` is the evidence.
->
-> Scope: a cloth and soft-chain simulator that lives inside `engine/physics`, collides against the
-> `Collider` components the rest of the engine already authors, runs on a worker, and is safe to ship
-> with its defaults untouched.
-
----
-
-## 1. What this is
-
-One solver over particles, driven by components:
-
-- **`Cloth`** — the thing that simulates. Put it on an entity and that entity's transform subtree
-  becomes a simulated chain: a rope, a chain, a hanging sign, a mooring line.
-- **`ClothRig`** — add it alongside `Cloth` and the particles are the **joints of a skinned model**
-  rather than the entity subtree. This is what makes a cape, a skirt, a banner on a character.
-- **`ClothCollider`** — the marker that opts an existing `(Collider, Transform64)` entity into being
-  something cloth collides with. This is the `RigidBody`-analogue: it says *this collider participates*,
-  and carries only what cloth needs that `Collider` does not already say.
-
-That last component follows a pattern the engine already has twice. `AcousticBody` opts a collider
-into the acoustic simulation and carries an `AcousticMaterial`; `FluidObstacle` opts a collider into
-the fluid simulation and carries an inflation radius. `ClothCollider` is the third instance of the
-same idea, and it should read like a sibling of those two, not like a new invention.
-
-The design commitments, in priority order, because they conflict and the ordering is the design:
-
-1. **It does not explode.** Not at 5 fps, not at 500, not when a parameter is absurd, not when a
-   character teleports, not when a collider is spawned inside the cloth.
-2. **It does not get stuck.** The set of configurations the simulation can reach is bounded around
-   the animated pose, and error cannot accumulate across steps.
-3. **It works untouched.** Adding a `Cloth` component with default values to a correctly authored
-   garment produces shippable motion. Tuning is an optimisation, never a prerequisite.
-4. **It is cheap.** A CPU worker budget measured in low single-digit milliseconds per character.
-5. **It is accurate.** Last, deliberately. Cloth that is 10% too stiff and never misbehaves beats
-   cloth that is correct and occasionally detonates.
-
----
-
-## 2. Non-goals
-
-- **Garment authoring.** No pattern cutting, no sewing, no pressure/inflation. Import a mesh.
-- **Woven anisotropy.** No warp/weft/shear tensor. That needs UV-aligned quad topology and a
-  material model this design does not carry. Cloth here is isotropic with a bend modulus.
-- **Penetration-free guarantees.** IPC-class methods (`C-IPC`, `GIPC`) guarantee no intersection ever,
-  at a cost per step this budget cannot pay. We guarantee bounded, self-correcting penetration.
-- **Cloth pushing rigid bodies.** Coupling is one-way: colliders move cloth. Two-way coupling into
-  `PhysicsSystem`'s velocity solver is a later question and the constraint model leaves room for it
-  (§6), but it is not in scope.
-- **Tearing, plasticity, burning.**
-- **GPU simulation.** The engine has a mature WebGPU path and a particle VM that could host this, but
-  the requirement is a worker, and a worker is the cheaper, more portable, more debuggable answer.
-  Nothing in the data layout forecloses a GPU port; §12 keeps that door open.
-
----
-
-## 3. Author-facing API
-
-```js
-// An entity hierarchy — rope, chain, hanging sign, a prop built out of entities.
-// Cloth simulates the transform subtree of the entity it is on. That entity is the anchor.
-rope_top.add(Cloth.from(ClothDynamics.ROPE));
-
-// A skinned model's garment — cape, skirt, banner, hair.
-// Cloth simulates the JOINTS of the model instance this entity owns.
-character.add(Cloth.from(ClothDynamics.SILK));
-character.add(ClothRig.from(cape_proxy));   // cape_proxy: ClothProxy, built at import
-```
-
-There is no mode enum and no discriminator field. **`Cloth` alone simulates the entity subtree;
-`Cloth` + `ClothRig` simulates a skinned model's joints** — component presence doing the job an enum
-would otherwise do badly. The solver is identical either way; only seeding and write-back differ.
-
-Those are two cases rather than one because **the engine has two hierarchies, and that is a decision
-rather than an accident**. `shade_node_to_entity_composition` expands a loaded model into entities and
-gives a `ShadedGeometry` to every node that draws — except a skinned one, which "is not expanded, and
-that is a boundary rather than an omission": it contributes its transform and its name and no
-geometry, because its vertices deform against a skeleton the renderer owns and the GPU poses, and
-making those joints entities is a design this program does not do (D47). A rope prop is entities all
-the way down. A character's cape is not, and never will be. §11 is where that lands.
-
-### 3.1 `Cloth`
-
-```js
-export class Cloth {
-    dynamics = new ClothDynamics();  // how it behaves — §3.3
-    blend = 1;                       // 0 = fully animated pose, 1 = fully simulated
-    layer = 1;                       // ClothCollider layer/mask filtering, RigidBody semantics
-    mask = 0xFFFFFFFF;
-    flags = ClothFlags.None;
-}
-```
-
-**The anchor is the entity the component is on**, and nothing names anything. Without a `ClothRig`
-the particle set is the entity's own transform subtree, walked through
-`TransformAttachmentSystem#findChildrenOf`/`#countChildrenOf` — the parent-to-children index the
-engine already maintains. Put `Cloth` on the top link of a rope and you get the rope; put it on a
-node with several chains under it and you get all of them in **one coupled solve**, which is what
-makes self-collision between them work.
-
-Two rules keep the walk unambiguous:
-
-- **A nested `Cloth` claims its own subtree.** The walk stops when it meets another `Cloth`, so
-  independent hanging parts of one prop partition naturally.
-- **`ClothExclude`** is a tag component that prunes a subtree from the walk, for the rig that has a
-  non-simulated attachment point in the middle of a chain.
-
-With a `ClothRig`, the entity is instead the one that owns the skinned model instance, and the
-subtree walk does not run at all — the particle set comes from the proxy's joint list (§3.2).
-
-`blend` is the escape hatch for cinematics, LOD and "turn it off for this one shot". It is a lerp
-between the animated pose and the simulated pose applied at write-back, not a solver parameter, so it
-is free and always safe. **M1 note:** writing it wakes a sleeping cloth, because sleep skips the
-write-back as well as the step (§7 P5) and a `blend` written to a sleeping cloth would otherwise take
-effect at whatever later moment something else happened to wake it.
-
-### 3.2 `ClothRig`
-
-```js
-export class ClothRig {
-    proxy = null;   // ClothProxy — shared, immutable, built at import
-    skin = 0;       // which of the instance's skins the proxy's joint indices are into
-}
-```
-
-A `ClothProxy` **object**, not a path. This is the convention the engine already uses for a component
-that points at a built, shared, immutable asset: `Collider#shape` holds an `AbstractShape3D` and is
-documented as *not* serialised because shapes are shared assets the pipeline wires up;
-`ParticleEffect` holds a `ParticleLayout` and a `ParticleProgram` the same way. `ClothRig` serialises
-the proxy's identity and the skin ordinal, and the asset pipeline resolves the rest.
-
-**The proxy addresses joints by index, never by name.** A joint is a `Node3D` inside a
-`SceneBundleInstance`, not an entity, so an `EntityReference` to one is impossible by construction —
-and reintroducing strings at runtime to work around that would be the wrong answer. Instead the
-binding is resolved **once, at import**: the builder has `SceneBundleInstance#nodes` (the by-name map
-the engine keeps because sockets and effect anchors are authored as bone names) and turns names into
-integer indices into `Skin#joints`. The runtime component holds integers.
-
-### 3.3 `ClothDynamics`
-
-The parameters live in one value object, and the library is a set of instances of it.
-
-```js
-export class ClothDynamics {
-    stretch = 0.7;      // 0..1 normalised material coordinate
-    bend = 0.2;         // 0..1
-    damping = 0.15;     // 0..1
-    slack = 0.5;        // 0..1 — how far the cloth may leave the animated pose (§3.4)
-    thickness = 0.02;   // metres — particle radius, for collision offset and self-collision
-    inertia = 1;        // 0..1 — how much of the anchor's world motion the cloth feels
-    drag = 0.1;         // 0..1 — aerodynamic coupling to the air (§10)
-    substeps = 2;       // solver budget
-    iterations = 4;     // solver budget
-    flags = 0;          // ClothDynamicsFlags.SelfCollision, ...
-}
-```
-
-The library is `ClothDynamics.SILK`, `.COTTON`, `.DENIM`, `.LEATHER`, `.ROPE`, `.CHAIN`, `.HAIR` —
-frozen instances in `cloth_dynamics_library.js`. Assign one directly and it is shared, immutable and
-free; call `.clone()` and you own a copy to edit. There is no field that silently rewrites other
-fields, and no second "advanced" block: this *is* the parameter set, and the library is a set of
-points in it that are known to be good rather than a mechanism.
-
-The stiffnesses are normalised coordinates, not moduli in N/m — log-mapped internally so that `0.7`
-means something an author can predict and `0.9` is not four orders of magnitude away from it. They are
-independent, because the library carries the good combinations and that is protection enough; nothing
-needs to be collapsed onto a single magic axis to keep an author out of trouble.
-
-**M1 wrote that mapping (`cloth_dynamics_map.js`) and neither stiffness maps to newtons per metre.**
-`stretch` maps to a *strain allowance*, because §6's measurement makes the fabric row hard and leaves
-nothing for a stiffness to be. `bend` maps to a **ratio** of the row's own `m_eff/dt²` — at the fixed
-step rather than the substep — for two reasons that are both wanted: the fabric's look becomes
-invariant to how heavy the author made the particles, which is what a normalised knob should mean; and
-since `k/(m/h²) = ratio/substeps²`, a bend row expressed that way is inside M0's dissipative band at
-*any* substep count by construction, rather than by an author staying out of trouble. A stiffness in
-N/m has neither property. The cost, stated: **bending saturates** at the top of that band, so a fabric
-stiffer than `bend = 1` cannot be expressed as a soft row that also comes to rest.
-
-`substeps` and `iterations` are budget rather than material, and they are here because a chain wants
-more of both than a bedsheet does, so they are part of what "chain" means. Raising `iterations`
-converges further toward the same answer (§5.1); raising `substeps` also reduces implicit Euler's
-numerical damping, so it does change the drape slightly. Both are ordinary fields with ordinary
-documentation, not hidden couplings.
-
-`ClothDynamics` carries `equals` and `hash` like every other value type in the engine, so a component
-holding one compares and hashes cheaply.
-
-### 3.4 Slack, and why there is no radius in metres
-
-`slack` is dimensionless. Each particle's leash radius is derived, not authored:
-
-```
-r_i = 2 · slack · d_geo,i
-```
-
-**M1 corrected the factor of two, and it is a derivation rather than a fudge.** This paragraph
-originally read `r_i = slack · d_geo,i`, which makes `slack = 1` a real and fairly tight constraint
-instead of the absence of one: a rope hanging straight down cannot swing through ninety degrees,
-because its tip has to travel `√2·d_geo` to get there and its leash is `d_geo`. The radius at which
-the row is *provably* inert is `2·d_geo` — the tether already holds every particle within `d_geo` of
-the anchor, the animated position it is leashed to is also within `d_geo` of the anchor since a chord
-is never longer than the arc it subtends, so by the triangle inequality the two are never further
-apart than that. With the factor of two in, `slack = 1` means exactly "no leash": the row cannot
-bind, so it is not built at all, and there is no sentinel and no discontinuity to code around.
-`MEASUREMENTS.md` §10.
-
-where `d_geo,i` is the particle's baked geodesic distance to the fixed set. At `slack = 0` every
-particle is welded to its animated position; at `slack = 1` a particle may be anywhere within its own
-reach of that position. Three things fall out of that and none of them need a knob:
-
-- **The profile is automatic.** A hem gets a long leash and a waistband gets a short one, because
-  that is what their geodesic depth says, not because someone painted it.
-- **The fixed set falls out too.** A pinned particle has `d_geo = 0`, so `r_i = 0`, so the leash *is*
-  the pin. There is no separate attach constraint — one row covers both (§6).
-- **There is no magic default.** The old formulation had a radius in metres with `0` meaning "derive
-  it from the mesh extent", which is the kind of overloaded sentinel that gets copied into a save file
-  and then means the wrong thing.
-
-Slack is not a stretch allowance and does not govern inextensibility — the tether row does that, and
-the two are different questions (§6). Slack asks how loosely the cloth is leashed to the animation;
-the tether asks how far the fabric may extend from its anchor. A cape wants both: a moderate leash so
-it follows the character, and a hard tether so it never becomes rubber.
-
-### 3.5 `ClothCollider`
-
-```js
-export class ClothCollider {
-    inflation = 0;       // extra thickness in metres, on top of ClothDynamics#thickness
-    friction_scale = 1;  // multiplies the entity's Collider#friction
-    flags = 0;           // ClothColliderFlags
-}
-```
-
-Three fields, and two of them are usually left alone. Everything else is read from components the
-entity already has: geometry and friction from `Collider`, pose from `Transform64`, layer filtering
-from the `Cloth` side.
-
-**A `ClothCollider` does not require a `RigidBody`.** This is a deliberate divergence from
-`FluidObstacle`, which does require one because it needs a wall velocity. Cloth's colliders are
-overwhelmingly character bones — ordinary entities in a `TransformAttachment` hierarchy — and forcing
-each of them to become a physics body to be seen by cloth would be a tax on the common case. Collider
-velocity is derived from the pose delta between fixed steps, which the system caches anyway for swept
-collision (§8.2). World props that *do* carry a `RigidBody` add a `ClothCollider` the same way and land
-in the same index; the two cases are not distinguished.
-
----
-
-## 4. Components and systems
-
-```
-engine/physics/cloth/
-  ecs/
-    Cloth.js                        component: the simulated thing; anchor is its own entity
-    ClothFlags.js                   TeleportKeep, NeverSleep
-    ClothExclude.js                 tag: prune a subtree from the walk
-    ClothRig.js                     component: particles are a skinned model instance's joints
-    ClothDynamics.js                value object: how it behaves
-    ClothDynamicsFlags.js           SelfCollision, StrainLimit
-    cloth_dynamics_library.js       SILK, COTTON, DENIM, LEATHER, ROPE, CHAIN, HAIR — frozen instances
-    cloth_dynamics_map.js           normalised coordinates → row parameters; every constant measured
-    ClothCollider.js                component: the RigidBody-analogue for collision
-    ClothColliderFlags.js
-    ClothSystem.js                  main-thread system: gather, step, write back
-    ClothInstance.js                one live cloth: the binding between a subtree and a ClothState
-    cloth_seed_subtree.js           the walk, the rows, and the ClothState it produces
-    cloth_write_back.js             solved positions → Transform64, with the orientation swing
-    WorkerClothSystem.js            drop-in worker variant (WorkerSystem subclass)
-    ClothWorkerCore.js
-    cloth.worker.js
-    makeClothWorker.js
-    cloth_worker_protocol.js
-    ClothSerializationAdapter.js
-    ClothRigSerializationAdapter.js
-    ClothColliderSerializationAdapter.js
-  collider/
-    ClothColliderIndex.js           the index of live cloth colliders + their AABBs
-    ClothColliderRecord.js          one packed collider: kind, params, world/inverse pose, prev pose
-    cloth_collider_pack.js          AbstractShape3D → packed record
-    sdf/                            closed-form SDF + gradient per packed kind
-  solver/
-    ClothState.js                   SoA particle + topology + constraint storage over one buffer
-    cloth_step.js                   the fixed step: predict, warm start, iterate, dual update, integrate
-    cloth_solve_vertex.js           the per-vertex 3x3 block update
-    constraint/                     one module per row type (§6)
-    cloth_color_particles.js        graph colouring of the particle graph
-    constraint/cloth_leash_row.js   §6's slack row and its tether row, which are one row model
-  build/
-    ClothProxy.js                   the built artefact + its binary codec
-    cloth_proxy_build.js            source mesh → proxy (weld, simplify, extract, validate)
-    cloth_proxy_bind.js             render mesh → proxy binding weights
-    cloth_geodesic_build.js         distances to the fixed set — drives both tether and slack
-  ClothDiagnostics.js               dev-build tripwires
-```
-
-Two systems:
-
-- **`ClothColliderSystem`** observes `(Collider, Transform64, ClothCollider)` and maintains a
-  `ClothColliderIndex` — a flat array of packed records plus world AABBs. This is the same shape as
-  `AcousticOccluderIndex`/`OccluderBody` in the sound simulation, and for the same reason: the
-  consumers need a compact, pose-cached, broadphase-able view of a set of colliders that is not the
-  physics BVH. It cannot be the physics BVH, because `ColliderObserverSystem` deliberately skips
-  colliders with no owning body, and bone colliders have no body.
-
-- **`ClothSystem`** owns the simulation. Per fixed step: refresh the animated targets, gather the
-  overlapping colliders from the index, step, write back.
-
-Cloth runs at the fixed rate and is interpolated for display, exactly as `PhysicsSystem` does — the
-same producer/`__interp_restore` contract, so a cloth-driven `Transform64` is authoritative during the
-fixed pass and interpolated outside it. Reusing the existing contract rather than inventing a second
-one is what keeps a cloth-driven bone from fighting an animation-driven one.
-
-### 4.1 Ordering, and why the answer is not to be ordered
-
-Cloth wants to read the skeleton *after* animation has posed it for this step and *before* anything
-renders. The engine has exactly two ways to order systems: **registration order**, and what each
-system declares in `components_used`, from which writers are sorted before readers. There is
-deliberately no `runs_before`/`runs_after`, because naming other systems is the coupling that design
-exists to avoid.
-
-**Cloth both reads and writes `Transform64`**, which puts it on both sides of that component's own
-rule, and M1 established that neither mechanism can express the relation — for a structural reason
-rather than an arithmetic one. `updateExecutionOrder` scores a system as a **sum** over the components
-it references and sorts descending, so a score can only be *raised* by touching more components or
-touching them at a higher access level. The only way to sort **later** is therefore to touch strictly
-less than the system you have to follow, and a consumer of a posed hierarchy touches strictly more.
-Registration order cannot rescue it either: ties break by registration, and this is not a tie —
-`ClothSystem` outscores `TransformAttachmentSystem` and any plausible poser outright, registered first
-or last.
-
-**So the answer is not a third mechanism. The answer is that cloth must not care.** An earlier draft
-of M1 added an execution-phase number to `System`, which put the words "pose" and "animation" into a
-layer of the engine that has no such vocabulary, and bought an ordering the design should not have
-needed. What M1 ships instead is a write-back that is **idempotent under recomposition**: cloth writes
-each node's local `TransformAttachment#transform` alongside its world `Transform64`, so a hierarchy
-recomposition — which is what happens whenever anything announces on the anchor — reproduces the
-simulated pose instead of replacing it with the authored one. Measured at **1.7e-15 m** across a
-16-link rope (`MEASUREMENTS.md` §15). With that, where cloth runs is a **quality** question.
-
-And a small one. Running before the poser means reading last step's anchor pose, so the cloth's
-*shape* is one fixed step stale; its *position* is not, because the attachment cascade carries the
-whole subtree rigidly with the anchor from cloth's own local transforms. Measured on a 1.6 m rope: a
-few centimetres under ordinary motion, up to a fifth of its own length at the sharpest velocity
-reversal of a ±9 m/s square wave, and **not accumulating** — the same figure after fifteen seconds as
-after two, because the leash and the tether bound the reachable set. `ClothSystem.spec.js` asserts the
-idempotency, records the order the scheduler actually produces, and bounds that divergence.
-
-What the declaration *does* buy is the half of the ordering that is real: cloth writes
-`TransformAttachment#transform` and `TransformAttachmentSystem` reads it, so writer-before-reader puts
-cloth first and the attachment system publishes its result. That falls out of `components_used` with
-nothing else asked for.
-
-**`InverseKinematicsSystem` is the same shape and reaches the same conclusion.** It reads world
-`Transform64`s "the hierarchy has already composed" and writes local ones back — which is exactly the
-arrangement above, and exactly why it is not fragile in the way its scoring suggests.
-
----
-
-## 5. The solver
-
-**Augmented Vertex Block Descent** (Giles, Diaz & Yuksel, SIGGRAPH 2025) — VBD's per-vertex
-Gauss-Seidel block coordinate descent on the implicit-Euler variational energy, with an augmented
-Lagrangian in place of pure penalties.
-
-### 5.1 Why this, and not XPBD
-
-XPBD with small substeps is the incumbent: MagicaCloth2, Chaos Cloth, Blender, most of the field.
-It works. Three properties push past it, and each maps onto a stated requirement:
-
-- **Unconditional stability at any iteration count.** Every per-vertex update is a descent step on an
-  energy that is bounded below, so the update can be truncated at one iteration and the simulation is
-  still stable — just softer. That turns requirement 1 into a property of the update rule rather than
-  a property of tuning. XPBD is stable in practice, but its stability is a function of substep size
-  and stiffness; ours is not.
-- **Parameters that keep their meaning.** AVBD targets the implicit-Euler solution, so a stiffness is
-  a material modulus and adding iterations moves the result *toward* the same answer rather than
-  changing which answer it is. Under XPBD, apparent stiffness and apparent damping both move when the
-  iteration budget moves, which is why cloth packages ship dozens of interacting sliders and
-  per-parameter animation curves to compensate. §3.3's small, independent parameter set is only
-  honest on a solver whose knobs are orthogonal to its budget.
-
-  This is iteration-count insensitivity, not substep insensitivity. Implicit Euler is numerically
-  damped by an amount that depends on `h`, so more substeps still means less artificial damping and
-  a livelier drape — which is why `substeps` is a documented field rather than a hidden constant.
-- **Hard constraints without stiff penalties.** The augmented Lagrangian reaches effectively infinite
-  stiffness through an accumulating multiplier rather than a large `k`, so pins, tethers and slack
-  bounds are *hard* — enforced to convergence — while cloth stays soft, in the same sweep, without
-  the conditioning disaster a 10⁸ penalty would cause. VBD alone cannot do this; it is exactly the
-  limitation AVBD was written to fix.
-
-Two smaller wins. Colouring the *particle* graph needs far fewer colours than colouring the
-*constraint* graph — the VBD paper reports 8 colours for a 3,891-vertex tetrahedral mesh against 76
-for its 14,802 tetrahedra — which matters for a future GPU port and for cache behaviour now. And the
-per-vertex form is a natural fit for SoA typed arrays, which is what a worker needs anyway.
-
-The cost is honest: more arithmetic per vertex than an XPBD projection, and a shorter track record
-for cloth specifically. §18 carries both as risks with a measurement plan.
-
-### 5.2 The step
-
-Per substep, with `h` the substep length, `m_i` particle mass, `y_i` the inertial target:
-
-```
-predict      y_i  = x_i + h·v_i + h²·a_ext,i
-             x_i ← x_i + h·v_i + h²·ã_i          (adaptive initialisation)
-
-warm start   for each HARD constraint c:               (soft rows: k_c = stiffness, λ_c = 0)
-               λ_c ← λ_c · α · γ
-               k_c ← clamp(k_c · γ, k_min·s_c, k_max·s_c)     s_c = the row's own m_eff/h²
-
-iterate      repeat `iterations` times:
-               for each colour:                   (parallel within a colour)
-                 for each particle i in colour:
-                   f = -(m_i/h²)(x_i - y_i)
-                   H =  (m_i/h²)·I
-                   for each constraint c on i:
-                     C  = C_c(x);  g = ∂C_c/∂x_i
-                     fu = k_c·C + λ_c
-                     fc = clamp(fu, fmin_c, fmax_c)
-                     f -= fc·g
-                     if fc > 0:                   (row in tension)
-                       H += (fc/L)·(I − g gᵀ)     (geometric stiffness, PSD part)
-                     if fc == fu:                 (row active — not at a clamp)
-                       H += k_c·(g gᵀ)
-                   x_i += H⁻¹·f                   (3×3 LDLᵀ, capped at the shortest incident row)
-
-               dual update, for each HARD constraint c:
-                 λ_c ← clamp(k_c·C_c + λ_c, fmin_c, fmax_c)
-                 k_c ← min(k_c + β·|C_c|, k_max·s_c)
-
-integrate    v_i = (x_i - x_i^prev)/h
-```
-
-The Hessian contribution is gated on the row being *active*. A clamped row's force is constant with
-respect to position, so its true second derivative is zero; adding `k·ggᵀ` anyway would make an
-inactive unilateral constraint resist motion it should not touch. It contributes its (constant) force
-to `f` and nothing to `H`.
-
-`α ∈ [0,1]` regularises the multiplier carried between steps, `γ ∈ [0,1)` decays warm-started duals so
-a resting configuration bleeds off accumulated force instead of ringing, and `β` is the penalty ramp.
-These are solver internals, global, and deliberately **not** on `ClothDynamics` — they are not a
-property of a fabric. The reference 2D implementation's defaults are a rigid-body tuning and will not
-transfer; §17 M0 makes picking cloth values a measured step with its own spec, not a copied constant.
-
-**M0 measured them, and four things about this pseudocode were wrong.** The sweep and its full grids
-are in `MEASUREMENTS.md`; the corrections are folded into the listing above and are, in short:
-
-1. **The five constants only govern *hard* rows.** A row whose material stiffness is finite is
-   representable as a plain penalty, and a plain penalty at the material stiffness *is* the material
-   law — there is nothing for a multiplier to add. Carrying one anyway drives `C` to zero and makes
-   every fabric inextensible regardless of what it was authored as: a 1 kN/m spring measured 100×
-   stiffer than Hooke. So a soft row is a pure penalty at its material stiffness and reads dead flat
-   against all five constants, which is what makes them honest as global internals. A row is **hard**
-   exactly when its stiffness is `Infinity` — §6's table already says `hard` in that column, and this
-   makes it literal rather than a threshold.
-2. **`k_min` and `k_max` are ratios of `m/h²`, not stiffnesses in N/m.** Held at a fixed multiple of
-   the row's own inertial scale, a 20-link hard chain produced the same residual column across five
-   decades of particle mass; held at a fixed stiffness it produced a different answer for every mass.
-   This paragraph's own reasoning already names `k_max/(m/h²)` as the quantity that matters — it just
-   stopped one step short of making the ratio the parameter.
-3. **`α` and `γ` act only through their product, and `α·γ ≥ 0.5` diverges.** At `α·γ ≤ 0.3` a 20-link
-   hard chain settles to rest with kinetic energy at 1e-9 J; at 0.5 it jitters; at 0.6 it detonates.
-   Residual improves monotonically towards that cliff, so the value is a margin decision:
-   **α·γ = 0.25**, a factor of two clear.
-4. **`β` could not be chosen from M0 data.** Above about 1e4 every M0 scenario gives an identical
-   answer, and with `k_min = k_max` — which measured as good as any ramp for M0's persistent rows —
-   it has no effect at all. The ramp exists for **transient** rows, a contact that should arrive soft
-   rather than shock the mesh on its first frame, and M0 has none. M2 has to measure it.
-
-Chosen: **α = 0.25, γ = 1, β = 1e5 (unexercised), k_min = k_max = 8·(m/h²)**. γ sits at 1 because its
-second job — decaying the penalty — has nothing to do while the band is a single point, so the whole
-decay lives in α, whose only job is the multiplier. When M2's contacts make the band real, γ becomes
-live and has to be re-measured.
-
-**Adaptive initialisation** is VBD's: seed the iteration at `x + h·v + h²·ã` where `ã` interpolates
-between zero and full external acceleration according to whether the previous step looked like free
-fall or like resting contact. Without it, a low iteration count over-stretches under gravity on the
-first iteration and the tethers spend the rest of the budget pulling it back.
-
-**Chebyshev acceleration** (`ω₁ = 1`, `ω₂ = 2/(2−ρ²)`, `ωₙ = 4/(4−ρ²ωₙ₋₁)`) is available and
-**disabled for any particle in contact this step**, per the VBD paper — accelerating a vertex whose
-constraint set just changed is where the method's stability argument stops applying. It is off by
-default and turned on per-dynamics only where it measurably helps.
-
-### 5.3 Why the update never explodes
-
-`H = (m/h²)·I + Σ_tension (fc/L)·(I − g gᵀ) + Σ_active k_c·(g gᵀ)`. The mass term is positive
-definite; every `k_c·g gᵀ` is a positive semidefinite rank-one term; every `(fc/L)·(I − g gᵀ)` with
-`fc > 0` is positive semidefinite too. So `H` is symmetric positive definite by construction — for any
-topology, any parameter values, any degenerate configuration, and regardless of how many rows are
-clamped out. `H⁻¹f` is always a descent direction.
-
-**Three things M0 measured changed this paragraph.** They are corrections to the mechanism, not to the
-goal; the full evidence is in `MEASUREMENTS.md`.
-
-**The geometric-stiffness term is kept where it is positive semidefinite, not dropped wholesale.**
-For a distance row `∂²C/∂x² = (I − g gᵀ)/L`, which is PSD exactly when the row is in tension, so
-`max(fc, 0)·∂²C/∂x²` can be added without touching the SPD argument — every term in `H` is still PSD
-on top of a PD mass term, and there is still no threshold. Dropping it *all* was measured to make the
-update overshoot sideways whenever `fc/L` passes `m/h²`, raising the vertex energy by 20% at a ratio
-of 4 and by a factor of 40 at a ratio of 7e4. This is not "adding the indefinite term back": the
-negative-semidefinite half, where the row is in compression, is still dropped, and dropping it there
-is conservative rather than dangerous. Note the term is added whether or not the row is at a clamp —
-a saturated row applies a constant-magnitude force that still swings as the row rotates.
-
-**The 3×3 solve is an LDLᵀ factorisation, not a cofactor inverse.** They agree in exact arithmetic
-and do not agree in `Float64`. A vertex carrying one very stiff row against a small mass term
-assembles an `H` with a condition number in the billions, and the cofactor determinant — a sum of
-triple products that has to cancel by that ratio squared — comes out **negative** on a matrix whose
-eigenvalues are all positive (measured: eigenvalues 0.12, 0.12, 5.4e8; determinant −4.8e8 against a
-true 7.75e6). The factorisation never forms those products; its pivots stayed positive throughout the
-fuzz, and their product is the determinant to full precision. The dev-build assertion checks the
-pivots, which *is* the positive-definiteness claim rather than a proxy for it.
-
-**Positive definiteness gives a descent direction, not a monotone step.** `Δ = H⁻¹f` satisfies
-`f·Δ > 0`, so the energy falls for a small enough step — and the update takes a full step of 1. Where
-the quadratic model stops resembling the energy, a full step overshoots and climbs: measured falling
-monotonically out to `t ≈ 0.001` of one step and then rising to 40× the starting energy at `t = 1`.
-The step is therefore capped at the **shortest row incident on the particle** — the distance over
-which "the direction to a neighbour" means anything, which is the mesh's own geometry rather than a
-tuned constant, and which never binds for cloth in ordinary motion. With all three corrections in,
-full-step energy increases on a realistic cape are 0.004% of updates and never exceed a fifth of the
-local energy scale; across deliberately absurd cloth they are 1.5% and never exceed 1.0. §7 P1 states
-the gate that follows from this.
-
-A dev-build tripwire mirrors `find_non_finite_physics_state.js`: a post-step sweep for non-finite
-particle state that names the first offender. It sits behind `assert.*` so it compiles out of consumer
-bundles — the engine ships raw source, and a check moved out of `assert.*` stops being strippable.
-
-### 5.4 Colouring
-
-The particle graph is coloured so no constraint touches two particles of the same colour, using the
-existing `core/graph/coloring/colorizeGraphGreedy.js` and checked by the existing
-`validateGraphColoring.js`. Bending stencils span four particles, so the graph is the mesh graph plus
-the bend diagonals — around 8–10 colours for typical garment topology. Colouring runs once, on a
-`Graph` object, and is baked into the `ClothProxy` as colour ranges over a permuted particle order;
-for a chain it runs at link time on a graph of a few dozen nodes. Nothing colours per step and the
-runtime never sees a graph object.
-
-Contacts and self-collision rows appear and vanish per step and cannot be pre-coloured. They are
-accumulated into a per-particle scratch buffer and applied Jacobi-style within the sweep — the same
-mixed Gauss-Seidel/Jacobi treatment VBD uses for dynamic collisions, and the reason a step is
-deterministic regardless of how many contacts a particle picked up.
-
----
-
-## 6. Everything is one constraint row
-
-Every feature in this system is a row in one table. A row is `(C(x), f_min, f_max, stiffness)`, and
-the solver in §5.2 knows nothing else about it.
-
-| Row | `C(x)` | `f_min` | `f_max` | Stiffness | Gives you |
-|---|---|---|---|---|---|
-| Stretch | `‖x_i − x_j‖ − L₀` | −∞ | +∞ | `k_stretch` | fabric that resists stretching |
-| Bend | quadratic stencil `Σ w_k·x_k` | −∞ | +∞ | `k_bend` | fabric that resists folding |
-| Slack | `‖x_i − s_i‖ − 2·slack·d_geo,i` | 0 | +∞ | hard | follows the animation; pins at `d_geo = 0` |
-| Tether (LRA) | `‖x_i − p_anchor‖ − d_geo,i` | 0 | +∞ | hard | no rubber-band stretch |
-| Backstop | `r_b − (x_i − b_i)·n_i` | 0 | +∞ | hard | never inside the body |
-| Collision | `(r_i + infl) − sdf_c(x_i)` | 0 | +∞ | `k_contact` | colliders push cloth |
-| Friction | tangential slip magnitude | `−μ·f_n` | `+μ·f_n` | `k_friction` | cloth grips |
-| Self-collision | `‖x_i − x_j‖ − (r_i + r_j)` | −∞ | 0 | `k_self` | cloth doesn't pass through itself |
-| Strain limit | `‖x_i − x_j‖ − L_max` | 0 | +∞ | hard | hard cap on elongation |
-
-Unilateral rows fall out of the clamp: **`[0, +∞)` admits only forces that reduce `C`, `(−∞, 0]` only
-forces that increase it**, and `(−∞, +∞)` is bilateral.
-
-**M1 corrected three of those clamps and the sentence above them.** An earlier draft glossed the rule
-as "`[0, +∞)` is push-only, `(−∞, 0]` is pull-only", which is true only relative to a particular sign
-of `C` — the collision row writes `C` as `r − sdf` and the distance rows write it as `‖·‖ − r`, so the
-same clamp means opposite things on them. Following the gloss rather than the rule gave Slack, Tether
-and Strain limit `(−∞, 0]`, which under the solver's own `f -= fc·g` is the force that pushes a
-distance row *apart*. Such a row does not bind weakly; it never binds at all, and it would drive a
-particle away from the leash centre it is supposed to hold it near. `cloth_leash_row.spec.js`
-demonstrates it directly and `MEASUREMENTS.md` §10 carries the derivation. **A row is hard exactly when its stiffness is `Infinity`** — the word in the table above,
-made literal. A hard row's penalty lives in `[k_min, k_max]·(m/h²)` and its multiplier carries the
-load; a soft row is a pure penalty at its material stiffness and carries no multiplier at all. M0
-measured why it has to be one or the other rather than a sliding scale (§5.2), and measured what the
-multiplier actually buys: not a smaller residual — at a fixed budget a stiff penalty is comparable —
-but **settling**. A hard 20-link chain comes to rest with 1e-14 J of kinetic energy where the same
-chain on a penalty of any stiffness sits in a limit cycle at 1e-4 J. That is §7 P5, and it is the
-augmented Lagrangian's real return.
-
-`C` for a bending row is a **vector** — the discrete mean-curvature vector — so that row carries three
-multipliers against one penalty, and its clamps are absent because a bending moment has no sign to be
-one-sided about. Every other row in the table is scalar.
-
-**There is no separate attach row.** A pinned particle is a slack row with `d_geo = 0`: the constraint
-becomes `‖x_i − s_i‖ ≤ 0` under a pull-only clamp, which welds it. One row, one code path, and the
-distinction between "pinned" and "loosely following" is a number rather than a branch. (The gradient of
-`‖x − s‖` is undefined at `x = s`; the row is skipped below an epsilon, which is the standard guard and
-is also exactly when it has nothing to do.)
-
-**Slack and tether are different questions, and a cape needs both.** Slack bounds distance to the
-particle's *animated position*; the tether bounds distance to the *anchor*. Slack alone implies a
-tether bound of `(1 + slack)·d_geo` — enough to stop a catastrophe, not enough to stop visible rubber —
-and for a garment with no meaningful animated pose to follow (a flag, a curtain, where `slack` is near
-1 by necessity) the tether is doing all the inextensibility work on its own.
-
-This mirrors the doctrine already written into `physics/constraint/solve_constraints.js`, whose
-6-DOF joints are "one row model, parameterised by mode", with LOCKED and LIMITED differing only in
-bias and clamp. Same idea, position level instead of velocity level. A reader who knows one knows the
-other, and a new cloth feature is a new row rather than a new pass.
-
-Two rows deserve a note.
-
-**Bend is the quadratic model**, not a dihedral angle. Its Hessian is constant for a fixed rest shape,
-so the stencil weights are precomputed at build time, `C` is linear in `x`, and `g` is a constant read
-from the proxy — bending costs almost nothing per iteration, and M0 measured it at an eighth of a
-stretch row per visit despite touching twice as many particles. The weights annihilate the rest shape
-and every affine image of it, which is every in-plane deformation to first order; they do *not*
-annihilate an arbitrary planar configuration, and that is the precise content of the near-isometric
-assumption below. More importantly, it has **no singularity
-at 0° or 180°**. Dihedral bending needs a normal, an angle and a sign, all of which degenerate when two
-triangles become coplanar or invert, and that degeneracy is a classic source of exactly the twitching
-this design exists to eliminate. The cost is that the quadratic model assumes a near-flat rest shape
-and near-isometric deformation; a garment with a strongly curved rest shape it wants to hold will
-under-resist. §18 carries that.
-
-**Stretch is per-edge.** Edge springs on a triangle mesh do not resist shear on their own; the bend
-rows and the slack bound between them keep the mesh from collapsing in practice, and a triangle-area
-row is available for the cases where they do not. Full in-plane anisotropy is a non-goal (§2).
-
-**A chain bends through a skip row, not through the quadratic stencil.** M1 found there is nothing to
-build a hinge on: the stencil is a discrete mean curvature over a *surface*, four particles across the
-diamond either side of a shared edge, and a rope has no diamond — `bt_edge_read_diamond` declines a
-wire edge for exactly that reason and is right to. What a chain gets instead is an ordinary stretch
-row between a node and its **grandparent**, at whatever distance the authored pose puts them. That is
-this section's own doctrine applied once more, it costs no new row kind, and it keeps both properties
-the quadratic model was chosen for: no normal, no angle and no sign, so nothing degenerates at 0° or
-180°, and a fold is high energy rather than a singular configuration. It also does something the
-quadratic stencil explicitly cannot (§18) — because its rest length is read from the authored pose
-rather than assumed flat, **it holds a curved rest shape**. `MEASUREMENTS.md` §9.
-
-**And a stretch row has to be hard, which this table's `k_stretch` does not say.** M0 measured that a
-*penalty* stiffer than about `8·(m/h²)` makes the step add energy rather than dissipate it — the cloth
-sustains a limit cycle forever, and raising the iteration count shrinks it without removing it. For a
-half-gram particle at 60 Hz × 2 substeps that boundary sits near 60 N/m, which is a rubber band rather
-than a fabric, so every stiffness an author would reach for is on the wrong side of it. The augmented
-Lagrangian is therefore not a refinement over a stiff penalty for this row: it is the only formulation
-of it that comes to rest, because its penalty is capped at the top of the dissipative band and the
-multiplier carries the rest. M1's normalised `ClothDynamics#stretch` should map to `Infinity` with a
-strain-limit row governing extension, not to a large finite `k`. `MEASUREMENTS.md` §6.
-
-**M1 built that and measured what the strain-limit row is actually worth, and the answer is "a
-third".** It removes 34–38% of the peak over-stretch, consistently, at every budget — and it **never
-reaches its own allowance**: at `stretch = 1` it asks for 0.1% of strain and delivers 5.9% at one
-iteration per substep, 2.2% at 2×2 and 0.9% at 2×4. The reason is structural. A strain-limit row is a
-*second hard row on the same edge with the same gradient*, so it competes for the same trust region
-and the same penalty band as the fabric row it is backing up; it can add force in a direction force is
-already being added in, and nothing more. Below about `stretch = 0.35` its allowance is looser than
-what the fabric row does unaided and it is simply inert.
-
-So **`stretch` is the weakest field in §3.3's parameter set**, and the honest statement is that at low
-budgets the bound belongs to the budget rather than to the fabric. The row is worth its 13–15% of a
-garment frame where the residual is visible and is not worth it where the residual is already around
-one per cent, which is why it is a flag — `ClothDynamicsFlags.StrainLimit` — rather than always on,
-and why the library entries at 2×4 clear it. `MEASUREMENTS.md` §11.
-
----
-
-## 7. Pathology budget
-
-The requirement was cloth that does not fold up, get stuck, or spaz out. Each failure mode below gets
-a named mechanism and a spec that fails without it. This table is the acceptance criterion for the
-whole system, and every row's spec is a standing gate, not a one-off.
-
-**P1 — Blow-up, NaN, unbounded velocity.**
-*Mechanism:* SPD Hessian by construction (§5.3), so every update is a descent direction; the step
-capped at the shortest incident row so a full Newton step cannot leave the region its model describes;
-a per-particle velocity clamp; the `assert.*` non-finite tripwire.
-
-**M1 landed the clamp and it is not derived from `thickness`.** This row asked for one "derived from
-`thickness` and `h`", and `thickness` turns out to be the wrong length scale: it is a *contact*
-radius, so a clamp built from it is a **tunnelling** bound, and a tunnelling bound sits below ordinary
-cloth speeds rather than above them. Silk is 4 mm thick, so "a particle may not cross its own radius
-in a step" is 0.24 m/s at 60 Hz — against the 29 m/s the same silk reaches behind a sprinting anchor.
-Any multiple large enough to stop the clamp being a *behaviour* for silk is large enough to be
-meaningless for leather, whose thickness is five times silk's and whose speeds are not.
-
-The scale that works is the solver's own **correction authority**,
-`shortest_row · substeps · iterations / dt` — the trust region caps a vertex update at the shortest
-row incident on the particle, so that product is the whole of what one fixed step can undo. M1
-measured a cloth losing its bounds past it (§7 P2 below), and the clamp is four times it: a bound on
-the solver being asked to do more than it can, scaling with the mesh and the budget rather than with a
-radius nothing reads until M2. The smallest headroom over it in the library is 5.7×. M2 still needs
-the tunnelling bound — it is a different number for a different job and it arrives with the contacts.
-`MEASUREMENTS.md` §13.
-*Spec:* fuzz over random topologies and random `ClothDynamics` values including absurd ones, 10,000
-steps, assert every particle finite. **M0 corrected the second half of this.** "The per-vertex energy
-never increases across an update" does not follow from an SPD Hessian and is not true — SPD buys a
-descent direction, and the update takes a full step (§5.3). What is asserted instead, and holds:
-every LDLᵀ pivot positive on every update (which *is* positive definiteness, checked where it is
-used); nothing non-finite across 10,000 steps of absurd cloth; and full-step energy increases bounded
-and rare — 0.004% of updates on a realistic cape, never above a fifth of the local energy scale, and
-1.5% / 1.0 across the absurd fuzz. Those measured figures are the thresholds the standing gate holds
-the solver to, so a change that makes it worse fails.
-
-**P2 — Over-stretch, the rubber cape.**
-*Mechanism:* long-range attachments (Kim et al. 2012). Each particle carries the geodesic distance to
-its nearest fixed particle, baked once, enforced as a hard unilateral row. Because it is hard rather
-than a penalty, one iteration enforces it almost exactly — this is the row that makes low iteration
-counts viable.
-*Spec:* a 30-link × 3-strand rig at one iteration per substep, dropped through ninety degrees; assert
-`max‖x − p_anchor‖ ≤ d_geo·(1+ε)` for every particle across 600 steps, and assert the same rig without
-the rows does not hold.
-*Measured, M1:* **1.0155 with the tether against 1.4650 without**, at 1×1. Four times the budget takes
-the untethered rig to 1.0199, which is still worse than one iteration *with* tethers — so the tether
-is not a cheaper way to buy convergence, it answers a question the per-edge rows cannot.
-
-*Limit, stated, and M1 found it:* **the bound is conditional on the solver's correction authority.**
-The trust region caps a vertex update at the shortest row incident on the particle (§5.3), so one
-fixed step can move a particle at most `shortest_row · substeps · iterations`, and a displacement
-larger than that is not one the tether has been given a chance to answer for. Measured: a 30-link
-chain kicked at 16 m/s against 3.0 m/s of authority reaches **6.9× its own reach**, and the same kick
-against 24 m/s of authority reaches 1.06×. Both recover — the excursion is transient, which is P4(c)
-holding — but "no particle is ever further from the anchor than `d_geo`" is true only while the
-velocity clamp of P1 keeps a particle inside what the solve can undo, and that is the reason the clamp
-is built out of the same quantity. `MEASUREMENTS.md` §10.
-
-**P3 — Tunnelling through the character.**
-*Mechanism:* three layers. (a) Collision rows evaluate against the collider pose *interpolated to the
-substep*, from the previous and current poses the index caches — cheap swept collision. (b) The slack
-bound stops a particle long before it can travel far enough to cross a limb. (c) Substepping shrinks
-per-step travel.
-*Limit, stated:* this is swept in translation, not in rotation. A collider spinning fast enough that a
-point on its surface travels more than its own radius within one substep can still be missed. Full CCD
-for cloth is out of scope.
-*Spec:* a capsule swept through a sheet at 20 m/s; assert no particle's `sdf` sign flips across a step.
-
-**P4 — Folds, tangles, and stays stuck.** The named requirement, so four mechanisms:
-
-  *(a) No history-dependent normals.* Self-collision and collision normals are derived from the
-  proxy's own surface orientation and the collider's SDF gradient at the current position — never from
-  "which side was this on last frame". A history-based scheme latches onto a wrong side and stays
-  wrong indefinitely; an orientation-based one resolves a tangle as soon as the surrounding geometry
-  permits. This is the "predefined surface orientation" branch of the untangling literature, chosen
-  specifically because it has no state that *can* get stuck.
-
-  *(b) No degenerate fold state.* Quadratic bending (§6) means a fully inverted 180° fold is not a
-  singular configuration — it is simply high energy, and high energy relaxes.
-
-  *(c) The slack bound bounds the reachable set.* Every particle is under a hard leash of radius
-  `slack·d_geo,i` around its animated position, so the set of configurations the simulation can occupy
-  is a bounded neighbourhood of the animation. **Error cannot accumulate** — however bad a step is, the
-  next step starts inside that same neighbourhood, and there is no drift mode that walks the cloth
-  somewhere it cannot return from. That is the guarantee, and note what it does *not* claim: the
-  animated pose itself can be imperfect. It is collision-free in the bind pose (the build validates
-  exactly that, §11.3, and fails loudly with the offending vertex and collider named), but an extreme
-  animation pose can skin a garment slightly into a thigh. When that happens the attractor is slightly
-  wrong and the cloth is slightly wrong with it — bounded and self-limiting, not divergent.
-
-  This is also why `slack` is the one number worth reaching for when a garment misbehaves: it is
-  literally the size of the neighbourhood the simulation is allowed to explore. **M1 note:** with §3.4's
-  corrected factor of two, `slack = 1` makes that neighbourhood the whole of what the tether already
-  allows, so the guarantee at `slack = 1` is the tether's rather than the leash's — which is the right
-  answer for a rope, and is why every chain in the library sits there.
-
-  *(d) A bounded escape hatch.* If a particle's constraint residual stays above a threshold for N
-  consecutive steps, it blends to its animated position over a short window. Local, bounded, on by
-  default with a conservative threshold, and counted in `ClothDiagnostics` so that a garment relying on
-  it is visible rather than silently rescued.
-
-*Spec:* deliberately invert half a sheet through itself, run, assert the residual falls below threshold
-and the mesh is self-intersection-free within N steps; separately assert the escape hatch is not
-triggered by a correctly authored garment under normal animation.
-
-**P5 — Jitter at rest.**
-*Mechanism:* the multiplier decay `α·γ < 1` bleeds accumulated force out of a resting configuration so
-it cannot ring; per-cloth sleep when the maximum particle displacement over a window falls below a
-threshold; wake on collider motion, anchor motion, wind change, or a `ClothDynamics` change.
-*M0 found the gap, and it is wider than "nothing is damping it".* The mechanism reaches **hard** rows
-only, because a soft row has no multiplier to decay — and a soft row whose penalty exceeds about
-`8·(m/h²)` does not merely fail to dissipate, it makes the step **add** energy. Measured on a hanging
-sheet: total mechanical energy climbing +6.8 J against a system whose entire gravitational potential
-is 1.2 J, sustained indefinitely, and shrinking but never vanishing as iterations or substeps go up.
-Below that ratio the same row is dissipative and settles. What stops it is `ClothDynamics#damping`,
-which arrives with the component in M1 — so **damping is load-bearing for P5 rather than a taste
-control**, and the M1 spec has to gate on a soft cloth actually settling. `MEASUREMENTS.md` §6.
-*Spec:* a settled cloth reaches sleep within a bounded number of steps and its positions are bit-identical
-across the following 300.
-*M1 landed both halves and measured them.* Every library fabric, on a 12-link chain set swinging at
-3 m/s, sleeps: **220 steps for denim, 770 for silk**, everything else between, and the order is the
-damping order. Sleep stops the **write-back** as well as the step, which is what makes "bit-identical"
-a fact rather than a hope — a pose that is not rewritten cannot drift, and one rewritten from unchanged
-inputs is only *probably* identical. A cloth wakes on anchor motion, on a `ClothDynamics` change, on a
-`blend` change, and on an explicit `ClothSystem#wake` for anything it cannot see.
-
-And the damping gate, on the configuration §6 measured the limit cycle in — a 16-link rope with its
-stretch rows forced soft at 1e5 N/m, a ratio of about 350 — after 1,500 steps: **2.90e-3 J undamped,
-1.28e-6 J at the library's own `damping = 0.12`**, 1.82e-12 J at the top of the range. Three orders of
-magnitude from a field the design first described as a taste control. Note what damping does *not* do:
-it does not stop the step adding energy, it removes energy faster than the step adds it, which is why
-the numbers keep falling to `damping = 1` instead of hitting a floor. `MEASUREMENTS.md` §12.
-
-**P6 — Teleport and cut.**
-*Mechanism:* anchor motion above a threshold in one step is a teleport — `Reset` (re-seed at the
-animated pose, zero velocity) or `Keep` (carry the shape across). Default `Reset`, followed by a short
-stabilisation window in which the velocity limit ramps back from nothing, so the first steps after a
-reset cannot produce a whip.
-*Spec:* teleport 1 km mid-swing; assert bounded velocity every step and convergence to the animated pose.
-*Measured, M1:* `Reset` peaks at **0.000 m/s** across the 240 steps after the jump and lands on the
-animated pose; `Keep` peaks at 5.58 m/s, which is the swing it was already carrying, and shifts by
-0.078 m in local coordinates against 1.489 m for the reset. The threshold is `max(4·reach, 2 m)` per
-step, and a 9 m/s sprint does not reach it for any library fabric.
-
-**M1 named the mode differently and found `Keep` is free.** There is no `ClothTeleportMode`: the choice
-is binary, so it is `ClothFlags.TeleportKeep`, one bit on the component that already carries the
-cloth's own switches — a mode enum for two values is the discriminator field §3.1 exists to avoid. And
-`Keep` is *literally* free: MagicaCloth2 applies the anchor delta rigidly to every particle, but in a
-frame anchored to the cloth's own entity the particles are already anchor-relative, so "apply the
-delta" is doing nothing. The implementation is a `return`.
-
-**P7 — Fast locomotion: whipping, lag, centrifugal spray.**
-*Mechanism:* the simulation runs in a **local frame anchored to the cloth's own entity**, with
-`ClothDynamics#inertia` controlling how much of the anchor's world motion the cloth is allowed to
-feel, plus anchor linear and angular speed limits. This is MagicaCloth2's `InertiaConstraint` idea and
-it is the correct one: it makes "character sprints, cape behaves" a default rather than a tuning
-exercise.
-*Spec:* drive the anchor along a step-function velocity profile; assert bounded particle speed throughout.
-*Measured, M1:* a square wave of ±9 m/s, one second a phase. Peak local particle speed runs 11.3 to
-29.3 m/s across the library against clamps of 96 to 288, so the smallest headroom is **5.7×**; nothing
-teleports, and nothing leaves its own reach by more than 0.35%. The anchor limits are derived rather
-than authored — half a reach of travel and half a radian of rotation per fixed step, both expressed
-against the cloth's own geometry so a 3 cm pendant and a 30 m mooring line get the same treatment.
-`inertia` measures monotone and exactly zero at zero: 0, 0.20, 0.37, 0.52, 0.65 m of tip lag across
-its range, which is what makes it a dial rather than a switch with a meaningless middle.
-`MEASUREMENTS.md` §13.
-
-**P8 — Degenerate authoring.**
-*Mechanism:* build-time validation, not runtime tolerance. The proxy builder welds duplicates, drops
-zero-area triangles, and refuses non-manifold and inconsistently-wound configurations. The existing
-`bt_edge_read_diamond` already declines every configuration a bending stencil cannot be built on —
-wire edges, boundary edges, non-manifold edges, non-triangular neighbours, inconsistent winding, and a
-"diamond" that is really one doubled triangle — so the degenerate cases are rejected by a function that
-has already thought about them rather than by new code.
-*Spec:* a corpus of deliberately broken meshes, each producing a specific diagnostic and no proxy.
-
----
-
-## 8. Collision against the physics world
-
-### 8.1 The index
-
-`ClothColliderSystem` maintains `ClothColliderIndex`: a flat array of packed records, each holding the
-shape kind and its parameters, the world matrix, its cached inverse, the previous step's matrix, the
-world AABB, friction and inflation. `OccluderBody` in the acoustic simulator is the same record and is
-the shape to copy — including its precondition that the pose is rigid, so a distance in the shape's
-local frame equals a distance in world space.
-
-Per step, `ClothSystem` queries the index with the cloth's own fattened AABB and gets the overlapping
-records. That set is packed into shared memory for the worker; nothing on the far side of the worker
-boundary is an object.
-
-### 8.2 Evaluating a collision
-
-The collision row needs `sdf_c(x_i)` and its gradient. Bring the particle into the collider's local
-frame with the cached inverse, evaluate the closed-form SDF and gradient there, rotate the gradient
-back. Swept behaviour comes from interpolating the collider's pose between the previous and current
-matrices at the substep's fraction.
-
-**Supported kinds are analytic primitives**: sphere, capsule, box, cylinder, and a plane. That
-restriction is universal in shipping cloth systems — MagicaCloth2 offers sphere, capsule and plane;
-Chaos Cloth adds tapered capsules and convex hulls — and it is what makes the inner loop a handful of
-arithmetic instead of a BVH descent. A `Collider` carrying a mesh or heightmap shape is **skipped with
-one warning naming the entity**, and the documented answer is to add primitive `ClothCollider` children,
-which is what an author would do anyway for a character.
-
-The engine's shapes already carry the closed-form SDFs — `CapsuleShape3D#signed_distance_at_point`,
-`BoxShape3D#signed_distance_at_point` and the rest are exact and inline. Their *gradients* are not:
-`signed_distance_gradient_at_point` on capsule, box and cylinder all fall back to
-`compute_signed_distance_gradient_by_sampling`, which is four SDF evaluations and a normalise. That is
-fine for voxelising a fluid obstacle once per step. It is not fine in a per-particle, per-iteration
-loop, so §14 makes the analytic gradients shared code that both sides use.
-
-### 8.3 Friction
-
-Coulomb friction as a row with clamps at `±μ·f_n`, where `f_n` is the collision row's converged
-multiplier from this step and `μ` combines `Collider#friction` with `ClothCollider#friction_scale`.
-The combine rule is the one `physics/contact/combine_material.js` already applies, so cloth and rigid
-bodies agree about what a surface feels like. Static/dynamic separation follows the smooth transition
-VBD uses, which avoids the high-order derivatives that make a hard Coulomb switch jitter.
-
----
-
-## 9. Self-collision
-
-Off by default — `ClothDynamicsFlags.SelfCollision`, set on the library entries that need it (skirts,
-long coats, hair) and clear on the ones that do not (capes, ponytails, banners). It is the most
-expensive part of every cloth system that has it — MagicaCloth2's self-collision constraint is 2,564
-lines against 606 for distance — and the pathology guarantees in §7 do not depend on it.
-
-Two tiers:
-
-**M4a — particle-particle repulsion.** A uniform hash grid over particles in the cloth's local frame;
-pairs closer than `r_i + r_j` get the unilateral row from §6. Pairs sharing a triangle or an edge are
-excluded, since they are already governed by stretch and bend rows and would otherwise fight them.
-O(n) with a small constant, and it prevents the great majority of visible interpenetration.
-
-*This tier cannot see cloth passing between particles.* A sheet thinner than its particle spacing can
-still slip through itself. Stated, not hidden.
-
-**M4b — point-triangle and edge-edge.** The full stencil set, which closes that gap, over the same
-grid. Deferred behind measurement: it roughly triples the self-collision cost and the benefit is
-garment-dependent.
-
-Both tiers derive their normals from the proxy's surface orientation, per P4(a).
-
-There is no 3D uniform hash grid in `core` today; there is a well-tested 2D one
-(`core/geom/2d/hash-grid/SpatialHashGrid.js`) whose structure is the template. §14.
-
----
-
-## 10. Wind and aerodynamics
-
-Cloth that does not move with the air reads as dead, and this engine has something better than a wind
-zone: a **fluid simulator**. `FluidField` exposes `sampleVelocity(out, x, y, z)` with trilinear
-filtering over a MAC grid, `fluid_build_world_to_grid` builds the world→grid transform, and
-`FluidObstacle` already voxelises physics colliders into the field so the air is genuinely disturbed by
-the bodies in the scene.
-
-So the design is: **a cloth overlapping a `FluidComponent` samples its velocity field per particle and
-applies aerodynamic drag against it**, scaled by `ClothDynamics#drag`. The term is an external
-acceleration, `a_drag = drag · (u_air − v) · |n·û|`, with the normal-facing factor making a sheet catch
-the wind broadside and slice through it edge-on — the difference between a flag and a rope.
-
-The payoff is that a character running past a cape gets a wake, because the fluid solver already
-produces one; a fire's convection lifts a banner; a door slamming pushes a curtain. None of that needs
-cloth-specific authoring, and none of it needs a wind system that duplicates what the fluid system
-already does.
-
-Fallback when there is no fluid field in range: a `GlobalFluidEffector`-shaped ambient term — a
-constant `wind` vector plus a small band-limited noise for gusting — read from the same interface, so
-the cloth code has one path and does not branch on whether a simulation is present.
-
-Cost control: sampling is per particle per *step*, not per iteration, and a cloth outside every fluid
-field's bounds skips it entirely. Sleep (P5) wakes on a wind change so a settled banner does not stay
-asleep through a gust.
-
-This is deferred to M6 — it is the feature most likely to be cut for schedule, and nothing else depends
-on it.
-
----
-
-## 11. Geometry in, results out
-
-**Cloth moves joints. It does not produce vertices.** The mapping from a simulated particle to a
-render vertex already exists in this engine and it is the **skin**: a `Skin` holds `joints: Node3D[]`
-plus inverse-bind matrices, every render vertex carries a four-entry weight palette into that joint
-list, and `node.global · inverse_bind` is what the GPU blends every frame. Cloth writes joint
-transforms; the existing skinning pass does the rest — including bounds refresh and BLAS refit, which
-a bespoke vertex-deformation path would have to reimplement.
-
-That is the whole relation, and it is why there is no cloth-owned render mesh anywhere in this design.
-
-### 11.1 Entity hierarchies — `Cloth` alone
-
-One particle per entity in the transform subtree of the entity the component is on, walked through
-`TransformAttachmentSystem#findChildrenOf`, stopping at a nested `Cloth` or a `ClothExclude`. Stretch
-rows along parent-child links, bend rows along each chain, and the anchor entity itself is the fixed
-set — so `d_geo` is hop distance from the anchor and every derived quantity in §3.4 works unchanged.
-
-Output is written back to the subtree entities' `Transform64` — position directly, rotation derived
-from the direction to the child, interpolated between parent-driven and child-driven orientation, which
-is what keeps a two-link chain from looking hinged.
-
-**M1 made three of those words exact.**
-
-*Both transforms are written: the world `Transform64` and the local
-`TransformAttachment#transform`.* 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, 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 (measured at 1.7e-15 m), and §4.1's ordering problem stops
-being one. It is also 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*.
-
-The authored pose is not lost by being overwritten. It is captured once, when the cloth seeds, and
-lives in the cloth from then on — which is what `blend = 0` returns to, what the leash centres are
-measured from, and what a re-seed of a live cloth reads instead of the shape the solver left behind.
-The consequence, stated: **in the entity path the animated pose is constant in the anchor's frame.**
-That is a property of the case rather than a limitation of the code — a subtree's authored pose is
-rigid relative to its anchor — but it does mean a subtree whose *links* are independently animated is
-not an M1 case. That is the rig path, where the animated pose comes from the skeleton and is live.
-
-*The rotation is a **swing** on top of the animated orientation*, `q = swing(d_animated → d_simulated)
-⊗ q_animated`, using the minimal (twist-free) arc. Twist is inherited from the animation rather than
-invented, because 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, since at `blend = 0` the
-simulated direction *is* the animated one and the swing is the identity. A node with both a parent and
-children takes the half-way rotation between the two swings; a leaf takes its parent's. The shortest
-arc had no primitive in `core` and now does (`quat3_shortest_arc`), which is §14's doctrine turning up
-a fourth time.
-
-*Nothing is announced on a simulated node, and every pruned boundary is.* A `TRANSFORM64_EVENT_CHANGE`
-on a simulated node would make the attachment system recompose its children from the authored pose —
-undoing the write that was just made, and cascading, for a chain, quadratically. But the root of a
-`ClothExclude` subtree, and a nested `Cloth`'s anchor, are *not* particles and still have to move: the
-write-back poses each of them by hand against the link it hangs from and announces exactly there, which
-reaches everything below the cut through the ordinary cascade and reaches nothing above it.
-
-This is the path for props that genuinely *are* entity hierarchies: a rope, a chain, a hanging sign, a
-mooring line, a rigid model whose parts were expanded into entities and each drew as a
-`ShadedGeometry`. It needs no new rendering code, because moving an entity's `Transform64` is already
-how anything moves.
-
-### 11.2 Skinned garments — `Cloth` + `ClothRig`
-
-A character's cape is not an entity hierarchy and cannot be made into one.
-`shade_node_to_entity_composition` expands a model into entities and attaches a `ShadedGeometry` to
-each node that draws — but a skinned node contributes its transform and its name and **no geometry**,
-because its vertices deform against a skeleton the renderer owns and the GPU poses. Its joints are
-`Node3D`s inside the entity's `SceneBundleInstance`, and making them entities is explicitly a design
-this program does not do (D47). So for a skinned garment there is no `ShadedGeometry` component and no
-bone entities: the geometry is registered with `GPUAnimationManager` through
-`register_instance_animation`, and the only writable handle is the joint's `Node3D.transform_local` —
-the same handle the animation systems write.
-
-Cloth therefore drives joints, and the proxy names which ones. **Three resolutions, deliberately:**
-
-| tier | order of magnitude, skirt | what it is | who owns it |
-|---|---|---|---|
-| render mesh | ~5,000 vertices | `MeshletGeometry`, GPU-resident, never touched by cloth | the asset |
-| sim proxy | ~400 particles | what the solver steps | `ClothProxy` |
-| output joints | ~60 | what `Skin#joints` holds; the palette binds render vertices to these | `ClothProxy` |
-
-Decoupling the middle tier from the bottom one is the point. Simulation wants enough particles to
-drape; skinning wants only enough joints to *describe* the drape, and a four-weight palette blends
-smoothly between far fewer of them than the simulation needs. Each output joint takes its position and
-its frame from a small neighbourhood of particles — a triangle fan or a fitted patch — so the joint
-count is a build-time choice about deformation fidelity rather than a consequence of solver
-resolution. That is also what disposes of the "one node per particle" cost worry: nothing requires
-one node per particle.
-
-Two cases, and they differ only in where the joints and weights came from:
-
-- **The garment is already rigged** — an artist made 8–20 cape joints and skinned the cape to them.
-  This is the common case and by far the cheapest. The proxy is thin: joint indices, the topology
-  connecting them, rest lengths, `d_geo`. **There is no binding step and no generated geometry — the
-  artist's skin is the relation.** A cape, a ponytail, a coat tail, a loincloth: all of this.
-- **The garment has no usable rig** and wants per-vertex drape — a full skirt. The importer generates
-  the joint set and generates a skin binding render vertices to it, then bakes both into the proxy.
-  At runtime this is *indistinguishable* from the rigged case: the GPU sees an ordinary skin, the
-  solver sees an ordinary particle set.
-
-Animated targets — the `s_i` that the slack row, blending and P4 all need — come from
-`mesh_apply_skeletal_vertex_skinning`, which already takes flat positions, weights, indices and 4×3
-bone matrices and writes flat output. Typed arrays in, typed arrays out, no objects: it crosses the
-worker boundary as-is.
-
-**What was rejected.** A dedicated deformation pass — cloth writing vertex positions into a dynamic
-geometry buffer, with render vertices bound barycentrically to proxy triangles — is the obvious
-alternative and is genuinely simpler *as a deformation*: one frame per triangle rather than per joint,
-no palette width to respect. It loses because `MeshletGeometry` is meshlet-clustered and BLAS-backed,
-so a new path has to reimplement per-frame vertex upload, meshlet bounds refresh, normal
-recomputation and BLAS refit — all of which the skinning path already does and has playgrounds for.
-It stays written down as the fallback if M3's measurements go badly.
-
-### 11.3 Building a `ClothProxy`
-
-At import, producing the object `ClothRig#proxy` points at. Almost entirely existing code.
-
-For a **rigged** garment, only steps 5–8 run, over the joint graph rather than a mesh:
-
-1. Load the source garment into a `BinaryTopology` (`bt_mesh_from_indexed_geometry`).
-2. Weld and clean (`geometry_deduplicate_vertices`, drop degenerate faces).
-3. Decimate to the target particle count with `bt_mesh_simplify_by_error` — quadric error metric, via
-   `bt_mesh_compute_vertex_quadrics`. This is the standard distance-based reduction every cloth package
-   does, with a principled metric instead of a hand-rolled one.
-4. Extract stretch rows from edges, bend stencils from `bt_edge_read_diamond`, and the boundary from
-   `bt_collect_boundary_segments`.
-5. Derive the **fixed set automatically**: particles whose skin weights are dominated by joints
-   *outside* the garment's own joint set are pinned. This is what makes "works untouched" true — a
-   cape pinned at the shoulders needs no painting, because the skin data already says where the cape
-   stops being cape.
-6. Bake `d_geo` — geodesic distance from every particle to the fixed set. This one array drives the
-   tether row, the slack profile, and the pinning, so the three cannot disagree.
-7. Colour the particle graph (`colorizeGraphGreedy`, checked by `validateGraphColoring`), and permute
-   the particle order so each colour is a contiguous range.
-8. Resolve joint **names to indices** into `Skin#joints`, using `SceneBundleInstance#nodes`. This is
-   the only place a name appears anywhere in the system.
-9. **Unrigged only:** choose the output joint set, fit each joint's neighbourhood and bind pose, and
-   generate the skin's weights and inverse-bind matrices for the render mesh.
-10. **Validate**: manifoldness, no zero-length edges, and — the P4(c) precondition — that the skinned
-    bind pose is collision-free against the character's `ClothCollider` set.
-
-Vertex painting (per-vertex stiffness or slack multiplier) is supported through an optional texture or
-vertex-colour channel and is never required. Steps 5 and 6 are the default, and the intent is that most
-garments never override them.
-
----
-
-## 12. Data layout, threading, the worker
-
-**One `SharedArrayBuffer` for the whole cloth world**, not one per instance. `WorkerSystem`'s model is
-a single shared buffer, a single command region and a single atomic publishing one in-flight step, and
-`WorkerFluidSystem` already shows how a variable set of simulated things fits that model: the command
-region carries a count and then a list of ids to step. Cloth does the same — each instance gets a
-region inside the buffer, and the command region names which instances are live this step, so sleeping
-(P5) and culled (§12.1) instances cost nothing but their absence from a list.
-
-SoA throughout:
-
-| Region | Type | Contents |
-|---|---|---|
-| particle state | `Float32Array` | `x`, `x_prev`, `v`, `y`, inverse mass, radius |
-| animated targets | `Float32Array` | `s`, backstop origin + normal |
-| topology | `Int32Array` | edge pairs, bend stencils, colour ranges, tether anchors |
-| rest data | `Float32Array` | rest lengths, bend weights, `d_geo` |
-| duals | `Float32Array` | `λ` and `k` per persistent constraint |
-| colliders | `Float32Array` | packed records for this step |
-| contacts | `Float32Array` | transient rows + their warm-start `λ`, keyed by (particle, collider slot) |
-
-`ClothDynamics` reaches the worker through the command region, written every step — a dozen words into
-memory the worker already shares, cheaper than tracking dirtiness, and it keeps
-`cloth.dynamics.slack = 0.2` working live, which is the point of a value object rather than a preset
-that has to be re-applied.
-
-`Float32` for particle state, not `Float64`. The simulation runs in the cloth's **local frame**, so
-coordinates are garment-sized rather than world-sized and f32 has ample precision; the payoff is half
-the bandwidth in the loop that dominates. The local frame is not a memory optimisation that happens to
-help — it is the same choice that makes P7's inertia handling natural, and the precision win follows.
-Write-back converts local f32 to world `Transform64` at the boundary, once per particle per step.
-
-Transient contact rows need their multipliers warm-started across steps to be worth anything, so they
-are keyed by `(particle index, collider slot)` and matched on the next step. A collider that leaves the
-index drops its slot and its contacts start cold, which is correct.
-
-**The worker.** `WorkerClothSystem` is a `WorkerSystem` subclass and follows `WorkerFluidSystem`
-exactly, because that pattern is already proven in this repo: `collect` packs colliders and animated
-targets into shared memory and writes the command words, a single `Atomics.store` publishes the step,
-`apply` reads the result on the next tick, and the fixed-step gate guarantees the worker is idle during
-every system's `fixedUpdate`. The split is the same shape too — arbitrary user-facing work (component
-reads, `Transform64` sync, index queries) stays on the main thread; the pure numeric step crosses.
-
-The standing gate is the one the fluid system already holds itself to: **`ClothSystem` and
-`WorkerClothSystem` must produce bit-identical results.** Identical code over identical data in an
-identical order. That is what makes the worker a deployment choice rather than a behavioural fork, and
-it is why the core is a pure function over typed arrays from milestone zero even though the worker does
-not arrive until milestone five.
-
-Testing the bridge needs no worker: `SystemWorkerLoopback` gives a real `SystemWorkerHost`, a real
-`SharedArrayBuffer` and real `Atomics` in-process, with message delivery and step execution as explicit
-events a spec can order. Only the thread is faked.
-
-`SharedArrayBuffer` requires a cross-origin isolated page (`COOP`/`COEP`), which `WorkerFluidSystem`
-already documents. The main-thread `ClothSystem` is the fallback where that is not available, and it is
-not a degraded mode — it is the same code.
-
-### 12.1 Culling
-
-Cloth outside the view frustum stops stepping, which for a crowd is the difference between a budget and
-a problem. Resuming without a pop means blending from the animated pose back to the simulated one over
-a short window rather than snapping — the same `blend` machinery from §3.1, driven by the system
-instead of the author.
-
----
-
-## 13. Reuse ledger
-
-What this design takes from the engine rather than building:
-
-| Need | Existing code |
-|---|---|
-| Vector and quaternion math | `core/geom/vec3/*` (95 functions), `core/geom/3d/quaternion/*` |
-| Mesh topology, adjacency, bending stencils | `core/geom/3d/topology/struct/binary/` — `BinaryTopology`, `bt_edge_read_diamond`, `bt_edge_is_boundary`, `bt_collect_boundary_segments` |
-| Proxy decimation | `bt_mesh_simplify_by_error`, `bt_mesh_compute_vertex_quadrics` |
-| Mesh cleanup | `geometry_deduplicate_vertices` |
-| Graph colouring | `core/graph/coloring/colorizeGraphGreedy.js`, `validateGraphColoring.js` |
-| Collider shapes and their SDFs | `core/geom/3d/shape/*` — closed-form `signed_distance_at_point` on every primitive |
-| Collider AABBs, pose caching | `core/geom/3d/aabb/*`, `aabb3_matrix4_project` |
-| Collider ECS wiring | `Collider`, `ColliderFlags`, `ColliderObserverSystem` (as the pattern) |
-| "Opt a collider into a second simulation" | `FluidObstacle` + `FluidObstacleSystem`, `AcousticBody` |
-| Collider index shape | `AcousticOccluderIndex` + `OccluderBody` |
-| Component holds a built shared asset | `Collider#shape`, `ParticleEffect#program` — the convention `ClothRig#proxy` follows |
-| Surface material combination | `physics/contact/combine_material.js` |
-| Constraint-row doctrine | `physics/constraint/solve_constraints.js` |
-| Subtree walk | `TransformAttachmentSystem#findChildrenOf` / `#countChildrenOf`, `TransformAttachment` |
-| Animated targets | `mesh_apply_skeletal_vertex_skinning` (flat arrays, worker-safe) |
-| Wind / aerodynamics | `FluidField#sampleVelocity`, `fluid_build_world_to_grid`, `GlobalFluidEffector` |
-| Worker offload | `ecs/async/WorkerSystem.js`, `SystemWorkerHost`, `SystemWorkerLoopback`, `WorkerFluidSystem` as the worked example |
-| Fixed step + render interpolation | `PhysicsSystem`'s producer/`__interp_restore` contract |
-| Transforms | `Transform64`, `Node3D` |
-| Particle → render-vertex mapping | `Skin` — joints + inverse-bind matrices + the four-weight palette; cloth writes joints and the existing pass does the rest |
-| Reaching a model's joints from its entity | `SceneBundleInstance` (`skins`, `nodes` by name), `register_instance_animation` |
-| Deformation, bounds refresh, BLAS refit | `GPUMeshSkinningContext`, `shader_skin_matrix_prep`, `bounds_refresh/` — all of it inherited by driving joints rather than vertices |
-| Non-finite tripwire pattern | `find_non_finite_physics_state.js` |
-| Strippable assertions | `core/assert.js` |
-| Serialisation | the `*SerializationAdapter` pattern and its binary codecs |
-
----
-
-## 14. New shared code this justifies
-
-Three pieces belong in `core`, not in `cloth`, because the cloth need exposes a gap the engine has
-anyway:
-
-1. **Analytic SDF gradients** for sphere, capsule, box, cylinder and plane, as free functions in
-   `core/geom/3d/shape/sdf/`. Today `signed_distance_gradient_at_point` on capsule, box and cylinder is
-   `compute_signed_distance_gradient_by_sampling` — four SDF evaluations plus a normalise, for shapes
-   whose gradients are two lines of algebra. The shape classes call the new functions, cloth calls them
-   directly on packed data, and there is one implementation rather than two. This makes the existing
-   shapes faster as a side effect.
-
-2. **A 3D uniform hash grid**, modelled on `core/geom/2d/hash-grid/SpatialHashGrid.js`. Needed for
-   self-collision; useful anywhere a broadphase over many small equal-sized things is wanted, which the
-   2D one already demonstrates.
-
-3. **`PlaneShape3D`.** There is no infinite plane shape. Cloth wants one for ground and for author-placed
-   cut planes, and its absence today is worked around with large boxes.
-
-4. **A shortest-arc quaternion**, `core/geom/3d/quaternion/quat3_shortest_arc.js` — the minimal,
-   twist-free rotation carrying one unit vector onto another. **M1 needed it and the family did not
-   have it**: `quat3_*` had `multiply`, `integrate`, `nlerp` and the uint32 codecs but nothing that
-   answers "orient this bone along that direction", which is the whole of §11.1's write-back. It is
-   also the one place in the family with a genuine discontinuity — no continuous choice of axis exists
-   on the whole sphere, so an antipodal pair has to pick one — and having it in `core` with a spec
-   around that case is better than having it inlined in a write-back loop without.
-
-Test helpers for all of it live inside the `.spec.js` files or in `__fixtures__`, per the repo rule —
-a shared helper module would ship on npm.
-
----
-
-## 15. MagicaCloth2: what we take, what we leave
-
-MagicaCloth2 is the reference and it is a good one. It has shipped, it is fast, and its feature set is
-the accumulated answer to a decade of production complaints. Taken:
-
-- **Two cloth kinds over one solver.** MeshCloth and BoneCloth differ only in how particles are seeded
-  and how results are written back. This is right and §11 copies it — expressed as component presence
-  rather than an enum.
-- **A proxy mesh decoupled from the render mesh**, with distance-based reduction and custom skinning
-  back to the render vertices. Also right; §11.3 does the same thing with `bt_mesh_simplify_by_error`.
-- **The inertia model.** World and local inertia fractions, movement and rotation speed limits, an
-  anchor that cancels inertia for a character on a moving vehicle, teleport detection with Reset/Keep
-  modes, and a stabilisation window after reset. This is the least glamorous part of the package and
-  the most valuable; P6 and P7 are it, nearly verbatim.
-- **Max-distance and backstop** as first-class constraints rather than debugging aids. P3 and P4 lean on
-  them harder than MagicaCloth does — here the leash is the correctness argument, not a polish pass.
-- **Tether/LRA** as the answer to over-stretch at low iteration counts.
-
-Left:
-
-- **The parameter surface.** MagicaCloth2's serialised data is a dozen constraint blocks, several of them
-  animation curves over "depth", and its per-constraint files run to hundreds of lines of tuning. That is
-  the direct consequence of a PBD solver whose apparent stiffness depends on iteration count: when the
-  physical meaning of a slider moves with the budget, you end up shipping a curve per slider. AVBD's
-  parameters do not move that way, so §3.3 can be one small value object — and the per-particle profile
-  that MagicaCloth authors with curves falls out of `d_geo` instead (§3.4).
-- **Angle restoration and angle limit constraints.** These exist to give PBD chains a restoring force
-  that bending alone cannot supply at low iteration counts. With a solver that converges, bend rows plus
-  tethers cover the same ground with less to configure.
-- **A separate spring constraint.** Subsumed by the slack row with a non-zero radius.
-- **A distance constraint solved twice per substep** (before and after collision). An artefact of the
-  Gauss-Seidel ordering; the augmented Lagrangian's dual update does this work.
-- **Its collision layering model.** We already have `Collider`, layers and masks; a parallel system would
-  be a second thing to keep in sync.
-- **Its wind zones.** We have a fluid simulator (§10).
-
----
-
-## 16. State of the art
-
-**The line this design sits on.** PBD → XPBD → substepped XPBD → VBD → AVBD.
-
-- **XPBD** (Macklin, Müller & Chentanez) made PBD stiffness independent of iteration count by
-  introducing compliance and a per-constraint multiplier. **Small Steps in Physics Simulation**
-  (Macklin et al. 2019) then showed that *n* substeps with one iteration each beats one step with *n*
-  iterations — less constraint error, far less artificial damping, and better behaviour across a wider
-  stiffness range than Krylov-based implicit solvers. Together these are the state of practice: Chaos
-  Cloth, MagicaCloth2 and Blender's cloth all sit here.
-- **Vertex Block Descent** (Chen, Liu, Yang & Yuksel, SIGGRAPH 2024) reframed the step as block
-  coordinate descent on implicit Euler's variational form, solving one 3×3 system per vertex per
-  iteration. Unconditionally stable at any iteration count, no line search, and it colours the vertex
-  graph rather than the constraint graph. Its reported failure mode is exactly the one that matters here:
-  it struggles to converge under high stiffness ratios and has no mechanism for enforcing hard
-  constraints — which is what a pinned garment on a rigid body *is*.
-- **Augmented Vertex Block Descent** (Giles, Diaz & Yuksel, SIGGRAPH 2025) fixes precisely that with an
-  augmented Lagrangian: hard constraints at effectively infinite stiffness without the instability, plus
-  substantially better convergence under high stiffness ratios. Reference implementations exist in 2D,
-  in Metal, in PhysX, in Houdini, and — relevant to this engine — as a WebGPU solver.
-- **Going Further With Vertex Block Descent** (Saillant et al., 2025) extends VBD to higher-order
-  elements and confirms that substepping improves its convergence — which is why §5.2 substeps rather
-  than only iterating.
-
-**The line this design does not sit on.** **Incremental Potential Contact** and its descendants —
-**C-IPC** for codimensional objects, **GIPC** and **AGIPC** on GPU — guarantee intersection-free,
-inversion-free results through log-barrier contact and continuous collision detection. They are the
-correct answer when correctness is the requirement, and they are the wrong answer at a millisecond
-budget. We take one idea from that family: IPC's smooth static/dynamic friction transition, which VBD
-also adopts.
-
-**Self-collision** is where the field is currently moving, because parallel position solvers have made
-it the bottleneck rather than the solve. **Air Meshes** (Müller et al. 2015) tessellate the space
-between objects and prevent element inversion, which handles untangling robustly and automatically but
-requires maintaining a volumetric mesh. **Global Intersection Analysis** (Baraff, Witkin & Kass,
-"Untangling Cloth", 2003) is history-free and resolves tangles as soon as geometry permits — the
-property P4(a) is built on, even though we implement a far cheaper approximation of it. Recent work on
-hierarchical culling via discrete curvature targets the same bottleneck.
-
-**Industry.** Chaos Cloth (Unreal) is substepped XPBD with long-range attachments, max distance and
-backstop distance/radius — the same safety constraints §7 relies on, which is useful independent
-confirmation that they are what production actually needs. Comparative studies of VBD against PBD in
-Unity report parity at low vertex counts and a widening VBD advantage as the count rises, which matches
-the per-iteration cost story: VBD does more arithmetic per vertex and far less coordination.
-
-Sources:
-[Vertex Block Descent](https://arxiv.org/abs/2403.06321) ·
-[VBD project page](https://graphics.cs.utah.edu/research/projects/vbd/) ·
-[Augmented Vertex Block Descent](https://graphics.cs.utah.edu/research/projects/avbd/) ·
-[AVBD reference implementation](https://github.com/savant117/avbd-demo2d) ·
-[WebGPU AVBD](https://github.com/jure/webphysics) ·
-[Going Further With Vertex Block Descent](https://onlinelibrary.wiley.com/doi/10.1002/cav.70039) ·
-[XPBD](https://matthias-research.github.io/pages/publications/XPBD.pdf) ·
-[Small Steps in Physics Simulation](https://mmacklin.com/smallsteps.pdf) ·
-[Untangling Cloth](https://dl.acm.org/doi/10.1145/882262.882357) ·
-[Air Meshes for Robust Collision Handling](https://dl.acm.org/doi/10.1145/2766907) ·
-[Codimensional IPC](https://arxiv.org/pdf/2012.04457) ·
-[Efficient Self-Collision Culling via Discrete Curvature](https://www.mdpi.com/2227-7390/14/9/1504) ·
-[VBD vs PBD in Unity](https://www.mdpi.com/2076-3417/14/23/11072) ·
-[Chaos Cloth](https://dev.epicgames.com/documentation/en-us/unreal-engine/clothing-tool-in-unreal-engine)
-
----
-
-## 17. Milestones
-
-Each milestone is shippable and each `done` names evidence that ran. Nothing is reported complete on
-the strength of code existing.
-
-**M0 — the solver core. DONE, 2026-09-10.** `ClothState`, `cloth_step`, the vertex update, stretch and
-bend rows, colouring. Pure functions over typed arrays; no ECS, no worker, no rendering.
-*Proofs, all green:* finite-difference agreement between each row's analytic gradient and its numerical
-gradient; the P1 property test (see the correction in §7 P1 — strict per-update energy monotonicity is
-not true and the gate is what replaced it); a measured choice of α, β, γ and `k_min`/`k_max` with the
-sweep recorded in `MEASUREMENTS.md`, nothing copied; the performance budget measured on real topology.
-43 tests across six spec files.
-
-**M0 changed the design in six places**, each with the measurement behind it in `MEASUREMENTS.md` and
-each folded back into §5.2, §5.3, §6, §7 P1 and §7 P5 above. In one line each: the multiplier and the
-penalty band apply only to *hard* rows; the band is a ratio of `m/h²` rather than a stiffness; the PSD
-half of the geometric-stiffness term has to be kept; the 3×3 solve has to be an LDLᵀ; an SPD Hessian
-gives a descent direction rather than a monotone step; and P5's jitter mechanism does not reach soft
-rows, which need M1's damping.
-
-**Deliberately not in M0:** Chebyshev acceleration (§5.2) is gated on a particle not being in contact,
-and contacts arrive at M2, so there is nothing here to measure it against. The velocity clamp named in
-P1 is derived from `ClothDynamics#thickness` and belongs with the component that carries it — and it
-would have masked the property M0 exists to measure.
-
-**M1 — chains end to end. DONE, 2026-09-10.** `Cloth`, `ClothFlags`, `ClothExclude`, `ClothDynamics`,
-`ClothDynamicsFlags`, `cloth_dynamics_library.js`, `ClothSystem`, subtree seeding and write-back, the
-slack and tether rows, the strain-limit row, the inertia model, teleport handling, sleep, and the
-velocity clamp P1 deferred. No collision.
-*Proofs, all green:* P2, P5, P6 and P7, each with a companion test that runs the same scenario with the
-mechanism switched off; `ClothDynamics` value semantics and the measured mapping; three ordering tests
-— the derived order, the recomposition idempotency that makes it not matter, and a bound on the
-divergence when it is inverted; a second playground page, `playground/rig.html`, driving the real
-ECS with a rope, a chain, a five-strand rig under one `Cloth`, a hanging sign with a `ClothExclude`,
-and a nested pair. **43 tests across four spec files** — the leash row's 8, the system's 9, the
-pathology budget's 11, the value semantics and the mapping's 15 — plus 5 for the shortest-arc
-primitive and 4 more in `system_execution_order.spec.js`, for 52 in all. The engine suite is green
-at 18,179.
-
-**M1 changed the design in seven places**, each with the measurement behind it in `MEASUREMENTS.md`
-§9–15 and each folded back above. In one line each: three of §6's clamps had the wrong sign and would
-never have bound; §3.4's leash radius needs a factor of two before `slack = 1` means "no leash"; §7
-P1's velocity clamp cannot be derived from `thickness`, because that is a tunnelling bound and a
-tunnelling bound is *below* ordinary cloth speeds; §11.1's chain bending has no diamond to build a
-hinge on and uses a skip row instead; §11.1's write-back has to write the **local** transform as well
-as the world one; the levers no longer close the frame budget one at a time; and the strain-limit row
-buys a third of the over-stretch rather than the allowance it asks for, which makes `stretch` the
-weakest field in the parameter set.
-
-**And one thing M1 got wrong before it got it right, which is worth recording because the wrong answer
-was plausible.** §4.1 correctly identified that neither of the engine's two ordering mechanisms can
-place cloth after a poser, and the first attempt was to add a third — an execution-phase number on
-`System`, with a `PostPose` value. That put the vocabulary of animation into `engine/ecs`, which has
-none, to buy an ordering the design should not have needed in the first place. Removing the need was
-both smaller and better: writing the local transform makes the write-back idempotent, which turns the
-placement into a bounded quality question and leaves the scheduler alone.
-
-**Deliberately not in M1:** P4(d)'s bounded escape hatch, which needs a per-particle residual monitor
-and belongs with the collision rows that make a particle get *stuck* in the first place — a chain has
-no configuration to be stuck in. Chebyshev acceleration, still gated on contacts that arrive at M2. `β`,
-which M0 could not choose and M1 has no transient rows to choose it with either — every row M1 adds is
-persistent. `ClothSerializationAdapter` and its siblings: nothing in M1's scope list names them, and a
-codec written before `ClothRig` exists would be revised by M3 before it was ever loaded.
-Interpolation: cloth writes `Transform64` at the fixed rate and §12's producer/`__interp_restore`
-contract is not wired, which shows as a cloth updating at the fixed rate rather than the frame rate
-and is a visible-but-not-wrong gap. M5 is where it belongs, with the worker.
-**This is the first shippable feature.**
-
-**M2 — collision.** `ClothCollider`, `ClothColliderFlags`, `ClothColliderSystem`, `ClothColliderIndex`,
-packed records, analytic SDF gradients (§14.1), collision and friction rows, backstop.
-*Proofs:* P3 and P4 specs green; playground with a cape over an animated character.
-
-**M3 — skinned garments.** `ClothRig`, `ClothProxy`, the import build, joint write-back into
-`Node3D.transform_local`. **Rigged garments first** — no generated skin, no binding step, which is
-most of the value for a fraction of the work — then the unrigged path (steps 9 of §11.3) behind its
-own measurement.
-*Proofs:* P8 corpus green; a rigged cape over an animated character in a playground; for the unrigged
-path, the joint-count-to-fidelity curve measured before a joint budget is fixed, and the deformation
-compared against the source garment simulated at full resolution.
-
-**M4 — self-collision.** The 3D hash grid (§14.2), particle-particle repulsion, exclusion of
-topologically adjacent pairs.
-*Proofs:* the P4 tangle spec extended to self-intersection counts; a measured cost delta that justifies
-which library entries set `ClothDynamicsFlags.SelfCollision`.
-
-**M5 — the worker.** `WorkerClothSystem`, `ClothWorkerCore`, `cloth.worker.js`, the protocol.
-*Proofs:* bit-parity between `ClothSystem` and `WorkerClothSystem` as a standing gate; loopback specs
-covering step ordering, message ordering and shutdown; a measured main-thread cost reduction.
-
-**M6 — wind.** Fluid-field sampling, aerodynamic drag, the ambient fallback.
-*Proofs:* a playground with a banner in a simulated wake; a measured cost showing the per-step sampling
-stays inside budget. Cuttable without affecting anything else.
-
-**Performance budget — measured at M0, re-measured at M1, and it still does not hold on its own.** One
-character's full cloth complement — 1,024 particles at 2 substeps × 4 iterations, on a triangulated
-patch carrying 16.8 row incidences per particle — cost **3.50 ms per frame** at best at M0, against a
-2 ms target. **M1's rows made it 4.61 ms**: the strain limit is 0.73 ms (it doubles the stretch table,
-and the stretch rows are already 69% of the frame), the tether 0.36 ms, the slack row 0.10 ms. What
-that costs the plan is stated below.
-
-The estimate was wrong in its reasoning as well as its number: **gathering neighbour positions is not
-what dominates.** The controlled test is to relabel the source vertices at random, which destroys the
-locality `cloth_color_order` provides and changes nothing else — same colouring, same rows, same
-arithmetic. It costs nothing measurable at the 1,024 particles §17 budgets for (the whole state fits in
-L2) and 11% at four times that size. So the *entire* memory-locality component of the gather is a few
-per cent of the frame, and a layout optimisation has at most 11% to win.
-
-Deleting the workload piece by piece puts 69% of the frame in the stretch rows, 18% in the bend rows
-and 7% in everything else. That is a split of what each row kind *causes*, not of the arithmetic in
-its accumulate: the variants sit in different physical states, and an isolated loop over one accumulate
-measures a converged mesh rather than a moving one and disagrees with the deletion by a factor of five
-on the stretch row. `MEASUREMENTS.md` §7 carries the discrepancy rather than a story that resolves it.
-
-The levers, priced at M0 (`MEASUREMENTS.md` §7) and again on M1's row set (§14):
-
-| Lever | M0's rows | M1's rows |
-|---|---|---|
-| Fewer iterations — 1,024 at 2×**2** | **1.69 ms** inside | **2.38 ms** over |
-| Fewer substeps — 1,024 at 1×4 | **1.68 ms** inside | **2.40 ms** over |
-| Fewer particles — ~500 at 2×4 | **1.54 ms** inside | **2.53 ms** over |
-
-**No single lever reaches 2 ms any more.** Each of them lands inside when a second is spent alongside
-it — 400 particles at 2×4 is 1.72 ms, 576 at 2×2 is 1.28 ms, 1,024 at 1×2 is 1.17 ms — so this is a
-sizing decision rather than a wall, and it is one the library now makes explicitly: every garment entry
-spends two levers and says which two. The barycentric binding fallback from §11.2 is still not needed.
-
-Every figure here is the best of four independent rounds, which agree to ±5%. Cost is close to linear
-in both particles and sweeps, so any one lever is enough on its own and they compose. **Note what the worker does not do:** §12 moves this off the main thread, it does
-not make it cheaper, so "2 ms on the worker" with several characters in flight is a scheduling question
-this measurement does not answer.
-
-Re-measure at M2, M4 and M5.
-
----
-
-## 18. Risks and open questions
-
-**AVBD has a short track record for cloth. — MEASURED, and the risk was real.** VBD's paper covers
-cloth; AVBD's public reference implementations are 2D and rigid-body-focused. The augmented Lagrangian
-layer is well understood in the abstract, but its interaction with cloth's particular constraint mix —
-many soft rows, a few hard ones, transient contacts — is not something anyone has published numbers on.
-M0 found exactly that interaction to be where the design was wrong: **the multiplier must not touch a
-soft row at all** (it drove a 1 kN/m spring 100× stiffer than Hooke), and **the penalty band is only
-meaningful relative to `m/h²`**, which is a cloth-specific statement because cloth's mass term is four
-orders of magnitude below a rigid body's. Both are fixed and measured (§5.2, `MEASUREMENTS.md` §3–4).
-The core is now stable across 10,000 steps of deliberately absurd cloth, settles a hard chain to 1e-14 J
-at 80 links deep, and reproduces Hooke exactly on a soft row. The §6 row abstraction still means the
-descent loop could be replaced with substepped XPBD without touching the constraint definitions, and
-that fallback still costs one module — but nothing measured so far argues for taking it.
-
-**Per-vertex Hessian assembly in JavaScript may not hit the budget. — MEASURED, and it does not.**
-3.50 ms against a 2 ms target for 1,024 particles at 2×4. *Resolved by:* the plan's own first lever —
-half the iteration count, or half the particles, lands inside — so this is a sizing decision for M1's
-library and M3's proxy rather than an open risk. What is *not* resolved is that the cost is
-concentrated in the stretch row and only a third of that is the gather, so the obvious memory-layout
-optimisation is aimed at the smaller half. `MEASUREMENTS.md` §7.
-
-**System ordering. — DISSOLVED rather than resolved.** §4.1 carries the reasoning; in short, the
-derived score is a *sum* over what a system references, so touching more can only move a system
-**earlier**, and a consumer of a posed hierarchy touches strictly more than the poser. There is no
-declaration cloth could have made, and registration order does not break a non-tie. The engine has two
-ordering mechanisms and neither expresses this.
-
-The answer is not a third mechanism, it is not needing one: cloth writes each node's **local**
-transform alongside its world one, so a hierarchy recomposition reproduces the simulated pose rather
-than replacing it — measured at 1.7e-15 m — and the placement stops being a correctness question.
-*What is left, and it is a real cost:* running before the poser means the cloth's shape is one fixed
-step stale, which measures at a few centimetres on a 1.6 m rope under ordinary motion and up to a
-fifth of its own length at the sharpest reversal of a ±9 m/s square wave. It does not accumulate.
-An application that cares registers accordingly and gets nothing, because this is not a tie; an
-application that does not care is unaffected, which is the common case and the one this trades for.
-`MEASUREMENTS.md` §15.
-
-**The unrigged path's joint budget is unknown.** A rigged garment costs nothing new — its joints
-already exist. An unrigged one needs a generated joint set, and how many joints it takes to represent
-a skirt's drape through a four-weight palette is an open empirical question: too few and the garment
-reads as faceted, too many and every instance pays for rows in a transforms table shared with the
-whole scene. *Mitigation:* M3 measures the fidelity curve before fixing a budget, and ships the rigged
-path first so the feature is useful whatever the answer. The barycentric deformation pass (§11.2) is a
-designed fallback, not an improvisation.
-
-**Per-joint frames are the real cost of the unrigged path.** A particle has a position; a joint needs
-an orientation, fitted from a neighbourhood of particles every frame. That fit is the part with no
-existing implementation to lean on and the part most likely to be a source of artefacts when the
-neighbourhood degenerates — a fold that collapses a triangle fan has no well-defined frame.
-*Mitigation:* it is confined to the unrigged path, which M3 sequences last.
-
-**Quadratic bending cannot hold a curved rest shape.** A garment authored with a strong permanent curve
-will relax flatter than intended. M0 measured the exact boundary: the stencil annihilates the rest shape
-and **every affine image of it** — which is every in-plane deformation to first order, so a flat sheet
-being sheared, stretched or rotated stays at zero bending energy — but it does *not* annihilate an
-arbitrary planar configuration. Four coplanar particles that are not an affine image of the rest four
-read as bent. *Mitigation:* accepted for the fabrics the library targets. If a case appears, the fix is
-a rest-curvature offset in the stencil, which is a change to one row and not to the solver.
-
-**Swept collision is translation-only.** P3 states the limit. A fast-spinning collider can still be
-missed. *Mitigation:* more substeps in the affected `ClothDynamics`; genuine CCD stays out of scope.
-
-**A soft-row cloth does not come to rest. — CLOSED by M1's damping, and the size is measured.** M0
-measured a soft chain landing in a bounded limit cycle that 2,000 further steps do not move, and no
-solver constant reaches it, because `α·γ` decays a multiplier and a soft row has none. `damping` does
-reach it: on the configuration §6 measured, 2.90e-3 J undamped against 1.28e-6 J at the library's own
-`damping = 0.12`, and 1.82e-12 J at the top of the range. `cloth_pathology.spec.js` gates on exactly
-that pair.
-*What this does not claim:* damping does not stop the step adding energy, it removes energy faster than
-the step adds it. The equilibrium is bounded rather than zero — which is why the numbers keep falling
-all the way to `damping = 1` instead of hitting a floor — and a cloth whose rows are soft and far above
-the dissipative band is still a cloth being rescued rather than a cloth behaving. M1's mapping does not
-produce one; the gate exists so a future mapping that does is caught. `MEASUREMENTS.md` §12.
-
-**The escape hatch could mask authoring errors.** P4(d) rescues a stuck particle, which means a badly
-authored garment can look acceptable while relying on it. *Mitigation:* `ClothDiagnostics` counts
-escape-hatch activations per cloth and surfaces them, so "this garment is being rescued 30 times a
-second" is visible rather than invisible.
-
-**Open — two-way coupling.** Cloth does not push rigid bodies. The row model could carry it (the
-collision row's multiplier is a force, and applying its negation to the collider's body is mechanically
-straightforward), but the stability of that loop across two solvers with different time discretisations
-is a real question and is not answered here.
-
-**Open — the fixed set for an unskinned surface.** Step 5 of §11.3 derives the fixed set from skin
-weights, which is right for a garment on a skeleton and has no answer for a flag, a curtain or a
-banner that is not skinned at all. Those also sit at `slack ≈ 1` by necessity (there is no meaningful
-animated pose to follow), so the tether carries all the inextensibility — which works, but the fixed
-set still has to come from the mesh boundary or from authoring. M3 needs a second rule.
-
-**Open — LOD.** Distance-based particle-count reduction would need either multiple baked proxies per
-garment or a runtime hierarchy. Culling (§12.1) covers the off-screen case; the far-but-visible case is
-unaddressed.
-
-**Open — `stretch` is a weak control, and it is not obvious what would make it a strong one.** M1
-measured the strain-limit row removing about a third of the peak over-stretch and never reaching its
-own allowance, because it is a second hard row competing with the first for the same trust region and
-the same penalty band (§6). A fabric's *extension* is therefore governed by the iteration budget more
-than by the fabric, and the library says so by which entries build the row at all. Three things might
-change that and none is free: a soft fabric row inside the dissipative band with the hard row acting
-only as the limit (which reintroduces M0's settling problem at any realistic stiffness); a per-row
-penalty band, making `k_max/(m/h²)` a material property rather than a global (which `MEASUREMENTS.md`
-§4 shows trades stretchiness against settling); or accepting that near-inextensibility is what fabric
-*is* and demoting `stretch` to a documented weak knob. M2's contacts do not bear on it either way.
-
-**Open — the write-back has no interpolation.** §12 gives cloth `PhysicsSystem`'s producer /
-`__interp_restore` contract, and M1 does not wire it: cloth writes `Transform64` at the fixed rate and
-nothing blends between ticks, so a cloth updates at 60 Hz on a 165 Hz display. That is visible and it
-is not wrong — the poses are authoritative, they are simply held. It lands with M5, where the worker
-makes the fixed-step producer contract load-bearing for a second reason.
-
-**Open — the subtree is walked once.** A rope's links do not come and go, so `cloth_seed_subtree` runs
-on first step and `ClothSystem#reseed` is how a caller says the structure changed. That is the same
-contract `TransformAttachment#parent` already carries, and it is the right default; what it does not
-have is a way to *notice*. An entity added under a live `Cloth` is silently not simulated until
-someone re-seeds, which is a class of authoring mistake with no diagnostic behind it. `ClothDiagnostics`
-is where one would go.
+# Cloth — Design
+
+> Design document. Written 2026-09-10; **M0, M1, M2 and M3's rigged path are implemented**, and
+> every place they contradicted it has been corrected in place with the measurement named beside it.
+> §17 says what is done and what is not; `MEASUREMENTS.md` is the evidence.
+>
+> Scope: a cloth and soft-chain simulator that lives inside `engine/physics`, collides against the
+> `Collider` components the rest of the engine already authors, runs on a worker, and is safe to ship
+> with its defaults untouched.
+
+---
+
+## 1. What this is
+
+One solver over particles, driven by components:
+
+- **`Cloth`** — the thing that simulates. Put it on an entity and that entity's transform subtree
+  becomes a simulated chain: a rope, a chain, a hanging sign, a mooring line.
+- **`ClothRig`** — add it alongside `Cloth` and the particles are the **joints of a skinned model**
+  rather than the entity subtree. This is what makes a cape, a skirt, a banner on a character.
+- **`ClothCollider`** — the marker that opts an existing `(Collider, Transform64)` entity into being
+  something cloth collides with. This is the `RigidBody`-analogue: it says *this collider participates*,
+  and carries only what cloth needs that `Collider` does not already say.
+
+That last component follows a pattern the engine already has twice. `AcousticBody` opts a collider
+into the acoustic simulation and carries an `AcousticMaterial`; `FluidObstacle` opts a collider into
+the fluid simulation and carries an inflation radius. `ClothCollider` is the third instance of the
+same idea, and it should read like a sibling of those two, not like a new invention.
+
+The design commitments, in priority order, because they conflict and the ordering is the design:
+
+1. **It does not explode.** Not at 5 fps, not at 500, not when a parameter is absurd, not when a
+   character teleports, not when a collider is spawned inside the cloth.
+2. **It does not get stuck.** The set of configurations the simulation can reach is bounded around
+   the animated pose, and error cannot accumulate across steps.
+3. **It works untouched.** Adding a `Cloth` component with default values to a correctly authored
+   garment produces shippable motion. Tuning is an optimisation, never a prerequisite.
+4. **It is cheap.** A CPU worker budget measured in low single-digit milliseconds per character.
+5. **It is accurate.** Last, deliberately. Cloth that is 10% too stiff and never misbehaves beats
+   cloth that is correct and occasionally detonates.
+
+---
+
+## 2. Non-goals
+
+- **Garment authoring.** No pattern cutting, no sewing, no pressure/inflation. Import a mesh.
+- **Woven anisotropy.** No warp/weft/shear tensor. That needs UV-aligned quad topology and a
+  material model this design does not carry. Cloth here is isotropic with a bend modulus.
+- **Penetration-free guarantees.** IPC-class methods (`C-IPC`, `GIPC`) guarantee no intersection ever,
+  at a cost per step this budget cannot pay. We guarantee bounded, self-correcting penetration.
+- **Cloth pushing rigid bodies.** Coupling is one-way: colliders move cloth. Two-way coupling into
+  `PhysicsSystem`'s velocity solver is a later question and the constraint model leaves room for it
+  (§6), but it is not in scope.
+- **Tearing, plasticity, burning.**
+- **GPU simulation.** The engine has a mature WebGPU path and a particle VM that could host this, but
+  the requirement is a worker, and a worker is the cheaper, more portable, more debuggable answer.
+  Nothing in the data layout forecloses a GPU port; §12 keeps that door open.
+
+---
+
+## 3. Author-facing API
+
+```js
+// An entity hierarchy — rope, chain, hanging sign, a prop built out of entities.
+// Cloth simulates the transform subtree of the entity it is on. That entity is the anchor.
+rope_top.add(Cloth.from(ClothDynamics.ROPE));
+
+// A skinned model's garment — cape, skirt, banner, hair.
+// Cloth simulates the JOINTS of the model instance this entity owns.
+character.add(Cloth.from(ClothDynamics.SILK));
+character.add(ClothRig.from(cape_proxy));   // cape_proxy: ClothProxy, built at import
+```
+
+There is no mode enum and no discriminator field. **`Cloth` alone simulates the entity subtree;
+`Cloth` + `ClothRig` simulates a skinned model's joints** — component presence doing the job an enum
+would otherwise do badly. The solver is identical either way; only seeding and write-back differ.
+
+Those are two cases rather than one because **the engine has two hierarchies, and that is a decision
+rather than an accident**. `shade_node_to_entity_composition` expands a loaded model into entities and
+gives a `ShadedGeometry` to every node that draws — except a skinned one, which "is not expanded, and
+that is a boundary rather than an omission": it contributes its transform and its name and no
+geometry, because its vertices deform against a skeleton the renderer owns and the GPU poses, and
+making those joints entities is a design this program does not do (D47). A rope prop is entities all
+the way down. A character's cape is not, and never will be. §11 is where that lands.
+
+### 3.1 `Cloth`
+
+```js
+export class Cloth {
+    dynamics = new ClothDynamics();  // how it behaves — §3.3
+    blend = 1;                       // 0 = fully animated pose, 1 = fully simulated
+    layer = 1;                       // ClothCollider layer/mask filtering, RigidBody semantics
+    mask = 0xFFFFFFFF;
+    flags = ClothFlags.None;
+}
+```
+
+**The anchor is the entity the component is on**, and nothing names anything. Without a `ClothRig`
+the particle set is the entity's own transform subtree, walked through
+`TransformAttachmentSystem#findChildrenOf`/`#countChildrenOf` — the parent-to-children index the
+engine already maintains. Put `Cloth` on the top link of a rope and you get the rope; put it on a
+node with several chains under it and you get all of them in **one coupled solve**, which is what
+makes self-collision between them work.
+
+Two rules keep the walk unambiguous:
+
+- **A nested `Cloth` claims its own subtree.** The walk stops when it meets another `Cloth`, so
+  independent hanging parts of one prop partition naturally.
+- **`ClothExclude`** is a tag component that prunes a subtree from the walk, for the rig that has a
+  non-simulated attachment point in the middle of a chain.
+
+With a `ClothRig`, the entity is instead the one that owns the skinned model instance, and the
+subtree walk does not run at all — the particle set comes from the proxy's joint list (§3.2).
+
+`blend` is the escape hatch for cinematics, LOD and "turn it off for this one shot". It is a lerp
+between the animated pose and the simulated pose applied at write-back, not a solver parameter, so it
+is free and always safe. **M1 note:** writing it wakes a sleeping cloth, because sleep skips the
+write-back as well as the step (§7 P5) and a `blend` written to a sleeping cloth would otherwise take
+effect at whatever later moment something else happened to wake it.
+
+### 3.2 `ClothRig`
+
+```js
+export class ClothRig {
+    proxy = null;   // ClothProxy — shared, immutable, built at import
+    skin = 0;       // which of the instance's skins the proxy's joint indices are into
+}
+```
+
+A `ClothProxy` **object**, not a path. This is the convention the engine already uses for a component
+that points at a built, shared, immutable asset: `Collider#shape` holds an `AbstractShape3D` and is
+documented as *not* serialised because shapes are shared assets the pipeline wires up;
+`ParticleEffect` holds a `ParticleLayout` and a `ParticleProgram` the same way. `ClothRig` serialises
+the proxy's identity and the skin ordinal, and the asset pipeline resolves the rest.
+
+**The proxy addresses joints by index, never by name.** A joint is a `Node3D` inside a
+`SceneBundleInstance`, not an entity, so an `EntityReference` to one is impossible by construction —
+and reintroducing strings at runtime to work around that would be the wrong answer. Instead the
+binding is resolved **once, at import**: the builder has `SceneBundleInstance#nodes` (the by-name map
+the engine keeps because sockets and effect anchors are authored as bone names) and turns names into
+integer indices into `Skin#joints`. The runtime component holds integers.
+
+### 3.3 `ClothDynamics`
+
+The parameters live in one value object, and the library is a set of instances of it.
+
+```js
+export class ClothDynamics {
+    stretch = 0.7;      // 0..1 normalised material coordinate
+    bend = 0.2;         // 0..1
+    damping = 0.15;     // 0..1
+    slack = 0.5;        // 0..1 — how far the cloth may leave the animated pose (§3.4)
+    thickness = 0.02;   // metres — particle radius, for collision offset and self-collision
+    inertia = 1;        // 0..1 — how much of the anchor's world motion the cloth feels
+    drag = 0.1;         // 0..1 — aerodynamic coupling to the air (§10)
+    substeps = 2;       // solver budget
+    iterations = 4;     // solver budget
+    flags = 0;          // ClothDynamicsFlags.SelfCollision, ...
+}
+```
+
+The library is `ClothDynamics.SILK`, `.COTTON`, `.DENIM`, `.LEATHER`, `.ROPE`, `.CHAIN`, `.HAIR` —
+frozen instances in `cloth_dynamics_library.js`. Assign one directly and it is shared, immutable and
+free; call `.clone()` and you own a copy to edit. There is no field that silently rewrites other
+fields, and no second "advanced" block: this *is* the parameter set, and the library is a set of
+points in it that are known to be good rather than a mechanism.
+
+The stiffnesses are normalised coordinates, not moduli in N/m — log-mapped internally so that `0.7`
+means something an author can predict and `0.9` is not four orders of magnitude away from it. They are
+independent, because the library carries the good combinations and that is protection enough; nothing
+needs to be collapsed onto a single magic axis to keep an author out of trouble.
+
+**M1 wrote that mapping (`cloth_dynamics_map.js`) and neither stiffness maps to newtons per metre.**
+`stretch` maps to a *strain allowance*, because §6's measurement makes the fabric row hard and leaves
+nothing for a stiffness to be. `bend` maps to a **ratio** of the row's own `m_eff/dt²` — at the fixed
+step rather than the substep — for two reasons that are both wanted: the fabric's look becomes
+invariant to how heavy the author made the particles, which is what a normalised knob should mean; and
+since `k/(m/h²) = ratio/substeps²`, a bend row expressed that way is inside M0's dissipative band at
+*any* substep count by construction, rather than by an author staying out of trouble. A stiffness in
+N/m has neither property. The cost, stated: **bending saturates** at the top of that band, so a fabric
+stiffer than `bend = 1` cannot be expressed as a soft row that also comes to rest.
+
+`substeps` and `iterations` are budget rather than material, and they are here because a chain wants
+more of both than a bedsheet does, so they are part of what "chain" means. Raising `iterations`
+converges further toward the same answer (§5.1); raising `substeps` also reduces implicit Euler's
+numerical damping, so it does change the drape slightly. Both are ordinary fields with ordinary
+documentation, not hidden couplings.
+
+`ClothDynamics` carries `equals` and `hash` like every other value type in the engine, so a component
+holding one compares and hashes cheaply.
+
+### 3.4 Slack, and why there is no radius in metres
+
+`slack` is dimensionless. Each particle's leash radius is derived, not authored:
+
+```
+r_i = 2 · slack · d_geo,i
+```
+
+**M1 corrected the factor of two, and it is a derivation rather than a fudge.** This paragraph
+originally read `r_i = slack · d_geo,i`, which makes `slack = 1` a real and fairly tight constraint
+instead of the absence of one: a rope hanging straight down cannot swing through ninety degrees,
+because its tip has to travel `√2·d_geo` to get there and its leash is `d_geo`. The radius at which
+the row is *provably* inert is `2·d_geo` — the tether already holds every particle within `d_geo` of
+the anchor, the animated position it is leashed to is also within `d_geo` of the anchor since a chord
+is never longer than the arc it subtends, so by the triangle inequality the two are never further
+apart than that. With the factor of two in, `slack = 1` means exactly "no leash": the row cannot
+bind, so it is not built at all, and there is no sentinel and no discontinuity to code around.
+`MEASUREMENTS.md` §10.
+
+where `d_geo,i` is the particle's baked geodesic distance to the fixed set. At `slack = 0` every
+particle is welded to its animated position; at `slack = 1` a particle may be anywhere within its own
+reach of that position. Three things fall out of that and none of them need a knob:
+
+- **The profile is automatic.** A hem gets a long leash and a waistband gets a short one, because
+  that is what their geodesic depth says, not because someone painted it.
+- **The fixed set falls out too.** A pinned particle has `d_geo = 0`, so `r_i = 0`, so the leash *is*
+  the pin. There is no separate attach constraint — one row covers both (§6).
+- **There is no magic default.** The old formulation had a radius in metres with `0` meaning "derive
+  it from the mesh extent", which is the kind of overloaded sentinel that gets copied into a save file
+  and then means the wrong thing.
+
+Slack is not a stretch allowance and does not govern inextensibility — the tether row does that, and
+the two are different questions (§6). Slack asks how loosely the cloth is leashed to the animation;
+the tether asks how far the fabric may extend from its anchor. A cape wants both: a moderate leash so
+it follows the character, and a hard tether so it never becomes rubber.
+
+### 3.5 `ClothCollider`
+
+```js
+export class ClothCollider {
+    inflation = 0;       // extra thickness in metres, on top of ClothDynamics#thickness
+    friction_scale = 1;  // multiplies the entity's Collider#friction
+    layer = 1;           // RigidBody semantics, and see below
+    mask = 0xFFFFFFFF;
+    flags = 0;           // ClothColliderFlags.Static
+}
+```
+
+Everything else is read from components the entity already has: geometry and friction from
+`Collider`, pose from `Transform64`.
+
+**M2 added the layer and the mask, because this paragraph originally said "layer filtering from the
+`Cloth` side" and that is not a thing that can happen.** `Cloth#mask` is a mask *of collider layers*,
+and §3.5 is also the paragraph that says a `ClothCollider` does not require a `RigidBody` — so there
+is nowhere else in the tuple for a collider's layer to live. The pair is here with `RigidBody`'s own
+semantics, symmetric: a cloth and a collider interact when each is in the other's mask.
+
+**A `ClothCollider` does not require a `RigidBody`.** This is a deliberate divergence from
+`FluidObstacle`, which does require one because it needs a wall velocity. Cloth's colliders are
+overwhelmingly character bones — ordinary entities in a `TransformAttachment` hierarchy — and forcing
+each of them to become a physics body to be seen by cloth would be a tax on the common case. Collider
+velocity is derived from the pose delta between fixed steps, which the system caches anyway for swept
+collision (§8.2). World props that *do* carry a `RigidBody` add a `ClothCollider` the same way and land
+in the same index; the two cases are not distinguished.
+
+---
+
+## 4. Components and systems
+
+```
+engine/physics/cloth/
+  ecs/
+    Cloth.js                        component: the simulated thing; anchor is its own entity
+    ClothFlags.js                   TeleportKeep, NeverSleep
+    ClothExclude.js                 tag: prune a subtree from the walk
+    ClothRig.js                     component: particles are a skinned model instance's joints
+    ClothDynamics.js                value object: how it behaves
+    ClothDynamicsFlags.js           SelfCollision, StrainLimit
+    cloth_dynamics_library.js       SILK, COTTON, DENIM, LEATHER, ROPE, CHAIN, HAIR — frozen instances
+    cloth_dynamics_map.js           normalised coordinates → row parameters; every constant measured
+    ClothCollider.js                component: the RigidBody-analogue for collision
+    ClothColliderFlags.js
+    ClothSystem.js                  main-thread system: gather, step, write back
+    ClothInstance.js                one live cloth: the binding between a subtree and a ClothState
+    cloth_seed_subtree.js           §11.1's walk: entities → node_parent + animated_position
+    cloth_seed_rig.js               §11.2's proxy: joints → node_parent + animated_position
+    cloth_build_rows.js             everything after that, shared by both seeders
+    cloth_reconstruct_pose.js       particles → a pose, shared by both write-backs
+    cloth_write_back.js             that pose → Transform64 + TransformAttachment
+    cloth_write_back_rig.js         that pose → Node3D.transform_local
+    cloth_gather_colliders.js       the index's overlapping records, in the cloth's own frame
+    WorkerClothSystem.js            drop-in worker variant (WorkerSystem subclass)
+    ClothWorkerCore.js
+    cloth.worker.js
+    makeClothWorker.js
+    cloth_worker_protocol.js
+    ClothSerializationAdapter.js
+    ClothRigSerializationAdapter.js
+    ClothColliderSerializationAdapter.js
+  collider/
+    ClothColliderIndex.js           the index of live cloth colliders + their swept AABBs
+    ClothColliderRecord.js          the packed layout: kind, params, both poses, bounds, interpolated pose
+    ClothColliderKind.js            sphere, capsule, box, cylinder, plane
+    cloth_collider_pack.js          AbstractShape3D → packed record
+    cloth_collider_bounds.js        the swept AABB, shared by the index and each cloth's own table
+    cloth_collider_sdf.js           pose interpolation, localisation, and the field dispatch
+  solver/
+    ClothState.js                   SoA particle + topology + constraint storage over one buffer
+    cloth_step.js                   the fixed step: predict, warm start, iterate, dual update, integrate
+    cloth_solve_vertex.js           the per-vertex 3x3 block update
+    constraint/                     one module per row type (§6)
+    cloth_color_particles.js        graph colouring of the particle graph
+    constraint/cloth_leash_row.js   §6's slack row and its tether row, which are one row model
+  build/
+    ClothProxy.js                   the built artefact
+    cloth_proxy_from_joints.js      §11.3 steps 5–8, for a garment that is already rigged
+    cloth_proxy_build.js            unrigged: source mesh → proxy (weld, simplify, extract, validate)
+    cloth_proxy_bind.js             unrigged: render mesh → proxy binding weights
+  ClothDiagnostics.js               dev-build tripwires
+```
+
+Two systems:
+
+- **`ClothColliderSystem`** observes `(Collider, Transform64, ClothCollider)` and maintains a
+  `ClothColliderIndex` — a flat array of packed records plus swept world AABBs. This is the same shape
+  as `AcousticOccluderIndex`/`OccluderBody` in the sound simulation, and for the same reason: the
+  consumers need a compact, pose-cached, broadphase-able view of a set of colliders that is not the
+  physics BVH. It cannot be the physics BVH, because `ColliderObserverSystem` deliberately skips
+  colliders with no owning body, and bone colliders have no body.
+
+  **M2 note: it has no `fixedUpdate`, and that is §4.1 applied a second time.** The index has to be
+  refreshed from the world's transforms *before* any cloth reads it, and the scheduler cannot express
+  that for exactly the reason §4.1 gives — a score is a sum over what a system references, so a system
+  can only be moved earlier by touching more, and `ClothSystem` (which reads and writes `Transform64`
+  and `TransformAttachment`) outscores one that only reads. So the answer is not a third mechanism, it
+  is one call site: `ClothSystem#fixedUpdate` calls `refresh()` at the top of its own step, before any
+  cloth is advanced. The collider poses are then read at exactly the moment the anchor poses are, which
+  is what makes a contact consistent rather than merely fresh. With no `ClothSystem` in the manager the
+  index is never refreshed, and nothing reads it either.
+
+  **And the index is a linear scan rather than a BVH**, which is a divergence from
+  `AcousticOccluderIndex` with two reasons. The query is one AABB per cloth per step against a set that
+  is a character's bones — a `ClothCollider` is an opt-in marker, not every collider in the scene — and
+  a tree over twenty leaves that all move every frame costs more to keep than to skip. And a
+  `PlaneShape3D` has an **unbounded** AABB, which a BVH cannot hold: every refit would grow the root to
+  infinity. If a scene ever wants thousands of cloth colliders, the shape of the fix is a BVH over the
+  bounded ones with the planes in a short list beside it.
+
+- **`ClothSystem`** owns the simulation. Per fixed step: refresh the animated targets, gather the
+  overlapping colliders from the index, step, write back.
+
+Cloth runs at the fixed rate and is interpolated for display, exactly as `PhysicsSystem` does — the
+same producer/`__interp_restore` contract, so a cloth-driven `Transform64` is authoritative during the
+fixed pass and interpolated outside it. Reusing the existing contract rather than inventing a second
+one is what keeps a cloth-driven bone from fighting an animation-driven one.
+
+### 4.1 Ordering, and why the answer is not to be ordered
+
+Cloth wants to read the skeleton *after* animation has posed it for this step and *before* anything
+renders. The engine has exactly two ways to order systems: **registration order**, and what each
+system declares in `components_used`, from which writers are sorted before readers. There is
+deliberately no `runs_before`/`runs_after`, because naming other systems is the coupling that design
+exists to avoid.
+
+**Cloth both reads and writes `Transform64`**, which puts it on both sides of that component's own
+rule, and M1 established that neither mechanism can express the relation — for a structural reason
+rather than an arithmetic one. `updateExecutionOrder` scores a system as a **sum** over the components
+it references and sorts descending, so a score can only be *raised* by touching more components or
+touching them at a higher access level. The only way to sort **later** is therefore to touch strictly
+less than the system you have to follow, and a consumer of a posed hierarchy touches strictly more.
+Registration order cannot rescue it either: ties break by registration, and this is not a tie —
+`ClothSystem` outscores `TransformAttachmentSystem` and any plausible poser outright, registered first
+or last.
+
+**So the answer is not a third mechanism. The answer is that cloth must not care.** An earlier draft
+of M1 added an execution-phase number to `System`, which put the words "pose" and "animation" into a
+layer of the engine that has no such vocabulary, and bought an ordering the design should not have
+needed. What M1 ships instead is a write-back that is **idempotent under recomposition**: cloth writes
+each node's local `TransformAttachment#transform` alongside its world `Transform64`, so a hierarchy
+recomposition — which is what happens whenever anything announces on the anchor — reproduces the
+simulated pose instead of replacing it with the authored one. Measured at **1.7e-15 m** across a
+16-link rope (`MEASUREMENTS.md` §15). With that, where cloth runs is a **quality** question.
+
+And a small one. Running before the poser means reading last step's anchor pose, so the cloth's
+*shape* is one fixed step stale; its *position* is not, because the attachment cascade carries the
+whole subtree rigidly with the anchor from cloth's own local transforms. Measured on a 1.6 m rope: a
+few centimetres under ordinary motion, up to a fifth of its own length at the sharpest velocity
+reversal of a ±9 m/s square wave, and **not accumulating** — the same figure after fifteen seconds as
+after two, because the leash and the tether bound the reachable set. `ClothSystem.spec.js` asserts the
+idempotency, records the order the scheduler actually produces, and bounds that divergence.
+
+What the declaration *does* buy is the half of the ordering that is real: cloth writes
+`TransformAttachment#transform` and `TransformAttachmentSystem` reads it, so writer-before-reader puts
+cloth first and the attachment system publishes its result. That falls out of `components_used` with
+nothing else asked for.
+
+**`InverseKinematicsSystem` is the same shape and reaches the same conclusion.** It reads world
+`Transform64`s "the hierarchy has already composed" and writes local ones back — which is exactly the
+arrangement above, and exactly why it is not fragile in the way its scoring suggests.
+
+---
+
+## 5. The solver
+
+**Augmented Vertex Block Descent** (Giles, Diaz & Yuksel, SIGGRAPH 2025) — VBD's per-vertex
+Gauss-Seidel block coordinate descent on the implicit-Euler variational energy, with an augmented
+Lagrangian in place of pure penalties.
+
+### 5.1 Why this, and not XPBD
+
+XPBD with small substeps is the incumbent: MagicaCloth2, Chaos Cloth, Blender, most of the field.
+It works. Three properties push past it, and each maps onto a stated requirement:
+
+- **Unconditional stability at any iteration count.** Every per-vertex update is a descent step on an
+  energy that is bounded below, so the update can be truncated at one iteration and the simulation is
+  still stable — just softer. That turns requirement 1 into a property of the update rule rather than
+  a property of tuning. XPBD is stable in practice, but its stability is a function of substep size
+  and stiffness; ours is not.
+- **Parameters that keep their meaning.** AVBD targets the implicit-Euler solution, so a stiffness is
+  a material modulus and adding iterations moves the result *toward* the same answer rather than
+  changing which answer it is. Under XPBD, apparent stiffness and apparent damping both move when the
+  iteration budget moves, which is why cloth packages ship dozens of interacting sliders and
+  per-parameter animation curves to compensate. §3.3's small, independent parameter set is only
+  honest on a solver whose knobs are orthogonal to its budget.
+
+  This is iteration-count insensitivity, not substep insensitivity. Implicit Euler is numerically
+  damped by an amount that depends on `h`, so more substeps still means less artificial damping and
+  a livelier drape — which is why `substeps` is a documented field rather than a hidden constant.
+- **Hard constraints without stiff penalties.** The augmented Lagrangian reaches effectively infinite
+  stiffness through an accumulating multiplier rather than a large `k`, so pins, tethers and slack
+  bounds are *hard* — enforced to convergence — while cloth stays soft, in the same sweep, without
+  the conditioning disaster a 10⁸ penalty would cause. VBD alone cannot do this; it is exactly the
+  limitation AVBD was written to fix.
+
+Two smaller wins. Colouring the *particle* graph needs far fewer colours than colouring the
+*constraint* graph — the VBD paper reports 8 colours for a 3,891-vertex tetrahedral mesh against 76
+for its 14,802 tetrahedra — which matters for a future GPU port and for cache behaviour now. And the
+per-vertex form is a natural fit for SoA typed arrays, which is what a worker needs anyway.
+
+The cost is honest: more arithmetic per vertex than an XPBD projection, and a shorter track record
+for cloth specifically. §18 carries both as risks with a measurement plan.
+
+### 5.2 The step
+
+Per substep, with `h` the substep length, `m_i` particle mass, `y_i` the inertial target:
+
+```
+predict      y_i  = x_i + h·v_i + h²·a_ext,i
+             x_i ← x_i + h·v_i + h²·ã_i          (adaptive initialisation)
+
+warm start   for each HARD constraint c:               (soft rows: k_c = stiffness, λ_c = 0)
+               λ_c ← λ_c · α · γ
+               k_c ← clamp(k_c · γ, k_min·s_c, k_max·s_c)     s_c = the row's own m_eff/h²
+
+iterate      repeat `iterations` times:
+               for each colour:                   (parallel within a colour)
+                 for each particle i in colour:
+                   f = -(m_i/h²)(x_i - y_i)
+                   H =  (m_i/h²)·I
+                   for each constraint c on i:
+                     C  = C_c(x);  g = ∂C_c/∂x_i
+                     fu = k_c·C + λ_c
+                     fc = clamp(fu, fmin_c, fmax_c)
+                     f -= fc·g
+                     if fc > 0:                   (row in tension)
+                       H += (fc/L)·(I − g gᵀ)     (geometric stiffness, PSD part)
+                     if fc == fu:                 (row active — not at a clamp)
+                       H += k_c·(g gᵀ)
+                   x_i += H⁻¹·f                   (3×3 LDLᵀ, capped at the shortest incident row)
+
+               dual update, for each HARD constraint c:
+                 λ_c ← clamp(k_c·C_c + λ_c, fmin_c, fmax_c)
+                 k_c ← min(k_c + β·|C_c|, k_max·s_c)
+
+integrate    v_i = (x_i - x_i^prev)/h
+```
+
+The Hessian contribution is gated on the row being *active*. A clamped row's force is constant with
+respect to position, so its true second derivative is zero; adding `k·ggᵀ` anyway would make an
+inactive unilateral constraint resist motion it should not touch. It contributes its (constant) force
+to `f` and nothing to `H`.
+
+`α ∈ [0,1]` regularises the multiplier carried between steps, `γ ∈ [0,1)` decays warm-started duals so
+a resting configuration bleeds off accumulated force instead of ringing, and `β` is the penalty ramp.
+These are solver internals, global, and deliberately **not** on `ClothDynamics` — they are not a
+property of a fabric. The reference 2D implementation's defaults are a rigid-body tuning and will not
+transfer; §17 M0 makes picking cloth values a measured step with its own spec, not a copied constant.
+
+**M0 measured them, and four things about this pseudocode were wrong.** The sweep and its full grids
+are in `MEASUREMENTS.md`; the corrections are folded into the listing above and are, in short:
+
+1. **The five constants only govern *hard* rows.** A row whose material stiffness is finite is
+   representable as a plain penalty, and a plain penalty at the material stiffness *is* the material
+   law — there is nothing for a multiplier to add. Carrying one anyway drives `C` to zero and makes
+   every fabric inextensible regardless of what it was authored as: a 1 kN/m spring measured 100×
+   stiffer than Hooke. So a soft row is a pure penalty at its material stiffness and reads dead flat
+   against all five constants, which is what makes them honest as global internals. A row is **hard**
+   exactly when its stiffness is `Infinity` — §6's table already says `hard` in that column, and this
+   makes it literal rather than a threshold.
+2. **`k_min` and `k_max` are ratios of `m/h²`, not stiffnesses in N/m.** Held at a fixed multiple of
+   the row's own inertial scale, a 20-link hard chain produced the same residual column across five
+   decades of particle mass; held at a fixed stiffness it produced a different answer for every mass.
+   This paragraph's own reasoning already names `k_max/(m/h²)` as the quantity that matters — it just
+   stopped one step short of making the ratio the parameter.
+3. **`α` and `γ` act only through their product, and `α·γ ≥ 0.5` diverges.** At `α·γ ≤ 0.3` a 20-link
+   hard chain settles to rest with kinetic energy at 1e-9 J; at 0.5 it jitters; at 0.6 it detonates.
+   Residual improves monotonically towards that cliff, so the value is a margin decision:
+   **α·γ = 0.25**, a factor of two clear.
+4. **`β` could not be chosen from M0 data.** Above about 1e4 every M0 scenario gives an identical
+   answer, and with `k_min = k_max` — which measured as good as any ramp for M0's persistent rows —
+   it has no effect at all. The ramp exists for **transient** rows, a contact that should arrive soft
+   rather than shock the mesh on its first frame, and M0 has none. M2 has to measure it.
+
+Chosen: **α = 0.25, γ = 1, β = 1e5 (unexercised), k_min = k_max = 8·(m/h²)**. γ sits at 1 because its
+second job — decaying the penalty — has nothing to do while the band is a single point, so the whole
+decay lives in α, whose only job is the multiplier. When M2's contacts make the band real, γ becomes
+live and has to be re-measured.
+
+**Adaptive initialisation** is VBD's: seed the iteration at `x + h·v + h²·ã` where `ã` interpolates
+between zero and full external acceleration according to whether the previous step looked like free
+fall or like resting contact. Without it, a low iteration count over-stretches under gravity on the
+first iteration and the tethers spend the rest of the budget pulling it back.
+
+**Chebyshev acceleration** (`ω₁ = 1`, `ω₂ = 2/(2−ρ²)`, `ωₙ = 4/(4−ρ²ωₙ₋₁)`) is **not here**. M2
+built it as specified — including the gate the VBD paper requires, disabled for any particle in
+contact this step, since accelerating a vertex whose constraint set just changed is where the method's
+stability argument stops applying — and measured it against the first contacts the system has.
+
+It lost on every axis. On a sheet landing at 3 m/s it left the penetration inside the run-to-run
+spread and made the settled kinetic energy 1.5× worse; on a hanging cape it traded a third off the
+penetration for ten times the residual energy, which is a livelier cloth rather than a
+better-converged one; it costs 2–5%; and past `ρ = 0.9` it diverges, with `ρ = 0.99` reaching a
+non-positive-definite Hessian inside a second. A mechanism that costs, does not help, and detonates at
+the top of its own range is worse than its absence. `MEASUREMENTS.md` §21 keeps the grid so a future
+attempt starts from the numbers.
+
+### 5.3 Why the update never explodes
+
+`H = (m/h²)·I + Σ_tension (fc/L)·(I − g gᵀ) + Σ_active k_c·(g gᵀ)`. The mass term is positive
+definite; every `k_c·g gᵀ` is a positive semidefinite rank-one term; every `(fc/L)·(I − g gᵀ)` with
+`fc > 0` is positive semidefinite too. So `H` is symmetric positive definite by construction — for any
+topology, any parameter values, any degenerate configuration, and regardless of how many rows are
+clamped out. `H⁻¹f` is always a descent direction.
+
+**Three things M0 measured changed this paragraph.** They are corrections to the mechanism, not to the
+goal; the full evidence is in `MEASUREMENTS.md`.
+
+**The geometric-stiffness term is kept where it is positive semidefinite, not dropped wholesale.**
+For a distance row `∂²C/∂x² = (I − g gᵀ)/L`, which is PSD exactly when the row is in tension, so
+`max(fc, 0)·∂²C/∂x²` can be added without touching the SPD argument — every term in `H` is still PSD
+on top of a PD mass term, and there is still no threshold. Dropping it *all* was measured to make the
+update overshoot sideways whenever `fc/L` passes `m/h²`, raising the vertex energy by 20% at a ratio
+of 4 and by a factor of 40 at a ratio of 7e4. This is not "adding the indefinite term back": the
+negative-semidefinite half, where the row is in compression, is still dropped, and dropping it there
+is conservative rather than dangerous. Note the term is added whether or not the row is at a clamp —
+a saturated row applies a constant-magnitude force that still swings as the row rotates.
+
+**The 3×3 solve is an LDLᵀ factorisation, not a cofactor inverse.** They agree in exact arithmetic
+and do not agree in `Float64`. A vertex carrying one very stiff row against a small mass term
+assembles an `H` with a condition number in the billions, and the cofactor determinant — a sum of
+triple products that has to cancel by that ratio squared — comes out **negative** on a matrix whose
+eigenvalues are all positive (measured: eigenvalues 0.12, 0.12, 5.4e8; determinant −4.8e8 against a
+true 7.75e6). The factorisation never forms those products; its pivots stayed positive throughout the
+fuzz, and their product is the determinant to full precision. The dev-build assertion checks the
+pivots, which *is* the positive-definiteness claim rather than a proxy for it.
+
+**Positive definiteness gives a descent direction, not a monotone step.** `Δ = H⁻¹f` satisfies
+`f·Δ > 0`, so the energy falls for a small enough step — and the update takes a full step of 1. Where
+the quadratic model stops resembling the energy, a full step overshoots and climbs: measured falling
+monotonically out to `t ≈ 0.001` of one step and then rising to 40× the starting energy at `t = 1`.
+The step is therefore capped at the **shortest row incident on the particle** — the distance over
+which "the direction to a neighbour" means anything, which is the mesh's own geometry rather than a
+tuned constant, and which never binds for cloth in ordinary motion. With all three corrections in,
+full-step energy increases on a realistic cape are 0.004% of updates and never exceed a fifth of the
+local energy scale; across deliberately absurd cloth they are 1.5% and never exceed 1.0. §7 P1 states
+the gate that follows from this.
+
+A dev-build tripwire mirrors `find_non_finite_physics_state.js`: a post-step sweep for non-finite
+particle state that names the first offender. It sits behind `assert.*` so it compiles out of consumer
+bundles — the engine ships raw source, and a check moved out of `assert.*` stops being strippable.
+
+### 5.4 Colouring
+
+The particle graph is coloured so no constraint touches two particles of the same colour, using the
+existing `core/graph/coloring/colorizeGraphGreedy.js` and checked by the existing
+`validateGraphColoring.js`. Bending stencils span four particles, so the graph is the mesh graph plus
+the bend diagonals — around 8–10 colours for typical garment topology. Colouring runs once, on a
+`Graph` object, and is baked into the `ClothProxy` as colour ranges over a permuted particle order;
+for a chain it runs at link time on a graph of a few dozen nodes. Nothing colours per step and the
+runtime never sees a graph object.
+
+Self-collision rows appear and vanish per step and cannot be pre-coloured. They are accumulated into
+a per-particle scratch buffer and applied Jacobi-style within the sweep — the same mixed
+Gauss-Seidel/Jacobi treatment VBD uses for dynamic collisions.
+
+**M2 found that a *collider* contact needs none of that.** A contact against a collider is **unary**:
+one particle against a surface that is fixed for the substep. It couples no two particles, so there is
+no Gauss-Seidel versus Jacobi distinction to make and nothing to keep out of the colouring — it
+accumulates in the vertex update exactly like a leash row. What is true of a contact is that it *comes
+and goes*, which is a storage problem rather than an ordering one: M2's answer is a fixed four slots
+per particle inside `ClothState`'s own buffer, rebuilt each step and keyed on the collider's index
+handle so a multiplier survives the rebuild. Determinism comes from the *set* being built by one pass
+in a fixed order over a fixed table. The paragraph above stands unchanged for M4's rows, which really
+are pairs. `MEASUREMENTS.md` §18.
+
+---
+
+## 6. Everything is one constraint row
+
+Every feature in this system is a row in one table. A row is `(C(x), f_min, f_max, stiffness)`, and
+the solver in §5.2 knows nothing else about it.
+
+| Row | `C(x)` | `f_min` | `f_max` | Stiffness | Gives you |
+|---|---|---|---|---|---|
+| Stretch | `‖x_i − x_j‖ − L₀` | −∞ | +∞ | `k_stretch` | fabric that resists stretching |
+| Bend | quadratic stencil `Σ w_k·x_k` | −∞ | +∞ | `k_bend` | fabric that resists folding |
+| Slack | `‖x_i − s_i‖ − 2·slack·d_geo,i` | 0 | +∞ | hard | follows the animation; pins at `d_geo = 0` |
+| Tether (LRA) | `‖x_i − p_anchor‖ − d_geo,i` | 0 | +∞ | hard | no rubber-band stretch |
+| Backstop | `r_b − (x_i − b_i)·n_i` | 0 | +∞ | hard | never inside the body |
+| Collision | `(r_i + infl) − sdf_c(x_i)` | 0 | +∞ | hard | colliders push cloth |
+| Friction | tangential slip magnitude | 0 | `+μ·f_n` | hard | cloth grips |
+| Self-collision | `‖x_i − x_j‖ − (r_i + r_j)` | −∞ | 0 | `k_self` | cloth doesn't pass through itself |
+| Strain limit | `‖x_i − x_j‖ − L_max` | 0 | +∞ | hard | hard cap on elongation |
+
+Unilateral rows fall out of the clamp: **`[0, +∞)` admits only forces that reduce `C`, `(−∞, 0]` only
+forces that increase it**, and `(−∞, +∞)` is bilateral.
+
+**M1 corrected three of those clamps and the sentence above them.** An earlier draft glossed the rule
+as "`[0, +∞)` is push-only, `(−∞, 0]` is pull-only", which is true only relative to a particular sign
+of `C` — the collision row writes `C` as `r − sdf` and the distance rows write it as `‖·‖ − r`, so the
+same clamp means opposite things on them. Following the gloss rather than the rule gave Slack, Tether
+and Strain limit `(−∞, 0]`, which under the solver's own `f -= fc·g` is the force that pushes a
+distance row *apart*. Such a row does not bind weakly; it never binds at all, and it would drive a
+particle away from the leash centre it is supposed to hold it near. `cloth_leash_row.spec.js`
+demonstrates it directly and `MEASUREMENTS.md` §10 carries the derivation. **A row is hard exactly when its stiffness is `Infinity`** — the word in the table above,
+made literal. A hard row's penalty lives in `[k_min, k_max]·(m/h²)` and its multiplier carries the
+load; a soft row is a pure penalty at its material stiffness and carries no multiplier at all. M0
+measured why it has to be one or the other rather than a sliding scale (§5.2), and measured what the
+multiplier actually buys: not a smaller residual — at a fixed budget a stiff penalty is comparable —
+but **settling**. A hard 20-link chain comes to rest with 1e-14 J of kinetic energy where the same
+chain on a penalty of any stiffness sits in a limit cycle at 1e-4 J. That is §7 P5, and it is the
+augmented Lagrangian's real return.
+
+`C` for a bending row is a **vector** — the discrete mean-curvature vector — so that row carries three
+multipliers against one penalty, and its clamps are absent because a bending moment has no sign to be
+one-sided about. Every other row in the table is scalar.
+
+**M2 corrected the last two rows of that table, and both corrections come from rules the table already
+states.** The collision and friction rows carried named stiffnesses `k_contact` and `k_friction`, and
+by M0's own rule — a row is hard exactly when its stiffness is `Infinity` — that made both of them
+soft penalties. A soft row's entire force is `k·C` with `k` capped at `8·(m/h²)`, which is **4.6 N at
+one full thickness of penetration**; the hard row measured producing 11 N for a sheet arriving at
+1 m/s and 376 N at 8 m/s. A soft contact holds a draped garment and fails every time one is put down.
+Both rows are hard.
+
+And friction's clamps were `±μ·f_n`, which is the *signed-slip* formulation — a row whose `C` is a
+displacement along a chosen tangent. This row's `C` is the **magnitude** of the slip in the contact's
+tangent plane, so `C ≥ 0` always and the negative half of that clamp names a force pulling the
+particle further from where it stuck. `[0, μ·f_n]` is the same physics, and writing it as a magnitude
+is what removes the tangent basis: a signed row needs two per contact, and any choice continuous frame
+to frame carries state, which is exactly what §7 P4(a) exists to keep out. Measured against Coulomb:
+the stick/slide transition sits on `tan θ` at 10°, 20°, 30°, 40° and 50°. `MEASUREMENTS.md` §18.
+
+**There is no separate attach row.** A pinned particle is a slack row with `d_geo = 0`: the constraint
+becomes `‖x_i − s_i‖ ≤ 0` under a pull-only clamp, which welds it. One row, one code path, and the
+distinction between "pinned" and "loosely following" is a number rather than a branch. (The gradient of
+`‖x − s‖` is undefined at `x = s`; the row is skipped below an epsilon, which is the standard guard and
+is also exactly when it has nothing to do.)
+
+**Slack and tether are different questions, and a cape needs both.** Slack bounds distance to the
+particle's *animated position*; the tether bounds distance to the *anchor*. Slack alone implies a
+tether bound of `(1 + slack)·d_geo` — enough to stop a catastrophe, not enough to stop visible rubber —
+and for a garment with no meaningful animated pose to follow (a flag, a curtain, where `slack` is near
+1 by necessity) the tether is doing all the inextensibility work on its own.
+
+This mirrors the doctrine already written into `physics/constraint/solve_constraints.js`, whose
+6-DOF joints are "one row model, parameterised by mode", with LOCKED and LIMITED differing only in
+bias and clamp. Same idea, position level instead of velocity level. A reader who knows one knows the
+other, and a new cloth feature is a new row rather than a new pass.
+
+Two rows deserve a note.
+
+**Bend is the quadratic model**, not a dihedral angle. Its Hessian is constant for a fixed rest shape,
+so the stencil weights are precomputed at build time, `C` is linear in `x`, and `g` is a constant read
+from the proxy — bending costs almost nothing per iteration, and M0 measured it at an eighth of a
+stretch row per visit despite touching twice as many particles. The weights annihilate the rest shape
+and every affine image of it, which is every in-plane deformation to first order; they do *not*
+annihilate an arbitrary planar configuration, and that is the precise content of the near-isometric
+assumption below. More importantly, it has **no singularity
+at 0° or 180°**. Dihedral bending needs a normal, an angle and a sign, all of which degenerate when two
+triangles become coplanar or invert, and that degeneracy is a classic source of exactly the twitching
+this design exists to eliminate. The cost is that the quadratic model assumes a near-flat rest shape
+and near-isometric deformation; a garment with a strongly curved rest shape it wants to hold will
+under-resist. §18 carries that.
+
+**Stretch is per-edge.** Edge springs on a triangle mesh do not resist shear on their own; the bend
+rows and the slack bound between them keep the mesh from collapsing in practice, and a triangle-area
+row is available for the cases where they do not. Full in-plane anisotropy is a non-goal (§2).
+
+**A chain bends through a skip row, not through the quadratic stencil.** M1 found there is nothing to
+build a hinge on: the stencil is a discrete mean curvature over a *surface*, four particles across the
+diamond either side of a shared edge, and a rope has no diamond — `bt_edge_read_diamond` declines a
+wire edge for exactly that reason and is right to. What a chain gets instead is an ordinary stretch
+row between a node and its **grandparent**, at whatever distance the authored pose puts them. That is
+this section's own doctrine applied once more, it costs no new row kind, and it keeps both properties
+the quadratic model was chosen for: no normal, no angle and no sign, so nothing degenerates at 0° or
+180°, and a fold is high energy rather than a singular configuration. It also does something the
+quadratic stencil explicitly cannot (§18) — because its rest length is read from the authored pose
+rather than assumed flat, **it holds a curved rest shape**. `MEASUREMENTS.md` §9.
+
+**And a stretch row has to be hard, which this table's `k_stretch` does not say.** M0 measured that a
+*penalty* stiffer than about `8·(m/h²)` makes the step add energy rather than dissipate it — the cloth
+sustains a limit cycle forever, and raising the iteration count shrinks it without removing it. For a
+half-gram particle at 60 Hz × 2 substeps that boundary sits near 60 N/m, which is a rubber band rather
+than a fabric, so every stiffness an author would reach for is on the wrong side of it. The augmented
+Lagrangian is therefore not a refinement over a stiff penalty for this row: it is the only formulation
+of it that comes to rest, because its penalty is capped at the top of the dissipative band and the
+multiplier carries the rest. M1's normalised `ClothDynamics#stretch` should map to `Infinity` with a
+strain-limit row governing extension, not to a large finite `k`. `MEASUREMENTS.md` §6.
+
+**M1 built that and measured what the strain-limit row is actually worth, and the answer is "a
+third".** It removes 34–38% of the peak over-stretch, consistently, at every budget — and it **never
+reaches its own allowance**: at `stretch = 1` it asks for 0.1% of strain and delivers 5.9% at one
+iteration per substep, 2.2% at 2×2 and 0.9% at 2×4. The reason is structural. A strain-limit row is a
+*second hard row on the same edge with the same gradient*, so it competes for the same trust region
+and the same penalty band as the fabric row it is backing up; it can add force in a direction force is
+already being added in, and nothing more. Below about `stretch = 0.35` its allowance is looser than
+what the fabric row does unaided and it is simply inert.
+
+So **`stretch` is the weakest field in §3.3's parameter set**, and the honest statement is that at low
+budgets the bound belongs to the budget rather than to the fabric. The row is worth its 13–15% of a
+garment frame where the residual is visible and is not worth it where the residual is already around
+one per cent, which is why it is a flag — `ClothDynamicsFlags.StrainLimit` — rather than always on,
+and why the library entries at 2×4 clear it. `MEASUREMENTS.md` §11.
+
+---
+
+## 7. Pathology budget
+
+The requirement was cloth that does not fold up, get stuck, or spaz out. Each failure mode below gets
+a named mechanism and a spec that fails without it. This table is the acceptance criterion for the
+whole system, and every row's spec is a standing gate, not a one-off.
+
+**P1 — Blow-up, NaN, unbounded velocity.**
+*Mechanism:* SPD Hessian by construction (§5.3), so every update is a descent direction; the step
+capped at the shortest incident row so a full Newton step cannot leave the region its model describes;
+a per-particle velocity clamp; the `assert.*` non-finite tripwire.
+
+**M1 landed the clamp and it is not derived from `thickness`.** This row asked for one "derived from
+`thickness` and `h`", and `thickness` turns out to be the wrong length scale: it is a *contact*
+radius, so a clamp built from it is a **tunnelling** bound, and a tunnelling bound sits below ordinary
+cloth speeds rather than above them. Silk is 4 mm thick, so "a particle may not cross its own radius
+in a step" is 0.24 m/s at 60 Hz — against the 29 m/s the same silk reaches behind a sprinting anchor.
+Any multiple large enough to stop the clamp being a *behaviour* for silk is large enough to be
+meaningless for leather, whose thickness is five times silk's and whose speeds are not.
+
+The scale that works is the solver's own **correction authority**,
+`shortest_row · substeps · iterations / dt` — the trust region caps a vertex update at the shortest
+row incident on the particle, so that product is the whole of what one fixed step can undo. M1
+measured a cloth losing its bounds past it (§7 P2 below), and the clamp is four times it: a bound on
+the solver being asked to do more than it can, scaling with the mesh and the budget rather than with a
+radius nothing reads until M2. The smallest headroom over it in the library is 5.7×. M2 still needs
+the tunnelling bound — it is a different number for a different job and it arrives with the contacts.
+`MEASUREMENTS.md` §13.
+*Spec:* fuzz over random topologies and random `ClothDynamics` values including absurd ones, 10,000
+steps, assert every particle finite. **M0 corrected the second half of this.** "The per-vertex energy
+never increases across an update" does not follow from an SPD Hessian and is not true — SPD buys a
+descent direction, and the update takes a full step (§5.3). What is asserted instead, and holds:
+every LDLᵀ pivot positive on every update (which *is* positive definiteness, checked where it is
+used); nothing non-finite across 10,000 steps of absurd cloth; and full-step energy increases bounded
+and rare — 0.004% of updates on a realistic cape, never above a fifth of the local energy scale, and
+1.5% / 1.0 across the absurd fuzz. Those measured figures are the thresholds the standing gate holds
+the solver to, so a change that makes it worse fails.
+
+**P2 — Over-stretch, the rubber cape.**
+*Mechanism:* long-range attachments (Kim et al. 2012). Each particle carries the geodesic distance to
+its nearest fixed particle, baked once, enforced as a hard unilateral row. Because it is hard rather
+than a penalty, one iteration enforces it almost exactly — this is the row that makes low iteration
+counts viable.
+*Spec:* a 30-link × 3-strand rig at one iteration per substep, dropped through ninety degrees; assert
+`max‖x − p_anchor‖ ≤ d_geo·(1+ε)` for every particle across 600 steps, and assert the same rig without
+the rows does not hold.
+*Measured, M1:* **1.0155 with the tether against 1.4650 without**, at 1×1. Four times the budget takes
+the untethered rig to 1.0199, which is still worse than one iteration *with* tethers — so the tether
+is not a cheaper way to buy convergence, it answers a question the per-edge rows cannot.
+
+*Limit, stated, and M1 found it:* **the bound is conditional on the solver's correction authority.**
+The trust region caps a vertex update at the shortest row incident on the particle (§5.3), so one
+fixed step can move a particle at most `shortest_row · substeps · iterations`, and a displacement
+larger than that is not one the tether has been given a chance to answer for. Measured: a 30-link
+chain kicked at 16 m/s against 3.0 m/s of authority reaches **6.9× its own reach**, and the same kick
+against 24 m/s of authority reaches 1.06×. Both recover — the excursion is transient, which is P4(c)
+holding — but "no particle is ever further from the anchor than `d_geo`" is true only while the
+velocity clamp of P1 keeps a particle inside what the solve can undo, and that is the reason the clamp
+is built out of the same quantity. `MEASUREMENTS.md` §10.
+
+**P3 — Tunnelling through the character.**
+*Mechanism:* three layers. (a) Collision rows evaluate against the collider pose *interpolated to the
+substep*, from the previous and current poses the index caches — cheap swept collision. (b) The slack
+bound stops a particle long before it can travel far enough to cross a limb. (c) Substepping shrinks
+per-step travel.
+
+**M2 found (a) is two mechanisms and only had one of them.** Interpolating the poses does nothing
+unless the contact **set** covers the sweep as well, and it did not: `cloth_contact_find` runs once
+per step against the *end-of-step* pose, so a collider that crossed the cloth within the step is
+already past it and no row is ever created. Measured on a capsule driven through a hanging sheet at
+20 m/s: **zero contact rows for the whole pass**, with the sheet untouched — not tunnelled through so
+much as never noticed. The fix is one subtraction per record per step, folding the collider's own
+travel into the discovery reach, and it makes 2 to 40 m/s behave alike (94.8 rows a step at 20 m/s
+against 0.0 without). `MEASUREMENTS.md` §20.
+
+**And the interpolation is of a translation and a quaternion, not of two matrices.** §8.2 said
+matrices; a component-wise lerp of two rotation matrices is not a rotation, and halfway through a turn
+of `θ` it scales the shape it poses by `cos(θ/2)`. At the half-radian per step
+`CLOTH_ANCHOR_ROTATION_LIMIT` already calls a spin, a 25 cm collider loses 7.8 mm — twice a silk
+garment's thickness — halfway through every step. `MEASUREMENTS.md` §19.
+
+*Limit, stated:* both halves are swept in translation first. A collider spinning fast enough that a
+point on its surface travels more than its own radius within one substep can still be missed, because
+the discovery margin is built from the *centre's* travel. Full CCD for cloth is out of scope.
+*Spec:* a capsule driven through a hanging sheet at 2 to 40 m/s, swept against unswept; assert the
+swept pass creates rows at every speed and that no particle spends a step more than half a collider
+radius inside. `cloth_collision.spec.js` carries the ECS-level companion.
+
+**P4 — Folds, tangles, and stays stuck.** The named requirement, so four mechanisms:
+
+  *(a) No history-dependent normals.* Self-collision and collision normals are derived from the
+  proxy's own surface orientation and the collider's SDF gradient at the current position — never from
+  "which side was this on last frame". A history-based scheme latches onto a wrong side and stays
+  wrong indefinitely; an orientation-based one resolves a tangle as soon as the surrounding geometry
+  permits. This is the "predefined surface orientation" branch of the untangling literature, chosen
+  specifically because it has no state that *can* get stuck.
+
+  *(b) No degenerate fold state.* Quadratic bending (§6) means a fully inverted 180° fold is not a
+  singular configuration — it is simply high energy, and high energy relaxes.
+
+  *(c) The slack bound bounds the reachable set.* Every particle is under a hard leash of radius
+  `slack·d_geo,i` around its animated position, so the set of configurations the simulation can occupy
+  is a bounded neighbourhood of the animation. **Error cannot accumulate** — however bad a step is, the
+  next step starts inside that same neighbourhood, and there is no drift mode that walks the cloth
+  somewhere it cannot return from. That is the guarantee, and note what it does *not* claim: the
+  animated pose itself can be imperfect. It is collision-free in the bind pose (the build validates
+  exactly that, §11.3, and fails loudly with the offending vertex and collider named), but an extreme
+  animation pose can skin a garment slightly into a thigh. When that happens the attractor is slightly
+  wrong and the cloth is slightly wrong with it — bounded and self-limiting, not divergent.
+
+  This is also why `slack` is the one number worth reaching for when a garment misbehaves: it is
+  literally the size of the neighbourhood the simulation is allowed to explore. **M1 note:** with §3.4's
+  corrected factor of two, `slack = 1` makes that neighbourhood the whole of what the tether already
+  allows, so the guarantee at `slack = 1` is the tether's rather than the leash's — which is the right
+  answer for a rope, and is why every chain in the library sits there.
+
+  **M2 note, and it is a limit rather than a gap.** The escape hatch below watches a *residual*, and
+  there is a configuration whose residual is zero and which is still stuck: a rope authored exactly
+  along an axis, compressed by a plane whose normal is exactly that axis, has no lateral component
+  anywhere in the system and folds into an accordion in which every link is at its rest length. That
+  is an exact equilibrium, so nothing has anything to act on. Measured: an 8-link rope on a floor
+  stops 18 cm above it and stays; **one part in a thousand of lateral lean** — a millimetre across a
+  10 cm link — and it lies down. Recorded rather than fixed, because the fix is noise injected by a
+  solver whose whole design commitment is that it needs none, and no authored scene is that
+  symmetric. `MEASUREMENTS.md` §22.
+
+  *(d) A bounded escape hatch.* If a particle's constraint residual stays above a threshold for N
+  consecutive steps, it blends to its animated position over a short window. Local, bounded, on by
+  default with a conservative threshold, and counted in `ClothDiagnostics` so that a garment relying on
+  it is visible rather than silently rescued.
+
+*Spec:* deliberately invert half a sheet through itself, run, assert the residual falls below threshold
+and the mesh is self-intersection-free within N steps; separately assert the escape hatch is not
+triggered by a correctly authored garment under normal animation.
+
+**P5 — Jitter at rest.**
+*Mechanism:* the multiplier decay `α·γ < 1` bleeds accumulated force out of a resting configuration so
+it cannot ring; per-cloth sleep when the maximum particle displacement over a window falls below a
+threshold; wake on collider motion, anchor motion, wind change, or a `ClothDynamics` change.
+*M0 found the gap, and it is wider than "nothing is damping it".* The mechanism reaches **hard** rows
+only, because a soft row has no multiplier to decay — and a soft row whose penalty exceeds about
+`8·(m/h²)` does not merely fail to dissipate, it makes the step **add** energy. Measured on a hanging
+sheet: total mechanical energy climbing +6.8 J against a system whose entire gravitational potential
+is 1.2 J, sustained indefinitely, and shrinking but never vanishing as iterations or substeps go up.
+Below that ratio the same row is dissipative and settles. What stops it is `ClothDynamics#damping`,
+which arrives with the component in M1 — so **damping is load-bearing for P5 rather than a taste
+control**, and the M1 spec has to gate on a soft cloth actually settling. `MEASUREMENTS.md` §6.
+*Spec:* a settled cloth reaches sleep within a bounded number of steps and its positions are bit-identical
+across the following 300.
+*M1 landed both halves and measured them.* Every library fabric, on a 12-link chain set swinging at
+3 m/s, sleeps: **220 steps for denim, 770 for silk**, everything else between, and the order is the
+damping order. Sleep stops the **write-back** as well as the step, which is what makes "bit-identical"
+a fact rather than a hope — a pose that is not rewritten cannot drift, and one rewritten from unchanged
+inputs is only *probably* identical. A cloth wakes on anchor motion, on a `ClothDynamics` change, on a
+`blend` change, and on an explicit `ClothSystem#wake` for anything it cannot see.
+
+And the damping gate, on the configuration §6 measured the limit cycle in — a 16-link rope with its
+stretch rows forced soft at 1e5 N/m, a ratio of about 350 — after 1,500 steps: **2.90e-3 J undamped,
+1.28e-6 J at the library's own `damping = 0.12`**, 1.82e-12 J at the top of the range. Three orders of
+magnitude from a field the design first described as a taste control. Note what damping does *not* do:
+it does not stop the step adding energy, it removes energy faster than the step adds it, which is why
+the numbers keep falling to `damping = 1` instead of hitting a floor. `MEASUREMENTS.md` §12.
+
+**P6 — Teleport and cut.**
+*Mechanism:* anchor motion above a threshold in one step is a teleport — `Reset` (re-seed at the
+animated pose, zero velocity) or `Keep` (carry the shape across). Default `Reset`, followed by a short
+stabilisation window in which the velocity limit ramps back from nothing, so the first steps after a
+reset cannot produce a whip.
+*Spec:* teleport 1 km mid-swing; assert bounded velocity every step and convergence to the animated pose.
+*Measured, M1:* `Reset` peaks at **0.000 m/s** across the 240 steps after the jump and lands on the
+animated pose; `Keep` peaks at 5.58 m/s, which is the swing it was already carrying, and shifts by
+0.078 m in local coordinates against 1.489 m for the reset. The threshold is `max(4·reach, 2 m)` per
+step, and a 9 m/s sprint does not reach it for any library fabric.
+
+**M1 named the mode differently and found `Keep` is free.** There is no `ClothTeleportMode`: the choice
+is binary, so it is `ClothFlags.TeleportKeep`, one bit on the component that already carries the
+cloth's own switches — a mode enum for two values is the discriminator field §3.1 exists to avoid. And
+`Keep` is *literally* free: MagicaCloth2 applies the anchor delta rigidly to every particle, but in a
+frame anchored to the cloth's own entity the particles are already anchor-relative, so "apply the
+delta" is doing nothing. The implementation is a `return`.
+
+**P7 — Fast locomotion: whipping, lag, centrifugal spray.**
+*Mechanism:* the simulation runs in a **local frame anchored to the cloth's own entity**, with
+`ClothDynamics#inertia` controlling how much of the anchor's world motion the cloth is allowed to
+feel, plus anchor linear and angular speed limits. This is MagicaCloth2's `InertiaConstraint` idea and
+it is the correct one: it makes "character sprints, cape behaves" a default rather than a tuning
+exercise.
+*Spec:* drive the anchor along a step-function velocity profile; assert bounded particle speed throughout.
+*Measured, M1:* a square wave of ±9 m/s, one second a phase. Peak local particle speed runs 11.3 to
+29.3 m/s across the library against clamps of 96 to 288, so the smallest headroom is **5.7×**; nothing
+teleports, and nothing leaves its own reach by more than 0.35%. The anchor limits are derived rather
+than authored — half a reach of travel and half a radian of rotation per fixed step, both expressed
+against the cloth's own geometry so a 3 cm pendant and a 30 m mooring line get the same treatment.
+`inertia` measures monotone and exactly zero at zero: 0, 0.20, 0.37, 0.52, 0.65 m of tip lag across
+its range, which is what makes it a dial rather than a switch with a meaningless middle.
+`MEASUREMENTS.md` §13.
+
+**P8 — Degenerate authoring.**
+*Mechanism:* build-time validation, not runtime tolerance. The proxy builder welds duplicates, drops
+zero-area triangles, and refuses non-manifold and inconsistently-wound configurations. The existing
+`bt_edge_read_diamond` already declines every configuration a bending stencil cannot be built on —
+wire edges, boundary edges, non-manifold edges, non-triangular neighbours, inconsistent winding, and a
+"diamond" that is really one doubled triangle — so the degenerate cases are rejected by a function that
+has already thought about them rather than by new code.
+*Spec:* a corpus of deliberately broken meshes, each producing a specific diagnostic and no proxy.
+
+---
+
+## 8. Collision against the physics world
+
+### 8.1 The index
+
+`ClothColliderSystem` maintains `ClothColliderIndex`: a flat array of packed records, each holding the
+shape kind and its parameters, the world matrix, its cached inverse, the previous step's matrix, the
+world AABB, friction and inflation. `OccluderBody` in the acoustic simulator is the same record and is
+the shape to copy — including its precondition that the pose is rigid, so a distance in the shape's
+local frame equals a distance in world space.
+
+Per step, `ClothSystem` queries the index with the cloth's own fattened AABB and gets the overlapping
+records. That set is packed into shared memory for the worker; nothing on the far side of the worker
+boundary is an object.
+
+### 8.2 Evaluating a collision
+
+The collision row needs `sdf_c(x_i)` and its gradient. Bring the particle into the collider's local
+frame, evaluate the closed-form SDF and gradient there, rotate the gradient back.
+
+**The pose is a translation and a quaternion, and there is no cached inverse.** A rigid pose inverts by
+conjugating its quaternion and subtracting its translation, which costs less than storing an inverse
+and is exact rather than cached — and, more importantly, it is the only form the sweep can
+interpolate. This paragraph originally said the sweep comes from "interpolating between the previous
+and current **matrices**", and a component-wise lerp of two rotation matrices is not a rotation: it
+scales the shape it poses by `cos(θ/2)`, which at the half-radian per step the anchor limit already
+calls a spin is 7.8 mm off a 25 cm collider — twice a silk garment's thickness, every step.
+`MEASUREMENTS.md` §19.
+
+**And the sweep is two things, not one.** Interpolating the poses is useless unless the contact *set*
+also covers the sweep; §7 P3 carries what that cost and what it now does.
+
+**Supported kinds are analytic primitives**: sphere, capsule, box, cylinder, and a plane. That
+restriction is universal in shipping cloth systems — MagicaCloth2 offers sphere, capsule and plane;
+Chaos Cloth adds tapered capsules and convex hulls — and it is what makes the inner loop a handful of
+arithmetic instead of a BVH descent. A `Collider` carrying a mesh or heightmap shape is **skipped with
+one warning naming the entity**, and the documented answer is to add primitive `ClothCollider` children,
+which is what an author would do anyway for a character.
+
+The engine's shapes already carry the closed-form SDFs — `CapsuleShape3D#signed_distance_at_point`,
+`BoxShape3D#signed_distance_at_point` and the rest are exact and inline. Their *gradients* are not:
+`signed_distance_gradient_at_point` on capsule, box and cylinder all fall back to
+`compute_signed_distance_gradient_by_sampling`, which is four SDF evaluations and a normalise. That is
+fine for voxelising a fluid obstacle once per step. It is not fine in a per-particle, per-iteration
+loop, so §14 makes the analytic gradients shared code that both sides use.
+
+### 8.3 Friction
+
+Coulomb friction as a row on the same contact, with `μ` combining `Collider#friction` with
+`ClothCollider#friction_scale`. The combine rule is the one `physics/contact/combine_material.js`
+already applies, so cloth and rigid bodies agree about what a surface feels like.
+
+**M2 made three of those words exact.** The clamp is `[0, μ·f_n]` rather than `±μ·f_n`, because the
+row's `C` is the *magnitude* of the tangential slip — §6 carries the derivation and what writing it
+that way buys. `f_n` is the collision row's force **this iteration**, not its converged multiplier
+from this step: the multiplier is one iteration stale and therefore exactly zero on a contact's first
+iteration, so at the one iteration per substep §5.1 says the solver must be usable at, friction would
+never act at all. And the static/dynamic separation needs no smooth transition function of its own —
+it falls out of the clamp, because a row under the cap is enforced to convergence and sticks, and one
+at the cap applies exactly `μ·f_n` against the slip direction and slides.
+
+The row's anchor — where the particle stuck — is stored in the **collider's** own frame and read back
+through the interpolated pose, which is what makes a sliding surface drag cloth with it instead of a
+point in space holding it still.
+
+---
+
+## 9. Self-collision
+
+Off by default — `ClothDynamicsFlags.SelfCollision`. It is the most expensive part of every cloth
+system that has it — MagicaCloth2's self-collision constraint is 2,564 lines against 606 for
+distance — and the pathology guarantees in §7 do not depend on it.
+
+**M4 corrected which entries set it, and the axis the list was drawn along.** This paragraph used
+to name them by what the garment *is* — set on skirts, long coats and hair, clear on capes,
+ponytails and banners. What decides is **how far the fabric bends**. Measured on a folding sheet
+at each entry's own `bend`: silk, hair and cotton pass through themselves 8 to 11 times a sample
+and the row removes 71% to 81% of it; denim tangles a third as much; leather does not tangle at
+all — 0.18 crossings a sample — and the row makes it *worse*, because the few pairs it finds are
+noise it is adding to a fabric that was never going to fold that tightly. `CLOTH_SILK`,
+`CLOTH_COTTON` and `CLOTH_HAIR` set the flag; `CLOTH_DENIM`, `CLOTH_LEATHER` and both chains do
+not. `MEASUREMENTS.md` §33.
+
+Two tiers:
+
+**M4a — particle-particle repulsion. M4 built it.** A uniform hash grid over particles in the
+cloth's local frame; pairs closer than `r_i + r_j` get the unilateral row from §6. Pairs sharing a
+triangle or an edge are excluded, since they are already governed by stretch and bend rows and
+would otherwise fight them — in practice the exclusion is *sharing any row at all*, which is the
+same set plus a chain's skip rows.
+
+**That `r` is not the fabric's thickness, and M4 got that wrong before it measured its way out.**
+It reads as the same `r` a collider contact uses, which is `ClothDynamics#thickness`; a fabric is
+4 to 20 mm thick and a proxy's particles are 2 to 8 cm apart, so at that radius the two layers of
+a fold are almost never in contact and the row finds 1.6 to 3.7 pairs across a whole garment. The
+radius is a property of **the proxy**: `ClothState#self_radius`, `max(thickness, shortest_row/2)`,
+so the row's diameter is one particle spacing. At the fabric's own 6 mm the row removes 21% of a
+sheet's self-intersections; at half the shortest row it removes 82%. `MEASUREMENTS.md` §31.
+
+**It also needs a ceiling, and the ceiling is a measured length.** A diameter that reaches the
+closest pair *no row governs* puts a cloth which is not folded at all in permanent contact with
+itself — leather, 20 mm thick on a 20 mm proxy, found 1,398 pairs a step across 576 particles
+standing still (§36). On a sheet that distance is two hops and could have been assumed; on a
+rigged garment, whose proxy is strips with nothing joining one to the next, it is the gap the
+artist left between strips and is half what the link length implies. So `ClothInstance` measures
+it once at seed, in the bind pose, and the ceiling is two fifths of it. `MEASUREMENTS.md` §37.
+
+"O(n) with a small constant" is right about the shape and optimistic about the constant: the pair
+search is linear in particles with no term in the pair count, and it is **12% of a frame** at the
+§17 workload, and most of everything self-collision costs. The rows themselves are nearly free.
+`MEASUREMENTS.md` §34. "The great majority of visible interpenetration" is 82% of it, and the
+stiffness that does it is `8·(m_eff/h²)`, chosen on the crossing count rather than on M0's
+dissipative band — a one-sided row that vanishes when satisfied shows no energy growth at 64×
+that. `MEASUREMENTS.md` §32.
+
+*This tier cannot see cloth passing between particles.* A sheet thinner than its particle spacing can
+still slip through itself. Stated, not hidden.
+
+**M4b — point-triangle and edge-edge.** The full stencil set, which closes that gap, over the same
+grid. Deferred behind measurement: it roughly triples the self-collision cost and the benefit is
+garment-dependent.
+
+**M4 makes that cost estimate the first thing to re-measure.** The stencils would ride on a grid
+that has already been built, and the grid is where nearly all the money goes — tripling the rows
+triples something that is 5% to 20% of the feature. `MEASUREMENTS.md` §34.
+
+Both tiers derive their normals from the proxy's surface orientation, per P4(a).
+
+**M4a's normal is the line between the two particles, not a surface orientation**, because a
+particle pair has no surface in it. What P4(a) is actually asking for — nothing history-dependent,
+no "which side was this on last frame" to latch onto — the pair normal satisfies completely and
+more simply: `(x_i − x_j)/‖x_i − x_j‖` at the current position, recomputed every iteration, with
+no multiplier, no warm start and no identity across steps. The sentence above is right about M4b,
+where a point-triangle stencil genuinely needs an orientation to choose a side.
+
+There is no 3D uniform hash grid in `core` today; there is a well-tested 2D one
+(`core/geom/2d/hash-grid/SpatialHashGrid.js`) whose structure is the template. §14.
+
+**M4 built `core/geom/3d/hash-grid/PointHashGrid3.js` and it is not that structure.** The 2D grid
+is persistent and incremental — a bounded cell array, elements that are AABBs and carry identity,
+insert/remove/move as the primitives. Cloth particles are points with no identity across steps in
+an unbounded domain, and *every one of them moves every step*, so the incremental primitive never
+gets to be incremental. `PointHashGrid3` is a counting sort into a power-of-two hash and has no
+insert, no remove and no element identity at all. The idea carried over; not one line of the
+structure did. `MEASUREMENTS.md` §34.
+
+---
+
+## 10. Wind and aerodynamics
+
+Cloth that does not move with the air reads as dead, and this engine has something better than a wind
+zone: a **fluid simulator**. `FluidField` exposes `sampleVelocity(out, x, y, z)` with trilinear
+filtering over a MAC grid, `fluid_build_world_to_grid` builds the world→grid transform, and
+`FluidObstacle` already voxelises physics colliders into the field so the air is genuinely disturbed by
+the bodies in the scene.
+
+So the design is: **a cloth overlapping a `FluidComponent` samples its velocity field per particle and
+applies aerodynamic drag against it**, scaled by `ClothDynamics#drag`. The term is an external
+acceleration, `a_drag = drag · (u_air − v) · |n·û|`, with the normal-facing factor making a sheet catch
+the wind broadside and slice through it edge-on — the difference between a flag and a rope.
+
+The payoff is that a character running past a cape gets a wake, because the fluid solver already
+produces one; a fire's convection lifts a banner; a door slamming pushes a curtain. None of that needs
+cloth-specific authoring, and none of it needs a wind system that duplicates what the fluid system
+already does.
+
+Fallback when there is no fluid field in range: a `GlobalFluidEffector`-shaped ambient term — a
+constant `wind` vector plus a small band-limited noise for gusting — read from the same interface, so
+the cloth code has one path and does not branch on whether a simulation is present.
+
+Cost control: sampling is per particle per *step*, not per iteration, and a cloth outside every fluid
+field's bounds skips it entirely. Sleep (P5) wakes on a wind change so a settled banner does not stay
+asleep through a gust.
+
+This is deferred to M6 — it is the feature most likely to be cut for schedule, and nothing else depends
+on it.
+
+---
+
+## 11. Geometry in, results out
+
+**Cloth moves joints. It does not produce vertices.** The mapping from a simulated particle to a
+render vertex already exists in this engine and it is the **skin**: a `Skin` holds `joints: Node3D[]`
+plus inverse-bind matrices, every render vertex carries a four-entry weight palette into that joint
+list, and `node.global · inverse_bind` is what the GPU blends every frame. Cloth writes joint
+transforms; the existing skinning pass does the rest — including bounds refresh and BLAS refit, which
+a bespoke vertex-deformation path would have to reimplement.
+
+That is the whole relation, and it is why there is no cloth-owned render mesh anywhere in this design.
+
+### 11.1 Entity hierarchies — `Cloth` alone
+
+One particle per entity in the transform subtree of the entity the component is on, walked through
+`TransformAttachmentSystem#findChildrenOf`, stopping at a nested `Cloth` or a `ClothExclude`. Stretch
+rows along parent-child links, bend rows along each chain, and the anchor entity itself is the fixed
+set — so `d_geo` is hop distance from the anchor and every derived quantity in §3.4 works unchanged.
+
+Output is written back to the subtree entities' `Transform64` — position directly, rotation derived
+from the direction to the child, interpolated between parent-driven and child-driven orientation, which
+is what keeps a two-link chain from looking hinged.
+
+**M1 made three of those words exact.**
+
+*Both transforms are written: the world `Transform64` and the local
+`TransformAttachment#transform`.* 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, 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 (measured at 1.7e-15 m), and §4.1's ordering problem stops
+being one. It is also 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*.
+
+The authored pose is not lost by being overwritten. It is captured once, when the cloth seeds, and
+lives in the cloth from then on — which is what `blend = 0` returns to, what the leash centres are
+measured from, and what a re-seed of a live cloth reads instead of the shape the solver left behind.
+The consequence, stated: **in the entity path the animated pose is constant in the anchor's frame.**
+That is a property of the case rather than a limitation of the code — a subtree's authored pose is
+rigid relative to its anchor — but it does mean a subtree whose *links* are independently animated is
+not an M1 case.
+
+**M3 corrected the sentence that used to end this paragraph**, which said that was the rig path and
+that there the animated pose "comes from the skeleton and is live". For a **rigged** garment it is
+not: cloth claims those joints (§11.2), so nothing else poses them, so their authored pose is the
+proxy's baked bind pose — constant in the anchor's frame, exactly as a rope's is. What moves is the
+anchor, and the anchor is a bone of the character's own animated skeleton. The live case is the
+**unrigged** path, where the targets are mesh vertices skinned by
+`mesh_apply_skeletal_vertex_skinning` and genuinely move under the animation.
+
+*The rotation is a **swing** on top of the animated orientation*, `q = swing(d_animated → d_simulated)
+⊗ q_animated`, using the minimal (twist-free) arc. Twist is inherited from the animation rather than
+invented, because 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, since at `blend = 0` the
+simulated direction *is* the animated one and the swing is the identity. A node with both a parent and
+children takes the half-way rotation between the two swings; a leaf takes its parent's. The shortest
+arc had no primitive in `core` and now does (`quat3_shortest_arc`), which is §14's doctrine turning up
+a fourth time.
+
+*Nothing is announced on a simulated node, and every pruned boundary is.* A `TRANSFORM64_EVENT_CHANGE`
+on a simulated node would make the attachment system recompose its children from the authored pose —
+undoing the write that was just made, and cascading, for a chain, quadratically. But the root of a
+`ClothExclude` subtree, and a nested `Cloth`'s anchor, are *not* particles and still have to move: the
+write-back poses each of them by hand against the link it hangs from and announces exactly there, which
+reaches everything below the cut through the ordinary cascade and reaches nothing above it.
+
+This is the path for props that genuinely *are* entity hierarchies: a rope, a chain, a hanging sign, a
+mooring line, a rigid model whose parts were expanded into entities and each drew as a
+`ShadedGeometry`. It needs no new rendering code, because moving an entity's `Transform64` is already
+how anything moves.
+
+### 11.2 Skinned garments — `Cloth` + `ClothRig`
+
+A character's cape is not an entity hierarchy and cannot be made into one.
+`shade_node_to_entity_composition` expands a model into entities and attaches a `ShadedGeometry` to
+each node that draws — but a skinned node contributes its transform and its name and **no geometry**,
+because its vertices deform against a skeleton the renderer owns and the GPU poses. Its joints are
+`Node3D`s inside the entity's `SceneBundleInstance`, and making them entities is explicitly a design
+this program does not do (D47). So for a skinned garment there is no `ShadedGeometry` component and no
+bone entities: the geometry is registered with `GPUAnimationManager` through
+`register_instance_animation`, and the only writable handle is the joint's `Node3D.transform_local` —
+the same handle the animation systems write.
+
+**And cloth has to *claim* those joints, which §11.2 originally read as though it did not.** The
+sentence above says the handle is "the same handle the animation systems write", and they do not
+write it: `TransformAuthority` is explicit that a node a clip drives is `GPU`, that "the CPU
+allocates and seeds the row, then never writes to it again", and that "the node's own
+`transform_local` stops describing it and should not be read as if it did" — and
+`instantiate_scene_bundle` stamps `GPU` on every node a clip channel targets. So cloth writing
+`transform_local` on a clip-driven joint would be writing into a field nothing reads.
+
+`cloth_seed_rig` therefore sets `TransformAuthority.CPU` on every joint it drives. The consequence,
+stated: **a joint cloth simulates stops being animatable by a clip.** Two writers of one row is the
+race the enum exists to prevent, and for a cape that is the point of simulating it; for a garment
+whose joints are also keyed it is an authoring error, and the claim is where it surfaces.
+`MEASUREMENTS.md` §25.
+
+**The anchor's world pose is computed, never read back.** A joint of an animated skeleton has no
+CPU-side `transform_global` — nothing maintains it — so the rig path evaluates the anchor with
+`pose_evaluate_world` over the clips the entity is playing, which is the engine's own sanctioned
+answer to "where is this bone" and the one `query_entity_node_world_pose` gives gameplay. A cape and
+a scabbard on the same shoulder are then placed by the same evaluator off the same clock.
+
+Cloth therefore drives joints, and the proxy names which ones. **Three resolutions, deliberately:**
+
+| tier | order of magnitude, skirt | what it is | who owns it |
+|---|---|---|---|
+| render mesh | ~5,000 vertices | `MeshletGeometry`, GPU-resident, never touched by cloth | the asset |
+| sim proxy | ~400 particles | what the solver steps | `ClothProxy` |
+| output joints | ~60 | what `Skin#joints` holds; the palette binds render vertices to these | `ClothProxy` |
+
+Decoupling the middle tier from the bottom one is the point. Simulation wants enough particles to
+drape; skinning wants only enough joints to *describe* the drape, and a four-weight palette blends
+smoothly between far fewer of them than the simulation needs. Each output joint takes its position and
+its frame from a small neighbourhood of particles — a triangle fan or a fitted patch — so the joint
+count is a build-time choice about deformation fidelity rather than a consequence of solver
+resolution. That is also what disposes of the "one node per particle" cost worry: nothing requires
+one node per particle.
+
+Two cases, and they differ only in where the joints and weights came from:
+
+- **The garment is already rigged** — an artist made 8–20 cape joints and skinned the cape to them.
+  This is the common case and by far the cheapest. The proxy is thin: joint indices, the topology
+  connecting them, rest lengths, `d_geo`. **There is no binding step and no generated geometry — the
+  artist's skin is the relation.** A cape, a ponytail, a coat tail, a loincloth: all of this.
+- **The garment has no usable rig** and wants per-vertex drape — a full skirt. The importer generates
+  the joint set and generates a skin binding render vertices to it, then bakes both into the proxy.
+  At runtime this is *indistinguishable* from the rigged case: the GPU sees an ordinary skin, the
+  solver sees an ordinary particle set.
+
+Animated targets — the `s_i` that the slack row, blending and P4 all need — come from
+`mesh_apply_skeletal_vertex_skinning`, which already takes flat positions, weights, indices and 4×3
+bone matrices and writes flat output. Typed arrays in, typed arrays out, no objects: it crosses the
+worker boundary as-is.
+
+**What was rejected.** A dedicated deformation pass — cloth writing vertex positions into a dynamic
+geometry buffer, with render vertices bound barycentrically to proxy triangles — is the obvious
+alternative and is genuinely simpler *as a deformation*: one frame per triangle rather than per joint,
+no palette width to respect. It loses because `MeshletGeometry` is meshlet-clustered and BLAS-backed,
+so a new path has to reimplement per-frame vertex upload, meshlet bounds refresh, normal
+recomputation and BLAS refit — all of which the skinning path already does and has playgrounds for.
+It stays written down as the fallback if M3's measurements go badly.
+
+### 11.3 Building a `ClothProxy`
+
+At import, producing the object `ClothRig#proxy` points at. Almost entirely existing code.
+
+For a **rigged** garment, only steps 5–8 run, over the joint graph rather than a mesh:
+
+1. Load the source garment into a `BinaryTopology` (`bt_mesh_from_indexed_geometry`).
+2. Weld and clean (`geometry_deduplicate_vertices`, drop degenerate faces).
+3. Decimate to the target particle count with `bt_mesh_simplify_by_error` — quadric error metric, via
+   `bt_mesh_compute_vertex_quadrics`. This is the standard distance-based reduction every cloth package
+   does, with a principled metric instead of a hand-rolled one.
+4. Extract stretch rows from edges, bend stencils from `bt_edge_read_diamond`, and the boundary from
+   `bt_collect_boundary_segments`.
+5. Derive the **fixed set automatically**: particles whose skin weights are dominated by joints
+   *outside* the garment's own joint set are pinned. This is what makes "works untouched" true — a
+   cape pinned at the shoulders needs no painting, because the skin data already says where the cape
+   stops being cape.
+
+   **M3 found this is the unrigged rule and that the rigged path has a better one.** For a garment
+   that is already rigged there are no mesh vertices to read weights for — the particles *are*
+   joints — and the topology answers directly: a joint whose parent is outside the named set is a
+   joint the garment hangs from, and they all have to hang from the same bone. That bone is the
+   anchor and its `d_geo` is zero, so §3.4's derived quantities collapse onto it with nothing else
+   saying "this one is pinned". Several chains from one bone are one garment and are §3.1's coupled
+   solve; chains from *different* bones are refused, because there is then no single frame to
+   simulate in.
+6. Bake `d_geo` — geodesic distance from every particle to the fixed set. This one array drives the
+   tether row, the slack profile, and the pinning, so the three cannot disagree.
+7. Colour the particle graph (`colorizeGraphGreedy`, checked by `validateGraphColoring`), and permute
+   the particle order so each colour is a contiguous range.
+8. Resolve joint **names to indices** into `Skin#joints`, using `SceneBundleInstance#nodes`. This is
+   the only place a name appears anywhere in the system.
+9. **Unrigged only:** choose the output joint set, fit each joint's neighbourhood and bind pose, and
+   generate the skin's weights and inverse-bind matrices for the render mesh.
+10. **Validate**: manifoldness, no zero-length edges, and — the P4(c) precondition — that the skinned
+    bind pose is collision-free against the character's `ClothCollider` set.
+
+Vertex painting (per-vertex stiffness or slack multiplier) is supported through an optional texture or
+vertex-colour channel and is never required. Steps 5 and 6 are the default, and the intent is that most
+garments never override them.
+
+---
+
+## 12. Data layout, threading, the worker
+
+**One `SharedArrayBuffer` for the whole cloth world**, not one per instance. `WorkerSystem`'s model is
+a single shared buffer, a single command region and a single atomic publishing one in-flight step, and
+`WorkerFluidSystem` already shows how a variable set of simulated things fits that model: the command
+region carries a count and then a list of ids to step. Cloth does the same — each instance gets a
+region inside the buffer, and the command region names which instances are live this step, so sleeping
+(P5) and culled (§12.1) instances cost nothing but their absence from a list.
+
+SoA throughout:
+
+| Region | Type | Contents |
+|---|---|---|
+| particle state | `Float32Array` | `x`, `x_prev`, `v`, `y`, inverse mass, radius |
+| animated targets | `Float32Array` | `s`, backstop origin + normal |
+| topology | `Int32Array` | edge pairs, bend stencils, colour ranges, tether anchors |
+| rest data | `Float32Array` | rest lengths, bend weights, `d_geo` |
+| duals | `Float32Array` | `λ` and `k` per persistent constraint |
+| colliders | `Float32Array` | packed records for this step |
+| contacts | `Float32Array` | transient rows + their warm-start `λ`, keyed by (particle, collider slot) |
+
+`ClothDynamics` reaches the worker through the command region, written every step — a dozen words into
+memory the worker already shares, cheaper than tracking dirtiness, and it keeps
+`cloth.dynamics.slack = 0.2` working live, which is the point of a value object rather than a preset
+that has to be re-applied.
+
+`Float32` for particle state, not `Float64`. The simulation runs in the cloth's **local frame**, so
+coordinates are garment-sized rather than world-sized and f32 has ample precision; the payoff is half
+the bandwidth in the loop that dominates. The local frame is not a memory optimisation that happens to
+help — it is the same choice that makes P7's inertia handling natural, and the precision win follows.
+Write-back converts local f32 to world `Transform64` at the boundary, once per particle per step.
+
+Transient contact rows need their multipliers warm-started across steps to be worth anything, so they
+are keyed by `(particle index, collider handle)` and matched on the next step. A collider that leaves
+the index drops its slot and its contacts start cold, which is correct.
+
+**M2 made "slot" exact and it matters.** The key is the collider's **handle in the index**, not its
+record index in the cloth's own per-step table: that table is whatever this step's broadphase returned,
+in whatever order, so a record index names a different collider from one step to the next. Storage is a
+fixed `CLOTH_CONTACT_SLOTS` per particle inside `ClothState`'s single buffer — four, measured never to
+saturate on a twenty-collider scene and to average a tenth of one — which keeps §12's one-allocation
+property and bounds the worst case at the four *most violated* colliders, which is the four that matter.
+
+**The worker.** `WorkerClothSystem` is a `WorkerSystem` subclass and follows `WorkerFluidSystem`
+exactly, because that pattern is already proven in this repo: `collect` packs colliders and animated
+targets into shared memory and writes the command words, a single `Atomics.store` publishes the step,
+`apply` reads the result on the next tick, and the fixed-step gate guarantees the worker is idle during
+every system's `fixedUpdate`. The split is the same shape too — arbitrary user-facing work (component
+reads, `Transform64` sync, index queries) stays on the main thread; the pure numeric step crosses.
+
+The standing gate is the one the fluid system already holds itself to: **`ClothSystem` and
+`WorkerClothSystem` must produce bit-identical results.** Identical code over identical data in an
+identical order. That is what makes the worker a deployment choice rather than a behavioural fork, and
+it is why the core is a pure function over typed arrays from milestone zero even though the worker does
+not arrive until milestone five.
+
+Testing the bridge needs no worker: `SystemWorkerLoopback` gives a real `SystemWorkerHost`, a real
+`SharedArrayBuffer` and real `Atomics` in-process, with message delivery and step execution as explicit
+events a spec can order. Only the thread is faked.
+
+`SharedArrayBuffer` requires a cross-origin isolated page (`COOP`/`COEP`), which `WorkerFluidSystem`
+already documents. The main-thread `ClothSystem` is the fallback where that is not available, and it is
+not a degraded mode — it is the same code.
+
+### 12.1 Culling
+
+Cloth outside the view frustum stops stepping, which for a crowd is the difference between a budget and
+a problem. Resuming without a pop means blending from the animated pose back to the simulated one over
+a short window rather than snapping — the same `blend` machinery from §3.1, driven by the system
+instead of the author.
+
+---
+
+## 13. Reuse ledger
+
+What this design takes from the engine rather than building:
+
+| Need | Existing code |
+|---|---|
+| Vector and quaternion math | `core/geom/vec3/*` (95 functions), `core/geom/3d/quaternion/*` |
+| Mesh topology, adjacency, bending stencils | `core/geom/3d/topology/struct/binary/` — `BinaryTopology`, `bt_edge_read_diamond`, `bt_edge_is_boundary`, `bt_collect_boundary_segments` |
+| Proxy decimation | `bt_mesh_simplify_by_error`, `bt_mesh_compute_vertex_quadrics` |
+| Mesh cleanup | `geometry_deduplicate_vertices` |
+| Graph colouring | `core/graph/coloring/colorizeGraphGreedy.js`, `validateGraphColoring.js` |
+| Collider shapes and their SDFs | `core/geom/3d/shape/*` — closed-form `signed_distance_at_point` on every primitive |
+| Collider AABBs, pose caching | `core/geom/3d/aabb/*`, `aabb3_matrix4_project` |
+| Collider ECS wiring | `Collider`, `ColliderFlags`, `ColliderObserverSystem` (as the pattern) |
+| "Opt a collider into a second simulation" | `FluidObstacle` + `FluidObstacleSystem`, `AcousticBody` |
+| Collider index shape | `AcousticOccluderIndex` + `OccluderBody` |
+| Component holds a built shared asset | `Collider#shape`, `ParticleEffect#program` — the convention `ClothRig#proxy` follows |
+| Surface material combination | `physics/contact/combine_material.js` |
+| Constraint-row doctrine | `physics/constraint/solve_constraints.js` |
+| Subtree walk | `TransformAttachmentSystem#findChildrenOf` / `#countChildrenOf`, `TransformAttachment` |
+| Animated targets | `mesh_apply_skeletal_vertex_skinning` (flat arrays, worker-safe) |
+| Wind / aerodynamics | `FluidField#sampleVelocity`, `fluid_build_world_to_grid`, `GlobalFluidEffector` |
+| Worker offload | `ecs/async/WorkerSystem.js`, `SystemWorkerHost`, `SystemWorkerLoopback`, `WorkerFluidSystem` as the worked example |
+| Fixed step + render interpolation | `PhysicsSystem`'s producer/`__interp_restore` contract |
+| Transforms | `Transform64`, `Node3D` |
+| Particle → render-vertex mapping | `Skin` — joints + inverse-bind matrices + the four-weight palette; cloth writes joints and the existing pass does the rest |
+| Reaching a model's joints from its entity | `SceneBundleInstance` (`skins`, `nodes` by name), `register_instance_animation` |
+| Deformation, bounds refresh, BLAS refit | `GPUMeshSkinningContext`, `shader_skin_matrix_prep`, `bounds_refresh/` — all of it inherited by driving joints rather than vertices |
+| Non-finite tripwire pattern | `find_non_finite_physics_state.js` |
+| Strippable assertions | `core/assert.js` |
+| Serialisation | the `*SerializationAdapter` pattern and its binary codecs |
+
+---
+
+## 14. New shared code this justifies
+
+Three pieces belong in `core`, not in `cloth`, because the cloth need exposes a gap the engine has
+anyway:
+
+1. **Analytic SDF gradients** for sphere, capsule, box, cylinder and plane, as free functions in
+   `core/geom/3d/shape/sdf/`. **M2 built them.** Before it, `signed_distance_gradient_at_point` on
+   sphere, capsule, box and cylinder was `compute_signed_distance_gradient_by_sampling` — four SDF
+   evaluations plus a normalise, for shapes whose gradients are two lines of algebra. The shape classes
+   call the new functions, and so do their `signed_distance_at_point`s, so there is one implementation
+   of each field rather than two that can drift; cloth calls the same functions on packed data.
+
+   One thing the sampled version was quietly wrong about, and it is the reason a degenerate normal
+   needed a decision rather than a default: at a sphere's centre the forward difference returns
+   `(1,1,1)/√3`, which is unit length and entirely an artefact of sampling three positive offsets from
+   one point. The analytic functions return a documented arbitrary direction there instead, because a
+   gradient of zero carries no force and a particle that reaches the exact centre of a sphere would
+   stay there for ever — and "it does not get stuck" is the second design commitment in §1.
+
+2. **A 3D uniform hash grid.** **M4 built it**, as `core/geom/3d/hash-grid/PointHashGrid3.js`, and
+   **not** modelled on `core/geom/2d/hash-grid/SpatialHashGrid.js` as this line asked for. The 2D
+   grid is a persistent incremental structure over a bounded cell array holding AABBs with
+   identity; a cloth's particles are points, carry no identity across steps, live in an unbounded
+   domain and all move every step, so the operation that matters is *rebuild* and insert/remove
+   never runs. `PointHashGrid3` is a counting sort — count, prefix-sum, scatter — into a
+   power-of-two hash of the integer cell, with a `forEachNear` that walks the 27 neighbouring
+   cells and de-duplicates the buckets they hash into. Useful anywhere a broadphase over many
+   small equal-sized *points* is wanted; anything with extent and identity still wants the 2D
+   grid's shape. `MEASUREMENTS.md` §34.
+
+3. **`PlaneShape3D`.** **M2 built it**: the half-space `{ p : n·p − offset ≤ 0 }`, with the outward
+   normal and its offset, a constant gradient and no degenerate configuration anywhere. A box standing
+   in for a ground plane has to be large enough that nothing reaches its edge and thin enough that
+   nothing tunnels through it, and those pull against each other in `Float32`.
+
+   It is the one shape in the family that is **unbounded**, and that is a real cost paid in three
+   places: `support` is left unimplemented, because `argmax(p·d)` over a half-space is at infinity for
+   all but one direction and a large finite point would be a silently wrong contact manifold rather
+   than a loud failure; `sample_random_point_in_volume` likewise, since there is no uniform
+   distribution on an infinite volume; and `compute_bounding_box` answers with `±Infinity` on the
+   unbounded axes, which is what the set is. A consumer that cannot hold an infinite AABB must not be
+   handed a plane — which is why `ClothColliderIndex` is a linear scan rather than a BVH, and why it
+   bounds a plane from its world normal instead of projecting that box.
+
+4. **A shortest-arc quaternion**, `core/geom/3d/quaternion/quat3_shortest_arc.js` — the minimal,
+   twist-free rotation carrying one unit vector onto another. **M1 needed it and the family did not
+   have it**: `quat3_*` had `multiply`, `integrate`, `nlerp` and the uint32 codecs but nothing that
+   answers "orient this bone along that direction", which is the whole of §11.1's write-back. It is
+   also the one place in the family with a genuine discontinuity — no continuous choice of axis exists
+   on the whole sphere, so an antipodal pair has to pick one — and having it in `core` with a spec
+   around that case is better than having it inlined in a write-back loop without.
+
+Test helpers for all of it live inside the `.spec.js` files or in `__fixtures__`, per the repo rule —
+a shared helper module would ship on npm.
+
+---
+
+## 15. MagicaCloth2: what we take, what we leave
+
+MagicaCloth2 is the reference and it is a good one. It has shipped, it is fast, and its feature set is
+the accumulated answer to a decade of production complaints. Taken:
+
+- **Two cloth kinds over one solver.** MeshCloth and BoneCloth differ only in how particles are seeded
+  and how results are written back. This is right and §11 copies it — expressed as component presence
+  rather than an enum.
+- **A proxy mesh decoupled from the render mesh**, with distance-based reduction and custom skinning
+  back to the render vertices. Also right; §11.3 does the same thing with `bt_mesh_simplify_by_error`.
+- **The inertia model.** World and local inertia fractions, movement and rotation speed limits, an
+  anchor that cancels inertia for a character on a moving vehicle, teleport detection with Reset/Keep
+  modes, and a stabilisation window after reset. This is the least glamorous part of the package and
+  the most valuable; P6 and P7 are it, nearly verbatim.
+- **Max-distance and backstop** as first-class constraints rather than debugging aids. P3 and P4 lean on
+  them harder than MagicaCloth does — here the leash is the correctness argument, not a polish pass.
+- **Tether/LRA** as the answer to over-stretch at low iteration counts.
+
+Left:
+
+- **The parameter surface.** MagicaCloth2's serialised data is a dozen constraint blocks, several of them
+  animation curves over "depth", and its per-constraint files run to hundreds of lines of tuning. That is
+  the direct consequence of a PBD solver whose apparent stiffness depends on iteration count: when the
+  physical meaning of a slider moves with the budget, you end up shipping a curve per slider. AVBD's
+  parameters do not move that way, so §3.3 can be one small value object — and the per-particle profile
+  that MagicaCloth authors with curves falls out of `d_geo` instead (§3.4).
+- **Angle restoration and angle limit constraints.** These exist to give PBD chains a restoring force
+  that bending alone cannot supply at low iteration counts. With a solver that converges, bend rows plus
+  tethers cover the same ground with less to configure.
+- **A separate spring constraint.** Subsumed by the slack row with a non-zero radius.
+- **A distance constraint solved twice per substep** (before and after collision). An artefact of the
+  Gauss-Seidel ordering; the augmented Lagrangian's dual update does this work.
+- **Its collision layering model.** We already have `Collider`, layers and masks; a parallel system would
+  be a second thing to keep in sync.
+- **Its wind zones.** We have a fluid simulator (§10).
+
+---
+
+## 16. State of the art
+
+**The line this design sits on.** PBD → XPBD → substepped XPBD → VBD → AVBD.
+
+- **XPBD** (Macklin, Müller & Chentanez) made PBD stiffness independent of iteration count by
+  introducing compliance and a per-constraint multiplier. **Small Steps in Physics Simulation**
+  (Macklin et al. 2019) then showed that *n* substeps with one iteration each beats one step with *n*
+  iterations — less constraint error, far less artificial damping, and better behaviour across a wider
+  stiffness range than Krylov-based implicit solvers. Together these are the state of practice: Chaos
+  Cloth, MagicaCloth2 and Blender's cloth all sit here.
+- **Vertex Block Descent** (Chen, Liu, Yang & Yuksel, SIGGRAPH 2024) reframed the step as block
+  coordinate descent on implicit Euler's variational form, solving one 3×3 system per vertex per
+  iteration. Unconditionally stable at any iteration count, no line search, and it colours the vertex
+  graph rather than the constraint graph. Its reported failure mode is exactly the one that matters here:
+  it struggles to converge under high stiffness ratios and has no mechanism for enforcing hard
+  constraints — which is what a pinned garment on a rigid body *is*.
+- **Augmented Vertex Block Descent** (Giles, Diaz & Yuksel, SIGGRAPH 2025) fixes precisely that with an
+  augmented Lagrangian: hard constraints at effectively infinite stiffness without the instability, plus
+  substantially better convergence under high stiffness ratios. Reference implementations exist in 2D,
+  in Metal, in PhysX, in Houdini, and — relevant to this engine — as a WebGPU solver.
+- **Going Further With Vertex Block Descent** (Saillant et al., 2025) extends VBD to higher-order
+  elements and confirms that substepping improves its convergence — which is why §5.2 substeps rather
+  than only iterating.
+
+**The line this design does not sit on.** **Incremental Potential Contact** and its descendants —
+**C-IPC** for codimensional objects, **GIPC** and **AGIPC** on GPU — guarantee intersection-free,
+inversion-free results through log-barrier contact and continuous collision detection. They are the
+correct answer when correctness is the requirement, and they are the wrong answer at a millisecond
+budget. We take one idea from that family: IPC's smooth static/dynamic friction transition, which VBD
+also adopts.
+
+**Self-collision** is where the field is currently moving, because parallel position solvers have made
+it the bottleneck rather than the solve. **Air Meshes** (Müller et al. 2015) tessellate the space
+between objects and prevent element inversion, which handles untangling robustly and automatically but
+requires maintaining a volumetric mesh. **Global Intersection Analysis** (Baraff, Witkin & Kass,
+"Untangling Cloth", 2003) is history-free and resolves tangles as soon as geometry permits — the
+property P4(a) is built on, even though we implement a far cheaper approximation of it. Recent work on
+hierarchical culling via discrete curvature targets the same bottleneck.
+
+**Industry.** Chaos Cloth (Unreal) is substepped XPBD with long-range attachments, max distance and
+backstop distance/radius — the same safety constraints §7 relies on, which is useful independent
+confirmation that they are what production actually needs. Comparative studies of VBD against PBD in
+Unity report parity at low vertex counts and a widening VBD advantage as the count rises, which matches
+the per-iteration cost story: VBD does more arithmetic per vertex and far less coordination.
+
+Sources:
+[Vertex Block Descent](https://arxiv.org/abs/2403.06321) ·
+[VBD project page](https://graphics.cs.utah.edu/research/projects/vbd/) ·
+[Augmented Vertex Block Descent](https://graphics.cs.utah.edu/research/projects/avbd/) ·
+[AVBD reference implementation](https://github.com/savant117/avbd-demo2d) ·
+[WebGPU AVBD](https://github.com/jure/webphysics) ·
+[Going Further With Vertex Block Descent](https://onlinelibrary.wiley.com/doi/10.1002/cav.70039) ·
+[XPBD](https://matthias-research.github.io/pages/publications/XPBD.pdf) ·
+[Small Steps in Physics Simulation](https://mmacklin.com/smallsteps.pdf) ·
+[Untangling Cloth](https://dl.acm.org/doi/10.1145/882262.882357) ·
+[Air Meshes for Robust Collision Handling](https://dl.acm.org/doi/10.1145/2766907) ·
+[Codimensional IPC](https://arxiv.org/pdf/2012.04457) ·
+[Efficient Self-Collision Culling via Discrete Curvature](https://www.mdpi.com/2227-7390/14/9/1504) ·
+[VBD vs PBD in Unity](https://www.mdpi.com/2076-3417/14/23/11072) ·
+[Chaos Cloth](https://dev.epicgames.com/documentation/en-us/unreal-engine/clothing-tool-in-unreal-engine)
+
+---
+
+## 17. Milestones
+
+Each milestone is shippable and each `done` names evidence that ran. Nothing is reported complete on
+the strength of code existing.
+
+**M0 — the solver core. DONE, 2026-09-10.** `ClothState`, `cloth_step`, the vertex update, stretch and
+bend rows, colouring. Pure functions over typed arrays; no ECS, no worker, no rendering.
+*Proofs, all green:* finite-difference agreement between each row's analytic gradient and its numerical
+gradient; the P1 property test (see the correction in §7 P1 — strict per-update energy monotonicity is
+not true and the gate is what replaced it); a measured choice of α, β, γ and `k_min`/`k_max` with the
+sweep recorded in `MEASUREMENTS.md`, nothing copied; the performance budget measured on real topology.
+43 tests across six spec files.
+
+**M0 changed the design in six places**, each with the measurement behind it in `MEASUREMENTS.md` and
+each folded back into §5.2, §5.3, §6, §7 P1 and §7 P5 above. In one line each: the multiplier and the
+penalty band apply only to *hard* rows; the band is a ratio of `m/h²` rather than a stiffness; the PSD
+half of the geometric-stiffness term has to be kept; the 3×3 solve has to be an LDLᵀ; an SPD Hessian
+gives a descent direction rather than a monotone step; and P5's jitter mechanism does not reach soft
+rows, which need M1's damping.
+
+**Deliberately not in M0:** Chebyshev acceleration (§5.2) is gated on a particle not being in contact,
+and contacts arrive at M2, so there is nothing here to measure it against. The velocity clamp named in
+P1 is derived from `ClothDynamics#thickness` and belongs with the component that carries it — and it
+would have masked the property M0 exists to measure.
+
+**M1 — chains end to end. DONE, 2026-09-10.** `Cloth`, `ClothFlags`, `ClothExclude`, `ClothDynamics`,
+`ClothDynamicsFlags`, `cloth_dynamics_library.js`, `ClothSystem`, subtree seeding and write-back, the
+slack and tether rows, the strain-limit row, the inertia model, teleport handling, sleep, and the
+velocity clamp P1 deferred. No collision.
+*Proofs, all green:* P2, P5, P6 and P7, each with a companion test that runs the same scenario with the
+mechanism switched off; `ClothDynamics` value semantics and the measured mapping; three ordering tests
+— the derived order, the recomposition idempotency that makes it not matter, and a bound on the
+divergence when it is inverted; a second playground page, `playground/rig.html`, driving the real
+ECS with a rope, a chain, a five-strand rig under one `Cloth`, a hanging sign with a `ClothExclude`,
+and a nested pair. **43 tests across four spec files** — the leash row's 8, the system's 9, the
+pathology budget's 11, the value semantics and the mapping's 15 — plus 5 for the shortest-arc
+primitive and 4 more in `system_execution_order.spec.js`, for 52 in all. The engine suite is green
+at 18,179.
+
+**M1 changed the design in seven places**, each with the measurement behind it in `MEASUREMENTS.md`
+§9–15 and each folded back above. In one line each: three of §6's clamps had the wrong sign and would
+never have bound; §3.4's leash radius needs a factor of two before `slack = 1` means "no leash"; §7
+P1's velocity clamp cannot be derived from `thickness`, because that is a tunnelling bound and a
+tunnelling bound is *below* ordinary cloth speeds; §11.1's chain bending has no diamond to build a
+hinge on and uses a skip row instead; §11.1's write-back has to write the **local** transform as well
+as the world one; the levers no longer close the frame budget one at a time; and the strain-limit row
+buys a third of the over-stretch rather than the allowance it asks for, which makes `stretch` the
+weakest field in the parameter set.
+
+**And one thing M1 got wrong before it got it right, which is worth recording because the wrong answer
+was plausible.** §4.1 correctly identified that neither of the engine's two ordering mechanisms can
+place cloth after a poser, and the first attempt was to add a third — an execution-phase number on
+`System`, with a `PostPose` value. That put the vocabulary of animation into `engine/ecs`, which has
+none, to buy an ordering the design should not have needed in the first place. Removing the need was
+both smaller and better: writing the local transform makes the write-back idempotent, which turns the
+placement into a bounded quality question and leaves the scheduler alone.
+
+**Deliberately not in M1:** P4(d)'s bounded escape hatch, which needs a per-particle residual monitor
+and belongs with the collision rows that make a particle get *stuck* in the first place — a chain has
+no configuration to be stuck in. Chebyshev acceleration, still gated on contacts that arrive at M2. `β`,
+which M0 could not choose and M1 has no transient rows to choose it with either — every row M1 adds is
+persistent. `ClothSerializationAdapter` and its siblings: nothing in M1's scope list names them, and a
+codec written before `ClothRig` exists would be revised by M3 before it was ever loaded.
+Interpolation: cloth writes `Transform64` at the fixed rate and §12's producer/`__interp_restore`
+contract is not wired, which shows as a cloth updating at the fixed rate rather than the frame rate
+and is a visible-but-not-wrong gap. M5 is where it belongs, with the worker.
+**This is the first shippable feature.**
+
+**M2 — collision. DONE, 2026-09-10.** `ClothCollider`, `ClothColliderFlags`, `ClothColliderSystem`,
+`ClothColliderIndex`, the packed record and its swept bounds, analytic SDF gradients and
+`PlaneShape3D` in `core` (§14.1, §14.3), the contact row and its friction row, the backstop row, and a
+measured `β` and contact penalty band.
+*Proofs, all green:* the packed field dispatch agreeing with the shape objects it was extracted from,
+across all five kinds under a non-axis-aligned pose; the index's swept bounds, layer filter, handle
+reuse and plane handling; the contact row against Coulomb's own answer for a slope; friction's anchor
+dragging cloth with a sliding surface; P3 measured swept against unswept from 2 to 40 m/s; the whole
+stack through a real `EntityManager`, including a collider arriving, leaving, being filtered out and
+waking a sleeping cloth. **53 tests across five new cloth spec files** — 15 for the collider layer, 21
+for the two new rows, 12 for the ECS path — plus **21 in `core`** across two more, for the SDF family
+and `PlaneShape3D`, and the M0 and M1 suites unchanged at 93. The engine suite is green at 18,251. A third playground page, `playground/collide.html`, with six collider
+scenes, a sweep toggle and the contact band live.
+
+**M2 changed the design in six places**, each with the measurement behind it in `MEASUREMENTS.md`
+§16–23 and each folded back above. In one line each: §8.2's swept pose cannot be a lerp of two
+matrices, because that is not a rotation and it shrinks the collider by twice a garment's thickness at
+the anchor's own rotation limit; sweeping the poses does nothing unless the contact **set** is swept
+too, and without that a capsule at 20 m/s produced *no rows at all*; §6's collision and friction rows
+cannot be soft penalties, because a soft row's whole force is 4.6 N against the 376 N an 8 m/s arrival
+needs; friction's clamp is one-sided, because its `C` is a magnitude; §5.4's Jacobi treatment is not
+needed for a collider contact, which is unary; and Chebyshev acceleration, which §5.2 carried as
+available, loses on every axis and is gone.
+
+**Deliberately not in M2:** P4(d)'s bounded escape hatch, still — M2 has the contacts that make a
+particle get stuck, and also measured the one stuck configuration whose *residual is zero*, which is
+the quantity the escape hatch was to watch (§7 P4). It belongs with the self-collision of M4, where a
+particle can be pinched between two rows rather than merely held by one. The backstop row is built,
+specced and driven by the playground, but nothing **authors** one: its plane comes from a garment's own
+skinned surface and a skinned garment is M3. Two-way coupling, per §2. `ClothSerializationAdapter` and
+its siblings, per M1's own reasoning.
+
+**M3 — skinned garments, the rigged path. DONE, 2026-09-10.** `ClothRig`, `ClothProxy`,
+`cloth_proxy_from_joints` (§11.3 steps 5–8), the rig seeder, and joint write-back into
+`Node3D.transform_local`. **The unrigged path is not here** — §11.3 step 9's generated joint set and
+generated skin — and §18 carries what M3 measured about it instead.
+*Proofs, all green:* the P8 corpus for a joint tree, each refusal naming what an author can act on;
+the rig path end to end through a real `EntityManager` — the authority claim, the tether under a
+swinging shoulder, `blend = 0` reproducing the baked bind pose, a model that has not loaded waiting
+rather than failing, a proxy that does not fit its skin refused once by name, and a rigged cape
+colliding with a body; and the entity path unchanged beside it. **23 tests across two new spec
+files** — 12 for the proxy build, 11 for the rig path — plus 14 unchanged for the pose query M3
+refactored. The engine suite is green at 18,274. A fourth playground page,
+`playground/garment.html`, with a `Node3D` skeleton, four garments and four motion profiles.
+
+**M3 changed the design in four places**, each with the measurement behind it in `MEASUREMENTS.md`
+§24–29 and each folded back above. In one line each: §11.2's writable handle is *not* what the
+animation systems write, and cloth has to claim `TransformAuthority.CPU` to make its write-back
+visible at all; §11.1's rig path is not "live" for a rigged garment, because cloth owns those joints
+and their authored pose is the proxy's baked bind pose; §11.3 step 5's weight-derived fixed set is
+the unrigged rule and the topology answers better for a rigged garment; and §11.2's "~60 output
+joints" is four to six times short of what a four-weight palette needs for a few per cent of
+fidelity.
+
+**And the strongest result is a number rather than a correction.** §11 claims the two paths are "the
+solver, identical either way". Built as an entity subtree and as a skin's joints, the same garment
+produces **bit-identical** particle trajectories across three fabrics and three motion profiles.
+That is what the row builder and the pose reconstruction being *one* function each buys, and it is
+why M3 moved both out of the entity path's files rather than copying them.
+
+**Deliberately not in M3:** the unrigged path, per §17's own sequencing and behind §18's measured
+budget. §11.3 step 10's bind-pose collision validation, which `cloth_proxy_from_joints` cannot do
+because it has a joint tree and no collider set — and which `MEASUREMENTS.md` §29 makes the argument
+for, because a garment authored inside its own body reads as a *tether* failure and costs an hour to
+diagnose. `ClothProxy`'s binary codec and `ClothRigSerializationAdapter`, for M1's own reason: a
+codec written before the unrigged path exists would be revised before it was ever loaded.
+
+**M4 — self-collision. DONE, 2026-09-11.** `core/geom/3d/hash-grid/PointHashGrid3.js`, the
+particle-particle row (`solver/constraint/cloth_self_row.js`), the pair search
+(`solver/cloth_self_find.js`) with its exclusion set, and `ClothState`'s pair storage, Jacobi
+scratch and `self_radius`. Wired into `ClothSystem` behind `ClothDynamicsFlags.SelfCollision`,
+which three library entries now set. **M4b is not here** — point-triangle and edge-edge, per §9's
+own deferral — and §34 is the argument for re-pricing it before anyone builds it.
+*Proofs, all green:* the P4 tangle spec extended to self-intersection counts, as this line asks —
+a folding sheet crossing itself, and the row removing more than half of those crossings where the
+same sheet without it does not; the row's sign, and its Jacobi scratch being rebuilt rather than
+accumulated so a pair that separates stops pushing; the exclusion rule against a stretch row, a
+bend stencil and a pinned particle, and each pair found once with the lower index first; and the
+grid's counting sort, its 27-cell walk, its de-duplication across hash collisions and its
+independence from where in space the points sit; and the radius at both ends — a sheet's closest
+ungoverned pair being exactly two hops, strips measuring their gap rather than their link length, and
+a pinned pair not counting because no row will ever act on it. **22 tests across four new spec
+files** — the grid's 9, the search's 4, the row's 4, the radius's 5 — plus the library's
+self-collision assertion rewritten and `ClothState`'s buffer test extended. The engine suite is green
+at 18,296. The garment playground gains a self-collision toggle and a live pair count beside its
+contact count.
+
+**M4 changed the design in four places**, each with the measurement behind it in `MEASUREMENTS.md`
+§30–37 and each folded back above. In one line each: §9's radius is the **proxy's** resolution and
+not the fabric's thickness, which is the difference between removing 21% of a sheet's
+self-intersections and removing 82%; §14.2's 3D hash grid is *not* modelled on the 2D one, because
+a cloth's particles are points without identity that all move every step, so the operation that
+matters is rebuild and insert/remove never runs; §9's list of which entries set the flag was drawn
+along what the garment is rather than how far the fabric bends, and leather — at the top of the
+bend scale — does not tangle at all and is made slightly *worse* by the row; and M4a's normal is
+the line between two particles rather than the surface orientation §9 promises, which satisfies
+what P4(a) is actually asking for and does it more simply.
+
+**And one thing the design had no line for at all.** §9 never wrote a radius down, which is how
+that question stayed open long enough to be got wrong three times. `max(thickness, shortest_row/2)`
+has an upper end: a diameter reaching the closest pair *no row governs* puts a cloth which is not
+folded at all in permanent contact with itself. Leather at 20 mm on a 20 mm proxy is exactly that
+case and found 1,398 pairs a step on a 576-particle sheet that was barely folded (§36). And that
+distance has to be **measured** rather than assumed to be two hops, because two hops is a fact
+about sheets: the playground's cape has 8 cm links and an 8.5 cm gap between strips, half what the
+link length implies, and the assumed ceiling left it with three pairs permanently in contact at
+rest. `ClothInstance#closest_free_pair` is measured once at seed and the ceiling is two fifths of
+it. On a sheet the two rules agree exactly, so §31–36 stand. `MEASUREMENTS.md` §37.
+
+**And the playground earned its keep.** Every measurement from §31 to §36 is on a sheet, because a
+sheet is the only thing here with a surface to pass through. Put the same row on the geometry M3
+actually ships and it does something no sheet could have shown: **without it a cape settles at half
+the width it was drawn at** — 0.178 m against a 0.340 m bind pose — because nothing holds five
+independent strips apart and gravity swings them all into the same place. With it, 0.351 m. That is
+not a transient tangle of the kind §32 measured; it is what the garment settles into.
+
+**Deliberately not in M4:** **conditional storage for the pair list.** `ClothState` is one buffer
+sized at seed, and M4's three self-collision regions are 16% of it on the §17 workload — 100 KB a
+garment — whether or not the flag is ever set, which four of the seven library entries never do.
+Sizing them lazily would make `ClothDynamicsFlags.SelfCollision` a reseed trigger, which it is not
+today, and that is a change to the reseed contract rather than a tidy-up. `MEASUREMENTS.md` §33.
+M4b, above. A **swept pair search** — the set is discovered from the
+positions the last step left, with no margin for the travel of the step about to run, which is the
+shape of the gap §20 found in the contact set. §35 went looking for it and found the opposite:
+widening the search a hundred and fifty times over does not move the crossing count, so what is
+left is not a discovery problem but the tier's own stated limit, and it is M4b's. And **P4(d)'s
+bounded escape hatch**, which M2's entry above handed to M4 on the grounds that self-collision is
+what gives a residual monitor something to escape from — measured across ninety-six fold
+realisations, a self-tangled sheet unties itself every time the gust stops, so M4 still has no
+configuration to escape from. The case P4(d) names is a particle wedged between a collider *and* a
+fold, which is collision and self-collision together, and M4 has not measured it.
+
+**M5 — the worker.** `WorkerClothSystem`, `ClothWorkerCore`, `cloth.worker.js`, the protocol.
+*Proofs:* bit-parity between `ClothSystem` and `WorkerClothSystem` as a standing gate; loopback specs
+covering step ordering, message ordering and shutdown; a measured main-thread cost reduction.
+
+**M6 — wind.** Fluid-field sampling, aerodynamic drag, the ambient fallback.
+*Proofs:* a playground with a banner in a simulated wake; a measured cost showing the per-step sampling
+stays inside budget. Cuttable without affecting anything else.
+
+**Performance budget — measured at M0, re-measured at M1, and it still does not hold on its own.** One
+character's full cloth complement — 1,024 particles at 2 substeps × 4 iterations, on a triangulated
+patch carrying 16.8 row incidences per particle — cost **3.50 ms per frame** at best at M0, against a
+2 ms target. **M1's rows made it 4.61 ms**: the strain limit is 0.73 ms (it doubles the stretch table,
+and the stretch rows are already 69% of the frame), the tether 0.36 ms, the slack row 0.10 ms. What
+that costs the plan is stated below.
+
+The estimate was wrong in its reasoning as well as its number: **gathering neighbour positions is not
+what dominates.** The controlled test is to relabel the source vertices at random, which destroys the
+locality `cloth_color_order` provides and changes nothing else — same colouring, same rows, same
+arithmetic. It costs nothing measurable at the 1,024 particles §17 budgets for (the whole state fits in
+L2) and 11% at four times that size. So the *entire* memory-locality component of the gather is a few
+per cent of the frame, and a layout optimisation has at most 11% to win.
+
+Deleting the workload piece by piece puts 69% of the frame in the stretch rows, 18% in the bend rows
+and 7% in everything else. That is a split of what each row kind *causes*, not of the arithmetic in
+its accumulate: the variants sit in different physical states, and an isolated loop over one accumulate
+measures a converged mesh rather than a moving one and disagrees with the deletion by a factor of five
+on the stretch row. `MEASUREMENTS.md` §7 carries the discrepancy rather than a story that resolves it.
+
+The levers, priced at M0 (`MEASUREMENTS.md` §7) and again on M1's row set (§14):
+
+| Lever | M0's rows | M1's rows |
+|---|---|---|
+| Fewer iterations — 1,024 at 2×**2** | **1.69 ms** inside | **2.38 ms** over |
+| Fewer substeps — 1,024 at 1×4 | **1.68 ms** inside | **2.40 ms** over |
+| Fewer particles — ~500 at 2×4 | **1.54 ms** inside | **2.53 ms** over |
+
+**No single lever reaches 2 ms any more.** Each of them lands inside when a second is spent alongside
+it — 400 particles at 2×4 is 1.72 ms, 576 at 2×2 is 1.28 ms, 1,024 at 1×2 is 1.17 ms — so this is a
+sizing decision rather than a wall, and it is one the library now makes explicitly: every garment entry
+spends two levers and says which two. The barycentric binding fallback from §11.2 is still not needed.
+
+Every figure here is the best of four independent rounds, which agree to ±5%. Cost is close to linear
+in both particles and sweeps, so any one lever is enough on its own and they compose. **Note what the worker does not do:** §12 moves this off the main thread, it does
+not make it cheaper, so "2 ms on the worker" with several characters in flight is a scheduling question
+this measurement does not answer.
+
+**Re-measured at M2, and the library is not re-sized.** M2 adds a broadphase pass per particle per
+step, up to four contact rows per particle, and two field evaluations per contact per iteration. On the
+same workload: 4.43 ms with no collider system against M1's 4.61 — agreement to 4%, inside M1's own
+spread — 4.47 ms with a collider out of range, and 4.6 to 5.5 ms with one to twenty colliders touching.
+The column is not monotone in the collider count, because the variants sit in different physical states
+and a cloth draped over a sphere is not the same workload as one hanging free; §7's warning about
+attributing cost by deletion applies unchanged. What it licenses is that the collision layer costs
+between nothing and a quarter of a frame and does not scale with the collider count over the range a
+character occupies. Every library entry's own budget is untouched. `MEASUREMENTS.md` §23.
+
+Re-measure at M4 and M5.
+
+---
+
+## 18. Risks and open questions
+
+**AVBD has a short track record for cloth. — MEASURED, and the risk was real.** VBD's paper covers
+cloth; AVBD's public reference implementations are 2D and rigid-body-focused. The augmented Lagrangian
+layer is well understood in the abstract, but its interaction with cloth's particular constraint mix —
+many soft rows, a few hard ones, transient contacts — is not something anyone has published numbers on.
+M0 found exactly that interaction to be where the design was wrong: **the multiplier must not touch a
+soft row at all** (it drove a 1 kN/m spring 100× stiffer than Hooke), and **the penalty band is only
+meaningful relative to `m/h²`**, which is a cloth-specific statement because cloth's mass term is four
+orders of magnitude below a rigid body's. Both are fixed and measured (§5.2, `MEASUREMENTS.md` §3–4).
+The core is now stable across 10,000 steps of deliberately absurd cloth, settles a hard chain to 1e-14 J
+at 80 links deep, and reproduces Hooke exactly on a soft row. The §6 row abstraction still means the
+descent loop could be replaced with substepped XPBD without touching the constraint definitions, and
+that fallback still costs one module — but nothing measured so far argues for taking it.
+
+**Per-vertex Hessian assembly in JavaScript may not hit the budget. — MEASURED, and it does not.**
+3.50 ms against a 2 ms target for 1,024 particles at 2×4. *Resolved by:* the plan's own first lever —
+half the iteration count, or half the particles, lands inside — so this is a sizing decision for M1's
+library and M3's proxy rather than an open risk. What is *not* resolved is that the cost is
+concentrated in the stretch row and only a third of that is the gather, so the obvious memory-layout
+optimisation is aimed at the smaller half. `MEASUREMENTS.md` §7.
+
+**System ordering. — DISSOLVED rather than resolved.** §4.1 carries the reasoning; in short, the
+derived score is a *sum* over what a system references, so touching more can only move a system
+**earlier**, and a consumer of a posed hierarchy touches strictly more than the poser. There is no
+declaration cloth could have made, and registration order does not break a non-tie. The engine has two
+ordering mechanisms and neither expresses this.
+
+The answer is not a third mechanism, it is not needing one: cloth writes each node's **local**
+transform alongside its world one, so a hierarchy recomposition reproduces the simulated pose rather
+than replacing it — measured at 1.7e-15 m — and the placement stops being a correctness question.
+*What is left, and it is a real cost:* running before the poser means the cloth's shape is one fixed
+step stale, which measures at a few centimetres on a 1.6 m rope under ordinary motion and up to a
+fifth of its own length at the sharpest reversal of a ±9 m/s square wave. It does not accumulate.
+An application that cares registers accordingly and gets nothing, because this is not a tie; an
+application that does not care is unaffected, which is the common case and the one this trades for.
+`MEASUREMENTS.md` §15.
+
+**The unrigged path's joint budget. — MEASURED, and §11.2's guess was low.** A rigged garment costs
+nothing new; an unrigged one needs a generated joint set, and how many joints a drape takes through a
+four-weight palette was an open empirical question. M3 measured it: a 33×33 cape simulated at full
+resolution, reconstructed by linear blend skinning from k-by-k fitted joints, error against the
+reference. **RMS error is inversely proportional to the joint count** — the product is flat across a
+factor of 72 in joints — and the worst case falls as about `N^−0.83`. At §11.2's "~60 output joints"
+the worst-case error is 5% of the garment's own size, which is five grid cells and reads as faceting;
+**80 to 120 joints** puts it inside one. A crumpled cloth needs about three times as many, so the
+number is per-fabric rather than per-garment. `MEASUREMENTS.md` §28. The barycentric deformation pass
+(§11.2) remains the designed fallback.
+
+**Per-joint frames. — MEASURED, and the degeneracy did not happen.** A particle has a position; a
+joint needs an orientation, fitted from a neighbourhood every frame, and §18 expected "a fold that
+collapses a triangle fan" to have no well-defined frame. Across 800 frames × up to 121 joints,
+including a deliberately crumpled variant with bending at 1e-7 and a gust four times as hard, the
+count of degenerate fits is **zero**. The mechanism is that a tangent is a difference across two
+links and the stretch rows are hard, so each link holds its length and the only way the difference
+vanishes is a fold of exactly 180° at the joint's own vertex. That is possible rather than forbidden,
+so a future unrigged path keeps the epsilon and the fallback; it is no longer the thing to be most
+worried about. `MEASUREMENTS.md` §28.
+
+**Quadratic bending cannot hold a curved rest shape.** A garment authored with a strong permanent curve
+will relax flatter than intended. M0 measured the exact boundary: the stencil annihilates the rest shape
+and **every affine image of it** — which is every in-plane deformation to first order, so a flat sheet
+being sheared, stretched or rotated stays at zero bending energy — but it does *not* annihilate an
+arbitrary planar configuration. Four coplanar particles that are not an affine image of the rest four
+read as bent. *Mitigation:* accepted for the fabrics the library targets. If a case appears, the fix is
+a rest-curvature offset in the stencil, which is a change to one row and not to the solver.
+
+**Swept collision is translation-first, and it is two mechanisms rather than one. — MEASURED.** P3
+states the limit. M2 found that the half nobody had written down — sweeping the contact **set**, not
+just the poses — was the half that mattered: without it a capsule at 20 m/s created zero rows and the
+sheet was never touched. With the collider's travel folded into the discovery reach, 2 to 40 m/s all
+behave. What remains is that both halves are built from the collider's *centre*: a collider spinning
+fast enough that a point on its surface travels more than its own radius within one substep can still
+be missed. *Mitigation:* more substeps in the affected `ClothDynamics`; genuine CCD stays out of scope.
+The shape of a fix, if one is ever wanted, is to build the discovery margin from the swept **surface**
+travel — `|Δt| + θ·R` — which is one more term and no new structure. `MEASUREMENTS.md` §20.
+
+**Open — a rigid collider driven through pinned cloth wraps rather than parts.** A contact row bounds
+the interpenetration; it cannot prevent it, because the cloth has nowhere to go. The playground's
+spinning-bar scene is the case, and it settles at 18 mm inside a 25 mm bar. This is not a solver
+failure — a kinematic collider is infinitely strong by construction and the cloth is inextensible and
+pinned — but it is the configuration a garment author will find first, and the answer is authoring
+(a collider that does not sweep through the garment's own plane) rather than a solver mechanism.
+
+**A soft-row cloth does not come to rest. — CLOSED by M1's damping, and the size is measured.** M0
+measured a soft chain landing in a bounded limit cycle that 2,000 further steps do not move, and no
+solver constant reaches it, because `α·γ` decays a multiplier and a soft row has none. `damping` does
+reach it: on the configuration §6 measured, 2.90e-3 J undamped against 1.28e-6 J at the library's own
+`damping = 0.12`, and 1.82e-12 J at the top of the range. `cloth_pathology.spec.js` gates on exactly
+that pair.
+*What this does not claim:* damping does not stop the step adding energy, it removes energy faster than
+the step adds it. The equilibrium is bounded rather than zero — which is why the numbers keep falling
+all the way to `damping = 1` instead of hitting a floor — and a cloth whose rows are soft and far above
+the dissipative band is still a cloth being rescued rather than a cloth behaving. M1's mapping does not
+produce one; the gate exists so a future mapping that does is caught. `MEASUREMENTS.md` §12.
+
+**The escape hatch could mask authoring errors.** P4(d) rescues a stuck particle, which means a badly
+authored garment can look acceptable while relying on it. *Mitigation:* `ClothDiagnostics` counts
+escape-hatch activations per cloth and surfaces them, so "this garment is being rescued 30 times a
+second" is visible rather than invisible.
+
+**Open — two-way coupling.** Cloth does not push rigid bodies. The row model could carry it (the
+collision row's multiplier is a force, and applying its negation to the collider's body is mechanically
+straightforward), but the stability of that loop across two solvers with different time discretisations
+is a real question and is not answered here.
+
+**Open — the fixed set for an unskinned surface, and M3 found there are three rules rather than
+two.** Step 5 of §11.3 derives the fixed set from skin weights, which is right for a garment on a
+skeleton. A **rigged** garment does not need weights at all: the topology answers, and a joint whose
+parent is outside the proxy is the fixed set (§11.3, corrected). What is still open is the third
+case — a flag, a curtain, a banner that is not skinned at all — where there is neither a joint tree
+nor a weight to read. Those also sit at `slack ≈ 1` by necessity, so the tether carries all the
+inextensibility, but the fixed set still has to come from the mesh boundary or from authoring, and
+neither is built. It belongs with the unrigged path, which is where a mesh first becomes a particle
+set.
+
+**Open — LOD.** Distance-based particle-count reduction would need either multiple baked proxies per
+garment or a runtime hierarchy. Culling (§12.1) covers the off-screen case; the far-but-visible case is
+unaddressed.
+
+**Open — `stretch` is a weak control, and it is not obvious what would make it a strong one.** M1
+measured the strain-limit row removing about a third of the peak over-stretch and never reaching its
+own allowance, because it is a second hard row competing with the first for the same trust region and
+the same penalty band (§6). A fabric's *extension* is therefore governed by the iteration budget more
+than by the fabric, and the library says so by which entries build the row at all. Three things might
+change that and none is free: a soft fabric row inside the dissipative band with the hard row acting
+only as the limit (which reintroduces M0's settling problem at any realistic stiffness); a per-row
+penalty band, making `k_max/(m/h²)` a material property rather than a global (which `MEASUREMENTS.md`
+§4 shows trades stretchiness against settling); or accepting that near-inextensibility is what fabric
+*is* and demoting `stretch` to a documented weak knob. M2's contacts do not bear on it either way.
+
+**Open — the write-back has no interpolation.** §12 gives cloth `PhysicsSystem`'s producer /
+`__interp_restore` contract, and M1 does not wire it: cloth writes `Transform64` at the fixed rate and
+nothing blends between ticks, so a cloth updates at 60 Hz on a 165 Hz display. That is visible and it
+is not wrong — the poses are authoritative, they are simply held. It lands with M5, where the worker
+makes the fixed-step producer contract load-bearing for a second reason.
+
+**Open — the subtree is walked once.** A rope's links do not come and go, so `cloth_seed_subtree` runs
+on first step and `ClothSystem#reseed` is how a caller says the structure changed. That is the same
+contract `TransformAttachment#parent` already carries, and it is the right default; what it does not
+have is a way to *notice*. An entity added under a live `Cloth` is silently not simulated until
+someone re-seeds, which is a class of authoring mistake with no diagnostic behind it. `ClothDiagnostics`
+is where one would go.