effect-motion 0.4.0 → 0.5.0

package/dist/Instance.d.ts

@@ -1,16 +1,78 @@
 import * as Effect from "effect/Effect";
 import * as Pipeable from "effect/Pipeable";
-import type * as Schema from "effect/Schema";
-import type * as Entity from "./Entity.js";
-export declare const TypeId: "~motion/Instance";
-export interface Instance<Name extends string = string, Data extends Schema.Top = Schema.Top, Traits extends Partial<Entity.EntityTraits<Data["Type"]>> = {}> extends Pipeable.Pipeable {
-    readonly [TypeId]: typeof TypeId;
+import type { EntityByTag, EntityTag } from "./Entity.js";
+/**
+ * An Instance is a REFERENCE to a live entity in the runner tree: an id and
+ * the tag of what it is. It carries no entity data — the runner owns that —
+ * so it stays a tiny, pipeable handle that animator chains flow through.
+ */
+/**
+ * A handle to something living in a scene — what `Scene.instantiate` returns
+ * and what every animator takes.
+ *
+ * @remarks
+ * An instance holds no entity data of its own, only an id and a kind. The
+ * data lives in the scene and changes every frame; the handle stays valid
+ * throughout, which is why it can be captured once and animated repeatedly.
+ * To read the current values, use `Scene.data`.
+ *
+ * The `Tag` parameter is what makes animators statically safe: `fadeTo`
+ * accepts only instances whose entity actually has an `opacity`, so fading a
+ * Camera fails at compile time with a message naming the missing field
+ * rather than misbehaving at runtime.
+ *
+ * Instances are Pipeable — that is what lets `circle.pipe(moveTo(…),
+ * fadeTo(…))` read as one chain. A handle is NOT itself an Effect, so
+ * anything accepting one in Effect position lifts it with
+ * {@link flattenInstance} first.
+ *
+ * @typeParam Tag - Which entity this refers to, e.g. `"Circle"`.
+ */
+export interface Instance<Tag extends EntityTag = EntityTag> extends Pipeable.Pipeable {
+    readonly _tag: "Instance";
     readonly id: string;
-    readonly entity: Entity.Entity<Name, Data, Traits>;
+    readonly kind: Tag;
 }
-/** the Instance type of a given entity, traits included */
-export type Of<E extends Entity.AnyEntity> = E extends Entity.Entity<infer Name, infer Data, infer Traits> ? Instance<Name, Data, Traits> : never;
+/**
+ * Build an instance handle from an id and a kind.
+ *
+ * @remarks
+ * Internal plumbing — the scene runner calls this when creating entities.
+ * Author code gets handles from `Scene.instantiate` instead; constructing
+ * one by hand refers to an entity that may not exist.
+ */
+export declare const makeInstance: <Tag extends EntityTag>(id: string, kind: Tag) => Instance<Tag>;
+/**
+ * Whether `u` is an {@link Instance}.
+ *
+ * @remarks
+ * The dispatch behind every dual animator: `moveTo(circle, …)` and
+ * `circle.pipe(moveTo(…))` are told apart by testing the first argument
+ * with this, rather than by counting arguments — trailing optional
+ * parameters make arity ambiguous.
+ */
 export declare const isInstance: (u: unknown) => u is Instance;
-export declare const make: <Name extends string, Data extends Schema.Top, Traits extends Partial<Entity.EntityTraits<Data["Type"]>>>(entity: Entity.Entity<Name, Data, Traits>, id: string) => Instance<Name, Data, Traits>;
-export type InstanceOrEffect<Name extends string = string, Data extends Schema.Top = Schema.Top, Traits extends Partial<Entity.EntityTraits<Data["Type"]>> = {}, E = never, R = never> = Instance<Name, Data, Traits> | Effect.Effect<Instance<Name, Data, Traits>, E, R>;
-export declare const flatten: <Name extends string, Data extends Schema.Top, Traits extends Partial<Entity.EntityTraits<Data["Type"]>>, E = never, R = never>(instance: InstanceOrEffect<Name, Data, Traits, E, R>) => Effect.Effect<Instance<Name, Data, Traits>, E, R>;
+/**
+ * Whether `u` is an instance of one specific entity kind.
+ *
+ * @remarks
+ * Narrows to `Instance<Tag>`, so a heterogeneous list can be filtered down
+ * to the circles and then animated with circle-only fields.
+ *
+ * @param tag - The kind to test for, e.g. `"Circle"`.
+ * @param u - The value to test.
+ */
+export declare const isInstanceOf: <Tag extends EntityTag>(tag: Tag, u: unknown) => u is Instance<Tag>;
+/**
+ * An instance, or an un-yielded `instantiate` effect that produces one.
+ *
+ * @remarks
+ * Animators accept both, so a scene can animate straight off an
+ * `instantiate` call without binding it to a variable first — the create
+ * step and the first animation read as one expression.
+ */
+export type InstanceOrEffect<Tag extends EntityTag = EntityTag, E = never, R = never> = Instance<Tag> | Effect.Effect<Instance<Tag>, E, R>;
+/** Resolve an {@link InstanceOrEffect} to the instance itself. */
+export declare const flattenInstance: <Tag extends EntityTag, E = never, R = never>(instance: InstanceOrEffect<Tag, E, R>) => Effect.Effect<Instance<Tag>, E, R>;
+/** The entity data type a given instance handle refers to. */
+export type DataOf<I> = I extends Instance<infer Tag> ? EntityByTag<Tag> : never;

package/dist/Instance.js

@@ -1,18 +1,51 @@
 import * as Effect from "effect/Effect";
 import * as Pipeable from "effect/Pipeable";
-export const TypeId = "~motion/Instance";
-export const isInstance = (u) => typeof u === "object" && u !== null && TypeId in u;
-const Proto = {
-    [TypeId]: TypeId,
+/**
+ * Instances are Pipeable so animator chains read data-last:
+ * `circle.pipe(moveTo(...), fadeTo(...))`. That is the authored form in most
+ * scenes, so the protocol is load-bearing, not a convenience.
+ */
+const InstanceProto = {
+    _tag: "Instance",
     pipe() {
         // biome-ignore lint: lint/style/noArguments: Pipeable's variadic protocol
         return Pipeable.pipeArguments(this, arguments);
     },
 };
-export const make = (entity, id) => Object.assign(Object.create(Proto), { id, entity });
-export const flatten = (instance) => {
-    if (isInstance(instance)) {
-        return Effect.succeed(instance);
-    }
-    return instance;
-};
+/**
+ * Build an instance handle from an id and a kind.
+ *
+ * @remarks
+ * Internal plumbing — the scene runner calls this when creating entities.
+ * Author code gets handles from `Scene.instantiate` instead; constructing
+ * one by hand refers to an entity that may not exist.
+ */
+export const makeInstance = (id, kind) => Object.assign(Object.create(InstanceProto), { id, kind });
+/**
+ * Whether `u` is an {@link Instance}.
+ *
+ * @remarks
+ * The dispatch behind every dual animator: `moveTo(circle, …)` and
+ * `circle.pipe(moveTo(…))` are told apart by testing the first argument
+ * with this, rather than by counting arguments — trailing optional
+ * parameters make arity ambiguous.
+ */
+export const isInstance = (u) => typeof u === "object" &&
+    u !== null &&
+    "_tag" in u &&
+    u._tag === "Instance";
+/**
+ * Whether `u` is an instance of one specific entity kind.
+ *
+ * @remarks
+ * Narrows to `Instance<Tag>`, so a heterogeneous list can be filtered down
+ * to the circles and then animated with circle-only fields.
+ *
+ * @param tag - The kind to test for, e.g. `"Circle"`.
+ * @param u - The value to test.
+ */
+export const isInstanceOf = (tag, u) => isInstance(u) && u.kind === tag;
+/** Resolve an {@link InstanceOrEffect} to the instance itself. */
+export const flattenInstance = (instance) => isInstance(instance)
+    ? Effect.succeed(instance)
+    : instance;

package/dist/Motion.d.ts

@@ -1,6 +1,49 @@
+/**
+ * Duration-based animation: the animators that interpolate a value over a
+ * span of scene time, paced by an easing curve.
+ *
+ * The module is two layers over one engine:
+ *
+ * - **raw** — {@link tween} / {@link tweenTo} interpolate numeric fields BY
+ *   NAME (`radius`, `width`, `fontSize`), whatever the entity's schema
+ *   declares.
+ * - **semantic** — {@link move} / {@link moveTo} and {@link fade} /
+ *   {@link fadeTo} speak in concepts rather than field names, and are what
+ *   you should reach for when one exists: geometry is relative to
+ *   `position`, so moving a Line translates both endpoints and moving a
+ *   Group carries its whole subtree, with no per-entity handling.
+ *
+ * Every animator ships as a base/To pair — `verbTo` starts from the
+ * instance's CURRENT value, `verb` takes an explicit origin — and each is a
+ * dual, callable data-first (`moveTo(circle, …)`) or pipeable
+ * (`circle.pipe(moveTo(…))`). They resolve with the instance, so chains
+ * compose. For durationless motion whose length emerges from a simulation,
+ * see `Physics`.
+ *
+ * Timing is frame-exact: a `duration` is converted to whole frames at the
+ * runner's frame rate, and the last frame receives exactly the target value
+ * for any easing with f(1) = 1 — a tween never lands "almost" on its
+ * target. A zero-length duration still consumes one frame.
+ *
+ * @example
+ * Chain a raw tween into two semantic animators. `1 second` at 30fps is 30
+ * animation frames, and `radius`/`position`/`opacity` all land exactly.
+ * ```typescript
+ * import * as Motion from "effect-motion/Motion";
+ * import * as Scene from "effect-motion/Scene";
+ *
+ * const scene = Scene.make(function* () {
+ * 	const dot = yield* Scene.instantiate("Circle", { radius: 4 });
+ * 	yield* dot.pipe(
+ * 		Motion.tweenTo({ radius: 40 }, "1 second", "easeOutCubic"),
+ * 		Motion.moveTo({ x: 300 }, "1 second"),
+ * 		Motion.fadeTo(0, "500 millis"),
+ * 	);
+ * });
+ * ```
+ */
 import type * as Duration from "effect/Duration";
 import * as Effect from "effect/Effect";
-import type * as Schema from "effect/Schema";
 import * as Color from "./Color.js";
 import * as Entity from "./Entity.js";
 import * as Instance from "./Instance.js";
@@ -16,76 +59,308 @@ export type InterpolableOnly<T> = Pick<T, InterpolableKeys<T>>;
 type InterpolableOrInterpolator<T> = {
     [K in keyof T]-?: NonNullable<T[K]> extends number ? number : NonNullable<T[K]> extends Color.Color ? Color.Color | ColorInterpolator : never;
 };
-/** target props, or an updater computing them from the current data */
-export type Target<Data extends Schema.Top> = Partial<InterpolableOrInterpolator<Data["Type"]>> | ((data: Data["Type"]) => Partial<InterpolableOrInterpolator<Data["Type"]>>);
-export declare const resolveTarget: <Data extends Schema.Top>(target: Target<Data>, current: Data["Type"]) => Record<string, number>;
+/**
+ * What {@link tween} / {@link tweenTo} accept as an endpoint: the fields to
+ * animate and their values.
+ *
+ * @remarks
+ * Two forms. A plain object states targets literally. A function receives
+ * the entity's data at animation start and computes them, which is how you
+ * express a target relative to where the entity already is (`data.radius *
+ * 2`) without reading it out in a separate step.
+ *
+ * Only numeric and Color fields of the entity are addressable — those are
+ * the ones that can be interpolated.
+ *
+ * @typeParam Tag - The entity tag, which determines the available fields.
+ */
+export type Target<Tag extends Entity.EntityTag> = Partial<InterpolableOrInterpolator<Entity.EntityByTag<Tag>>> | ((data: Entity.EntityByTag<Tag>) => Partial<InterpolableOrInterpolator<Entity.EntityByTag<Tag>>>);
+export declare const resolveTarget: <Tag extends Entity.EntityTag>(target: Target<Tag>, current: Entity.EntityByTag<Tag>) => Record<string, number>;
 export declare const startValues: (current: unknown, target: Record<string, number>, explicitFrom: Record<string, number>) => Record<string, number>;
 /**
- * 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 declare const tweenTo: (<Name extends string, Data extends Schema.Top, Traits extends Partial<Entity.EntityTraits<Data["Type"]>>>(to: Target<Data>, duration: Duration.Input, timing?: Timing.TimingInput) => <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"]>>, E = never, R = never>(instance: Instance.InstanceOrEffect<Name, Data, Traits, E, R>, to: Target<Data>, duration: Duration.Input, timing?: Timing.TimingInput) => Effect.Effect<Instance.Instance<Name, Data, Traits>, E, R | Runner.Runner>);
+export declare const tweenTo: (<Tag extends Entity.EntityTag>(to: Target<Tag>, duration: Duration.Input, timing?: Timing.TimingInput) => <E = never, R = never>(instance: Instance.InstanceOrEffect<Tag, E, R>) => Effect.Effect<Instance.Instance<Tag>, E, R | Runner.Runner>) & (<Tag extends Entity.EntityTag, E = never, R = never>(instance: Instance.InstanceOrEffect<Tag, E, R>, to: Target<Tag>, duration: Duration.Input, timing?: Timing.TimingInput) => Effect.Effect<Instance.Instance<Tag>, E, R | Runner.Runner>);
 /**
- * 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 declare const drive: (<Name extends string, Data extends Schema.Top, Traits extends Partial<Entity.EntityTraits<Data["Type"]>>>(duration: Duration.Input, timing: Timing.TimingInput, fn: (t: number, data: Data["Type"]) => Data["Type"]) => <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"]>>, E = never, R = never>(instance: Instance.InstanceOrEffect<Name, Data, Traits, E, R>, duration: Duration.Input, timing: Timing.TimingInput, fn: (t: number, data: Data["Type"]) => Data["Type"]) => Effect.Effect<Instance.Instance<Name, Data, Traits>, E, R | Runner.Runner>);
+export declare const drive: (<Tag extends Entity.EntityTag>(duration: Duration.Input, timing: Timing.TimingInput, fn: (t: number, data: Entity.EntityByTag<Tag>) => Entity.EntityByTag<Tag>) => <E = never, R = never>(instance: Instance.InstanceOrEffect<Tag, E, R>) => Effect.Effect<Instance.Instance<Tag>, E, R | Runner.Runner>) & (<Tag extends Entity.EntityTag, E = never, R = never>(instance: Instance.InstanceOrEffect<Tag, E, R>, duration: Duration.Input, timing: Timing.TimingInput, fn: (t: number, data: Entity.EntityByTag<Tag>) => Entity.EntityByTag<Tag>) => Effect.Effect<Instance.Instance<Tag>, E, R | Runner.Runner>);
 /**
- * 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 declare const tween: (<Name extends string, Data extends Schema.Top, Traits extends Partial<Entity.EntityTraits<Data["Type"]>>>(from: Target<Data>, to: Target<Data>, duration: Duration.Input, timing?: Timing.TimingInput) => <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"]>>, E = never, R = never>(instance: Instance.InstanceOrEffect<Name, Data, Traits, E, R>, from: Target<Data>, to: Target<Data>, duration: Duration.Input, timing?: Timing.TimingInput) => Effect.Effect<Instance.Instance<Name, Data, Traits>, E, R | Runner.Runner>);
-type HasPosition<Data extends Schema.Top> = {
-    readonly "~position": Entity.TraitLens<Data["Type"], Entity.Position>;
-};
-type HasOpacity<Data extends Schema.Top> = {
-    readonly "~opacity": Entity.TraitLens<Data["Type"], number>;
+export declare const tween: (<Tag extends Entity.EntityTag>(from: Target<Tag>, to: Target<Tag>, duration: Duration.Input, timing?: Timing.TimingInput) => <E = never, R = never>(instance: Instance.InstanceOrEffect<Tag, E, R>) => Effect.Effect<Instance.Instance<Tag>, E, R | Runner.Runner>) & (<Tag extends Entity.EntityTag, E = never, R = never>(instance: Instance.InstanceOrEffect<Tag, E, R>, from: Target<Tag>, to: Target<Tag>, duration: Duration.Input, timing?: Timing.TimingInput) => Effect.Effect<Instance.Instance<Tag>, E, R | Runner.Runner>);
+/** a 3D position as the semantic animators speak it */
+export type Position = {
+    readonly x: number;
+    readonly y: number;
+    readonly z: number;
 };
+/** tags whose entity carries a position: every one of them */
+type Positionable = Entity.TagsWith<"position">;
+/** tags whose entity carries opacity: every paintable one (not Camera) */
+type Fadeable = Entity.TagsWith<"opacity">;
+/**
+ * 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 declare const moveTo: (<Tag extends Positionable>(to: Partial<Position>, duration: Duration.Input, timing?: Timing.TimingInput) => <E = never, R = never>(instance: Instance.InstanceOrEffect<Tag, E, R>) => Effect.Effect<Instance.Instance<Tag>, E, R | Runner.Runner>) & (<Tag extends Positionable, E = never, R = never>(instance: Instance.InstanceOrEffect<Tag, E, R>, to: Partial<Position>, duration: Duration.Input, timing?: Timing.TimingInput) => Effect.Effect<Instance.Instance<Tag>, E, R | Runner.Runner>);
+/**
+ * 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 declare const move: (<Tag extends Positionable>(from: Partial<Position>, to: Partial<Position>, duration: Duration.Input, timing?: Timing.TimingInput) => <E = never, R = never>(instance: Instance.InstanceOrEffect<Tag, E, R>) => Effect.Effect<Instance.Instance<Tag>, E, R | Runner.Runner>) & (<Tag extends Positionable, E = never, R = never>(instance: Instance.InstanceOrEffect<Tag, E, R>, from: Partial<Position>, to: Partial<Position>, duration: Duration.Input, timing?: Timing.TimingInput) => Effect.Effect<Instance.Instance<Tag>, E, R | Runner.Runner>);
 /**
- * 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?))`.
+ * 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 declare const moveTo: (<Name extends string, Data extends Schema.Top, Traits extends Partial<Entity.EntityTraits<Data["Type"]>> & HasPosition<Data>>(to: Partial<Entity.Position>, duration: Duration.Input, timing?: Timing.TimingInput) => <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>, duration: Duration.Input, timing?: Timing.TimingInput) => Effect.Effect<Instance.Instance<Name, Data, Traits>, E, R | Runner.Runner>);
-/** Like `moveTo`, but from an explicit position (partials filled from current). */
-export declare const move: (<Name extends string, Data extends Schema.Top, Traits extends Partial<Entity.EntityTraits<Data["Type"]>> & HasPosition<Data>>(from: Partial<Entity.Position>, to: Partial<Entity.Position>, duration: Duration.Input, timing?: Timing.TimingInput) => <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>, duration: Duration.Input, timing?: Timing.TimingInput) => Effect.Effect<Instance.Instance<Name, Data, Traits>, E, R | Runner.Runner>);
+export declare const fadeTo: (<Tag extends Fadeable>(to: number, duration: Duration.Input, timing?: Timing.TimingInput) => <E = never, R = never>(instance: Instance.InstanceOrEffect<Tag, E, R>) => Effect.Effect<Instance.Instance<Tag>, E, R | Runner.Runner>) & (<Tag extends Fadeable, E = never, R = never>(instance: Instance.InstanceOrEffect<Tag, E, R>, to: number, duration: Duration.Input, timing?: Timing.TimingInput) => Effect.Effect<Instance.Instance<Tag>, E, R | Runner.Runner>);
 /**
- * Fade an instance's opacity via its `~opacity` trait. Dual:
- * `fadeTo(instance, opacity, duration, timing?)` or
- * `instance.pipe(fadeTo(opacity, duration, timing?))`.
+ * 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 declare const fadeTo: (<Name extends string, Data extends Schema.Top, Traits extends Partial<Entity.EntityTraits<Data["Type"]>> & HasOpacity<Data>>(to: number, duration: Duration.Input, timing?: Timing.TimingInput) => <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"]>> & HasOpacity<Data>, E = never, R = never>(instance: Instance.InstanceOrEffect<Name, Data, Traits, E, R>, to: number, duration: Duration.Input, timing?: Timing.TimingInput) => Effect.Effect<Instance.Instance<Name, Data, Traits>, E, R | Runner.Runner>);
-/** Like `fadeTo`, but from an explicit opacity. */
-export declare const fade: (<Name extends string, Data extends Schema.Top, Traits extends Partial<Entity.EntityTraits<Data["Type"]>> & HasOpacity<Data>>(from: number, to: number, duration: Duration.Input, timing?: Timing.TimingInput) => <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"]>> & HasOpacity<Data>, E = never, R = never>(instance: Instance.InstanceOrEffect<Name, Data, Traits, E, R>, from: number, to: number, duration: Duration.Input, timing?: Timing.TimingInput) => Effect.Effect<Instance.Instance<Name, Data, Traits>, E, R | Runner.Runner>);
+export declare const fade: (<Tag extends Fadeable>(from: number, to: number, duration: Duration.Input, timing?: Timing.TimingInput) => <E = never, R = never>(instance: Instance.InstanceOrEffect<Tag, E, R>) => Effect.Effect<Instance.Instance<Tag>, E, R | Runner.Runner>) & (<Tag extends Fadeable, E = never, R = never>(instance: Instance.InstanceOrEffect<Tag, E, R>, from: number, to: number, duration: Duration.Input, timing?: Timing.TimingInput) => Effect.Effect<Instance.Instance<Tag>, E, R | Runner.Runner>);
 /**
- * `Motion.wait(duration)` is both an Effect and a pipe step: yield it
- * directly, or place it between chained animations, where it holds the
- * scene AFTER the previous step and passes that step's result through.
+ * The dual nature of {@link wait}: an Effect you can yield, and a function
+ * you can drop into a `pipe` chain.
+ *
+ * @remarks
+ * Being callable is what lets a hold sit BETWEEN two animators in the same
+ * chain — it wraps the preceding step, waits after it completes, and passes
+ * that step's value (the instance) through untouched, so the chain keeps
+ * flowing.
  */
 export interface Wait extends Effect.Effect<void, never, Runner.Runner> {
-    <A, E, R>(effect: Effect.Effect<A, E, R>): Effect.Effect<A, E, R | Runner.Runner>;
+    <Self extends Effect.Effect<any, any, any> | Instance.Instance>(self: Self): Self extends Instance.Instance ? Effect.Effect<Self, never, Runner.Runner> : Self extends Effect.Effect<infer A, infer E, infer R> ? Effect.Effect<A, E, R | Runner.Runner> : never;
 }
 /**
- * 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 declare const wait: (duration: Duration.Input) => Wait;
 export {};