@woosh/meep-engine 3.60.4 → 3.60.6

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

@@ -1,3056 +0,0 @@
-# Cloth — Design
-
-> Design document. Written 2026-09-10; **M0 through M5 are implemented** — the solver, chains,
-> collision, the rigged path, self-collision and the worker — 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 — and,
-  built from triangles by `cloth_proxy_from_mesh`, a sheet: a flag, a curtain, a cloth thrown over a
-  table (§19.5).
-- **`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.
-- **`ClothPin`** — *M7.* Put it on any entity and that entity holds the particles it names. A cloth
-  has as many holders as name it — a rope its own top, a flag its pole, a cape both shoulders — and
-  none is a cloth that falls. §19.
-
-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 included.
-// What holds it is a ClothPin: here the top holds its own particle, 0.
-rope_top.add(Cloth.from(ClothDynamics.ROPE));
-rope_top.add(ClothPin.from({ cloth: rope_top, particles: [0] }));
-
-// 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.
-
-**M7 note: what holds a cloth is not part of it.** Every sentence below that says "the anchor" meant
-three things at once — the frame the cloth is simulated in, the particle it was pinned at, and what
-its tethers measured from — and only the first is the `Cloth` entity's. The fixed set is now whatever
-`ClothPin`s name (§19), any number of them, and the rest of the "anchor" sentences are read through
-§19.
-
-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).
-
-**M7 corrected "the anchor is the entity the component is on".** The entity is the cloth's **frame**:
-what it is simulated in and what §7 P7's inertia is measured against. It is still particle 0 of the
-walk — links run from it — but nothing pins it: a `ClothPin` on it does, `ClothPin.from({ cloth: e,
-particles: [0] })`, and without one the rope falls while the entity, which cloth reads and never
-writes, stays where it is. That is the price of there being no structural pin, paid in one line per
-rope, and §19 has why it is the right one.
-
-`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 = -1;      // the entity whose MeshSkin 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's entity, and the asset pipeline resolves the rest.
-
-**The skin is an entity's, named by entity** (2026-10-11). `skin` was an ordinal into the skins of
-whatever `MeshSystem.instance_of` answered for the cloth's entity, which made a rig reachable only
-through a loaded model. A skin is now a `MeshSkin` component on the mesh it deforms, and the rig
-names that entity; a mesh built in code is rigged the same way as a loaded one. -1 means not named
-yet, and waits like a model still loading.
-
-**The proxy addresses joints by index, never by name.** The binding is resolved **once, at import**:
-the builder turns authored bone names into integer indices into `Skin#joints`, and the runtime
-component holds integers. Reintroducing strings at runtime would be the wrong answer.
-
-**A joint is an entity, and this paragraph used to say it could not be.** It said "a joint is a
-`Node3D` inside a `SceneBundleInstance`, not an entity, so an `EntityReference` to one is impossible
-by construction", and the engine moved: a model is spawned by `prefab_instantiate`, its joints *are*
-entities, each carrying a `TransformAttachment` holding its offset from its parent joint, and that
-attachment is what `cloth_write_back_rig` writes. Names are resolved through `Prefab`/`PrefabInstance`
-rather than through `SceneBundleInstance#nodes`. The *conclusion* is unchanged and is now better
-supported — indices into `Skin#joints` are stable across respawns where entity ids are not, so the
-proxy still holds integers — but it is a choice rather than an impossibility. §11.2 and §13 carried
-the same description.
-
-### 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 = ClothDynamicsFlags.StrainLimit;   // | 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). *M7: not any more — a
-  held particle is kinematic, inverse mass zero, carried by its holder (§19); `d_geo` is its distance
-  to the nearest held particle along the fabric, and the animated position `s_i` is the rest pose hung
-  from that particle. The factor of two still holds exactly: `|s_i − x_p| = |r_i − r_p| ≤ d_geo`.*
-- **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: none defined; bit 0 was Static, retired
-}
-```
-
-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
-    ClothWorld.js                   every cloth in a scene, and everything that is not arithmetic
-    ClothSystem.js                  main-thread system: a ClothWorld stepped inline
-    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: the same ClothWorld, stepped over there
-    ClothWorkerCore.js              worker side: a ClothState view per registered cloth
-    cloth.worker.js                 the entry point, a real module worker
-    makeClothWorker.js              the spawn expression, isolated because it needs import.meta
-    cloth_worker_protocol.js        the command region: a count, then a block per cloth
-    ClothSerializationAdapter.js    the component + its ClothDynamics, by value
-    ClothPin.js                     component: this entity holds these particles of that cloth (§19)
-    ClothPinSerializationAdapter.js the pin, with its cloth as a raw entity id
-    ClothHold.js                    one pin as the cloth sees it: offsets, the holder's pose
-    cloth_holds.js                  what holding decides: who is kinematic, tethers, the animated pose
-    cloth_geodesic.js               distance along the fabric from a set of particles
-    ClothColliderSerializationAdapter.js   five authored scalars, the same way
-    ClothRigSerializationAdapter.js NOT BUILT — §3.2's asset identity, and the proxy codec
-  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
-  wind/
-    AbstractClothWind.js            §10's one interface: sample the air, and say whether it varies
-    ClothGPUFluidWind.js            the GPU wind: lattices read back from GPUFluidSystem, the far field elsewhere
-    ClothFluidWind.js               every live FluidComponent, with the scene's far field underneath it
-    cloth_sample_air.js             the air into the cloth's own frame, on the main thread
-  solver/
-    ClothState.js                   SoA particle + topology + constraint storage over one buffer
-    cloth_step_instance.js          one cloth, one step, over nothing but memory — what crosses
-    cloth_step.js                   the fixed step: predict, warm start, iterate, dual update, integrate
-    cloth_solve_vertex.js           the per-vertex 3x3 block update
-    cloth_wind_accelerate.js        §10's aerodynamic term, and the factor that makes a flag a flag
-    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.
-
-  **M5 note: it owns it jointly with `WorkerClothSystem`, and "two systems" is now three.** The two
-  are interchangeable — same components, same declared access, same position in the derived order —
-  and they share a `ClothWorld`, which is the registry and every phase of a step that is not
-  arithmetic. `ClothSystem` calls `cloth_step_instance` between the two halves; `WorkerClothSystem`
-  puts a thread there. §12 has why that is what makes the bit-parity gate structural.
-
-Cloth runs at the fixed rate and its poses are **held** between ticks rather than interpolated, which
-on a display faster than the fixed step is visible and is not wrong. The first draft of this paragraph
-said cloth reuses `PhysicsSystem`'s producer/`__interp_restore` contract; M5 measured that it cannot —
-that contract is entity-keyed and a rigged garment's joints are not entities — and §13.1 and §18 carry
-what the cloth-shaped version would be and what it would cost. What keeps a cloth-driven bone from
-fighting an animation-driven one is not interpolation but `TransformAuthority`, which `cloth_seed_rig`
-claims (§11.2, `MEASUREMENTS.md` §25) — as a hold since §61, because the bit alone never stopped a
-clip on the GPU.
-
-### 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)
-
-               last iteration only, when the held particles lie on one line (axis a through o):
-                 for each free particle i:  r_i = x_i − o,  t_i = a × r_i
-                   ∇E_i, H_i = the vertex update's inertial term + leash, backstop, contact rows
-                 g = Σ t_i·∇E_i
-                 H = Σ t_iᵀ·H_i·t_i + max(0, Σ ∇E_i·(a(a·r_i) − r_i))
-                 turn every free particle about the line by θ = −g/H
-
-               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)
-                 (a contact's normal row: k_c ← min(k_c + ρ·k_max·s_c·|C_c|/offset, k_max·s_c))
-
-integrate    v_i = (x_i - x_i^prev)/h
-```
-
-A contact's warm start differs in one line from the listing above: its two penalties decay by
-`γ_c = CLOTH_CONTACT_GAMMA` rather than `γ`, the multipliers by `α·γ` as every hard row's do. The
-correction below is why.
-
-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 at M0: **α = 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.
-
-**M2 made the band real and the line above is out of date in three places.** `β` is **1e3**, not 1e5:
-M2's contacts are the first transient rows in the system and the ramp is finally live, and both ends
-of the range measured worse than the middle — no ramp at all settles at 1.95 J of residual kinetic
-energy against 0.12 J at 1e3, a fast ramp gives up most of what the low floor bought
-(`MEASUREMENTS.md` §17, and `cloth_solver_constants.js`'s own docblock carries the argument). The band
-is no longer a single point for a **contact**: `CLOTH_CONTACT_K_MIN_RATIO = 0.25` is its floor,
-against a ceiling of `8·(m/h²)` — a margin decision in the middle of a flat region, with two decades
-of ramp above it. And `γ` **is still 1, and was never re-measured**: this paragraph said it would be
-"when M2's contacts make the band real", M2 made the band real, and the sweep was not run. That is now
-a decision rather than an omission — nothing measured since has asked for a decaying penalty, and the
-one place it would help is recorded in §18 as a coupling rather than as a bug — but it is an
-**unmeasured** constant and the only one left in the set, so it is named here as one.
-
-**The cloth-skirt example corrected the contact's ramp and gave it a decay (`MEASUREMENTS.md` §67).**
-A thigh advancing 17 mm a substep into a hanging skirt showed through it in 12.7% of the dance's
-steps, up to 13 mm, and four times the iteration budget made that zero: the row was arriving soft.
-`β = 1e3 N/m²` against that garment's band of 72 to 2,300 N/m is **0.003 of the band per contact
-offset of violation**, so against a limb the penalty never left the floor and the multiplier, rebuilt
-from a quarter every substep, could not carry the push in four iterations. The ramp is a ratio now,
-`ρ = CLOTH_CONTACT_RAMP_RATIO = 0.1` of the band per offset of violation per iteration, which keeps the
-shape the M2 measurement picked in the units the contact is defined in: 12.7% → 0.1% of steps, M2's
-landing sheet 1.10 → 0.68 mm, M2 §6's swept capsule 17 → 1.8 mm, the tunnelling threshold unmoved.
-It ramps whether or not the row is active, as before: ramping active rows only, the reference
-implementation's form, leaves the thigh through ten times as often and takes the thrown particle's
-stopped speed from 6 to 4 m/s at two substeps, which is §18's one-sided finding again.
-
-What a ratio ramp does to a **resting** contact is what §18 predicted: every row violated by
-millimetres while a pile lands is at the ceiling for good, where §53's limit cycle is too large for
-silk to sleep — §64's ribbon pile never slept, the twirled skirt settled 17 mm from where it hung, the
-draped sheet was carried 4° less. The resolution is the one §18 named, a `γ < 1` for contacts:
-`γ_c = CLOTH_CONTACT_GAMMA = 0.8` decays a contact's two penalties per substep while the multiplier
-carries the load, and every scene sleeps as before (erratic at 0.7, slow at 0.5; decaying the normal
-penalty alone leaves the resting rope's sleep a coin toss, so both decay). Its cost is static
-friction's exactness: a sheet on a slope it should stick to creeps 0.2–0.3 mm in four seconds, and
-the marginal case, μ a tenth over the tangent, slides 0.55 m where the old ramp slid 0.19 — the ratio
-ramp without the decay made that case stick exactly, so the two together are a trade, not a free win.
-
-**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.
-
-**M7 added one block to the descent: the turn about a hold line** (`cloth_hold_line.js`). Every vertex
-update is a 3×3 block, and a cloth whose held particles lie on one line has a motion no such block can
-make — turning about the line as a rigid body. A vertex update moves one particle, so each adds
-`x_i × m·Δx_i` of angular momentum about the line, and the step stopped at a fabric's iteration count
-leaves a gradient along the turn. About a vertical line nothing restores it, and the warm start's
-`α·γ = 0.25` means a cloth at rest re-solves three quarters of its weight every substep and is never a
-fixed point: a flag on a pole turned for as long as it was run (§18).
-
-So the turn gets its own block, in the listing above: one Newton step of `E` along it, in the last
-iteration, after the sweep and before the dual update. Internal rows are invariant under the turn —
-their ends turn together, or one of them is on the axis — so only the inertial term and the unary rows
-enter. The last term of `H` is the path's own curvature, `d²x/dθ² = −r⊥`: near zero about a vertical
-axis, the pendulum's gravity stiffness about a horizontal one, and added only where positive so the step
-is never longer than the one without it. It is a descent step on the same energy, so §5.3 stands, and it
-changes no row, multiplier or constant. It runs when the held particles lie on one line at that substep,
-at two distinct points or more, to `2⁻¹⁶` of their largest coordinate. That is a runtime fact about the
-holds, and the predict, which carries every held particle, lists them on its way.
-
-What it does not cover: a single held point has three free turns and a cloth nothing holds has six, and
-neither is handled. On a line gravity does restore it has slowed some sleeps and kept one cloth awake
-(§18). Carrying the multiplier instead — AVBD's Eq. 18, or the reference code's post-stabilisation —
-stops the turn too, and fails six to ten of the cloth gates. `MEASUREMENTS.md` §66.
-
-### 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
-greedy colouring in `core/graph/csr/csr_graph_color_greedy.js` and checked by
-`csr_graph_validate_coloring.js`, over the deduplicated particle-coupling CSR that
-`solver/cloth_particle_coupling.js` builds (the object `Graph` route was O(n²·degree): 134 ms → 3.5 ms
-on a 64×64 sheet, same colours). 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 that
-CSR, 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.)
-
-**M7: and there still is none, but a pin is not a row either.** The anchor was pinned by inverse mass
-zero all along, and that is what a hold is: a kinematic particle carried to where its holder puts it,
-an equal share of the way at each substep (§19). Both leash rows now measure from a **particle** —
-`ClothState#leash_source` and an offset, re-centred every substep after the held particles move —
-because a centre written once a step sits a step behind a held particle that is moving, and a hard
-row measured from a stale point fights the hold. The tether's centre is the nearest held particle,
-not "the anchor"; a particle nothing holds has both rows at radius `Infinity`, skipped before any
-arithmetic.
-
-**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 the flag defaults to *set*, which is the opposite of what §3.3 used to show.** `ClothDynamics`
-starts at `ClothDynamicsFlags.StrainLimit`, so a garment that says nothing gets the row. Of the four
-library entries at 2×4, three clear it — silk, cotton and hair, and they clear it by writing
-`flags: ClothDynamicsFlags.SelfCollision`, which *replaces* the default rather than adding to it — and
-**`CLOTH_ROPE` does not**: it sets no flags at all, so it keeps the default and runs the strain-limit
-row at 2×4. That is the right answer for a rope, whose `stretch` is its most characteristic property
-and whose forty particles make the row free (`cloth_dynamics_library.js` says exactly that), but "the
-library entries at 2×4 clear it" was never true of 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. **The gate is those figures doubled, not those figures**: the spec
-holds 3% / 2 on the absurd fuzz and 0.01% / 0.5 on the cape, which is twice each measurement rather
-than the measurement itself. The last sentence of this paragraph used to claim otherwise. The margin
-is deliberate — a full step's energy behaviour is a distribution over a fuzz corpus and a gate pinned
-to its own sample is a gate that fails on an unrelated change — but "a change that makes it worse
-fails" is true only of a change that makes it *twice* as bad.
-
-**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.
-
-**Post-M6 found the mirror case, and M2 had argued it away rather than measured it.** (a) folds the
-*collider's* travel into the discovery reach and nothing folds in the *particle's*, so a **static**
-collider is only ever discovered within `2·(thickness + inflation)` — 16 mm for a garment, which is
-half a metre a second of approach. The docblock said anything faster was already bounded by §7 P1's
-velocity clamp; that clamp is `4 · shortest_row · substeps · iterations / dt`, about **154 m/s** for a
-garment, and everything in between was uncovered. Measured, one particle at 8 mm thrown at a static
-3 cm capsule with no gravity at 2 × 4: **no row is ever created before the particle is already
-inside, at any speed**, and from **3 m/s** the row the next step finally makes is evaluated on the far
-side and pushes it the rest of the way out — which is P4(a)'s orientation-over-history choice
-collecting its bill when discovery is late. The reach now carries `|v_i|·dt` per particle as well.
-That is free at rest and 0.8% of a step for a cloth falling at 3 m/s, and `cloth_library_bench.mjs`
-cannot see it because the bench has no colliders. `MEASUREMENTS.md` §54.
-
-*Limit, stated:* all three 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.
-
-*And the second limit, which post-M6 measured rather than assumed:* **discovery being right is
-necessary and not sufficient.** A row that exists is still evaluated at substep positions, so a
-particle crossing a whole collider inside one substep has a row that never sees it touching. Swept,
-in half-metre steps from 1 to 12 m/s, the particle is stopped up to **6.0 m/s at two substeps and
-through the whole range at four** — a clean threshold, and it is `ClothDynamics#substeps` rather than
-the reach. This row has always said "more substeps in the affected `ClothDynamics`"; that is where it
-lands.
-*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. The mirror — a particle thrown at a *static* capsule from 1 to 10 m/s, with a step
-length of zero standing in for the unswept side — is in `cloth_contact_row.spec.js`.
-`cloth_collision.spec.js` carries the ECS-level companion of both.
-
-**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. **NOT BUILT, and this row is the design for one rather than a
-  description of one.*** 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, and counted in
-  `ClothDiagnostics` so that a garment relying on it is visible rather than silently rescued.
-
-  **It has been deferred at every milestone that could have built it** — M1 for want of a residual
-  monitor, M2 to M4 on the grounds that self-collision is where a particle gets *pinched* rather than
-  merely held, M4 onward as still open — and it is deferred deliberately rather than forgotten: M2
-  measured the one stuck configuration whose residual is **zero** (§7 P4's own note, `MEASUREMENTS.md`
-  §22), which is the quantity this row watches, so the mechanism would not have caught the case that
-  motivated looking for it. The sentence that used to stand here said "on by default with a
-  conservative threshold", which read as a shipped default and was never true of any build.
-  `ClothDiagnostics` is not built either; every reference to it in this document is a design for one.
-  What *is* shipped and does the job an author reaches for is `Cloth#blend` (§3.1), which is the same
-  blend applied deliberately instead of automatically.
-
-*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, a collider arriving or leaving, or a
-`ClothDynamics` change.
-
-**Post-M6 note, and "wake on collider motion" was the wrong question.** Motion is what the test asked
-and it is not what a sleeping cloth needs to know. `ClothColliderSystem#link` **places** a new
-collider — previous pose equal to current, deliberately, so its first step sweeps nothing — so a
-collider *spawned* inside a sleeping cloth has not moved and never woke it. Measured: a 6-link rope
-settled and asleep, a sphere of radius 0.2 spawned around its lower half, still asleep 300 steps later
-with **4 of its 6 links inside**. §1's first commitment names exactly this case. The test now also
-compares the **set** of handles the broadphase returns with the set the cloth last stepped against —
-one integer per record, against a pose comparison that was already there — so a collider appearing or
-leaving wakes it whatever the poses say. Its own limit, stated: a `PlaneShape3D`'s AABB is unbounded,
-so a plane is in every cloth's set the moment it exists and every sleeping cloth wakes once when one
-appears anywhere in the scene. It finds nothing, and sleeps again thirty steps later.
-
-**Post-M6 note, and it is this row's own sentence coming true two milestones late.** "Maximum particle
-displacement over a window" is what this row has said since M0 and it is not what M1 built: M1's test
-is the largest particle **speed** the step produced, held under `CLOTH_SLEEP_SPEED_RATIO · reach` for
-`CLOTH_SLEEP_STEPS`. On a free-hanging chain the two agree. On a cloth **resting on a collider** they
-do not, and the gap is total: four of the seven library fabrics — cotton on a floor with or without
-friction, leather and rope on a floor with it — **never sleep at all**, where the same rope with no
-collider under it sleeps at step 283. The cause is not friction, which the frictionless column rules
-out; it is that a contact's penalty ramps by `β·|C|` and `γ = 1` never brings it down, so what a
-resting cloth settles into is a **bounded limit cycle** rather than a rest state: measured on cotton,
-a tenth of a millimetre of travel a step — invisible — at a peak speed of 1.5e-2 m/s, eighteen times
-the threshold. Displacement tells those apart and an instantaneous speed cannot. The sleep test now
-reads displacement from a window anchor, at `CLOTH_SLEEP_DISPLACEMENT_RATIO = 5e-4` of reach, chosen
-to be no *looser* than the speed test it replaces rather than the fastest value that works; every
-entry on a floor and on a sphere then sleeps within **961 steps**, and the free-hanging column gets
-uniformly faster rather than slower. The limit cycle itself is recorded and not fixed — `γ` is
-unmeasured-by-decision (§5.2) and a tenth of a millimetre is not a rendering problem.
-`MEASUREMENTS.md` §53.
-*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.
-**M6 note: a cloth also wakes on the air changing, and the test has one sample in it.** §10's "sleep
-wakes on a wind change" is the same shape as the collider test beside it — ask a question three orders
-of magnitude cheaper than the step it decides whether to skip — and the question is the air at the
-cloth's own centre against the air the last *applied* step saw. The last applied rather than the last
-sampled, so a gust that builds slowly accumulates instead of being reset by every step that declined
-to act on it. *Its limit, stated:* one point. A gust that reaches only the hem of a sleeping banner
-and leaves its middle still will not wake it. The collider test has no such gap because a collider's
-pose is seven exact numbers and a field is a continuum.
-
-*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. (Those two figures are the speed test's; the post-M6 note above replaced it, and every
-entry sleeps sooner under the displacement window than it did under the speed one.) 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`.
-
-**M7: a holder can jump too, and it is measured in the frame.** A rope tied to a ship that is moved
-across the map has a frame that did not move and a holder that did. The test is now the frame's jump
-in the world *or* any holder's jump in the frame, against the same threshold. `Reset` puts every
-particle on the animated pose hung from where the holders now are, held particles on their targets so
-the jump is taken between steps rather than dragged through one; `Keep` does nothing for the frame, as
-before, and for a holder applies that holder's own jump to what hangs from it. Measured: a hand holding
-a rope's top, moved a kilometre in one step, resets once and peaks under 5% of the velocity clamp
-(`cloth_pin.spec.js`).
-
-**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.
-
-**M7: the frame is the only motion this softens.** A holder moving *relative to the frame* moves its
-particles in full — that is what holding means — so P7's limits protect a cloth whose holders ride its
-frame, which is every garment and every rope hung from its own top. A cloth held by something that
-moves independently — a banner between two characters — feels that motion unsoftened, and the frame
-it should ride is the author's choice, as Chaos Cloth's reference bone is. What bounds such a cloth is
-P1's clamp and P2's authority: measured, a hand dragging a rope at four times what one step can
-correct stays under the clamp every step and is back inside 1% of its tether within ten seconds of
-stopping (`cloth_pin.spec.js`).
-
-**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 *not* `physics/contact/combine_material.js`, and this paragraph used to say it
-was.** Nothing in `cloth/` imports that module. `combine_material` answers a different question — how
-two *bodies'* materials combine into one contact coefficient, which is a `sqrt(μ₁·μ₂)`-shaped rule
-over a symmetric pair — and cloth's question is not symmetric: one side is a collider with a material
-and the other is a garment with an opt-in scale on top of it. `ClothColliderSystem` therefore packs
-`Collider#friction · ClothCollider#friction_scale` into the index record, one multiply at link time,
-and a `friction_scale` of 1 means "whatever this surface already is". The *claim* the old sentence was
-making — that cloth and rigid bodies agree about what a surface feels like — is still true and is why
-`Collider#friction` is the base: what is not true is that the agreement comes from sharing a function.
-§13's reuse ledger carried the same wrong entry.
-
-**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. And the
-row is **the particle's own** (`ClothState#self_row`), a pair's reach the sum of its two radii: a circle
-skirt's hem has rows five times the waistband's, and one radius per cloth gave it the waistband's, a
-fifth of its spacing, with the flutes through each other at every sample. §67, §68.
-
-**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 `cloth_build_rows` measures
-it once at seed, in the bind pose, per particle into `ClothState#self_free_pair`, and the ceiling is
-two fifths of it. `MEASUREMENTS.md` §37, §68.
-
-"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 at the
-stiffness M4 shipped, `8·(m_eff/h²)`, which §32 chose on a folding sheet's crossing count.
-**Post-M7 corrected the stiffness to `2·(m_eff/h²)`.** §32's sheet showed no energy growth at 64×
-because its contacts come and go. A fold resting on a fold is a pair that carries weight, a spring
-that is on every step, and at 8 it never comes to rest (§18). 2 is the stiffest ratio that lets it,
-and it removes 63% to 71% of the folding sheet's crossings rather than 73% to 79%.
-`MEASUREMENTS.md` §32, §65.
-
-*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 = response · facing · (u_air − v)`.
-
-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.
-
-*Corrected by the GPU wind fluid's S5 (`../fluid/GPU_FLUID_CASCADES_PROPOSAL_2026_10_16.md` §12, G2):*
-the fallback is no longer cloth's own. It is the scene's **far field** — its `GlobalFluidEffector`s,
-gust included, folded by `FluidEffectorsSystem` once a tick — which is what the shape above was
-always copying. `ClothAmbientWind` is retired; `ClothGPUFluidWind` reads the GPU wind and
-`ClothFluidWind` the CPU fields, each with the far field underneath. `MEASUREMENTS.md` §69.
-And cloth reads it **by default**: with nothing assigned, `ClothWorld#wind` is a `ClothGPUFluidWind`
-while the scene has an enabled `GPUFluidComponent`, else a `ClothFluidWind` while the far field is not
-zero, else `null` as before — decided again every tick from those facts, so a scene without wind gains
-no drag. An assigned source, `null` included, always wins.
-
-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.
-
-**M6 built it and corrected this section in four places.**
-
-**The factor above is not `|n·û|`, because half of what this system simulates has no `n`.** This
-paragraph originally wrote the term as `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". It is right about what it wants and wrong that a normal is available to want it
-with. A chain's particles span a **line** — every direction perpendicular to it is equally a normal,
-so picking one is the history-dependent fabrication §7 P4(a) exists to keep out — and a rope's
-aerodynamics are the *complement* of a sheet's anyway: it catches the flow across it and slices along
-it. Both are one quantity, **the part of the flow the particle's own incident rows cannot let past**:
-take the span `T` of the directions to its stretch-row neighbours in the current configuration, and
-`facing = ‖û − proj_T(û)‖`.
-
-| rank of `T` | what the particle is | the factor |
-|---|---|---|
-| 2 | a point on a surface | `\|û·n\|` with `n = b₁×b₂` — this paragraph's own expression |
-| 1 | a link of a chain | `√(1 − (û·t)²)` — the cross-flow, which is the rope's answer |
-| 0 | an isolated particle | `1` — a bead has no preferred direction |
-
-One expression, three topologies, no stored normal, no orientation, no sign, nothing carried between
-steps. `MEASUREMENTS.md` §47.
-
-**And the factor's headline claim is about *laminar* air, which is a limit rather than a fault.** On
-the playground's banner, turning a uniform wind through ninety degrees takes the mean factor from
-0.221 to **0.000** and the aerodynamic acceleration from 43.2 m/s² to 0.08 — a flag becoming a rope,
-exactly as promised. Turning a **wake** through ninety degrees does nothing at all: 0.216 to 0.280. A
-wake has velocity in every direction, so no orientation of a surface is edge-on to one, and the factor
-is correctly reporting that there is nothing to slice through. That makes this section's argument for
-reading a simulation *stronger* than this section knew. `MEASUREMENTS.md` §51.
-
-**`drag` is not what multiplies the flow, and the difference is a stability argument.** One external
-acceleration is held for the whole fixed step, so an explicit `rate · (u_air − v)` overshoots the air
-once `rate·dt > 1` and diverges past 2 — and §1's first commitment is "not at 5 fps", which is a `dt`
-of 0.2 s and a rate of 10. What the step multiplies by is the **per-step response**
-`(1 − e^(−rate·dt))/dt` (`cloth_drag_response`), the exact solution of the same linear ODE, which
-closes a fraction of the gap that is strictly below one for every rate and every step length. It is
-also the step `GlobalFluidEffector` already takes for the air itself, which is a symmetry rather than
-a coincidence: both are relaxations toward a velocity. `MEASUREMENTS.md` §49.
-
-**The field answers in grid cells per second and cloth needs metres.** `FluidField#sampleVelocity`
-documents that it deliberately does not rescale, "on the assumption that callers (vegetation sway,
-dust drift) interpret the field as a direction × magnitude wind". Cloth is not such a caller: its row
-is a relaxation toward a velocity, so without the multiply by `cell_size` the same wind voxelised at
-0.25 m instead of 1 m blows a garment four times as hard. `ClothFluidWind` converts.
-`MEASUREMENTS.md` §46.
-
-**And this section never said which thread samples, which M5 made a question.** It cannot be the
-worker's: a fluid field is a hundred thousand floats its own solver rewrites every step and may itself
-live on another worker, while the *answer* is three floats a particle. So `cloth_sample_air` runs on
-the **main thread** in both systems and writes into `ClothState#air_velocity` — a region of the
-cloth's own `SharedArrayBuffer`, so nothing is copied — and everything built from it runs in
-`cloth_step_instance` with the rest of the arithmetic, which is what keeps §12's parity structural.
-Measured: 58–62 ns a particle for a field sample, a twenty-fifth of that for the ambient (one sample
-for the whole cloth, which is what §10's "skips it entirely" is worth), and one per cent of a step for
-the term itself. `MEASUREMENTS.md` §48, §49.
-
-**Where the air comes from is a scene's choice and there is no default.** `ClothWorld#wind` is `null`
-until something assigns a source, exactly as the collider index is: a scene without one gets M5's
-cloth rather than an error. Null rather than a still-air ambient, because a source answering zero
-everywhere is not "no wind" — the row is a relaxation toward the air, so still air still resists a
-*moving* cloth, anisotropically. That is better physics than `ClothDynamics#damping`'s isotropic decay
-and it is not free, so it is a thing a scene asks for. What a cloth does in air that is not moving is
-`damping`'s job (§7 P5, where it is load-bearing); what it does in air that *is* is this.
-
----
-
-## 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.
-
-**Post-M6 found both halves of that last clause to be false in the code**, and they are the same
-mistake twice: the authored pose lives in the cloth, so the cloth is the only thing that can give it
-back, and it did not. `ClothWorld#reseed` cleared `ClothInstance#seeded` *before* the walk, and the
-capture was keyed on `seeded` — so the one path that exists to re-walk a live cloth was the one path
-that could remember nothing, and `read_rest_pose` fell back to `TransformAttachment#transform`, which
-this very paragraph says the write-back has been overwriting every step. Reproduced on a 6-link rope
-authored horizontally and settled for 300 steps: a re-seed took the authored tip from **x 0.600,
-y −0.012 to x −0.003, y −0.600**, and `blend = 0` then landed on the sagged pose. The capture is now
-keyed on there *being* a previous capture. And the same for removal: `unlink` dropped the registry
-entry and nothing put the authored local transforms back, so a `Cloth` removed left its subtree frozen
-in the solver's last shape and a `Cloth` added back seeded *that* as the pose it returns to.
-`cloth_release_subtree` is the other half of the seed, announced once on the anchor.
-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 **of its own**: 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. The geometry is registered with `GPUAnimationManager`, and what cloth writes is a
-joint's offset from its parent joint.
-
-**Where that offset lives is no longer a `Node3D`, and the three paragraphs that follow were written
-when it was.** M3 wrote `Node3D.transform_local` on joints inside a `SceneBundleInstance`, and this
-section still describes that, including a flat assertion that bone entities are "explicitly a design
-this program does not do (D47)". The engine's Rows-Not-Nodes work deleted `Node3D`: a model is spawned
-by `prefab_instantiate`, its joints **are** entities, and the writable handle is
-`TransformAttachment#transform` on the joint entity — which is what `cloth_seed_rig` collects and
-`cloth_write_back_rig` writes. Nothing about the design changes with it and one thing gets simpler:
-the rig path and the entity path now write the *same component*, so §11's "the solver is identical
-either way; only seeding and write-back differ" is now true of the write-back's data type as well as
-of its shape. Read `Node3D.transform_local` below as `TransformAttachment#transform` on a joint
-entity, and `SceneBundleInstance` as `PrefabInstance`.
-
-**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.
-
-**Post-M6: the claim is a loan, and it was written as a gift.** The consequence above is the right
-trade only while the cloth is *there*. `cloth_seed_rig` revoked the GPU's authority over every joint
-it drove and nothing ever re-granted it, so a garment removed left its joints owned by a CPU that had
-stopped writing them — neither animated nor simulated, stuck in the pose the solver last produced, and
-with no component left anywhere naming which joints those were. The seed now records exactly the
-joints its revoke *changed*, and `cloth_release_rig` hands those back when the `Cloth` is removed or
-the `ClothRig` is taken away; a joint that was already the CPU's before cloth arrived stays the CPU's.
-
-**2026-10-06: the claim never stopped a clip, and the loan was handed back to whoever asked last.**
-No GPU pass reads `GPUStateAuthority`. A bound clip's bindings write a joint's row through the pose
-accumulator every frame, after the CPU's flush, whatever the bit says, so clearing the bit only let
-cloth's flush and the clip race for one row, and the clip won. And cloth and `GPUAnimationManager`
-each flipped the same bit without the other: a clip that left during the loan was answered by
-cloth's re-grant with a joint nothing wrote again, and a clip that arrived during it took the bit
-from under cloth's write-back. The rule now is a **hold**. `GPUStateAuthority#held` records that a CPU
-writer has the offset, the bit stays clear while it does, and the animation manager — the only
-writer of the bit — mutes every binding that names a held joint and leaves its offset alone when the
-last clip goes. Ending the hold grants nothing; a clip still bound takes the joint back. So **"a joint
-cloth simulates stops being animatable by a clip" is true now, and a garment whose joints are also
-keyed is not an authoring error**: exporters often bake every bone, and the cape simulates anyway.
-`MEASUREMENTS.md` §61.
-
-**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.
-
-   **M7 lifted the refusal, because the frame and the fixed set came apart.** The bones a garment
-   hangs from are particles of the proxy that cloth reads and never writes (`ClothProxy#output`), with
-   the links to their roots the first links of the fabric; the frame is the nearest skin joint above
-   all of them (`ClothProxy#frame`); and the builder hands back one `ClothProxyGroup` per bone — the
-   pin to add. A cape across both shoulders is one proxy, two pins, riding the chest
-   (`cloth_rig.spec.js`).
-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 (`csr_graph_color_greedy`, checked by `csr_graph_validate_coloring`), 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) — **not built.** The sentence that used to
-stand here said it "is supported through an optional texture or vertex-colour channel"; nothing reads
-a texture or a colour channel, and `ClothProxy` has no per-vertex override to read one into. Steps 5
-and 6 are the whole of what a garment gets, which is the design's own claim that most garments never
-need to override them, made by there being no override. The shape of one, if a garment ever needs it,
-is a per-particle multiplier beside the geodesic — one array, read where `slack` and `stretch` are
-read — and it is the kind of authored knob §3.4 spent a section removing, so it should arrive with a
-garment that demonstrably needs it rather than ahead of one.
-
----
-
-## 12. Data layout, threading, the worker
-
-**One `SharedArrayBuffer` per cloth**, and the command region names which cloths are live this step —
-so sleeping (P5) and culled (§12.1) cloths cost nothing but their absence from a list. `WorkerSystem`'s
-model is a single shared buffer, a single command region and a single atomic publishing one in-flight
-step, and `WorkerFluidSystem` shows how a variable set of simulated things fits it.
-
-**M5 corrected "one buffer for the whole cloth world", and `reseed` is why.** A `ClothState` is sized
-at seed from *that cloth's* particle and row counts, and `ClothSystem#reseed` — a chain gaining a link,
-a `ClothDynamics` change the row tables depend on, a rigged garment whose model has just loaded —
-builds a different one while other cloths have steps in flight. A world buffer would therefore need an
-allocator with relocation, and a relocation invalidates every view of every region on both threads at
-once. One buffer per cloth costs one cold-plane message per seed (`add_cloth` / `remove_cloth`, the
-shape `WorkerFluidSystem` already has) and makes a re-seed a re-registration, which is the same code
-path as a first seed. `MEASUREMENTS.md` §39.
-
-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 — `CLOTH_COLLIDER_SLOTS` of them |
-| contacts | `Float32Array` | transient rows + their warm-start `λ`, keyed by (particle, collider slot) |
-
-The **step's parameters** reach the worker through the command region, written every step — fourteen
-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. (Thirteen at M5; M6's §10 adds the drag response, and the air itself
-travels as a region of the same buffer rather than as words — `ClothState#air_velocity`, written by
-the main thread and read by the step, which is the one direction the buffer could always carry and
-nothing had used.)
-
-**M5 corrected "`ClothDynamics` reaches the worker".** By the time the step can use them a cloth's
-dynamics have been through `cloth_dynamics_map.js` — a damping retention, a velocity clamp, a
-self-collision radius, gravity rotated into the local frame — and sending the raw component would mean
-running that mapping a second time on the far side, with no way to prove the two copies agreed. What
-crosses is `ClothStepParam`: `dt`, local gravity, substeps, iterations, retention, clamp, contact
-radius, self radius, collider count, and whether self-collision is on. `Float64` throughout, so the
-round trip is exact — an `f32` command region would round the clamp, and a clamp that rounds is a
-velocity that rounds. `MEASUREMENTS.md` §40.
-
-The same block is what makes the parity gate below structural rather than aspirational:
-`ClothSystem` fills the words of a private scratch array and calls `cloth_step_instance`;
-`WorkerClothSystem` fills the same words of the shared command region and the worker calls the same
-function. Neither system computes a step parameter of its own, so neither can compute one differently.
-
-**M6 found the one thing that is not a parameter and still differs: the clock.** A gust is a function
-of time, and a worker cloth is not advanced until its registration is acknowledged — so the two
-systems reach a cloth's *first step* at different tick counts, and a clock that counted ticks hands
-that cloth a different gust on the same step. Measured with the clock put back on ticks, the gate
-fails at step 1, byte 0, which is the step's own result word. `ClothWorld#time` therefore counts the
-steps the world has taken rather than the ticks it has been asked about: it advances at the first
-`advance` of a tick, so a tick in which nothing is advanced does not move the weather. That is also
-the right semantic on its own terms — a paused simulation should not have the wind move.
-`MEASUREMENTS.md` §50.
-
-**Post-M6: a world clock fixes the first cloth in a scene and no other.** The paragraph above is
-right about *one* cloth and the gate it was measured against had one. With cloth A already running,
-cloth B's registration takes k ticks during which A is still being advanced — so the world clock
-moves, and B reaches its own first step at a different clock value under the two systems. Measured
-with a two-tick delivery: **0.1000 s against 0.1333 s** at B's first step, and the gate fails at B's
-step 1, byte 0, exactly as it did for the tick clock. A gust of zero gives zero differences, which is
-what identifies the clock as the cause rather than the latency. So the gust reads **the asking
-cloth's own age** — `ClothInstance#age`, seconds *this instance* has stepped — and `ClothWorld#time`
-is left to do the one job it can do correctly, which is telling a source that reads the scene when to
-walk it. The visible consequence is that two garments spawned a second apart are a second apart in
-the gust rather than in phase with it; for a bounded sum of sinusoids that is indistinguishable from
-weather, which is why this is free. `MEASUREMENTS.md` §57.
-
-**G2 (the GPU wind fluid's S5): the clock is the scene's, and the gate is restated.** The gust moved
-onto `GlobalFluidEffector` and runs on the scene's tick, so every consumer of the wind reads one
-weather — and a cloth steps in the weather of the tick it is advanced on. The worker advances a cloth
-from the tick its registration is acknowledged, so the gate now reads: **worker and inline agree for
-cloths registered on the same tick, and for any registration under a time-invariant wind.** Measured:
-the staggered spawn under a 3 m/s gust differs at the second cloth's step 1, byte 0; registered on
-the same tick, none in 180 steps. Under the GPU wind on a device, lattices land when the GPU answers,
-so run-to-run repeatability is given up too (F4). `MEASUREMENTS.md` §69.
-
-**And post-M6 found the other one, which is not a clock: the two systems ran a tick's phases in
-different orders.** `ClothSystem` ran advance, step and finish per cloth, in hierarchy-depth order, so
-a **nested** cloth advanced against an anchor the cloth above it had already written *this* step;
-`WorkerClothSystem` cannot do that — its `apply` writes step T−1 back at the top of a tick and its
-`collect` then advances everything for step T. Measured on a 4-link rope hung from link 3 of a 6-link
-rope, no wind, 120 steps: the parent identical, the child differing at **step 1, byte 24**. Both
-systems now run three loops — advance every cloth, then step every cloth, then finish every cloth — so
-a nested cloth reads its parent one fixed step stale on both sides, and `ClothWorld`'s depth sort,
-which existed only to make the other answer true, is gone. That was necessary and not sufficient: the
-write-back also composed each node's world pose against the **live** anchor rather than the anchor the
-step ran on, which for a worker writing step T−1 during tick T is a different anchor. It now uses the
-pose `advance` cached, which is the same value for `ClothSystem` and the honest one for both.
-`MEASUREMENTS.md` §56.
-
-`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.
-
-**And M5 moved the per-step collider table itself into that buffer**, at a fixed
-`CLOTH_COLLIDER_SLOTS`, which is where the table above always put it. M2 kept it on `ClothInstance`
-and grew it by doubling, on the correct grounds that its size is a property of the world rather than of
-the cloth; what decides is that an array which can be *replaced* mid-run is memory the worker has to be
-told about again before it can name it. So the size stays a property of the world and the region gets a
-capacity. **Sixty-four**, because the measurement showed the bound is a *scene* rather than a garment —
-a cloth's table holds every collider on every character standing inside its query box, which is ten for
-one body and thirty for three — and because an overflow discards colliders in the index's own order
-rather than in order of how much they matter. It warns once. `MEASUREMENTS.md` §41.
-
-**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.
-
-**M5 measured it and the number is zero**, at every step of a run rather than at the end of one: the
-whole `ClothState` buffer — particles, velocities, every dual and penalty, the collider table, the
-warm-started contact multipliers, the self-collision pair list — compared byte for byte after each of
-420 steps across two scenes, one with a walking anchor and one with colliders and self-collision live.
-What the scene sees differs by exactly one tick: the pose written at tick `T` is step `T − 1`'s. That
-is §4.1's own sentence in a second setting — the cloth's *shape* is one fixed step stale and its
-*position* is not, because the attachment cascade carries the subtree rigidly with the anchor.
-`MEASUREMENTS.md` §40.
-
-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/csr/csr_graph_color_greedy.js`, `csr_graph_validate_coloring.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_transform_oriented_array` |
-| 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`~~ — **not reused**, see §8.3: cloth's `μ` is `Collider#friction · ClothCollider#friction_scale`, which is a scale on one material rather than a combination of two |
-| 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` (in grid cells a second — §10 converts), `fluid_build_world_to_grid`, `GlobalFluidEffector` as the shape of the ambient *and* as the exact-ODE relaxation step `cloth_drag_response` copies |
-| Worker offload | `ecs/async/WorkerSystem.js`, `SystemWorkerHost`, `SystemWorkerLoopback`, `WorkerFluidSystem` as the worked example |
-| Fixed step | `EntityManager`'s fixed-step loop, gate and `fixedStepTick` |
-| 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 |
-
----
-
-### 13.1 What is *not* reusable — render interpolation
-
-`PhysicsSystem`'s producer/`__interp_restore` contract was in the ledger above and M5 took it out,
-because it cannot express a rigged garment. `Interpolated` is an **entity-keyed marker**: the
-`InterpolationSystem` files snapshots under a `key` it assigns from the entity id at link time. A
-rope's links are entities and a skinned garment's joints are not — `shade_node_to_entity_composition`
-does not expand a skinned node, "and that is a boundary rather than an omission" (§3) — so half the
-feature has nothing to put the component on.
-
-Cloth also needs only half of what that contract does. `__interp_restore` exists to hand the
-simulation its authoritative pose back before it integrates, because the render blend writes into the
-components the simulation reads. Cloth's state is `ClothState.position` in the cloth's local frame and
-its write-back never touches the anchor it reads, so **cloth never reads back what it writes** and has
-nothing to restore. It needs the publish half, over a pose per node rather than a component per entity.
-§18 carries what that would cost. `MEASUREMENTS.md` §43.
-
----
-
-## 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. The serialization adapters: 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 — **true of one of the three;
-the correction follows this block.**
-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.**
-
-**Corrected 2026-09-13: the deferral above only ever fitted `ClothRig`'s adapter, and it was applied to
-all three of them from here to the end of the plan.** It fits `ClothRigSerializationAdapter`, whose
-component points at a built, shared, immutable asset and therefore needs the asset-identity story §3.2
-only gestures at; and it fits `ClothProxy`'s own codec, which genuinely does depend on what §11.3
-step 9 adds to a proxy. It never fitted `Cloth` or `ClothCollider`. Those two are scalars — `blend`,
-`layer`, `mask`, `flags` and a `ClothDynamics` value object of ten more; `inflation`,
-`friction_scale`, `layer`, `mask`, `flags` — and neither holds a proxy, a skin, or anything either
-geometry path introduces. The evidence that the revision this sentence feared was never coming is M3
-itself: it changed the design in four places (`MEASUREMENTS.md` §24–29) and not one of them was a
-field on either component.
-
-What turned a sequencing call into a hole is that it was **re-deferred rather than re-examined**. M2
-deferred all three "per M1's own reasoning"; M3 deferred them again for M1's reason while, in the same
-list, deferring the unrigged path that the reason had just been made to wait on; and §11.3 step 9 is
-in no milestone at all. A wait with no scheduled end is not a sequencing decision, and what it cost is
-that M6 closed this plan with a subsystem a scene could not contain: a `Cloth` could be added from
-code and from nowhere else. `ClothSerializationAdapter` and `ClothColliderSerializationAdapter` are
-built and specced as of 2026-09-13, outside any milestone and with no `MEASUREMENTS.md` section,
-because there is no measurement behind them — a codec has nothing to measure, and that file's sections
-belong to milestones. `ClothRigSerializationAdapter` and the proxy codec stay deferred, on the reason
-as narrowed here.
-
-**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 and
-specced, but nothing **authors** one: its plane comes from a garment's own skinned surface and a
-skinned garment is M3. (**"and driven by the playground" was not true and has been removed** — no page
-under `playground/` writes `ClothState#backstop_plane`, then or now. The row's own docblock made the
-same claim and has been corrected. What holds it up is `cloth_backstop_row.spec.js`, which is a
-solver-level spec rather than a scene, and that is the honest status of a row with no author.) Two-way coupling, per §2. The serialization adapters, per
-M1's own reasoning — which, as M1 now records, reached only `ClothRig`'s. The other two were not
-blocked by anything M2 had in hand or M3 was about to add, and this line is the first of the two
-restatements that carried them anyway.
-
-**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. **Those two
-only, corrected 2026-09-13.** As written this sentence carried `Cloth`'s and `ClothCollider`'s
-adapters with them, over a set of three, for a reason that held for one — and it did so in the same
-list that defers the unrigged path the reason had just been made to wait on, which is what closed the
-loop: the dependency and the thing depending on it were deferred by the same paragraph. Neither scalar
-component holds a proxy, so §3.2's asset-identity question — the real content of M1's reason — was
-never theirs to answer. Both adapters were built on 2026-09-13; M1 carries the full correction.
-
-**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. `ClothState#self_free_pair` is measured once at seed, per particle, and the ceiling is two
-fifths of it. On a sheet the two rules agree exactly, so §31–36 stand. `MEASUREMENTS.md` §37, §68.
-
-**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. DONE, 2026-09-12.** `WorkerClothSystem`, `ClothWorkerCore`, `cloth.worker.js`,
-`makeClothWorker` and the protocol — plus the two pieces that had to exist for the parity gate to be
-structural rather than hopeful: `ClothWorld`, which is every cloth in a scene and everything about
-stepping one that is not arithmetic, owned by *both* systems; and `cloth_step_instance`, which is the
-arithmetic, driven by a `Float64` parameter block that is also the command region's per-cloth record.
-`ClothState` gains shared-memory backing, a descriptor, the collider table and a result region.
-*Proofs, all green:* bit-parity over the **whole `ClothState` buffer at every step** of two runs — a
-walking anchor for 240 steps, and colliders plus self-collision for 180 — with the write-back's
-one-tick lag pinned tick by tick rather than asserted at the end; the state a worker steps being the
-main thread's memory rather than a copy; a cloth being neither stepped **nor advanced** until its
-registration is acknowledged, which is what keeps the two systems' step *sequences* identical rather
-than merely similar; a re-seed retiring its registration and waiting again; a despawn between dispatch
-and step not failing the bridge; sleep removing a cloth from the dispatch and `wake` putting it back;
-shutdown settling the step in flight, releasing the gate and dropping the worker; and the derived
-execution order landing `WorkerClothSystem` exactly where `ClothSystem` lands. **10 tests in one new
-spec file**, with the M0–M4 suites unchanged at 183. The engine suite is green at 18,579.
-
-**M5 changed the design in four places**, each with the measurement behind it in `MEASUREMENTS.md`
-§38–44 and each folded back above. In one line each: §12's one buffer for the whole cloth world is one
-buffer per cloth, because `reseed` resizes one while others are in flight; §12's collider table does
-belong in that buffer and therefore needs a capacity rather than a growth policy, and the capacity is
-bounded by the *scene* — thirty records for three characters — rather than by the garment; §12's
-"`ClothDynamics` reaches the worker through the command region" is the *mapped* step parameters rather
-than the component, because mapping them twice is two copies that cannot be proved equal; and §13's
-reuse of `PhysicsSystem`'s interpolation contract does not hold, because that contract is entity-keyed
-and a rigged garment's joints are not entities.
-
-**And the strongest result is again a number rather than a correction.** §12 asks the two systems for
-bit-identical results. Over 420 steps across two scenes, comparing the entire state buffer after every
-one of them, the number of differing bytes is **zero** — and it is zero by construction rather than by
-luck, because there is one `ClothWorld`, one `cloth_step_instance`, and one parameter block that both
-systems fill and neither system interprets. The main thread's share of a thousand-particle garment goes
-from 3.62 ms to 0.18 ms; across the library's shapes, 92% to 96% of it crosses. `MEASUREMENTS.md` §40,
-§41.
-
-**Deliberately not in M5:** **render interpolation**, which §18 said would land here and which M5
-decided against with three findings rather than a deferral — the named contract is entity-keyed and
-cannot reach a rigged garment's joints, cloth needs only the half of it that has no name, and the
-worker removes the cheap implementation by owning `ClothState` outside the fixed pass. What it needs
-instead is a published pose slot, and §18 now carries what that costs (about 0.12 ms a frame on the
-§17 workload, which roughly triples the main thread's share of cloth and leaves it at a seventh of
-its pre-M5 cost) and what it buys (half a link length a step at a walk, a whole one at a sprint).
-`MEASUREMENTS.md` §43. **A playground page**, for a reason about the dev server rather than the cloth:
-`SharedArrayBuffer` needs a cross-origin isolated page, and adding `COOP`/`COEP` to
-`vite.config.mjs` changes how every other playground page in the package loads its subresources —
-to demonstrate a bridge `SystemWorkerLoopback` already tests more precisely than a page could.
-**Culling (§12.1)**, which is a policy over the same dispatch list sleep already uses and belongs with
-a camera. And **a deeper pipeline**: `WorkerSystem` allows one step in flight and the fixed-step gate
-means a cloth could not use a second.
-
-**M6 — wind. DONE, 2026-09-13.** §10 end to end: `wind/AbstractClothWind.js` and the two sources
-behind it (`ClothAmbientWind`, `ClothFluidWind`), `wind/cloth_sample_air.js`,
-`solver/cloth_wind_accelerate.js`, `ClothState`'s air and external-acceleration regions,
-`cloth_drag_response`, the parameter block's fourteenth word, and `ClothWorld`'s wind source, clock
-and wake test.
-*Proofs, all green:* the normal-facing factor on both topologies, which is the whole of what M6 adds
-to the physics — a sheet reading 1.000 broadside and 0.000 edge-on, a chain reading the reverse, and
-neither a skip row nor a strain-limit row able to fabricate a plane out of a line; the two sources
-through the interface, including a field answering in metres rather than grid cells and `varies()`
-being a promise the sampler acts on; the ECS path end to end — a garment blown downwind, one inside a
-`FluidComponent` reading the simulation while one ten metres away reads the weather, a settled banner
-sleeping in a steady wind and waking on a gust, and a scene with no source producing the cloth M5
-shipped **byte for byte** across 120 steps; the drag response closing a fraction of the gap to the
-air that is strictly below one at every step length from 1/240 s to 1 s; and §12's parity gate
-extended to a third run with wind live. **25 tests across three new spec files** — the term's 9, the
-sources' 10, the ECS path's 6 — plus the parity spec's eleventh, for 26 in all, with the M0–M5
-suites unchanged at 193. The engine suite is green at **18,638**, and the same suite run against M5's
-own commit in a detached worktree reads 18,612 on this machine, so the difference is exactly M6's
-twenty-six. A fifth playground page, `playground/wind.html`, with a banner hanging in a real
-`FluidSimulator`'s wake.
-
-**M6 changed the design in five places**, each with the measurement behind it in `MEASUREMENTS.md`
-§45–§52 and each folded back above. In one line each: §10's `|n·û|` cannot be written for a chain,
-which has no normal and wants the complementary factor anyway, so both are one expression over the
-span of the incident rows; §10's "samples its velocity field" needs a unit conversion, because
-`FluidField` answers in grid cells a second and a garment blowing at a speed that depends on the
-voxel size is not a garment; §10 never said which thread samples and it cannot be the worker's, so
-the field stays where it is and three floats a particle cross in the cloth's own buffer; `drag`
-cannot multiply the flow directly, because one acceleration held for a whole fixed step overshoots
-the air once `rate·dt > 1`; and §12's thirteen-word block is fourteen, with a clock that has to count
-steps rather than ticks or the two systems' weather diverges at step 1.
-
-**And the strongest result is again a number rather than a correction.** §10 offers the normal-facing
-factor as the difference between a flag and a rope. In uniform air it is: turning the wind ninety
-degrees at the same speed takes the banner's aerodynamic acceleration from **43.2 m/s² to 0.08**, a
-factor of five hundred. In a **wake** it does nothing at all — 0.216 against 0.280 — because a wake
-has velocity in every direction and no orientation of a surface is edge-on to one. That is not a
-failure of the factor; it is the measurement saying §10's argument for reading a simulation is
-stronger than §10 knew, and that the flag-versus-rope claim is a statement about laminar air.
-`MEASUREMENTS.md` §51.
-
-**Deliberately not in M6:** **a spatially varying ambient.** The gust is uniform in space, so a long
-banner does not see it arrive at one end before the other — and that is what makes the no-simulation
-case cost one sample for a whole garment instead of one a particle (§48). Spatial structure is what a
-fluid field is *for*, and a second, worse one inside the fallback is the duplication §10 exists to
-avoid. **A blend at a field's edge**: a point inside a volume reads the volume and a point outside
-reads the ambient, so a garment straddling the boundary sees a step rather than a ramp. Where the
-ambient is the far field the volume relaxes toward — `GlobalFluidEffector`'s own `wind` — the step is
-small and is mostly the disturbance the volume exists to carry; where it is not, the answer is a
-volume large enough to hold what moves through it. **Two-way coupling into the fluid**, per §2's
-one-way rule: cloth reads the air and does not disturb it, and anything that should has
-`FluidObstacle`. And **per-substep sampling**, because §10 says per step and §48 measures the sample
-at 58 ns a particle — the one part of this that is not free is the one part per-substep sampling
-would double.
-
-**Post-M6 — six defects, six fixes, and the plan corrected where the code proved it wrong. DONE,
-2026-09-13.** No new mechanism and no new milestone: a pass over what M6 left, taken in the order the
-defects were found.
-
-1. **A cloth resting on a collider never slept.** §7 P5 has asked for "maximum particle displacement
-   over a window" since M0 and M1 built an instantaneous speed; four of the seven library fabrics
-   never slept at all on a floor, because a resting contact is a bounded limit cycle whose *speed* is
-   eighteen times the threshold and whose *travel* is a tenth of a millimetre a step.
-   `CLOTH_SLEEP_DISPLACEMENT_RATIO`, and every entry on a floor or a sphere sleeps.
-   `MEASUREMENTS.md` §53.
-2. **A static collider was tunnelled from 3 m/s.** M2 folded the collider's travel into the discovery
-   reach and argued the particle's own away with a velocity clamp three orders of magnitude too large
-   to be the bound. The reach carries `|v_i|·dt` too; what is left is the substep count, measured.
-   §7 P3, `MEASUREMENTS.md` §54.
-3. **Seeding took three things from the scene and gave none of them back**: the authored pose across a
-   re-seed, the authored pose on removal, and the GPU's authority over a rig's joints. And `ClothRig`
-   was read once rather than watched, so a rig arriving a fixed step late seeded a skeleton as a rope.
-   §11.1, §11.2, §18.
-4. **A collider arriving and a collider retiring were both asked about a pose.** A collider spawned
-   inside a sleeping cloth has not *moved*; a handle retired and reused inside one tick is the same
-   handle. The wake test compares the handle set, and a retired slot is cold for a step.
-   `MEASUREMENTS.md` §55.
-5. **The parity gate had one cloth in it.** A nested pair and a staggered spawn are two scenes in
-   which the two systems could differ and did — a tick's phases ran in different orders, the
-   write-back composed against a newer anchor than its own step, and the gust read a world clock that
-   moves while a second cloth is registering. §12, `MEASUREMENTS.md` §56, §57.
-6. **The plan said eight things the code does not do**, each corrected in place above: P4(d)'s escape
-   hatch and `ClothDiagnostics` recorded as never built rather than "on by default"; §5.2's constants
-   line brought to `β = 1e3` with the contact floor recorded and `γ = 1` named as the one unmeasured
-   constant left; §7 P1's gate stated as twice its measurements rather than as them; §3.3's `flags`
-   default; §6's claim about the library at 2×4, which was never true of `CLOTH_ROPE`; §8.3 and §13's
-   `combine_material.js`, which nothing imports; §3.2 and §11.2's joints-are-`Node3D`s, which the
-   engine's own Rows-Not-Nodes work made false; §11.3's vertex painting; and the backstop row's
-   playground, which does not exist. §18 gains the wind span rank as a limit, recorded not fixed.
-
-*Proofs, all green:* eleven specs that were red before their fix and green after — the P5 collider
-sleep gate over the whole library × three scenes, the swept-versus-unswept throw at a static capsule
-and its three companions, the re-seed and the removal on the entity path, the rig's authority and the
-two `ClothRig` edges, the four collider-lifecycle cases, and the two parity scenes. **The cloth suite
-is 251 tests across 26 files**, against M6's 234.
-
-**Deliberately not in this pass:** the `γ` sweep; tightening §7 P1's gate to its measurements;
-building the escape hatch or `ClothDiagnostics`; render interpolation; culling; the unrigged path;
-M4b; the wind span rank, which is recorded in §18 and not fixed; the `ClothRig` serialization adapter;
-and the physics adapter registry gap.
-
-**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-measured at M5, and no entry is re-sized — but not for the reason the table reads.** The absolute
-column came back 15% to 25% above M4's, on a machine carrying nineteen other node processes at 30–38%
-background CPU, which is exactly the swing M4's own lesson predicts. What licenses leaving the library
-alone is a *paired* measurement instead: `cloth_library_bench.mjs` never touches
-`WorkerClothSystem` — it drives `cloth_step` over a `ClothState` directly — so the only thing M5
-changed that it can see is the buffer layout, and an interleaved A/B of the two layouts in one process
-reads 0.95 to 0.98 with the two states staying bit-identical for 1,600 steps. §33's ordering stands
-entry for entry. `MEASUREMENTS.md` §39, §42.
-
-**Re-measured at M6, and no entry is re-sized — now with a measured reason rather than only a
-disclaimer.** §10's aerodynamic term, priced in the bench's own §33 scenario, moves each entry by
-−2.7% to +9.3% across three runs, with the sign not monotone in `drag`; and with the *physics* held fixed so the two
-sides simulate the same cloth, the whole feature is **one per cent of a step**. The rest of that
-column is a different cloth — a rope blown horizontal costs 3.24× a rope hanging straight down, which
-is §7's warning arriving in a new setting and is about the rope. Three runs of the same bench within
-an hour put the §17 baseline row at 3.49, 3.83 and 4.26 ms, so the absolute column is still the
-machine: M5's advice to re-measure it quietly stands, and M6 adds that a process count is a proxy for
-load rather than a measure of it. `MEASUREMENTS.md` §49, §52.
-
-**And the budget now means something slightly different.** The worker moves the cost rather than
-reducing it, so 2 ms is still 2 ms — but it is 2 ms on a thread that is not drawing the frame, and the
-question it answers has become "does all the cloth in the scene fit in one worker tick" rather than
-"does one garment fit in a frame". The main thread's share of the §17 workload is 0.18 ms.
-`MEASUREMENTS.md` §41. Re-measure the absolute column on a quiet machine, and check the process count
-first.
-
-**M7 — attachment points. DONE, 2026-10-10.** `ClothPin`, `ClothHold`, `cloth_holds.js`,
-`cloth_geodesic.js`, `ClothPinSerializationAdapter`; the rows built from a particle graph rather than a
-parent array; held particles carried through the step (`ClothState#kinematic_target`) and leash rows
-measured from a particle (`leash_source`); the rig proxy's bones-to-hang-from and frame joint. There is
-no anchor: a cloth is held by whatever pins name it, from none up. §19 is the design.
-*Proofs, all green:* `cloth_held.spec.js` (five of six red against the previous solver),
-`cloth_pin.spec.js` (free fall, a rope held at its top, a rope bridge, letting go and catching mid-swing,
-a holder teleporting, a holder outrunning the cloth, holds pulled beyond the fabric, a pin before its
-cloth, lifecycle and refusals), `cloth_geodesic.spec.js`, the adapter's, a two-shoulder cape in
-`cloth_rig.spec.js`, and a worker parity run in which a second holder drags, lets go and takes hold
-again — bit-identical every step for 240. Cloth suite 327, slow 7, physics 1,861. *Cost:* +1.4% and
-+2.8% median a step on a 129- and a 1,025-particle rope rig, paired against the previous build in one
-process. *Equivalence:* a rope pinned at its own top under M7 and the same rope under the anchor differ
-by 1.9e-7 m after one step, and grow apart exactly as fast as two copies of the old build nudged 1e-7 m
-apart — chaos, not a change. `MEASUREMENTS.md` §62.
-
-**M7, sheets. DONE, 2026-10-10.** `cloth_proxy_from_mesh`: a proxy from a skin with one joint per vertex
-and the triangles over them — a stretch row per edge, a hinge per interior edge, the authoring mistakes
-refused by name (§7 P8). `ClothProxy` carries its graph for both builders; hinge rows are built wherever
-a proxy has hinges, each stiffened as a ratio of its own inertia; a joint with triangles round it is
-turned by its surface rather than swung along a chain. §19.5 is the design.
-*Proofs, all green:* `cloth_proxy_from_mesh.spec.js`, and `cloth_sheet.spec.js` through `ClothSystem` —
-a flag held at its hoist by a pole, every library fabric swinging down from a held edge and coming to
-rest, a free sheet draped on a sphere with every joint turned onto its surface, and a cloth in two
-pieces of which only one is held. *Found:* a flag on a pole in still air turns about the pole, and the
-solver did it before holds existed (§18). `MEASUREMENTS.md` §63.
-*The stage's remaining scenes, later:* a sheet carried round by friction on a turning sphere, and a
-circle skirt that flares on a turning body and settles, both in `cloth_sheet.slow.spec.js`. The third, a
-pile of ribbons, found that a fold resting on a fold never comes to rest at the shipped self-collision
-stiffness (§18), and is kept as the proof a change to it needs. `MEASUREMENTS.md` §64.
-
-**Post-M7 — a fold resting on a fold comes to rest. DONE, 2026-10-11.** `CLOTH_SELF_RATIO` goes from
-8 to 2 (§9, §18). *Proofs, red on 8 and green on 2:* in `cloth_sheet.slow.spec.js`, a pile of three
-silk ribbons fanned 60°, which sleeps with no crossing at any step and its order kept, and the circle
-skirt, asleep after its twirl; in `cloth_sheet.spec.js`, the sheet draped on a sphere, asleep. *Cost:*
-§32's folding sheet goes from 2.09 to 2.98 crossings a sample over 48 gusts, and the library bench
-does not move. The turning-sphere spec's 2° on where the sheet stops after the spin was one
-realisation and is now 10°. `MEASUREMENTS.md` §65.
-
----
-
-## 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 three 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. Post-M6 found the third: the *particle's* own travel, which M2 argued was covered by §7 P1's
-velocity clamp and is not, by three orders of magnitude — so a **static** collider was tunnelled from
-3 m/s. That is fixed and measured (§7 P3, `MEASUREMENTS.md` §54). What remains is that all three 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.
-
-**A handle is a slot index, and a slot was reused the instant it was retired. — FIXED.** §12 says a
-cloth drops its warm-started contacts when the collider behind a handle changes, and `ClothColliderIndex`
-docblocks said the same in two places; the mechanism was `cloth_contact_find` matching on the handle
-alone, which can only work if the handle is *absent* for a step. `add` popped the retired slot
-immediately, so a collider removed and another added within one tick were the same handle. Measured: a
-particle settled on the old floor carried **lambda 0.0981 and a friction anchor in the old collider's
-frame** onto the new one. `remove` now retires into a list `advance` drains one step later — every
-cloth has by then stepped against an index the handle was not in, which is what makes the slot cold.
-It composes with the wake test above: a sleeping cloth notices the handle leaving its set and wakes,
-so it clears its slots before anything can take the number.
-
-**Open — the contact penalty ramps on the *unsigned* residual, and that is load-bearing by accident.
-— MEASURED.** `cloth_contact_dual_update` climbs `k` by `β·|C|`, so a row that is **not touching**
-ramps as hard as one that is, and with `γ = 1` nothing brings it back down: every contact in a scene
-is at `k_max` within a few steps of being discovered, which makes §5.2's measured choice of `β`
-describe a ramp that is not running. Post-M6 made this visible rather than introducing it — with the
-particle's own travel in the discovery reach, rows now appear tens of centimetres out instead of
-sixteen millimetres, so the pre-stiffening happens long before contact. *And the obvious repair is a
-net loss:* making the ramp one-sided takes the speed at which a thrown particle is still stopped from
-12 m/s down to 9.5 with holes, at four substeps — trading cloth passing through a character, which is
-visible, for a hair rope creeping for thirty-seven seconds instead of three, which is not. Recorded
-rather than fixed; the thing that would actually resolve it is a `γ < 1` for contacts, which is
-§5.2's own open number. `MEASUREMENTS.md` §54.
-
-**— RESOLVED the way it said, when the ramp became a ratio.** The cloth-skirt example turned the ramp
-into `CLOTH_CONTACT_RAMP_RATIO` (§5.2), which made the pre-stiffening total — every row violated by
-millimetres at the ceiling for good — and a resting pile stopped sleeping. `CLOTH_CONTACT_GAMMA = 0.8`
-is the `γ < 1` for contacts, on both penalties. The one-sided ramp was measured again in ratio form and
-lost again (a sweeping thigh through ten times as often, 6 → 4 m/s stopped at two substeps), so the
-pre-stiffening stays and the decay is what bounds it. What the pair costs is static friction's
-exactness, stated in §5.2. `MEASUREMENTS.md` §67.
-
-**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.
-
-**M7 closed half of this.** The fixed set is authored now, by `ClothPin` (§19), for every case: a
-flag's hoist is the vertices a pin on the pole names. **M7's sheets closed the mesh:**
-`cloth_proxy_from_mesh` builds the proxy from triangles (§19.5). What is left is a way to draw one
-(§19.6).
-
-**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 — a wake has no direction, and the aerodynamic model has only one term. — MEASURED.** §10's
-normal-facing factor is the whole of M6's aerodynamics, and in uniform air it does exactly what §10
-promises: ninety degrees of flow angle is a factor of five hundred in the force a banner feels. In a
-fluid wake it does nothing — 0.216 against 0.280 — because a wake has velocity in every direction.
-What that leaves open is whether a cloth *in* a wake wants something the linear drag row does not
-carry: the fluttering a real flag does in one comes from a pressure difference across the sheet and a
-shed vortex, not from a relaxation toward a local velocity, and this design has no term for either.
-*Mitigation:* none is needed for what M6 claims — the cloth reads the air the simulation produces and
-is moved by it. It is named because "a banner in a wake looks alive" is what a reader will expect from
-§10 and is not what a drag row alone produces. `MEASUREMENTS.md` §51.
-
-**Open — the aerodynamic factor decides what a particle *is* on a 14.5° threshold, and a bent chain
-reads as a sheet.** §10's normal-facing factor is one expression over the rank of the span of a
-particle's incident stretch rows (`cloth_wind_accelerate.js`): rank 2 is a surface and gets `|û·n|`,
-rank 1 is a link of a chain and gets the complementary `√(1 − (û·t)²)`, rank 0 is a bead and gets 1.
-Rank is decided by `CLOTH_WIND_SPAN_MIN = 0.25` — how much of a second incident direction has to
-survive projection out of the first — and a quarter is **about fourteen and a half degrees**. Below it
-two rows describe the same line and their cross product is a normal built out of rounding, which is
-the failure the threshold exists to prevent and is why it is not smaller.
-
-What it costs is that a **chain bent past that angle at a link is a surface at that link**, and gets
-the factor for one. A rope hanging straight reads as a rope; a rope draped over a collider reads as a
-sheet at every link on the curve, and does so for as long as it is draped, because the rank is
-recomputed from the configuration every step and the configuration is not changing. The magnitude is
-§51's: turning the flow ninety degrees is a factor of five hundred in a banner's acceleration, so the
-two branches are not close together, and a rope reading as a sheet catches the wind broadside where it
-should be slicing it.
-
-*Not fixed, and recorded rather than guessed at.* The threshold is a single number doing two jobs — a
-numerical guard against a degenerate cross product, and a physical statement about when a chain stops
-being a line — and separating them is the shape of a fix: rank the span with a tolerance chosen for
-conditioning, and blend between the two factors over an angular window chosen for looks. Both halves
-would need a measurement neither M6 nor this pass has, and what a draped rope does in wind is a
-question about a scene rather than about a step.
-
-**Open — the ambient is uniform in space and the field boundary is a step.** Two limits of §10's
-fallback, both deliberate and both cheap to see: a gust lifts a whole banner at once rather than
-travelling along it, and a garment carried out of a fluid volume crosses a discontinuity rather than a
-ramp. The first is what makes the no-simulation case cost one sample rather than one a particle; the
-second is small where the ambient is the far field the volume relaxes toward and visible where it is
-not. A blend would want a falloff distance, which is an authored quantity of exactly the kind §3.4
-spent a section removing.
-
-**Open — a fluid volume's wake is steady at a grid a frame can afford. — MEASURED, and it is the
-fluid system's rather than cloth's.** At 18, 26 and 34 cells across, with the simulator's damping and
-vorticity confinement at both ends of their range, the air a banner's width behind a solid post varies
-by under 0.03 m/s: a velocity deficit, not a shedding street. The deficit is real and is a third of
-the free stream, which is what the cloth reads; what is not there is the unsteadiness. Resolving a
-shedding shear layer costs 15 ms a step at 26 cells and 35 at 34, against 5 ms at 18.
-`MEASUREMENTS.md` §51.
-
-**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, and M5 decided it does not land with the worker.** Cloth
-writes `Transform64` at the fixed rate and nothing blends between ticks, so a cloth updates at 60 Hz on
-a 165 Hz display — 105 of every 165 frames repeat a pose. That is visible and it is not wrong: the
-poses are authoritative, they are simply held. **How** visible is now measured, on M3's cape geometry:
-a node covers 0.47 link lengths in a fixed step at a walk and 1.33 at a sprint (`MEASUREMENTS.md` §43).
-
-What M5 changed is the shape of the remaining work, in three findings that between them delete the
-sentence this note used to end with.
-
-- **`PhysicsSystem`'s producer / `__interp_restore` contract cannot express half the feature.**
-  `Interpolated` is an entity-keyed marker and a rigged garment's joints were `Node3D`s, not entities
-  (§13.1). There was nothing to put the component on and no key to file a snapshot under.
-  **Post-M6: a joint is an entity now** (§3.2, §11.2), so this finding's *reason* is gone even though
-  its conclusion is not — the published-pose slot below is still the cheaper half and still the one
-  cloth needs, and an entity-keyed marker on a hundred joints a garment is not obviously better than
-  one array copied at join. What changed is that it is a trade rather than an impossibility.
-- **Cloth needs only the publish half.** `__interp_restore` undoes render-time writes before the
-  simulation reads them; cloth's state is its particle array and its write-back never touches the
-  anchor it reads, so there is nothing to restore. The restore it *does* depend on — an anchor on a
-  physics-driven character — it already gets from `PhysicsSystem`.
-- **The worker removes the cheap implementation.** A render-time pass cannot read
-  `ClothState.position`, because the worker owns it from dispatch until the next tick's join, which is
-  essentially all of the time outside the fixed pass. What is needed is a **published pose slot**: the
-  last two steps' node poses, copied out at join and blended at render time — the same double-buffered
-  publish slot `WorkerFluidSystem` names as the unbuilt prerequisite for its own render-time reads.
-
-The slot is nearly free to fill, because `cloth_write_back` already computes every node's local TRS
-and would only have to keep it; what costs is the per-frame pass. For the §17 workload that is about
-0.12 ms a frame — 20.5 ms a second at 165 Hz, against the 10.9 ms a second M5 leaves on the main
-thread and the 217 ms a second it cost before. **Interpolating a cloth would roughly triple the main
-thread's share of it and leave it at a seventh of what it was**, which is the honest shape of the
-trade: the feature is affordable because M5 happened, and it is not free. The cloth-shaped version is
-*simpler* than the engine's, not harder: no restore pass, no serialization adapters, no log, and it
-covers the rigged and entity paths identically because both end in a pose per node.
-
-**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.
-
-**Post-M6 narrowed this: a `ClothRig` is not part of it and never was.** §3.1 says the discriminator
-between the two paths is a component's *presence*, and `ClothSystem#dependencies` is
-`[Cloth, Transform64]` — so a `ClothRig` added to a live cloth completed no tuple the system observed
-and one removed broke none. A character whose rig arrived a fixed step after its `Cloth` simulated its
-**whole skeleton as one rope** (in a dev build, through `gpu_authority_assert_cpu`, it threw), and one
-whose rig was taken away kept driving the joints. Both edges are now watched by an `EntityObserver` on
-`Cloth` + `ClothRig` inside `ClothWorld`, so the discriminator is read whenever it changes rather than
-once. The **subtree** case above is untouched and stays open: an entity appearing under a live rope is
-still a `reseed` the caller has to ask for.
-
-**Open — M7: a seam between two holders that move apart.** The animated pose hangs each particle from
-its *nearest* held particle, so two holders moving relative to each other put a step in it where their
-regions meet. It binds only where the slack row does — past `2·slack·d_geo`, which at a seam is the
-widest radius the cloth has — and nothing measured has reached it. A geodesic-weighted blend of the
-holders' motions is the shape of a fix if a garment ever does.
-
-**M7: a sheet held along a vertical line turned about it. — FIXED, by one more block of the descent.**
-A flag on a pole in still air did not hang still: it turned about the pole as a rigid body, ten degrees
-a second at rope's settings, for all 3,000 steps measured. A turn about a vertical hold line is the one
-motion nothing restores — gravity is parallel to it, and every row ends on the axis or is an equal and
-opposite pair — and AVBD stopped at a fabric's iteration count left a residual whose torque about that
-axis was not zero, so the step's fixed point was a steady turn rather than rest. `damping` balanced the
-torque rather than removing it: ten times the rate, a tenth of the speed. It was there with hard stretch
-rows and nothing else, and in the solver from before holds existed, digit for digit. A fabric with
-`slack < 1` came to rest only because its slack row caught the turn — a silk flag 123° round its pole,
-cotton 74° — and one at `slack = 1`, rope or chain, never did. `MEASUREMENTS.md` §63.
-
-*The cause, measured.* A vertex update moves one particle, so each adds `x_i × m·Δx_i` of angular
-momentum about the line, and the step's change about the pole is exactly `h·Σ x × R`, `R` the energy
-gradient left when the iterations stop; the identity closes to four figures. The warm start keeps
-`α·γ = 0.25` of each hard multiplier, so a cloth at rest re-solves three quarters of its weight every
-substep and leaves that gradient every substep. Sweep order is not it: forward, backward and
-alternating each step all read −0.46 at 8 iterations.
-
-*The fix* is the turn as a block of its own (§5.2, `cloth_hold_line.js`): one Newton step along it in
-the last iteration, whenever the held particles lie on one line. The bare flag reads 0 to four figures
-at every budget from 1 to 16 iterations, and every library fabric's flag sleeps: rope at step 416,
-chain at 250 and cotton at 336, where they never did. It costs 3–9% of a sheet's step, and nothing on a
-cloth held at one point, where it never runs. Carrying the multiplier instead — AVBD's Eq. 18, or the
-reference code's post-stabilisation — stops the turn too, fails six to ten of the 345 cloth gates, and
-diverges where its rows meet rows still on the old warm start. `MEASUREMENTS.md` §66.
-
-*Still open, measured and not fixed:*
-- A single held point has three free turns and a cloth nothing holds has six; the block covers a line
-  only. A sheet hung from one corner turns at no more than 0.004, and silk's is awake at step 3,000.
-- Where gravity does restore the turn, the block slows some sleeps: leather's lying sheet from 72 steps
-  to 165, and rope and chain on a pole tilted 30° from 474 to 574 and 264 to 312. Why is not measured.
-- And in one case it keeps a cloth awake. Cotton held by its two top corners, after the hands see-saw
-  for 900 steps and stop, never sleeps under the block, creeping 1.7 mm per 30 steps at step 8,000;
-  before it, it slept at 1,378. Switched off at the stop it sleeps at 1,409, so it is the block's
-  ongoing action: it takes out the leftover turn about the corner line rigidly, about 7e-7 rad a
-  substep, and the sweeps put it back near a corner. Rope never sleeps after that see-saw in either
-  build. Running the block only on hold lines near the vertical would remove this and the item above,
-  at the price of a tolerance constant and a test against gravity; it was not done.
-- Far from the frame's origin the correction is smaller than the coordinates' rounding. A bare flag
-  100 m out turns at −0.025 at step 500 and −0.136 at 3,000, against −0.18 to −0.23 before. `ClothSystem`
-  steps a cloth in its own frame, where its coordinates are its own size.
-- After a one-kilometre teleport neither build sleeps within 2,400 steps, rope, silk, hair or chain. It
-  was so before the block, and the cause is not measured.
-
-**A fold resting on a fold never came to rest. — FIXED, `CLOTH_SELF_RATIO` 8 → 2, and the cost is
-measured.** §32 cleared `CLOTH_SELF_RATIO = 8` of adding energy on a folding sheet, whose
-contacts come and go. A self-collision pair that carries weight stays in contact, so a resting fold is
-a standing spring, which is the case M0's dissipative band was measured on. At 8 the step gains energy
-through it:
-- Two silk ribbons stacked parallel on a floor peak at 1.5 m/s after a 0.35 m/s drop, and never sleep.
-- Two crossed at 90°, dropped from gaps of 4 to 12 cm, sleep only from the 6 and 8 cm drops. From the
-  others they creep 3 to 56 mm every five seconds.
-- Piles of three to six reach up to 5.7 m/s, 1.3 to 3.8 times what their drop gives them, and are
-  left with 11 to 139 crossings. Every three-ribbon pile tried crosses.
-- §63's draped sheet stays awake on its sphere, with 14 to 18 pairs found every step.
-- A circle skirt stays awake after a twirl, with eight.
-
-At ratio 1 all of them sleep. Averaging a particle's Jacobi share over its pairs is not the fix.
-*Fixed at 2*, the stiffest ratio at which cloth resting on itself reliably comes to rest. Of 225 ribbon
-piles in silk, cotton and hair, the 135 that land without passing through themselves all sleep but
-one, and so do the draped sheet and the skirt. At 4, five of 38 clean silk piles never do, and above
-2.25 the draped sheet's sleep is erratic. *What it costs* is §32's folding sheet: 2.09 → 2.98 crossings
-a sample over 48 gusts, where ratio 1 would cost 3.74. The library bench does not move. The proof is a
-three-ribbon pile fanned 60°, asserting no crossing at any step and the order kept. "No crossings at
-rest" is not enough, because a ribbon can land right through another and lie under it. *Still open,
-and not this:* piles land through themselves, 90 of 225 at 2, every one of them while landing. That is
-§35's missing travel term in the pair search. `MEASUREMENTS.md` §64, §65.
-
-**The self radius is one per cloth, and a circle skirt's hem gets the waistband's. — FIXED: the
-radius is the particle's own (§68); Lewin's two pair-row moves wait on their limb cost.**
-`ClothState#self_radius` was `max(thickness, ½·shortest row)` capped at `0.4 × closest free pair`,
-with both the shortest row and the closest free pair measured over the whole cloth. The cloth-skirt
-example's rows run from 9.8 mm at
-the waistband to 54 mm at the hem, so the hem gets a 6 mm radius against a 37–54 mm spacing — a row
-diameter a fifth of the spacing where §9 wants one spacing — and the flutes pass through each other
-at every sample: ~400 edge-through-triangle crossings, budget-independent (272 at 4×8), the example's
-own README says "the flutes sometimes cross". `MEASUREMENTS.md` §67 measured three answers:
-
-- **The shipped formula applied per particle — LANDED (§68)**, `r_i = clamp(thickness, ½·shortest
-  row incident on i, 0.4 × closest free pair of i)`, pairs tested at `r_i + r_j`, both lengths seeded
-  into `ClothState#self_row` and `#self_free_pair` and the radius filled each step by
-  `cloth_self_radius_update`. Paired on the dance: crossings 422 → 102 a step (worst 618 → 180), a
-  thigh through in 0.6% → 0.0% of steps, the step 0.96× for 70 fewer contact rows with the hem held
-  off the legs, search and scratch 1.2× on three times the pairs; the twirled skirt's 16 crossings → 0,
-  and its gate pinned. It is still the sphere model, and a sharp fold still slips between particles.
-- **Lewin's two moves on the pair row (GDC 2018):** the particle's predicted travel in the pair
-  search's reach — §35's missing term — and the pair's normal frozen for the step, which makes the row
-  a half-space a pair cannot pass through however far the other rows shove it. On §64's eleven ribbon
-  piles they take the pair row from 6 clean and 7 in order to 10 clean and 11 in order, every pile
-  asleep, the worst crossings 7.5 → 0.2 a scene, at no new row kind. On the skirt they do not touch
-  the crossings and they cost limbs: a thigh through in 1.1–1.9% of steps against 0.1%, and 1.2% for
-  the travel term on top of the per-particle radius (crossings 38). A half-space stays active after
-  its pair has slid apart tangentially, the artefact the talk names; gating it on the live distance
-  halves the cost and keeps the piles' result. Why a wider or stickier pair row puts a hem particle
-  into a thigh is not measured, and it is what keeps the two moves from landing with the radius.
-- **Predictive point-triangle rows, as the talk's self collision,** as plain penalties into the
-  self row's Jacobi scratch: a four-particle row is only Jacobi-stable with each participant taking
-  its mass-weighted share of the correction (the pair row at ratio 2 sits exactly at the share sum
-  of 1, which is why §65 found it the stiffest that comes to rest), and with that split a ribbon
-  landing from 10 mm a step is stopped at 8 mm of separation. On their own they sleep 5 of 11 piles
-  and push the lowest ribbon into the floor; on the skirt they are unstable at every form tried (peak
-  speeds at the clamp, a thigh through in 5–7% of steps). They add the last pile only on top of the
-  pair row with Lewin's moves. The talk's own numbers say the same: 20 ms to 1 s a frame for the
-  general method, 0.1–0.2 ms only with authored layer order and cached contact sets. M4b stays what
-  it was: the thin-surface closure, not a quick win, and in this solver it wants a hard row with a
-  multiplier and a Gauss-Seidel treatment, not a penalty in the Jacobi scratch.
-
----
-
-## 19. Attachment points
-
-Written for M7, after an adversarial review of the first draft by three reviewers against the code;
-the review's findings are folded in below and listed in `MEASUREMENTS.md` §62.
-
-### 19.1 The anchor was four jobs
-
-Node 0 was the frame the cloth was simulated in, the one pinned particle, the point every tether
-measured from, and the root the rows were derived from. Only the first is a property of the entity the
-`Cloth` is on, and splitting the other three off is the whole design:
-
-| Job | Now |
-|---|---|
-| Frame: the solve, gravity, colliders, wind, §7 P7 | The `Cloth` entity for a subtree; `ClothProxy#frame` for a rig |
-| The fixed set | Held particles: any number, each held by an entity carrying a `ClothPin` |
-| Tether centre and `d_geo` | The nearest held particle along the fabric |
-| Root of the rows | A particle graph — `ClothInstance#edge`, `#skip`, `#hinge` |
-
-A cloth with no pins is the case where nothing is held, and it needs no code: every tether and slack
-row has radius `Infinity`.
-
-### 19.2 `ClothPin`
-
-On the holder, naming the cloth's entity and its particles by index — a proxy's particle order, or for
-a subtree the breadth-first walk, where 0 is the `Cloth` entity. Every field required; references fixed
-while attached; saved with its entity. A hold begins **where the particle is**: on a cloth's first step
-that is the rest pose, mid-run it is a grab. Removing the pin lets go, and the particle leaves at the
-speed its holder carried it. Destroying the cloth's entity removes the pins naming it (an entity id is
-reused). A particle two pins name goes to the lower holder; a holder the cloth itself moves is refused,
-once, by name.
-
-The world keeps one `ClothHold` per pin **outside** the seeded instance: the offsets a hold takes are
-the hold's, so a re-seed does not move what is held. The observer only notices; everything a hold
-writes into a `ClothState` is written in `ClothWorld#advance`, the one window in which the main thread
-owns that state under both systems.
-
-A holder's pose is read off its `Transform64` when the CPU owns it and evaluated exactly, under the
-clips of every model on its chain, when the GPU does; a holder whose chain is not complete yet holds
-where it last held.
-
-### 19.3 What a hold does in the step
-
-A held particle is kinematic: inverse mass zero, carried towards `kinematic_target` by an equal share
-of what remains at every substep, so it lands exactly at the last one and a target equal to the
-position moves nothing by a single bit. Chaos Cloth interpolates its kinematic particles the same way.
-Held particles are not carried by the frame's inertia; they belong to their holders.
-
-**One tether per particle, to the nearest held particle.** Chaos tethers to the nearest of up to four
-kinematic islands; that is four hard rows per particle, three of them idle on every cloth with one
-hold, and two hard tethers to holders pulled apart are bounds no position satisfies. The fabric between
-two holders already carries everything a second tether would. The search is one Dijkstra over the
-fabric edges with every held particle a source, in double. A tether starts no tighter than where its
-particle already is and only ever comes in, so a hold taken mid-run does not snap the cloth onto it.
-
-The **animated pose** is the rest pose hung from the nearest held particle and turned with its holder,
-`s_i = x_p + R_p·(r_i − r_p)`; it keeps §3.4's factor of two exact. When no holder has moved in the
-frame since the last step — every holder that rides its frame — nothing per step is recomputed.
-
-`reach` is the largest `d_geo`, with a particle no hold reaches counted at its rest distance from the
-frame's origin.
-
-### 19.4 The rig path
-
-A rig proxy's particles are the garment's joints and the bones it hangs from; cloth writes the first
-and reads the second, each step, exactly, to express the garment's roots against. The builder finds
-the bones, the frame and the pins; the spawn code adds the pins. `Cloth` and `ClothRig` stay on the
-model's root, which is saved, rather than on a bone, which is not.
-
-### 19.5 Sheets
-
-A sheet is a skin with **one joint per vertex**, every one hanging straight off one root joint, and
-`cloth_proxy_from_mesh` builds its proxy from the triangles over them: a stretch row per edge, a hinge
-per interior edge — the shared edge, then each triangle's opposite wing, which is `cloth_bend_row`'s
-stencil — the root joint as the frame, and nothing pinned: a pin on a pole names the hoist. A triangle
-with no area, an edge three triangles share, joints under two roots and a name the skin lacks are
-refused by name. `ClothProxy` carries its graph (`edge`, `skip`, `hinge`, `triangle`) for both
-builders.
-
-A hinge's stiffness is the skip row's rule over its own stencil, `bend ratio × (m / Σ w²) / h²`: a
-hinge across a sliver, whose cotangent weights are large, is softer per unit of `C` for exactly the
-reason its `C` is larger, and stays inside M0's dissipative band where a stiffness in newtons per metre
-would leave it.
-
-A joint with triangles round it has no chain to swing along, and what its orientation is for is the
-normal it turns its vertex's normal by. It takes the swing carrying the area-weighted normal of its
-triangles in the animated pose onto the same in the simulated one, then the twist about that normal
-carrying one fixed neighbour's direction onto where it is now. A joint hanging straight off the frame is
-written in the frame.
-
-### 19.6 Not done
-
-- **Drawing a sheet: the route exists, nothing takes it yet.** A skin is a `MeshSkin` on the mesh it
-  deforms and a rig names that entity (`38b2fe208`, `0e20799be`), so a sheet built in code needs no
-  loaded asset: a mesh entity with `ShadedGeometry` and a `MeshSkin` naming the vertex joints, named
-  by `ClothRig.from(proxy, mesh)`. Not built: a helper that makes that geometry, its skin and the
-  joints from the triangles, and anything that shows a sheet drawn.
-- **The cost of a joint per vertex.** About 620 ns a joint a step, on the main thread, where
-  `WorkerClothSystem` leaves it: 0.25 ms for a 400-particle sheet. `MEASUREMENTS.md` §63.
-- **Curved rest shapes.** The hinge stencil reads a curved rest as already bent (§18); a flag, a banner
-  and a circle skirt cut flat are what it serves.
-- **Welding.** The builder takes a mesh that is already one joint per welded vertex.
-- **A sheet held at one point, or by two holders that see-saw.** The hold-line block that stopped a
-  flag turning on its pole covers a line only, and after a see-saw it keeps a corner-held sheet awake
-  (§18).
-- **A seam between holders that move apart** (§18).
-- **A pile landing through itself.** A fold resting on a fold comes to rest since the self-collision row
-  went to 2 (§18). What is left is a pile passing through itself while it lands, which is §35's
-  missing travel term in the pair search.