@woosh/meep-engine 3.24.0 → 3.26.0

package/src/engine/physics/cloth/ecs/cloth_dynamics_map.js

@@ -1,271 +1,366 @@
-/**
- * # Normalised coordinates → row parameters
- *
- * {@link ClothDynamics}' stiffnesses are coordinates in `[0, 1]`, and this is
- * the whole of what they mean. It is one module rather than methods on the
- * value object because the mapping is *measured* — every constant below has a
- * number in `MEASUREMENTS.md` behind it — and a measured mapping deserves to be
- * readable on its own and specced on its own.
- *
- * ## Why neither stiffness maps to newtons per metre
- *
- * M0's central finding: a **soft** row — a plain penalty — is dissipative only
- * while its stiffness stays below about `8·(m/h²)`, and above that boundary the
- * step *adds* energy and the cloth sustains a limit cycle forever. More
- * iterations and more substeps shrink it; neither removes it
- * (`MEASUREMENTS.md` §6). And that boundary is not a stiffness: it is a
- * multiple of the row's own inertial scale, which moved across five decades of
- * particle mass in §4's sweep without the answer changing.
- *
- * Two consequences, one for each stiffness:
- *
- * - **`stretch` cannot be a penalty at all.** Real fabric wants a stretch
- *   stiffness far above that boundary — for a half-gram particle at 60 Hz × 2
- *   substeps it sits near 60 N/m, a rubber band — so the stretch row is hard
- *   (`Infinity`, augmented Lagrangian), and what `stretch` actually selects is
- *   {@link cloth_strain_allowance}: how far the fabric may extend before the
- *   strain-limit row of §6 stops it.
- * - **`bend` maps to a ratio.** A bend row is soft and must stay inside the
- *   dissipative band, so its stiffness is expressed as a multiple of
- *   `m_eff/dt²` — the row's own inertial scale at the **fixed** step rather
- *   than the substep. Two things fall out of that choice and both are wanted:
- *   the fabric's look is invariant to how heavy the author made the particles
- *   (which is what a normalised `[0, 1]` knob should mean), and the row is
- *   inside the band at *any* substep count, since `k/(m/h²) = ratio/substeps²`
- *   and `substeps ≥ 1`. A stiffness in newtons per metre has neither property.
- *
- * @author Alex Goldring
- * @copyright Company Named Limited (c) 2026
- */
-
-/**
- * Strain a fabric at `stretch = 0` may carry: a quarter of its own length, a
- * loose knit. Chosen as the loosest thing that still reads as fabric rather
- * than as elastic.
- * @type {number}
- */
-export const CLOTH_STRAIN_MAX = 0.25;
-
-/**
- * Strain a fabric at `stretch = 1` may carry: a tenth of a per cent, which is
- * a chain. Below this the strain-limit row is asking for more precision than a
- * `Float32` position over a garment-sized coordinate resolves.
- * @type {number}
- */
-export const CLOTH_STRAIN_MIN = 1e-3;
-
-/**
- * Bend stiffness at `bend = 1`, as a multiple of the row's `m_eff/dt²`.
- *
- * It is 8 because that is the top of the dissipative band M0 measured
- * (`MEASUREMENTS.md` §4 and §6) and a bend row is soft. The consequence, stated
- * rather than hidden: **bending saturates**. A fabric stiffer than this cannot
- * be expressed as a soft row that also comes to rest, and asking for one is
- * asking for the limit cycle §7 P5 exists to prevent. If a garment ever needs
- * more, the answer is a hard bend row with a multiplier, not a bigger number
- * here.
- * @type {number}
- */
-export const CLOTH_BEND_RATIO_MAX = 8;
-
-/**
- * Bend stiffness just above `bend = 0`, as a multiple of `m_eff/dt²`. Four
- * orders of magnitude below the ceiling, which is what makes the log map
- * useful across the whole range instead of spending most of it near zero.
- * @type {number}
- */
-export const CLOTH_BEND_RATIO_MIN = 1e-3;
-
-/**
- * How many times its own **correction authority** a particle may travel in one
- * fixed step before the velocity clamp of §7 P1 catches it.
- *
- * ## Not `thickness`, and the measurement is why
- *
- * §7 P1 asks for a clamp "derived from `thickness` and `h`", and that turns out
- * to be the wrong length scale for this job. `thickness` is a **contact**
- * radius: a clamp built from it is a tunnelling bound, and a tunnelling bound
- * sits *below* ordinary cloth speeds rather than above them. Silk is 4 mm
- * thick, so at 60 Hz "a particle may not cross its own radius in a step" is
- * 0.24 m/s — and M1 measured a rope behind a 9 m/s sprinter reaching 13 m/s
- * (§7 P7). Any multiple large enough to stop the clamp being a *behaviour* for
- * silk is large enough to make it meaningless for leather, because the two
- * thicknesses differ by 5× and their speeds do not.
- *
- * ## What the scale actually is
- *
- * The solver has a measurable ability to pull a particle back, and it is not
- * unlimited: the trust region caps each vertex update at the **shortest row
- * incident on that particle** (§5.3), so one fixed step can move a particle at
- * most `shortest_row · substeps · iterations`. M1 measured what happens past
- * it — a 30-link chain kicked at 16 m/s at 1 substep × 1 iteration stretches to
- * **17× its own reach** before recovering, against 1.02× when it is dropped
- * under gravity, and 2.6× for the same kick at 2×4. The tether row is not what
- * failed there; the tether row was never given a chance to act.
- *
- * So the clamp is a multiple of exactly that quantity, which makes it a bound
- * on *the solver being asked to do more than it can*, and makes it scale with
- * the budget the fabric bought and the mesh it is built on rather than with a
- * contact radius it does not use until M2.
- *
- * Four, because one would bind: a coat on a sprinting character carries several
- * metres a second of anchor-relative velocity, and a clamp that engages there
- * is a behaviour rather than a backstop. Four leaves every library entry an
- * order of magnitude of headroom over its measured peak and still bounds the
- * absurd cases in a handful of steps.
- * @type {number}
- */
-export const CLOTH_VELOCITY_CORRECTION_MARGIN = 4;
-
-/**
- * Velocity decay rate at `damping = 1`, per second.
- *
- * `damping` maps to an exponential decay rather than a per-step multiplier so
- * that the same value means the same thing at any fixed rate. At the default
- * `damping = 0.15` the time constant is a third of a second, which is a cape
- * that stops swinging without looking like it is under water.
- * @type {number}
- */
-export const CLOTH_DAMPING_RATE = 20;
-
-/**
- * How far a cloth's anchor may carry it in one fixed step, as a multiple of the
- * cloth's own reach. Motion above this is felt as though it were exactly this,
- * which is what "anchor speed limit" means in §7 P7.
- *
- * Expressing it as a fraction of reach rather than in metres per second is what
- * makes it work for a 3 cm pendant and a 30 m mooring line at the same time: a
- * cloth is whipped by motion large *compared to itself*, and the reach is the
- * only length scale the cloth carries. Half a reach per step is 30 reaches a
- * second at 60 Hz, which no character locomotion comes near — §7 P7's own
- * profile peaks two orders below it — and which a lift, a lurching vehicle or a
- * badly-keyed cut does exceed.
- * @type {number}
- */
-export const CLOTH_ANCHOR_TRAVEL_REACH = 0.5;
-
-/**
- * How far a cloth's anchor may rotate in one fixed step, radians. Rotation
- * above this is felt as though it were exactly this.
- *
- * Unlike the travel limit this has no length scale to hang off — an angle is
- * already dimensionless — so it is a plain number. Half a radian per step is
- * about 1,700 degrees a second, which is a spin rather than a turn.
- * @type {number}
- */
-export const CLOTH_ANCHOR_ROTATION_LIMIT = 0.5;
-
-/**
- * Anchor displacement in one fixed step, as a multiple of the cloth's reach,
- * above which the motion is a **teleport** rather than locomotion (§7 P6).
- *
- * Four reaches in one step is 240 reaches a second: for a 1 m rope that is
- * 240 m/s, well past anything the world moves at and well short of the values a
- * cut or a level load produces.
- * @type {number}
- */
-export const CLOTH_TELEPORT_REACH = 4;
-
-/**
- * Absolute floor on the teleport threshold, metres per fixed step.
- *
- * The reach multiple alone would make a small cloth absurdly twitchy — a 3 cm
- * pendant would call 7 m/s a teleport, which is a brisk walk. This floor is
- * 2 metres in a sixtieth of a second, so nothing under 120 m/s is a teleport
- * whatever size the cloth is.
- * @type {number}
- */
-export const CLOTH_TELEPORT_FLOOR = 2;
-
-/**
- * Length of the stabilisation window after a teleport reset, in fixed steps.
- *
- * The velocity limit ramps linearly from zero back to its full value across it,
- * so a re-seeded cloth cannot leave the animated pose faster than the window
- * allows however wrong its first solve is. A third of a second at 60 Hz.
- * @type {number}
- */
-export const CLOTH_STABILISE_STEPS = 20;
-
-/**
- * Speed below which a particle counts as still, as a fraction of the cloth's
- * reach per second. A metre-long rope sleeps once nothing on it is moving
- * faster than a millimetre a second.
- * @type {number}
- */
-export const CLOTH_SLEEP_SPEED_RATIO = 1e-3;
-
-/**
- * How many consecutive still steps put a cloth to sleep (§7 P5). Half a second
- * at 60 Hz, which is long enough that a cloth pausing at the top of a swing
- * does not sleep through the way down.
- * @type {number}
- */
-export const CLOTH_SLEEP_STEPS = 30;
-
-/**
- * Fabric extension allowance for a normalised `stretch`, as a fraction of rest
- * length. Log-mapped between {@link CLOTH_STRAIN_MAX} and
- * {@link CLOTH_STRAIN_MIN}, so equal steps in `stretch` are equal ratios in
- * strain and `0.9` is not four orders of magnitude away from `0.7`.
- *
- * @param {number} stretch `[0, 1]`
- * @returns {number} strain, `L_max = L₀·(1 + ε)`
- */
-export function cloth_strain_allowance(stretch) {
-    const t = stretch < 0 ? 0 : (stretch > 1 ? 1 : stretch);
-
-    return CLOTH_STRAIN_MAX * Math.pow(CLOTH_STRAIN_MIN / CLOTH_STRAIN_MAX, t);
-}
-
-/**
- * Bend row stiffness for a normalised `bend`, as a multiple of the row's own
- * `m_eff/dt²`. Log-mapped, and **exactly zero at `bend = 0`** — a log map
- * cannot reach zero, and "no bending resistance at all" is a state a chain is
- * actually in rather than a limit it approaches.
- *
- * @param {number} bend `[0, 1]`
- * @returns {number} ratio of `m_eff/dt²`
- */
-export function cloth_bend_ratio(bend) {
-    if (bend <= 0) {
-        return 0;
-    }
-
-    const t = bend > 1 ? 1 : bend;
-
-    return CLOTH_BEND_RATIO_MIN * Math.pow(CLOTH_BEND_RATIO_MAX / CLOTH_BEND_RATIO_MIN, t);
-}
-
-/**
- * Largest speed a particle may carry, metres per second. §7 P1, and see
- * {@link CLOTH_VELOCITY_CORRECTION_MARGIN} for why this is built out of the
- * mesh and the budget rather than out of `thickness`.
- *
- * @param {number} shortest_row metres — the shortest row in the cloth, which
-   is what the trust region caps a vertex update at
- * @param {number} substeps
- * @param {number} iterations
- * @param {number} dt fixed step, seconds
- * @returns {number}
- */
-export function cloth_velocity_limit(shortest_row, substeps, iterations, dt) {
-    return CLOTH_VELOCITY_CORRECTION_MARGIN * shortest_row * substeps * iterations / dt;
-}
-
-/**
- * Fraction of a particle's velocity surviving one fixed step. §7 P5, and see
- * {@link ClothDynamics#damping} for why this is a correctness mechanism rather
- * than a taste control.
- *
- * @param {number} damping `[0, 1]`
- * @param {number} dt fixed step, seconds
- * @returns {number} `[0, 1]`
- */
-export function cloth_velocity_retention(damping, dt) {
-    if (damping <= 0) {
-        return 1;
-    }
-
-    return Math.exp(-CLOTH_DAMPING_RATE * (damping > 1 ? 1 : damping) * dt);
-}
+/**
+ * # Normalised coordinates → row parameters
+ *
+ * {@link ClothDynamics}' stiffnesses are coordinates in `[0, 1]`, and this is
+ * the whole of what they mean. It is one module rather than methods on the
+ * value object because the mapping is *measured* — every constant below has a
+ * number in `MEASUREMENTS.md` behind it — and a measured mapping deserves to be
+ * readable on its own and specced on its own.
+ *
+ * ## Why neither stiffness maps to newtons per metre
+ *
+ * M0's central finding: a **soft** row — a plain penalty — is dissipative only
+ * while its stiffness stays below about `8·(m/h²)`, and above that boundary the
+ * step *adds* energy and the cloth sustains a limit cycle forever. More
+ * iterations and more substeps shrink it; neither removes it
+ * (`MEASUREMENTS.md` §6). And that boundary is not a stiffness: it is a
+ * multiple of the row's own inertial scale, which moved across five decades of
+ * particle mass in §4's sweep without the answer changing.
+ *
+ * Two consequences, one for each stiffness:
+ *
+ * - **`stretch` cannot be a penalty at all.** Real fabric wants a stretch
+ *   stiffness far above that boundary — for a half-gram particle at 60 Hz × 2
+ *   substeps it sits near 60 N/m, a rubber band — so the stretch row is hard
+ *   (`Infinity`, augmented Lagrangian), and what `stretch` actually selects is
+ *   {@link cloth_strain_allowance}: how far the fabric may extend before the
+ *   strain-limit row of §6 stops it.
+ * - **`bend` maps to a ratio.** A bend row is soft and must stay inside the
+ *   dissipative band, so its stiffness is expressed as a multiple of
+ *   `m_eff/dt²` — the row's own inertial scale at the **fixed** step rather
+ *   than the substep. Two things fall out of that choice and both are wanted:
+ *   the fabric's look is invariant to how heavy the author made the particles
+ *   (which is what a normalised `[0, 1]` knob should mean), and the row is
+ *   inside the band at *any* substep count, since `k/(m/h²) = ratio/substeps²`
+ *   and `substeps ≥ 1`. A stiffness in newtons per metre has neither property.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+
+/**
+ * Strain a fabric at `stretch = 0` may carry: a quarter of its own length, a
+ * loose knit. Chosen as the loosest thing that still reads as fabric rather
+ * than as elastic.
+ * @type {number}
+ */
+export const CLOTH_STRAIN_MAX = 0.25;
+
+/**
+ * Strain a fabric at `stretch = 1` may carry: a tenth of a per cent, which is
+ * a chain. Below this the strain-limit row is asking for more precision than a
+ * `Float32` position over a garment-sized coordinate resolves.
+ * @type {number}
+ */
+export const CLOTH_STRAIN_MIN = 1e-3;
+
+/**
+ * Bend stiffness at `bend = 1`, as a multiple of the row's `m_eff/dt²`.
+ *
+ * It is 8 because that is the top of the dissipative band M0 measured
+ * (`MEASUREMENTS.md` §4 and §6) and a bend row is soft. The consequence, stated
+ * rather than hidden: **bending saturates**. A fabric stiffer than this cannot
+ * be expressed as a soft row that also comes to rest, and asking for one is
+ * asking for the limit cycle §7 P5 exists to prevent. If a garment ever needs
+ * more, the answer is a hard bend row with a multiplier, not a bigger number
+ * here.
+ * @type {number}
+ */
+export const CLOTH_BEND_RATIO_MAX = 8;
+
+/**
+ * Bend stiffness just above `bend = 0`, as a multiple of `m_eff/dt²`. Four
+ * orders of magnitude below the ceiling, which is what makes the log map
+ * useful across the whole range instead of spending most of it near zero.
+ * @type {number}
+ */
+export const CLOTH_BEND_RATIO_MIN = 1e-3;
+
+/**
+ * How many times its own **correction authority** a particle may travel in one
+ * fixed step before the velocity clamp of §7 P1 catches it.
+ *
+ * ## Not `thickness`, and the measurement is why
+ *
+ * §7 P1 asks for a clamp "derived from `thickness` and `h`", and that turns out
+ * to be the wrong length scale for this job. `thickness` is a **contact**
+ * radius: a clamp built from it is a tunnelling bound, and a tunnelling bound
+ * sits *below* ordinary cloth speeds rather than above them. Silk is 4 mm
+ * thick, so at 60 Hz "a particle may not cross its own radius in a step" is
+ * 0.24 m/s — and M1 measured a rope behind a 9 m/s sprinter reaching 13 m/s
+ * (§7 P7). Any multiple large enough to stop the clamp being a *behaviour* for
+ * silk is large enough to make it meaningless for leather, because the two
+ * thicknesses differ by 5× and their speeds do not.
+ *
+ * ## What the scale actually is
+ *
+ * The solver has a measurable ability to pull a particle back, and it is not
+ * unlimited: the trust region caps each vertex update at the **shortest row
+ * incident on that particle** (§5.3), so one fixed step can move a particle at
+ * most `shortest_row · substeps · iterations`. M1 measured what happens past
+ * it — a 30-link chain kicked at 16 m/s at 1 substep × 1 iteration stretches to
+ * **17× its own reach** before recovering, against 1.02× when it is dropped
+ * under gravity, and 2.6× for the same kick at 2×4. The tether row is not what
+ * failed there; the tether row was never given a chance to act.
+ *
+ * So the clamp is a multiple of exactly that quantity, which makes it a bound
+ * on *the solver being asked to do more than it can*, and makes it scale with
+ * the budget the fabric bought and the mesh it is built on rather than with a
+ * contact radius it does not use until M2.
+ *
+ * Four, because one would bind: a coat on a sprinting character carries several
+ * metres a second of anchor-relative velocity, and a clamp that engages there
+ * is a behaviour rather than a backstop. Four leaves every library entry an
+ * order of magnitude of headroom over its measured peak and still bounds the
+ * absurd cases in a handful of steps.
+ * @type {number}
+ */
+export const CLOTH_VELOCITY_CORRECTION_MARGIN = 4;
+
+/**
+ * Velocity decay rate at `damping = 1`, per second.
+ *
+ * `damping` maps to an exponential decay rather than a per-step multiplier so
+ * that the same value means the same thing at any fixed rate. At the default
+ * `damping = 0.15` the time constant is a third of a second, which is a cape
+ * that stops swinging without looking like it is under water.
+ * @type {number}
+ */
+export const CLOTH_DAMPING_RATE = 20;
+
+/**
+ * How far a cloth's anchor may carry it in one fixed step, as a multiple of the
+ * cloth's own reach. Motion above this is felt as though it were exactly this,
+ * which is what "anchor speed limit" means in §7 P7.
+ *
+ * Expressing it as a fraction of reach rather than in metres per second is what
+ * makes it work for a 3 cm pendant and a 30 m mooring line at the same time: a
+ * cloth is whipped by motion large *compared to itself*, and the reach is the
+ * only length scale the cloth carries. Half a reach per step is 30 reaches a
+ * second at 60 Hz, which no character locomotion comes near — §7 P7's own
+ * profile peaks two orders below it — and which a lift, a lurching vehicle or a
+ * badly-keyed cut does exceed.
+ * @type {number}
+ */
+export const CLOTH_ANCHOR_TRAVEL_REACH = 0.5;
+
+/**
+ * How far a cloth's anchor may rotate in one fixed step, radians. Rotation
+ * above this is felt as though it were exactly this.
+ *
+ * Unlike the travel limit this has no length scale to hang off — an angle is
+ * already dimensionless — so it is a plain number. Half a radian per step is
+ * about 1,700 degrees a second, which is a spin rather than a turn.
+ * @type {number}
+ */
+export const CLOTH_ANCHOR_ROTATION_LIMIT = 0.5;
+
+/**
+ * Anchor displacement in one fixed step, as a multiple of the cloth's reach,
+ * above which the motion is a **teleport** rather than locomotion (§7 P6).
+ *
+ * Four reaches in one step is 240 reaches a second: for a 1 m rope that is
+ * 240 m/s, well past anything the world moves at and well short of the values a
+ * cut or a level load produces.
+ * @type {number}
+ */
+export const CLOTH_TELEPORT_REACH = 4;
+
+/**
+ * Absolute floor on the teleport threshold, metres per fixed step.
+ *
+ * The reach multiple alone would make a small cloth absurdly twitchy — a 3 cm
+ * pendant would call 7 m/s a teleport, which is a brisk walk. This floor is
+ * 2 metres in a sixtieth of a second, so nothing under 120 m/s is a teleport
+ * whatever size the cloth is.
+ * @type {number}
+ */
+export const CLOTH_TELEPORT_FLOOR = 2;
+
+/**
+ * Length of the stabilisation window after a teleport reset, in fixed steps.
+ *
+ * The velocity limit ramps linearly from zero back to its full value across it,
+ * so a re-seeded cloth cannot leave the animated pose faster than the window
+ * allows however wrong its first solve is. A third of a second at 60 Hz.
+ * @type {number}
+ */
+export const CLOTH_STABILISE_STEPS = 20;
+
+/**
+ * Aerodynamic relaxation rate at `drag = 1`, per second (§10).
+ *
+ * ## Linear, not log
+ *
+ * `bend` is log-mapped because a stiffness spans decades and an author needs
+ * the whole range to be useful. Drag does not: the library's own entries run
+ * from leather at 0.05 to silk at 0.45, a factor of nine, and a linear map is
+ * the one that keeps that factor of nine meaning a factor of nine. It is also
+ * exactly zero at zero without a special case, which a log map cannot be.
+ *
+ * ## Sixty, because that is "the cloth goes where the air goes"
+ *
+ * The rate is a reciprocal time constant, so what `drag = 1` has to mean is a
+ * cloth with no aerodynamic memory at all — one that takes the air's velocity
+ * within a step. At 60 Hz, a rate of 60 closes 63% of the gap to the air every
+ * step and has a time constant of 17 ms, which is that. The library then reads:
+ * silk 27/s (37 ms), hair 18/s, cotton 12/s (83 ms), rope 7.2/s, denim 4.8/s
+ * (0.21 s), leather and chain 3/s (0.33 s) — a light banner that answers a gust
+ * within a couple of frames and an armour skirt that takes a third of a second
+ * to notice one, which is the ordering the fabrics already claimed.
+ *
+ * Raising it further buys nothing: {@link cloth_drag_response} saturates at
+ * `1/dt` by construction, so past about `1/dt` the whole range compresses into
+ * "the cloth is a streamer". `MEASUREMENTS.md` §48.
+ * @type {number}
+ */
+export const CLOTH_DRAG_RATE_MAX = 60;
+
+/**
+ * Speed below which the air counts as unchanged, as a fraction of the cloth's
+ * reach per second — §10's wake test, which asks whether a gust has arrived.
+ *
+ * This was the sleep test's own threshold until the sleep test stopped reading
+ * a speed; see {@link CLOTH_SLEEP_DISPLACEMENT_RATIO} for why.
+ * @type {number}
+ */
+export const CLOTH_SLEEP_SPEED_RATIO = 1e-3;
+
+/**
+ * How far a particle may travel from the window's anchor and still count as
+ * still, as a fraction of the cloth's reach (§7 P5).
+ *
+ * **Displacement rather than speed, and a contact is why.** A cloth resting on
+ * a collider carries contact rows whose penalty `γ = 1` never decays, and the
+ * configuration it settles into is a *bounded limit cycle* rather than a rest
+ * state: measured on an 8-link rope on a floor, a tenth of a millimetre of
+ * travel per step — invisible — at a peak particle speed of 1.5e-2 m/s, which
+ * is eighteen times what the old speed threshold allowed. An instantaneous
+ * speed cannot tell a cloth vibrating in place apart from one going somewhere;
+ * the distance it has covered since the window opened can, and that is what
+ * §7 P5's own text has always described.
+ *
+ * `5e-4` rather than {@link CLOTH_SLEEP_SPEED_RATIO}'s `1e-3` so the gate is no
+ * *looser* than the speed test it replaces: over the {@link CLOTH_SLEEP_STEPS}
+ * window at the engine's 60 Hz fixed step, half a thousandth of a reach is the
+ * same millimetre a second. Every library entry on a floor or a sphere sleeps
+ * inside 961 steps at this value. `MEASUREMENTS.md` §53.
+ * @type {number}
+ */
+export const CLOTH_SLEEP_DISPLACEMENT_RATIO = 5e-4;
+
+/**
+ * How many consecutive still steps put a cloth to sleep (§7 P5). Half a second
+ * at 60 Hz, which is long enough that a cloth pausing at the top of a swing
+ * does not sleep through the way down.
+ * @type {number}
+ */
+export const CLOTH_SLEEP_STEPS = 30;
+
+/**
+ * Fabric extension allowance for a normalised `stretch`, as a fraction of rest
+ * length. Log-mapped between {@link CLOTH_STRAIN_MAX} and
+ * {@link CLOTH_STRAIN_MIN}, so equal steps in `stretch` are equal ratios in
+ * strain and `0.9` is not four orders of magnitude away from `0.7`.
+ *
+ * @param {number} stretch `[0, 1]`
+ * @returns {number} strain, `L_max = L₀·(1 + ε)`
+ */
+export function cloth_strain_allowance(stretch) {
+    const t = stretch < 0 ? 0 : (stretch > 1 ? 1 : stretch);
+
+    return CLOTH_STRAIN_MAX * Math.pow(CLOTH_STRAIN_MIN / CLOTH_STRAIN_MAX, t);
+}
+
+/**
+ * Bend row stiffness for a normalised `bend`, as a multiple of the row's own
+ * `m_eff/dt²`. Log-mapped, and **exactly zero at `bend = 0`** — a log map
+ * cannot reach zero, and "no bending resistance at all" is a state a chain is
+ * actually in rather than a limit it approaches.
+ *
+ * @param {number} bend `[0, 1]`
+ * @returns {number} ratio of `m_eff/dt²`
+ */
+export function cloth_bend_ratio(bend) {
+    if (bend <= 0) {
+        return 0;
+    }
+
+    const t = bend > 1 ? 1 : bend;
+
+    return CLOTH_BEND_RATIO_MIN * Math.pow(CLOTH_BEND_RATIO_MAX / CLOTH_BEND_RATIO_MIN, t);
+}
+
+/**
+ * Largest speed a particle may carry, metres per second. §7 P1, and see
+ * {@link CLOTH_VELOCITY_CORRECTION_MARGIN} for why this is built out of the
+ * mesh and the budget rather than out of `thickness`.
+ *
+ * @param {number} shortest_row metres — the shortest row in the cloth, which
+   is what the trust region caps a vertex update at
+ * @param {number} substeps
+ * @param {number} iterations
+ * @param {number} dt fixed step, seconds
+ * @returns {number}
+ */
+export function cloth_velocity_limit(shortest_row, substeps, iterations, dt) {
+    return CLOTH_VELOCITY_CORRECTION_MARGIN * shortest_row * substeps * iterations / dt;
+}
+
+/**
+ * §10's aerodynamic coupling as the **per-step response** the step multiplies
+ * the relative flow by, 1/s.
+ *
+ * Not a rate, and the difference is a stability argument rather than a
+ * convenience. The step holds one acceleration for the whole fixed step, so an
+ * explicit `rate·(u − v)` changes the velocity by `rate·dt·(u − v)` — which
+ * overshoots the air once `rate·dt > 1` and diverges past 2. §1's first
+ * commitment is "not at 5 fps", which is a `dt` of 0.2 s and a rate of 10.
+ *
+ * The exact solution of the same linear ODE has no such boundary:
+ *
+ *     Δv = (1 − e^(−rate·dt))·(u − v)
+ *
+ * closes a fraction of the gap that is strictly below one for every `rate` and
+ * every `dt`, so the drag can never push a particle past the air it is
+ * relaxing toward. Dividing by `dt` turns it back into the acceleration the
+ * solver wants, and the exponential is evaluated **once per cloth per step** on
+ * the main thread rather than per particle.
+ *
+ * It is also the same step `GlobalFluidEffector` takes for the air itself —
+ * both are relaxations toward a velocity, and a cloth and the air around it
+ * reaching their common answer by the same arithmetic is a symmetry worth
+ * having.
+ *
+ * @param {number} drag `[0, 1]`
+ * @param {number} dt fixed step, seconds
+ * @returns {number} 1/s; `0` when there is no coupling at all
+ */
+export function cloth_drag_response(drag, dt) {
+    if (drag <= 0 || dt <= 0) {
+        return 0;
+    }
+
+    const rate = CLOTH_DRAG_RATE_MAX * (drag > 1 ? 1 : drag);
+
+    // `-expm1(-x)` is `1 - exp(-x)` without the cancellation at small `x`, and
+    // small `x` is every fabric below silk at a 60 Hz step.
+    return -Math.expm1(-rate * dt) / dt;
+}
+
+/**
+ * Fraction of a particle's velocity surviving one fixed step. §7 P5, and see
+ * {@link ClothDynamics#damping} for why this is a correctness mechanism rather
+ * than a taste control.
+ *
+ * @param {number} damping `[0, 1]`
+ * @param {number} dt fixed step, seconds
+ * @returns {number} `[0, 1]`
+ */
+export function cloth_velocity_retention(damping, dt) {
+    if (damping <= 0) {
+        return 1;
+    }
+
+    return Math.exp(-CLOTH_DAMPING_RATE * (damping > 1 ? 1 : damping) * dt);
+}