effect-motion 0.2.0

package/dist/Scene.d.ts

@@ -0,0 +1,241 @@
+import { Context } from "effect";
+import * as Cause from "effect/Cause";
+import type * as Duration from "effect/Duration";
+import * as Effect from "effect/Effect";
+import * as Fiber from "effect/Fiber";
+import type * as Schedule from "effect/Schedule";
+import type * as Schema from "effect/Schema";
+import type * as Scope from "effect/Scope";
+import * as Stream from "effect/Stream";
+import type * as Entity from "./Entity";
+import type * as Instance from "./Instance";
+import * as Phaser from "./Phaser";
+import * as Runner from "./Runner";
+export declare const TypeId: "~motion/Scene";
+export interface Scene<E, R, Entities> {
+    readonly [TypeId]: typeof TypeId;
+    readonly runner: Effect.Effect<void, E, R | Scope.Scope>;
+    readonly "~entities": Entities;
+    /** tooling-facing metadata; never read by the runtime */
+    readonly annotations: Context.Context<never>;
+    annotate<I, S>(key: Context.Key<I, S>, value: S): Scene<E, R, Entities>;
+    annotateMerge(context: Context.Context<never>): Scene<E, R, Entities>;
+}
+type MakeEffect<Eff extends Effect.Effect<any, any, any>, AEff> = Effect.Effect<AEff, [
+    Eff
+] extends [never] ? never : [Eff] extends [Effect.Effect<infer _A, infer E, infer _R>] ? E : never, [
+    Eff
+] extends [never] ? never : [Eff] extends [Effect.Effect<infer _A, infer _E, infer R>] ? R : never>;
+export declare const make: <const Eff extends Effect.Effect<any, any, any>, AEff>(f: () => Generator<Eff, void, never>) => MakeEffect<Eff, AEff> extends Effect.Effect<AEff, infer E, infer R> ? Scene<E, Exclude<R, {
+    readonly [Entity.TypeId]: typeof Entity.TypeId;
+}> | Scope.Scope, Extract<R, {
+    readonly [Entity.TypeId]: typeof Entity.TypeId;
+}>> : never;
+export declare const instantiate: <Name extends string, Data extends Schema.Top, Traits extends Partial<Entity.EntityTraits<Data["Type"]>>, MakeInput>(entity: Entity.Entity<Name, Data, Traits, MakeInput>, props: Runner.InstantiateProps<MakeInput>) => Effect.Effect<Instance.Instance<Name, Data, Traits>, unknown, Entity.Entity<Name, Data, Traits, MakeInput> | Runner.Runner>;
+export declare const tick: Effect.Effect<void, never, Runner.Runner>;
+/**
+ * Hold the scene for `duration` of scene time (frames at the runner's
+ * frame rate) — `Effect.sleep`'s sibling, but in frames, not wall time.
+ * A zero-length duration is a no-op.
+ */
+export declare const sleep: (duration: Duration.Input) => Effect.Effect<void, never, Runner.Runner>;
+export interface FrameEntry<Entity extends Entity.AnyEntity> {
+    data: Entity["data"]["Type"];
+    entity: Entity;
+    /**
+     * builtin visibility, held beside the data; renderers skip `false`.
+     * Optional in the frame type (a hand-built frame or external producer
+     * may omit it) — absent means visible; the runner always sets it.
+     */
+    $visible?: boolean;
+}
+export type EntriesFromEntities<Entities> = Entities extends Entity.AnyEntity ? {
+    [K in Entities as K["name"]]: FrameEntry<K>;
+}[Entities["name"]] : never;
+export interface Frame<Entities extends Entity.AnyEntity> {
+    instances: Record<string, EntriesFromEntities<Entities>>;
+    /** id of the root group (conventionally "root"); never rendered itself */
+    root: string;
+    /** render metadata from the runner settings — a frame is self-describing */
+    frameRate: number;
+    width: number;
+    height: number;
+    backgroundColor: string;
+    /** the active camera's view; identity `{0,0,1}` when unused */
+    camera: {
+        x: number;
+        y: number;
+        zoom: number;
+    };
+}
+export declare const step: <E, R, Entities extends Entity.AnyEntity>(runningScene: RunningScene<E, R, Entities>) => Effect.Effect<Frame<Entities> | null, E, never>;
+interface RunningScene<E, R, Entities> {
+    readonly runner: Runner.Runner["Service"];
+    readonly scene: Scene<E, R, Entities>;
+    readonly fiber: Fiber.Fiber<void, E>;
+    readonly done: boolean;
+    /** frames delivered so far — mutated by `step` for the maxFrames cap */
+    framesDelivered: number;
+}
+export declare const run: <E, R, Entities>(scene: Scene<E, R, Entities>, settings?: Partial<Runner.Settings>) => Effect.Effect<RunningScene<E, R, Entities>, never, Exclude<Exclude<Exclude<Exclude<R, Scope.Scope>, never>, Phaser.Phaser>, Runner.Runner>>;
+export declare const stream: <E, R, Entities extends Entity.AnyEntity>(scene: Scene<E, R, Entities>, settings?: Partial<Runner.Settings>) => Stream.Stream<Frame<Entities>, Exclude<E, Cause.Done<any>>, Exclude<Exclude<Exclude<Exclude<Exclude<R, Scope.Scope>, never>, Phaser.Phaser>, Runner.Runner>, Scope.Scope>>;
+type Updater<Data> = Data | ((data: Data) => Data);
+export declare const data: <Name extends string, Data extends Schema.Top>(instance: Instance.Instance<Name, Data>) => Effect.Effect<Data["Type"] & ({} | undefined), never, Runner.Runner>;
+export declare const update: <Name extends string, Data extends Schema.Top>(instance: Instance.Instance<Name, Data>, props: Updater<Data["Type"]>) => Effect.Effect<void | false, never, Runner.Runner>;
+/**
+ * Move `child` under `parent`, detaching it from its current parent first
+ * (so it is never double-referenced). Instances are born mounted under the
+ * ambient parent; `appendChild` is the explicit reparent — the door to
+ * placing a lazily-created node into an existing group.
+ */
+export declare const appendChild: (parent: Runner.GroupInstance, child: Instance.Instance) => Effect.Effect<void, never, Runner.Runner>;
+/** Detach `child` from `parent` (no-op unless it is currently its child). */
+export declare const removeChild: (parent: Runner.GroupInstance, child: Instance.Instance) => Effect.Effect<void, never, Runner.Runner>;
+export declare const settings: () => Effect.Effect<{
+    frameRate: number;
+    width: number;
+    height: number;
+    backgroundColor: string;
+    seed: Runner.Seed;
+    maxFrames: number;
+}, never, Runner.Runner>;
+/**
+ * The active camera instance — an ordinary instance carrying `~position`
+ * (x/y pan) and a `zoom` field, so the existing animators drive it:
+ * `Scene.make(function* () { const cam = yield* Scene.camera; yield*
+ * cam.pipe(Motion.moveTo({ x: 400 })) })`. A default identity camera is
+ * always present; animate it directly, or `Scene.setCamera` to swap in
+ * another instance. The camera is never drawn.
+ */
+export declare const camera: Effect.Effect<Instance.Instance<"Camera", Schema.Struct<{
+    x: Schema.withConstructorDefault<Schema.Number>;
+    y: Schema.withConstructorDefault<Schema.Number>;
+    zoom: Schema.withConstructorDefault<Schema.Number>;
+}>, {
+    readonly "~position": {
+        get: (data: Schema.Struct.ReadonlySide<{
+            x: Schema.withConstructorDefault<Schema.Number>;
+            y: Schema.withConstructorDefault<Schema.Number>;
+            zoom: Schema.withConstructorDefault<Schema.Number>;
+        }, "Type">) => {
+            x: number;
+            y: number;
+        };
+        set: (data: Schema.Struct.ReadonlySide<{
+            x: Schema.withConstructorDefault<Schema.Number>;
+            y: Schema.withConstructorDefault<Schema.Number>;
+            zoom: Schema.withConstructorDefault<Schema.Number>;
+        }, "Type">, value: Entity.Position) => Schema.Struct.ReadonlySide<{
+            x: Schema.withConstructorDefault<Schema.Number>;
+            y: Schema.withConstructorDefault<Schema.Number>;
+            zoom: Schema.withConstructorDefault<Schema.Number>;
+        }, "Type">;
+    };
+}>, never, Runner.Runner>;
+/** Swap the active camera to `instance`; its live data becomes the view. */
+export declare const setCamera: (instance: Instance.Instance) => Effect.Effect<void, never, Runner.Runner>;
+/**
+ * Handle to a branch of animation (a fork, background, or played scene).
+ * `finished` resolves at the branch's SEMANTIC end — `Scene.finish` or
+ * completion, whichever comes first. Awaiting it from scene code HOLDS
+ * the scene (the waiter keeps ticking frames, like `Scene.sleep`), so
+ * the rest of the scene stays live while you wait. `fiber` is the
+ * branch's physical execution — interrupt it to bound a tail.
+ */
+export interface BranchHandle<A = unknown, E = unknown> {
+    readonly finished: Effect.Effect<void, never, Runner.Runner>;
+    readonly fiber: Fiber.Fiber<A, E>;
+}
+/**
+ * Finish the innermost enclosing branch (the current fork, played scene,
+ * or the scene body itself): whoever awaits the branch's `finished`
+ * proceeds, the branch stops blocking its parent's end, and the code
+ * after `finish` keeps running as a TAIL — bounded by the parent, which
+ * interrupts it at scene end like a background. Idempotent; completion
+ * implies finish. NOTE: a failure in the tail (after finish) is NOT
+ * reported — by then nothing is listening.
+ */
+export declare const finish: Effect.Effect<undefined, never, never>;
+/**
+ * Run `effect`, then repeat it as long as `schedule` recurs, with the
+ * schedule evaluated in scene time (frames at the runner's frame rate) —
+ * `Effect.repeat`'s sibling, but paced by frames instead of the wall
+ * clock. The first run is immediate; the schedule paces the gaps after
+ * runs; each run's result is fed to the schedule as input. Resolves with
+ * the schedule's final output once it is done; a failed run fails
+ * immediately without consulting the schedule again.
+ */
+export declare const repeat: <A, E, R, Output, ScheduleE, ScheduleR>(effect: Effect.Effect<A, E, R>, schedule: Schedule.Schedule<Output, A, ScheduleE, ScheduleR>) => Effect.Effect<Output, E | ScheduleE, R | ScheduleR | Runner.Runner>;
+/**
+ * Run `effect` concurrently with the rest of the scene, sharing frame
+ * phases, and return its fiber immediately.
+ *
+ * NOTE: this inverts Effect's own `fork` semantics — the scene's end
+ * WAITS for forked work. A scene whose body returns while forks are
+ * still animating keeps producing frames until the last fork finishes
+ * (so a scene containing only a fork still plays). Use
+ * {@link background} for work that should be cut off at scene end
+ * instead. Forks are supervised by the fiber that spawned them: a fork
+ * made inside another fork is interrupted when its spawner completes.
+ */
+export declare const fork: <A, E, R>(effect: Effect.Effect<A, E, R>) => Effect.Effect<BranchHandle<A, E>, never, Runner.Runner | Exclude<Exclude<R, never>, Phaser.Phaser>>;
+/**
+ * Like {@link fork}, but the fiber is INTERRUPTED at scene end instead
+ * of awaited — for indefinite work (`Scene.repeat(…, Schedule.forever)`)
+ * that should play for the duration of the scene without keeping it
+ * alive. "Scene end" includes the fork drain: backgrounds keep animating
+ * while awaited forks finish, and are stopped after the last one.
+ */
+export declare const background: <A, E, R>(effect: Effect.Effect<A, E, R>) => Effect.Effect<BranchHandle<A, E>, never, Runner.Runner | Exclude<Exclude<R, never>, Phaser.Phaser>>;
+export interface PlayOptions {
+    /** group to mount the scene's instances under (default: the root) */
+    readonly parent?: Runner.GroupInstance;
+    /** seed for this evaluation (default: the movie's seed) */
+    readonly seed?: Runner.Seed;
+}
+/**
+ * Play a scene as a branch of the current scene — the explicit door to
+ * nesting. The child shares the movie's runner, phaser, frame rate, and
+ * frame cap, and gets its own scope, branch handle, mount parent, and a
+ * FRESH seeded Random stream: `play(scene)` inside a movie seeded `S`
+ * animates exactly like `run(scene, { seed: S })` standalone. Awaited
+ * like a fork — `yield* handle.finished` for sequential nesting, or
+ * don't await for concurrent scenes.
+ */
+export declare const play: <E, R, Entities>(scene: Scene<E, R, Entities>, options?: PlayOptions) => Effect.Effect<BranchHandle<void, E>, never, Runner.Runner | Exclude<R, Scope.Scope>>;
+/**
+ * Run effects in lockstep parallel, sharing frame phases — the public
+ * counterpart to the low-level `Phaser.all`. Takes no schedule: pacing a
+ * list sequentially belongs to {@link chain}, overlapping staggered
+ * starts to {@link stagger}.
+ */
+export declare const all: typeof Phaser.all;
+/**
+ * Run items one at a time, in order — items NEVER overlap, mirroring
+ * Effect's guarantee for scheduled effects. The first item runs
+ * immediately; after each item completes, `schedule` is stepped once
+ * (with the item's result as input) to pace the next start. `fixed`
+ * gives a start cadence with catch-up, `spaced` gives rests between
+ * items. When the schedule ends early, the remaining items are skipped —
+ * it is the release policy, including how many. Without a schedule,
+ * plain sequential composition. Resolves with how many items completed.
+ * For overlapping runs, reach for {@link stagger} or {@link fork}
+ * explicitly.
+ */
+export declare const chain: <Eff extends Effect.Effect<any, any, any>, ScheduleE = never, ScheduleR = never>(effects: Iterable<Eff>, schedule?: Schedule.Schedule<unknown, Eff extends Effect.Effect<infer A, any, any> ? A : never, ScheduleE, ScheduleR>) => Effect.Effect<{
+    completed: number;
+}, (Eff extends Effect.Effect<any, infer E, any> ? E : never) | ScheduleE, (Eff extends Effect.Effect<any, any, infer R> ? R : never) | Runner.Runner | ScheduleR>;
+/**
+ * Release effects on `schedule` with OVERLAP: the first starts
+ * immediately, each next one on the schedule's next emission, and
+ * released effects run concurrently — semantically
+ * `chain(effects.map(Scene.fork))`, but resolving when all released
+ * effects finish rather than at the last release. When the schedule ends
+ * early, the remaining effects are skipped. Overlap is this
+ * combinator's purpose; the schedule-paced default ({@link chain})
+ * never overlaps.
+ */
+export declare const stagger: <Eff extends Effect.Effect<any, any, any>, ScheduleE = never, ScheduleR = never>(effects: Iterable<Eff>, schedule: Schedule.Schedule<unknown, void, ScheduleE, ScheduleR>) => Effect.Effect<{
+    released: number;
+}, (Eff extends Effect.Effect<any, infer E, any> ? E : never) | ScheduleE, (Eff extends Effect.Effect<any, any, infer R> ? R : never) | Phaser.Phaser | Runner.Runner | ScheduleR>;
+export {};