effect-motion 0.2.0

package/dist/Phaser.js

@@ -0,0 +1,170 @@
+import { Context, Effect, Latch, Layer } from "effect";
+/**
+ * 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 class Phaser extends Context.Service()("motion/Phaser", {
+    make: Effect.sync(() => {
+        let phase = 0;
+        let parties = 0;
+        let arrived = 0;
+        let phaseLatch = Latch.makeUnsafe();
+        let state = "idle";
+        let waiter = null;
+        // The single invariant. Every event that touches `arrived` or
+        // `parties` re-runs this.
+        const checkQuiescence = () => {
+            if (arrived !== parties) {
+                return;
+            }
+            switch (state) {
+                case "idle": {
+                    // all parties arrived, no waiter: hold until awaitAdvance
+                    return;
+                }
+                case "pending": {
+                    phase++;
+                    arrived = 0;
+                    const oldLatch = phaseLatch;
+                    // swap BEFORE open: a party that synchronously re-arrives
+                    // awaits the new latch and counts toward the new phase
+                    phaseLatch = Latch.makeUnsafe();
+                    state = "running";
+                    oldLatch.openUnsafe();
+                    // covers parties === 0 and synchronous re-arrivals
+                    checkQuiescence();
+                    return;
+                }
+                case "running": {
+                    const resume = waiter;
+                    waiter = null;
+                    state = "idle";
+                    resume?.();
+                    return;
+                }
+            }
+        };
+        const register = (n) => {
+            parties += n;
+        };
+        const deregister = (n) => {
+            parties -= n;
+            checkQuiescence();
+        };
+        const arriveAndAwaitAdvance = Effect.uninterruptibleMask((restore) => Effect.suspend(() => {
+            const myLatch = phaseLatch; // generation token
+            arrived++;
+            checkQuiescence();
+            return restore(myLatch.await).pipe(Effect.onInterrupt(() => Effect.sync(() => {
+                // undo the phantom arrival, but only if our
+                // generation is still the current one
+                if (myLatch === phaseLatch) {
+                    arrived--;
+                    checkQuiescence();
+                }
+            })));
+        }));
+        const awaitAdvance = Effect.callback((resume) => {
+            if (waiter !== null) {
+                resume(Effect.die(new Error("Phaser: concurrent awaitAdvance — single controller only")));
+                return;
+            }
+            waiter = () => resume(Effect.succeed(phase));
+            if (arrived === parties) {
+                // quiescent: arm an advance so parties run the next phase
+                state = "pending";
+                checkQuiescence();
+            }
+            else {
+                // parties still running toward their next arrival (e.g.
+                // scene startup): resolve at the first quiescence, do not
+                // advance past it
+                state = "running";
+            }
+            return Effect.sync(() => {
+                // interrupted while suspended
+                waiter = null;
+                state = "idle";
+            });
+        });
+        return {
+            register,
+            deregister,
+            arriveAndAwaitAdvance,
+            awaitAdvance,
+            /** debug/test view of the internal counters */
+            snapshotUnsafe: () => ({ phase, parties, arrived, state }),
+        };
+    }),
+}) {
+}
+/**
+ * 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 const run = (phaser, scene) => Effect.uninterruptibleMask(() => Effect.suspend(() => {
+    phaser.register(1);
+    return Effect.interruptible(scene).pipe(Effect.ensuring(Effect.sync(() => phaser.deregister(1))), Effect.provide(Layer.succeed(Phaser, phaser)), Effect.forkChild);
+}));
+/**
+ * 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 const one = (effect) => Effect.gen(function* () {
+    const phaser = yield* Phaser;
+    const result = yield* effect;
+    yield* phaser.arriveAndAwaitAdvance;
+    return result;
+});
+/**
+ * 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 const all = (effects) => Effect.gen(function* () {
+    const phaser = yield* Phaser;
+    const list = Array.from(effects);
+    const n = list.length;
+    if (n === 0) {
+        return;
+    }
+    if (n === 1) {
+        // biome-ignore lint/style/noNonNullAssertion: n === 1 guarantees it
+        yield* list[0];
+        return;
+    }
+    let live = n;
+    let held = n - 1; // extra slots this `all` still holds
+    yield* Effect.uninterruptibleMask((restore) => Effect.suspend(() => {
+        phaser.register(held);
+        const branches = list.map((branch) => branch.pipe(Effect.andThen(Effect.sync(() => {
+            live--;
+            if (live > 0) {
+                held--;
+                phaser.deregister(1);
+            }
+        }))));
+        return restore(Effect.all(branches, { concurrency: "unbounded" })).pipe(Effect.ensuring(Effect.sync(() => {
+            // failure/interrupt: release whatever is still held
+            if (held > 0) {
+                const leftover = held;
+                held = 0;
+                phaser.deregister(leftover);
+            }
+        })));
+    }));
+});

package/dist/Physics.d.ts

@@ -0,0 +1,78 @@
+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";
+/**
+ * Physics-based motion: durationless animations that carry momentum and
+ * end on their own. A spring is a damped harmonic oscillator simulated
+ * until displacement and velocity settle within a tolerance — there is
+ * no duration to specify, so springs are combinators here rather than
+ * `TimingInput`s.
+ */
+export interface Spring {
+    readonly mass: number;
+    readonly stiffness: number;
+    readonly damping: number;
+    readonly initialVelocity?: number;
+}
+/** fast, gently damped general-purpose spring */
+export declare const defaultSpring: Spring;
+export declare const springs: {
+    readonly beat: {
+        readonly mass: 0.13;
+        readonly stiffness: 5.7;
+        readonly damping: 1.2;
+        readonly initialVelocity: 10;
+    };
+    readonly plop: {
+        readonly mass: 0.2;
+        readonly stiffness: 20;
+        readonly damping: 0.68;
+    };
+    readonly bounce: {
+        readonly mass: 0.08;
+        readonly stiffness: 4.75;
+        readonly damping: 0.05;
+    };
+    readonly swing: {
+        readonly mass: 0.39;
+        readonly stiffness: 19.85;
+        readonly damping: 2.82;
+    };
+    readonly jump: {
+        readonly mass: 0.04;
+        readonly stiffness: 10;
+        readonly damping: 0.7;
+        readonly initialVelocity: 8;
+    };
+    readonly strike: {
+        readonly mass: 0.03;
+        readonly stiffness: 20;
+        readonly damping: 0.9;
+        readonly initialVelocity: 4.8;
+    };
+    readonly smooth: {
+        readonly mass: 0.16;
+        readonly stiffness: 15.35;
+        readonly damping: 1.88;
+    };
+};
+export type SpringName = keyof typeof springs;
+/** a preset name (autocompleted) or a custom spring configuration */
+export type SpringInput = SpringName | Spring;
+export declare const resolve: (input: SpringInput) => Effect.Effect<Spring>;
+type HasPosition<Data extends Schema.Top> = {
+    readonly "~position": Entity.TraitLens<Data["Type"], Entity.Position>;
+};
+/**
+ * Spring an instance to a position via its `~position` trait — the
+ * durationless counterpart of `Motion.moveTo` (settles exactly, length
+ * emerges from the physics). Dual:
+ * `springTo(instance, to, springInput?, settleTolerance?)` or
+ * `instance.pipe(springTo(to, springInput?, settleTolerance?))`.
+ */
+export declare const springTo: (<Name extends string, Data extends Schema.Top, Traits extends Partial<Entity.EntityTraits<Data["Type"]>> & HasPosition<Data>>(to: Partial<Entity.Position>, springInput?: SpringInput, settleTolerance?: number) => <E = never, R = never>(instance: Instance.InstanceOrEffect<Name, Data, Traits, E, R>) => Effect.Effect<Instance.Instance<Name, Data, Traits>, E, R | Runner.Runner>) & (<Name extends string, Data extends Schema.Top, Traits extends Partial<Entity.EntityTraits<Data["Type"]>> & HasPosition<Data>, E = never, R = never>(instance: Instance.InstanceOrEffect<Name, Data, Traits, E, R>, to: Partial<Entity.Position>, springInput?: SpringInput, settleTolerance?: number) => Effect.Effect<Instance.Instance<Name, Data, Traits>, E, R | Runner.Runner>);
+/** Like `springTo`, but from an explicit position (partials filled from current). */
+export declare const spring: (<Name extends string, Data extends Schema.Top, Traits extends Partial<Entity.EntityTraits<Data["Type"]>> & HasPosition<Data>>(from: Partial<Entity.Position>, to: Partial<Entity.Position>, springInput?: SpringInput, settleTolerance?: number) => <E = never, R = never>(instance: Instance.InstanceOrEffect<Name, Data, Traits, E, R>) => Effect.Effect<Instance.Instance<Name, Data, Traits>, E, R | Runner.Runner>) & (<Name extends string, Data extends Schema.Top, Traits extends Partial<Entity.EntityTraits<Data["Type"]>> & HasPosition<Data>, E = never, R = never>(instance: Instance.InstanceOrEffect<Name, Data, Traits, E, R>, from: Partial<Entity.Position>, to: Partial<Entity.Position>, springInput?: SpringInput, settleTolerance?: number) => Effect.Effect<Instance.Instance<Name, Data, Traits>, E, R | Runner.Runner>);
+export {};

package/dist/Physics.js

@@ -0,0 +1,117 @@
+import * as Effect from "effect/Effect";
+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";
+/** fast, gently damped general-purpose spring */
+export const defaultSpring = {
+    mass: 0.05,
+    stiffness: 10,
+    damping: 0.5,
+};
+export const springs = {
+    beat: { mass: 0.13, stiffness: 5.7, damping: 1.2, initialVelocity: 10 },
+    plop: { mass: 0.2, stiffness: 20, damping: 0.68 },
+    bounce: { mass: 0.08, stiffness: 4.75, damping: 0.05 },
+    swing: { mass: 0.39, stiffness: 19.85, damping: 2.82 },
+    jump: { mass: 0.04, stiffness: 10, damping: 0.7, initialVelocity: 8 },
+    strike: { mass: 0.03, stiffness: 20, damping: 0.9, initialVelocity: 4.8 },
+    smooth: { mass: 0.16, stiffness: 15.35, damping: 1.88 },
+};
+// invalid configs are defects for now; may graduate to typed errors in E
+export const resolve = (input) => Effect.suspend(() => {
+    const spring = typeof input === "string" ? springs[input] : input;
+    if (spring === undefined) {
+        // unreachable for typed consumers; catches plain-JS typos
+        return Effect.die(new Error(`Physics: unknown spring "${String(input)}"`));
+    }
+    if (spring.mass <= 0) {
+        return Effect.die(new Error("Physics: spring mass must be greater than 0"));
+    }
+    if (spring.stiffness < 0) {
+        return Effect.die(new Error("Physics: spring stiffness must be >= 0"));
+    }
+    if (spring.damping < 0) {
+        return Effect.die(new Error("Physics: spring damping must be >= 0"));
+    }
+    return Effect.succeed(spring);
+});
+// fixed-rate integration keeps trajectories frame-rate independent:
+// explicit Euler diverges with large dt, so each scene frame consumes
+// its 1/frameRate seconds in 1/120 s substeps
+const SIMULATION_STEP = 1 / 120;
+/**
+ * The simulation engine: spring each key of `from` toward `to`, calling
+ * `fn` once per scene frame until every key's displacement AND velocity
+ * are within `settleTolerance`, then snap exactly onto `to`. Length
+ * emerges from the physics — a zero-damping spring never settles and
+ * animates indefinitely (the scene keeps ticking; stepping never
+ * blocks). Internal — public animators apply to instances.
+ */
+const simulate = Effect.fnUntraced(function* (from, to, springInput, fn, settleTolerance = 0.001) {
+    const runner = yield* Runner.Runner;
+    const config = yield* resolve(springInput);
+    const frameDt = 1 / runner.settings.frameRate;
+    const keys = Object.keys(from);
+    const positions = {};
+    const velocities = {};
+    for (const key of keys) {
+        positions[key] = from[key];
+        velocities[key] = config.initialVelocity ?? 0;
+    }
+    const settled = () => keys.every((key) => Math.abs(to[key] - positions[key]) <
+        settleTolerance &&
+        Math.abs(velocities[key]) < settleTolerance);
+    const substep = (dt) => {
+        for (const key of keys) {
+            const position = positions[key];
+            const velocity = velocities[key];
+            const displacement = position - to[key];
+            const force = -config.stiffness * displacement - config.damping * velocity;
+            const nextVelocity = velocity + (force / config.mass) * dt;
+            velocities[key] = nextVelocity;
+            positions[key] = position + nextVelocity * dt;
+        }
+    };
+    let done = settled();
+    while (!done) {
+        let remaining = frameDt;
+        while (remaining > 0) {
+            substep(Math.min(SIMULATION_STEP, remaining));
+            remaining -= SIMULATION_STEP;
+            if (settled()) {
+                done = true;
+                break;
+            }
+        }
+        if (!done) {
+            yield* fn({ ...positions });
+            yield* Scene.tick;
+        }
+    }
+    // physics only approaches the target; the final frame lands exactly
+    yield* fn({ ...to });
+    yield* Scene.tick;
+});
+const springPosition = Effect.fnUntraced(function* (instanceOrEffect, from, to, springInput, settleTolerance) {
+    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* simulate(start, target, springInput ?? defaultSpring, (value) => Scene.update(instance, (data) => lens.set(data, value)), settleTolerance);
+    return instance;
+});
+const firstArgIsInstance = (args) => Instance.isInstance(args[0]);
+/**
+ * Spring an instance to a position via its `~position` trait — the
+ * durationless counterpart of `Motion.moveTo` (settles exactly, length
+ * emerges from the physics). Dual:
+ * `springTo(instance, to, springInput?, settleTolerance?)` or
+ * `instance.pipe(springTo(to, springInput?, settleTolerance?))`.
+ */
+export const springTo = dual(firstArgIsInstance, (instance, to, springInput, settleTolerance) => springPosition(instance, undefined, to, springInput, settleTolerance));
+/** Like `springTo`, but from an explicit position (partials filled from current). */
+export const spring = dual(firstArgIsInstance, (instance, from, to, springInput, settleTolerance) => springPosition(instance, from, to, springInput, settleTolerance));

package/dist/Renderer.d.ts

@@ -0,0 +1,69 @@
+import { Layer } from "effect";
+import * as Context from "effect/Context";
+import * as Effect from "effect/Effect";
+import type * as Entity from "./Entity";
+import type { EntriesFromEntities, Frame } from "./Scene";
+/** Renders one entity instance to the renderer's per-entity output. */
+export type RenderFunction<Success, Ent extends Entity.AnyEntity, E = never, R = never> = (payload: {
+    entity: Ent;
+    id: string;
+    data: Ent["data"]["Type"];
+    /**
+     * rendered output of this instance's children, post-order (empty for
+     * leaves). In frame data, a `children: string[]` field means child
+     * instance ids — containers embed these results in their own output.
+     */
+    children: ReadonlyArray<Success>;
+}) => Effect.Effect<Success, E, R>;
+/** the frame's render metadata, handed to sink render functions */
+export interface FrameMeta {
+    readonly frameRate: number;
+    readonly width: number;
+    readonly height: number;
+    readonly backgroundColor: string;
+    /**
+     * the active camera's view — `{x, y}` pan in world units, `zoom` a
+     * uniform scale (1 = identity). Sinks apply it per top-level layer,
+     * scaled by that layer's `depth`. Absent camera work leaves this at
+     * identity `{0, 0, 1}` and output is unchanged.
+     */
+    readonly camera: {
+        readonly x: number;
+        readonly y: number;
+        readonly zoom: number;
+    };
+}
+export interface EntityRenderer<Name extends string, Success, Ent extends Entity.AnyEntity, E, R> {
+    readonly name: Name;
+    readonly render: RenderFunction<Success, Ent, E, R>;
+}
+type RendererName<Tag extends string, Ent extends Entity.AnyEntity> = `${Tag}/${Ent["name"]}`;
+/**
+ * Build a renderer family.
+ *
+ * `make<EntityOutput>()(tag, { render })` creates a frame renderer that
+ * resolves one `EntityRenderer` per entity type from context (keyed
+ * `<tag>/<entity name>`) and combines the per-entity outputs with
+ * `config.render`. Provide per-entity renderers with
+ * `makeEntityRendererLayer` and the frame renderer with `layer`.
+ */
+export declare const make: <RenderEntitySuccess, Config = void>() => <const Tag extends string, RenderSuccess>(tag: Tag, config: {
+    render: <Entities>(entities: Iterable<{
+        id: string;
+        render: Effect.Effect<RenderEntitySuccess>;
+        entry: EntriesFromEntities<Entities>;
+    }>, config: Config, meta: FrameMeta) => Effect.Effect<RenderSuccess>;
+}) => {
+    Context: Context.Service<{
+        render: <const Entities extends Entity.AnyEntity>(frame: Frame<Entities>, config: Config) => Effect.Effect<RenderSuccess, never, Entities extends Entity.AnyEntity ? { [K in Entities as K["name"]]: EntityRenderer<`${Tag}/${K["name"]}`, RenderEntitySuccess, K, never, never>; }[Entities["name"]] : never>;
+    }, {
+        render: <const Entities extends Entity.AnyEntity>(frame: Frame<Entities>, config: Config) => Effect.Effect<RenderSuccess, never, Entities extends Entity.AnyEntity ? { [K in Entities as K["name"]]: EntityRenderer<`${Tag}/${K["name"]}`, RenderEntitySuccess, K, never, never>; }[Entities["name"]] : never>;
+    }>;
+    layer: Layer.Layer<{
+        render: <const Entities extends Entity.AnyEntity>(frame: Frame<Entities>, config: Config) => Effect.Effect<RenderSuccess, never, Entities extends Entity.AnyEntity ? { [K in Entities as K["name"]]: EntityRenderer<`${Tag}/${K["name"]}`, RenderEntitySuccess, K, never, never>; }[Entities["name"]] : never>;
+    }, never, never>;
+    makeEntityRendererContext: <const Ent extends Entity.AnyEntity, E = never, R = never>(entity: Ent) => Context.Service<EntityRenderer<`${Tag}/${Ent["name"]}`, RenderEntitySuccess, Ent, E, R>, EntityRenderer<`${Tag}/${Ent["name"]}`, RenderEntitySuccess, Ent, E, R>>;
+    makeEntityRendererService: <const Ent extends Entity.AnyEntity, E = never, R = never>(entity: Ent, render: RenderFunction<RenderEntitySuccess, Ent, E, R>) => EntityRenderer<`${Tag}/${Ent["name"]}`, RenderEntitySuccess, Ent, E, R>;
+    makeEntityRendererLayer: <const Ent extends Entity.AnyEntity, E = never, R = never>(entity: Ent, render: RenderFunction<RenderEntitySuccess, Ent, E, R>) => Layer.Layer<EntityRenderer<RendererName<Tag, Ent>, RenderEntitySuccess, Ent, E, R>>;
+};
+export {};

package/dist/Renderer.js

@@ -0,0 +1,90 @@
+import { Layer } from "effect";
+import * as Context from "effect/Context";
+import * as Effect from "effect/Effect";
+/**
+ * Build a renderer family.
+ *
+ * `make<EntityOutput>()(tag, { render })` creates a frame renderer that
+ * resolves one `EntityRenderer` per entity type from context (keyed
+ * `<tag>/<entity name>`) and combines the per-entity outputs with
+ * `config.render`. Provide per-entity renderers with
+ * `makeEntityRendererLayer` and the frame renderer with `layer`.
+ */
+export const make = () => (tag, config) => {
+    const makeEntityRendererContext = (entity) => Context.Service(`${tag}/${entity.name}`);
+    const makeEntityRendererService = (entity, render) => makeEntityRendererContext(entity).of({
+        name: `${tag}/${entity.name}`,
+        render,
+    });
+    const makeEntityRendererLayer = (entity, render) => Layer.succeed(makeEntityRendererContext(entity), makeEntityRendererService(entity, render));
+    // The concrete member of Renderers<Entities> is only known at
+    // runtime (it depends on the instance's entity), hence the cast.
+    const getEntityRenderer = (entity) => Effect.gen(function* () {
+        return yield* makeEntityRendererContext(entity);
+    });
+    const context = Context.Service(tag);
+    // in frame data, a `children: string[]` field means child instance ids
+    const childIdsOf = (data) => {
+        const children = data?.children;
+        return Array.isArray(children) ? children : [];
+    };
+    // a hidden instance ($visible false) and its subtree are skipped
+    // entirely — target-agnostic, so every sink honors visibility for free
+    const isVisible = (frame, id) => frame.instances[id]?.$visible !== false;
+    const service = context.of({
+        render: Effect.fnUntraced(function* (frame, customConfig) {
+            const visited = new Set();
+            // post-order: children build (and later render) before their
+            // container, which receives the rendered results
+            const buildEntry = (id) => Effect.gen(function* () {
+                if (visited.has(id)) {
+                    return yield* Effect.die(new Error(`Renderer: instance "${id}" is referenced more than once (duplicate parent or cycle)`));
+                }
+                visited.add(id);
+                const entry = frame.instances[id];
+                if (entry === undefined) {
+                    return yield* Effect.die(new Error(`Renderer: unknown instance id "${id}"`));
+                }
+                const childEntries = yield* Effect.all(childIdsOf(entry.data)
+                    .filter((childId) => isVisible(frame, childId))
+                    .map(buildEntry));
+                const entityRenderer = yield* getEntityRenderer(entry.entity);
+                return {
+                    id,
+                    render: Effect.gen(function* () {
+                        const children = yield* Effect.all(childEntries.map((child) => child.render));
+                        return yield* entityRenderer.render({
+                            id,
+                            children,
+                            ...entry,
+                        });
+                    }),
+                    entry,
+                };
+            });
+            const rootEntry = frame.instances[frame.root];
+            if (rootEntry === undefined) {
+                return yield* Effect.die(new Error(`Renderer: missing root instance "${frame.root}"`));
+            }
+            visited.add(frame.root);
+            // the root group never renders; its children are the top level
+            const entries = yield* Effect.all(childIdsOf(rootEntry.data)
+                .filter((childId) => isVisible(frame, childId))
+                .map(buildEntry));
+            return yield* config.render(entries, customConfig, {
+                frameRate: frame.frameRate,
+                width: frame.width,
+                height: frame.height,
+                backgroundColor: frame.backgroundColor,
+                camera: frame.camera,
+            });
+        }),
+    });
+    return {
+        Context: context,
+        layer: Layer.succeed(context, service),
+        makeEntityRendererContext,
+        makeEntityRendererService,
+        makeEntityRendererLayer,
+    };
+};