coily 0.13.1 → 0.14.0

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

@@ -1,4 +1,10 @@
 //#region src/flush-queue.ts
+/**
+* Defers callbacks while inside a batch or tick: `request` runs the
+* callback immediately at depth 0 and queues it — deduplicated — until
+* the outermost exit otherwise. Composite springs use it to coalesce
+* per-channel events into composite ones.
+*/
 var FlushQueue = class {
 	#callbacks = /* @__PURE__ */ new Set();
 	#depth = 0;
@@ -27,6 +33,11 @@ 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;
@@ -52,6 +63,7 @@ var MotionSet = class {
 	finishAll() {
 		this.flushes.batch(() => {
 			for (const motion of this.#motions) {
+				if (!motion.respectsReducedMotion) continue;
 				motion.finish();
 				this.#motions.delete(motion);
 			}
@@ -83,6 +95,11 @@ function invariant(condition, message) {
 	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);
@@ -97,23 +114,39 @@ function isArray(value) {
 function isNumber(value) {
 	return typeof value === "number";
 }
+const RESOLVED = Promise.resolve();
 //#endregion
 //#region src/config.ts
 /**
-* Immutable spring configuration. Instances are frozen — to change a spring's
-* behavior, assign a new config via `spring.config`.
+* Immutable, resolved spring parameters. Whatever `defineSpring` input
+* shape produced it, a config carries concrete `mass`, `tension`,
+* `damping`, and `precision`, plus the quantities derived from them.
+* Instances are frozen and safe to share between springs; to change a
+* spring's behavior, assign a new config via `spring.config`.
 */
-var SpringConfig = class SpringConfig {
-	static default = new SpringConfig({
+var SpringDefinition = class SpringDefinition {
+	/** The config for springs created without one: critically damped, settling in about 500ms. */
+	static default = new SpringDefinition({
 		dampingRatio: 1,
 		duration: 500
 	});
+	/** Mass of the moving value, as provided or derived. */
 	mass;
+	/** Spring stiffness, as provided or derived. */
 	tension;
+	/** Friction strength, as provided or derived. */
 	damping;
+	/** Decimal places of the resting threshold — see `restingMagnitude`. */
 	precision;
+	/** Oscillation rate with no damping: `sqrt(tension / mass)`, in radians per second. */
 	naturalFrequency;
+	/** The damping at which bounce disappears: `2 * mass * naturalFrequency`. */
 	criticalDamping;
+	/**
+	* `damping / criticalDamping`. Below 1 the spring overshoots and
+	* bounces, at 1 it settles fastest without overshooting, above 1 it
+	* settles slower.
+	*/
 	dampingRatio;
 	/** Resting threshold in value units: half a unit in the last `precision` place. */
 	restingMagnitude;
@@ -126,6 +159,10 @@ var SpringConfig = class SpringConfig {
 		const duration = raw.duration !== void 0 ? raw.duration / 1e3 : void 0;
 		const displacement = raw.displacement ?? 1;
 		const precision = raw.precision ?? 2;
+		for (const key of Object.keys(raw)) {
+			const value = raw[key];
+			if (value !== void 0) invariant(Number.isFinite(value), () => `Invalid ${key}: expected a finite number`);
+		}
 		if (mass !== void 0) invariant(mass > 0, "Mass must be greater than 0");
 		if (tension !== void 0) invariant(tension > 0, "Tension must be greater than 0");
 		if (damping !== void 0) invariant(damping >= 0, "Damping must be greater than or equal to 0");
@@ -194,23 +231,13 @@ var SpringConfig = class SpringConfig {
 		Object.freeze(this);
 	}
 	/**
-	* Analytically estimates the time remaining for a spring to come to rest,
-	* given the current displacement and velocity.
-	*
-	* Uses the exponential decay envelope common to all three damping regimes.
-	* The decay rate depends on the regime:
-	* - Underdamped (ζ < 1): σ = ζωₙ
-	* - Critically damped (ζ = 1): σ = ωₙ
-	* - Overdamped (ζ > 1): σ = (ζ - √(ζ²-1))ωₙ  (the slower eigenvalue)
+	* Estimates how long a spring with this config takes to come to rest
+	* from `state`, in milliseconds.
 	*
-	* The effective initial amplitude accounts for both displacement and velocity,
-	* since kinetic energy can convert to additional displacement:
-	*   A₀ = |x₀| + |v₀| / ωₙ
-	*
-	* Settling time: t = ln(A₀ / threshold) / σ, with a 2× safety factor
-	* to account for polynomial terms in the critically damped solution.
-	*
-	* Returns the estimated time in milliseconds.
+	* 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).
 	*/
 	computeTimeRemaining(state) {
 		const { position, velocity } = state;
@@ -225,10 +252,11 @@ var SpringConfig = class SpringConfig {
 	}
 };
 function defineSpring(input) {
-	return new SpringConfig(input);
+	return new SpringDefinition(input);
 }
 //#endregion
 //#region src/emitter.ts
+/** Minimal fixed-event emitter behind motions and composite springs. */
 var Emitter = class {
 	#update = [];
 	#start = [];
@@ -267,6 +295,10 @@ 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;
@@ -291,12 +323,18 @@ var State = class {
 	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;
@@ -328,6 +366,7 @@ var UnderdampedSolver = class {
 		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;
@@ -353,6 +392,7 @@ var CriticallyDampedSolver = class {
 		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;
@@ -387,8 +427,16 @@ var OverdampedSolver = class {
 };
 //#endregion
 //#region src/motion.ts
+/**
+* One spring simulation in displacement space: position is measured from
+* the target (0 means settled), so retargeting is a rebase performed by
+* the owning `Spring`. Picks the closed-form solver for the config's
+* damping regime and emits update/start/stop/dispose events.
+*/
 var Motion = class {
+	/** Tick-pass marker written by `MotionSet` so a motion re-added mid-pass isn't ticked twice. */
 	_pass = 0;
+	respectsReducedMotion = true;
 	#config;
 	#state;
 	#underdampedSolver = null;
@@ -513,223 +561,7 @@ var Motion = class {
 	}
 };
 //#endregion
-//#region src/spring.ts
-function normalizeTarget(target) {
-	if (target instanceof Spring) return {
-		spring: target,
-		offset: 0
-	};
-	if (typeof target === "object" && target !== null && "spring" in target && target.spring instanceof Spring) return {
-		spring: target.spring,
-		offset: target.offset ?? 0
-	};
-	return null;
-}
-const RESOLVED$1 = Promise.resolve();
-var Spring = class {
-	#target;
-	#override;
-	#resolved;
-	#motion;
-	#motions;
-	#followers = /* @__PURE__ */ new Set();
-	#leader = null;
-	#offset = 0;
-	#unsubLeader = null;
-	#settled = null;
-	#resolveSettled = null;
-	#disposed = false;
-	constructor(motions, position, config) {
-		this.#motions = motions;
-		let numericTarget;
-		let value;
-		let normalized = null;
-		if (typeof position === "number") {
-			numericTarget = position;
-			value = position;
-		} else {
-			normalized = normalizeTarget(position.target);
-			if (normalized) {
-				numericTarget = normalized.spring.value + normalized.offset;
-				value = position.value ?? numericTarget;
-			} else {
-				numericTarget = position.target ?? position.value ?? 0;
-				value = position.value ?? numericTarget;
-			}
-		}
-		if (motions.reduced) value = numericTarget;
-		this.#override = config ?? null;
-		this.#resolved = config ?? (normalized ? normalized.spring.#resolved : SpringConfig.default);
-		this.#target = numericTarget;
-		this.#motion = new Motion(this.#resolved, value - numericTarget, 0);
-		if (!this.#motion.isResting) this.#motions.add(this.#motion);
-		if (normalized) {
-			this.#leader = normalized.spring;
-			this.#offset = normalized.offset;
-			normalized.spring.#followers.add(this);
-			this.#unsubLeader = normalized.spring.onUpdate(() => {
-				this.#setTarget(this.#leader.value + this.#offset);
-			});
-		}
-	}
-	get target() {
-		return this.#target;
-	}
-	set target(value) {
-		if (typeof value === "number") {
-			this.#unfollow();
-			this.#setTarget(value);
-		} else {
-			const normalized = normalizeTarget(value);
-			this.#follow(normalized.spring, normalized.offset);
-		}
-	}
-	get value() {
-		return this.#target + this.#motion.position;
-	}
-	set value(value) {
-		if (this.#motions.reduced) {
-			if (value !== this.value) this.jumpTo(value);
-			return;
-		}
-		const position = value - this.#target;
-		if (position !== this.#motion.position) {
-			this.#motions.add(this.#motion);
-			this.#motion.position = position;
-			this.#motion.tick(0);
-		}
-	}
-	get velocity() {
-		return this.#motion.velocity;
-	}
-	set velocity(value) {
-		if (this.#motions.reduced) return;
-		this.#motions.add(this.#motion);
-		this.#motion.velocity = value;
-	}
-	get config() {
-		return this.#resolved;
-	}
-	get mass() {
-		return this.#resolved.mass;
-	}
-	get tension() {
-		return this.#resolved.tension;
-	}
-	get damping() {
-		return this.#resolved.damping;
-	}
-	get dampingRatio() {
-		return this.#resolved.dampingRatio;
-	}
-	get precision() {
-		return this.#resolved.precision;
-	}
-	set config(value) {
-		this.#override = value;
-		this.#applyConfig(value ?? (this.#leader ? this.#leader.#resolved : SpringConfig.default));
-	}
-	get timeRemaining() {
-		return this.#motion.timeRemaining;
-	}
-	get isResting() {
-		return this.#motion.isResting;
-	}
-	get settled() {
-		if (this.#disposed || this.#motion.isResting) return RESOLVED$1;
-		this.#settled ??= new Promise((resolve) => {
-			this.#resolveSettled = resolve;
-			const unsubscribe = this.onStop(() => {
-				unsubscribe();
-				this.#settled = null;
-				this.#resolveSettled = null;
-				resolve();
-			});
-		});
-		return this.#settled;
-	}
-	jumpTo(value) {
-		this.#target = value;
-		this.#motion.finish();
-	}
-	dispose() {
-		if (this.#disposed) return;
-		this.#disposed = true;
-		if (this.#resolveSettled) {
-			this.#resolveSettled();
-			this.#settled = null;
-			this.#resolveSettled = null;
-		}
-		if (this.#unsubLeader) {
-			this.#unsubLeader();
-			this.#unsubLeader = null;
-		}
-		if (this.#leader) {
-			this.#leader.#followers.delete(this);
-			this.#leader = null;
-		}
-		for (const follower of this.#followers) follower.#unfollow();
-		this.#motions.remove(this.#motion);
-		this.#motion.dispose();
-	}
-	onUpdate(callback) {
-		return this.#motion.onUpdate(callback);
-	}
-	onStart(callback) {
-		return this.#motion.onStart(callback);
-	}
-	onStop(callback) {
-		return this.#motion.onStop(callback);
-	}
-	onDispose(callback) {
-		return this.#motion.onDispose(callback);
-	}
-	#setTarget(value) {
-		if (value !== this.#target) {
-			if (this.#motions.reduced) {
-				this.jumpTo(value);
-				return;
-			}
-			this.#motions.add(this.#motion);
-			const current = this.value;
-			this.#target = value;
-			this.#motion.position = current - this.#target;
-			this.#motion.tick(0, false);
-		}
-	}
-	#follow(leader, offset) {
-		if (this.#unsubLeader) {
-			this.#unsubLeader();
-			this.#leader.#followers.delete(this);
-		}
-		this.#leader = leader;
-		this.#offset = offset;
-		leader.#followers.add(this);
-		if (this.#override === null) this.#applyConfig(leader.#resolved);
-		this.#unsubLeader = leader.onUpdate(() => {
-			this.#setTarget(this.#leader.value + this.#offset);
-		});
-		this.#setTarget(leader.value + offset);
-	}
-	#unfollow() {
-		if (!this.#leader) return;
-		this.#unsubLeader();
-		this.#unsubLeader = null;
-		this.#leader.#followers.delete(this);
-		this.#leader = null;
-		this.#offset = 0;
-		if (this.#override === null) this.#override = this.#resolved;
-	}
-	#applyConfig(next) {
-		if (this.#resolved === next) return;
-		this.#resolved = next;
-		this.#motion.configure(next);
-		if (!this.#motion.isResting) this.#motions.add(this.#motion);
-		for (const follower of this.#followers) if (follower.#override === null) follower.#applyConfig(next);
-	}
-};
-//#endregion
-//#region src/channel-tree-node.ts
+//#region src/shape-tree.ts
 function joinPath(path, key) {
 	return path ? `${path}.${key}` : String(key);
 }
@@ -738,48 +570,32 @@ function describePath(path) {
 }
 /** The sentinel a resolver returns to descend into a node instead of covering it. */
 const BRANCH = Symbol("branch");
+/** The standard scatter leaf guard: partial numeric shapes take only finite numbers at channels. */
+function acceptNumber(input, path) {
+	invariant(isNumber(input) && Number.isFinite(input), () => `Expected a finite number for channel '${path}'`);
+	return input;
+}
 /**
-* One node of a shape's tree: a `LeafNode` wraps a single channel's leaf
-* object, `ListNode` and `RecordNode` carry the nesting. Every traversal is
-* an ordinary method each kind implements for itself, so call sites dispatch
-* without inspecting nodes; errors keep their dot paths because each node
-* stores the `path` it was built at.
+* The canonical numeric `LeafParser`: finite-number leaves built through
+* `factory`, named "channels" in structural errors. The default for value
+* shapes, whose leaves are all numbers.
 */
-var ChannelTreeNode = class ChannelTreeNode {
-	/** This node's dot path from the root (`position.x`), fixed at construction. */
-	path;
-	constructor(path) {
-		this.path = path;
-	}
-	/** Parses a numeric shape into a node tree, appending each created leaf to `leaves`. */
-	static build(shape, path, factory, leaves) {
-		if (isArray(shape)) {
-			invariant(shape.length > 0, () => emptyShape(path));
-			return new ListNode(shape.map((child, i) => ChannelTreeNode.#child(child, joinPath(path, i), factory, leaves)), path);
-		}
-		const keys = Object.keys(shape);
-		invariant(keys.length > 0, () => emptyShape(path));
-		const children = /* @__PURE__ */ new Map();
-		for (const key of keys) children.set(key, ChannelTreeNode.#child(shape[key], joinPath(path, key), factory, leaves));
-		return new RecordNode(children, path);
-	}
-	static #child(value, path, factory, leaves) {
-		if (isNumber(value)) {
-			const leaf = factory(value, path);
-			leaves.push(leaf);
-			return new LeafNode(leaf, path);
-		}
-		invariant(isRecordOrArray(value), `Invalid value at '${path}': expected a number or a nested shape of numbers`);
-		return ChannelTreeNode.build(value, path, factory, leaves);
-	}
-};
-function emptyShape(path) {
-	return `Invalid value at ${describePath(path)}: a shape must contain at least one channel`;
+function channelParser(factory) {
+	return {
+		match(value, path) {
+			if (!isNumber(value)) return void 0;
+			invariant(Number.isFinite(value), () => `Invalid value at '${path}': channel values must be finite`);
+			return factory(value, path);
+		},
+		mismatch: (path) => `Invalid value at '${path}': expected a number or a nested shape of numbers`,
+		empty: (path) => `Invalid value at ${describePath(path)}: a shape must contain at least one channel`
+	};
 }
-var LeafNode = class LeafNode extends ChannelTreeNode {
+var LeafNode = class LeafNode {
+	path;
 	leaf;
 	constructor(leaf, path) {
-		super(path);
+		this.path = path;
 		this.leaf = leaf;
 	}
 	mirror(read, slots, carrier, key) {
@@ -790,18 +606,12 @@ var LeafNode = class LeafNode extends ChannelTreeNode {
 			carrier
 		});
 	}
-	scatter(input, apply) {
-		invariant(isNumber(input), `Expected a number for channel '${this.path}'`);
-		apply(this.leaf, input);
+	scatter(input, accept, apply) {
+		apply(this.leaf, accept(input, this.path));
 	}
-	zip(theirs, values, label, fn) {
+	zip(theirs, fn) {
 		invariant(theirs instanceof LeafNode, () => `Shape mismatch at ${describePath(this.path)}`);
-		let value;
-		if (values !== void 0) {
-			invariant(isNumber(values), `Expected a number at '${this.path}' in ${label}`);
-			value = values;
-		}
-		fn(this.leaf, theirs.leaf, value, this.path);
+		fn(this.leaf, theirs.leaf);
 	}
 	broadcast(input, resolve, apply, _label) {
 		const resolved = resolve(input, this.path);
@@ -812,10 +622,11 @@ var LeafNode = class LeafNode extends ChannelTreeNode {
 		apply(this.leaf, value);
 	}
 };
-var ListNode = class ListNode extends ChannelTreeNode {
+var ListNode = class ListNode {
+	path;
 	children;
 	constructor(children, path) {
-		super(path);
+		this.path = path;
 		this.children = children;
 	}
 	mirror(read, slots, carrier, key) {
@@ -824,23 +635,17 @@ var ListNode = class ListNode extends ChannelTreeNode {
 		const slotcarrier = mine;
 		for (let i = 0; i < this.children.length; i++) this.children[i].mirror(read, slots, slotcarrier, i);
 	}
-	scatter(input, apply) {
+	scatter(input, accept, apply) {
 		invariant(isArray(input), () => `Expected an array at ${describePath(this.path)}`);
 		invariant(input.length <= this.children.length, `Unknown channel '${joinPath(this.path, this.children.length)}'`);
 		for (let i = 0; i < input.length; i++) {
 			if (input[i] === void 0) continue;
-			this.children[i].scatter(input[i], apply);
+			this.children[i].scatter(input[i], accept, apply);
 		}
 	}
-	zip(theirs, values, label, fn) {
+	zip(theirs, fn) {
 		invariant(theirs instanceof ListNode && theirs.children.length === this.children.length, () => `Shape mismatch at ${describePath(this.path)}`);
-		let list;
-		if (values !== void 0) {
-			invariant(isArray(values), `Expected an array at ${describePath(this.path)} in ${label}`);
-			invariant(values.length <= this.children.length, `Unknown channel '${joinPath(this.path, this.children.length)}' in ${label}`);
-			list = values;
-		}
-		for (let i = 0; i < this.children.length; i++) this.children[i].zip(theirs.children[i], list?.[i], label, fn);
+		for (let i = 0; i < this.children.length; i++) this.children[i].zip(theirs.children[i], fn);
 	}
 	broadcast(input, resolve, apply, label) {
 		const resolved = resolve(input, this.path);
@@ -859,10 +664,11 @@ var ListNode = class ListNode extends ChannelTreeNode {
 		for (const child of this.children) child.cover(value, apply);
 	}
 };
-var RecordNode = class RecordNode extends ChannelTreeNode {
+var RecordNode = class RecordNode {
+	path;
 	children;
 	constructor(children, path) {
-		super(path);
+		this.path = path;
 		this.children = children;
 	}
 	mirror(read, slots, carrier, key) {
@@ -870,28 +676,22 @@ var RecordNode = class RecordNode extends ChannelTreeNode {
 		carrier[key] = mine;
 		for (const [childKey, child] of this.children) child.mirror(read, slots, mine, childKey);
 	}
-	scatter(input, apply) {
+	scatter(input, accept, apply) {
 		invariant(isRecord(input), () => `Expected an object at ${describePath(this.path)}`);
 		for (const key of Object.keys(input)) {
 			const value = input[key];
 			if (value === void 0) continue;
 			const child = this.children.get(key);
 			invariant(child !== void 0, () => `Unknown channel '${joinPath(this.path, key)}'`);
-			child.scatter(value, apply);
+			child.scatter(value, accept, apply);
 		}
 	}
-	zip(theirs, values, label, fn) {
+	zip(theirs, fn) {
 		invariant(theirs instanceof RecordNode && theirs.children.size === this.children.size, () => `Shape mismatch at ${describePath(this.path)}`);
-		let record;
-		if (values !== void 0) {
-			invariant(isRecord(values), () => `Expected an object at ${describePath(this.path)} in ${label}`);
-			for (const key of Object.keys(values)) invariant(this.children.has(key), () => `Unknown channel '${joinPath(this.path, key)}' in ${label}`);
-			record = values;
-		}
 		for (const [key, child] of this.children) {
 			const their = theirs.children.get(key);
 			invariant(their !== void 0, () => `Shape mismatch at ${describePath(this.path)}`);
-			child.zip(their, record?.[key], label, fn);
+			child.zip(their, fn);
 		}
 	}
 	broadcast(input, resolve, apply, label) {
@@ -914,11 +714,50 @@ var RecordNode = class RecordNode extends ChannelTreeNode {
 	}
 };
 /**
+* A shape parsed into a node tree, paired with its leaves flattened in
+* depth-first shape order. `parser.match` decides leaf vs branch at every
+* position; the root must already be a container — callers validate that
+* (with their own message) before building. Nested non-containers and
+* empty nodes throw through `parser.mismatch`/`parser.empty`.
+*
+* Holds no behavior of its own: traversals run through `root`, and a live
+* view comes from `new ShapeView(root, read)`.
+*/
+var ShapeTree = class {
+	root;
+	leaves;
+	constructor(shape, parser) {
+		const leaves = [];
+		this.root = buildContainer(shape, "", parser, leaves);
+		this.leaves = leaves;
+	}
+};
+function buildContainer(shape, path, parser, leaves) {
+	if (isArray(shape)) {
+		invariant(shape.length > 0, () => parser.empty(path));
+		return new ListNode(shape.map((child, i) => buildChild(child, joinPath(path, i), parser, leaves)), path);
+	}
+	const keys = Object.keys(shape);
+	invariant(keys.length > 0, () => parser.empty(path));
+	const children = /* @__PURE__ */ new Map();
+	for (const key of keys) children.set(key, buildChild(shape[key], joinPath(path, key), parser, leaves));
+	return new RecordNode(children, path);
+}
+function buildChild(value, path, parser, leaves) {
+	const leaf = parser.match(value, path);
+	if (leaf !== void 0) {
+		leaves.push(leaf);
+		return new LeafNode(leaf, path);
+	}
+	invariant(isRecordOrArray(value), () => parser.mismatch(path));
+	return buildContainer(value, path, parser, leaves);
+}
+/**
 * A live view of a shape: `read(leaf)` at every leaf, mirrored into a stable
-* object — `refresh` rewrites the numbers in place through slots recorded at
+* object — `refresh` rewrites the values in place through slots recorded at
 * construction, so per-frame reads do no traversal or allocation.
 */
-var ChannelView = class {
+var ShapeView = class {
 	root;
 	#read;
 	#slots = [];
@@ -934,83 +773,463 @@ var ChannelView = class {
 	}
 };
 //#endregion
-//#region src/channel-tree.ts
+//#region src/spring-source.ts
 /**
-* A numeric shape — a plain object or array whose leaves are all numbers —
-* flattened into one leaf object per number, with the nesting preserved as a
-* tree of `ChannelTreeNode`s. The shape is fixed at construction. Knows nothing
-* about what the leaves are: construction, views, scatter, zip, and
-* broadcast are all structural; leaf semantics
-* live with the caller. Paths appear as dot-joined strings (`position.x`,
-* `color.2`) in every error.
+* The property key that brands a `SpringSource` and holds the channel its
+* followers read. A registry symbol (`Symbol.for('coily/spring-source')`),
+* so sources from one copy of coily are recognized by another when a
+* bundle duplicates the library.
 */
-var ChannelTree = class {
-	#root;
-	#leaves = [];
-	constructor(shape, factory) {
-		invariant(isRecordOrArray(shape), "A shape must be a plain object or an array of numeric channels");
-		this.#root = ChannelTreeNode.build(shape, "", factory, this.#leaves);
+const SpringSourceSymbol = Symbol.for("coily/spring-source");
+function isSpringSource(value) {
+	return typeof value === "object" && value !== null && SpringSourceSymbol in value;
+}
+const RECIPES = /* @__PURE__ */ new WeakMap();
+function applyFns(fns, value) {
+	let result = value;
+	for (const fn of fns) result = fn(result);
+	return result;
+}
+function sourceMismatch(path) {
+	return `Invalid value at ${describePath(path)}: expected a SpringSource or a nested shape of SpringSources`;
+}
+/**
+* Parses a shape of sources into a live view, collecting subscription
+* roots along the way (a mapped leaf contributes its recipe's roots and
+* reads through its pipeline). Structure is validated once at creation;
+* reads refresh a stable mirror through the view's slots, so per-update
+* reads do no traversal or allocation.
+*/
+function compileShape(shape, roots) {
+	const { root } = new ShapeTree(shape, {
+		match(value) {
+			if (!isSpringSource(value)) return void 0;
+			const recipe = RECIPES.get(value);
+			if (recipe) {
+				roots.push(...recipe.sources);
+				return () => applyFns(recipe.fns, recipe.read());
+			}
+			roots.push(value);
+			const api = value[SpringSourceSymbol];
+			return () => api.value;
+		},
+		mismatch: sourceMismatch,
+		empty: (path) => `Invalid value at ${describePath(path)}: a shape must contain at least one source`
+	});
+	return new ShapeView(root, (leaf) => leaf());
+}
+function mapSpring(source, map) {
+	const compute = map;
+	let recipe;
+	if (isSpringSource(source)) {
+		const flat = RECIPES.get(source);
+		if (flat) recipe = {
+			sources: flat.sources,
+			read: flat.read,
+			fns: [...flat.fns, compute]
+		};
+		else {
+			const api = source[SpringSourceSymbol];
+			recipe = {
+				sources: [source],
+				read: () => api.value,
+				fns: [compute]
+			};
+		}
+	} else {
+		invariant(isRecordOrArray(source), () => sourceMismatch(""));
+		const roots = [];
+		const view = compileShape(source, roots);
+		recipe = {
+			sources: [...new Set(roots)],
+			read: () => {
+				view.refresh();
+				return view.root;
+			},
+			fns: [compute]
+		};
 	}
-	/** Every leaf in depth-first shape order. */
-	get leaves() {
-		return this.#leaves;
+	const { sources, read, fns } = recipe;
+	const single = sources.length === 1 ? sources[0][SpringSourceSymbol] : null;
+	const apis = single ? null : sources.map((leaf) => leaf[SpringSourceSymbol]);
+	const mapped = Object.freeze({ [SpringSourceSymbol]: Object.freeze({
+		get value() {
+			return applyFns(fns, read());
+		},
+		onUpdate: single ? (callback) => single.onUpdate(callback) : (callback) => {
+			const unsubscribes = apis.map((api) => api.onUpdate(callback));
+			return () => {
+				for (const unsubscribe of unsubscribes) unsubscribe();
+			};
+		},
+		onDispose: single ? (callback) => single.onDispose(callback) : (callback) => {
+			let fired = false;
+			const unsubscribes = apis.map((api) => api.onDispose(() => {
+				if (fired) return;
+				fired = true;
+				for (const unsubscribe of unsubscribes) unsubscribe();
+				callback();
+			}));
+			return () => {
+				for (const unsubscribe of unsubscribes) unsubscribe();
+			};
+		}
+	}) });
+	RECIPES.set(mapped, recipe);
+	return mapped;
+}
+//#endregion
+//#region src/spring.ts
+/**
+* One animated number, driven toward its target with damped spring
+* motion. Create springs with `SpringSystem.createSpring`; the owning
+* system advances them, so a spring only moves while its system runs.
+*
+* Reads return the exact simulated state; nothing is rounded. Numeric
+* writes — `target`, `value`, `velocity`, `jumpTo` — require finite
+* numbers: `NaN` or an infinity throws rather than poisoning the
+* simulation. See
+* https://github.com/tkofh/coily/blob/main/PRECISION.md for the
+* numerical contract.
+*/
+var Spring = class {
+	/** Brands the spring as a `KinematicSource` whose api is the spring itself. */
+	get [SpringSourceSymbol]() {
+		return this;
+	}
+	#target;
+	#config;
+	#purpose;
+	#motion;
+	#motions;
+	#leader = null;
+	#unsubLeader = null;
+	#settled = null;
+	#resolveSettled = null;
+	#disposed = false;
+	constructor(motions, value, config, purpose = "motion") {
+		invariant(Number.isFinite(value), "Spring value must be a finite number");
+		invariant(purpose === "motion" || purpose === "appearance", "Spring purpose must be 'motion' or 'appearance'");
+		this.#motions = motions;
+		this.#config = config ?? SpringDefinition.default;
+		this.#target = value;
+		this.#purpose = purpose;
+		this.#motion = new Motion(this.#config, 0, 0);
+		this.#motion.respectsReducedMotion = purpose === "motion";
 	}
 	/**
-	* Builds a live view of the shape with `read(leaf)` at every leaf —
-	* see `ChannelView`.
+	* The value the spring is animating toward. While following a source,
+	* reads return the source's value as of its last update.
+	*
+	* Assignment accepts any `SpringTarget`:
+	* - A number retargets the spring. The current value and momentum carry
+	*   over, so mid-flight retargets stay smooth. Assigning a number while
+	*   following also stops the following.
+	* - A `SpringSource` — a `Spring`, or a value derived with `mapSpring` —
+	*   makes this spring follow the source's live value.
+	*
+	* Under reduced motion, retargets apply instantly — unless `purpose` is
+	* `'appearance'`, in which case they animate as normal.
 	*/
-	createView(read) {
-		return new ChannelView(this.#root, read);
+	get target() {
+		return this.#target;
+	}
+	set target(value) {
+		if (typeof value === "number") {
+			this.#unfollow();
+			this.#setTarget(value);
+		} else {
+			invariant(isSpringSource(value), "Spring target must be a number or a SpringSource");
+			invariant(typeof value[SpringSourceSymbol].value === "number", "A spring can only follow a scalar SpringSource; derive one from a composite with mapSpring");
+			this.#follow(value);
+		}
 	}
 	/**
-	* Scatters a partial numeric shape: `apply` runs for each channel the input
-	* mentions, the rest are untouched. Unknown channels and structure
-	* mismatches throw; `undefined` entries (and array holes) are skipped.
+	* The current animated value: the target plus the remaining
+	* displacement.
+	*
+	* Writing displaces the spring: it keeps its target and springs back
+	* from the written value, notifying update listeners synchronously.
+	* Writing the current value is a no-op. Under reduced motion a write
+	* jumps the spring — target included — to the written value, unless
+	* `purpose` is `'appearance'`, in which case it displaces as normal.
 	*/
-	scatter(input, apply) {
-		this.#root.scatter(input, apply);
+	get value() {
+		return this.#target + this.#motion.position;
+	}
+	set value(value) {
+		invariant(Number.isFinite(value), "Spring value must be a finite number");
+		if (this.#motions.reduced && this.#purpose === "motion") {
+			if (value !== this.value) this.jumpTo(value);
+			return;
+		}
+		const position = value - this.#target;
+		if (position !== this.#motion.position) {
+			this.#motions.add(this.#motion);
+			this.#motion.position = position;
+			this.#motion.tick(0);
+		}
+	}
+	/**
+	* The current velocity, in value units per second.
+	*
+	* Writing flings the spring: motion continues from the current value
+	* with the written velocity, then settles back to the target. Under
+	* reduced motion writes are ignored, unless `purpose` is `'appearance'`,
+	* in which case the fling applies as normal.
+	*/
+	get velocity() {
+		return this.#motion.velocity;
+	}
+	set velocity(value) {
+		invariant(Number.isFinite(value), "Spring velocity must be a finite number");
+		if (this.#motions.reduced && this.#purpose === "motion") return;
+		this.#motions.add(this.#motion);
+		this.#motion.velocity = value;
 	}
 	/**
-	* Pairs this map's leaves with another map's, requiring the shapes to
-	* match exactly. `values` is an optional partial numeric shape (labelled
-	* `valuesLabel` in errors) delivered alongside each pair — absent entries
-	* arrive as `undefined`.
+	* The current acceleration, in value units per second squared — how
+	* fast the velocity is changing. Read-only: acceleration is the
+	* spring's stiffness and friction acting on its current displacement
+	* and velocity, so it follows from the motion rather than being set.
+	* To fling the spring, write `velocity` instead.
 	*/
-	zip(other, values, valuesLabel, fn) {
-		this.#root.zip(other.#root, values, valuesLabel, fn);
+	get acceleration() {
+		const { tension, damping, mass } = this.#config;
+		return -(tension * this.#motion.position + damping * this.#motion.velocity) / mass;
 	}
 	/**
-	* Broadcasts a covering shape — an input mirroring the shape where a value
-	* at any node covers every leaf below it. At each node, `resolve` decides
-	* whether the input is a value for the whole subtree or a branch to
-	* descend into; `apply` runs per covered leaf. `undefined` entries are
-	* skipped, unknown channels (labelled `label` in errors) throw.
+	* What the spring animates — `'motion'` or `'appearance'` — fixed when
+	* it was created. An `'appearance'` spring opts out of reduced motion:
+	* it keeps animating where a `'motion'` spring snaps to its target. See
+	* `Purpose`.
 	*/
-	broadcast(input, resolve, apply, label) {
-		if (input === void 0) return;
-		this.#root.broadcast(input, resolve, apply, label);
+	get purpose() {
+		return this.#purpose;
+	}
+	/**
+	* The spring's `SpringDefinition`: the one it was created with or last
+	* assigned, otherwise `SpringDefinition.default`. Following a source
+	* never changes it — how a spring chases its target is the spring's
+	* own setting.
+	*
+	* Assigning a config reconfigures the spring in place — value and
+	* velocity are preserved, so mid-flight reconfigures stay smooth.
+	* Assigning `null` reverts to the default.
+	*/
+	get config() {
+		return this.#config;
+	}
+	/** The config's mass. */
+	get mass() {
+		return this.#config.mass;
+	}
+	/** The config's tension (stiffness). */
+	get tension() {
+		return this.#config.tension;
+	}
+	/** The config's damping (friction). */
+	get damping() {
+		return this.#config.damping;
+	}
+	/** The config's damping ratio. */
+	get dampingRatio() {
+		return this.#config.dampingRatio;
+	}
+	/** The config's resting precision. */
+	get precision() {
+		return this.#config.precision;
+	}
+	set config(value) {
+		const next = value ?? SpringDefinition.default;
+		if (this.#config === next) return;
+		this.#config = next;
+		this.#motion.configure(next);
+		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.
+	*/
+	get timeRemaining() {
+		return this.#motion.timeRemaining;
+	}
+	/**
+	* Whether the spring's remaining motion is inside its resting
+	* threshold. Resting springs cost nothing until the next write. See
+	* https://github.com/tkofh/coily/blob/main/PRECISION.md for the rest
+	* test.
+	*/
+	get isResting() {
+		return this.#motion.isResting;
+	}
+	/**
+	* A promise that resolves when the spring next comes to rest — already
+	* resolved while resting or after dispose. Retargeting mid-flight
+	* extends the wait; disposing resolves it.
+	*
+	* @example
+	* ```ts
+	* spring.target = 300
+	* await spring.settled
+	* // the spring is at 300 and resting
+	* ```
+	*/
+	get settled() {
+		if (this.#disposed || this.#motion.isResting) return RESOLVED;
+		this.#settled ??= new Promise((resolve) => {
+			this.#resolveSettled = resolve;
+			const unsubscribe = this.onStop(() => {
+				unsubscribe();
+				this.#settled = null;
+				this.#resolveSettled = null;
+				resolve();
+			});
+		});
+		return this.#settled;
+	}
+	/**
+	* Snaps the spring to `value` with no animation: target and value both
+	* become `value` and velocity clears. Listeners are notified
+	* synchronously — `update`, plus `stop` if the spring was moving.
+	*/
+	jumpTo(value) {
+		invariant(Number.isFinite(value), "Spring value must be a finite number");
+		this.#target = value;
+		this.#motion.finish();
+	}
+	/**
+	* Releases the spring permanently: stops following, detaches followers
+	* (each keeps its current target), resolves `settled`, and notifies
+	* dispose listeners. Calling it again is a no-op.
+	*
+	* A disposed spring keeps its final value readable; writes throw.
+	*/
+	dispose() {
+		if (this.#disposed) return;
+		this.#disposed = true;
+		if (this.#resolveSettled) {
+			this.#resolveSettled();
+			this.#settled = null;
+			this.#resolveSettled = null;
+		}
+		if (this.#unsubLeader) {
+			this.#unsubLeader();
+			this.#unsubLeader = null;
+			this.#leader = null;
+		}
+		this.#motions.remove(this.#motion);
+		this.#motion.dispose();
+	}
+	/**
+	* Subscribes to value changes: every tick the spring moves, plus
+	* synchronous `value` writes and `jumpTo` calls. Returns an unsubscribe
+	* function.
+	*/
+	onUpdate(callback) {
+		return this.#motion.onUpdate(callback);
+	}
+	/**
+	* Subscribes to the spring leaving rest. `start` and `stop` always
+	* alternate; retargeting mid-flight fires neither. Returns an
+	* unsubscribe function.
+	*/
+	onStart(callback) {
+		return this.#motion.onStart(callback);
+	}
+	/**
+	* Subscribes to the spring coming to rest, whether by settling or by
+	* `jumpTo`. Always alternates with `start`. Returns an unsubscribe
+	* function.
+	*/
+	onStop(callback) {
+		return this.#motion.onStop(callback);
+	}
+	/** Subscribes to `dispose`, which fires once. Returns an unsubscribe function. */
+	onDispose(callback) {
+		return this.#motion.onDispose(callback);
+	}
+	#setTarget(value) {
+		invariant(Number.isFinite(value), "Spring target must be a finite number");
+		if (value !== this.#target) {
+			if (this.#motions.reduced && this.#purpose === "motion") {
+				this.jumpTo(value);
+				return;
+			}
+			this.#motions.add(this.#motion);
+			const current = this.value;
+			this.#target = value;
+			this.#motion.position = current - this.#target;
+			this.#motion.tick(0, false);
+		}
+	}
+	#follow(source) {
+		this.#unsubLeader?.();
+		this.#leader = source;
+		const api = source[SpringSourceSymbol];
+		const unsubUpdate = api.onUpdate(() => {
+			this.#setTarget(api.value);
+		});
+		const unsubDispose = api.onDispose(() => {
+			this.#unfollow();
+		});
+		this.#unsubLeader = () => {
+			unsubUpdate();
+			unsubDispose();
+		};
+		this.#setTarget(api.value);
+	}
+	#unfollow() {
+		if (!this.#leader) return;
+		this.#unsubLeader();
+		this.#unsubLeader = null;
+		this.#leader = null;
 	}
 };
 //#endregion
-//#region src/spring-object.ts
+//#region src/composite-spring.ts
 function invalidConfig(path) {
-	return `Invalid config for ${describePath(path)}: expected a SpringConfig, null, or a config shape matching the value`;
+	return `Invalid config for ${describePath(path)}: expected a SpringDefinition, null, or a config shape matching the value`;
 }
 /**
-* Decides what a config node means: `null` and `SpringConfig` instances are
+* Decides what a config node means: `null` and `SpringDefinition` instances are
 * configs covering the whole subtree, any other object or array is a config
 * shape to descend into (its structure is checked on the way down), and
 * anything else — a bare number, string, or options object — is invalid.
 */
 function resolveConfigNode(node, path) {
 	if (node === null) return null;
-	if (node instanceof SpringConfig) return node;
+	if (node instanceof SpringDefinition) return node;
 	if (isRecordOrArray(node)) return BRANCH;
 	throw new Error(invalidConfig(path));
 }
+function invalidPurpose(path) {
+	return `Invalid purpose for ${describePath(path)}: expected 'motion', 'appearance', or a purpose shape matching the value`;
+}
+/**
+* Decides what a purpose node means: a `Purpose` string covers the whole
+* subtree, any object or array is a purpose shape to descend into, and
+* anything else is invalid.
+*/
+function resolvePurposeNode(node, path) {
+	if (node === "motion" || node === "appearance") return node;
+	if (isRecordOrArray(node)) return BRANCH;
+	throw new Error(invalidPurpose(path));
+}
 const readTarget = (spring) => spring.target;
 const readValue = (spring) => spring.value;
 const readVelocity = (spring) => spring.velocity;
+const readAcceleration = (spring) => spring.acceleration;
+/**
+* The target scatter's leaf guard: a channel animates toward a number,
+* or follows a scalar source. Checked here so the error carries the
+* channel's path.
+*/
+function acceptChannelTarget(input, path) {
+	invariant(isNumber(input) && Number.isFinite(input) || isSpringSource(input) && typeof input[SpringSourceSymbol].value === "number", () => `Invalid value at '${path}': expected a finite number or a scalar SpringSource`);
+	return input;
+}
 const assignTarget = (spring, value) => {
 	spring.target = value;
 };
@@ -1026,19 +1245,37 @@ const applyJump = (spring, value) => {
 const assignConfig = (spring, config) => {
 	spring.config = config;
 };
-const followChannel = (mine, theirs, offset) => {
-	mine.target = offset ? {
-		spring: theirs,
-		offset
-	} : theirs;
+const followChannel = (mine, theirs) => {
+	mine.target = theirs;
 };
-const RESOLVED = Promise.resolve();
-var SpringObject = class SpringObject {
+/**
+* A composite spring over a fixed numeric shape — a nested plain object
+* or array whose leaves are all numbers. Each leaf runs an independent
+* spring, called a channel, behind one API: targets, values, velocities,
+* and configs read and write as (partial) shapes, and events are
+* coalesced across channels. Create composite springs with
+* `SpringSystem.createSpring`.
+*
+* A composite spring is a `SpringSource` of its value shape: `mapSpring`
+* derives scalar sources from it — alone or at the leaves of a shape —
+* which springs can then follow. Only scalar sources are followable
+* directly.
+*
+* The shape is fixed at construction. Writes naming unknown channels
+* throw with the channel's path (`position.z`), and so do non-finite
+* channel values.
+*/
+var CompositeSpring = class CompositeSpring {
+	/** Brands the composite as a `KinematicSource` whose api is the composite itself. */
+	get [SpringSourceSymbol]() {
+		return this;
+	}
 	#motions;
-	#map;
-	#targetView;
+	#tree;
 	#valueView;
-	#velocityView;
+	#targetView = null;
+	#velocityView = null;
+	#accelerationView = null;
 	#emitter = new Emitter();
 	#running = false;
 	#dirty = false;
@@ -1061,14 +1298,18 @@ var SpringObject = class SpringObject {
 			this.#emitter.emit("start");
 		}
 	};
-	constructor(motions, value, config) {
+	constructor(motions, value, config, purpose) {
 		this.#motions = motions;
-		invariant(isRecordOrArray(value), "Spring object value must be a plain object or an array of numeric channels");
-		this.#map = new ChannelTree(value, (leafValue) => new Spring(motions, leafValue));
-		if (config !== void 0) this.#map.broadcast(config, resolveConfigNode, assignConfig, "config");
-		this.#targetView = this.#map.createView(readTarget);
-		this.#valueView = this.#map.createView(readValue);
-		this.#velocityView = this.#map.createView(readVelocity);
+		invariant(isRecordOrArray(value), "Composite spring value must be a plain object or an array of numeric channels");
+		let purposeByPath = null;
+		if (purpose !== void 0) {
+			const byPath = /* @__PURE__ */ new Map();
+			new ShapeTree(value, channelParser((_leafValue, path) => path)).root.broadcast(purpose, resolvePurposeNode, (path, p) => byPath.set(path, p), "purpose");
+			purposeByPath = byPath;
+		}
+		this.#tree = new ShapeTree(value, channelParser((leafValue, path) => new Spring(motions, leafValue, void 0, purposeByPath?.get(path) ?? "motion")));
+		if (config !== void 0) this.#tree.root.broadcast(config, resolveConfigNode, assignConfig, "config");
+		this.#valueView = new ShapeView(this.#tree.root, readValue);
 		const markDirty = () => {
 			this.#dirty = true;
 			this.#motions.flushes.request(this.#flush);
@@ -1076,66 +1317,141 @@ var SpringObject = class SpringObject {
 		const schedule = () => {
 			this.#motions.flushes.request(this.#flush);
 		};
-		for (const channel of this.#map.leaves) {
+		for (const channel of this.#tree.leaves) {
 			channel.onUpdate(markDirty);
 			channel.onStart(schedule);
 			channel.onStop(schedule);
 		}
 	}
+	/**
+	* The value each channel is animating toward, as a read-only mirror of
+	* the shape. The mirror object is reused: every read refreshes its
+	* numbers in place, so read it fresh rather than holding it across
+	* frames.
+	*
+	* Assignment accepts a `CompositeSpringTarget`:
+	* - A partial shape retargets the channels it names and leaves the
+	*   others alone. Each named channel takes a number, or a scalar
+	*   `SpringSource` to follow — a `Spring`, or a value derived with
+	*   `mapSpring`. While following a leader, naming a channel also
+	*   detaches that channel from it.
+	* - A `CompositeSpring` of the same shape follows the leader channel by
+	*   channel.
+	*
+	* Unknown channels throw with their path.
+	*/
 	get target() {
-		this.#targetView.refresh();
-		return this.#targetView.root;
+		const view = this.#targetView ??= new ShapeView(this.#tree.root, readTarget);
+		view.refresh();
+		return view.root;
 	}
 	set target(value) {
-		if (value instanceof SpringObject) this.#follow(value, void 0);
-		else if (isRecord(value) && "spring" in value && value.spring instanceof SpringObject) {
-			const { spring, offset } = value;
-			this.#follow(spring, offset);
-		} else this.#motions.flushes.batch(() => {
-			this.#map.scatter(value, assignTarget);
+		if (value instanceof CompositeSpring) this.#follow(value);
+		else this.#motions.flushes.batch(() => {
+			this.#tree.root.scatter(value, acceptChannelTarget, assignTarget);
 		});
 	}
+	/**
+	* The current animated value of every channel, as a read-only mirror of
+	* the shape. The mirror object is reused: every read refreshes its
+	* numbers in place, so read it fresh rather than holding it across
+	* frames.
+	*
+	* Assignment takes a partial shape and displaces the channels it names:
+	* each keeps its target and springs back from the written value, with
+	* one coalesced `update` fired synchronously. Under reduced motion a
+	* write jumps the named channels — targets included — except channels
+	* whose `purpose` is `'appearance'`, which displace as normal.
+	*/
 	get value() {
 		this.#valueView.refresh();
 		return this.#valueView.root;
 	}
 	set value(value) {
 		this.#motions.flushes.batch(() => {
-			this.#map.scatter(value, assignValue);
+			this.#tree.root.scatter(value, acceptNumber, assignValue);
 		});
 	}
+	/**
+	* The current velocity of every channel in value units per second, as a
+	* read-only mirror of the shape — reused and refreshed in place on each
+	* read.
+	*
+	* Assignment takes a partial shape and flings the channels it names;
+	* the rest are untouched. Under reduced motion writes are ignored,
+	* except on channels whose `purpose` is `'appearance'`.
+	*/
 	get velocity() {
-		this.#velocityView.refresh();
-		return this.#velocityView.root;
+		const view = this.#velocityView ??= new ShapeView(this.#tree.root, readVelocity);
+		view.refresh();
+		return view.root;
 	}
 	set velocity(value) {
 		this.#motions.flushes.batch(() => {
-			this.#map.scatter(value, assignVelocity);
+			this.#tree.root.scatter(value, acceptNumber, assignVelocity);
 		});
 	}
+	/**
+	* The current acceleration of every channel in value units per second
+	* squared, as a read-only mirror of the shape — reused and refreshed in
+	* place on each read. Read-only, like each channel's: acceleration
+	* follows from the motion. To fling channels, write `velocity`.
+	*/
+	get acceleration() {
+		const view = this.#accelerationView ??= new ShapeView(this.#tree.root, readAcceleration);
+		view.refresh();
+		return view.root;
+	}
+	/**
+	* The shared config when every channel resolves to the same
+	* `SpringDefinition`, and `null` when they differ.
+	*
+	* Assignment accepts a `ConfigShape`: one config for every channel,
+	* `null` to revert every channel to the default, or a shape mirroring
+	* the value with configs at any level — a config at a subtree covers
+	* every channel below it. Non-config leaves throw with their path.
+	*/
 	get config() {
-		const channels = this.#map.leaves;
+		const channels = this.#tree.leaves;
 		const first = channels[0].config;
 		for (let i = 1; i < channels.length; i++) if (channels[i].config !== first) return null;
 		return first;
 	}
 	set config(value) {
 		this.#motions.flushes.batch(() => {
-			this.#map.broadcast(value ?? null, resolveConfigNode, assignConfig, "config");
+			this.#tree.root.broadcast(value ?? null, resolveConfigNode, assignConfig, "config");
 		});
 	}
+	/**
+	* The shared purpose when every channel resolves to the same `Purpose`,
+	* and `null` when they differ. Fixed when the spring is created — an
+	* `'appearance'` channel opts out of reduced motion. See `Purpose`.
+	*/
+	get purpose() {
+		const channels = this.#tree.leaves;
+		const first = channels[0].purpose;
+		for (let i = 1; i < channels.length; i++) if (channels[i].purpose !== first) return null;
+		return first;
+	}
+	/** The largest `timeRemaining` across channels, in milliseconds. */
 	get timeRemaining() {
 		let max = 0;
-		for (const channel of this.#map.leaves) {
+		for (const channel of this.#tree.leaves) {
 			const remaining = channel.timeRemaining;
 			if (remaining > max) max = remaining;
 		}
 		return max;
 	}
+	/** Whether every channel is resting. */
 	get isResting() {
-		for (const channel of this.#map.leaves) if (!channel.isResting) return false;
+		for (const channel of this.#tree.leaves) if (!channel.isResting) return false;
 		return true;
 	}
+	/**
+	* A promise that resolves when every channel next rests — already
+	* resolved while resting or after dispose. Retargeting any channel
+	* mid-flight extends the wait; disposing resolves it.
+	*/
 	get settled() {
 		if (this.#disposed || this.isResting) return RESOLVED;
 		this.#settled ??= new Promise((resolve) => {
@@ -1149,11 +1465,23 @@ var SpringObject = class SpringObject {
 		});
 		return this.#settled;
 	}
+	/**
+	* Snaps the channels the partial shape names to the given values with
+	* no animation, notifying listeners synchronously. Channels it leaves
+	* out are untouched.
+	*/
 	jumpTo(value) {
 		this.#motions.flushes.batch(() => {
-			this.#map.scatter(value, applyJump);
+			this.#tree.root.scatter(value, acceptNumber, applyJump);
 		});
 	}
+	/**
+	* Releases every channel permanently: resolves `settled` and notifies
+	* dispose listeners. Calling it again is a no-op.
+	*
+	* A disposed composite spring keeps its final values readable; writes
+	* throw.
+	*/
 	dispose() {
 		if (this.#disposed) return;
 		this.#disposed = true;
@@ -1162,24 +1490,40 @@ var SpringObject = class SpringObject {
 			this.#settled = null;
 			this.#resolveSettled = null;
 		}
-		for (const channel of this.#map.leaves) channel.dispose();
+		for (const channel of this.#tree.leaves) channel.dispose();
 		this.#emitter.clear();
 	}
+	/**
+	* Subscribes to coalesced value changes: at most one `update` per tick,
+	* fired after every channel has advanced, plus one per synchronous
+	* write. Returns an unsubscribe function.
+	*/
 	onUpdate(callback) {
 		return this.#emitter.on("update", callback);
 	}
+	/**
+	* Subscribes to the composite leaving rest: a channel starts moving
+	* while all were resting. Always alternates with `stop`. Returns an
+	* unsubscribe function.
+	*/
 	onStart(callback) {
 		return this.#emitter.on("start", callback);
 	}
+	/**
+	* Subscribes to the composite coming to rest: every channel resting,
+	* fired after that tick's final `update`. Always alternates with
+	* `start`. Returns an unsubscribe function.
+	*/
 	onStop(callback) {
 		return this.#emitter.on("stop", callback);
 	}
+	/** Subscribes to `dispose`, which fires once. Returns an unsubscribe function. */
 	onDispose(callback) {
-		return this.#map.leaves[0].onDispose(callback);
+		return this.#tree.leaves[0].onDispose(callback);
 	}
-	#follow(leader, offset) {
+	#follow(leader) {
 		this.#motions.flushes.batch(() => {
-			this.#map.zip(leader.#map, offset, "offset", followChannel);
+			this.#tree.root.zip(leader.#tree.root, followChannel);
 		});
 	}
 };
@@ -1190,6 +1534,12 @@ const cancel = (id) => {
 	if (typeof window !== "undefined") window.cancelAnimationFrame(id);
 	else clearTimeout(id);
 };
+/**
+* Drives a `MotionSet` from animation frames. Schedules frames only
+* while motions exist — otherwise it sleeps and the set's `onWake`
+* rearms it — paces fps caps to whole display frames, and clamps lag
+* gaps.
+*/
 var Ticker = class {
 	#fps;
 	#gap;
@@ -1295,18 +1645,21 @@ var Ticker = class {
 	}
 	#onFrame(timestamp) {
 		if (this.#stopped) return;
-		if (this.#primed) {
-			const wallElapsed = timestamp - this.#lastWallTime;
-			const elapsed = wallElapsed > this.#lagThreshold ? this.#adjustedLag : wallElapsed;
-			this.#acc += elapsed;
-			if (this.#acc + elapsed / 2 >= this.#capGap) {
-				const delta = this.#acc;
-				this.#acc = 0;
-				this.#step(delta);
-			}
-		} else this.#primed = true;
-		this.#lastWallTime = timestamp;
-		this.#schedule();
+		try {
+			if (this.#primed) {
+				const wallElapsed = timestamp - this.#lastWallTime;
+				const elapsed = wallElapsed > this.#lagThreshold ? this.#adjustedLag : wallElapsed;
+				this.#acc += elapsed;
+				if (this.#acc + elapsed / 2 >= this.#capGap) {
+					const delta = this.#acc;
+					this.#acc = 0;
+					this.#step(delta);
+				}
+			} else this.#primed = true;
+		} finally {
+			this.#lastWallTime = timestamp;
+			if (!this.#stopped) this.#schedule();
+		}
 	}
 	#step(dt) {
 		this.#time += dt;
@@ -1340,13 +1693,19 @@ var SpringSystemImpl = class {
 	get reducedMotion() {
 		return this.#motion.reduced;
 	}
-	createSpring(position, config) {
-		return new Spring(this.#motion, position, config);
-	}
-	createSpringObject(value, config) {
-		return new SpringObject(this.#motion, value, config);
+	createSpring(value, config, options) {
+		if (typeof value === "number") return new Spring(this.#motion, value, config, options?.purpose);
+		if (isSpringSource(value)) {
+			const api = value[SpringSourceSymbol];
+			invariant(typeof api.value === "number", "A spring can only follow a scalar SpringSource; derive one from a composite with mapSpring");
+			const spring = new Spring(this.#motion, api.value, config, options?.purpose);
+			spring.target = value;
+			return spring;
+		}
+		return new CompositeSpring(this.#motion, value, config, options?.purpose);
 	}
 	advance(dt) {
+		invariant(Number.isFinite(dt), "dt must be a finite number of milliseconds");
 		this.#motion.tick(dt / 1e3);
 	}
 	start() {
@@ -1377,8 +1736,23 @@ var SpringSystemImpl = class {
 		this.#ticker.adjustedLag = value;
 	}
 };
+/**
+* Creates a spring system: the entry point of the library.
+*
+* @example
+* ```ts
+* const system = createSpringSystem()
+* system.start()
+*
+* const spring = system.createSpring(0)
+* spring.onUpdate(() => {
+*   element.style.translate = `${spring.value}px 0`
+* })
+* spring.target = 300
+* ```
+*/
 function createSpringSystem(options) {
 	return new SpringSystemImpl(options);
 }
 //#endregion
-export { SpringConfig as n, defineSpring as r, createSpringSystem as t };
+export { SpringDefinition as a, mapSpring as i, SpringSourceSymbol as n, defineSpring as o, isSpringSource as r, invariant as s, createSpringSystem as t };