effect-motion 0.2.0

package/README.md

@@ -0,0 +1,40 @@
+# effect-motion
+
+Deterministic, 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.
+
+## Install
+
+`effect` is a peer dependency — install it alongside:
+
+```bash
+pnpm add effect-motion effect
+```
+
+## Write a scene
+
+Every `yield*` composes another effect into the scene.
+
+```ts
+import { Motion, Scene, Shapes } from "effect-motion";
+
+export const scene = Scene.make(function* () {
+	const circle = yield* Scene.instantiate(Shapes.Circle, {
+		x: 60,
+		y: 150,
+		radius: 16,
+		fill: "#7f5af0",
+	});
+
+	yield* circle.pipe(
+		Motion.tweenTo({ x: 440 }, "1 second", "easeInOutCubic"),
+	);
+});
+```
+
+Render it to SVG, play it in React with [`@effect-motion/react`](https://www.npmjs.com/package/@effect-motion/react), or export it to a video with [`@effect-motion/export`](https://www.npmjs.com/package/@effect-motion/export).
+
+## Documentation
+
+Full docs, concepts, and live examples: **https://github.com/julia-script/effect-motion**

package/dist/Camera.d.ts

@@ -0,0 +1,49 @@
+import type * as Schema from "effect/Schema";
+import * as Entity from "./Entity";
+/**
+ * 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.
+ *
+ * `~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.
+ */
+declare const fields: {
+    x: Schema.withConstructorDefault<Schema.Number>;
+    y: Schema.withConstructorDefault<Schema.Number>;
+    zoom: Schema.withConstructorDefault<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>;
+}>, {
+    readonly "~position": {
+        get: (data: CameraData) => {
+            x: number;
+            y: 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;
+}
+export {};

package/dist/Camera.js

@@ -0,0 +1,33 @@
+import * as Entity from "./Entity";
+import * as Shape2D from "./shapes/Shape2D";
+/**
+ * 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.
+ *
+ * `~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.
+ */
+const fields = {
+    ...Shape2D.position,
+    zoom: Shape2D.defaultedNumber(1),
+};
+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.
+    "~position": {
+        get: (data) => ({ x: data.x, y: data.y }),
+        set: (data, value) => ({
+            ...data,
+            x: value.x,
+            y: value.y,
+        }),
+    },
+});
+/** The identity view: no pan, no zoom. */
+export const IDENTITY = { x: 0, y: 0, zoom: 1 };

package/dist/Entity.d.ts

@@ -0,0 +1,40 @@
+import * as Schema from "effect/Schema";
+import type { AnyStructSchema } from "effect/unstable/workflow/Workflow";
+export declare const TypeId: "~motion/Entity";
+/**
+ * A trait is a complete get/set lens over the entity's data — all or
+ * nothing: a lone getter or setter is unrepresentable. `set` receives
+ * the whole data and returns a new immutable whole with the change
+ * applied, so each entity owns its semantics (e.g. Line's position
+ * translates both endpoints).
+ */
+export interface TraitLens<Data, Value> {
+    readonly get: (data: Data) => Value;
+    readonly set: (data: Data, value: Value) => Data;
+}
+/** a type alias (not interface) so it satisfies Record constraints */
+export type Position = {
+    readonly x: number;
+    readonly y: number;
+};
+export type EntityTraits<Data> = {
+    readonly "~position": TraitLens<Data, Position>;
+    readonly "~opacity": TraitLens<Data, number>;
+};
+export type TraitKey = keyof EntityTraits<unknown>;
+export interface Entity<Name extends string = string, Data extends Schema.Top = Schema.Top, Traits extends Partial<EntityTraits<Data["Type"]>> = {}, MakeInput = Data["~type.make.in"]> {
+    readonly [TypeId]: typeof TypeId;
+    readonly name: Name;
+    readonly data: Data;
+    readonly traits: Traits;
+    make(input: MakeInput | Data["~type.make.in"]): Data["Type"];
+    readonly _MakeInput?: MakeInput;
+}
+export type AnyEntity = Entity<any, any, any, any>;
+/** the entity's trait lens, or a defect naming entity and trait */
+export declare const traitOrDie: <Data, Value>(entity: AnyEntity, key: TraitKey) => TraitLens<Data, Value>;
+type NormalizeStructLike<T extends Schema.Struct.Fields | AnyStructSchema> = T extends AnyStructSchema ? T : T extends Schema.Struct.Fields ? Schema.Struct<T> : never;
+export declare const make: <Name extends string, Data extends Schema.Struct.Fields | AnyStructSchema, const Traits extends Partial<EntityTraits<NormalizeStructLike<Data>["Type"]>> = {}, MakeInput = NormalizeStructLike<Data>["~type.make.in"]>(name: Name, data: Data, traits?: Traits, options?: {
+    readonly normalize: (input: MakeInput | NormalizeStructLike<Data>["~type.make.in"]) => NormalizeStructLike<Data>["~type.make.in"];
+}) => Entity<Name, NormalizeStructLike<Data>, Traits, MakeInput>;
+export {};

package/dist/Entity.js

@@ -0,0 +1,32 @@
+import * as Schema from "effect/Schema";
+export const TypeId = "~motion/Entity";
+/** the entity's trait lens, or a defect naming entity and trait */
+export const traitOrDie = (entity, key) => {
+    const lens = entity.traits[key];
+    if (lens === undefined) {
+        throw new Error(`Entity "${entity.name}" does not implement the "${key}" trait`);
+    }
+    return lens;
+};
+const normalizeStructLike = (data) => {
+    return (Schema.isSchema(data) ? data : Schema.Struct(data));
+};
+export const make = (name, data, traits, options) => {
+    const normalized = normalizeStructLike(data);
+    // `$` is reserved for builtin, engine-owned instance properties (e.g.
+    // `$visible`), which live beside the data — never as entity-data fields.
+    for (const field of Object.keys(normalized.fields)) {
+        if (field.startsWith("$")) {
+            throw new Error(`Entity "${name}": field "${field}" uses the reserved "$" prefix (reserved for builtin instance properties like $visible)`);
+        }
+    }
+    return {
+        [TypeId]: TypeId,
+        name,
+        data: normalized,
+        traits: traits ?? {},
+        make: (input) => normalized.make(options === undefined
+            ? input
+            : options.normalize(input)),
+    };
+};

package/dist/Fonts.d.ts

@@ -0,0 +1,31 @@
+import * as Context from "effect/Context";
+/**
+ * One loadable font face. `family` is the name text entities reference in
+ * `fontFamily`; `src` carries per-environment sources — browsers load
+ * `url`, offline rasterizers read `path`. Consumers skip sources they
+ * can't use. `weight`/`style` are browser variant-matching descriptors;
+ * file-based rasterizers read them from the font file itself. Declare one
+ * entry per face (e.g. Inter 400 and Inter 700 are two entries).
+ */
+export interface FontResource {
+    readonly family: string;
+    readonly src: {
+        readonly url?: string;
+        readonly path?: string;
+    };
+    /** CSS font-weight (e.g. 400, 700) */
+    readonly weight?: number;
+    readonly style?: "normal" | "italic";
+}
+/**
+ * Scene annotation key declaring the fonts a scene's text depends on:
+ * `scene.annotate(Fonts.Fonts, [...])`. The runtime never reads it — the
+ * engine cannot measure text, so fonts cannot affect frame data. Consumers
+ * (the player, export tools) read it to prepare their environment before
+ * rendering.
+ */
+export declare const Fonts: Context.Reference<readonly FontResource[]>;
+/** A scene's declared fonts — empty for scenes never annotated. */
+export declare const get: (scene: {
+    readonly annotations: Context.Context<never>;
+}) => ReadonlyArray<FontResource>;

package/dist/Fonts.js

@@ -0,0 +1,11 @@
+import * as Context from "effect/Context";
+/**
+ * Scene annotation key declaring the fonts a scene's text depends on:
+ * `scene.annotate(Fonts.Fonts, [...])`. The runtime never reads it — the
+ * engine cannot measure text, so fonts cannot affect frame data. Consumers
+ * (the player, export tools) read it to prepare their environment before
+ * rendering.
+ */
+export const Fonts = Context.Reference("motion/Fonts", { defaultValue: () => [] });
+/** A scene's declared fonts — empty for scenes never annotated. */
+export const get = (scene) => Context.get(scene.annotations, Fonts);

package/dist/Instance.d.ts

@@ -0,0 +1,16 @@
+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";
+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;
+    readonly id: string;
+    readonly entity: Entity.Entity<Name, Data, Traits, any>;
+}
+/** 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, any> ? Instance<Name, Data, Traits> : never;
+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"]>>, MakeInput>(entity: Entity.Entity<Name, Data, Traits, MakeInput>, 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>;

package/dist/Instance.js

@@ -0,0 +1,18 @@
+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,
+    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;
+};

package/dist/Motion.d.ts

@@ -0,0 +1,74 @@
+import type * as Duration from "effect/Duration";
+import * as Effect from "effect/Effect";
+import type * as Schema from "effect/Schema";
+import * as Entity from "./Entity";
+import * as Instance from "./Instance";
+import * as Runner from "./Runner";
+import * as Timing from "./Timing";
+export type InterpolableValue = number;
+type InterpolableKeys<T> = {
+    [K in keyof T]: T[K] extends InterpolableValue ? K : never;
+}[keyof T];
+export type InterpolableOnly<T> = Pick<T, InterpolableKeys<T>>;
+/** target props, or an updater computing them from the current data */
+export type Target<Data extends Schema.Top> = Partial<InterpolableOnly<Data["Type"]>> | ((data: Data["Type"]) => Partial<InterpolableOnly<Data["Type"]>>);
+export declare const resolveTarget: <Data extends Schema.Top>(target: Target<Data>, current: Data["Type"]) => 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.
+ */
+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>);
+/**
+ * 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?))`.
+ */
+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>;
+};
+/**
+ * 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?))`.
+ */
+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>);
+/**
+ * Fade an instance's opacity via its `~opacity` trait. Dual:
+ * `fadeTo(instance, opacity, duration, timing?)` or
+ * `instance.pipe(fadeTo(opacity, duration, timing?))`.
+ */
+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>);
+/**
+ * `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.
+ */
+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>;
+}
+/**
+ * Hold the scene for `duration` of scene time (frames at the runner's
+ * frame rate) — `Scene.sleep`'s chainable sibling.
+ *
+ * - `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
+ */
+export declare const wait: (duration: Duration.Input) => Wait;
+export {};

package/dist/Motion.js

@@ -0,0 +1,125 @@
+import * as Effect from "effect/Effect";
+import * as Effectable from "effect/Effectable";
+import { dual } from "effect/Function";
+import * as Entity from "./Entity";
+import * as Instance from "./Instance";
+import * as Runner from "./Runner";
+import * as Scene from "./Scene";
+import * as Time from "./Time";
+import * as Timing from "./Timing";
+// extrapolating on purpose: eased t goes outside [0, 1] for back/elastic
+const lerpNumber = (from, to, t) => from + (to - from) * t;
+/**
+ * The interpolation engine: from `from` to `to` over `duration`, calling
+ * `fn` with the eased value once per frame (each step ends in a
+ * Scene.tick). The last call receives exactly `to` for any timing with
+ * f(1) = 1; a zero-length duration still takes one frame. Internal —
+ * public animators apply to instances.
+ */
+const interpolate = Effect.fnUntraced(function* (from, to, duration, fn, timing = "linear") {
+    const runner = yield* Runner.Runner;
+    const timingFn = Timing.resolve(timing);
+    const keys = Object.keys(from);
+    const frames = Math.max(1, Time.toFrames(duration, runner.settings.frameRate));
+    for (let i = 1; i <= frames; i++) {
+        const t = timingFn(i / frames);
+        const value = {};
+        for (const key of keys) {
+            value[key] = lerpNumber(from[key], to[key], t);
+        }
+        yield* fn(value);
+        yield* Scene.tick;
+    }
+});
+// InterpolableOnly of an opaque Data["Type"] 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"
+    ? target(current)
+    : target);
+// start values for the keys of `target`: from `explicitFrom` where given,
+// otherwise from the instance's current data
+export const startValues = (current, target, explicitFrom) => {
+    const start = {};
+    for (const key of Object.keys(target)) {
+        start[key] =
+            explicitFrom[key] ?? current[key];
+    }
+    return start;
+};
+const animate = Effect.fnUntraced(function* (instanceOrEffect, from, to, duration, timing) {
+    const instance = yield* Instance.flatten(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
+    Scene.update(instance, (data) => Object.assign({}, data, value)), timing);
+    return instance;
+});
+// dispatch on the first argument, not arity: the optional trailing
+// `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.
+ */
+export const tweenTo = dual(firstArgIsInstance, (instance, to, duration, timing) => animate(instance, undefined, to, duration, timing));
+/**
+ * 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?))`.
+ */
+export const tween = dual(firstArgIsInstance, (instance, from, to, duration, timing) => animate(instance, from, to, duration, timing));
+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));
+    // 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);
+    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);
+    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?))`.
+ */
+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). */
+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?))`.
+ */
+export const fadeTo = dual(firstArgIsInstance, (instance, to, duration, timing) => animateOpacity(instance, undefined, to, duration, timing));
+/** Like `fadeTo`, but from an explicit opacity. */
+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.
+ *
+ * - `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
+ */
+export const wait = (duration) => Object.assign((effect) => Effect.tap(effect, () => Scene.sleep(duration)), Effectable.Prototype({
+    label: "Motion.wait",
+    evaluate: () => Scene.sleep(duration),
+}));

package/dist/Phaser.d.ts

@@ -0,0 +1,65 @@
+import { Context, Effect } from "effect";
+declare const Phaser_base: Context.ServiceClass<Phaser, "motion/Phaser", {
+    register: (n: number) => void;
+    deregister: (n: number) => void;
+    arriveAndAwaitAdvance: Effect.Effect<void, never, never>;
+    awaitAdvance: Effect.Effect<number, never, never>;
+    /** debug/test view of the internal counters */
+    snapshotUnsafe: () => {
+        phase: number;
+        parties: number;
+        arrived: number;
+        state: "idle" | "pending" | "running";
+    };
+}> & {
+    readonly make: Effect.Effect<{
+        register: (n: number) => void;
+        deregister: (n: number) => void;
+        arriveAndAwaitAdvance: Effect.Effect<void, never, never>;
+        awaitAdvance: Effect.Effect<number, never, never>;
+        /** debug/test view of the internal counters */
+        snapshotUnsafe: () => {
+            phase: number;
+            parties: number;
+            arrived: number;
+            state: "idle" | "pending" | "running";
+        };
+    }, never, never>;
+};
+/**
+ * An externally paced phaser (cf. java.util.concurrent.Phaser).
+ *
+ * Unlike java's Phaser, which advances the moment the last party arrives,
+ * this phaser HOLDS at quiescence until the controller calls `awaitAdvance`,
+ * which arms the advance and resolves once every registered party has
+ * arrived again. One call = one phase = one animation frame.
+ */
+export declare class Phaser extends Phaser_base {
+}
+/**
+ * Fork `scene` as the root party of `phaser`.
+ *
+ * Registration happens synchronously before the fork, so between combinators
+ * the scene is registered-but-running and `awaitAdvance` can never resolve
+ * during a sequential handoff or before the scene starts. The slot is
+ * released by a finalizer on success, failure, and interrupt alike.
+ */
+export declare const run: <A, E, R>(phaser: Phaser["Service"], scene: Effect.Effect<A, E, R>) => Effect.Effect<import("effect/Fiber").Fiber<A, E>, never, Exclude<R, Phaser>>;
+/**
+ * Run `effect`, then arrive at the phase boundary.
+ *
+ * Borrows the caller's party slot (no register/deregister) — that is what
+ * makes consecutive `one` calls handoff-gap-free.
+ */
+export declare const one: <A, E, R>(effect: Effect.Effect<A, E, R>) => Effect.Effect<A, E, R | Phaser>;
+/**
+ * Run branches in parallel, sharing phases.
+ *
+ * N branches share N slots: the caller's one (the caller is blocked, not
+ * arrived, so it must not hold a countable slot) plus N-1 minted here. A
+ * finished branch releases a slot immediately so it cannot hold the phase
+ * open — except the last branch, whose slot returns to the resuming caller
+ * with no deregister/register gap.
+ */
+export declare const all: <Eff extends Effect.Effect<any, any, any>>(effects: Iterable<Eff>) => Effect.Effect<void, Eff extends Effect.Effect<any, infer E, any> ? E : never, (Eff extends Effect.Effect<any, any, infer R> ? R : never) | Phaser>;
+export {};