effect-motion 0.2.0 → 0.3.1

package/dist/Camera.d.ts

@@ -1,49 +1,71 @@
-import type * as Schema from "effect/Schema";
-import * as Entity from "./Entity";
+import * as Schema from "effect/Schema";
+import * as Entity from "./Entity.js";
+import * as Projection from "./Projection.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({ x: 400 }))`,
- * `tween("zoom", ...)`, `spring`, `Scene.fork`, etc.
+ * 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` (x/y) is the pan in world units; `zoom` is a uniform scale
- * (1 = identity). The sink reads these off `FrameMeta.camera` and applies
- * them per top-level layer, scaled by each layer's `depth` — instance data
- * stays in world coordinates, so determinism and `moveTo` semantics are
- * untouched by the camera.
+ * `~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
+ * 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
+ * every instance through them; instance data stays in world coordinates, so
+ * determinism and `moveTo` semantics are untouched by the camera.
+ *
+ * `z` and `focalLength` have no static schema default: the right resting
+ * values are width-relative (After Effects' 50mm-equivalent — see
+ * `Projection.defaultFocalLength`), and only the Runner knows the scene
+ * width. The Runner fills both at instantiate time for every Camera
+ * 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>;
-    zoom: 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>;
-    zoom: 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;
     };
-}, {
-    readonly x?: number;
-    readonly y?: number;
-    readonly zoom?: number;
 }>;
-/** The identity view: no pan, no zoom. */
-export declare const IDENTITY: {
-    readonly x: 0;
-    readonly y: 0;
-    readonly zoom: 1;
-};
-export interface CameraState {
-    readonly x: number;
-    readonly y: number;
-    readonly zoom: number;
-}
+/**
+ * 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.
+ */
+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 {};

package/dist/Camera.js

@@ -1,33 +1,85 @@
-import * as Entity from "./Entity";
-import * as Shape2D from "./shapes/Shape2D";
+import { Effect } from "effect";
+import * as Schema from "effect/Schema";
+import * as Entity from "./Entity.js";
+import * as Projection from "./Projection.js";
+import * as Shape2D from "./shapes/Shape2D.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({ x: 400 }))`,
- * `tween("zoom", ...)`, `spring`, `Scene.fork`, etc.
+ * 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` (x/y) is the pan in world units; `zoom` is a uniform scale
- * (1 = identity). The sink reads these off `FrameMeta.camera` and applies
- * them per top-level layer, scaled by each layer's `depth` — instance data
- * stays in world coordinates, so determinism and `moveTo` semantics are
- * untouched by the camera.
+ * `~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
+ * 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
+ * every instance through them; instance data stays in world coordinates, so
+ * determinism and `moveTo` semantics are untouched by the camera.
+ *
+ * `z` and `focalLength` have no static schema default: the right resting
+ * values are width-relative (After Effects' 50mm-equivalent — see
+ * `Projection.defaultFocalLength`), and only the Runner knows the scene
+ * width. The Runner fills both at instantiate time for every Camera
+ * instance, so by the time animators or the renderer read the data they are
+ * always concrete.
  */
 const fields = {
-    ...Shape2D.position,
-    zoom: Shape2D.defaultedNumber(1),
+    x: Shape2D.defaultedNumber(0),
+    y: Shape2D.defaultedNumber(0),
+    z: Schema.Number.pipe(Schema.withConstructorDefault(Effect.succeed(0))),
+    rotX: Shape2D.defaultedNumber(0),
+    rotY: Shape2D.defaultedNumber(0),
+    rotZ: Shape2D.defaultedNumber(0),
+    focalLength: Schema.Number.pipe(Schema.withConstructorDefault(Effect.succeed(0))),
+    // depth of field: view-space distance to the sharp plane, and blur
+    // strength. Like z/focalLength, focusDistance's right default is
+    // width-relative (the resting distance, so z=0 is in focus) — the Runner
+    // fills it. aperture 0 = pinhole = DoF off (explicit opt-in).
+    focusDistance: Schema.Number.pipe(Schema.withConstructorDefault(Effect.succeed(0))),
+    aperture: Shape2D.defaultedNumber(0),
+    // Optional point of interest (world coordinates): when present the camera
+    // auto-orients toward it and explicit Euler composes AFTER the aim (the
+    // AE two-node model — see Projection.resolveCamera). Flat numeric fields
+    // so tween/spring drive the aim like any other field. NOT Runner-filled:
+    // absent = today's one-node camera, byte-identical (explicit opt-in).
+    poiX: Schema.optionalKey(Schema.Number),
+    poiY: Schema.optionalKey(Schema.Number),
+    poiZ: Schema.optionalKey(Schema.Number),
 };
 export const Camera = Entity.make("Camera", fields, {
-    // only ~position: zoom is a raw numeric field, animated via tween.
-    // Inlined (not positionLens()) so the data type flows into the lens —
-    // the generic helper needs a second trait present to infer it.
+    // x/y/z is the camera position; rotation + focalLength are raw numeric
+    // fields animated via tween. Inlined (not positionLens()) so the data
+    // type flows into the lens.
     "~position": {
-        get: (data) => ({ x: data.x, y: data.y }),
+        // z is filled by the Runner at instantiate; the ?? 0 is unreachable,
+        // it only satisfies the optional schema type
+        get: (data) => ({ x: data.x, y: data.y, z: data.z ?? 0 }),
         set: (data, value) => ({
             ...data,
             x: value.x,
             y: value.y,
+            z: value.z,
         }),
     },
 });
-/** The identity view: no pan, no zoom. */
-export const IDENTITY = { x: 0, y: 0, zoom: 1 };
+/**
+ * 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.
+ */
+export const identity = (width) => {
+    const focalLength = Projection.defaultFocalLength(width);
+    return {
+        x: 0,
+        y: 0,
+        z: Projection.defaultCameraZ(focalLength),
+        rotX: 0,
+        rotY: 0,
+        rotZ: 0,
+        focalLength,
+        // the z=0 plane in focus, no depth of field
+        focusDistance: Projection.defaultCameraZ(focalLength),
+        aperture: 0,
+    };
+};

package/dist/CameraHelpers.d.ts

@@ -0,0 +1,70 @@
+import * as Duration from "effect/Duration";
+import * as Effect from "effect/Effect";
+import type { Camera } from "./Camera.js";
+import * as Entity from "./Entity.js";
+import * as Instance from "./Instance.js";
+import * as Runner from "./Runner.js";
+import * as Timing from "./Timing.js";
+/**
+ * The public Camera surface: the entity/identity from Camera.js plus the
+ * directing helpers. This module (not Camera.ts) is what index exports as
+ * the `Camera` namespace — Runner/Renderer import the schema file
+ * directly, so helpers can depend on Motion/Scene without an import
+ * cycle.
+ *
+ * Naming rule (recorded in the camera-poi-helpers change): verbs that
+ * name their target (`lookAt`, `follow`) have no base/To pair — an
+ * optional duration selects instant vs eased. Value-animating helpers
+ * (`orbit`/`orbitTo`, `dolly`/`dollyTo`) keep the pair, exactly like
+ * `move`/`moveTo`.
+ */
+export { Camera, identity } from "./Camera.js";
+export type { CameraState } from "./Camera.js";
+type AnyInstance = Instance.Instance<any, any, any>;
+/**
+ * A helper target: an Instance (position read live each frame), an Effect
+ * resolving to one (resolved once at helper start, then read live), or a
+ * plain position (inherently fixed — the no-entity escape hatch).
+ */
+export type CameraTarget = AnyInstance | Effect.Effect<AnyInstance, never, Runner.Runner> | Partial<Entity.Position>;
+type CamData = (typeof Camera)["data"];
+type CamTraits = (typeof Camera)["traits"];
+type CamOrEffect<E = never, R = Runner.Runner> = Instance.InstanceOrEffect<"Camera", CamData, CamTraits, E, R>;
+type CamInstance = Instance.Instance<"Camera", CamData, CamTraits>;
+type CamEffect = Effect.Effect<CamInstance, never, Runner.Runner>;
+/**
+ * Aim the camera at a target. No duration: set the point of interest this
+ * frame. With a duration: eased re-aim as a retargeted tween (lands
+ * exactly on a moving target, no terminal snap). `offset` shifts the aim
+ * relative to the target ("slightly above their head"). Dual:
+ * `lookAt(cam, target, ...)` or `cam.pipe(lookAt(target, ...))`.
+ */
+export declare const lookAt: ((target: CameraTarget, duration?: Duration.Input, timing?: Timing.TimingInput, offset?: Partial<Entity.Position>) => (cam: CamOrEffect) => CamEffect) & ((cam: CamOrEffect, target: CameraTarget, duration?: Duration.Input, timing?: Timing.TimingInput, offset?: Partial<Entity.Position>) => CamEffect);
+/**
+ * Track a target for the duration: the point of interest is a hard
+ * per-frame copy of the target position (+offset). A plain animator — it
+ * pipes, `Scene.all`s, staggers, repeats. No timing input (lag is
+ * expressed by springing the POI instead). Ordering practice: within a
+ * tick, branches run in fork order — a follow forked before its target's
+ * animator reads the previous frame's position, a deterministic one-frame
+ * trail. Dual like `lookAt`.
+ */
+export declare const follow: ((target: CameraTarget, duration: Duration.Input, offset?: Partial<Entity.Position>) => (cam: CamOrEffect) => CamEffect) & ((cam: CamOrEffect, target: CameraTarget, duration: Duration.Input, offset?: Partial<Entity.Position>) => CamEffect);
+/**
+ * Turntable the camera to an absolute azimuth around its point of
+ * interest (angle about the world-Y axis through the POI; 0 = directly +z
+ * of it). Position travels the arc — orientation comes entirely from the
+ * POI, so there is no orientation math to get wrong. Radius and height
+ * are preserved. Dies loudly without a POI. Dual like `moveTo`.
+ */
+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 `orbitTo`, but from an explicit start azimuth. */
+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 along its view axis to an absolute distance from the
+ * point of interest (in: toward it, out: away), aim unchanged. Dies
+ * loudly without a POI. Dual like `moveTo`.
+ */
+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 `dollyTo`, but from an explicit start distance. */
+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);

package/dist/CameraHelpers.js

@@ -0,0 +1,239 @@
+import * as Duration from "effect/Duration";
+import * as Effect from "effect/Effect";
+import { dual } from "effect/Function";
+import * as Entity from "./Entity.js";
+import * as Instance from "./Instance.js";
+import * as Motion from "./Motion.js";
+import * as Runner from "./Runner.js";
+import * as Scene from "./Scene.js";
+import * as Time from "./Time.js";
+import * as Timing from "./Timing.js";
+/**
+ * The public Camera surface: the entity/identity from Camera.js plus the
+ * directing helpers. This module (not Camera.ts) is what index exports as
+ * the `Camera` namespace — Runner/Renderer import the schema file
+ * directly, so helpers can depend on Motion/Scene without an import
+ * cycle.
+ *
+ * Naming rule (recorded in the camera-poi-helpers change): verbs that
+ * name their target (`lookAt`, `follow`) have no base/To pair — an
+ * optional duration selects instant vs eased. Value-animating helpers
+ * (`orbit`/`orbitTo`, `dolly`/`dollyTo`) keep the pair, exactly like
+ * `move`/`moveTo`.
+ */
+// explicit named re-exports (not `export *`) so the public Camera surface
+// is enumerable at a glance: the entity + identity from the schema module,
+// plus the helpers below
+export { Camera, identity } from "./Camera.js";
+// a target argument (vs a duration/timing in the same slot): instances,
+// effects, or a position-like object — Durations are objects too, so
+// exclude them explicitly
+const isTargetArg = (v) => Instance.isInstance(v) ||
+    Effect.isEffect(v) ||
+    (typeof v === "object" &&
+        v !== null &&
+        !Duration.isDuration(v) &&
+        ("x" in v || "y" in v || "z" in v));
+// data-first iff the first arg is an instance AND the second is a target —
+// plain firstArgIsInstance would misread `cam.pipe`-less pipeable calls
+// whose TARGET is an instance (`lookAt(hero, "1 second")`)
+const dataFirst = (args) => Instance.isInstance(args[0]) && isTargetArg(args[1]);
+/**
+ * Resolve a target once (Effects yield their Instance), returning a
+ * per-frame position reader with the offset folded in: live for
+ * instances, fixed for plain positions.
+ */
+const targetReader = Effect.fnUntraced(function* (target, offset) {
+    const ox = offset?.x ?? 0;
+    const oy = offset?.y ?? 0;
+    const oz = offset?.z ?? 0;
+    if (Instance.isInstance(target) || Effect.isEffect(target)) {
+        const instance = yield* Instance.flatten(target);
+        const lens = Entity.traitOrDie(instance.entity, "~position");
+        return Scene.data(instance).pipe(Effect.map((data) => {
+            const p = lens.get(data);
+            return { x: p.x + ox, y: p.y + oy, z: p.z + oz };
+        }));
+    }
+    // AnyInstance's `any` params defeat narrowing — the guards above
+    // returned for instances/effects, so this is a plain position
+    const point = target;
+    const fixed = {
+        x: (point.x ?? 0) + ox,
+        y: (point.y ?? 0) + oy,
+        z: (point.z ?? 0) + oz,
+    };
+    return Effect.succeed(fixed);
+});
+const setPoi = (data, p) => Object.assign({}, data, { poiX: p.x, poiY: p.y, poiZ: p.z });
+// the camera's WORLD position: x/y are pan-from-viewport-center
+const worldPosition = Effect.fnUntraced(function* (cam) {
+    const { settings } = yield* Runner.Runner;
+    const data = (yield* Scene.data(cam));
+    return {
+        x: settings.width / 2 + data.x,
+        y: settings.height / 2 + data.y,
+        z: data.z ?? 0,
+    };
+});
+const lookAtImpl = Effect.fnUntraced(function* (camOrEffect, target, duration, timing, offset) {
+    const cam = yield* Instance.flatten(camOrEffect);
+    const read = yield* targetReader(target, offset);
+    if (duration === undefined) {
+        const p = yield* read;
+        yield* Scene.update(cam, (d) => setPoi(d, p));
+        return cam;
+    }
+    // eased re-aim: a RETARGETED tween — each frame interpolates from the
+    // start POI toward the target's CURRENT position, converging exactly
+    // onto a moving target at t = 1 (a plain-Position target degenerates to
+    // a fixed tween). Effectful per-frame read, so this runs its own loop
+    // rather than Motion.drive (whose callback is pure).
+    const runner = yield* Runner.Runner;
+    const timingFn = Timing.resolve(timing ?? "linear");
+    const data = (yield* Scene.data(cam));
+    let start;
+    if (data.poiX !== undefined &&
+        data.poiY !== undefined &&
+        data.poiZ !== undefined) {
+        start = { x: data.poiX, y: data.poiY, z: data.poiZ };
+    }
+    else {
+        // no POI yet: seed on the camera's UNAIMED axis (straight down world
+        // -z) at the target's distance. resolveCamera derives zero aim for
+        // that point, so the explicit Euler alone carries the view — engaging
+        // POI mode is snap-free for ANY current orientation, and the tween
+        // takes over from there.
+        const world = yield* worldPosition(cam);
+        const first = yield* read;
+        const distance = Math.hypot(first.x - world.x, first.y - world.y, first.z - world.z);
+        start = { x: world.x, y: world.y, z: world.z - distance };
+    }
+    const frames = Math.max(1, Time.toFrames(duration, runner.settings.frameRate));
+    for (let i = 1; i <= frames; i++) {
+        const t = timingFn(i / frames);
+        const p = yield* read;
+        yield* Scene.update(cam, (d) => setPoi(d, {
+            x: start.x + (p.x - start.x) * t,
+            y: start.y + (p.y - start.y) * t,
+            z: start.z + (p.z - start.z) * t,
+        }));
+        yield* Scene.tick;
+    }
+    return cam;
+});
+/**
+ * Aim the camera at a target. No duration: set the point of interest this
+ * frame. With a duration: eased re-aim as a retargeted tween (lands
+ * exactly on a moving target, no terminal snap). `offset` shifts the aim
+ * relative to the target ("slightly above their head"). Dual:
+ * `lookAt(cam, target, ...)` or `cam.pipe(lookAt(target, ...))`.
+ */
+export const lookAt = dual(dataFirst, lookAtImpl);
+/**
+ * Track a target for the duration: the point of interest is a hard
+ * per-frame copy of the target position (+offset). A plain animator — it
+ * pipes, `Scene.all`s, staggers, repeats. No timing input (lag is
+ * expressed by springing the POI instead). Ordering practice: within a
+ * tick, branches run in fork order — a follow forked before its target's
+ * animator reads the previous frame's position, a deterministic one-frame
+ * trail. Dual like `lookAt`.
+ */
+export const follow = dual(dataFirst, Effect.fnUntraced(function* (camOrEffect, target, duration, offset) {
+    const cam = yield* Instance.flatten(camOrEffect);
+    const read = yield* targetReader(target, offset);
+    const runner = yield* Runner.Runner;
+    const frames = Math.max(1, Time.toFrames(duration, runner.settings.frameRate));
+    for (let i = 1; i <= frames; i++) {
+        const p = yield* read;
+        yield* Scene.update(cam, (d) => setPoi(d, p));
+        yield* Scene.tick;
+    }
+    return cam;
+}));
+// orbit/dolly are defined relative to the POI — die loudly without one
+const poiOrDie = (data) => {
+    if (data.poiX === undefined ||
+        data.poiY === undefined ||
+        data.poiZ === undefined) {
+        throw new Error("Camera: orbit/dolly need a point of interest — set one first (Camera.lookAt(target))");
+    }
+    return { x: data.poiX, y: data.poiY, z: data.poiZ };
+};
+const orbitImpl = Effect.fnUntraced(function* (camOrEffect, from, to, duration, timing) {
+    const cam = yield* Instance.flatten(camOrEffect);
+    const { settings } = yield* Runner.Runner;
+    const origin = { x: settings.width / 2, y: settings.height / 2 };
+    const startData = (yield* Scene.data(cam));
+    const poi = poiOrDie(startData);
+    const world = {
+        x: origin.x + startData.x,
+        z: startData.z ?? 0,
+    };
+    // azimuth 0 = directly +z of the POI (the resting side); radius = the
+    // current horizontal distance, preserved through the arc; height too
+    const radius = Math.hypot(world.x - poi.x, world.z - poi.z);
+    const startAzimuth = from ?? Math.atan2(world.x - poi.x, world.z - poi.z);
+    return yield* Motion.drive(cam, duration, timing ?? "linear", (t, d) => {
+        const data = d;
+        // POI read from live data: orbiting a moving POI stays centered on it
+        const p = poiOrDie(data);
+        const angle = startAzimuth + (to - startAzimuth) * t;
+        return Object.assign({}, d, {
+            x: p.x + radius * Math.sin(angle) - origin.x,
+            z: p.z + radius * Math.cos(angle),
+        });
+    });
+});
+/**
+ * Turntable the camera to an absolute azimuth around its point of
+ * interest (angle about the world-Y axis through the POI; 0 = directly +z
+ * of it). Position travels the arc — orientation comes entirely from the
+ * POI, so there is no orientation math to get wrong. Radius and height
+ * are preserved. Dies loudly without a POI. Dual like `moveTo`.
+ */
+export const orbitTo = dual((args) => Instance.isInstance(args[0]), ((cam, azimuth, duration, timing) => orbitImpl(cam, undefined, azimuth, duration, timing)));
+/** Like `orbitTo`, but from an explicit start azimuth. */
+export const orbit = dual((args) => Instance.isInstance(args[0]), orbitImpl);
+const dollyImpl = Effect.fnUntraced(function* (camOrEffect, from, to, duration, timing) {
+    const cam = yield* Instance.flatten(camOrEffect);
+    const { settings } = yield* Runner.Runner;
+    const origin = { x: settings.width / 2, y: settings.height / 2 };
+    const startData = (yield* Scene.data(cam));
+    const poi = poiOrDie(startData);
+    const world = {
+        x: origin.x + startData.x,
+        y: origin.y + startData.y,
+        z: startData.z ?? 0,
+    };
+    const startDistance = Math.hypot(world.x - poi.x, world.y - poi.y, world.z - poi.z);
+    // the fixed unit direction POI → camera; a zero distance has no
+    // direction to dolly along
+    if (startDistance === 0) {
+        throw new Error("Camera: dolly from distance 0 — the camera sits ON its point of interest, so there is no view axis to move along");
+    }
+    const u = {
+        x: (world.x - poi.x) / startDistance,
+        y: (world.y - poi.y) / startDistance,
+        z: (world.z - poi.z) / startDistance,
+    };
+    const d0 = from ?? startDistance;
+    return yield* Motion.drive(cam, duration, timing ?? "linear", (t, d) => {
+        const data = d;
+        const p = poiOrDie(data);
+        const dist = d0 + (to - d0) * t;
+        return Object.assign({}, d, {
+            x: p.x + u.x * dist - origin.x,
+            y: p.y + u.y * dist - origin.y,
+            z: p.z + u.z * dist,
+        });
+    });
+});
+/**
+ * Move the camera along its view axis to an absolute distance from the
+ * point of interest (in: toward it, out: away), aim unchanged. Dies
+ * loudly without a POI. Dual like `moveTo`.
+ */
+export const dollyTo = dual((args) => Instance.isInstance(args[0]), ((cam, distance, duration, timing) => dollyImpl(cam, undefined, distance, duration, timing)));
+/** Like `dollyTo`, but from an explicit start distance. */
+export const dolly = dual((args) => Instance.isInstance(args[0]), dollyImpl);

package/dist/CanvasExporter.d.ts

@@ -0,0 +1,12 @@
+import * as Effect from "effect/Effect";
+import { EffectMotionError } from "./EffectMotionError.js";
+import type * as Renderer from "./Renderer.js";
+/**
+ * Blit a framebuffer onto a DOM canvas. The canvas buffer takes the
+ * framebuffer's PHYSICAL size (logical × dpr); CSS display size is left to
+ * the caller — the intrinsic aspect ratio is preserved by the attributes, so
+ * responsive styling (`width: 100%`) or a fixed `fb.logicalWidth`px both
+ * work. Writing CSS here would clobber caller styling (e.g. React inline
+ * styles are not re-applied on rerender).
+ */
+export declare const toCanvas: (fb: Renderer.Framebuffer, target: "string" | HTMLCanvasElement) => Effect.Effect<undefined, EffectMotionError, never>;

package/dist/CanvasExporter.js

@@ -0,0 +1,40 @@
+import * as Effect from "effect/Effect";
+import { EffectMotionError } from "./EffectMotionError.js";
+const resolveCanvas = Effect.fnUntraced(function* (target) {
+    if (typeof target === "string") {
+        if (typeof document === "undefined") {
+            return yield* Effect.fail(EffectMotionError.of("'document' is not available in the current environment"));
+        }
+        const maybeCanvas = document.querySelector(target);
+        if (maybeCanvas === null) {
+            return yield* Effect.fail(EffectMotionError.of(`Could not find canvas with selector '${target}'`));
+        }
+        if (!(maybeCanvas instanceof HTMLCanvasElement)) {
+            return yield* Effect.fail(EffectMotionError.of(`Could not find canvas with selector '${target}'`));
+        }
+        return maybeCanvas;
+    }
+    if (!(target instanceof HTMLCanvasElement)) {
+        return yield* Effect.fail(EffectMotionError.of(`'target' is not a HTMLCanvasElement`));
+    }
+    return target;
+});
+/**
+ * Blit a framebuffer onto a DOM canvas. The canvas buffer takes the
+ * framebuffer's PHYSICAL size (logical × dpr); CSS display size is left to
+ * the caller — the intrinsic aspect ratio is preserved by the attributes, so
+ * responsive styling (`width: 100%`) or a fixed `fb.logicalWidth`px both
+ * work. Writing CSS here would clobber caller styling (e.g. React inline
+ * styles are not re-applied on rerender).
+ */
+export const toCanvas = Effect.fnUntraced(function* (fb, target) {
+    const canvas = yield* resolveCanvas(target);
+    canvas.width = fb.width;
+    canvas.height = fb.height;
+    const ctx = canvas.getContext("2d");
+    if (ctx === null) {
+        return yield* Effect.fail(EffectMotionError.of("Could not get a 2D context from the canvas"));
+    }
+    const clamped = Uint8ClampedArray.from(fb.rgba);
+    ctx.putImageData(new ImageData(clamped, fb.width, fb.height), 0, 0);
+});