@woosh/meep-engine 3.42.0 → 3.44.0

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

@@ -18,10 +18,15 @@ 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.
+  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
@@ -63,8 +68,10 @@ The design commitments, in priority order, because they conflict and the orderin
 
 ```js
 // An entity hierarchy — rope, chain, hanging sign, a prop built out of entities.
-// Cloth simulates the transform subtree of the entity it is on. That entity is the anchor.
+// 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.
@@ -76,6 +83,12 @@ There is no mode enum and no discriminator field. **`Cloth` alone simulates the
 `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
@@ -113,6 +126,13 @@ Two rules keep the walk unambiguous:
 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
@@ -124,7 +144,7 @@ effect at whatever later moment something else happened to wake it.
 ```js
 export class ClothRig {
     proxy = null;   // ClothProxy — shared, immutable, built at import
-    skin = 0;       // which of the instance's skins the proxy's joint indices are into
+    skin = -1;      // the entity whose MeshSkin the proxy's joint indices are into
 }
 ```
 
@@ -132,7 +152,13 @@ A `ClothProxy` **object**, not a path. This is the convention the engine already
 that points at a built, shared, immutable asset: `Collider#shape` holds an `AbstractShape3D` and is
 documented as *not* serialised because shapes are shared assets the pipeline wires up;
 `ParticleEffect` holds a `ParticleLayout` and a `ParticleProgram` the same way. `ClothRig` serialises
-the proxy's identity and the skin ordinal, and the asset pipeline resolves the rest.
+the proxy'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
@@ -223,7 +249,10 @@ reach of that position. Three things fall out of that and none of them need a kn
 - **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).
+  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.
@@ -295,6 +324,11 @@ engine/physics/cloth/
     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/
@@ -485,6 +519,13 @@ iterate      repeat `iterations` times:
                        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)
@@ -563,6 +604,29 @@ non-positive-definite Hessian inside a second. A mechanism that costs, does not
 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
@@ -696,6 +760,15 @@ distinction between "pinned" and "loosely following" is a number rather than a b
 `‖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 —
@@ -1031,6 +1104,15 @@ cloth's own switches — a mode enum for two values is the discriminator field
 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
@@ -1047,6 +1129,15 @@ against the cloth's own geometry so a 3 cm pendant and a 30 m mooring line get t
 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
@@ -1177,10 +1268,13 @@ it once at seed, in the bind pose, and the ceiling is two fifths of it. `MEASURE
 "O(n) with a small constant" is right about the shape and optimistic about the constant: the pair
 search is linear in particles with no term in the pair count, and it is **12% of a frame** at the
 §17 workload, and most of everything self-collision costs. The rows themselves are nearly free.
-`MEASUREMENTS.md` §34. "The great majority of visible interpenetration" is 82% of it, and the
-stiffness that does it is `8·(m_eff/h²)`, chosen on the crossing count rather than on M0's
-dissipative band — a one-sided row that vanishes when satisfied shows no energy growth at 64×
-that. `MEASUREMENTS.md` §32.
+`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.
@@ -1517,6 +1611,13 @@ For a **rigged** garment, only steps 5–8 run, over the joint graph rather than
    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 (`colorizeGraphGreedy`, checked by `validateGraphColoring`), and permute
@@ -2361,6 +2462,45 @@ question it answers has become "does all the cloth in the scene fit in one worke
 `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
@@ -2506,6 +2646,11 @@ inextensibility, but the fixed set still has to come from the mesh boundary or f
 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.
@@ -2623,3 +2768,188 @@ whose rig was taken away kept driving the joints. Both edges are now watched by
 `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.
+
+---
+
+## 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.