effect-motion 0.4.0 → 0.6.0

package/dist/Motion.js

@@ -49,7 +49,7 @@ const interpolate = Effect.fnUntraced(function* (from, to, duration, fn, timing
         yield* Scene.tick;
     }
 });
-// InterpolableOnly of an opaque Data["Type"] can't be proven
+// InterpolableOnly of an opaque Entity.EntityByTag<Tag> can't be proven
 // index-compatible with Record<string, number>; the runtime shape is
 // guaranteed by the Target type, so cast once here.
 export const resolveTarget = (target, current) => (typeof target === "function"
@@ -71,12 +71,12 @@ export const startValues = (current, target, explicitFrom) => {
     return start;
 };
 const animate = Effect.fnUntraced(function* (instanceOrEffect, from, to, duration, timing) {
-    const instance = yield* Instance.flatten(instanceOrEffect);
+    const instance = yield* Instance.flattenInstance(instanceOrEffect);
     const current = yield* Scene.data(instance);
     const target = resolveTarget(to, current);
     const start = startValues(current, target, from === undefined ? {} : resolveTarget(from, current));
     yield* interpolate(start, target, duration, (value) => 
-    // Data["Type"] is opaque to TS, so spread is disallowed — assign + cast
+    // Entity.EntityByTag<Tag> is opaque to TS, so spread is disallowed — assign + cast
     Scene.update(instance, (data) => Object.assign({}, data, value)), timing);
     return instance;
 });
@@ -84,26 +84,87 @@ const animate = Effect.fnUntraced(function* (instanceOrEffect, from, to, duratio
 // `timing` makes call arity ambiguous between the two forms
 const firstArgIsInstance = (args) => Instance.isInstance(args[0]);
 /**
- * Animate interpolable (numeric) props of an instance toward `to` over
- * `duration` by raw field name, starting from the instance's current
- * data, optionally paced by a timing function (name or function, default
- * linear). Dual: `tweenTo(instance, to, duration, timing?)` or
- * `instance.pipe(tweenTo(to, duration, timing?))`. Resolves with the
- * instance, so animations chain.
+ * Interpolate numeric fields of an instance to `to` over `duration`,
+ * starting from whatever they currently are.
+ *
+ * @remarks
+ * This is the RAW layer: fields are addressed by their schema name, so
+ * `tweenTo` reaches everything the semantic animators don't cover —
+ * `radius`, `width`, `height`, `fontSize`, `strokeWidth`, a Camera's
+ * `focalLength`. Prefer {@link moveTo} / {@link fadeTo} where they apply;
+ * they move an entity as a unit, which a per-field tween cannot.
+ *
+ * Only the fields named in `to` are touched; the rest are left alone.
+ * `to` may also be a function of the current data, for a target computed
+ * at animation start. Colors are interpolable too, mixed through Lab by
+ * default.
+ *
+ * The final frame receives exactly `to` (for any easing with f(1) = 1), so
+ * a chain of tweens never accumulates drift. A field that has no current
+ * value — an optional one never set — is a loud defect rather than a
+ * silent NaN; pass an explicit origin with {@link tween} instead.
+ *
+ * @param to - The fields to animate and their target values.
+ * @param duration - How long, in scene time; rounded to whole frames at
+ *   the runner's frame rate. A zero duration still takes one frame.
+ * @param timing - An easing name from `Timing.timingFunctions`, or your own
+ *   `(t: number) => number`.
+ * @defaultValue `timing` — `"linear"`
+ * @returns The instance, so animators chain.
+ * @see {@link tween} to specify the starting value explicitly.
+ *
+ * @example
+ * Grow a circle's radius, then shrink it back with a different curve.
+ * ```typescript
+ * yield* dot.pipe(
+ * 	Motion.tweenTo({ radius: 40 }, "600 millis", "easeOutBack"),
+ * 	Motion.tweenTo({ radius: 4 }, "400 millis", "easeInQuad"),
+ * );
+ * ```
  */
 export const tweenTo = dual(firstArgIsInstance, (instance, to, duration, timing) => animate(instance, undefined, to, duration, timing));
 /**
- * Parametric animator: each frame applies `fn` with the eased parameter
- * and the current data, then ticks. The final frame receives exactly
- * `t = 1` for any timing with f(1) = 1; a zero-length duration still
- * takes one frame. This is the primitive under coordinated multi-field
- * motion — arcs, orbits, counters — where independent per-field tweens
- * cannot express the coupling. Determinism: `fn` sees only `(t, data)`.
- * Dual: `drive(instance, duration, timing, fn)` or
- * `instance.pipe(drive(duration, timing, fn))`.
+ * The escape hatch: run `fn` once per frame with the eased progress and the
+ * entity's current data, and use whatever it returns as the new data.
+ *
+ * @remarks
+ * Reach for `drive` when fields must move TOGETHER in a way independent
+ * tweens cannot express. Tweening `x` and `y` separately gives you a
+ * straight line; a circular orbit needs both derived from one angle, and
+ * that coupling is what this provides. It is the primitive `Camera.orbit`
+ * and `Camera.dolly` are themselves built on.
+ *
+ * `fn` must be pure — it receives only `(t, data)` and returns new data, so
+ * a scene stays reproducible frame-for-frame. Reading a clock or a random
+ * number here is what breaks determinism. `t` is the EASED parameter, so a
+ * non-linear `timing` reshapes the pacing without `fn` knowing.
+ *
+ * The final frame receives exactly `t = 1` for any easing with f(1) = 1, so
+ * the motion lands precisely on whatever `fn(1, …)` computes.
+ *
+ * @param duration - How long, in scene time.
+ * @param timing - An easing name or function; applied to `t` before `fn`
+ *   sees it.
+ * @param fn - Pure `(t, data) => data`, called once per frame.
+ * @returns The instance, so animators chain.
+ *
+ * @example
+ * Sweep a dot around a circle — one angle driving both axes, which two
+ * independent tweens could not do.
+ * ```typescript
+ * yield* dot.pipe(
+ * 	Motion.drive("2 seconds", "linear", (t, data) => ({
+ * 		...data,
+ * 		position: Entity.vec3({
+ * 			x: 250 + Math.cos(t * 2 * Math.PI) * 120,
+ * 			y: 150 + Math.sin(t * 2 * Math.PI) * 120,
+ * 		}),
+ * 	})),
+ * );
+ * ```
  */
 export const drive = dual(firstArgIsInstance, Effect.fnUntraced(function* (instanceOrEffect, duration, timing, fn) {
-    const instance = yield* Instance.flatten(instanceOrEffect);
+    const instance = yield* Instance.flattenInstance(instanceOrEffect);
     const runner = yield* Runner.Runner;
     const timingFn = Timing.resolve(timing);
     const frames = Math.max(1, Time.toFrames(duration, runner.settings.frameRate));
@@ -115,56 +176,227 @@ export const drive = dual(firstArgIsInstance, Effect.fnUntraced(function* (insta
     return instance;
 }));
 /**
- * Like `tweenTo`, but with an explicit start: interpolates the keys of
- * `to` from `from` (keys missing in `from` start at the current data).
- * Dual: `tween(instance, from, to, duration, timing?)` or
- * `instance.pipe(tween(from, to, duration, timing?))`.
+ * Like {@link tweenTo}, but with an explicit starting value.
+ *
+ * @remarks
+ * Reach for this when the animation should not begin where the entity
+ * currently sits — a "flash in from nothing" that must start at 0 no matter
+ * what the last animation left behind, or a field with no current value at
+ * all (an optional one never set), which {@link tweenTo} rejects as a
+ * defect.
+ *
+ * Keys present in `to` but missing from `from` still start at the current
+ * data, so a partial origin is a targeted override rather than an
+ * all-or-nothing switch.
+ *
+ * @param from - Starting values; keys omitted here start at the current data.
+ * @param to - Target values — this key set defines what gets animated.
+ * @param duration - How long, in scene time.
+ * @param timing - An easing name or function.
+ * @defaultValue `timing` — `"linear"`
+ * @returns The instance, so animators chain.
+ *
+ * @example
+ * Pop a label in from zero size, regardless of its current `fontSize`.
+ * ```typescript
+ * yield* label.pipe(
+ * 	Motion.tween({ fontSize: 0 }, { fontSize: 32 }, "400 millis", "easeOutBack"),
+ * );
+ * ```
  */
 export const tween = dual(firstArgIsInstance, (instance, from, to, duration, timing) => animate(instance, from, to, duration, timing));
+const readPosition = (data) => data.position;
+/**
+ * Structural parameter, not `EntityByTag<Tag>`: `Tag extends Fadeable`
+ * guarantees the field, but TypeScript will not distribute that constraint
+ * over the union, so asking for the shape directly is both true and simpler
+ * than an intersection type that never resolves.
+ */
+const readOpacity = (data) => data.opacity;
+/**
+ * Write a position, holding unnamed channels at their current value — the
+ * channel-level sparseness rule (design D8) that has to survive `position`
+ * becoming a nested Vec3. A partial Vec3 must never reach `interpolate`:
+ * lerping an absent channel yields NaN frames.
+ */
+const writePosition = (data, value) => ({
+    ...data,
+    position: Entity.vec3({
+        x: value.x ?? data.position.x,
+        y: value.y ?? data.position.y,
+        z: value.z ?? data.position.z,
+    }),
+});
 const animatePosition = Effect.fnUntraced(function* (instanceOrEffect, from, to, duration, timing) {
-    const instance = yield* Instance.flatten(instanceOrEffect);
-    const lens = Entity.traitOrDie(instance.entity, "~position");
-    const current = lens.get(yield* Scene.data(instance));
+    const instance = yield* Instance.flattenInstance(instanceOrEffect);
+    const current = readPosition(yield* Scene.data(instance));
     // partial targets/origins hold the missing axis at its current value
     const target = { ...current, ...to };
     const start = { ...current, ...(from ?? {}) };
-    yield* interpolate(start, target, duration, (value) => Scene.update(instance, (data) => lens.set(data, value)), timing);
+    yield* interpolate(start, target, duration, (value) => Scene.update(instance, (data) => writePosition(data, value)), timing);
     return instance;
 });
 const animateOpacity = Effect.fnUntraced(function* (instanceOrEffect, from, to, duration, timing) {
-    const instance = yield* Instance.flatten(instanceOrEffect);
-    const lens = Entity.traitOrDie(instance.entity, "~opacity");
-    const current = lens.get(yield* Scene.data(instance));
-    yield* interpolate({ opacity: from ?? current }, { opacity: to }, duration, (value) => Scene.update(instance, (data) => lens.set(data, value.opacity)), timing);
+    const instance = yield* Instance.flattenInstance(instanceOrEffect);
+    const current = readOpacity(yield* Scene.data(instance));
+    yield* interpolate({ opacity: from ?? current }, { opacity: to }, duration, (value) => Scene.update(instance, (data) => ({ ...data, opacity: value.opacity })), timing);
     return instance;
 });
 /**
- * Move an instance to a position via its `~position` trait — per-entity
- * semantics (a Line translates whole, a Group carries its subtree).
- * Partial targets hold the missing axis. Dual:
- * `moveTo(instance, to, duration, timing?)` or
- * `instance.pipe(moveTo(to, duration, timing?))`.
+ * Move an instance to a position over `duration`.
+ *
+ * @remarks
+ * The semantic counterpart to tweening x/y/z by hand, and what you should
+ * reach for whenever you want something to travel. Because every entity's
+ * geometry is expressed RELATIVE to its `position`, one `moveTo` translates
+ * the whole shape rigidly: a Line carries both endpoints, a Path its whole
+ * command list, a Group its entire subtree. There is no per-entity special
+ * casing to remember.
+ *
+ * Targets are partial — naming only `x` holds `y` and `z` at their current
+ * values, which is what makes single-axis motion read cleanly. `z` is depth:
+ * moving along it changes an entity's size and parallax under a perspective
+ * camera rather than just its sort order.
+ *
+ * Accepted for any entity that carries a position, which is all of them —
+ * the Camera included, so this is also how you fly the camera.
+ *
+ * @param to - Target position; omitted axes hold their current value.
+ * @param duration - How long, in scene time.
+ * @param timing - An easing name or function.
+ * @defaultValue `timing` — `"linear"`
+ * @returns The instance, so animators chain.
+ * @see {@link move} to start from an explicit position, and
+ *   `Physics.springTo` for durationless motion with momentum.
+ *
+ * @example
+ * Slide right, then drop — the second leg holds the x reached by the first.
+ * ```typescript
+ * yield* box.pipe(
+ * 	Motion.moveTo({ x: 400 }, "1 second", "easeInOutCubic"),
+ * 	Motion.moveTo({ y: 250 }, "600 millis", "easeInQuad"),
+ * );
+ * ```
  */
 export const moveTo = dual(firstArgIsInstance, (instance, to, duration, timing) => animatePosition(instance, undefined, to, duration, timing));
-/** Like `moveTo`, but from an explicit position (partials filled from current). */
+/**
+ * Like {@link moveTo}, but starting from an explicit position.
+ *
+ * @remarks
+ * The entrance animator: an instance can sit at its final position in the
+ * scene tree and still fly in from off-screen, because the origin is stated
+ * rather than read. Both `from` and `to` are partial, and each fills its
+ * missing axes from the current position.
+ *
+ * @param from - Starting position; omitted axes start at the current value.
+ * @param to - Target position; omitted axes hold their current value.
+ * @param duration - How long, in scene time.
+ * @param timing - An easing name or function.
+ * @defaultValue `timing` — `"linear"`
+ * @returns The instance, so animators chain.
+ *
+ * @example
+ * Slide a title in from off the left edge to where it was declared.
+ * ```typescript
+ * yield* title.pipe(
+ * 	Motion.move({ x: -200 }, { x: 60 }, "700 millis", "easeOutCubic"),
+ * );
+ * ```
+ */
 export const move = dual(firstArgIsInstance, (instance, from, to, duration, timing) => animatePosition(instance, from, to, duration, timing));
 /**
- * Fade an instance's opacity via its `~opacity` trait. Dual:
- * `fadeTo(instance, opacity, duration, timing?)` or
- * `instance.pipe(fadeTo(opacity, duration, timing?))`.
+ * Fade an instance's `opacity` to `to` over `duration`.
+ *
+ * @remarks
+ * Opacity runs 0 (invisible) to 1 (fully opaque), and applies to the whole
+ * subtree: fading a Group fades everything inside it, which is the usual way
+ * to dissolve a composed element as one piece.
+ *
+ * Only entities that actually paint carry `opacity`, so this is statically
+ * gated — fading a Camera is a compile error naming the missing field, not a
+ * runtime surprise.
+ *
+ * @param to - Target opacity, 0 to 1.
+ * @param duration - How long, in scene time.
+ * @param timing - An easing name or function.
+ * @defaultValue `timing` — `"linear"`
+ * @returns The instance, so animators chain.
+ * @see {@link fade} to start from an explicit opacity.
+ *
+ * @example
+ * Land, hold, then dissolve out.
+ * ```typescript
+ * yield* card.pipe(
+ * 	Motion.moveTo({ y: 100 }, "500 millis"),
+ * 	Motion.wait("1 second"),
+ * 	Motion.fadeTo(0, "400 millis"),
+ * );
+ * ```
  */
 export const fadeTo = dual(firstArgIsInstance, (instance, to, duration, timing) => animateOpacity(instance, undefined, to, duration, timing));
-/** Like `fadeTo`, but from an explicit opacity. */
+/**
+ * Like {@link fadeTo}, but starting from an explicit opacity.
+ *
+ * @remarks
+ * The fade-in idiom: entities are born fully opaque, so `fadeTo(1)` alone
+ * would be a no-op. Stating the origin is what makes an entrance possible
+ * without first writing `opacity: 0` at instantiate time.
+ *
+ * @param from - Starting opacity, 0 to 1.
+ * @param to - Target opacity, 0 to 1.
+ * @param duration - How long, in scene time.
+ * @param timing - An easing name or function.
+ * @defaultValue `timing` — `"linear"`
+ * @returns The instance, so animators chain.
+ *
+ * @example
+ * Fade a caption in from nothing.
+ * ```typescript
+ * yield* caption.pipe(Motion.fade(0, 1, "500 millis"));
+ * ```
+ */
 export const fade = dual(firstArgIsInstance, (instance, from, to, duration, timing) => animateOpacity(instance, from, to, duration, timing));
 /**
- * Hold the scene for `duration` of scene time (frames at the runner's
- * frame rate) — `Scene.sleep`'s chainable sibling.
+ * Hold for `duration` of scene time — the chainable sibling of
+ * `Scene.sleep`.
+ *
+ * @remarks
+ * This is frame time, not wall time: `Effect.sleep` would block on a real
+ * clock and make the scene non-deterministic, so `wait` advances whole
+ * frames at the runner's frame rate instead. The same hold produces the
+ * same frame count on every run and on every machine.
+ *
+ * Its value over `Scene.sleep` is placement — because it doubles as a pipe
+ * step, a beat can sit inside an animator chain without breaking it apart
+ * into separate statements.
+ *
+ * As a pipe step it wraps the PRECEDING step and passes its value through,
+ * so it sits anywhere in a chain — including first, where the step it wraps
+ * is the bare instance handle.
+ *
+ * @param duration - How long to hold, in scene time.
+ *
+ * @example
+ * A hold between two animations, mid-chain — `card` flows through to the
+ * fade.
+ * ```typescript
+ * yield* card.pipe(
+ * 	Motion.moveTo({ y: 100 }, "500 millis"),
+ * 	Motion.wait("1 second"),
+ * 	Motion.fadeTo(0, "300 millis"),
+ * );
+ * ```
  *
- * - `yield* Motion.wait("1 second")` — plain frame-based sleep
- * - `instance.pipe(moveTo(...), Motion.wait("1 second"), fadeTo(...))`
- *   — the hold runs between the two animations and the instance flows on
+ * @example
+ * Or yielded on its own, as a plain pause in the scene body.
+ * ```typescript
+ * yield* Motion.wait("2 seconds");
+ * ```
  */
-export const wait = (duration) => Object.assign((effect) => Effect.tap(effect, () => Scene.sleep(duration)), Effectable.Prototype({
+export const wait = (duration) => Object.assign((effect) => Effect.tap(
+// an Instance is Pipeable but NOT an Effect, so a bare handle as
+// the opening pipe step must be lifted before tapping
+Instance.flattenInstance(effect), () => Scene.sleep(duration)), Effectable.Prototype({
     label: "Motion.wait",
     evaluate: () => Scene.sleep(duration),
 }));

package/dist/Physics.d.ts

@@ -1,23 +1,105 @@
 import * as Effect from "effect/Effect";
-import type * as Schema from "effect/Schema";
 import * as Entity from "./Entity.js";
 import * as Instance from "./Instance.js";
+import type * as Motion from "./Motion.js";
 import * as Runner from "./Runner.js";
 /**
- * Physics-based motion: durationless animations that carry momentum and
- * end on their own. A spring is a damped harmonic oscillator simulated
- * until displacement and velocity settle within a tolerance — there is
- * no duration to specify, so springs are combinators here rather than
- * `TimingInput`s.
+ * Physics-based motion: animations with no duration, whose length emerges
+ * from a simulation rather than being declared.
+ *
+ * @remarks
+ * A spring is a damped harmonic oscillator, integrated until both
+ * displacement and velocity fall inside a tolerance — then snapped exactly
+ * onto the target. You describe the FEEL (mass, stiffness, damping) and the
+ * physics decides how long it takes. That is the whole reason springs live
+ * here as their own animators rather than as another easing name: an easing
+ * curve is a function of a duration you supply, and a spring has no duration
+ * to supply.
+ *
+ * Reach for a spring when motion should feel physical — something landing,
+ * settling, or reacting — and for `Motion`'s tweens when you need a beat to
+ * take an exact, known amount of time. A springy easing (`easeOutElastic`,
+ * `easeOutBounce`) is the middle ground: spring-like shape, fixed duration.
+ *
+ * Named presets live in {@link springs}; the same call takes a custom
+ * `{ mass, stiffness, damping }` when none of them fit.
+ *
+ * Determinism holds despite the simulation: integration runs at a fixed
+ * internal timestep, so a spring produces identical frames at any frame rate
+ * and on any machine.
+ *
+ * @example
+ * Three springs chained — each starts where the last settled, and the whole
+ * sequence takes however long the physics takes.
+ * ```typescript
+ * import * as Physics from "effect-motion/Physics";
+ * import * as Scene from "effect-motion/Scene";
+ *
+ * const scene = Scene.make(function* () {
+ * 	const ball = yield* Scene.instantiate("Circle", { radius: 24 });
+ * 	yield* ball.pipe(
+ * 		Physics.springTo({ x: 430 }, "swing"),
+ * 		Physics.springTo({ x: 70 }, "bounce"),
+ * 		Physics.springTo({ x: 250, y: 70 }, "jump"),
+ * 	);
+ * });
+ * ```
+ */
+/**
+ * A spring's physical parameters — the knobs that decide how motion feels
+ * and, indirectly, how long it lasts.
+ *
+ * @remarks
+ * The three interact, so tune by feel rather than in isolation: heavier
+ * `mass` makes motion sluggish and prolongs it; higher `stiffness` pulls
+ * harder toward the target and speeds it up; higher `damping` bleeds off
+ * energy, trading overshoot and wobble for a quicker settle. Low damping
+ * with low stiffness is what produces a long ringing tail.
+ *
+ * Start from a preset in {@link springs} and adjust from there — the
+ * presets are the calibrated points in this space.
  */
 export interface Spring {
+    /** Inertia. Higher is heavier and slower to start and stop. */
     readonly mass: number;
+    /** Pull toward the target. Higher is snappier. */
     readonly stiffness: number;
+    /** Energy loss. Higher settles sooner with less overshoot; near 0 rings. */
     readonly damping: number;
+    /**
+     * Speed the motion already carries at frame one, for launching something
+     * that should feel struck or thrown rather than pulled.
+     *
+     * @defaultValue `0`
+     */
     readonly initialVelocity?: number;
 }
-/** fast, gently damped general-purpose spring */
+/**
+ * The spring used when a call names none: quick and only lightly damped, so
+ * it overshoots a little before settling.
+ */
 export declare const defaultSpring: Spring;
+/**
+ * The named spring presets, each a calibrated point in `{ mass, stiffness,
+ * damping }` space. Pass the NAME to any spring animator — it autocompletes.
+ *
+ * @remarks
+ * Durations below are measured for a 100px move at 60fps and scale with
+ * distance; a spring's length is emergent, so treat them as character, not
+ * contract:
+ *
+ * - `strike` — hardest and fastest, launched with initial velocity (~0.7s).
+ * - `jump` — a quick launched hop (~1.4s).
+ * - `smooth` — mild overshoot, unobtrusive (~2s).
+ * - `beat` — a small, tight pulse; the least overshoot of the set (~2.6s).
+ * - `swing` — a relaxed, pendulum-like arc (~3.5s).
+ * - `plop` — lands heavy and wobbles noticeably (~7s).
+ * - `bounce` — barely damped, so it rings for a LONG time: about 37 seconds
+ *   and 90 direction changes for a 100px move. Striking as a one-off accent,
+ *   but check the frame count before putting it in a timed sequence.
+ *
+ * @see {@link Spring} to define your own.
+ */
 export declare const springs: {
     readonly beat: {
         readonly mass: 0.13;
@@ -58,21 +140,73 @@ export declare const springs: {
         readonly damping: 1.88;
     };
 };
+/** The name of a built-in preset in {@link springs}. */
 export type SpringName = keyof typeof springs;
-/** a preset name (autocompleted) or a custom spring configuration */
+/**
+ * What the spring animators accept: a preset name (autocompleted at the call
+ * site) or a full {@link Spring} of your own.
+ */
 export type SpringInput = SpringName | Spring;
 export declare const resolve: (input: SpringInput) => Effect.Effect<Spring>;
-type HasPosition<Data extends Schema.Top> = {
-    readonly "~position": Entity.TraitLens<Data["Type"], Entity.Position>;
-};
 /**
- * Spring an instance to a position via its `~position` trait — the
- * durationless counterpart of `Motion.moveTo` (settles exactly, length
- * emerges from the physics). Dual:
- * `springTo(instance, to, springInput?, settleTolerance?)` or
- * `instance.pipe(springTo(to, springInput?, settleTolerance?))`.
+ * Spring an instance to a position — `Motion.moveTo` with momentum instead
+ * of a duration.
+ *
+ * @remarks
+ * The animation runs until the simulation settles, then lands exactly on
+ * `to`, so chaining springs is safe: each starts precisely where the last
+ * finished, with no accumulated drift. How long that takes depends on the
+ * spring AND the distance — a longer move rings longer.
+ *
+ * Because the length is emergent, a spring is awkward to synchronize
+ * against a fixed beat. When several things must finish together, either
+ * spring them inside a `Scene.all` and let the slowest govern, or use a
+ * duration-based tween with an elastic easing.
+ *
+ * Targets are partial, like `moveTo` — naming only `x` holds the other axes.
+ * Every axis is simulated by the same spring, so a diagonal move settles as
+ * one motion.
+ *
+ * @param to - Target position; omitted axes hold their current value.
+ * @param springInput - A preset name from {@link springs}, or a custom
+ *   {@link Spring}.
+ * @param settleTolerance - How close to the target (in both displacement
+ *   and velocity) counts as settled. Larger ends sooner and cuts the tail.
+ * @defaultValue `springInput` — {@link defaultSpring}; `settleTolerance` — `0.001`
+ * @returns The instance, so animators chain.
+ * @see {@link spring} to start from an explicit position.
+ *
+ * @example
+ * A struck-then-settling entrance, using two different presets.
+ * ```typescript
+ * yield* badge.pipe(
+ * 	Physics.springTo({ y: 120 }, "strike"),
+ * 	Physics.springTo({ x: 300 }, "smooth"),
+ * );
+ * ```
+ */
+export declare const springTo: (<Tag extends Entity.TagsWith<"position">>(to: Partial<Motion.Position>, springInput?: SpringInput, settleTolerance?: number) => <E = never, R = never>(instance: Instance.InstanceOrEffect<Tag, E, R>) => Effect.Effect<Instance.Instance<Tag>, E, R | Runner.Runner>) & (<Tag extends Entity.TagsWith<"position">, E = never, R = never>(instance: Instance.InstanceOrEffect<Tag, E, R>, to: Partial<Motion.Position>, springInput?: SpringInput, settleTolerance?: number) => Effect.Effect<Instance.Instance<Tag>, E, R | Runner.Runner>);
+/**
+ * Like {@link springTo}, but starting from an explicit position.
+ *
+ * @remarks
+ * The springy entrance: an instance declared at its resting place can still
+ * fly in from off-screen and settle, because the origin is stated rather
+ * than read from the entity. Both `from` and `to` are partial and fill
+ * missing axes from the current position.
+ *
+ * @param from - Starting position; omitted axes start at the current value.
+ * @param to - Target position; omitted axes hold their current value.
+ * @param springInput - A preset name from {@link springs}, or a custom
+ *   {@link Spring}.
+ * @param settleTolerance - How close counts as settled.
+ * @defaultValue `springInput` — {@link defaultSpring}; `settleTolerance` — `0.001`
+ * @returns The instance, so animators chain.
+ *
+ * @example
+ * Drop a card in from above and let it settle where it was declared.
+ * ```typescript
+ * yield* card.pipe(Physics.spring({ y: -200 }, { y: 150 }, "plop"));
+ * ```
  */
-export declare const springTo: (<Name extends string, Data extends Schema.Top, Traits extends Partial<Entity.EntityTraits<Data["Type"]>> & HasPosition<Data>>(to: Partial<Entity.Position>, springInput?: SpringInput, settleTolerance?: number) => <E = never, R = never>(instance: Instance.InstanceOrEffect<Name, Data, Traits, E, R>) => Effect.Effect<Instance.Instance<Name, Data, Traits>, E, R | Runner.Runner>) & (<Name extends string, Data extends Schema.Top, Traits extends Partial<Entity.EntityTraits<Data["Type"]>> & HasPosition<Data>, E = never, R = never>(instance: Instance.InstanceOrEffect<Name, Data, Traits, E, R>, to: Partial<Entity.Position>, springInput?: SpringInput, settleTolerance?: number) => Effect.Effect<Instance.Instance<Name, Data, Traits>, E, R | Runner.Runner>);
-/** Like `springTo`, but from an explicit position (partials filled from current). */
-export declare const spring: (<Name extends string, Data extends Schema.Top, Traits extends Partial<Entity.EntityTraits<Data["Type"]>> & HasPosition<Data>>(from: Partial<Entity.Position>, to: Partial<Entity.Position>, springInput?: SpringInput, settleTolerance?: number) => <E = never, R = never>(instance: Instance.InstanceOrEffect<Name, Data, Traits, E, R>) => Effect.Effect<Instance.Instance<Name, Data, Traits>, E, R | Runner.Runner>) & (<Name extends string, Data extends Schema.Top, Traits extends Partial<Entity.EntityTraits<Data["Type"]>> & HasPosition<Data>, E = never, R = never>(instance: Instance.InstanceOrEffect<Name, Data, Traits, E, R>, from: Partial<Entity.Position>, to: Partial<Entity.Position>, springInput?: SpringInput, settleTolerance?: number) => Effect.Effect<Instance.Instance<Name, Data, Traits>, E, R | Runner.Runner>);
-export {};
+export declare const spring: (<Tag extends Entity.TagsWith<"position">>(from: Partial<Motion.Position>, to: Partial<Motion.Position>, springInput?: SpringInput, settleTolerance?: number) => <E = never, R = never>(instance: Instance.InstanceOrEffect<Tag, E, R>) => Effect.Effect<Instance.Instance<Tag>, E, R | Runner.Runner>) & (<Tag extends Entity.TagsWith<"position">, E = never, R = never>(instance: Instance.InstanceOrEffect<Tag, E, R>, from: Partial<Motion.Position>, to: Partial<Motion.Position>, springInput?: SpringInput, settleTolerance?: number) => Effect.Effect<Instance.Instance<Tag>, E, R | Runner.Runner>);