effect-motion 0.2.0 → 0.3.0

package/dist/Runner.d.ts

@@ -4,10 +4,11 @@ import * as Context from "effect/Context";
 import * as Effect from "effect/Effect";
 import type * as Fiber from "effect/Fiber";
 import type * as Schema from "effect/Schema";
-import { type CameraState } from "./Camera";
-import type * as Entity from "./Entity";
-import * as Instance from "./Instance";
-import { Group } from "./shapes/Group";
+import { type CameraState } from "./Camera.js";
+import * as Color from "./Color.js";
+import type * as Entity from "./Entity.js";
+import * as Instance from "./Instance.js";
+import { Group } from "./shapes/Group.js";
 export declare const TypeId: "~motion/SceneRunner";
 /** conventional id of the implicit root group every instance attaches to */
 export declare const ROOT_ID = "root";
@@ -20,7 +21,7 @@ export type Settings = {
     width: number;
     height: number;
     /** canvas background — carried on every frame so renderers can paint it (default a near-black, not pure #000) */
-    backgroundColor: string;
+    backgroundColor: Color.Color;
     /**
      * seeds the scene's pseudo-random service (effect's Random via
      * withSeed); the fixed default keeps default-constructed scenes
@@ -43,7 +44,7 @@ export type GroupInstance = Instance.Of<typeof Group>;
  * not-yet-yielded `instantiate` — yielded internally so JSX children need
  * no `yield*`). Normalized to a stored child id in list order.
  */
-export type Child = string | Instance.Instance | Effect.Effect<Instance.Instance, unknown, unknown>;
+export type Child = string | Instance.Instance | Effect.Effect<Instance.Instance, never, Runner>;
 /**
  * Builtin, engine-owned instance properties — namespaced with `$` and
  * held BESIDE entity data, never in the entity schema. Every entity gets
@@ -68,6 +69,7 @@ export type InstantiateProps<MakeInput> = Omit<MakeInput, "children"> & BuiltinP
 export declare const CurrentParent: Context.Reference<Instance.Instance<"shapes/Group", Schema.Struct<{
     x: Schema.withConstructorDefault<Schema.Number>;
     y: Schema.withConstructorDefault<Schema.Number>;
+    z: Schema.withConstructorDefault<Schema.Number>;
     opacity: Schema.withConstructorDefault<Schema.Number>;
     transform: Schema.withConstructorDefault<Schema.Struct<{
         readonly a: Schema.Number;
@@ -82,6 +84,7 @@ export declare const CurrentParent: Context.Reference<Instance.Instance<"shapes/
     "~position": Entity.TraitLens<Schema.Struct.ReadonlySide<{
         x: Schema.withConstructorDefault<Schema.Number>;
         y: Schema.withConstructorDefault<Schema.Number>;
+        z: Schema.withConstructorDefault<Schema.Number>;
         opacity: Schema.withConstructorDefault<Schema.Number>;
         transform: Schema.withConstructorDefault<Schema.Struct<{
             readonly a: Schema.Number;
@@ -96,6 +99,7 @@ export declare const CurrentParent: Context.Reference<Instance.Instance<"shapes/
     "~opacity": Entity.TraitLens<Schema.Struct.ReadonlySide<{
         x: Schema.withConstructorDefault<Schema.Number>;
         y: Schema.withConstructorDefault<Schema.Number>;
+        z: Schema.withConstructorDefault<Schema.Number>;
         opacity: Schema.withConstructorDefault<Schema.Number>;
         transform: Schema.withConstructorDefault<Schema.Struct<{
             readonly a: Schema.Number;
@@ -121,6 +125,7 @@ declare const Runner_base: Context.ServiceClass<Runner, "Runner", {
     root: Instance.Instance<"shapes/Group", Schema.Struct<{
         x: Schema.withConstructorDefault<Schema.Number>;
         y: Schema.withConstructorDefault<Schema.Number>;
+        z: Schema.withConstructorDefault<Schema.Number>;
         opacity: Schema.withConstructorDefault<Schema.Number>;
         transform: Schema.withConstructorDefault<Schema.Struct<{
             readonly a: Schema.Number;
@@ -135,6 +140,7 @@ declare const Runner_base: Context.ServiceClass<Runner, "Runner", {
         "~position": Entity.TraitLens<Schema.Struct.ReadonlySide<{
             x: Schema.withConstructorDefault<Schema.Number>;
             y: Schema.withConstructorDefault<Schema.Number>;
+            z: Schema.withConstructorDefault<Schema.Number>;
             opacity: Schema.withConstructorDefault<Schema.Number>;
             transform: Schema.withConstructorDefault<Schema.Struct<{
                 readonly a: Schema.Number;
@@ -149,6 +155,7 @@ declare const Runner_base: Context.ServiceClass<Runner, "Runner", {
         "~opacity": Entity.TraitLens<Schema.Struct.ReadonlySide<{
             x: Schema.withConstructorDefault<Schema.Number>;
             y: Schema.withConstructorDefault<Schema.Number>;
+            z: Schema.withConstructorDefault<Schema.Number>;
             opacity: Schema.withConstructorDefault<Schema.Number>;
             transform: Schema.withConstructorDefault<Schema.Struct<{
                 readonly a: Schema.Number;
@@ -161,14 +168,14 @@ declare const Runner_base: Context.ServiceClass<Runner, "Runner", {
             children: Schema.withConstructorDefault<Schema.$Array<Schema.String>>;
         }, "Type">, number>;
     }>;
-    instantiate: <Name extends string, Data extends Schema.Top, Traits extends Partial<Entity.EntityTraits<Data["Type"]>>, MakeInput>(entity: Entity.Entity<Name, Data, Traits, MakeInput>, props: InstantiateProps<MakeInput>) => Effect.Effect<Instance.Instance<Name, Data, Traits>, unknown, Entity.Entity<Name, Data, Traits, MakeInput> | Runner>;
+    instantiate: <Name extends string, Data extends Schema.Top, Traits extends Partial<Entity.EntityTraits<Data["Type"]>>>(entity: Entity.Entity<Name, Data, Traits>, props: InstantiateProps<Data["~type.make.in"]>) => Effect.Effect<Instance.Instance<Name, Data, Traits>, never, Runner>;
     appendChild: (parent: GroupInstance, child: Instance.Instance) => void;
     removeChild: (parent: GroupInstance, child: Instance.Instance) => void;
     settings: {
         frameRate: number;
         width: number;
         height: number;
-        backgroundColor: string;
+        backgroundColor: Color.Color;
         seed: Seed;
         maxFrames: number;
     };
@@ -186,32 +193,69 @@ declare const Runner_base: Context.ServiceClass<Runner, "Runner", {
         frameRate: number;
         width: number;
         height: number;
-        backgroundColor: string;
+        backgroundColor: Color.Color;
         camera: CameraState;
     }, never, never>;
     camera: Instance.Instance<"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: Schema.Struct.ReadonlySide<{
-                x: Schema.withConstructorDefault<Schema.Number>;
-                y: Schema.withConstructorDefault<Schema.Number>;
-                zoom: Schema.withConstructorDefault<Schema.Number>;
-            }, "Type">) => {
+            get: (data: {
+                readonly x: number;
+                readonly y: number;
+                readonly z: number;
+                readonly rotX: number;
+                readonly rotY: number;
+                readonly rotZ: number;
+                readonly focalLength: number;
+                readonly focusDistance: number;
+                readonly aperture: number;
+                readonly poiX?: number;
+                readonly poiY?: number;
+                readonly poiZ?: number;
+            }) => {
                 x: number;
                 y: number;
+                z: number;
+            };
+            set: (data: {
+                readonly x: number;
+                readonly y: number;
+                readonly z: number;
+                readonly rotX: number;
+                readonly rotY: number;
+                readonly rotZ: number;
+                readonly focalLength: number;
+                readonly focusDistance: number;
+                readonly aperture: number;
+                readonly poiX?: number;
+                readonly poiY?: number;
+                readonly poiZ?: number;
+            }, value: Entity.Position) => {
+                readonly x: number;
+                readonly y: number;
+                readonly z: number;
+                readonly rotX: number;
+                readonly rotY: number;
+                readonly rotZ: number;
+                readonly focalLength: number;
+                readonly focusDistance: number;
+                readonly aperture: number;
+                readonly poiX?: number;
+                readonly poiY?: number;
+                readonly poiZ?: 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">;
         };
     }>;
     setCamera: (instance: Instance.Instance) => void;
@@ -239,6 +283,7 @@ declare const Runner_base: Context.ServiceClass<Runner, "Runner", {
         root: Instance.Instance<"shapes/Group", Schema.Struct<{
             x: Schema.withConstructorDefault<Schema.Number>;
             y: Schema.withConstructorDefault<Schema.Number>;
+            z: Schema.withConstructorDefault<Schema.Number>;
             opacity: Schema.withConstructorDefault<Schema.Number>;
             transform: Schema.withConstructorDefault<Schema.Struct<{
                 readonly a: Schema.Number;
@@ -253,6 +298,7 @@ declare const Runner_base: Context.ServiceClass<Runner, "Runner", {
             "~position": Entity.TraitLens<Schema.Struct.ReadonlySide<{
                 x: Schema.withConstructorDefault<Schema.Number>;
                 y: Schema.withConstructorDefault<Schema.Number>;
+                z: Schema.withConstructorDefault<Schema.Number>;
                 opacity: Schema.withConstructorDefault<Schema.Number>;
                 transform: Schema.withConstructorDefault<Schema.Struct<{
                     readonly a: Schema.Number;
@@ -267,6 +313,7 @@ declare const Runner_base: Context.ServiceClass<Runner, "Runner", {
             "~opacity": Entity.TraitLens<Schema.Struct.ReadonlySide<{
                 x: Schema.withConstructorDefault<Schema.Number>;
                 y: Schema.withConstructorDefault<Schema.Number>;
+                z: Schema.withConstructorDefault<Schema.Number>;
                 opacity: Schema.withConstructorDefault<Schema.Number>;
                 transform: Schema.withConstructorDefault<Schema.Struct<{
                     readonly a: Schema.Number;
@@ -279,14 +326,14 @@ declare const Runner_base: Context.ServiceClass<Runner, "Runner", {
                 children: Schema.withConstructorDefault<Schema.$Array<Schema.String>>;
             }, "Type">, number>;
         }>;
-        instantiate: <Name extends string, Data extends Schema.Top, Traits extends Partial<Entity.EntityTraits<Data["Type"]>>, MakeInput>(entity: Entity.Entity<Name, Data, Traits, MakeInput>, props: InstantiateProps<MakeInput>) => Effect.Effect<Instance.Instance<Name, Data, Traits>, unknown, Entity.Entity<Name, Data, Traits, MakeInput> | Runner>;
+        instantiate: <Name extends string, Data extends Schema.Top, Traits extends Partial<Entity.EntityTraits<Data["Type"]>>>(entity: Entity.Entity<Name, Data, Traits>, props: InstantiateProps<Data["~type.make.in"]>) => Effect.Effect<Instance.Instance<Name, Data, Traits>, never, Runner>;
         appendChild: (parent: GroupInstance, child: Instance.Instance) => void;
         removeChild: (parent: GroupInstance, child: Instance.Instance) => void;
         settings: {
             frameRate: number;
             width: number;
             height: number;
-            backgroundColor: string;
+            backgroundColor: Color.Color;
             seed: Seed;
             maxFrames: number;
         };
@@ -304,32 +351,69 @@ declare const Runner_base: Context.ServiceClass<Runner, "Runner", {
             frameRate: number;
             width: number;
             height: number;
-            backgroundColor: string;
+            backgroundColor: Color.Color;
             camera: CameraState;
         }, never, never>;
         camera: Instance.Instance<"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: Schema.Struct.ReadonlySide<{
-                    x: Schema.withConstructorDefault<Schema.Number>;
-                    y: Schema.withConstructorDefault<Schema.Number>;
-                    zoom: Schema.withConstructorDefault<Schema.Number>;
-                }, "Type">) => {
+                get: (data: {
+                    readonly x: number;
+                    readonly y: number;
+                    readonly z: number;
+                    readonly rotX: number;
+                    readonly rotY: number;
+                    readonly rotZ: number;
+                    readonly focalLength: number;
+                    readonly focusDistance: number;
+                    readonly aperture: number;
+                    readonly poiX?: number;
+                    readonly poiY?: number;
+                    readonly poiZ?: number;
+                }) => {
                     x: number;
                     y: number;
+                    z: number;
+                };
+                set: (data: {
+                    readonly x: number;
+                    readonly y: number;
+                    readonly z: number;
+                    readonly rotX: number;
+                    readonly rotY: number;
+                    readonly rotZ: number;
+                    readonly focalLength: number;
+                    readonly focusDistance: number;
+                    readonly aperture: number;
+                    readonly poiX?: number;
+                    readonly poiY?: number;
+                    readonly poiZ?: number;
+                }, value: Entity.Position) => {
+                    readonly x: number;
+                    readonly y: number;
+                    readonly z: number;
+                    readonly rotX: number;
+                    readonly rotY: number;
+                    readonly rotZ: number;
+                    readonly focalLength: number;
+                    readonly focusDistance: number;
+                    readonly aperture: number;
+                    readonly poiX?: number;
+                    readonly poiY?: number;
+                    readonly poiZ?: 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">;
             };
         }>;
         setCamera: (instance: Instance.Instance) => void;

package/dist/Runner.js

@@ -1,11 +1,13 @@
 import { Layer } from "effect";
 import * as Context from "effect/Context";
 import * as Effect from "effect/Effect";
-import { Camera, IDENTITY } from "./Camera";
-import * as Instance from "./Instance";
-import * as Phaser from "./Phaser";
-import { Group } from "./shapes/Group";
-import { Text } from "./shapes/Text";
+import { Camera, identity } from "./Camera.js";
+import * as Color from "./Color.js";
+import * as Instance from "./Instance.js";
+import * as Phaser from "./Phaser.js";
+import * as Projection from "./Projection.js";
+import { Group } from "./shapes/Group.js";
+import { Text } from "./shapes/Text.js";
 export const TypeId = "~motion/SceneRunner";
 /** conventional id of the implicit root group every instance attaches to */
 export const ROOT_ID = "root";
@@ -47,7 +49,7 @@ export class Runner extends Context.Service()("Runner", {
             // ($visible is set explicitly by instantiate when overridden)
             const prev = instances[instance.id];
             instances[instance.id] = {
-                data: instance.entity.make(data),
+                data: instance.entity.data.make(data),
                 entity: instance.entity,
                 $visible: prev?.$visible ?? true,
             };
@@ -66,7 +68,7 @@ export class Runner extends Context.Service()("Runner", {
             frameRate: settings.frameRate ?? 60,
             width: settings.width ?? 500,
             height: settings.height ?? 300,
-            backgroundColor: settings.backgroundColor ?? "#16161d",
+            backgroundColor: settings.backgroundColor ?? Color.rgba(22, 22, 29),
             seed: settings.seed ?? defaultSeed,
             maxFrames: settings.maxFrames ?? 36_000,
         };
@@ -78,13 +80,13 @@ export class Runner extends Context.Service()("Runner", {
         // camera is present from the start, so `depth`/zoom work with no author
         // ceremony; `setCamera` swaps which instance is active.
         const camera = Instance.make(Camera, "camera");
-        setDataUnsafe(camera, {});
+        setDataUnsafe(camera, identity(resolvedSettings.width));
         let activeCameraId = camera.id;
         const cameraState = () => {
             const data = instances[activeCameraId]?.data;
             // a destroyed active camera falls back to identity rather than dying:
             // the view is not scene-critical state
-            return data ?? IDENTITY;
+            return data ?? identity(resolvedSettings.width);
         };
         // append `id` to a group's children and record it as the child's parent
         const attach = (parent, id) => {
@@ -152,17 +154,40 @@ export class Runner extends Context.Service()("Runner", {
             instantiate: Effect.fnUntraced(function* (entity, props) {
                 // peel off builtin ($visible) and polymorphic children before the
                 // schema constructs the data — neither is an entity-data field
-                const { $visible, children, ...rest } = props;
+                // = props
                 // children are born (via normalizeChildren) attached to their
                 // ambient parent — reparent them into THIS instance below
-                const childIds = children === undefined
-                    ? undefined
-                    : yield* normalizeChildren(children);
-                const dataInput = childIds === undefined ? rest : { ...rest, children: childIds };
+                const childIds = "children" in props && props.children
+                    ? yield* normalizeChildren(props.children)
+                    : undefined;
                 const id = generateId(entity.name);
                 const instance = Instance.make(entity, id);
-                setDataUnsafe(instance, dataInput);
-                if ($visible === false) {
+                // cameras get width-relative z/focalLength defaults filled here
+                // (AE's 50mm equivalent — see Camera.ts): the schema can't default
+                // them because only the Runner knows the scene width. Filling for
+                // EVERY Camera instance (not just the built-in one) keeps a
+                // setCamera swap from jumping zoom.
+                const cameraDefaults = (() => {
+                    if (entity.name !== Camera.name) {
+                        return undefined;
+                    }
+                    const p = props;
+                    const focalLength = p.focalLength ??
+                        Projection.defaultFocalLength(resolvedSettings.width);
+                    return {
+                        focalLength,
+                        z: p.z ?? focalLength,
+                        // depth of field: focus at the resting distance by default,
+                        // so the z=0 plane is sharp for an untouched camera
+                        focusDistance: p.focusDistance ?? focalLength,
+                    };
+                })();
+                setDataUnsafe(instance, {
+                    ...props,
+                    ...cameraDefaults,
+                    children: childIds,
+                });
+                if (props.$visible === false) {
                     setVisibleUnsafe(id, false);
                 }
                 // cameras are view state, not tree nodes: they live in `instances`
@@ -230,7 +255,7 @@ export class Runner extends Context.Service()("Runner", {
                         instances[id] = {
                             entity: entry.entity,
                             $visible: entry.$visible,
-                            data: entry.entity.make({
+                            data: entry.entity.data.make({
                                 ...entry.data,
                                 children: children.filter((child) => child !== instance.id),
                             }),