effect-motion 0.4.0 → 0.6.0

package/README.md

@@ -1,15 +1,15 @@
 # effect-motion
 
-Deterministic, frame-exact motion graphics in code, composed with [Effect](https://effect.website).
+Frame-exact motion graphics in code, composed with [Effect](https://effect.website).
 
-A scene is an Effect generator program: instantiate entities, then tween or spring their properties, composing motions sequentially or in parallel. Scenes are **deterministic** — seeded randomness and a frame-locked clock make every run byte-identical — and **finite**, which is what lets a scene be scrubbed and replayed like a video.
+A scene is an Effect generator program: instantiate entities, then tween or spring their properties, composing motions sequentially or in parallel. Scenes are **frame-exact** — animation is counted in whole frames at the scene's frame rate, never read from a wall clock — and **finite**, which is what lets a scene be scrubbed and replayed like a video.
 
 ## Install
 
 `effect` is a peer dependency — install it alongside:
 
 ```bash
-pnpm add effect-motion effect
+bun add effect-motion effect
 ```
 
 ## Write a scene

package/dist/Camera.d.ts

@@ -1,14 +1,18 @@
-import * as Schema from "effect/Schema";
-import * as Entity from "./Entity.js";
-import * as Projection from "./Projection.js";
+import { Effect } from "effect";
+import * as Duration from "effect/Duration";
+import * as Instance from "./Instance.js";
+import * as Motion from "./Motion.js";
+import type * as Projection from "./Projection.js";
+import * as Runner from "./Runner.js";
+import * as Timing from "./Timing.js";
 /**
  * The camera is view state, not a shape — it is never registered with a sink
  * and never drawn. It exists as an ordinary Instance so the existing
  * animators drive it for free: `camera.pipe(moveTo({ z: -800 }))`,
  * `tween("rotY", ...)`, `spring`, `Scene.fork`, etc.
  *
- * `~position` (now x/y/z) is the camera's world position; `rotX/rotY/rotZ`
- * are its Euler orientation; `focalLength` sets the field of view. At rest
+ * `position` is the camera's world position, `rotation` its Euler
+ * orientation, and `focalLength` sets the field of view. At rest
  * the camera sits a focal-length back on +z looking down world -z, so a
  * world point at z=0 projects to plain-2D screen coordinates — see
  * `Projection.ts`. The sink reads these off `FrameMeta.camera` and projects
@@ -22,50 +26,183 @@ import * as Projection from "./Projection.js";
  * instance, so by the time animators or the renderer read the data they are
  * always concrete.
  */
-declare const fields: {
-    x: Schema.withConstructorDefault<Schema.Number>;
-    y: Schema.withConstructorDefault<Schema.Number>;
-    z: Schema.withConstructorDefault<Schema.Number>;
-    rotX: Schema.withConstructorDefault<Schema.Number>;
-    rotY: Schema.withConstructorDefault<Schema.Number>;
-    rotZ: Schema.withConstructorDefault<Schema.Number>;
-    focalLength: Schema.withConstructorDefault<Schema.Number>;
-    focusDistance: Schema.withConstructorDefault<Schema.Number>;
-    aperture: Schema.withConstructorDefault<Schema.Number>;
-    poiX: Schema.optionalKey<Schema.Number>;
-    poiY: Schema.optionalKey<Schema.Number>;
-    poiZ: Schema.optionalKey<Schema.Number>;
-};
-type CameraData = Schema.Struct<typeof fields>["Type"];
-export declare const Camera: Entity.Entity<"Camera", Schema.Struct<{
-    x: Schema.withConstructorDefault<Schema.Number>;
-    y: Schema.withConstructorDefault<Schema.Number>;
-    z: Schema.withConstructorDefault<Schema.Number>;
-    rotX: Schema.withConstructorDefault<Schema.Number>;
-    rotY: Schema.withConstructorDefault<Schema.Number>;
-    rotZ: Schema.withConstructorDefault<Schema.Number>;
-    focalLength: Schema.withConstructorDefault<Schema.Number>;
-    focusDistance: Schema.withConstructorDefault<Schema.Number>;
-    aperture: Schema.withConstructorDefault<Schema.Number>;
-    poiX: Schema.optionalKey<Schema.Number>;
-    poiY: Schema.optionalKey<Schema.Number>;
-    poiZ: Schema.optionalKey<Schema.Number>;
-}>, {
-    readonly "~position": {
-        get: (data: CameraData) => {
-            x: number;
-            y: number;
-            z: number;
-        };
-        set: (data: CameraData, value: Entity.Position) => CameraData;
-    };
-}>;
+/** the camera view as a frame carries it */
+export type CameraState = Projection.CameraView & Projection.PointOfInterest;
 /**
- * The identity view for a comp of the given width: resting camera, no
- * rotation, the width-relative default focal length (AE's 50mm equivalent).
- * Projects z=0 content to its plain-2D screen position at scale 1.
+ * What the camera helpers accept as something to aim at.
+ *
+ * @remarks
+ * An instance is read LIVE each frame, so aiming tracks it as it moves — the
+ * usual case. A plain position is fixed, for aiming at a spot where no
+ * entity exists.
  */
-export declare const identity: (width: number) => CameraState;
-/** The camera view carried on each frame (POI rides along when set). */
-export type CameraState = Projection.CameraView & Projection.PointOfInterest;
+export type CameraTarget = Instance.Instance | Effect.Effect<Instance.Instance, never, Runner.Runner> | Partial<Motion.Position>;
+type CamOrEffect<E = never, R = Runner.Runner> = Instance.InstanceOrEffect<"Camera", E, R>;
+type CamInstance = Instance.Instance<"Camera">;
+type CamEffect = Effect.Effect<CamInstance, never, Runner.Runner>;
+/**
+ * Point the camera at something.
+ *
+ * @remarks
+ * Aiming is expressed as a point of interest rather than as rotation
+ * angles, which is what makes it composable: the target can be a live
+ * instance, and the camera keeps facing it as it moves. There is no
+ * `lookAtTo` — the verb already names its target — so an optional
+ * `duration` selects between the two behaviors:
+ *
+ * - **Omitted** — aim snaps this frame. Use it to establish the shot before
+ *   anything moves.
+ * - **Given** — the aim eases over that time as a RETARGETED tween: each
+ *   frame interpolates toward the target's current position, so it converges
+ *   exactly onto a moving target with no snap at the end.
+ *
+ * Setting a point of interest is also the prerequisite for
+ * {@link orbitTo} and {@link dollyTo}, which are both defined relative to it.
+ *
+ * @param target - An instance to track, or a fixed world position.
+ * @param duration - Omit to snap; give a time to ease the re-aim.
+ * @param timing - An easing name or function.
+ * @param offset - Shifts the aim relative to the target, e.g. slightly above.
+ * @defaultValue `timing` — `"linear"`
+ * @returns The camera, so animators chain.
+ *
+ * @example
+ * Snap to establish, then ease across to a second subject.
+ * ```typescript
+ * const camera = yield* Scene.camera;
+ * yield* camera.pipe(Camera.lookAt(hero));
+ * yield* camera.pipe(Camera.lookAt(villain, "1 second", "easeInOutCubic"));
+ * ```
+ */
+export declare const lookAt: ((target: CameraTarget, duration?: Duration.Input, timing?: Timing.TimingInput, offset?: Partial<Motion.Position>) => (cam: CamOrEffect) => CamEffect) & ((cam: CamOrEffect, target: CameraTarget, duration?: Duration.Input, timing?: Timing.TimingInput, offset?: Partial<Motion.Position>) => CamEffect);
+/**
+ * Keep the camera locked onto a moving target for `duration`.
+ *
+ * @remarks
+ * Where {@link lookAt} with a duration EASES toward a target and stops,
+ * `follow` holds the aim on it: every frame copies the target's position, so
+ * the subject stays pinned while it moves. Run it concurrently with the
+ * subject's own animation — typically inside `Scene.all` or a `Scene.fork`.
+ *
+ * There is no timing parameter, because tracking is a hard per-frame copy
+ * rather than an interpolation. For a lagging, weighted camera, animate the
+ * point of interest with a spring instead.
+ *
+ * Ordering note: within a frame, branches run in the order they were forked.
+ * A follow forked BEFORE its target's animator reads the previous frame's
+ * position — a deterministic one-frame trail, not a bug.
+ *
+ * @param target - An instance to track, or a fixed world position.
+ * @param duration - How long to keep tracking.
+ * @param offset - Shifts the aim relative to the target.
+ * @returns The camera, so animators chain.
+ *
+ * @example
+ * Track the runner for the two seconds it is crossing frame.
+ * ```typescript
+ * yield* Scene.all([
+ * 	runner.pipe(Motion.moveTo({ x: 900 }, "2 seconds")),
+ * 	camera.pipe(Camera.follow(runner, "2 seconds")),
+ * ]);
+ * ```
+ */
+export declare const follow: ((target: CameraTarget, duration: Duration.Input, offset?: Partial<Motion.Position>) => (cam: CamOrEffect) => CamEffect) & ((cam: CamOrEffect, target: CameraTarget, duration: Duration.Input, offset?: Partial<Motion.Position>) => CamEffect);
+/**
+ * Swing the camera around its point of interest, like a turntable.
+ *
+ * @remarks
+ * The camera travels an arc at a fixed radius and height while continuing to
+ * face the subject — the standard "orbit the product" move. Only the
+ * position is animated; the aim follows from the point of interest, so there
+ * is no orientation math to get wrong.
+ *
+ * `azimuth` is an ABSOLUTE angle in radians about the world-Y axis through
+ * the point of interest, where 0 is directly in front (+z of it). A full
+ * turn is `Math.PI * 2`; the sign chooses direction.
+ *
+ * Requires a point of interest — call {@link lookAt} first, or this fails
+ * loudly telling you so.
+ *
+ * @param azimuth - Target angle in radians; 0 is directly in front.
+ * @param duration - How long, in scene time.
+ * @param timing - An easing name or function.
+ * @defaultValue `timing` — `"linear"`
+ * @returns The camera, so animators chain.
+ * @see {@link orbit} to start from an explicit angle.
+ *
+ * @example
+ * A quarter turn around a subject.
+ * ```typescript
+ * yield* camera.pipe(
+ * 	Camera.lookAt(subject),
+ * 	Camera.orbitTo(Math.PI / 2, "2 seconds", "easeInOutCubic"),
+ * );
+ * ```
+ */
+export declare const orbitTo: ((azimuth: number, duration: Duration.Input, timing?: Timing.TimingInput) => (cam: CamOrEffect) => CamEffect) & ((cam: CamOrEffect, azimuth: number, duration: Duration.Input, timing?: Timing.TimingInput) => CamEffect);
+/**
+ * Like {@link orbitTo}, but starting from an explicit azimuth.
+ *
+ * @remarks
+ * Stating both ends is what makes a full revolution expressible: `orbit(0,
+ * Math.PI * 2, …)` sweeps all the way around, whereas `orbitTo(Math.PI * 2)`
+ * from a resting camera would already be at its target and not move.
+ *
+ * @param from - Starting angle in radians.
+ * @param to - Target angle in radians.
+ * @param duration - How long, in scene time.
+ * @param timing - An easing name or function.
+ * @returns The camera, so animators chain.
+ *
+ * @example
+ * One full revolution.
+ * ```typescript
+ * yield* camera.pipe(Camera.orbit(0, Math.PI * 2, "4 seconds"));
+ * ```
+ */
+export declare const orbit: ((from: number, to: number, duration: Duration.Input, timing?: Timing.TimingInput) => (cam: CamOrEffect) => CamEffect) & ((cam: CamOrEffect, from: number, to: number, duration: Duration.Input, timing?: Timing.TimingInput) => CamEffect);
+/**
+ * Move the camera toward or away from its point of interest along the view
+ * axis.
+ *
+ * @remarks
+ * A push-in or pull-back that keeps the subject centered and the aim
+ * unchanged — only the distance changes. Distinct from tweening the camera's
+ * `z`, which moves along the WORLD axis and would slide the subject off
+ * center once the camera is aimed obliquely.
+ *
+ * Requires a point of interest — call {@link lookAt} first.
+ *
+ * @param distance - Target distance from the point of interest; smaller is
+ *   closer.
+ * @param duration - How long, in scene time.
+ * @param timing - An easing name or function.
+ * @defaultValue `timing` — `"linear"`
+ * @returns The camera, so animators chain.
+ * @see {@link dolly} to start from an explicit distance.
+ *
+ * @example
+ * Push in on a subject.
+ * ```typescript
+ * yield* camera.pipe(
+ * 	Camera.lookAt(subject),
+ * 	Camera.dollyTo(300, "1500 millis", "easeInOutCubic"),
+ * );
+ * ```
+ */
+export declare const dollyTo: ((distance: number, duration: Duration.Input, timing?: Timing.TimingInput) => (cam: CamOrEffect) => CamEffect) & ((cam: CamOrEffect, distance: number, duration: Duration.Input, timing?: Timing.TimingInput) => CamEffect);
+/**
+ * Like {@link dollyTo}, but starting from an explicit distance.
+ *
+ * @remarks
+ * For a push-in that begins further out than the camera currently sits —
+ * the move starts at `from` regardless of where the camera was left.
+ *
+ * @param from - Starting distance from the point of interest.
+ * @param to - Target distance.
+ * @param duration - How long, in scene time.
+ * @param timing - An easing name or function.
+ * @returns The camera, so animators chain.
+ */
+export declare const dolly: ((from: number, to: number, duration: Duration.Input, timing?: Timing.TimingInput) => (cam: CamOrEffect) => CamEffect) & ((cam: CamOrEffect, from: number, to: number, duration: Duration.Input, timing?: Timing.TimingInput) => CamEffect);
 export {};