@woosh/meep-engine 3.43.0 → 3.45.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.
@@ -241,7 +270,7 @@ export class ClothCollider {
     friction_scale = 1;  // multiplies the entity's Collider#friction
     layer = 1;           // RigidBody semantics, and see below
     mask = 0xFFFFFFFF;
-    flags = 0;           // ClothColliderFlags.Static
+    flags = 0;           // ClothColliderFlags: none defined; bit 0 was Static, retired
 }
 ```
 
@@ -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
@@ -611,10 +675,12 @@ bundles — the engine ships raw source, and a check moved out of `assert.*` sto
 ### 5.4 Colouring
 
 The particle graph is coloured so no constraint touches two particles of the same colour, using the
-existing `core/graph/coloring/colorizeGraphGreedy.js` and checked by the existing
-`validateGraphColoring.js`. Bending stencils span four particles, so the graph is the mesh graph plus
-the bend diagonals — around 8–10 colours for typical garment topology. Colouring runs once, on a
-`Graph` object, and is baked into the `ClothProxy` as colour ranges over a permuted particle order;
+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.
 
@@ -696,6 +762,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 +1106,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 +1131,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 +1270,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,9 +1613,16 @@ 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
+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.
@@ -1702,9 +1805,9 @@ What this design takes from the engine rather than building:
 | Mesh topology, adjacency, bending stencils | `core/geom/3d/topology/struct/binary/` — `BinaryTopology`, `bt_edge_read_diamond`, `bt_edge_is_boundary`, `bt_collect_boundary_segments` |
 | Proxy decimation | `bt_mesh_simplify_by_error`, `bt_mesh_compute_vertex_quadrics` |
 | Mesh cleanup | `geometry_deduplicate_vertices` |
-| Graph colouring | `core/graph/coloring/colorizeGraphGreedy.js`, `validateGraphColoring.js` |
+| 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_matrix4_project` |
+| 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` |
@@ -2361,6 +2464,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 +2648,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 +2770,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.