effect-motion 0.4.0 → 0.5.0

package/dist/Runner.js

@@ -1,17 +1,22 @@
 import { Layer } from "effect";
 import * as Context from "effect/Context";
 import * as Effect from "effect/Effect";
-import { Camera, identity } from "./Camera.js";
 import * as Color from "./Color.js";
+import * as Entity from "./Entity.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";
+import { ROOT_ID, Tree } from "./Tree.js";
 export const TypeId = "~motion/SceneRunner";
-/** conventional id of the implicit root group every instance attaches to */
-export const ROOT_ID = "root";
-/** the fixed default: scenes are deterministic even with no seed set */
+export { ROOT_ID };
+/**
+ * The seed used when none is given.
+ *
+ * @remarks
+ * Fixed rather than random on purpose: a scene using randomness still
+ * produces identical frames on every run unless you deliberately vary the
+ * seed.
+ */
 export const defaultSeed = "effect-motion";
 export const defaultComp = {
     width: 1920,
@@ -23,13 +28,48 @@ export const defaultComp = {
  * evaluation (`Scene.play({ parent })`); `null` means the runner root.
  */
 export const CurrentParent = Context.Reference("motion/Runner/CurrentParent", { defaultValue: () => null });
+const nodeNotFound = (id) => {
+    throw new Error(`Runner: node "${id}" not found`);
+};
+/**
+ * The entity → view bridge. `Projection.CameraView` is flat (x/y/z,
+ * rotX/rotY/rotZ) while the Camera entity nests position/rotation, so the
+ * conversion happens HERE, once, at the frame boundary — the renderer and
+ * the projection math keep the contract they already had.
+ */
+const toCameraView = (camera) => ({
+    x: camera.position.x,
+    y: camera.position.y,
+    z: camera.position.z,
+    rotX: camera.rotation.x,
+    rotY: camera.rotation.y,
+    rotZ: camera.rotation.z,
+    focalLength: camera.focalLength,
+    focusDistance: camera.focusDistance,
+    aperture: camera.aperture,
+    ...(camera.poi === null
+        ? {}
+        : { poiX: camera.poi.x, poiY: camera.poi.y, poiZ: camera.poi.z }),
+});
+/**
+ * The resting camera for a comp of the given width: width-relative focal
+ * length (AE's 50mm equivalent), positioned so the z=0 plane projects at
+ * scale 1 and is in focus.
+ */
+export const identityCameraView = (width) => toCameraView(identityCamera(width));
+export const identityCamera = (width) => {
+    const focalLength = Projection.defaultFocalLength(width);
+    const z = Projection.defaultCameraZ(focalLength);
+    return Entity.Camera.make({
+        position: Entity.vec3({ x: 0, y: 0, z }),
+        focalLength,
+        focusDistance: z,
+        aperture: 0,
+    });
+};
 export class Runner extends Context.Service()("Runner", {
     make: Effect.fnUntraced(function* (settings = {}, comp = defaultComp) {
-        const instances = {};
-        // each instance's current parent group id (or null = detached / root).
-        // Tracked so appendChild detaches from the old parent in O(1) rather
-        // than scanning the tree. The root is not tracked (it has no parent).
-        const parentOf = {};
+        const tree = new Tree();
         const phaser = yield* Phaser.Phaser.make;
         // concurrent branches spawned by Scene.fork / Scene.play /
         // Scene.background. `forks` hold the scene's end hostage until their
@@ -45,28 +85,28 @@ export class Runner extends Context.Service()("Runner", {
         // first NON-finished branch failure; failures in a tail (after
         // Scene.finish) are deliberately not reported
         let failure;
-        let idCounter = 0;
-        const generateId = (name) => {
-            return `${name}_${idCounter++}`;
-        };
-        const setDataUnsafe = (instance, data) => {
-            // preserve $visible across data updates; new instances default visible
-            // ($visible is set explicitly by instantiate when overridden)
-            const prev = instances[instance.id];
-            instances[instance.id] = {
-                data: instance.entity.data.make(data),
-                entity: instance.entity,
-                $visible: prev?.$visible ?? true,
-            };
-        };
-        const setVisibleUnsafe = (id, visible) => {
-            const entry = instances[id];
-            if (entry !== undefined) {
-                instances[id] = { ...entry, $visible: visible };
-            }
+        /**
+         * Mounted scenes, by the id of the group they mount under.
+         *
+         * A comp is a render-to-texture boundary — its own scene, render
+         * target, and identity camera — created ONLY by `Scene.play`. It used
+         * to be inferred from a Group carrying width/height, which duplicated
+         * what the child Scene already owned and made "is this a comp" a
+         * question about field presence. It is now declared here explicitly.
+         */
+        const comps = new Map();
+        const setDataUnsafe = (instance, state) => {
+            const entry = tree.getEntry(instance.id) ?? nodeNotFound(instance.id);
+            entry.state = state;
         };
         const getDataUnsafe = (instance) => {
-            return instances[instance.id]?.data ?? null;
+            const entry = tree.getEntry(instance.id);
+            if (entry === null) {
+                return null;
+            }
+            // the instance's tag names the entry's state; the tree stores mixed
+            // tags, so this is the one place the two are reconciled
+            return entry.state;
         };
         const resolvedSettings = {
             ...settings,
@@ -74,61 +114,38 @@ export class Runner extends Context.Service()("Runner", {
             seed: settings.seed ?? defaultSeed,
             maxFrames: settings.maxFrames ?? 36_000,
         };
-        // the root group: never rendered itself, holds the top level
-        const root = Instance.make(Group, ROOT_ID);
-        setDataUnsafe(root, {});
-        // the active camera: an ordinary instance (so the animators drive it),
-        // never registered with a sink so it never draws. A default identity
-        // 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, identity(comp.width));
+        // the root group: never rendered itself, holds the top level. Its
+        // entry is created by the tree itself.
+        const root = Instance.makeInstance(ROOT_ID, "Group");
+        // the active camera: an ordinary tree node (so the animators drive it),
+        // never rendered. A default resting camera is present from the start,
+        // so depth/zoom work with no author ceremony; `setCamera` swaps which
+        // instance is active.
+        tree.createNode(identityCamera(comp.width), "camera");
+        const camera = Instance.makeInstance("camera", "Camera");
         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(comp.width);
-        };
-        // append `id` to a group's children and record it as the child's parent
-        const attach = (parent, id) => {
-            const data = getDataUnsafe(parent);
-            if (data === null) {
-                throw new Error(`Runner: parent group "${parent.id}" was destroyed`);
+            const entry = tree.getEntry(activeCameraId);
+            // a destroyed (or swapped-to-non-camera) active camera falls back to
+            // the resting view rather than dying: the view is not scene-critical
+            if (entry === null || entry.state._tag !== "Camera") {
+                return toCameraView(identityCamera(comp.width));
             }
-            setDataUnsafe(parent, { ...data, children: [...data.children, id] });
-            parentOf[id] = parent.id;
+            return toCameraView(entry.state);
         };
-        // remove `id` from its current parent's children (O(1) via parentOf),
-        // leaving it detached. No-op if already detached or parent is gone.
-        const detach = (id) => {
-            const parentId = parentOf[id];
-            if (parentId == null) {
-                return;
-            }
-            const parentEntry = instances[parentId];
-            const children = parentEntry?.data
-                ?.children;
-            if (parentEntry !== undefined && Array.isArray(children)) {
-                setDataUnsafe({ id: parentId, entity: parentEntry.entity }, {
-                    ...parentEntry.data,
-                    children: children.filter((c) => c !== id),
-                });
-            }
-            parentOf[id] = null;
-        };
-        // move `child` under `parent`: detach from its current parent first
-        // (so it is never double-referenced), then attach.
+        // move `child` under `parent`: the tree detaches it from its current
+        // parent first, so it is never double-referenced.
         const appendChild = (parent, child) => {
-            if (instances[child.id] === undefined) {
+            const childEntry = tree.getEntry(child.id);
+            if (childEntry === null) {
                 throw new Error(`Runner: child "${child.id}" was destroyed`);
             }
-            detach(child.id);
-            attach(parent, child.id);
+            tree.appendChild(parent.id, childEntry);
         };
         const removeChild = (parent, child) => {
-            if (parentOf[child.id] === parent.id) {
-                detach(child.id);
+            const entry = tree.getEntry(child.id);
+            if (entry !== null && entry.parentId === parent.id) {
+                tree.removeFromParent(entry);
             }
         };
         // normalize a polymorphic children list into stored child ids, in
@@ -138,8 +155,8 @@ export class Runner extends Context.Service()("Runner", {
             const ids = [];
             for (const child of children) {
                 if (typeof child === "string") {
-                    const child$ = yield* self.instantiate(Text, { text: child });
-                    ids.push(child$.id);
+                    const text = yield* self.instantiate("Text", { text: child });
+                    ids.push(text.id);
                 }
                 else if (Instance.isInstance(child)) {
                     ids.push(child.id);
@@ -153,60 +170,39 @@ export class Runner extends Context.Service()("Runner", {
         });
         const self = {
             root,
-            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
-                // = props
-                // children are born (via normalizeChildren) attached to their
-                // ambient parent — reparent them into THIS instance below
-                const childIds = "children" in props && props.children
-                    ? yield* normalizeChildren(props.children)
-                    : undefined;
-                const id = generateId(entity.name);
-                const instance = Instance.make(entity, id);
+            instantiate: Effect.fnUntraced(function* (kind, props) {
+                const raw = props;
+                const children = Array.isArray(raw.children)
+                    ? raw.children
+                    : [];
+                const childIds = children.length > 0 ? yield* normalizeChildren(children) : undefined;
                 // 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(comp.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,
+                // (AE's 50mm equivalent): the schema cannot default them because
+                // only the Runner knows the comp width. Filled for EVERY Camera,
+                // not just the built-in one, so a setCamera swap never jumps zoom.
+                const defaults = kind === "Camera" ? cameraDefaults(raw, comp.width) : undefined;
+                // raw children never reach stored data: normalized ids are
+                // appended through the tree below, in list order
+                const { children: _children, ...rest } = raw;
+                const definition = Entity.getEntityDefinitionByTag(kind);
+                const state = definition.make({
+                    ...rest,
+                    ...defaults,
                 });
-                if (props.$visible === false) {
-                    setVisibleUnsafe(id, false);
-                }
-                // cameras are view state, not tree nodes: they live in `instances`
-                // so the animators drive them, but must NOT be mounted into the
-                // render tree (no sink renders a Camera — the renderer would die on
-                // the unknown entity). Everything else mounts under the ambient
-                // parent (Scene.play), defaulting to root.
-                if (entity.name !== Camera.name) {
+                const entry = tree.createNode(state);
+                const instance = Instance.makeInstance(entry.id, kind);
+                // cameras are view state, not scene content: they live in the tree
+                // so the animators drive them, but must NOT be mounted under a
+                // group. Everything else mounts under the ambient parent.
+                if (kind !== "Camera") {
                     const ambient = yield* CurrentParent;
-                    attach(ambient ?? root, id);
+                    tree.appendChild((ambient ?? root).id, entry);
                 }
                 // adopt listed children: they were attached to the ambient parent
-                // at birth; detach them there and record this instance as parent
-                // (their ids already live in this instance's `children` data)
+                // at birth; appendChild moves each under this instance in order
                 if (childIds !== undefined) {
                     for (const childId of childIds) {
-                        detach(childId);
-                        parentOf[childId] = id;
+                        tree.appendChild(entry, childId);
                     }
                 }
                 return instance;
@@ -224,21 +220,48 @@ export class Runner extends Context.Service()("Runner", {
             getDataUnsafe,
             setDataUnsafe,
             state: Effect.sync(() => {
-                // the active camera lives in `instances` so the animators drive it,
-                // but it is view state, not a renderable instance — omit it from the
-                // frame's instance map (its data is surfaced separately as `camera`)
-                const { [activeCameraId]: _camera, ...renderable } = instances;
+                // the active camera lives in the tree so the animators drive it,
+                // but it is view state, not a renderable instance — omit it from
+                // the frame's instance map (its data is surfaced as `camera`)
+                const instances = {};
+                for (const [id, entry] of Object.entries(tree.map)) {
+                    if (id === activeCameraId) {
+                        continue;
+                    }
+                    instances[id] = { data: entry.state };
+                }
                 return {
-                    instances: renderable,
+                    instances,
                     root: ROOT_ID,
                     frameRate: resolvedSettings.frameRate,
                     width: comp.width,
                     height: comp.height,
                     backgroundColor: comp.backgroundColor,
                     camera: cameraState(),
+                    // mounted scenes, by mount-group id: the renderer reads this
+                    // to know a subtree is a render-to-texture boundary, instead
+                    // of inferring it from a group carrying a size
+                    comps: Object.fromEntries(comps),
                 };
             }),
-            // the default identity camera (animate it, or swap via setCamera)
+            /**
+             * ponytail: create a tree node for an entity that is NOT in the
+             * union — the particle system only (design D10). Mounts under the
+             * ambient parent like any instance. Delete with the particles
+             * rewrite; see `particlesEscapeInstantiate`.
+             */
+            instantiateEscape: Effect.fnUntraced(function* (state) {
+                const entry = tree.createNode(state);
+                const ambient = yield* CurrentParent;
+                tree.appendChild((ambient ?? root).id, entry);
+                return Instance.makeInstance(entry.id, state._tag);
+            }),
+            // declare the group at `id` to be a mounted scene with these bounds
+            // (see `comps`); called by Scene.play, never by authors
+            registerComp: (id, config) => {
+                comps.set(id, config);
+            },
+            // the default resting camera (animate it, or swap via setCamera)
             camera,
             // swap the active camera to another instance; its live data becomes
             // the view on every subsequent frame
@@ -246,25 +269,11 @@ export class Runner extends Context.Service()("Runner", {
                 activeCameraId = instance.id;
             },
             destroy: (instance) => {
-                // O(1) detach from the tracked parent, then drop the instance
-                detach(instance.id);
-                delete instances[instance.id];
-                delete parentOf[instance.id];
-                // backstop scan: stays correct even after manual reparenting via
-                // raw data updates (which bypass parentOf tracking)
-                for (const [id, entry] of Object.entries(instances)) {
-                    const children = entry.data.children;
-                    if (Array.isArray(children) && children.includes(instance.id)) {
-                        instances[id] = {
-                            entity: entry.entity,
-                            $visible: entry.$visible,
-                            data: entry.entity.data.make({
-                                ...entry.data,
-                                children: children.filter((child) => child !== instance.id),
-                            }),
-                        };
-                    }
+                // double-destroy is a no-op, like the old map-based delete
+                if (tree.getEntry(instance.id) === null) {
+                    return;
                 }
+                tree.remove(instance.id);
             },
             phaser,
             forks,
@@ -282,4 +291,42 @@ export class Runner extends Context.Service()("Runner", {
     }),
 }) {
 }
+/**
+ * Width-relative camera defaults the schema cannot express, since only the
+ * Runner knows the comp width. Applied to any Camera at instantiate.
+ */
+const cameraDefaults = (props, width) => {
+    const position = props.position;
+    const focalLength = typeof props.focalLength === "number" && props.focalLength !== 0
+        ? props.focalLength
+        : Projection.defaultFocalLength(width);
+    const restingZ = Projection.defaultCameraZ(focalLength);
+    return {
+        focalLength,
+        position: Entity.vec3({
+            x: position?.x ?? 0,
+            y: position?.y ?? 0,
+            z: position?.z ?? restingZ,
+        }),
+        // depth of field: focus at the resting distance by default, so the
+        // z=0 plane is sharp for an untouched camera
+        focusDistance: typeof props.focusDistance === "number" && props.focusDistance !== 0
+            ? props.focusDistance
+            : restingZ,
+    };
+};
 export const layer = Layer.effect(Runner, Runner.make());
+/** the tag particle fields are stored under; never a union member */
+export const PARTICLE_FIELD_TAG = "particles/ParticleField";
+/** instantiate a non-union entity. Particles only. */
+export const particlesEscapeInstantiate = (runner, state) => 
+// bypasses the tag→EntityMap lookup, which by construction has no
+// ParticleField. The state is stored verbatim; only particles read it.
+runner.instantiateEscape({
+    ...state,
+    _tag: PARTICLE_FIELD_TAG,
+});
+/** read a non-union entity's state. Particles only. */
+export const particlesEscapeRead = (runner, instance) => runner.getDataUnsafe(instance);
+/** write a non-union entity's state. Particles only. */
+export const particlesEscapeWrite = (runner, instance, state) => runner.setDataUnsafe(instance, state);