coily 0.14.0 → 0.15.0

package/dist/{system-BXxAHM2a.js → system-Br_cPnaN.js}

@@ -1,3 +1,4 @@
+import { a as RESOLVED, c as isNumber, i as State, l as isRecord, n as OverdampedSolver, o as invariant, r as UnderdampedSolver, s as isArray, t as CriticallyDampedSolver, u as isRecordOrArray } from "./solver-CVXOTDkZ.js";
 //#region src/flush-queue.ts
 /**
 * Defers callbacks while inside a batch or tick: `request` runs the
@@ -32,90 +33,6 @@ var FlushQueue = class {
 	}
 };
 //#endregion
-//#region src/motion-set.ts
-/**
-* The set of motions currently moving. Motions leave the set as they
-* rest and re-enter on any write that disturbs them; `onWake` tells the
-* ticker the set became non-empty so it can stop sleeping.
-*/
-var MotionSet = class {
-	reduced = false;
-	onWake = null;
-	flushes = new FlushQueue();
-	#motions = /* @__PURE__ */ new Set();
-	#debug;
-	#lastSize = 0;
-	#pass = 0;
-	constructor(debug = false) {
-		this.#debug = debug;
-	}
-	get size() {
-		return this.#motions.size;
-	}
-	add(motion) {
-		const wasEmpty = this.#motions.size === 0;
-		this.#motions.add(motion);
-		if (wasEmpty) this.onWake?.();
-	}
-	remove(motion) {
-		this.#motions.delete(motion);
-	}
-	finishAll() {
-		this.flushes.batch(() => {
-			for (const motion of this.#motions) {
-				if (!motion.respectsReducedMotion) continue;
-				motion.finish();
-				this.#motions.delete(motion);
-			}
-		});
-	}
-	tick(dt) {
-		this.#pass++;
-		this.flushes.enter();
-		try {
-			for (const motion of this.#motions) {
-				if (motion._pass === this.#pass) continue;
-				motion._pass = this.#pass;
-				motion.tick(dt);
-				if (motion.isResting) this.#motions.delete(motion);
-			}
-		} finally {
-			this.flushes.exit();
-		}
-		if (this.#debug && this.#motions.size !== this.#lastSize) {
-			this.#lastSize = this.#motions.size;
-			console.log(`coily: ${this.#lastSize} active motions`);
-		}
-	}
-};
-//#endregion
-//#region src/util.ts
-function invariant(condition, message) {
-	if (condition) return;
-	const resolved = typeof message === "function" ? message() : message;
-	throw new Error(resolved ?? "Invariant Failed");
-}
-/**
-* True for plain objects only. Class instances are excluded so shape
-* walks reject values like a `Spring` instead of descending into their
-* fields as if they were nested shapes.
-*/
-function isRecord(value) {
-	if (typeof value !== "object" || value === null) return false;
-	const proto = Object.getPrototypeOf(value);
-	return proto === Object.prototype || proto === null;
-}
-function isRecordOrArray(value) {
-	return isRecord(value) || Array.isArray(value);
-}
-function isArray(value) {
-	return Array.isArray(value);
-}
-function isNumber(value) {
-	return typeof value === "number";
-}
-const RESOLVED = Promise.resolve();
-//#endregion
 //#region src/config.ts
 /**
 * Immutable, resolved spring parameters. Whatever `defineSpring` input
@@ -138,6 +55,13 @@ var SpringDefinition = class SpringDefinition {
 	damping;
 	/** Decimal places of the resting threshold — see `restingMagnitude`. */
 	precision;
+	/**
+	* Velocity multiplier applied when the value crosses the target, as
+	* provided or resolved from its named form. 1 (`'passthrough'`) leaves
+	* the motion untouched, 0 (`'stop'`) ends it at the target, negative
+	* values rebound.
+	*/
+	arrival;
 	/** Oscillation rate with no damping: `sqrt(tension / mass)`, in radians per second. */
 	naturalFrequency;
 	/** The damping at which bounce disappears: `2 * mass * naturalFrequency`. */
@@ -159,7 +83,9 @@ var SpringDefinition = class SpringDefinition {
 		const duration = raw.duration !== void 0 ? raw.duration / 1e3 : void 0;
 		const displacement = raw.displacement ?? 1;
 		const precision = raw.precision ?? 2;
+		const arrival = raw.arrival;
 		for (const key of Object.keys(raw)) {
+			if (key === "arrival") continue;
 			const value = raw[key];
 			if (value !== void 0) invariant(Number.isFinite(value), () => `Invalid ${key}: expected a finite number`);
 		}
@@ -173,8 +99,12 @@ var SpringDefinition = class SpringDefinition {
 		if (duration !== void 0) invariant(duration > 0, "Duration must be greater than 0");
 		invariant(displacement !== 0, "Displacement must not be 0");
 		invariant(precision >= 0, "Precision must be greater than or equal to 0");
+		invariant(arrival === void 0 || arrival === "passthrough" || arrival === "stop" || typeof arrival === "number" && Number.isFinite(arrival) && arrival >= -1 && arrival <= 1, "Arrival must be 'passthrough', 'stop', or a number between -1 and 1");
 		this.precision = precision;
 		this.restingMagnitude = .5 / 10 ** precision;
+		if (arrival === void 0 || arrival === "passthrough") this.arrival = 1;
+		else if (arrival === "stop") this.arrival = 0;
+		else this.arrival = arrival === 0 ? 0 : arrival;
 		const hasM = mass !== void 0;
 		const hasK = tension !== void 0;
 		const hasC = damping !== void 0;
@@ -203,12 +133,8 @@ var SpringDefinition = class SpringDefinition {
 			const threshold = .005;
 			const x0 = Math.abs(displacement);
 			invariant(x0 > threshold, "displacement must be greater than the precision threshold");
-			let sigmaCoeff;
-			if (dampingRatio < 1) sigmaCoeff = dampingRatio;
-			else if (dampingRatio === 1) sigmaCoeff = 1;
-			else sigmaCoeff = dampingRatio - Math.sqrt(dampingRatio ** 2 - 1);
-			invariant(sigmaCoeff > 0, "dampingRatio must be > 0 for duration-based config");
-			const wn = 2 * Math.log(x0 / threshold) / (sigmaCoeff * duration);
+			invariant(dampingRatio > 0, "dampingRatio must be > 0 for duration-based config");
+			const wn = restUnits(dampingRatio, x0 / threshold) / duration;
 			if (!hasK && !hasC) {
 				this.mass = mass ?? 1;
 				this.tension = wn ** 2 * this.mass;
@@ -231,26 +157,99 @@ var SpringDefinition = class SpringDefinition {
 		Object.freeze(this);
 	}
 	/**
-	* Estimates how long a spring with this config takes to come to rest
-	* from `state`, in milliseconds.
+	* Computes when a spring with this config comes to rest from `state`,
+	* in ms.
 	*
-	* The estimate follows the motion's decay envelope with a 2x safety
-	* margin, so actual rest usually lands earlier. Returns 0 when `state`
-	* is already inside the resting threshold, and Infinity when the config
-	* never settles (a `dampingRatio` of 0).
+	* The time is solved from the motion's decay bound rather than
+	* estimated: the spring is resting at the first tick at or after it.
+	* An underdamped spring can also rest earlier — its rest amplitude
+	* pulses, and a frame that samples a dip inside the resting threshold
+	* rests there — so read the value as "no later than", tight in
+	* practice. See
+	* https://github.com/tkofh/coily/blob/main/PRECISION.md.
+	*
+	* Returns 0 when `state` is already inside the resting threshold.
+	* Returns Infinity when the motion never settles: a `dampingRatio` of
+	* 0 whose `arrival` neither stops nor slows it. When `arrival` is 0
+	* the result is capped at the first target crossing, where such a
+	* spring rests exactly; other multipliers fold their per-crossing
+	* velocity loss into the time.
 	*/
 	computeTimeRemaining(state) {
 		const { position, velocity } = state;
-		const a0 = Math.abs(position) + Math.abs(velocity) / this.naturalFrequency;
-		if (a0 <= this.restingMagnitude) return 0;
-		let sigma;
-		if (this.dampingRatio < 1) sigma = this.dampingRatio * this.naturalFrequency;
-		else if (this.dampingRatio === 1) sigma = this.naturalFrequency;
-		else sigma = (this.dampingRatio - Math.sqrt(this.dampingRatio * this.dampingRatio - 1)) * this.naturalFrequency;
-		if (sigma <= 0) return Infinity;
-		return 2 * Math.log(a0 / this.restingMagnitude) / sigma * 1e3;
+		if (Math.abs(position) + Math.abs(velocity) / this.naturalFrequency <= this.restingMagnitude) return 0;
+		const crossing = this.arrival === 0 ? firstCrossing(this, position, velocity) * 1e3 : Infinity;
+		return Math.min(restTime(this, position, velocity) * 1e3, crossing);
 	}
 };
+function solveEntry(f, threshold, peak) {
+	let low = 0;
+	let high = Math.max(peak, 1e-6);
+	while (f(high) > threshold) {
+		low = high;
+		high *= 2;
+	}
+	for (let i = 0; i < 60; i++) {
+		const mid = (low + high) / 2;
+		if (f(mid) > threshold) low = mid;
+		else high = mid;
+	}
+	return high;
+}
+function restTime(config, position, velocity) {
+	const { naturalFrequency, dampingRatio, restingMagnitude, arrival } = config;
+	if (dampingRatio < 1) {
+		const sigma = dampingRatio * naturalFrequency;
+		const wd = naturalFrequency * Math.sqrt(1 - dampingRatio ** 2);
+		const R = Math.hypot(position, (velocity + sigma * position) / wd);
+		const drop = Math.log(R * Math.sqrt(2 + 2 * dampingRatio) / restingMagnitude);
+		const plain = sigma > 0 ? drop / sigma : Infinity;
+		const strength = Math.abs(arrival);
+		if (strength === 0 || strength === 1) return plain;
+		const first = firstCrossing(config, position, velocity);
+		if (plain <= first) return plain;
+		const loss = -Math.log(strength) * wd / Math.PI;
+		return (drop + loss * first) / (sigma + loss);
+	}
+	if (dampingRatio === 1) {
+		const a0 = Math.abs(position) + Math.abs(velocity) / naturalFrequency;
+		const beta = 2 * Math.abs(velocity + naturalFrequency * position);
+		return solveEntry((t) => Math.exp(-naturalFrequency * t) * (a0 + beta * t), restingMagnitude, beta > 0 ? Math.max(0, 1 / naturalFrequency - a0 / beta) : 0);
+	}
+	const wd = naturalFrequency * Math.sqrt(dampingRatio ** 2 - 1);
+	const slow = dampingRatio * naturalFrequency - wd;
+	const fast = dampingRatio * naturalFrequency + wd;
+	const slowAmplitude = Math.abs(velocity + fast * position) / (2 * wd) * (1 + slow / naturalFrequency);
+	const fastAmplitude = Math.abs(velocity + slow * position) / (2 * wd) * (1 + fast / naturalFrequency);
+	return solveEntry((t) => slowAmplitude * Math.exp(-slow * t) + fastAmplitude * Math.exp(-fast * t), restingMagnitude, 0);
+}
+function restUnits(dampingRatio, ratio) {
+	if (dampingRatio < 1) return Math.log(ratio * Math.sqrt(2 / (1 - dampingRatio))) / dampingRatio;
+	if (dampingRatio === 1) return solveEntry((u) => Math.exp(-u) * (1 + 2 * u), 1 / ratio, .5);
+	const wd = Math.sqrt(dampingRatio ** 2 - 1);
+	const slow = dampingRatio - wd;
+	const fast = dampingRatio + wd;
+	const slowAmplitude = fast / (2 * wd) * (1 + slow);
+	const fastAmplitude = slow / (2 * wd) * (1 + fast);
+	return solveEntry((u) => slowAmplitude * Math.exp(-slow * u) + fastAmplitude * Math.exp(-fast * u), 1 / ratio, 0);
+}
+function firstCrossing(config, position, velocity) {
+	const { naturalFrequency, dampingRatio } = config;
+	if (dampingRatio < 1) {
+		const wd = naturalFrequency * Math.sqrt(1 - dampingRatio ** 2);
+		const c2 = (velocity + dampingRatio * naturalFrequency * position) / wd;
+		let theta = Math.atan2(-position, c2) % Math.PI;
+		if (theta <= 0) theta += Math.PI;
+		return theta / wd;
+	}
+	if (dampingRatio === 1) {
+		const t = -position / (velocity + naturalFrequency * position);
+		return t > 0 ? t : Infinity;
+	}
+	const wd = naturalFrequency * Math.sqrt(dampingRatio ** 2 - 1);
+	const theta = Math.atanh(-position * wd / (velocity + dampingRatio * naturalFrequency * position));
+	return theta > 0 ? theta / wd : Infinity;
+}
 function defineSpring(input) {
 	return new SpringDefinition(input);
 }
@@ -294,139 +293,8 @@ var Emitter = class {
 	}
 };
 //#endregion
-//#region src/state.ts
-/**
-* The mutable position/velocity pair a motion and its solvers share, in
-* displacement space: position 0 means at the target.
-*/
-var State = class {
-	#config;
-	#position;
-	#velocity;
-	constructor(config, position, velocity) {
-		this.#config = config;
-		this.#position = position;
-		this.#velocity = velocity;
-	}
-	configure(config) {
-		this.#config = config;
-	}
-	get position() {
-		return this.#position;
-	}
-	set position(value) {
-		this.#position = value;
-	}
-	get velocity() {
-		return this.#velocity;
-	}
-	set velocity(value) {
-		this.#velocity = value;
-	}
-	/**
-	* The rest test: displacement, plus the displacement the current
-	* velocity could still convert into (|x| + |v| / wn), is inside the
-	* config's resting threshold.
-	*/
-	get isResting() {
-		return Math.abs(this.#position) + Math.abs(this.#velocity) / this.#config.naturalFrequency <= this.#config.restingMagnitude;
-	}
-};
-//#endregion
-//#region src/solver.ts
-/** dampingRatio < 1: decaying oscillation, x(t) = exp(-sigma*t) * (c1*cos(wd*t) + c2*sin(wd*t)). */
-var UnderdampedSolver = class {
-	#state;
-	#dampedFrequency = 0;
-	#decayRate = 0;
-	#t = 0;
-	#c1 = 0;
-	#c2 = 0;
-	constructor(state) {
-		this.#state = state;
-	}
-	configure(config) {
-		if (config) {
-			this.#decayRate = config.dampingRatio * config.naturalFrequency;
-			this.#dampedFrequency = config.naturalFrequency * Math.sqrt(1 - config.dampingRatio ** 2);
-		}
-		this.#t = 0;
-		this.#c1 = this.#state.position;
-		this.#c2 = (this.#state.velocity + this.#decayRate * this.#state.position) / this.#dampedFrequency;
-	}
-	tick(dt) {
-		this.#t += dt;
-		const sin = Math.sin(this.#dampedFrequency * this.#t);
-		const cos = Math.cos(this.#dampedFrequency * this.#t);
-		const decay = Math.exp(-this.#decayRate * this.#t);
-		const decayVelocity = -this.#decayRate * decay;
-		const oscillation = this.#c1 * cos + this.#c2 * sin;
-		const oscillationVelocity = -this.#c1 * this.#dampedFrequency * sin + this.#c2 * this.#dampedFrequency * cos;
-		this.#state.position = decay * oscillation;
-		this.#state.velocity = decay * oscillationVelocity + decayVelocity * oscillation;
-	}
-};
-/** dampingRatio = 1: fastest non-oscillating decay, x(t) = (c1 + c2*t) * exp(-wn*t). */
-var CriticallyDampedSolver = class {
-	#state;
-	#naturalFrequency = 0;
-	#t = 0;
-	#c1 = 0;
-	#c2 = 0;
-	constructor(state) {
-		this.#state = state;
-	}
-	configure(config) {
-		if (config) this.#naturalFrequency = config.naturalFrequency;
-		this.#t = 0;
-		this.#c1 = this.#state.position;
-		this.#c2 = this.#state.velocity + this.#naturalFrequency * this.#state.position;
-	}
-	tick(dt) {
-		this.#t += dt;
-		const decay = Math.exp(-this.#naturalFrequency * this.#t);
-		const decayVelocity = -this.#naturalFrequency * decay;
-		const scale = this.#c1 + this.#c2 * this.#t;
-		const scaleVelocity = this.#c2;
-		this.#state.position = scale * decay;
-		this.#state.velocity = scaleVelocity * decay + decayVelocity * scale;
-	}
-};
-/** dampingRatio > 1: slow non-oscillating decay, x(t) = exp(-sigma*t) * (c1*sinh(wd*t) + c2*cosh(wd*t)) / wd. */
-var OverdampedSolver = class {
-	#state;
-	#dampedFrequency = 0;
-	#decayRate = 0;
-	#t = 0;
-	#c1 = 0;
-	#c2 = 0;
-	constructor(state) {
-		this.#state = state;
-	}
-	configure(config) {
-		if (config) {
-			this.#decayRate = config.dampingRatio * config.naturalFrequency;
-			this.#dampedFrequency = config.naturalFrequency * Math.sqrt(config.dampingRatio ** 2 - 1);
-		}
-		this.#t = 0;
-		this.#c1 = this.#state.velocity + this.#decayRate * this.#state.position;
-		this.#c2 = this.#state.position * this.#dampedFrequency;
-	}
-	tick(dt) {
-		this.#t += dt;
-		const decay = Math.exp(-this.#decayRate * this.#t);
-		const decayVelocity = -this.#decayRate * decay;
-		const clamped = Math.min(this.#dampedFrequency * this.#t, 300);
-		const sinh = Math.sinh(clamped);
-		const cosh = Math.cosh(clamped);
-		const scale = this.#c1 * sinh + this.#c2 * cosh;
-		const scaleVelocity = this.#c1 * this.#dampedFrequency * cosh + this.#c2 * this.#dampedFrequency * sinh;
-		this.#state.position = scale * decay / this.#dampedFrequency;
-		this.#state.velocity = (scale * decayVelocity + scaleVelocity * decay) / this.#dampedFrequency;
-	}
-};
-//#endregion
 //#region src/motion.ts
+let nextMotionId = 0;
 /**
 * One spring simulation in displacement space: position is measured from
 * the target (0 means settled), so retargeting is a rebase performed by
@@ -434,8 +302,41 @@ var OverdampedSolver = class {
 * damping regime and emits update/start/stop/dispose events.
 */
 var Motion = class {
+	/** Monotone creation id: breaks ties wherever motions need a deterministic order. */
+	_id = nextMotionId++;
 	/** Tick-pass marker written by `MotionSet` so a motion re-added mid-pass isn't ticked twice. */
 	_pass = 0;
+	/**
+	* Frame marker written by `MotionSet`: sub-steps share one frame, and
+	* the first advance in it queues the motion for the settle sweep.
+	*/
+	_frame = 0;
+	/**
+	* Dependency rank written by `FollowGraph`: motions the follow graph
+	* touches count up from 0, leaders before followers; -1 marks a motion
+	* outside the graph.
+	*/
+	_rank = -1;
+	/**
+	* The edge this motion follows through, or null. Written by
+	* `FollowGraph` on edge add/remove so the tick's hot loop reads a
+	* field instead of a map.
+	*/
+	_edge = null;
+	/**
+	* A first-order-hold ramp slope in value units per second, armed by a
+	* ramped `recouple` immediately before the `_advance` that consumes
+	* it (read-and-clear; no user code runs between the two). 0 means the
+	* target holds still across the step — every path but a ramped
+	* recouple.
+	*/
+	_ramp = 0;
+	/**
+	* The edges reading this motion, or null when none. Written by
+	* `FollowGraph` with the rank cache, so it can lag a mid-pass edge
+	* change until the next recompute; the tick tolerates stale entries.
+	*/
+	_followers = null;
 	respectsReducedMotion = true;
 	#config;
 	#state;
@@ -445,7 +346,6 @@ var Motion = class {
 	#currentSolver = null;
 	#needsUpdate = false;
 	#needsReset = false;
-	#timeRemaining = 0;
 	#running;
 	#emitter;
 	constructor(config, position, velocity) {
@@ -454,7 +354,6 @@ var Motion = class {
 		this.#emitter = new Emitter();
 		this.#running = !this.#state.isResting;
 		this.#updateSolver();
-		this.#timeRemaining = this.#config.computeTimeRemaining(this.#state);
 	}
 	get position() {
 		return this.#state.position;
@@ -473,7 +372,7 @@ var Motion = class {
 		this.#syncStart();
 	}
 	get timeRemaining() {
-		return this.#timeRemaining;
+		return this.#config.computeTimeRemaining(this.#state);
 	}
 	get isResting() {
 		return this.#state.isResting;
@@ -485,8 +384,50 @@ var Motion = class {
 		this.#syncStart();
 	}
 	tick(dt, emit = true) {
+		this._advance(dt);
+		if (emit) this._settleFrame();
+		else this.#reconcileRunning();
+	}
+	/**
+	* Advances the simulation and emits nothing. The tick pass advances
+	* every motion through this, then delivers the frame's events with
+	* `_settleFrame`; the synchronous `tick` wraps the two.
+	*
+	* A pending `_ramp` integrates the step against a target moving at
+	* that slope instead of holding still: one affine transform around
+	* the unchanged solver. With the target at `p(t) = p0 + g*t`, the
+	* displacement u = x - p(t) obeys the homogeneous equation shifted by
+	* the constant u_ss = -(2*zeta/wn)*g = -(damping/tension)*g, so the
+	* solver ticks w = u - u_ss exactly and the results shift back.
+	* Measuring u from the moving target makes the ramp endpoint and the
+	* new target coincide — the armer assigns the target, no rebase
+	* arithmetic exists. The ramp is an argument of the step, never
+	* persistent solver state: g = 0 takes the plain step below, so a
+	* motion that never ramps steps bit-exactly like an isolated spring.
+	*/
+	_advance(dt) {
 		invariant(this.#currentSolver, "Cannot tick a disposed motion");
-		const needsTimeRemaining = this.#needsUpdate || this.#needsReset;
+		const g = this._ramp;
+		if (g !== 0) {
+			this._ramp = 0;
+			const state = this.#state;
+			const shift = this.#config.damping / this.#config.tension * g;
+			state.position += shift;
+			state.velocity -= g;
+			if (this.#needsUpdate) {
+				this.#updateSolver();
+				this.#needsUpdate = false;
+			} else this.#currentSolver.configure();
+			this.#currentSolver.tick(dt);
+			state.position -= shift;
+			state.velocity += g;
+			this.#needsReset = true;
+			if (state.isResting) {
+				state.position = 0;
+				state.velocity = 0;
+			}
+			return;
+		}
 		if (this.#needsUpdate) {
 			this.#updateSolver();
 			this.#needsUpdate = false;
@@ -495,19 +436,26 @@ var Motion = class {
 			this.#currentSolver.configure();
 			this.#needsReset = false;
 		}
-		if (needsTimeRemaining) this.#timeRemaining = this.#config.computeTimeRemaining(this.#state);
 		this.#currentSolver.tick(dt);
-		this.#timeRemaining = Math.max(0, this.#timeRemaining - dt * 1e3);
 		if (this.#state.isResting) {
 			this.#state.position = 0;
 			this.#state.velocity = 0;
 			this.#needsReset = true;
 		}
-		if (emit) this.#emitter.emit("update");
+	}
+	/**
+	* Emits the frame's `update`, then reconciles `stop`/`start`. The tick
+	* pass calls this in dependency order after every motion has advanced,
+	* so update callbacks read frame-final values everywhere.
+	*/
+	_settleFrame() {
+		this.#emitter.emit("update");
+		this.#reconcileRunning();
+	}
+	#reconcileRunning() {
 		if (this.#state.isResting) {
 			if (this.#running) {
 				this.#running = false;
-				this.#timeRemaining = 0;
 				this.#emitter.emit("stop");
 			}
 		} else if (!this.#running) {
@@ -520,6 +468,23 @@ var Motion = class {
 		this.velocity = 0;
 		this.tick(0);
 	}
+	/**
+	* The sub-step controller's shock signal, read by a follower's `plan`
+	* with this motion as its leader: deviation from the quasi-steady
+	* tracking manifold x = -(damping/tension) * v, where damping/tension
+	* is 2*zeta/wn. Near zero while chasing any smoothly moving target at
+	* any speed; the full displacement after a target teleport;
+	* (damping/tension) * |v| after a fling.
+	*/
+	_manifoldDeviation() {
+		const config = this.#config;
+		return Math.abs(this.#state.position + config.damping / config.tension * this.#state.velocity);
+	}
+	/** Acceleration from current state, for `plan`'s kinematic bound on a shock frame. */
+	_acceleration() {
+		const config = this.#config;
+		return -(config.tension * this.#state.position + config.damping * this.#state.velocity) / config.mass;
+	}
 	onUpdate(callback) {
 		return this.#emitter.on("update", callback);
 	}
@@ -785,6 +750,19 @@ function isSpringSource(value) {
 	return typeof value === "object" && value !== null && SpringSourceSymbol in value;
 }
 const RECIPES = /* @__PURE__ */ new WeakMap();
+/** The flattened recipe behind `source`, when it is a derived source. */
+function recipeOf(source) {
+	return RECIPES.get(source);
+}
+/**
+* Registers a derived source's recipe. Every source built on other
+* sources must register at creation: `mapSpring` composition and
+* `resolveLeaderMotions` both reach a derivation's roots through the
+* registry rather than through the wrapper object.
+*/
+function registerRecipe(source, recipe) {
+	RECIPES.set(source, recipe);
+}
 function applyFns(fns, value) {
 	let result = value;
 	for (const fn of fns) result = fn(result);
@@ -879,6 +857,391 @@ function mapSpring(source, map) {
 	return mapped;
 }
 //#endregion
+//#region src/follow-graph.ts
+const MOTION_BACKING = /* @__PURE__ */ new WeakMap();
+/**
+* Records what advances `source`: its own `Motion` for a scalar spring,
+* or the aggregated sources whose own registrations lead to motions (a
+* composite registers its channel springs). Called from the
+* `SpringSourceSymbol` brand getters on every api read — lazily, so
+* springs never used as sources stay out of the weak registry, and
+* idempotently, so repeated reads just overwrite the entry.
+*/
+function registerBacking(source, backing) {
+	MOTION_BACKING.set(source, backing);
+}
+/**
+* Resolves the motions behind `source`, deduplicated: every spring
+* reached through any chain of derivations — `mapSpring` pipelines,
+* `velocityOf`/`accelerationOf` wrappers, composite channels. A foreign
+* source resolves to nothing: it imposes no tick-ordering constraint and
+* couples through its emitter alone.
+*/
+function resolveLeaderMotions(source) {
+	const leaders = /* @__PURE__ */ new Set();
+	collectInto(source, leaders);
+	return [...leaders];
+}
+function collectInto(source, leaders) {
+	const recipe = recipeOf(source);
+	if (recipe) {
+		for (const root of recipe.sources) collectInto(root, leaders);
+		return;
+	}
+	let backing = MOTION_BACKING.get(source);
+	if (backing === void 0 && isSpringSource(source)) {
+		const api = source[SpringSourceSymbol];
+		backing = MOTION_BACKING.get(source);
+		if (backing === void 0 && typeof api === "object" && api !== null && api !== source) {
+			collectInto(api, leaders);
+			return;
+		}
+	}
+	if (backing === void 0) return;
+	if (backing instanceof Motion) leaders.add(backing);
+	else for (const part of backing) collectInto(part, leaders);
+}
+const NO_LEADERS = [];
+/**
+* The follow graph as a walkable structure: one edge per following
+* motion, and a cached dependency rank over every motion the edges
+* touch. `MotionSet` owns one; springs register and unregister edges as
+* follows are wired and torn down. What the tick reads per motion —
+* `_edge`, `_followers`, `_rank` — lives on the motions themselves;
+* this class is their writer.
+*/
+var FollowGraph = class {
+	#edges = /* @__PURE__ */ new Map();
+	/** Motions holding a rank from the last recompute, so stale ranks reset to -1. */
+	#ranked = [];
+	/** Motions holding a follower list from the last recompute, so stale lists reset to null. */
+	#withFollowers = [];
+	/** Edge list mirroring the map, rebuilt with the ranks, so the per-frame plan pass iterates an array. */
+	#edgeList = [];
+	#dirty = false;
+	/** Whether no edges are registered, letting the tick skip ordering work entirely. */
+	get isEmpty() {
+		return this.#edges.size === 0;
+	}
+	/** Every registered edge, valid after `ensureOrder`; the plan pass walks this once per frame. */
+	get edges() {
+		return this.#edgeList;
+	}
+	/**
+	* Registers `edge`, replacing any edge with the same follower: a
+	* spring follows at most one source at a time.
+	*/
+	addEdge(edge) {
+		this.#edges.set(edge.follower, edge);
+		edge.follower._edge = edge;
+		this.#dirty = true;
+	}
+	/** Drops the edge whose follower is `motion`, if one is registered. */
+	removeEdge(follower) {
+		if (this.#edges.delete(follower)) {
+			follower._edge = null;
+			this.#dirty = true;
+		}
+	}
+	/**
+	* Recomputes ranks if an edge was added or removed since the last
+	* call; clean calls return immediately. Afterward, motions the graph
+	* touches hold ranks counting up from 0 with every leader ranked
+	* before its followers, members of a cycle rank in ascending creation
+	* id, and motions outside the graph hold -1. Ranks are canonical: a
+	* function of graph structure and creation order, never of wiring
+	* order.
+	*/
+	ensureOrder() {
+		if (!this.#dirty) return;
+		this.#dirty = false;
+		this.#recompute();
+	}
+	#recompute() {
+		for (const motion of this.#ranked) motion._rank = -1;
+		for (const motion of this.#withFollowers) motion._followers = null;
+		const withFollowers = [];
+		for (const edge of this.#edges.values()) for (const leader of edge.leaders) {
+			if (leader._followers === null) {
+				leader._followers = [];
+				withFollowers.push(leader);
+			}
+			leader._followers.push(edge);
+		}
+		this.#withFollowers = withFollowers;
+		const nodes = /* @__PURE__ */ new Set();
+		for (const [follower, edge] of this.#edges) {
+			nodes.add(follower);
+			for (const leader of edge.leaders) nodes.add(leader);
+		}
+		const roots = [...nodes].sort((a, b) => a._id - b._id);
+		const indexOf = /* @__PURE__ */ new Map();
+		const lowOf = /* @__PURE__ */ new Map();
+		const onStack = /* @__PURE__ */ new Set();
+		const stack = [];
+		const ranked = [];
+		const sccOf = /* @__PURE__ */ new Map();
+		let index = 0;
+		let rank = 0;
+		let scc = 0;
+		for (const root of roots) {
+			if (indexOf.has(root)) continue;
+			const frames = [{
+				node: root,
+				leaders: this.#leadersOf(root),
+				next: 0
+			}];
+			indexOf.set(root, index);
+			lowOf.set(root, index);
+			index++;
+			stack.push(root);
+			onStack.add(root);
+			while (frames.length > 0) {
+				const frame = frames.at(-1);
+				if (frame.next < frame.leaders.length) {
+					const leader = frame.leaders[frame.next++];
+					const seen = indexOf.get(leader);
+					if (seen === void 0) {
+						indexOf.set(leader, index);
+						lowOf.set(leader, index);
+						index++;
+						stack.push(leader);
+						onStack.add(leader);
+						frames.push({
+							node: leader,
+							leaders: this.#leadersOf(leader),
+							next: 0
+						});
+					} else if (onStack.has(leader)) lowOf.set(frame.node, Math.min(lowOf.get(frame.node), seen));
+				} else {
+					frames.pop();
+					const low = lowOf.get(frame.node);
+					const parent = frames.at(-1);
+					if (parent !== void 0) lowOf.set(parent.node, Math.min(lowOf.get(parent.node), low));
+					if (low === indexOf.get(frame.node)) {
+						const members = [];
+						let member;
+						do {
+							member = stack.pop();
+							onStack.delete(member);
+							members.push(member);
+						} while (member !== frame.node);
+						members.sort((a, b) => a._id - b._id);
+						for (const motion of members) {
+							motion._rank = rank++;
+							sccOf.set(motion, scc);
+							ranked.push(motion);
+						}
+						scc++;
+					}
+				}
+			}
+		}
+		this.#ranked = ranked;
+		const edgeList = [...this.#edges.values()];
+		for (const edge of edgeList) {
+			const home = sccOf.get(edge.follower);
+			edge._cyclic = edge.leaders.some((leader) => sccOf.get(leader) === home);
+		}
+		this.#edgeList = edgeList;
+	}
+	#leadersOf(motion) {
+		return this.#edges.get(motion)?.leaders ?? NO_LEADERS;
+	}
+};
+//#endregion
+//#region src/motion-set.ts
+function compareMotions(a, b) {
+	return a._rank - b._rank || a._id - b._id;
+}
+const MAX_SUBSTEPS = 8;
+/**
+* A binary min-heap over (rank, creation id): the ordered pass worklist.
+* Duplicate pushes are expected — the tick's pass marker deduplicates at
+* pop.
+*/
+var MotionHeap = class {
+	#items = [];
+	clear() {
+		this.#items.length = 0;
+	}
+	push(motion) {
+		const items = this.#items;
+		let hole = items.length;
+		items.push(motion);
+		while (hole > 0) {
+			const parent = hole - 1 >> 1;
+			if (compareMotions(items[parent], motion) <= 0) break;
+			items[hole] = items[parent];
+			hole = parent;
+		}
+		items[hole] = motion;
+	}
+	pop() {
+		const items = this.#items;
+		if (items.length === 0) return void 0;
+		const top = items[0];
+		const last = items.pop();
+		if (items.length > 0) {
+			let hole = 0;
+			for (;;) {
+				const left = 2 * hole + 1;
+				if (left >= items.length) break;
+				const right = left + 1;
+				const child = right < items.length && compareMotions(items[right], items[left]) < 0 ? right : left;
+				if (compareMotions(last, items[child]) <= 0) break;
+				items[hole] = items[child];
+				hole = child;
+			}
+			items[hole] = last;
+		}
+		return top;
+	}
+};
+/**
+* The set of motions currently moving. Motions leave the set as they
+* rest and re-enter on any write that disturbs them; `onWake` tells the
+* ticker the set became non-empty so it can stop sleeping.
+*/
+var MotionSet = class {
+	reduced = false;
+	onWake = null;
+	/**
+	* The coupling error budget, in value units: the local per-frame error
+	* the sub-step controller targets on each follow edge, floored by the
+	* follower's resting magnitude. `SpringSystem` exposes it as the
+	* `couplingTolerance` option and property; validation lives there.
+	*/
+	couplingTolerance = .1;
+	flushes = new FlushQueue();
+	/** Follow edges registered by following springs, with the dependency rank over their motions. */
+	graph = new FollowGraph();
+	#motions = /* @__PURE__ */ new Set();
+	#heap = new MotionHeap();
+	#advanced = [];
+	/** The live pass worklist while an advance phase runs, so mid-phase wakes join it. */
+	#activeHeap = null;
+	/** Whether any tick is on the stack, settle sweep included — a reentrant advance must not share the pass structures. */
+	#inTick = false;
+	#debug;
+	#lastSize = 0;
+	#pass = 0;
+	/** Ordered-frame counter: sub-steps share one id, deduplicating the settle list. */
+	#frame = 0;
+	constructor(debug = false) {
+		this.#debug = debug;
+	}
+	get size() {
+		return this.#motions.size;
+	}
+	add(motion) {
+		const wasEmpty = this.#motions.size === 0;
+		this.#motions.add(motion);
+		this.#activeHeap?.push(motion);
+		if (wasEmpty) this.onWake?.();
+	}
+	remove(motion) {
+		this.#motions.delete(motion);
+	}
+	finishAll() {
+		this.flushes.batch(() => {
+			for (const motion of this.#motions) {
+				if (!motion.respectsReducedMotion) continue;
+				motion.finish();
+				this.#motions.delete(motion);
+			}
+		});
+	}
+	tick(dt) {
+		const reentrant = this.#inTick;
+		this.#inTick = true;
+		this.flushes.enter();
+		try {
+			this.graph.ensureOrder();
+			if (this.graph.isEmpty) this.#tickUnordered(dt, reentrant);
+			else this.#tickOrdered(dt, reentrant);
+		} finally {
+			this.#inTick = reentrant;
+			this.flushes.exit();
+		}
+		if (this.#debug && this.#motions.size !== this.#lastSize) {
+			this.#lastSize = this.#motions.size;
+			console.log(`coily: ${this.#lastSize} active motions`);
+		}
+	}
+	/** The no-edge fast path: nothing constrains order, so insertion order serves for free. */
+	#tickUnordered(dt, reentrant) {
+		this.#pass++;
+		const advanced = reentrant ? [] : this.#advanced;
+		advanced.length = 0;
+		for (const motion of this.#motions) {
+			if (motion._pass === this.#pass) continue;
+			motion._pass = this.#pass;
+			motion._advance(dt);
+			advanced.push(motion);
+			if (motion.isResting) this.#motions.delete(motion);
+		}
+		this.#settle(advanced);
+	}
+	#tickOrdered(dt, reentrant) {
+		const heap = reentrant ? new MotionHeap() : this.#heap;
+		const advanced = reentrant ? [] : this.#advanced;
+		const previous = this.#activeHeap;
+		this.#activeHeap = heap;
+		advanced.length = 0;
+		const frame = ++this.#frame;
+		let demand = 1;
+		if (!this.reduced) {
+			for (const edge of this.graph.edges) if (this.#shouldPlan(edge)) {
+				const k = edge.plan(dt);
+				if (k > demand) demand = k;
+			}
+		}
+		const K = Math.min(demand, MAX_SUBSTEPS);
+		const h = dt / K;
+		try {
+			for (let step = 0; step < K; step++) this.#advancePass(dt, h, step === 0, heap, advanced, frame);
+		} finally {
+			this.#activeHeap = previous;
+		}
+		this.#settle(advanced);
+	}
+	#advancePass(dt, h, first, heap, advanced, frame) {
+		this.#pass++;
+		heap.clear();
+		for (const motion of this.#motions) {
+			if (!first && motion._rank === -1) continue;
+			heap.push(motion);
+		}
+		for (let motion = heap.pop(); motion !== void 0; motion = heap.pop()) {
+			if (motion._pass === this.#pass) continue;
+			const edge = motion._edge;
+			if (edge !== null && this.#shouldRecouple(edge)) edge.recouple(h);
+			if (!this.#motions.has(motion)) continue;
+			motion._pass = this.#pass;
+			motion._advance(motion._rank === -1 ? dt : h);
+			if (motion._frame !== frame) {
+				motion._frame = frame;
+				advanced.push(motion);
+			}
+			if (motion.isResting) this.#motions.delete(motion);
+			const followers = motion._followers;
+			if (followers !== null) for (const out of followers) heap.push(out.follower);
+		}
+	}
+	#settle(advanced) {
+		for (const motion of advanced) motion._settleFrame();
+	}
+	#shouldRecouple(edge) {
+		for (const leader of edge.leaders) if (leader._pass === this.#pass || this.#motions.has(leader)) return true;
+		return false;
+	}
+	#shouldPlan(edge) {
+		for (const leader of edge.leaders) if (this.#motions.has(leader)) return true;
+		return false;
+	}
+};
+//#endregion
 //#region src/spring.ts
 /**
 * One animated number, driven toward its target with damped spring
@@ -895,6 +1258,7 @@ function mapSpring(source, map) {
 var Spring = class {
 	/** Brands the spring as a `KinematicSource` whose api is the spring itself. */
 	get [SpringSourceSymbol]() {
+		registerBacking(this, this.#motion);
 		return this;
 	}
 	#target;
@@ -1040,6 +1404,10 @@ var Spring = class {
 	get precision() {
 		return this.#config.precision;
 	}
+	/** The config's arrival multiplier. */
+	get arrival() {
+		return this.#config.arrival;
+	}
 	set config(value) {
 		const next = value ?? SpringDefinition.default;
 		if (this.#config === next) return;
@@ -1048,9 +1416,12 @@ var Spring = class {
 		if (!this.#motion.isResting) this.#motions.add(this.#motion);
 	}
 	/**
-	* Estimated milliseconds until the spring rests: 0 while resting,
-	* Infinity when undamped. The estimate carries a safety margin, so
-	* actual rest usually lands earlier.
+	* Milliseconds until the spring rests: 0 while resting, Infinity when
+	* the motion never settles. The time is solved from the motion, not
+	* estimated — the spring is resting at the first tick at or after it,
+	* and a bouncy spring can rest up to one oscillation earlier when a
+	* frame samples a low pulse. When the config's `arrival` is 0, it is
+	* capped at the exact ms of the first target crossing.
 	*/
 	get timeRemaining() {
 		return this.#motion.timeRemaining;
@@ -1174,9 +1545,59 @@ var Spring = class {
 		const unsubDispose = api.onDispose(() => {
 			this.#unfollow();
 		});
+		const leaders = resolveLeaderMotions(source);
+		if (leaders.length > 0) {
+			const edge = {
+				follower: this.#motion,
+				leaders,
+				_cyclic: false,
+				_prevValue: 0,
+				_d1: 0,
+				_d2: 0,
+				recouple: (h) => {
+					if (edge._cyclic || h === 0 || this.#config.arrival !== 1 || this.#motions.reduced && this.#purpose === "motion") {
+						this.#setTarget(api.value);
+						return;
+					}
+					const value = api.value;
+					invariant(Number.isFinite(value), "Spring target must be a finite number");
+					if (value === this.#target) return;
+					this.#motions.add(this.#motion);
+					this.#motion._ramp = (value - this.#target) / h;
+					this.#target = value;
+				},
+				plan: (dt) => {
+					const target = this.#target;
+					const d = target - edge._prevValue;
+					edge._d2 = edge._d1;
+					edge._d1 = d;
+					edge._prevValue = target;
+					let dHat = Math.abs(d);
+					let error = Math.abs(d - edge._d2) / 8;
+					for (const leader of leaders) if (leader._manifoldDeviation() > 4 * Math.abs(d)) {
+						const accel = Math.abs(leader._acceleration());
+						const speed = Math.abs(leader.velocity);
+						dHat = Math.max(dHat, speed * dt + .5 * accel * dt * dt);
+						error = Math.max(error, accel * dt * dt / 8);
+					}
+					const tol = Math.max(this.#config.restingMagnitude, this.#motions.couplingTolerance);
+					return edge._cyclic || this.#config.arrival !== 1 ? Math.ceil(dHat / (2 * tol)) : Math.ceil(Math.sqrt(error / tol));
+				}
+			};
+			this.#motions.graph.addEdge(edge);
+			this.#unsubLeader = () => {
+				unsubUpdate();
+				unsubDispose();
+				this.#motions.graph.removeEdge(this.#motion);
+			};
+			this.#setTarget(api.value);
+			edge._prevValue = this.#target;
+			return;
+		}
 		this.#unsubLeader = () => {
 			unsubUpdate();
 			unsubDispose();
+			this.#motions.graph.removeEdge(this.#motion);
 		};
 		this.#setTarget(api.value);
 	}
@@ -1268,6 +1689,7 @@ const followChannel = (mine, theirs) => {
 var CompositeSpring = class CompositeSpring {
 	/** Brands the composite as a `KinematicSource` whose api is the composite itself. */
 	get [SpringSourceSymbol]() {
+		registerBacking(this, this.#tree.leaves);
 		return this;
 	}
 	#motions;
@@ -1676,6 +2098,7 @@ var SpringSystemImpl = class {
 	constructor(options) {
 		this.#motion = new MotionSet(options?.debug);
 		this.#ticker = new Ticker(this.#motion, options);
+		if (options?.couplingTolerance !== void 0) this.couplingTolerance = options.couplingTolerance;
 		const mode = options?.reducedMotion ?? "user";
 		if (mode === "always") this.#motion.reduced = true;
 		else if (mode === "user" && typeof window !== "undefined" && typeof window.matchMedia === "function") {
@@ -1693,6 +2116,13 @@ var SpringSystemImpl = class {
 	get reducedMotion() {
 		return this.#motion.reduced;
 	}
+	get couplingTolerance() {
+		return this.#motion.couplingTolerance;
+	}
+	set couplingTolerance(value) {
+		invariant(Number.isFinite(value) && value >= 0, "couplingTolerance must be a finite, non-negative number");
+		this.#motion.couplingTolerance = value;
+	}
 	createSpring(value, config, options) {
 		if (typeof value === "number") return new Spring(this.#motion, value, config, options?.purpose);
 		if (isSpringSource(value)) {
@@ -1755,4 +2185,4 @@ function createSpringSystem(options) {
 	return new SpringSystemImpl(options);
 }
 //#endregion
-export { SpringDefinition as a, mapSpring as i, SpringSourceSymbol as n, defineSpring as o, isSpringSource as r, invariant as s, createSpringSystem as t };
+export { registerRecipe as a, mapSpring as i, SpringSourceSymbol as n, SpringDefinition as o, isSpringSource as r, defineSpring as s, createSpringSystem as t };