@woosh/meep-engine 3.21.0 → 3.23.0

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

@@ -0,0 +1,1967 @@
+# 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.