@yali-engine/physics 0.0.0-stage → 0.4.0

package/dist/cloth.js

@@ -0,0 +1,1578 @@
+// Kanduka's GPU cloth runtime (ADR-0101), `@yali-engine/physics/gpu`: the `physics.Cloth` component,
+// the system that turns cloth entities and colliders into GPU records each frame, and the
+// compute work the render plugin records before its frame graph (`render.prepasses`): one
+// dispatch per fixed step for every cloth (a workgroup each, shaders/kanduka/cloth.wesl), then
+// one that writes the interpolated vertices into the renderer's vertex pool. WebGPU core only;
+// elsewhere the cloths draw at rest (a CPU fallback is a later step).
+import { registerTransforms, YaliError } from '@yali-engine/core';
+import { clothTopology, FABRICS, NO_VERTEX, packCloth, splitTorn } from "./cloth-asset.js";
+import { registerPhysics, ShapeKind } from "./components.js";
+import { kandukaCloth } from "./gpu-shaders.gen.js";
+/** Preset fabric ids: 1-based, in `FABRICS` order. */
+const PRESETS = Object.keys(FABRICS);
+/**
+ * `physics.Cloth` values (ADR-0101): `asset` from `ClothSystem.addAsset`. Put it on an entity with
+ * a `Transform` and a `render.Mesh` (its material and colour are the cloth's; the system sets the
+ * mesh). Pinned vertices follow the entity's pose.
+ *
+ * @example
+ * const flagAsset = clothSys.addAsset(clothGrid({ width: 3, height: 2, pin: 'left' }));
+ * world.insert(flag, Cloth, cloth(flagAsset, { fabric: 'canvas' }));
+ */
+export function cloth(asset, o = {}) {
+    const f = o.fabric ?? 'cotton';
+    const fabric = typeof f === 'number' ? f : PRESETS.indexOf(f) + 1;
+    if (!(fabric > 0))
+        throw Object.assign(new YaliError('PHYSICS_INVALID', `No fabric ${JSON.stringify(f)}.`, `Use one of ${PRESETS.join(', ')}, or an id from addFabric.`), { path: 'fabric' });
+    if (!(asset > 0))
+        throw Object.assign(new YaliError('PHYSICS_INVALID', `Cloth asset ${asset}.`, 'Pass the id ClothSystem.addAsset returned.'), { path: 'asset' });
+    const wind = o.wind ?? 1;
+    if (!(wind >= 0 && Number.isFinite(wind)))
+        throw Object.assign(new YaliError('PHYSICS_INVALID', `Cloth wind ${wind}.`, 'Give a share of the wind ≥ 0 (1: all of it).'), { path: 'wind' });
+    const sc = o.selfCollision ?? false;
+    if (!(typeof sc === 'boolean' || (sc > 0 && Number.isFinite(sc)))) {
+        throw Object.assign(new YaliError('PHYSICS_INVALID', `Cloth selfCollision ${sc}.`, 'Give true, false, or a distance in metres above 0.'), { path: 'selfCollision' });
+    }
+    const tear = o.tear ?? 0;
+    if (!(tear >= 0 && Number.isFinite(tear)))
+        throw Object.assign(new YaliError('PHYSICS_INVALID', `Cloth tear ${tear}.`, 'Give the strain at which it tears (0.3: 30% stretch), or 0 for never.'), { path: 'tear' });
+    const tt = o.tether ?? false;
+    if (!(typeof tt === 'boolean' || (tt >= 0 && Number.isFinite(tt))))
+        throw Object.assign(new YaliError('PHYSICS_INVALID', `Cloth tether ${tt}.`, 'Give true, false, or a slack ≥ 0 (0.02: 2% longer than the distance over the mesh).'), { path: 'tether' });
+    const backstop = o.backstop ?? 0.01;
+    if (!(backstop >= 0 && Number.isFinite(backstop)))
+        throw Object.assign(new YaliError('PHYSICS_INVALID', `Cloth backstop ${backstop}.`, 'Give a distance in metres ≥ 0.'), { path: 'backstop' });
+    return { asset, fabric, wind, selfCollision: sc === true ? -1 : sc === false ? 0 : sc, tear, tether: tt === true ? 0.02 : tt === false ? 0 : Math.max(tt, 1e-6), body: o.body ?? 0, backstop, handle: 0 };
+}
+// WebGPU flags as numbers: the globals don't exist in Node, which imports this module in tests.
+const STORAGE = 0x80;
+const COPY_DST = 0x8;
+const COPY_SRC = 0x4;
+const UNIFORM = 0x40;
+const MAP_READ = 0x1;
+const QUERY_RESOLVE = 0x200;
+const COMPUTE = 0x4;
+/** Bytes per parameter slot (a dynamic uniform offset), and the slot the vertex write reads. */
+const SLOT = 256;
+const SLOTS = 256;
+const WRITE_SLOT = SLOTS - 1;
+/** Most fixed steps one frame runs (catch-up from the clock is capped; `step(n)` may queue more, up to the slots). */
+const MAX_CLOCK_STEPS = 8;
+const CLOTH_BYTES = 160;
+/** Bytes of one step's parameters (the shader's `Params`). */
+const PARAM_BYTES = 96;
+const COLLIDER_BYTES = 80;
+/** A free vertex gets a backstop when it starts within this distance (m) of the body's skin (ADR-0108). */
+const BACKSTOP_RANGE = 0.06;
+/**
+ * The cloth solver (the `cloth` resource): assets, fabrics, the wind, and the GPU work. Every
+ * cloth is in one solver group sharing a frame (world axes, metres from the first cloth's
+ * origin, f64), so cloths spread over kilometres lose precision; one group per region is later.
+ */
+export class ClothSystem {
+    Cloth;
+    /** The tag the system puts on a cloth's skinned body (ADR-0108), so only bodies are read each frame. */
+    ClothBody;
+    world;
+    /** The scene's wind (live). */
+    wind;
+    gravity;
+    /** Substeps per fixed step (live: 8 is softer and cheaper, 32 stiffer). */
+    substeps;
+    /** XPBD's bending passes per substep on the GPU (live, ADR-0128). */
+    bendIterations;
+    /** Substeps per fixed step on the CPU cloth (live). */
+    cpuSubsteps;
+    /** The most speed a vertex may reach, m/s (live). */
+    maxSpeed;
+    /** The GPU solver (live: ADR-0101's XPBD or ADR-0105's VBD). */
+    solver;
+    /**
+     * XPBD's wide step (ADR-0110, live, default on): each phase dispatched over the whole GPU for
+     * every cloth at once, instead of a cloth's whole step in one workgroup (one multiprocessor).
+     */
+    wide = true;
+    /** VBD's substeps per fixed step and iterations per substep (live). */
+    vbdSubsteps;
+    vbdIterations;
+    /** VBD's hard strain limit on each edge (live; 0: none). */
+    strainLimit;
+    /** Stops the clock's steps (`step(n)` still runs). */
+    paused = false;
+    /**
+     * Vertex splitting (ADR-0108): every this many frames a tearable cloth's tear flags are read back
+     * and its torn edges split into clean cuts (0: only when `flushTears()` is called, for goldens).
+     */
+    splitEvery = 20;
+    #splitWarned = false;
+    #render;
+    #app;
+    #assets = [];
+    #fabrics = PRESETS.map((k) => FABRICS[k]);
+    #instances = [];
+    #words = new Uint32Array(1 << 14);
+    #wordCount = 0;
+    /** Words the self-colliding cloths' hash tables need. */
+    #hashWords = 0;
+    /** Words the tearable cloths' triangle lists need. */
+    #indexWords = 0;
+    #vertices = 0;
+    #origin = new Float64Array(3);
+    #frame = 0;
+    #seenSteps = -1;
+    #manual = 0;
+    #simTime = 0;
+    // Colliders this frame: entity, shape, dims, friction, pose now (f64, group frame).
+    #colliderEntities = [];
+    #colliderData = new Float32Array(64 * 20);
+    #colliderCount = 0;
+    #colliderSim = new Map();
+    #skipped = 0;
+    #warned = false;
+    #gpu = null;
+    #cpu = null;
+    #cpuMs = Number.NaN;
+    #trash = [];
+    #gpuMs = Number.NaN;
+    #query;
+    #writeQuery;
+    #colliderQuery;
+    #bodyQuery;
+    /** This frame's bodies: mesh, palette row + 1, pose (t xyz in f64, r xyzw, s). */
+    #bodies = new Map();
+    /** Bodies a cloth names that are not tagged yet: tagged after this frame's extract. */
+    #untagged = new Set();
+    /** Anchor records after the colliders this frame. */
+    #anchorCount = 0;
+    /** Threads per cloth on this device (0 before the GPU state exists). */
+    workgroup = 0;
+    #workgroupOption;
+    /** Called with each GPU time measured (ms), for the profiler. */
+    onGpuTime = null;
+    constructor(app, render, o = {}) {
+        this.#app = app;
+        this.world = app.world;
+        this.#render = render;
+        this.substeps = Math.max(1, Math.round(o.substeps ?? 16));
+        this.bendIterations = Math.max(1, Math.round(o.bendIterations ?? 1));
+        this.cpuSubsteps = Math.max(1, Math.round(o.cpuSubsteps ?? 8));
+        this.#workgroupOption = o.workgroupSize ?? 1024;
+        this.maxSpeed = o.maxSpeed ?? 60;
+        this.solver = o.solver ?? 'xpbd';
+        this.vbdSubsteps = Math.max(1, Math.round(o.vbd?.substeps ?? 2));
+        this.vbdIterations = Math.max(1, Math.round(o.vbd?.iterations ?? 6));
+        this.strainLimit = o.vbd?.strainLimit ?? 0.1;
+        this.gravity = [...(o.gravity ?? [0, -9.81, 0])];
+        this.wind = { velocity: [0, 0, 0], turbulence: 0.3, gust: 0.3, gustFrequency: 0.2, airDensity: 1.2, ...o.wind };
+        this.Cloth = this.world.registerComponent({ name: 'physics.Cloth', fields: { asset: 'u32', fabric: 'u32', wind: 'f32', selfCollision: 'f32', tear: 'f32', tether: 'f32', body: 'entity', backstop: 'f32', handle: 'u32' } });
+        this.ClothBody = this.world.registerComponent({ name: 'physics.ClothBody', fields: {} });
+        const { GlobalTransform } = registerTransforms(this.world);
+        const { Collider } = registerPhysics(this.world);
+        const Mesh = render.Mesh;
+        this.#query = this.world.query({
+            with: Mesh ? [this.Cloth, GlobalTransform, Mesh] : [this.Cloth, GlobalTransform],
+            columns: [
+                [this.Cloth, 'asset'],
+                [this.Cloth, 'fabric'],
+                [this.Cloth, 'handle'],
+                [GlobalTransform, 't'],
+                [GlobalTransform, 'r'],
+                [GlobalTransform, 's'],
+                [this.Cloth, 'wind'],
+                [this.Cloth, 'selfCollision'],
+                [this.Cloth, 'tear'],
+                [this.Cloth, 'tether'],
+                [this.Cloth, 'body'],
+                [this.Cloth, 'backstop'],
+            ],
+        });
+        this.#bodyQuery = Mesh ? this.world.query({ with: [this.ClothBody, Mesh, GlobalTransform], columns: [[Mesh, 'mesh'], [Mesh, 'skin'], [GlobalTransform, 't'], [GlobalTransform, 'r'], [GlobalTransform, 's']] }) : null;
+        this.#writeQuery = Mesh ? this.world.query({ with: [this.Cloth, Mesh], columns: [[this.Cloth, 'handle', 'write'], [Mesh, 'mesh', 'write']] }) : null;
+        this.#colliderQuery = this.world.query({
+            with: [Collider, GlobalTransform],
+            columns: [
+                [Collider, 'shape'],
+                [Collider, 'dims'],
+                [Collider, 'offsetT'],
+                [Collider, 'offsetR'],
+                [Collider, 'friction'],
+                [Collider, 'sensor'],
+                [GlobalTransform, 't'],
+                [GlobalTransform, 'r'],
+            ],
+        });
+    }
+    /** Where cloths simulate: the GPU (WebGPU core), the CPU (the physics variant's CPU cloth, ADR-0102), or nowhere (they draw at rest). */
+    get mode() {
+        return this.supported ? 'gpu' : this.world.core.exports.yali_cloth_step ? 'cpu' : 'none';
+    }
+    /** Whether cloths simulate on the GPU (WebGPU core). */
+    get supported() {
+        return this.#render.backend === 'webgpu' && !!this.#render.gpu;
+    }
+    /** Registers a cloth mesh (the topology is built and coloured now); returns its id for `cloth()`. */
+    addAsset(mesh) {
+        this.#assets.push(clothTopology(mesh));
+        return this.#assets.length;
+    }
+    /** Registers a fabric; returns its id for `cloth({ fabric })`. */
+    addFabric(f) {
+        for (const [k, v] of Object.entries(f)) {
+            if (!(typeof v === 'number' && v >= 0 && Number.isFinite(v)))
+                throw Object.assign(new YaliError('PHYSICS_INVALID', `Fabric ${k} is ${v}.`, 'Give a finite number ≥ 0.'), { path: k });
+        }
+        this.#fabrics.push(f);
+        return this.#fabrics.length;
+    }
+    /** Runs `n` more fixed steps at the next frame, whatever the clock does (deterministic goldens). */
+    step(n) {
+        this.#manual = Math.min(SLOTS - 1 - MAX_CLOCK_STEPS, this.#manual + Math.max(0, Math.floor(n)));
+    }
+    /**
+     * Counts: cloths, vertices, constraints, the most colours a cloth has, colliders, colliders
+     * skipped (shapes the cloth does not collide with yet), simulated seconds, the last frame's GPU
+     * ms (NaN without timestamps) or CPU ms, and where it runs (`gpu`, `cpu` (ADR-0102), or `none`:
+     * no WebGPU core and no physics variant).
+     */
+    stats() {
+        let cloths = 0;
+        let vertices = 0;
+        let constraints = 0;
+        let colours = 0;
+        for (const c of this.#instances) {
+            if (!c.live)
+                continue;
+            cloths++;
+            vertices += c.count;
+            constraints += c.constraints;
+            colours = Math.max(colours, c.packed.ncolours);
+        }
+        return { cloths, vertices, constraints, colours, colliders: this.#colliderCount, skippedColliders: this.#skipped, time: this.#simTime, gpuMs: this.#gpuMs, cpuMs: this.#cpuMs, mode: this.mode, supported: this.supported };
+    }
+    /** Extract (before `render.extract`): new cloths get their mesh, every cloth its pose, every collider its record. */
+    extract() {
+        this.#frame++;
+        this.#readBodies();
+        const q = this.#query;
+        let created = null;
+        const n = q.run();
+        for (let k = 0; k < n; k++) {
+            const c = q.chunk(k);
+            const asset = c.u32(0);
+            const fabric = c.u32(1);
+            const handle = c.u32(2);
+            const t = c.f64(3);
+            const r = c.f32(4);
+            const s = c.f32(5);
+            const wind = c.f32(6);
+            const selfCol = c.f32(7);
+            const tear = c.f32(8);
+            const tether = c.f32(9);
+            const bodyW = c.view(10);
+            const backstop = c.f32(11);
+            for (let i = 0; i < c.length; i++) {
+                const e = c.entity(i);
+                let inst = handle[i] > 0 ? this.#instances[handle[i] - 1] : undefined;
+                if (!inst || inst.entity !== e) {
+                    const body = bodyW[i * 2] + bodyW[i * 2 + 1] * 2 ** 32;
+                    // A cloth worn on a body waits for the body's tag (one frame): its anchors need the body's skinned pose.
+                    if (body && !this.#bodies.has(body)) {
+                        this.#untagged.add(body);
+                        continue;
+                    }
+                    inst = this.#create(e, asset[i], fabric[i], selfCol[i], tear[i], tether[i], body, backstop[i], t, r, s, i);
+                    (created ??= []).push({ entity: e, handle: this.#instances.length, mesh: inst.mesh });
+                }
+                const now = inst.now;
+                for (let a = 0; a < 3; a++)
+                    now[a] = t[i * 3 + a] - this.#origin[a];
+                now[3] = Math.abs(s[i]) || 1;
+                for (let a = 0; a < 4; a++)
+                    now[4 + a] = r[i * 4 + a];
+                inst.wind = wind[i];
+                inst.seen = this.#frame;
+            }
+        }
+        if (created && this.#writeQuery) {
+            const w = this.#writeQuery;
+            const m = w.run();
+            for (let k = 0; k < m; k++) {
+                const c = w.chunk(k);
+                const handle = c.u32(0);
+                const mesh = c.u32(1);
+                for (let i = 0; i < c.length; i++) {
+                    const e = c.entity(i);
+                    const hit = created.find((x) => x.entity === e);
+                    if (hit) {
+                        handle[i] = hit.handle;
+                        mesh[i] = hit.mesh;
+                    }
+                }
+            }
+        }
+        for (const c of this.#instances)
+            if (c.live && c.seen !== this.#frame)
+                c.live = false;
+        for (const b of this.#untagged)
+            if (this.world.isAlive(b))
+                this.world.insert(b, this.ClothBody);
+        this.#untagged.clear();
+        if (this.#instances.length > 0) {
+            this.#extractColliders();
+            this.#extractAnchors();
+            if (this.#render.backend !== 'webgpu')
+                this.#runCpu();
+        }
+    }
+    #create(entity, assetId, fabricId, selfCollision, tear, tether, body, backstop, t, r, s, i) {
+        const topo = this.#assets[assetId - 1];
+        if (!topo)
+            throw new YaliError('CLOTH_ASSET', `physics.Cloth.asset ${assetId} is not a registered cloth asset.`, 'Pass the id ClothSystem.addAsset returned.');
+        const fabric = this.#fabrics[(fabricId || 2) - 1];
+        if (!fabric)
+            throw new YaliError('CLOTH_FABRIC', `physics.Cloth.fabric ${fabricId} is not a fabric.`, `Use a preset (${PRESETS.join(', ')}) or an id from addFabric.`);
+        if (this.#instances.length === 0)
+            for (let a = 0; a < 3; a++)
+                this.#origin[a] = t[i * 3 + a];
+        const scale = Math.abs(s[i]) || 1;
+        // Where its particles start: the rest pose placed by the entity (the solver group's frame).
+        const q = [r[i * 4], r[i * 4 + 1], r[i * 4 + 2], r[i * 4 + 3]];
+        const o = [t[i * 3] - this.#origin[0], t[i * 3 + 1] - this.#origin[1], t[i * 3 + 2] - this.#origin[2]];
+        const start = new Float64Array(topo.vertices * 3);
+        for (let v = 0; v < topo.vertices; v++) {
+            const ps = topo.mesh.positions;
+            const w = rotate(q, [ps[v * 3] * scale, ps[v * 3 + 1] * scale, ps[v * 3 + 2] * scale]);
+            start.set([o[0] + w[0], o[1] + w[1], o[2] + w[2]], v * 3);
+        }
+        const anchors = body ? this.#anchorsFor(body, topo.pinned, start, backstop) : null;
+        const packed = packCloth(topo, fabric, scale, tether, anchors?.map ?? null);
+        const base = this.#wordCount;
+        if (base + packed.words.length > this.#words.length) {
+            const grown = new Uint32Array(Math.max(this.#words.length * 2, base + packed.words.length));
+            grown.set(this.#words.subarray(0, base));
+            this.#words = grown;
+        }
+        this.#words.set(packed.words, base);
+        this.#wordCount += packed.words.length;
+        // The render mesh: the rest pose, double-sided, with a culling radius that covers a swing.
+        const nv = topo.vertices;
+        // A tearable cloth reserves spare vertices for the splits its tears make (ADR-0108).
+        const cap = tear > 0 ? nv + Math.max(16, Math.ceil(nv * 0.5)) : nv;
+        const p = topo.mesh.positions;
+        const verts = new Float32Array(cap * 8);
+        const nrm = new Float64Array(nv * 3);
+        const idx = topo.mesh.indices;
+        for (let f = 0; f < topo.triangles; f++) {
+            const [a, b, c] = [idx[f * 3], idx[f * 3 + 1], idx[f * 3 + 2]];
+            const u = [p[b * 3] - p[a * 3], p[b * 3 + 1] - p[a * 3 + 1], p[b * 3 + 2] - p[a * 3 + 2]];
+            const v = [p[c * 3] - p[a * 3], p[c * 3 + 1] - p[a * 3 + 1], p[c * 3 + 2] - p[a * 3 + 2]];
+            const cr = [u[1] * v[2] - u[2] * v[1], u[2] * v[0] - u[0] * v[2], u[0] * v[1] - u[1] * v[0]];
+            for (const x of [a, b, c])
+                for (let k = 0; k < 3; k++)
+                    nrm[x * 3 + k] += cr[k];
+        }
+        let r0 = 0;
+        for (let v = 0; v < nv; v++) {
+            const l = Math.hypot(nrm[v * 3], nrm[v * 3 + 1], nrm[v * 3 + 2]) || 1;
+            verts.set([p[v * 3], p[v * 3 + 1], p[v * 3 + 2], nrm[v * 3] / l, nrm[v * 3 + 1] / l, nrm[v * 3 + 2] / l, topo.mesh.uvs?.[v * 2] ?? 0, topo.mesh.uvs?.[v * 2 + 1] ?? 0], v * 8);
+            r0 = Math.max(r0, Math.hypot(p[v * 3], p[v * 3 + 1], p[v * 3 + 2]));
+        }
+        const mesh = this.#render.meshes.add({ vertices: verts, indices: idx, state: { doubleSided: true }, radius: r0 * 3 + 4 / scale });
+        // Particles start at the rest pose placed by the entity.
+        const initial = new Float32Array(cap * 4);
+        for (let v = 0; v < nv; v++)
+            initial.set([start[v * 3], start[v * 3 + 1], start[v * 3 + 2], packed.invMass[v]], v * 4);
+        const now = new Float64Array([o[0], o[1], o[2], scale, q[0], q[1], q[2], q[3]]);
+        // Self-collision: a dense hash of twice the vertices, its counts and entries in `hash`.
+        let edges = 0;
+        let edgeSum = 0;
+        for (let k = 0; k < topo.kinds.length; k++)
+            if (topo.kinds[k] === 0)
+                (edges++, (edgeSum += topo.rest[k * 4]));
+        const selfDist = selfCollision > 0 ? selfCollision : selfCollision < 0 ? (0.6 * edgeSum * scale) / Math.max(1, edges) : 0;
+        const table = selfDist > 0 ? nextPow2(cap * 2) : 0;
+        const hashAt = this.#hashWords;
+        if (table)
+            this.#hashWords += table + 1 + cap;
+        const indexAt = this.#indexWords;
+        if (tear > 0)
+            this.#indexWords += topo.triangles * 3;
+        const inst = { entity, packed, rest: verts, fabric, selfDist, table, hashAt, tear, triangles: topo.triangles, indexAt, first: this.#vertices, count: nv, base, mesh, constraints: topo.kinds.length, initial, now, sim: now.slice(), wind: 1, live: true, seen: this.#frame, body, anchors, topo, scale, tether, cap, copies: [], masses: [], tornTotal: 0, reported: new Uint8Array(topo.kinds.length), tornRead: 'idle' };
+        this.#vertices += cap;
+        this.#instances.push(inst);
+        return inst;
+    }
+    /** This frame's tagged bodies (ADR-0108): mesh, palette row + 1, pose. */
+    #readBodies() {
+        this.#bodies.clear();
+        const q = this.#bodyQuery;
+        if (!q)
+            return;
+        const n = q.run();
+        for (let k = 0; k < n; k++) {
+            const c = q.chunk(k);
+            const mesh = c.u32(0);
+            const skin = c.u32(1);
+            const t = c.f64(2);
+            const r = c.f32(3);
+            const s = c.f32(4);
+            for (let i = 0; i < c.length; i++) {
+                this.#bodies.set(c.entity(i), { mesh: mesh[i], skin: skin[i], pose: Float64Array.of(t[i * 3], t[i * 3 + 1], t[i * 3 + 2], r[i * 4], r[i * 4 + 1], r[i * 4 + 2], r[i * 4 + 3], Math.abs(s[i]) || 1) });
+            }
+        }
+    }
+    /** Body vertex `b`'s blended skinning matrix (3 × 4, row-major) under this frame's palette, or null. */
+    #skinMatrix(skin, row, b, out) {
+        const pal = this.#render.scene?.paletteSource?.();
+        if (!pal || row <= 0)
+            return false;
+        out.fill(0);
+        let wsum = 0;
+        for (let j = 0; j < 4; j++) {
+            const w = skin[b * 8 + 4 + j] / 65535;
+            if (w === 0)
+                continue;
+            wsum += w;
+            const at = pal.at + (row - 1 + skin[b * 8 + j]) * 12;
+            for (let k = 0; k < 12; k++)
+                out[k] += w * pal.f32[at + k];
+        }
+        if (wsum <= 0)
+            out.set([1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0]);
+        return true;
+    }
+    /**
+     * A cloth's anchors on its body (ADR-0108), from where its vertices start: each pinned vertex binds
+     * to its nearest body vertex (its spot carried into that vertex's bind space, so it follows that
+     * vertex's skinning); each free vertex lying on the skin (`BACKSTOP_RANGE`) gets a backstop there.
+     */
+    #anchorsFor(body, pinned, start, radius) {
+        const b = this.#bodies.get(body);
+        const g = this.#render.meshes.geometry(b.mesh);
+        const m = new Float64Array(12);
+        if (!g?.skin || !this.#skinMatrix(g.skin, b.skin, 0, m)) {
+            throw new YaliError('CLOTH_BODY', `The cloth's body ${body} has no skinned mesh with a palette this frame.`, 'Give physics.Cloth.body the entity of a skinned render.Mesh (spawnAnimatedGltf(...).skinned[0]) with animationPlugin() installed.');
+        }
+        const nb = g.vertices.length / 8;
+        // The body's vertices where they are now, in the solver group's frame.
+        const at = new Float64Array(nb * 3);
+        const nrm = new Float32Array(nb * 3);
+        for (let v = 0; v < nb; v++)
+            this.#bodyPoint(g, b, v, m, at, v * 3, nrm, v * 3);
+        const n = pinned.length;
+        const map = new Uint32Array(n).fill(NO_VERTEX);
+        const vertex = [];
+        const bodyVertex = [];
+        const bind = [];
+        for (let v = 0; v < n; v++) {
+            let best = -1;
+            let bestD = Infinity;
+            for (let u = 0; u < nb; u++) {
+                const d = (at[u * 3] - start[v * 3]) ** 2 + (at[u * 3 + 1] - start[v * 3 + 1]) ** 2 + (at[u * 3 + 2] - start[v * 3 + 2]) ** 2;
+                if (d < bestD)
+                    (bestD = d), (best = u);
+            }
+            // A backstop holds cloth lying on the skin: within BACKSTOP_RANGE of it, on its outside. Further
+            // off, an infinite plane at the nearest vertex (a hip's, a leg's) pushed the hanging cape sideways.
+            const off = best < 0 ? 0 : (start[v * 3] - at[best * 3]) * nrm[best * 3] + (start[v * 3 + 1] - at[best * 3 + 1]) * nrm[best * 3 + 1] + (start[v * 3 + 2] - at[best * 3 + 2]) * nrm[best * 3 + 2];
+            if (best < 0 || (!pinned[v] && (bestD > BACKSTOP_RANGE * BACKSTOP_RANGE || off < -0.005)))
+                continue;
+            map[v] = vertex.length;
+            vertex.push(v);
+            bodyVertex.push(best);
+            if (!pinned[v]) {
+                bind.push(NaN, NaN, NaN);
+                continue;
+            }
+            // The pin's spot in the body's mesh space, then back through its body vertex's skinning.
+            this.#skinMatrix(g.skin, b.skin, best, m);
+            const pose = b.pose;
+            const inv = [-pose[3], -pose[4], -pose[5], pose[6]];
+            const local = rotate(inv, [start[v * 3] + this.#origin[0] - pose[0], start[v * 3 + 1] + this.#origin[1] - pose[1], start[v * 3 + 2] + this.#origin[2] - pose[2]]).map((x) => x / pose[7]);
+            bind.push(...unskin(m, local));
+        }
+        if (vertex.length === 0)
+            return null;
+        const k = vertex.length;
+        const anchors = { map, vertex: Uint32Array.from(vertex), bodyVertex: Uint32Array.from(bodyVertex), bind: Float32Array.from(bind), radius, sim: new Float32Array(k * 8), now: new Float32Array(k * 8), base: 0 };
+        this.#poseAnchors(anchors, b, g);
+        anchors.sim.set(anchors.now);
+        return anchors;
+    }
+    /**
+     * Body vertex `v` (or, with `spot`, that bind-space spot skinned like it) in the solver group's
+     * frame into `out[o..]`; with `normal`, its skinned normal into `normal[o..]`. `m` is scratch.
+     */
+    #bodyPoint(g, b, v, m, out, o, normal, no = 0, spot) {
+        this.#skinMatrix(g.skin, b.skin, v, m);
+        const x = spot ?? [g.vertices[v * 8], g.vertices[v * 8 + 1], g.vertices[v * 8 + 2]];
+        const sk = [0, 1, 2].map((r) => m[r * 4] * x[0] + m[r * 4 + 1] * x[1] + m[r * 4 + 2] * x[2] + m[r * 4 + 3]);
+        const pose = b.pose;
+        const q = [pose[3], pose[4], pose[5], pose[6]];
+        const w = rotate(q, [sk[0] * pose[7], sk[1] * pose[7], sk[2] * pose[7]]);
+        for (let a = 0; a < 3; a++)
+            out[o + a] = pose[a] + w[a] - this.#origin[a];
+        if (normal) {
+            const nv = [g.vertices[v * 8 + 3], g.vertices[v * 8 + 4], g.vertices[v * 8 + 5]];
+            const nw = rotate(q, [0, 1, 2].map((r) => m[r * 4] * nv[0] + m[r * 4 + 1] * nv[1] + m[r * 4 + 2] * nv[2]));
+            const l = Math.hypot(nw[0], nw[1], nw[2]) || 1;
+            for (let a = 0; a < 3; a++)
+                normal[no + a] = nw[a] / l;
+        }
+    }
+    /** Each anchor where its body puts it now (ADR-0108). */
+    #poseAnchors(a, b, g) {
+        const m = new Float64Array(12);
+        const now = a.now;
+        for (let k = 0; k < a.vertex.length; k++) {
+            const pin = !Number.isNaN(a.bind[k * 3]);
+            // The point (a pin's bind-space spot skinned like its body vertex) and the body's normal there.
+            this.#bodyPoint(g, b, a.bodyVertex[k], m, now, k * 8, now, k * 8 + 4, pin ? a.bind.subarray(k * 3, k * 3 + 3) : undefined);
+            now[k * 8 + 3] = a.radius;
+            now[k * 8 + 7] = 0;
+        }
+    }
+    /** Every cloth's anchors this frame, as records after the colliders (ADR-0108). */
+    #extractAnchors() {
+        let count = 0;
+        for (const c of this.#instances) {
+            const a = c.anchors;
+            if (!a || !c.live)
+                continue;
+            const b = this.#bodies.get(c.body);
+            const g = b ? this.#render.meshes.geometry(b.mesh) : null;
+            if (b && g?.skin)
+                this.#poseAnchors(a, b, g);
+            a.base = count;
+            const need = (this.#colliderCount + count + a.vertex.length) * 20;
+            if (need > this.#colliderData.length) {
+                const grown = new Float32Array(nextPow2(need));
+                grown.set(this.#colliderData);
+                this.#colliderData = grown;
+            }
+            const d = this.#colliderData;
+            for (let k = 0; k < a.vertex.length; k++) {
+                const o = (this.#colliderCount + count + k) * 20;
+                d.set(a.sim.subarray(k * 8, k * 8 + 8), o);
+                d.set(a.now.subarray(k * 8, k * 8 + 8), o + 8);
+                d.fill(0, o + 16, o + 20);
+            }
+            count += a.vertex.length;
+        }
+        this.#anchorCount = count;
+    }
+    #extractColliders() {
+        const q = this.#colliderQuery;
+        const n = q.run();
+        let count = 0;
+        let skipped = 0;
+        this.#colliderEntities.length = 0;
+        for (let k = 0; k < n; k++) {
+            const c = q.chunk(k);
+            const shape = c.u8(0);
+            const dims = c.f32(1);
+            const offT = c.f32(2);
+            const offR = c.f32(3);
+            const friction = c.f32(4);
+            const sensor = c.u8(5);
+            const t = c.f64(6);
+            const r = c.f32(7);
+            for (let i = 0; i < c.length; i++) {
+                if (sensor[i])
+                    continue;
+                if (shape[i] > ShapeKind.Box) {
+                    skipped++;
+                    continue;
+                }
+                if ((count + 1) * 20 > this.#colliderData.length) {
+                    const grown = new Float32Array(this.#colliderData.length * 2);
+                    grown.set(this.#colliderData);
+                    this.#colliderData = grown;
+                }
+                const qr = [r[i * 4], r[i * 4 + 1], r[i * 4 + 2], r[i * 4 + 3]];
+                const off = rotate(qr, [offT[i * 3], offT[i * 3 + 1], offT[i * 3 + 2]]);
+                const qq = quatMul(qr, [offR[i * 4], offR[i * 4 + 1], offR[i * 4 + 2], offR[i * 4 + 3]]);
+                const e = c.entity(i);
+                let sim = this.#colliderSim.get(e);
+                const p = [t[i * 3] + off[0] - this.#origin[0], t[i * 3 + 1] + off[1] - this.#origin[1], t[i * 3 + 2] + off[2] - this.#origin[2]];
+                if (!sim) {
+                    sim = new Float64Array([p[0], p[1], p[2], qq[0], qq[1], qq[2], qq[3]]);
+                    this.#colliderSim.set(e, sim);
+                }
+                const d = this.#colliderData;
+                const o = count * 20;
+                d.set([sim[0], sim[1], sim[2], shape[i], sim[3], sim[4], sim[5], sim[6], p[0], p[1], p[2], friction[i], qq[0], qq[1], qq[2], qq[3], dims[i * 3], dims[i * 3 + 1], dims[i * 3 + 2], 0], o);
+                this.#colliderEntities.push(e);
+                count++;
+            }
+        }
+        this.#colliderCount = count;
+        if (skipped && !this.#warned) {
+            this.#warned = true;
+            console.warn(`[yali] cloth: ${skipped} hull, mesh or heightfield colliders are ignored by the cloth (spheres, capsules and boxes only, ADR-0101). Give the cloth simpler colliders to hit.`);
+        }
+        this.#skipped = skipped;
+        if (this.#colliderSim.size > count * 2 + 64) {
+            const keep = new Set(this.#colliderEntities);
+            for (const e of this.#colliderSim.keys())
+                if (!keep.has(e))
+                    this.#colliderSim.delete(e);
+        }
+    }
+    /** The fixed steps this frame runs: the clock's (unless paused, at most 8) plus any queued with `step(n)`; and the render alpha. */
+    #takeSteps() {
+        const clock = this.#app.time.fixedSteps;
+        if (this.#seenSteps < 0)
+            this.#seenSteps = clock;
+        let steps = this.paused ? 0 : Math.min(MAX_CLOCK_STEPS, clock - this.#seenSteps);
+        this.#seenSteps = clock;
+        const manual = this.#manual;
+        steps += manual;
+        this.#manual = 0;
+        return { steps, alpha: this.paused || manual > 0 ? 1 : this.#app.time.alpha };
+    }
+    /** Every cloth's record: its pose when it last stepped and now, its fabric; `pool` is where its output vertices start. */
+    #records(pool) {
+        const rec = new ArrayBuffer(this.#instances.length * CLOTH_BYTES);
+        const u = new Uint32Array(rec);
+        const f = new Float32Array(rec);
+        for (let k = 0; k < this.#instances.length; k++) {
+            const c = this.#instances[k];
+            const o = k * (CLOTH_BYTES / 4);
+            const pk = c.packed;
+            u.set([c.first, c.count, c.base, pool(c), pk.tris, pk.adj, pk.colours, pk.ncolours, pk.cons, c.live ? 1 : 0, c.hashAt, c.table], o);
+            // Pose when last stepped (origin, scale, rotation), then now.
+            f.set(c.sim, o + 12);
+            f.set(c.now, o + 20);
+            f.set([c.fabric.damping, c.fabric.friction, c.fabric.thickness, c.fabric.drag, c.fabric.skinDrag, c.wind, c.selfDist, c.tear], o + 28);
+            u[o + 36] = c.indexAt;
+            u[o + 37] = pk.vbd;
+            u[o + 39] = c.anchors?.base ?? 0;
+            f[o + 38] = this.strainLimit;
+        }
+        return rec;
+    }
+    /** The parameter slots (`SLOT` bytes each): one per step, and the write's (`WRITE_SLOT`). */
+    #paramSlots(steps, alpha, substeps, iterations = this.vbdIterations) {
+        const dt = this.#app.time.fixedDelta;
+        const slots = new ArrayBuffer(SLOTS * SLOT);
+        const pf = new Float32Array(slots);
+        const pu = new Uint32Array(slots);
+        const w = this.wind;
+        const sub = Math.max(1, Math.round(substeps));
+        for (let k = 0; k < steps; k++) {
+            const o = k * (SLOT / 4);
+            pf.set([...this.gravity, dt / sub, ...w.velocity, this.#simTime + k * dt, w.turbulence, w.gust, w.gustFrequency, w.airDensity], o);
+            pu[o + 12] = sub;
+            pu[o + 13] = this.#colliderCount;
+            pf.set([k / steps, (k + 1) / steps, 1, steps * dt, this.maxSpeed], o + 14);
+            // VBD's iterations (the GPU picks its pipeline; the CPU steps with VBD when this is above 0, ADR-0126).
+            pu[o + 19] = iterations;
+            pu[o + 20] = this.bendIterations;
+        }
+        pf[WRITE_SLOT * (SLOT / 4) + 16] = alpha;
+        return slots;
+    }
+    /** After `steps` steps: the poses they ended at are where the next frame's start. */
+    #stepped(steps) {
+        if (steps === 0)
+            return;
+        this.#simTime += steps * this.#app.time.fixedDelta;
+        for (const c of this.#instances) {
+            c.sim.set(c.now);
+            c.anchors?.sim.set(c.anchors.now);
+        }
+        const d = this.#colliderData;
+        for (let k = 0; k < this.#colliderCount; k++) {
+            const sim = this.#colliderSim.get(this.#colliderEntities[k]);
+            if (sim)
+                sim.set([d[k * 20 + 8], d[k * 20 + 9], d[k * 20 + 10], d[k * 20 + 12], d[k * 20 + 13], d[k * 20 + 14], d[k * 20 + 15]]);
+        }
+    }
+    /** The frame's GPU work (a `render.prepasses` hook): every pending fixed step, then the vertex write. */
+    encode(encoder, pool, indexPool) {
+        for (const b of this.#trash)
+            b.destroy();
+        this.#trash.length = 0;
+        if (this.#instances.length === 0 || !this.supported)
+            return;
+        const { steps, alpha } = this.#takeSteps();
+        const live = this.#instances.length;
+        const g = this.#ensure(this.#render.gpu.device, encoder);
+        if (g.pool !== pool) {
+            g.pool = pool;
+            g.writeGroup = null;
+        }
+        this.#bind(g);
+        // Vertices a split made start where their source vertex is (ADR-0108), through a scratch buffer:
+        // WebGPU copies never go from a buffer to itself.
+        let pairs = 0;
+        for (const c of this.#instances)
+            pairs += c.copies.length / 2;
+        if (pairs > 0) {
+            const bytes = pairs * 16 * g.particles.length;
+            if (!g.splitTmp || g.splitTmp.size < bytes) {
+                g.splitTmp?.destroy();
+                g.splitTmp = g.device.createBuffer({ label: 'yali:cloth:split', size: nextPow2(bytes), usage: COPY_SRC | COPY_DST });
+            }
+            const tmp = g.splitTmp;
+            for (const dir of [0, 1]) {
+                let slot = 0;
+                for (const c of this.#instances) {
+                    for (let k = 0; k < c.copies.length; k += 2) {
+                        for (const b of g.particles) {
+                            if (dir === 0)
+                                encoder.copyBufferToBuffer(b, (c.first + c.copies[k]) * 16, tmp, slot * 16, 16);
+                            else
+                                encoder.copyBufferToBuffer(tmp, slot * 16, b, (c.first + c.copies[k + 1]) * 16, 16);
+                            slot++;
+                        }
+                    }
+                }
+            }
+            for (const c of this.#instances)
+                c.copies.length = 0;
+        }
+        // A split's vertices lost the mass of the triangles they no longer share (ADR-0115): each new
+        // inverse mass into `pos.w`, after the copies above (which brought the source's).
+        let masses = 0;
+        for (const c of this.#instances)
+            masses += c.masses.length / 2;
+        if (masses > 0) {
+            if (!g.massTmp || g.massTmp.size < masses * 4) {
+                g.massTmp?.destroy();
+                g.massTmp = g.device.createBuffer({ label: 'yali:cloth:masses', size: nextPow2(masses * 4), usage: COPY_SRC | COPY_DST });
+            }
+            const vals = new Uint32Array(masses);
+            let k = 0;
+            for (const c of this.#instances)
+                for (let i = 1; i < c.masses.length; i += 2)
+                    vals[k++] = c.masses[i];
+            g.device.queue.writeBuffer(g.massTmp, 0, vals);
+            k = 0;
+            for (const c of this.#instances) {
+                for (let i = 0; i < c.masses.length; i += 2)
+                    encoder.copyBufferToBuffer(g.massTmp, 4 * k++, g.particles[0], (c.first + c.masses[i]) * 16 + 12, 4);
+                c.masses.length = 0;
+            }
+        }
+        const dev = g.device;
+        dev.queue.writeBuffer(g.cloths, 0, this.#records((c) => this.#render.meshes.entries[c.mesh].baseVertex));
+        const records = this.#colliderCount + this.#anchorCount;
+        if (records > 0)
+            dev.queue.writeBuffer(g.colliders, 0, this.#colliderData.buffer, 0, records * COLLIDER_BYTES);
+        const vbd = this.solver === 'vbd';
+        const slots = this.#paramSlots(steps, alpha, vbd ? this.vbdSubsteps : this.substeps);
+        if (steps > 0)
+            dev.queue.writeBuffer(g.params, 0, slots, 0, steps * SLOT);
+        dev.queue.writeBuffer(g.params, WRITE_SLOT * SLOT, slots, WRITE_SLOT * SLOT, SLOT);
+        const timer = g.timer?.state === 'idle' ? g.timer : null;
+        const self = this.#hashWords > 0;
+        // Each step starts from a copy of the positions in `last` (render interpolation): a buffer
+        // copy between passes, so the step binds the scratch `delta` instead (ADR-0110). The
+        // timestamps span from the first pass's start to the write pass's end.
+        const used = this.#vertices * 16;
+        const subs = vbd ? this.vbdSubsteps : this.substeps;
+        const wide = this.wide && steps > 0 ? this.#wideLayout(g, slots, steps, subs) : null;
+        const n = this.#instances.length;
+        const w = g.wide;
+        for (let k = 0; k < steps; k++) {
+            encoder.copyBufferToBuffer(g.particles[0], 0, g.particles[3], 0, used);
+            const sp = encoder.beginComputePass(timer && k === 0 ? { label: 'physics.cloth', timestampWrites: { querySet: timer.query, beginningOfPassWriteIndex: 0 } } : { label: 'physics.cloth' });
+            const go = (p, x) => {
+                if (x <= 0)
+                    return;
+                sp.setPipeline(p);
+                sp.dispatchWorkgroups(Math.ceil(x / 256), n);
+            };
+            if (wide && vbd) {
+                // Wide VBD (ADR-0118): each phase over the whole GPU, a dispatch per vertex colour.
+                const iters = Math.max(1, this.vbdIterations);
+                const edges = Math.max(wide.constraints, wide.vertices);
+                for (let sub = 0; sub < subs; sub++) {
+                    sp.setBindGroup(0, g.wideGroup, [(k * subs + sub) * SLOT]);
+                    go(w.air, wide.vertices);
+                    if (sub === 0)
+                        go(w.vbd.warm, edges);
+                    go(w.vbd.predict, wide.vertices);
+                    for (let it = 0; it < iters; it++) {
+                        wide.vcolours.forEach((size, c) => go(w.vbd.colour[c], size));
+                        go(w.vbd.dual, edges);
+                    }
+                    go(w.collide, wide.vertices);
+                }
+            }
+            else if (wide) {
+                for (let sub = 0; sub < this.substeps; sub++) {
+                    sp.setBindGroup(0, g.wideGroup, [(k * this.substeps + sub) * SLOT]);
+                    go(w.air, wide.vertices);
+                    go(w.predict, wide.vertices);
+                    wide.colours.forEach((size, c) => go(w.stretch[c], size));
+                    // Bending's passes (ADR-0128): the first starts the multipliers at zero.
+                    for (let it = 0; it < Math.max(1, this.bendIterations) && wide.bends > 0; it++) {
+                        go(it === 0 ? w.bend : w.bendMore, wide.bends);
+                        go(w.bendApply, wide.vertices);
+                    }
+                    if (wide.tethers)
+                        go(w.tether, wide.vertices);
+                    go(w.collide, wide.vertices);
+                }
+            }
+            else {
+                sp.setPipeline(vbd ? g.vbd : g.step);
+                sp.setBindGroup(0, g.stepGroup, [k * SLOT]);
+                sp.dispatchWorkgroups(live);
+            }
+            if (self && wide) {
+                // Wide self-collision (ADR-0118): its phases over the whole GPU, the scan a workgroup a cloth.
+                const sc = w.self;
+                sp.setBindGroup(0, g.selfGroup, [k * SLOT]);
+                go(sc.clear, wide.table + 1);
+                go(sc.count, wide.vertices);
+                sp.setPipeline(sc.scan);
+                sp.dispatchWorkgroups(1, n);
+                go(sc.fill, wide.vertices);
+                go(sc.sort, wide.table);
+                go(sc.push, wide.vertices);
+                go(sc.apply, wide.vertices);
+            }
+            else if (self) {
+                sp.setPipeline(g.self);
+                sp.setBindGroup(0, g.selfGroup, [k * SLOT]);
+                sp.dispatchWorkgroups(live);
+            }
+            sp.end();
+        }
+        const pass = encoder.beginComputePass(timer ? { label: 'physics.cloth', timestampWrites: steps > 0 ? { querySet: timer.query, endOfPassWriteIndex: 1 } : { querySet: timer.query, beginningOfPassWriteIndex: 0, endOfPassWriteIndex: 1 } } : { label: 'physics.cloth' });
+        pass.setPipeline(g.write);
+        pass.setBindGroup(0, g.writeGroup, [WRITE_SLOT * SLOT]);
+        pass.dispatchWorkgroups(live);
+        pass.end();
+        if (this.splitEvery > 0)
+            this.#readTears(encoder, g);
+        for (const c of this.#instances) {
+            if (c.live && c.tear > 0)
+                encoder.copyBufferToBuffer(g.triOut, c.indexAt * 4, indexPool, this.#render.meshes.entries[c.mesh].lods[0].firstIndex * 4, c.triangles * 12);
+        }
+        if (timer) {
+            encoder.resolveQuerySet(timer.query, 0, 2, timer.resolve, 0);
+            encoder.copyBufferToBuffer(timer.resolve, 0, timer.read, 0, 16);
+            timer.state = 'copied';
+        }
+        else if (g.timer?.state === 'copied')
+            this.#readTimer(g.timer);
+        this.#stepped(steps);
+    }
+    /**
+     * The CPU cloth (ADR-0102), where the page has no WebGPU core: the same steps in the core's
+     * physics variant (`yali_cloth_step`, then `yali_cloth_write`), on buffers in linear memory,
+     * and the vertices handed to the renderer through `MeshStore.updateVertices`. In Extract.
+     */
+    #runCpu() {
+        const core = this.world.core;
+        const x = core.exports;
+        if (!x.yali_cloth_step || !x.yali_cloth_write) {
+            if (!this.#warned) {
+                this.#warned = true;
+                console.warn(`[yali] cloth: this page renders on ${this.#render.backend} and its core has no CPU cloth, so cloths stay at their rest pose. Load the physics variant (import @yali-engine/physics, or features: ['physics'] in yali.config.ts).`);
+            }
+            return;
+        }
+        const t0 = performance.now();
+        const { steps, alpha } = this.#takeSteps();
+        const m = this.#ensureCpu();
+        const heap = core.heap;
+        heap.refresh();
+        const rec = new Uint32Array(this.#records((c) => c.first));
+        heap.u32.set(rec, m.cloths >>> 2);
+        // The colliders, then the skinned anchors' records (ADR-0108; pins and backstops on the CPU too, ADR-0126).
+        const records = this.#colliderCount + this.#anchorCount;
+        heap.f32.set(this.#colliderData.subarray(0, records * 20), m.colliders >>> 2);
+        const vbd = this.solver === 'vbd';
+        const slots = new Uint32Array(this.#paramSlots(steps, alpha, vbd ? this.vbdSubsteps : this.cpuSubsteps, vbd ? this.vbdIterations : 0));
+        const n = this.#instances.length;
+        const w = this.world.handle;
+        for (let k = 0; k <= steps; k++) {
+            const slot = k < steps ? k : WRITE_SLOT;
+            heap.u32.set(slots.subarray(slot * (SLOT / 4), slot * (SLOT / 4) + 20), m.params >>> 2);
+            const status = k < steps
+                ? x.yali_cloth_step(w, m.params, m.cloths, n, m.st, this.#wordCount, m.particles, m.cap, m.colliders, records, m.torn, this.#wordCount)
+                : x.yali_cloth_write(w, m.params, m.cloths, n, m.st, this.#wordCount, m.particles, m.cap, m.out, m.cap * 8);
+            this.world.check(status);
+        }
+        heap.refresh();
+        // Tears split into clean cuts here too (ADR-0117), every `splitEvery` frames: the flags are in
+        // linear memory, read with no readback.
+        if (steps > 0 && this.splitEvery > 0 && this.#frame % this.splitEvery === 0)
+            this.#cpuTears(m);
+        for (const c of this.#instances) {
+            // The mesh's whole block: a tearable cloth's holds its spare slots too (ADR-0108).
+            if (c.live)
+                this.#render.meshes.updateVertices(c.mesh, heap.f32.subarray((m.out >>> 2) + c.first * 8, (m.out >>> 2) + (c.first + c.cap) * 8));
+        }
+        this.#stepped(steps);
+        this.#cpuMs = performance.now() - t0;
+    }
+    /**
+     * The CPU cloth's tears (ADR-0117): each tearable cloth's compact flags read from linear memory and
+     * split (`#split`, the GPU path's), then the split applied here: the new vertices' particles copied
+     * from their sources, the changed inverse masses, the new uvs in the output, and the render mesh's
+     * triangles rewritten (`MeshStore.updateIndices`).
+     */
+    #cpuTears(m) {
+        const heap = this.world.core.heap;
+        for (const c of this.#instances) {
+            if (!c.live || c.tear <= 0)
+                continue;
+            const [at, n] = this.#tornRange(c);
+            const before = c.count;
+            this.#split(c, heap.u32.slice((m.torn >>> 2) + at, (m.torn >>> 2) + at + n));
+            if (c.count === before)
+                continue;
+            heap.refresh();
+            const f = heap.f32;
+            const u = heap.u32;
+            const p = m.particles >>> 2;
+            for (let k = 0; k < c.copies.length; k += 2) {
+                const src = (c.first + c.copies[k]) * 4;
+                const dst = (c.first + c.copies[k + 1]) * 4;
+                for (let a = 0; a < 4; a++)
+                    f.copyWithin(p + a * m.cap * 4 + dst, p + a * m.cap * 4 + src, p + a * m.cap * 4 + src + 4);
+            }
+            for (let k = 0; k < c.masses.length; k += 2)
+                u[p + (c.first + c.masses[k]) * 4 + 3] = c.masses[k + 1];
+            c.copies.length = 0;
+            c.masses.length = 0;
+            f.set(c.rest, (m.out >>> 2) + c.first * 8);
+            this.#render.meshes.updateIndices(c.mesh, c.topo.mesh.indices);
+        }
+    }
+    /** The CPU cloth's linear-memory buffers, grown (particles copied) as cloths arrive. */
+    #ensureCpu() {
+        const core = this.world.core;
+        const x = core.exports;
+        let m = this.#cpu;
+        const heap = core.heap;
+        const alloc = (bytes) => {
+            const p = x.yali_alloc(Math.max(16, bytes));
+            if (!p)
+                throw new YaliError('CLOTH_MEMORY', `Could not allocate ${bytes} bytes of linear memory for the CPU cloth.`, 'Fewer or smaller cloths on this device.');
+            heap.refresh();
+            return p;
+        };
+        if (!m) {
+            m = this.#cpu = { cap: 0, particles: 0, out: 0, st: 0, stCap: 0, stWords: -1, torn: 0, cloths: 0, clothCap: 0, colliders: 0, colliderCap: 0, params: alloc(PARAM_BYTES), uploaded: 0 };
+        }
+        if (this.#vertices > m.cap) {
+            const cap = nextPow2(Math.max(1024, this.#vertices));
+            const particles = alloc(cap * 96);
+            const out = alloc(cap * 32);
+            if (m.cap > 0) {
+                // Each of the four arrays to its new stride; the output (uvs and all) as it is.
+                for (let a = 0; a < 4; a++)
+                    heap.u8.copyWithin(particles + a * cap * 16, m.particles + a * m.cap * 16, m.particles + (a + 1) * m.cap * 16);
+                heap.u8.copyWithin(out, m.out, m.out + m.cap * 32);
+                x.yali_dealloc(m.particles, m.cap * 96);
+                x.yali_dealloc(m.out, m.cap * 32);
+            }
+            Object.assign(m, { cap, particles, out });
+        }
+        if (this.#wordCount > m.stCap) {
+            const old = m.stCap;
+            const cap = nextPow2(this.#wordCount);
+            const st = alloc(cap * 4);
+            // The torn words keep what tore (a split appends a packing; the old ones stay), zero beyond.
+            const torn = alloc(cap * 4);
+            heap.u32.fill(0, torn >>> 2, (torn >>> 2) + cap);
+            if (old) {
+                heap.u32.copyWithin(torn >>> 2, m.torn >>> 2, (m.torn >>> 2) + old);
+                x.yali_dealloc(m.st, old * 4);
+                x.yali_dealloc(m.torn, old * 4);
+            }
+            Object.assign(m, { st, torn, stCap: cap, stWords: -1 });
+        }
+        if (m.stWords !== this.#wordCount) {
+            heap.u32.set(this.#words.subarray(0, this.#wordCount), m.st >>> 2);
+            m.stWords = this.#wordCount;
+        }
+        if (this.#instances.length * CLOTH_BYTES > m.clothCap) {
+            if (m.clothCap)
+                x.yali_dealloc(m.cloths, m.clothCap);
+            m.clothCap = nextPow2(this.#instances.length * CLOTH_BYTES);
+            m.cloths = alloc(m.clothCap);
+        }
+        if (Math.max(1, this.#colliderCount + this.#anchorCount) * COLLIDER_BYTES > m.colliderCap) {
+            if (m.colliderCap)
+                x.yali_dealloc(m.colliders, m.colliderCap);
+            m.colliderCap = nextPow2(Math.max(1, this.#colliderCount + this.#anchorCount) * COLLIDER_BYTES);
+            m.colliders = alloc(m.colliderCap);
+        }
+        // New cloths: at rest and still, their output holding the rest pose's uvs.
+        for (; m.uploaded < this.#instances.length; m.uploaded++) {
+            const c = this.#instances[m.uploaded];
+            const f = heap.f32;
+            const p = m.particles >>> 2;
+            f.set(c.initial, p + c.first * 4);
+            f.set(c.initial, p + m.cap * 4 + c.first * 4);
+            f.fill(0, p + m.cap * 8 + c.first * 4, p + m.cap * 8 + (c.first + c.count) * 4);
+            f.set(c.initial, p + m.cap * 12 + c.first * 4);
+            f.set(c.rest, (m.out >>> 2) + c.first * 8);
+            c.sim.set(c.now);
+        }
+        return m;
+    }
+    #readTimer(t) {
+        t.state = 'mapping';
+        t.read.mapAsync(MAP_READ).then(() => {
+            const v = new BigUint64Array(t.read.getMappedRange());
+            const ms = Number(v[1] - v[0]) / 1e6;
+            t.read.unmap();
+            t.state = 'idle';
+            if (ms >= 0 && ms < 1e4) {
+                this.#gpuMs = ms;
+                this.onGpuTime?.(ms);
+            }
+        }, () => (t.state = 'idle'));
+    }
+    /** The GPU state for `device`: built on first use and after a device loss (cloths restart from where they were created). */
+    #ensure(device, encoder) {
+        let g = this.#gpu;
+        if (!g || g.device !== device) {
+            g = this.#build(device);
+            this.#gpu = g;
+        }
+        // Capacity: particles grow by copy (they hold the simulation); the rest is rewritten.
+        if (this.#vertices > g.capVertices) {
+            const cap = nextPow2(Math.max(1024, this.#vertices));
+            const used = g.capVertices > 0 ? this.#instances[g.uploaded - 1] : null;
+            const usedBytes = used ? (used.first + used.count) * 16 : 0;
+            const next = [0, 1, 2, 3].map((k) => device.createBuffer({ label: `yali:cloth:${['pos', 'prev', 'vel', 'last'][k]}`, size: cap * 16, usage: STORAGE | COPY_DST | COPY_SRC }));
+            if (usedBytes > 0)
+                for (let k = 0; k < 4; k++)
+                    encoder.copyBufferToBuffer(g.particles[k], 0, next[k], 0, usedBytes);
+            this.#trash.push(...g.particles, g.delta);
+            g.particles = next;
+            g.delta = device.createBuffer({ label: 'yali:cloth:delta', size: cap * 16, usage: STORAGE });
+            g.capVertices = cap;
+            g.stepGroup = g.writeGroup = g.selfGroup = null;
+        }
+        if (this.#wordCount > g.capWords) {
+            this.#trash.push(g.st, g.torn);
+            const old = g.torn;
+            const oldWords = g.capWords;
+            g.capWords = nextPow2(this.#wordCount);
+            g.st = device.createBuffer({ label: 'yali:cloth:static', size: g.capWords * 4, usage: STORAGE | COPY_DST });
+            // The tears so far survive the growth.
+            g.torn = device.createBuffer({ label: 'yali:cloth:torn', size: g.capWords * 4, usage: STORAGE | COPY_DST | COPY_SRC });
+            encoder.copyBufferToBuffer(old, 0, g.torn, 0, oldWords * 4);
+            g.stWords = 0;
+            g.stepGroup = g.writeGroup = g.selfGroup = null;
+        }
+        if (g.stWords !== this.#wordCount) {
+            device.queue.writeBuffer(g.st, 0, this.#words.buffer, 0, this.#wordCount * 4);
+            g.stWords = this.#wordCount;
+        }
+        const need = this.#instances.length * CLOTH_BYTES;
+        if (need > g.cloths.size) {
+            this.#trash.push(g.cloths);
+            g.cloths = device.createBuffer({ label: 'yali:cloth:cloths', size: nextPow2(need), usage: STORAGE | COPY_DST });
+            g.stepGroup = g.writeGroup = g.selfGroup = null;
+        }
+        if (this.#indexWords * 4 > g.triOut.size) {
+            this.#trash.push(g.triOut);
+            g.triOut = device.createBuffer({ label: 'yali:cloth:triangles', size: nextPow2(this.#indexWords * 4), usage: STORAGE | COPY_SRC });
+            g.writeGroup = null;
+        }
+        if (this.#hashWords * 4 > g.hash.size) {
+            this.#trash.push(g.hash);
+            g.hash = device.createBuffer({ label: 'yali:cloth:hash', size: nextPow2(this.#hashWords * 4), usage: STORAGE });
+            g.selfGroup = null;
+        }
+        const needC = Math.max(1, this.#colliderCount + this.#anchorCount) * COLLIDER_BYTES;
+        if (needC > g.colliders.size) {
+            this.#trash.push(g.colliders);
+            g.colliders = device.createBuffer({ label: 'yali:cloth:colliders', size: nextPow2(needC), usage: STORAGE | COPY_DST });
+            g.stepGroup = null;
+        }
+        // New cloths' particles: at rest, still.
+        for (; g.uploaded < this.#instances.length; g.uploaded++) {
+            const c = this.#instances[g.uploaded];
+            const at = c.first * 16;
+            device.queue.writeBuffer(g.particles[0], at, c.initial);
+            device.queue.writeBuffer(g.particles[1], at, c.initial);
+            device.queue.writeBuffer(g.particles[2], at, new Float32Array(c.count * 4));
+            device.queue.writeBuffer(g.particles[3], at, c.initial);
+            c.sim.set(c.now);
+        }
+        return g;
+    }
+    #build(device) {
+        const module = device.createShaderModule({ label: 'yali:cloth', code: kandukaCloth.wgsl });
+        const buf = (type, binding, dynamic = false) => ({ binding, visibility: COMPUTE, buffer: { type, hasDynamicOffset: dynamic } });
+        const head = [buf('uniform', 0, true), buf('read-only-storage', 1), buf('read-only-storage', 2), buf('storage', 3)];
+        const stepLayout = device.createBindGroupLayout({ label: 'yali:cloth:step', entries: [...head, buf('storage', 4), buf('storage', 5), buf('storage', 10), buf('read-only-storage', 7), buf('storage', 11)] });
+        const writeLayout = device.createBindGroupLayout({ label: 'yali:cloth:write', entries: [...head, buf('storage', 6), buf('storage', 8), buf('storage', 11), buf('storage', 12)] });
+        const selfLayout = device.createBindGroupLayout({ label: 'yali:cloth:self', entries: [...head, buf('storage', 5), buf('storage', 9), buf('storage', 10)] });
+        // The widest power of two the device runs in one workgroup, up to the option.
+        const most = Math.min(this.#workgroupOption, device.limits.maxComputeInvocationsPerWorkgroup, device.limits.maxComputeWorkgroupSizeX);
+        this.workgroup = 2 ** Math.floor(Math.log2(Math.max(32, most)));
+        const pipe = (layout, entryPoint) => device.createComputePipeline({ label: `yali:cloth:${entryPoint}`, layout: device.createPipelineLayout({ bindGroupLayouts: [layout] }), compute: { module, entryPoint, constants: { WG: this.workgroup } } });
+        let timer = null;
+        if (this.#render.gpu?.features.has('timestamp-query')) {
+            timer = {
+                query: device.createQuerySet({ type: 'timestamp', count: 2 }),
+                resolve: device.createBuffer({ label: 'yali:cloth:ts', size: 16, usage: QUERY_RESOLVE | COPY_SRC }),
+                read: device.createBuffer({ label: 'yali:cloth:ts-read', size: 16, usage: MAP_READ | COPY_DST }),
+                state: 'idle',
+            };
+        }
+        for (const c of this.#instances)
+            c.sim.set(c.now);
+        const widePipe = (entryPoint) => device.createComputePipeline({ label: `yali:cloth:${entryPoint}`, layout: device.createPipelineLayout({ bindGroupLayouts: [stepLayout] }), compute: { module, entryPoint, constants: { WG: this.workgroup } } });
+        return {
+            device,
+            module,
+            wide: {
+                air: widePipe('w_air'),
+                predict: widePipe('w_predict'),
+                bend: widePipe('w_bend'),
+                bendMore: device.createComputePipeline({ label: 'yali:cloth:w_bend:more', layout: device.createPipelineLayout({ bindGroupLayouts: [stepLayout] }), compute: { module, entryPoint: 'w_bend', constants: { WG: this.workgroup, BFIRST: 0 } } }),
+                bendApply: widePipe('w_bend_apply'),
+                tether: widePipe('w_tether'),
+                collide: widePipe('w_collide'),
+                stretch: [],
+                vbd: { warm: widePipe('vw_warm'), predict: widePipe('vw_predict'), dual: widePipe('vw_dual'), colour: [] },
+                self: { clear: pipe(selfLayout, 'sw_clear'), count: pipe(selfLayout, 'sw_count'), scan: pipe(selfLayout, 'sw_scan'), fill: pipe(selfLayout, 'sw_fill'), sort: pipe(selfLayout, 'sw_sort'), push: pipe(selfLayout, 'sw_push'), apply: pipe(selfLayout, 'sw_apply') },
+            },
+            wideParams: device.createBuffer({ label: 'yali:cloth:wide-params', size: 16 * SLOT, usage: UNIFORM | COPY_DST }),
+            wideGroup: null,
+            particles: [],
+            capVertices: 0,
+            st: device.createBuffer({ label: 'yali:cloth:static', size: 16, usage: STORAGE | COPY_DST }),
+            capWords: 4,
+            stWords: 0,
+            cloths: device.createBuffer({ label: 'yali:cloth:cloths', size: CLOTH_BYTES, usage: STORAGE | COPY_DST }),
+            colliders: device.createBuffer({ label: 'yali:cloth:colliders', size: COLLIDER_BYTES, usage: STORAGE | COPY_DST }),
+            params: device.createBuffer({ label: 'yali:cloth:params', size: SLOTS * SLOT, usage: UNIFORM | COPY_DST }),
+            stepLayout,
+            writeLayout,
+            step: pipe(stepLayout, 'step'),
+            vbd: pipe(stepLayout, 'vbd'),
+            write: pipe(writeLayout, 'write'),
+            selfLayout,
+            self: pipe(selfLayout, 'selfcollide'),
+            selfGroup: null,
+            hash: device.createBuffer({ label: 'yali:cloth:hash', size: 16, usage: STORAGE }),
+            delta: device.createBuffer({ label: 'yali:cloth:delta', size: 16, usage: STORAGE }),
+            torn: device.createBuffer({ label: 'yali:cloth:torn', size: 16, usage: STORAGE | COPY_DST | COPY_SRC }),
+            triOut: device.createBuffer({ label: 'yali:cloth:triangles', size: 16, usage: STORAGE | COPY_SRC }),
+            stepGroup: null,
+            writeGroup: null,
+            pool: null,
+            uploaded: 0,
+            timer,
+            tornReads: new Map(),
+            splitTmp: null,
+            massTmp: null,
+        };
+    }
+    #bind(g) {
+        const [pos, prev, vel, last] = g.particles;
+        const b = (binding, buffer, size) => ({ binding, resource: size ? { buffer, size } : { buffer } });
+        const head = [b(0, g.params, PARAM_BYTES), b(1, g.cloths), b(2, g.st), b(3, pos)];
+        if (!g.stepGroup)
+            g.wideGroup = null;
+        g.stepGroup ??= g.device.createBindGroup({ label: 'yali:cloth:step', layout: g.stepLayout, entries: [...head, b(4, prev), b(5, vel), b(10, g.delta), b(7, g.colliders), b(11, g.torn)] });
+        g.writeGroup ??= g.device.createBindGroup({ label: 'yali:cloth:write', layout: g.writeLayout, entries: [...head, b(6, last), b(8, g.pool), b(11, g.torn), b(12, g.triOut)] });
+        g.selfGroup ??= g.device.createBindGroup({ label: 'yali:cloth:self', layout: g.selfLayout, entries: [...head, b(5, vel), b(9, g.hash), b(10, g.delta)] });
+    }
+    /**
+     * Reads every cloth's particles back from the GPU (a copy, a frame or more late): per cloth
+     * its entity and positions in world space relative to the cloth's own entity origin (xyz per
+     * vertex), for checks and tools. Null before the GPU has any.
+     */
+    /**
+     * The wide step's sizes this frame (ADR-0110): the most vertices, stretch constraints per colour
+     * and bending stencils any live cloth has; its parameter slots (step k's, with the substep index
+     * in `iterations`) uploaded, and its pipelines for each colour made.
+     */
+    #wideLayout(g, slots, steps, substeps) {
+        let vertices = 0;
+        let bends = 0;
+        let tethers = false;
+        let constraints = 0;
+        let table = 0;
+        const colours = [];
+        // VBD's vertex colours (ADR-0118): their sizes from the VBD header (offset, count).
+        const vcolours = [];
+        for (const c of this.#instances) {
+            if (!c.live)
+                continue;
+            const w = c.packed.words;
+            const at = c.packed.colours;
+            const ns = w[c.packed.vbd + 13];
+            vertices = Math.max(vertices, c.count);
+            for (let k = 0; k < ns; k++)
+                colours[k] = Math.max(colours[k] ?? 0, w[at + k + 1] - w[at + k]);
+            if (ns < c.packed.ncolours)
+                bends = Math.max(bends, w[at + ns + 1] - w[at + ns]);
+            tethers ||= w[c.packed.vbd + 5] !== 0;
+            constraints = Math.max(constraints, w[at + c.packed.ncolours]);
+            table = Math.max(table, c.table);
+            const vc = w[c.packed.vbd + 1];
+            const ncv = w[c.packed.vbd + 2];
+            for (let k = 0; k < ncv; k++)
+                vcolours[k] = Math.max(vcolours[k] ?? 0, w[vc + k + 1] - w[vc + k]);
+        }
+        for (let k = g.wide.stretch.length; k < colours.length; k++)
+            g.wide.stretch.push(this.#widePipe(g, 'w_stretch', k));
+        if (this.solver === 'vbd')
+            for (let k = g.wide.vbd.colour.length; k < vcolours.length; k++)
+                g.wide.vbd.colour.push(this.#widePipe(g, 'vw_colour', k));
+        const n = steps * substeps;
+        if (g.wideParams.size < n * SLOT) {
+            g.wideParams.destroy();
+            g.wideParams = g.device.createBuffer({ label: 'yali:cloth:wide-params', size: nextPow2(n * SLOT), usage: UNIFORM | COPY_DST });
+            g.wideGroup = null;
+        }
+        const out = new Uint32Array(n * (SLOT / 4));
+        const src = new Uint32Array(slots);
+        for (let k = 0; k < steps; k++) {
+            for (let sub = 0; sub < substeps; sub++) {
+                const o = (k * substeps + sub) * (SLOT / 4);
+                out.set(src.subarray(k * (SLOT / 4), k * (SLOT / 4) + PARAM_BYTES / 4), o);
+                out[o + 19] = sub;
+            }
+        }
+        g.device.queue.writeBuffer(g.wideParams, 0, out);
+        if (!g.wideGroup) {
+            const [pos, prev, vel] = g.particles;
+            const b = (binding, buffer, size) => ({ binding, resource: size ? { buffer, size } : { buffer } });
+            g.wideGroup = g.device.createBindGroup({ label: 'yali:cloth:wide', layout: g.stepLayout, entries: [b(0, g.wideParams, PARAM_BYTES), b(1, g.cloths), b(2, g.st), b(3, pos), b(4, prev), b(5, vel), b(10, g.delta), b(7, g.colliders), b(11, g.torn)] });
+        }
+        return { vertices, colours, bends, tethers, constraints, vcolours, table };
+    }
+    /** A wide-step pipeline (ADR-0110) on the step's layout; `colour` for `w_stretch`. */
+    #widePipe(g, entryPoint, colour = 0) {
+        return g.device.createComputePipeline({
+            label: `yali:cloth:${entryPoint}${entryPoint === 'w_stretch' || entryPoint === 'vw_colour' ? colour : ''}`,
+            layout: g.device.createPipelineLayout({ bindGroupLayouts: [g.stepLayout] }),
+            compute: { module: g.module, entryPoint, constants: { WG: this.workgroup, ...(entryPoint === 'w_stretch' ? { WCOLOUR: colour } : entryPoint === 'vw_colour' ? { VCOLOUR: colour } : {}) } },
+        });
+    }
+    /** Where a cloth's compact tear flags are in the `torn` buffer (words), and how many. */
+    #tornRange(c) {
+        return [c.base + c.packed.words[c.packed.vbd + 12], c.constraints];
+    }
+    /** The tearable cloths' tear flags, copied every `splitEvery` frames and mapped a frame later (ADR-0108). */
+    #readTears(encoder, g) {
+        for (const c of this.#instances) {
+            if (!c.live || c.tear <= 0)
+                continue;
+            let buf = g.tornReads.get(c);
+            if (c.tornRead === 'copied' && buf) {
+                c.tornRead = 'mapping';
+                const base = c.base;
+                const b = buf;
+                b.mapAsync(MAP_READ).then(() => {
+                    const flags = new Uint32Array(b.getMappedRange().slice(0));
+                    b.unmap();
+                    c.tornRead = 'idle';
+                    if (c.base === base)
+                        this.#split(c, flags);
+                }, () => (c.tornRead = 'idle'));
+                continue;
+            }
+            if (c.tornRead !== 'idle' || this.#frame % this.splitEvery !== 0)
+                continue;
+            const [at, n] = this.#tornRange(c);
+            if (!buf || buf.size < n * 4) {
+                buf?.destroy();
+                buf = g.device.createBuffer({ label: 'yali:cloth:torn-read', size: nextPow2(n * 4), usage: MAP_READ | COPY_DST });
+                g.tornReads.set(c, buf);
+            }
+            encoder.copyBufferToBuffer(g.torn, at * 4, buf, 0, n * 4);
+            c.tornRead = 'copied';
+        }
+    }
+    /**
+     * Splits every tearable cloth's torn edges now (ADR-0108), waiting for the readback: deterministic
+     * runs (goldens) call it with `splitEvery = 0` between steps.
+     */
+    async flushTears() {
+        if (this.#cpu) {
+            this.#cpuTears(this.#cpu);
+            return;
+        }
+        const g = this.#gpu;
+        if (!g)
+            return;
+        for (const c of this.#instances) {
+            if (!c.live || c.tear <= 0 || c.tornRead !== 'idle')
+                continue;
+            const [at, n] = this.#tornRange(c);
+            const buf = g.device.createBuffer({ label: 'yali:cloth:torn-flush', size: n * 4, usage: MAP_READ | COPY_DST });
+            const enc = g.device.createCommandEncoder();
+            enc.copyBufferToBuffer(g.torn, at * 4, buf, 0, n * 4);
+            g.device.queue.submit([enc.finish()]);
+            await buf.mapAsync(MAP_READ);
+            const flags = new Uint32Array(buf.getMappedRange().slice(0));
+            buf.unmap();
+            buf.destroy();
+            this.#split(c, flags);
+        }
+    }
+    /**
+     * Splits cloth `c` along the stretch constraints `flags` marks torn (ADR-0108): new vertices from
+     * its spare slots, a new packing appended to the static words (the old one is left), and the
+     * render mesh's vertices (their uvs) uploaded. The split vertices keep their source's inverse
+     * mass (a small excess of mass at cut edges).
+     */
+    #split(c, flags) {
+        const pk = c.packed;
+        const w = pk.words;
+        const pairs = [];
+        // The edges torn since the last report, each reported once per packing (ADR-0115).
+        const fresh = [];
+        for (let j = 0; j < Math.min(flags.length, c.constraints); j++) {
+            const o = pk.cons + j * 12;
+            if (!flags[j] || w[o + 2] !== NO_VERTEX)
+                continue;
+            pairs.push([w[o], w[o + 1]]);
+            if (!c.reported[j]) {
+                c.reported[j] = 1;
+                fresh.push(w[o], w[o + 1]);
+            }
+        }
+        this.#splitEdges(c, pairs);
+        if (fresh.length > 0) {
+            c.tornTotal += fresh.length / 2;
+            const e = { entity: c.entity, edges: Uint32Array.from(fresh), total: c.tornTotal };
+            for (const fn of this.#tornListeners)
+                fn(e);
+        }
+    }
+    #tornListeners = new Set();
+    /**
+     * Calls `fn` when a cloth tears (ADR-0115), a frame or a few after the tear (when its flags are read
+     * back). Returns the unsubscribe.
+     *
+     * @example
+     * const off = cloth.onTorn((e) => audio.play(rip, { at: e.entity }));
+     */
+    onTorn(fn) {
+        this.#tornListeners.add(fn);
+        return () => void this.#tornListeners.delete(fn);
+    }
+    #splitEdges(c, pairs) {
+        const res = pairs.length ? splitTorn(c.topo.mesh, pairs) : null;
+        if (!res)
+            return;
+        const n = res.mesh.positions.length / 3;
+        if (n > c.cap) {
+            if (!this.#splitWarned) {
+                this.#splitWarned = true;
+                console.warn(`[yali] cloth: a torn cloth used its ${c.cap - c.topo.vertices} spare vertices; further tears open as gaps, not clean cuts (ADR-0108).`);
+            }
+            return;
+        }
+        const old = c.count;
+        const topo = clothTopology(res.mesh);
+        let map = null;
+        if (c.anchors) {
+            map = new Uint32Array(n);
+            map.set(c.anchors.map.subarray(0, old));
+            res.source.forEach((v, k) => (map[old + k] = c.anchors.map[v]));
+            c.anchors.map = map;
+        }
+        const packed = packCloth(topo, c.fabric, c.scale, c.tether, map);
+        const base = this.#wordCount;
+        if (base + packed.words.length > this.#words.length) {
+            const grown = new Uint32Array(Math.max(this.#words.length * 2, base + packed.words.length));
+            grown.set(this.#words.subarray(0, base));
+            this.#words = grown;
+        }
+        this.#words.set(packed.words, base);
+        this.#wordCount += packed.words.length;
+        const oldMass = c.packed.invMass;
+        Object.assign(c, { packed, topo, base, count: n, constraints: topo.kinds.length, reported: new Uint8Array(topo.kinds.length) });
+        res.source.forEach((v, k) => {
+            c.copies.push(v, old + k);
+            c.rest.copyWithin((old + k) * 8, v * 8, v * 8 + 8);
+            c.initial.copyWithin((old + k) * 4, v * 4, v * 4 + 4);
+        });
+        // Each vertex's mass is its share of its triangles' area (ADR-0115): a split vertex and its
+        // source keep only their own sides', so the cut does not add mass (they kept the source's before).
+        for (let v = 0; v < n; v++) {
+            const m = packed.invMass[v];
+            if (v < old && m === oldMass[v])
+                continue;
+            F32[0] = m;
+            c.masses.push(v, U32[0]);
+            c.initial[v * 4 + 3] = m;
+        }
+        this.#render.meshes.updateVertices(c.mesh, c.rest);
+    }
+    async readPositions() {
+        const m = this.#cpu;
+        if (m && m.uploaded > 0) {
+            const heap = this.world.core.heap;
+            heap.refresh();
+            return this.#perCloth(heap.f32.slice(m.particles >>> 2, (m.particles >>> 2) + m.cap * 4), m.uploaded);
+        }
+        const g = this.#gpu;
+        if (!g || g.particles.length === 0 || g.uploaded === 0)
+            return null;
+        const used = this.#instances[g.uploaded - 1];
+        const bytes = (used.first + used.count) * 16;
+        const read = g.device.createBuffer({ label: 'yali:cloth:readback', size: bytes, usage: MAP_READ | COPY_DST });
+        const enc = g.device.createCommandEncoder();
+        enc.copyBufferToBuffer(g.particles[0], 0, read, 0, bytes);
+        g.device.queue.submit([enc.finish()]);
+        await read.mapAsync(MAP_READ);
+        const all = new Float32Array(read.getMappedRange().slice(0));
+        read.unmap();
+        read.destroy();
+        return this.#perCloth(all, g.uploaded);
+    }
+    /** Each of the first `n` cloths' positions (xyz) from a copy of the `pos` array, relative to its entity. */
+    #perCloth(all, n) {
+        return this.#instances.slice(0, n).map((c) => {
+            const positions = new Float32Array(c.count * 3);
+            for (let v = 0; v < c.count; v++)
+                for (let k = 0; k < 3; k++)
+                    positions[v * 3 + k] = all[(c.first + v) * 4 + k] - c.now[k];
+            return { entity: c.entity, positions };
+        });
+    }
+    /** Releases the GPU buffers. */
+    destroy() {
+        const g = this.#gpu;
+        if (!g)
+            return;
+        for (const b of [...g.particles, g.st, g.cloths, g.colliders, g.params, g.hash, g.delta, g.torn, g.triOut, ...this.#trash])
+            b.destroy();
+        g.timer?.query.destroy();
+        for (const b of g.tornReads.values())
+            b.destroy();
+        g.splitTmp?.destroy();
+        g.massTmp?.destroy();
+        g.wideParams.destroy();
+        this.#gpu = null;
+        this.#trash.length = 0;
+    }
+    /** GPU buffers held (the dispose leak check). */
+    get liveBuffers() {
+        return this.#gpu ? this.#gpu.particles.length + 4 : 0;
+    }
+}
+/**
+ * Kanduka's GPU cloth as a plugin (ADR-0101): provides the `cloth` resource (`ClothSystem`) and
+ * its `physics.Cloth` component, steps every cloth on the GPU each fixed step and draws it through
+ * its entity's `render.Mesh`. Needs `@yali-engine/render` (WebGPU core simulates; WebGL2 and compatibility
+ * mode draw cloths at rest). Colliders are the scene's `physics.Collider` spheres, capsules and
+ * boxes; the cloth does not push them back yet.
+ *
+ * @example
+ * const app = App.create({ core, plugins: [transformsPlugin(), renderPlugin({ canvas }), clothPlugin({ wind: { velocity: [6, 0, 0] } }), game] });
+ * // in game's build:
+ * const clothSys = b.app.resource<ClothSystem>('cloth');
+ * const flag = clothSys.addAsset(clothGrid({ width: 3, height: 2, pin: 'left' }));
+ * const e = world.spawn([...bundle, render.Mesh!, clothSys.Cloth]);
+ * world.insert(e, clothSys.Cloth, cloth(flag, { fabric: 'canvas' }));
+ */
+export function clothPlugin(o = {}) {
+    return {
+        name: '@yali-engine/physics/gpu',
+        version: '0.4.0',
+        dependencies: [
+            { name: '@yali-engine/render', range: '^0.4.0' },
+            { name: '@yali-engine/transforms', range: '^0.4.0', optional: true },
+        ],
+        build(b) {
+            const render = b.app.resource('render');
+            const sys = new ClothSystem(b.app, render, o);
+            b.provide('cloth', sys);
+            b.system({ name: 'cloth.extract', stage: 'Extract', before: ['render.extract'], run: () => sys.extract() });
+            render.prepasses.push((encoder, pool, indexPool) => sys.encode(encoder, pool, indexPool));
+            const scope = b.app.profiler.gpuScope('physics.cloth');
+            sys.onGpuTime = (ms) => b.app.profiler.gpu(scope, ms);
+            b.counter('cloth.vertices', () => sys.stats().vertices);
+            b.tool({
+                name: 'physics.cloth',
+                description: 'Cloth counts (cloths, vertices, constraints, colours, colliders, GPU ms) and the wind; sets the wind, substeps or pause when given.',
+                input: {
+                    type: 'object',
+                    properties: {
+                        wind: { type: 'array', description: 'Mean wind velocity [x, y, z], m/s.' },
+                        turbulence: { type: 'number', description: 'Turbulence, a share of the wind speed (0–1).' },
+                        substeps: { type: 'number', description: 'Solver substeps per fixed step.' },
+                        paused: { type: 'boolean', description: 'Stop or resume the clock-driven steps.' },
+                        solver: { type: 'string', description: 'The GPU solver: xpbd or vbd (ADR-0105).' },
+                        iterations: { type: 'number', description: 'VBD iterations per substep.' },
+                    },
+                },
+                run: (args) => {
+                    const w = args.wind;
+                    if (w) {
+                        if (!(Array.isArray(w) && w.length === 3 && w.every((x) => Number.isFinite(x))))
+                            throw Object.assign(new YaliError('PHYSICS_INVALID', 'wind must be [x, y, z] in m/s.', 'Pass three finite numbers.'), { path: 'wind' });
+                        sys.wind.velocity = [w[0], w[1], w[2]];
+                    }
+                    if (typeof args.turbulence === 'number')
+                        sys.wind.turbulence = args.turbulence;
+                    if (typeof args.substeps === 'number')
+                        sys.substeps = Math.max(1, Math.round(args.substeps));
+                    if (typeof args.paused === 'boolean')
+                        sys.paused = args.paused;
+                    if (args.solver !== undefined) {
+                        if (args.solver !== 'xpbd' && args.solver !== 'vbd')
+                            throw Object.assign(new YaliError('PHYSICS_INVALID', `solver ${JSON.stringify(args.solver)}.`, 'Use "xpbd" or "vbd".'), { path: 'solver' });
+                        sys.solver = args.solver;
+                    }
+                    if (typeof args.iterations === 'number')
+                        sys.vbdIterations = Math.max(1, Math.round(args.iterations));
+                    return { ...sys.stats(), wind: { ...sys.wind }, substeps: sys.solver === 'vbd' ? sys.vbdSubsteps : sys.substeps, solver: sys.solver, iterations: sys.vbdIterations, paused: sys.paused };
+                },
+            });
+            b.onDispose(() => sys.destroy());
+        },
+    };
+}
+/** One float's bits (the split's inverse masses go to the GPU as words). */
+const F32 = new Float32Array(1);
+const U32 = new Uint32Array(F32.buffer);
+function nextPow2(n) {
+    return 2 ** Math.ceil(Math.log2(Math.max(1, n)));
+}
+/** `x` through the inverse of the 3 × 4 affine `m` (row-major): the spot `m` maps to `x` (ADR-0108). */
+function unskin(m, x) {
+    const [a, b, c, d, e, f, g, h, i] = [m[0], m[1], m[2], m[4], m[5], m[6], m[8], m[9], m[10]];
+    const y = [x[0] - m[3], x[1] - m[7], x[2] - m[11]];
+    const det = a * (e * i - f * h) - b * (d * i - f * g) + c * (d * h - e * g);
+    if (Math.abs(det) < 1e-12)
+        return y;
+    return [
+        ((e * i - f * h) * y[0] - (b * i - c * h) * y[1] + (b * f - c * e) * y[2]) / det,
+        (-(d * i - f * g) * y[0] + (a * i - c * g) * y[1] - (a * f - c * d) * y[2]) / det,
+        ((d * h - e * g) * y[0] - (a * h - b * g) * y[1] + (a * e - b * d) * y[2]) / det,
+    ];
+}
+/** `q` (x, y, z, w) applied to `v`. */
+function rotate(q, v) {
+    const [x, y, z, w] = q;
+    const tx = 2 * (y * v[2] - z * v[1]);
+    const ty = 2 * (z * v[0] - x * v[2]);
+    const tz = 2 * (x * v[1] - y * v[0]);
+    return [v[0] + w * tx + (y * tz - z * ty), v[1] + w * ty + (z * tx - x * tz), v[2] + w * tz + (x * ty - y * tx)];
+}
+/** a · b (x, y, z, w). */
+function quatMul(a, b) {
+    return [
+        a[3] * b[0] + a[0] * b[3] + a[1] * b[2] - a[2] * b[1],
+        a[3] * b[1] - a[0] * b[2] + a[1] * b[3] + a[2] * b[0],
+        a[3] * b[2] + a[0] * b[1] - a[1] * b[0] + a[2] * b[3],
+        a[3] * b[3] - a[0] * b[0] - a[1] * b[1] - a[2] * b[2],
+    ];
+}
+//# sourceMappingURL=cloth.js.map