effect-motion 0.4.0 → 0.6.0

package/dist/Runner.d.ts

@@ -3,43 +3,81 @@ import type * as Cause from "effect/Cause";
 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.js";
 import * as Color from "./Color.js";
-import type * as Entity from "./Entity.js";
+import * as Entity from "./Entity.js";
 import * as Instance from "./Instance.js";
-import { Group } from "./shapes/Group.js";
+import * as Projection from "./Projection.js";
+import { ROOT_ID } from "./Tree.js";
 export declare const TypeId: "~motion/SceneRunner";
-/** conventional id of the implicit root group every instance attaches to */
-export declare const ROOT_ID = "root";
+export { ROOT_ID };
 export type Seed = number | string;
-/** the fixed default: scenes are deterministic even with no seed set */
+/**
+ * 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 declare const defaultSeed: Seed;
 /**
- * Playback settings — how the movie RUNS. What the movie IS (resolution,
- * background) lives on the root scene as its composition config.
+ * Playback settings — how a scene RUNS, as opposed to what it IS.
+ *
+ * @remarks
+ * Passed to `Scene.run` / `Scene.stream`, so the same scene can be played
+ * back at different rates or seeds without being rewritten. Resolution and
+ * background are NOT here: those are the composition's own identity, fixed
+ * at `Scene.make`.
  */
 export type Settings = {
+    /**
+     * Frames produced per second of scene time.
+     *
+     * @remarks
+     * Determines how many frames a given duration becomes: a one-second
+     * animation is 30 frames at 30fps and 60 at 60fps. It changes the
+     * sampling, never the motion — the same scene looks the same, just
+     * smoother.
+     *
+     * @defaultValue `60`
+     */
     frameRate: number;
     /**
-     * seeds the scene's pseudo-random service (effect's Random via
-     * withSeed); the fixed default keeps default-constructed scenes
-     * byte-identical across runs. Note: the generator algorithm belongs
-     * to effect, so upgrading effect may change seeded sequences.
+     * Seeds the scene's random number generator.
+     *
+     * @remarks
+     * Randomness in a scene comes from this seed rather than
+     * `Math.random()`, so the "random" scatter of a particle field is
+     * identical on every run. Change the seed to get a different arrangement
+     * that is itself reproducible.
+     *
+     * Note the generator belongs to `effect`, so upgrading it can change the
+     * sequence a given seed produces.
+     *
+     * @defaultValue `"effect-motion"`
      */
     seed: Seed;
     /**
-     * hard cap on frames a scene may produce (default 36_000 — 10 minutes
-     * at 60fps): a scene that exceeds it dies instead of hanging the
-     * consumer. Set to `Infinity` to declare an intentionally infinite
-     * scene.
+     * Hard cap on how many frames a scene may produce.
+     *
+     * @remarks
+     * A safety net: a scene that exceeds it fails with a message naming the
+     * limit instead of hanging whatever is consuming it. The usual cause is
+     * an unbounded loop with nothing to end it.
+     *
+     * Set it to `Infinity` to declare a deliberately endless scene.
+     *
+     * @defaultValue `36_000` — ten minutes at 60fps
      */
     maxFrames: number;
 };
 /**
- * A scene's composition config, After Effects–style: what the comp IS.
- * The runner inherits the ROOT scene's config; a nested scene keeps its
- * own as its bounds (see Scene.play).
+ * What a composition IS: its pixel dimensions and background.
+ *
+ * @remarks
+ * Set at `Scene.make` and carried on every frame, so a frame is
+ * self-describing. A nested scene keeps its own config as its bounds — that
+ * is what a played scene clips and paints within.
  */
 export type CompConfig = {
     width: number;
@@ -48,7 +86,8 @@ export type CompConfig = {
     backgroundColor: Color.Color;
 };
 export declare const defaultComp: CompConfig;
-export type GroupInstance = Instance.Of<typeof Group>;
+/** A handle to a container (`Group` or `Hud`) — the only mountable parents. */
+export type GroupInstance = Instance.Instance<Entity.ContainerTag>;
 /**
  * A child in a polymorphic `children` list: a plain string (→ a `Text`),
  * an already-created `Instance`, or an `Effect` that resolves to one (a
@@ -57,81 +96,19 @@ export type GroupInstance = Instance.Of<typeof Group>;
  */
 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
- * them uniformly. `$visible` defaults to `true`.
+ * The input `instantiate` accepts: the entity's own make-input, except that
+ * a `children` field (stored as `Array<string>` of ids) is authored as the
+ * polymorphic {@link Child} list — the runner normalizes it to ids in list
+ * order.
  */
-export interface BuiltinProps {
-    readonly $visible?: boolean;
-}
-/**
- * The input accepted by `instantiate`: an entity's own make-input, plus
- * builtin props ($visible), plus — when the entity has a `children` field
- * — a polymorphic `children` list (strings/instances/effects) in place of
- * the stored `Array<string>` of ids.
- */
-export type InstantiateProps<MakeInput> = Omit<MakeInput, "children"> & BuiltinProps & ("children" extends keyof MakeInput ? {
+export type InstantiateProps<Tag extends Entity.EntityTag> = Omit<Entity.MakeInput<Tag>, "children"> & (Tag extends Entity.ContainerTag ? {
     readonly children?: ReadonlyArray<Child>;
 } : Record<never, never>);
 /**
  * The ambient mount parent for `instantiate` — provided per scene
  * evaluation (`Scene.play({ parent })`); `null` means the runner root.
  */
-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;
-        readonly b: Schema.Number;
-        readonly c: Schema.Number;
-        readonly d: Schema.Number;
-        readonly e: Schema.Number;
-        readonly f: Schema.Number;
-    }>>;
-    width: Schema.optionalKey<Schema.Number>;
-    height: Schema.optionalKey<Schema.Number>;
-    backgroundColor: Schema.optionalKey<typeof Color.Color>;
-    children: Schema.withConstructorDefault<Schema.$Array<Schema.String>>;
-}>, {
-    "~position": Entity.TraitLens<{
-        readonly x: number;
-        readonly y: number;
-        readonly z: number;
-        readonly opacity: number;
-        readonly transform: Schema.Struct.ReadonlySide<{
-            readonly a: Schema.Number;
-            readonly b: Schema.Number;
-            readonly c: Schema.Number;
-            readonly d: Schema.Number;
-            readonly e: Schema.Number;
-            readonly f: Schema.Number;
-        }, "Type">;
-        readonly width?: number;
-        readonly height?: number;
-        readonly backgroundColor?: Color.Color;
-        readonly children: readonly string[];
-    }, Entity.Position>;
-    "~opacity": Entity.TraitLens<{
-        readonly x: number;
-        readonly y: number;
-        readonly z: number;
-        readonly opacity: number;
-        readonly transform: Schema.Struct.ReadonlySide<{
-            readonly a: Schema.Number;
-            readonly b: Schema.Number;
-            readonly c: Schema.Number;
-            readonly d: Schema.Number;
-            readonly e: Schema.Number;
-            readonly f: Schema.Number;
-        }, "Type">;
-        readonly width?: number;
-        readonly height?: number;
-        readonly backgroundColor?: Color.Color;
-        readonly children: readonly string[];
-    }, number>;
-}> | null>;
+export declare const CurrentParent: Context.Reference<GroupInstance | null>;
 /**
  * A branch of animation as the runner tracks it: its fiber and its
  * SEMANTIC end (`finished` resolves at `Scene.finish` or completion,
@@ -141,63 +118,16 @@ export interface BranchEntry {
     readonly fiber: Fiber.Fiber<unknown, unknown>;
     readonly finished: Effect.Effect<void>;
 }
+/**
+ * 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 declare const identityCameraView: (width: number) => Projection.CameraView & Projection.PointOfInterest;
+export declare const identityCamera: (width: number) => Entity.EntityByTag<"Camera">;
 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;
-            readonly b: Schema.Number;
-            readonly c: Schema.Number;
-            readonly d: Schema.Number;
-            readonly e: Schema.Number;
-            readonly f: Schema.Number;
-        }>>;
-        width: Schema.optionalKey<Schema.Number>;
-        height: Schema.optionalKey<Schema.Number>;
-        backgroundColor: Schema.optionalKey<typeof Color.Color>;
-        children: Schema.withConstructorDefault<Schema.$Array<Schema.String>>;
-    }>, {
-        "~position": Entity.TraitLens<{
-            readonly x: number;
-            readonly y: number;
-            readonly z: number;
-            readonly opacity: number;
-            readonly transform: Schema.Struct.ReadonlySide<{
-                readonly a: Schema.Number;
-                readonly b: Schema.Number;
-                readonly c: Schema.Number;
-                readonly d: Schema.Number;
-                readonly e: Schema.Number;
-                readonly f: Schema.Number;
-            }, "Type">;
-            readonly width?: number;
-            readonly height?: number;
-            readonly backgroundColor?: Color.Color;
-            readonly children: readonly string[];
-        }, Entity.Position>;
-        "~opacity": Entity.TraitLens<{
-            readonly x: number;
-            readonly y: number;
-            readonly z: number;
-            readonly opacity: number;
-            readonly transform: Schema.Struct.ReadonlySide<{
-                readonly a: Schema.Number;
-                readonly b: Schema.Number;
-                readonly c: Schema.Number;
-                readonly d: Schema.Number;
-                readonly e: Schema.Number;
-                readonly f: Schema.Number;
-            }, "Type">;
-            readonly width?: number;
-            readonly height?: number;
-            readonly backgroundColor?: Color.Color;
-            readonly children: readonly string[];
-        }, number>;
-    }>;
-    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>;
+    root: GroupInstance;
+    instantiate: <Tag extends Entity.EntityTag>(kind: Tag, props: InstantiateProps<Tag>) => Effect.Effect<Instance.Instance<Tag>, never, Runner>;
     appendChild: (parent: GroupInstance, child: Instance.Instance) => void;
     removeChild: (parent: GroupInstance, child: Instance.Instance) => void;
     settings: {
@@ -206,87 +136,327 @@ declare const Runner_base: Context.ServiceClass<Runner, "Runner", {
         maxFrames: number;
     };
     comp: CompConfig;
-    getDataUnsafe: <Name extends string, Data extends Schema.Top>(instance: Instance.Instance<Name, Data>) => Data["Type"] | null;
-    setDataUnsafe: <Name extends string, Data extends Schema.Top>(instance: Instance.Instance<Name, Data>, data: unknown) => void;
+    getDataUnsafe: <Tag extends Entity.EntityTag>(instance: Instance.Instance<Tag>) => Entity.EntityByTag<Tag> | null;
+    setDataUnsafe: <Tag extends Entity.EntityTag>(instance: Instance.Instance<Tag>, state: Entity.EntityByTag<Tag>) => void;
     state: Effect.Effect<{
-        instances: {
-            [x: string]: {
-                data: unknown;
-                entity: Entity.AnyEntity;
-                $visible: boolean;
-            };
-        };
+        instances: Record<string, {
+            data: Entity.Entity;
+        }>;
         root: string;
         frameRate: number;
         width: number;
         height: number;
         backgroundColor: Color.Color;
-        camera: CameraState;
+        camera: Projection.CameraView & Projection.PointOfInterest;
+        comps: {
+            [k: string]: CompConfig;
+        };
     }, never, never>;
-    camera: Instance.Instance<"Camera", Schema.Struct<{
-        x: Schema.withConstructorDefault<Schema.Number>;
-        y: 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: {
-                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;
-            };
-        };
-    }>;
-    setCamera: (instance: Instance.Instance) => void;
-    destroy: <Name extends string, Data extends Schema.Top>(instance: Instance.Instance<Name, Data>) => void;
+    /**
+     * 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: (state: {
+        readonly _tag: "Camera";
+        readonly position: {
+            readonly _tag: "Vec3";
+            readonly x: number;
+            readonly y: number;
+            readonly z: number;
+        };
+        readonly rotation: {
+            readonly _tag: "Vec3";
+            readonly x: number;
+            readonly y: number;
+            readonly z: number;
+        };
+        readonly focalLength: number;
+        readonly focusDistance: number;
+        readonly aperture: number;
+        readonly poi: {
+            readonly _tag: "Vec3";
+            readonly x: number;
+            readonly y: number;
+            readonly z: number;
+        } | null;
+    } | {
+        readonly _tag: "Circle";
+        readonly position: {
+            readonly _tag: "Vec3";
+            readonly x: number;
+            readonly y: number;
+            readonly z: number;
+        };
+        readonly rotation: {
+            readonly _tag: "Vec3";
+            readonly x: number;
+            readonly y: number;
+            readonly z: number;
+        };
+        readonly scale: {
+            readonly _tag: "Vec3";
+            readonly x: number;
+            readonly y: number;
+            readonly z: number;
+        };
+        readonly opacity: number;
+        readonly visible: boolean;
+        readonly strokeWidth: number;
+        readonly strokeColor: Color.Color;
+        readonly fillColor: Color.Color;
+        readonly radius: number;
+    } | {
+        readonly _tag: "Ellipse";
+        readonly position: {
+            readonly _tag: "Vec3";
+            readonly x: number;
+            readonly y: number;
+            readonly z: number;
+        };
+        readonly rotation: {
+            readonly _tag: "Vec3";
+            readonly x: number;
+            readonly y: number;
+            readonly z: number;
+        };
+        readonly scale: {
+            readonly _tag: "Vec3";
+            readonly x: number;
+            readonly y: number;
+            readonly z: number;
+        };
+        readonly opacity: number;
+        readonly visible: boolean;
+        readonly strokeWidth: number;
+        readonly strokeColor: Color.Color;
+        readonly fillColor: Color.Color;
+        readonly radiusX: number;
+        readonly radiusY: number;
+    } | {
+        readonly _tag: "Group";
+        readonly position: {
+            readonly _tag: "Vec3";
+            readonly x: number;
+            readonly y: number;
+            readonly z: number;
+        };
+        readonly rotation: {
+            readonly _tag: "Vec3";
+            readonly x: number;
+            readonly y: number;
+            readonly z: number;
+        };
+        readonly scale: {
+            readonly _tag: "Vec3";
+            readonly x: number;
+            readonly y: number;
+            readonly z: number;
+        };
+        readonly opacity: number;
+        readonly visible: boolean;
+        readonly children: readonly string[];
+    } | {
+        readonly _tag: "Hud";
+        readonly position: {
+            readonly _tag: "Vec3";
+            readonly x: number;
+            readonly y: number;
+            readonly z: number;
+        };
+        readonly rotation: {
+            readonly _tag: "Vec3";
+            readonly x: number;
+            readonly y: number;
+            readonly z: number;
+        };
+        readonly scale: {
+            readonly _tag: "Vec3";
+            readonly x: number;
+            readonly y: number;
+            readonly z: number;
+        };
+        readonly opacity: number;
+        readonly visible: boolean;
+        readonly children: readonly string[];
+    } | {
+        readonly _tag: "Image";
+        readonly position: {
+            readonly _tag: "Vec3";
+            readonly x: number;
+            readonly y: number;
+            readonly z: number;
+        };
+        readonly rotation: {
+            readonly _tag: "Vec3";
+            readonly x: number;
+            readonly y: number;
+            readonly z: number;
+        };
+        readonly scale: {
+            readonly _tag: "Vec3";
+            readonly x: number;
+            readonly y: number;
+            readonly z: number;
+        };
+        readonly opacity: number;
+        readonly visible: boolean;
+        readonly image: {
+            readonly _tag: "effect-motion/Resources/Image";
+            readonly id: string;
+        };
+        readonly width?: number;
+        readonly height?: number;
+    } | {
+        readonly _tag: "Line";
+        readonly position: {
+            readonly _tag: "Vec3";
+            readonly x: number;
+            readonly y: number;
+            readonly z: number;
+        };
+        readonly rotation: {
+            readonly _tag: "Vec3";
+            readonly x: number;
+            readonly y: number;
+            readonly z: number;
+        };
+        readonly scale: {
+            readonly _tag: "Vec3";
+            readonly x: number;
+            readonly y: number;
+            readonly z: number;
+        };
+        readonly opacity: number;
+        readonly visible: boolean;
+        readonly strokeWidth: number;
+        readonly strokeColor: Color.Color;
+        readonly start: {
+            readonly _tag: "Vec3";
+            readonly x: number;
+            readonly y: number;
+            readonly z: number;
+        };
+        readonly end: {
+            readonly _tag: "Vec3";
+            readonly x: number;
+            readonly y: number;
+            readonly z: number;
+        };
+    } | {
+        readonly _tag: "Path";
+        readonly position: {
+            readonly _tag: "Vec3";
+            readonly x: number;
+            readonly y: number;
+            readonly z: number;
+        };
+        readonly rotation: {
+            readonly _tag: "Vec3";
+            readonly x: number;
+            readonly y: number;
+            readonly z: number;
+        };
+        readonly scale: {
+            readonly _tag: "Vec3";
+            readonly x: number;
+            readonly y: number;
+            readonly z: number;
+        };
+        readonly opacity: number;
+        readonly visible: boolean;
+        readonly strokeWidth: number;
+        readonly strokeColor: Color.Color;
+        readonly fillColor: Color.Color;
+        readonly commands: readonly [{
+            readonly _tag: "L";
+            readonly x: number;
+            readonly y: number;
+            readonly z?: number;
+        } | {
+            readonly _tag: "M";
+            readonly x: number;
+            readonly y: number;
+            readonly z?: number;
+        } | {
+            readonly _tag: "Z";
+        }, ...({
+            readonly _tag: "L";
+            readonly x: number;
+            readonly y: number;
+            readonly z?: number;
+        } | {
+            readonly _tag: "M";
+            readonly x: number;
+            readonly y: number;
+            readonly z?: number;
+        } | {
+            readonly _tag: "Z";
+        })[]];
+    } | {
+        readonly _tag: "Rect";
+        readonly position: {
+            readonly _tag: "Vec3";
+            readonly x: number;
+            readonly y: number;
+            readonly z: number;
+        };
+        readonly rotation: {
+            readonly _tag: "Vec3";
+            readonly x: number;
+            readonly y: number;
+            readonly z: number;
+        };
+        readonly scale: {
+            readonly _tag: "Vec3";
+            readonly x: number;
+            readonly y: number;
+            readonly z: number;
+        };
+        readonly opacity: number;
+        readonly visible: boolean;
+        readonly strokeWidth: number;
+        readonly strokeColor: Color.Color;
+        readonly fillColor: Color.Color;
+        readonly width: number;
+        readonly height: number;
+    } | {
+        readonly _tag: "Text";
+        readonly position: {
+            readonly _tag: "Vec3";
+            readonly x: number;
+            readonly y: number;
+            readonly z: number;
+        };
+        readonly rotation: {
+            readonly _tag: "Vec3";
+            readonly x: number;
+            readonly y: number;
+            readonly z: number;
+        };
+        readonly scale: {
+            readonly _tag: "Vec3";
+            readonly x: number;
+            readonly y: number;
+            readonly z: number;
+        };
+        readonly opacity: number;
+        readonly visible: boolean;
+        readonly fillColor: Color.Color;
+        readonly text: string;
+        readonly fontSize: number;
+        readonly fontFamily: {
+            readonly _tag: "effect-motion/Resources/Font";
+            readonly id: string;
+        };
+        readonly textAnchor?: "end" | "middle" | "start";
+        readonly baseline?: "auto" | "hanging" | "middle";
+    }) => Effect.Effect<Instance.Instance<"Camera" | "Circle" | "Ellipse" | "Group" | "Hud" | "Image" | "Line" | "Path" | "Rect" | "Text">, never, never>;
+    registerComp: (id: string, config: CompConfig) => void;
+    camera: Instance.Instance<"Camera">;
+    setCamera: (instance: Instance.Instance<"Camera">) => void;
+    destroy: (instance: Instance.Instance) => void;
     phaser: {
         register: (n: number) => void;
         deregister: (n: number) => void;
@@ -307,62 +477,8 @@ declare const Runner_base: Context.ServiceClass<Runner, "Runner", {
     failureCause: () => Cause.Cause<unknown> | undefined;
 }> & {
     readonly make: (settings?: Partial<Settings> | undefined, comp?: CompConfig | undefined) => Effect.Effect<{
-        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;
-                readonly b: Schema.Number;
-                readonly c: Schema.Number;
-                readonly d: Schema.Number;
-                readonly e: Schema.Number;
-                readonly f: Schema.Number;
-            }>>;
-            width: Schema.optionalKey<Schema.Number>;
-            height: Schema.optionalKey<Schema.Number>;
-            backgroundColor: Schema.optionalKey<typeof Color.Color>;
-            children: Schema.withConstructorDefault<Schema.$Array<Schema.String>>;
-        }>, {
-            "~position": Entity.TraitLens<{
-                readonly x: number;
-                readonly y: number;
-                readonly z: number;
-                readonly opacity: number;
-                readonly transform: Schema.Struct.ReadonlySide<{
-                    readonly a: Schema.Number;
-                    readonly b: Schema.Number;
-                    readonly c: Schema.Number;
-                    readonly d: Schema.Number;
-                    readonly e: Schema.Number;
-                    readonly f: Schema.Number;
-                }, "Type">;
-                readonly width?: number;
-                readonly height?: number;
-                readonly backgroundColor?: Color.Color;
-                readonly children: readonly string[];
-            }, Entity.Position>;
-            "~opacity": Entity.TraitLens<{
-                readonly x: number;
-                readonly y: number;
-                readonly z: number;
-                readonly opacity: number;
-                readonly transform: Schema.Struct.ReadonlySide<{
-                    readonly a: Schema.Number;
-                    readonly b: Schema.Number;
-                    readonly c: Schema.Number;
-                    readonly d: Schema.Number;
-                    readonly e: Schema.Number;
-                    readonly f: Schema.Number;
-                }, "Type">;
-                readonly width?: number;
-                readonly height?: number;
-                readonly backgroundColor?: Color.Color;
-                readonly children: readonly string[];
-            }, number>;
-        }>;
-        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>;
+        root: GroupInstance;
+        instantiate: <Tag extends Entity.EntityTag>(kind: Tag, props: InstantiateProps<Tag>) => Effect.Effect<Instance.Instance<Tag>, never, Runner>;
         appendChild: (parent: GroupInstance, child: Instance.Instance) => void;
         removeChild: (parent: GroupInstance, child: Instance.Instance) => void;
         settings: {
@@ -371,87 +487,327 @@ declare const Runner_base: Context.ServiceClass<Runner, "Runner", {
             maxFrames: number;
         };
         comp: CompConfig;
-        getDataUnsafe: <Name extends string, Data extends Schema.Top>(instance: Instance.Instance<Name, Data>) => Data["Type"] | null;
-        setDataUnsafe: <Name extends string, Data extends Schema.Top>(instance: Instance.Instance<Name, Data>, data: unknown) => void;
+        getDataUnsafe: <Tag extends Entity.EntityTag>(instance: Instance.Instance<Tag>) => Entity.EntityByTag<Tag> | null;
+        setDataUnsafe: <Tag extends Entity.EntityTag>(instance: Instance.Instance<Tag>, state: Entity.EntityByTag<Tag>) => void;
         state: Effect.Effect<{
-            instances: {
-                [x: string]: {
-                    data: unknown;
-                    entity: Entity.AnyEntity;
-                    $visible: boolean;
-                };
-            };
+            instances: Record<string, {
+                data: Entity.Entity;
+            }>;
             root: string;
             frameRate: number;
             width: number;
             height: number;
             backgroundColor: Color.Color;
-            camera: CameraState;
+            camera: Projection.CameraView & Projection.PointOfInterest;
+            comps: {
+                [k: string]: CompConfig;
+            };
         }, never, never>;
-        camera: Instance.Instance<"Camera", Schema.Struct<{
-            x: Schema.withConstructorDefault<Schema.Number>;
-            y: 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: {
-                    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;
-                };
+        /**
+         * 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: (state: {
+            readonly _tag: "Camera";
+            readonly position: {
+                readonly _tag: "Vec3";
+                readonly x: number;
+                readonly y: number;
+                readonly z: number;
             };
-        }>;
-        setCamera: (instance: Instance.Instance) => void;
-        destroy: <Name extends string, Data extends Schema.Top>(instance: Instance.Instance<Name, Data>) => void;
+            readonly rotation: {
+                readonly _tag: "Vec3";
+                readonly x: number;
+                readonly y: number;
+                readonly z: number;
+            };
+            readonly focalLength: number;
+            readonly focusDistance: number;
+            readonly aperture: number;
+            readonly poi: {
+                readonly _tag: "Vec3";
+                readonly x: number;
+                readonly y: number;
+                readonly z: number;
+            } | null;
+        } | {
+            readonly _tag: "Circle";
+            readonly position: {
+                readonly _tag: "Vec3";
+                readonly x: number;
+                readonly y: number;
+                readonly z: number;
+            };
+            readonly rotation: {
+                readonly _tag: "Vec3";
+                readonly x: number;
+                readonly y: number;
+                readonly z: number;
+            };
+            readonly scale: {
+                readonly _tag: "Vec3";
+                readonly x: number;
+                readonly y: number;
+                readonly z: number;
+            };
+            readonly opacity: number;
+            readonly visible: boolean;
+            readonly strokeWidth: number;
+            readonly strokeColor: Color.Color;
+            readonly fillColor: Color.Color;
+            readonly radius: number;
+        } | {
+            readonly _tag: "Ellipse";
+            readonly position: {
+                readonly _tag: "Vec3";
+                readonly x: number;
+                readonly y: number;
+                readonly z: number;
+            };
+            readonly rotation: {
+                readonly _tag: "Vec3";
+                readonly x: number;
+                readonly y: number;
+                readonly z: number;
+            };
+            readonly scale: {
+                readonly _tag: "Vec3";
+                readonly x: number;
+                readonly y: number;
+                readonly z: number;
+            };
+            readonly opacity: number;
+            readonly visible: boolean;
+            readonly strokeWidth: number;
+            readonly strokeColor: Color.Color;
+            readonly fillColor: Color.Color;
+            readonly radiusX: number;
+            readonly radiusY: number;
+        } | {
+            readonly _tag: "Group";
+            readonly position: {
+                readonly _tag: "Vec3";
+                readonly x: number;
+                readonly y: number;
+                readonly z: number;
+            };
+            readonly rotation: {
+                readonly _tag: "Vec3";
+                readonly x: number;
+                readonly y: number;
+                readonly z: number;
+            };
+            readonly scale: {
+                readonly _tag: "Vec3";
+                readonly x: number;
+                readonly y: number;
+                readonly z: number;
+            };
+            readonly opacity: number;
+            readonly visible: boolean;
+            readonly children: readonly string[];
+        } | {
+            readonly _tag: "Hud";
+            readonly position: {
+                readonly _tag: "Vec3";
+                readonly x: number;
+                readonly y: number;
+                readonly z: number;
+            };
+            readonly rotation: {
+                readonly _tag: "Vec3";
+                readonly x: number;
+                readonly y: number;
+                readonly z: number;
+            };
+            readonly scale: {
+                readonly _tag: "Vec3";
+                readonly x: number;
+                readonly y: number;
+                readonly z: number;
+            };
+            readonly opacity: number;
+            readonly visible: boolean;
+            readonly children: readonly string[];
+        } | {
+            readonly _tag: "Image";
+            readonly position: {
+                readonly _tag: "Vec3";
+                readonly x: number;
+                readonly y: number;
+                readonly z: number;
+            };
+            readonly rotation: {
+                readonly _tag: "Vec3";
+                readonly x: number;
+                readonly y: number;
+                readonly z: number;
+            };
+            readonly scale: {
+                readonly _tag: "Vec3";
+                readonly x: number;
+                readonly y: number;
+                readonly z: number;
+            };
+            readonly opacity: number;
+            readonly visible: boolean;
+            readonly image: {
+                readonly _tag: "effect-motion/Resources/Image";
+                readonly id: string;
+            };
+            readonly width?: number;
+            readonly height?: number;
+        } | {
+            readonly _tag: "Line";
+            readonly position: {
+                readonly _tag: "Vec3";
+                readonly x: number;
+                readonly y: number;
+                readonly z: number;
+            };
+            readonly rotation: {
+                readonly _tag: "Vec3";
+                readonly x: number;
+                readonly y: number;
+                readonly z: number;
+            };
+            readonly scale: {
+                readonly _tag: "Vec3";
+                readonly x: number;
+                readonly y: number;
+                readonly z: number;
+            };
+            readonly opacity: number;
+            readonly visible: boolean;
+            readonly strokeWidth: number;
+            readonly strokeColor: Color.Color;
+            readonly start: {
+                readonly _tag: "Vec3";
+                readonly x: number;
+                readonly y: number;
+                readonly z: number;
+            };
+            readonly end: {
+                readonly _tag: "Vec3";
+                readonly x: number;
+                readonly y: number;
+                readonly z: number;
+            };
+        } | {
+            readonly _tag: "Path";
+            readonly position: {
+                readonly _tag: "Vec3";
+                readonly x: number;
+                readonly y: number;
+                readonly z: number;
+            };
+            readonly rotation: {
+                readonly _tag: "Vec3";
+                readonly x: number;
+                readonly y: number;
+                readonly z: number;
+            };
+            readonly scale: {
+                readonly _tag: "Vec3";
+                readonly x: number;
+                readonly y: number;
+                readonly z: number;
+            };
+            readonly opacity: number;
+            readonly visible: boolean;
+            readonly strokeWidth: number;
+            readonly strokeColor: Color.Color;
+            readonly fillColor: Color.Color;
+            readonly commands: readonly [{
+                readonly _tag: "L";
+                readonly x: number;
+                readonly y: number;
+                readonly z?: number;
+            } | {
+                readonly _tag: "M";
+                readonly x: number;
+                readonly y: number;
+                readonly z?: number;
+            } | {
+                readonly _tag: "Z";
+            }, ...({
+                readonly _tag: "L";
+                readonly x: number;
+                readonly y: number;
+                readonly z?: number;
+            } | {
+                readonly _tag: "M";
+                readonly x: number;
+                readonly y: number;
+                readonly z?: number;
+            } | {
+                readonly _tag: "Z";
+            })[]];
+        } | {
+            readonly _tag: "Rect";
+            readonly position: {
+                readonly _tag: "Vec3";
+                readonly x: number;
+                readonly y: number;
+                readonly z: number;
+            };
+            readonly rotation: {
+                readonly _tag: "Vec3";
+                readonly x: number;
+                readonly y: number;
+                readonly z: number;
+            };
+            readonly scale: {
+                readonly _tag: "Vec3";
+                readonly x: number;
+                readonly y: number;
+                readonly z: number;
+            };
+            readonly opacity: number;
+            readonly visible: boolean;
+            readonly strokeWidth: number;
+            readonly strokeColor: Color.Color;
+            readonly fillColor: Color.Color;
+            readonly width: number;
+            readonly height: number;
+        } | {
+            readonly _tag: "Text";
+            readonly position: {
+                readonly _tag: "Vec3";
+                readonly x: number;
+                readonly y: number;
+                readonly z: number;
+            };
+            readonly rotation: {
+                readonly _tag: "Vec3";
+                readonly x: number;
+                readonly y: number;
+                readonly z: number;
+            };
+            readonly scale: {
+                readonly _tag: "Vec3";
+                readonly x: number;
+                readonly y: number;
+                readonly z: number;
+            };
+            readonly opacity: number;
+            readonly visible: boolean;
+            readonly fillColor: Color.Color;
+            readonly text: string;
+            readonly fontSize: number;
+            readonly fontFamily: {
+                readonly _tag: "effect-motion/Resources/Font";
+                readonly id: string;
+            };
+            readonly textAnchor?: "end" | "middle" | "start";
+            readonly baseline?: "auto" | "hanging" | "middle";
+        }) => Effect.Effect<Instance.Instance<"Camera" | "Circle" | "Ellipse" | "Group" | "Hud" | "Image" | "Line" | "Path" | "Rect" | "Text">, never, never>;
+        registerComp: (id: string, config: CompConfig) => void;
+        camera: Instance.Instance<"Camera">;
+        setCamera: (instance: Instance.Instance<"Camera">) => void;
+        destroy: (instance: Instance.Instance) => void;
         phaser: {
             register: (n: number) => void;
             deregister: (n: number) => void;
@@ -475,4 +831,13 @@ declare const Runner_base: Context.ServiceClass<Runner, "Runner", {
 export declare class Runner extends Runner_base {
 }
 export declare const layer: Layer.Layer<Runner, never, never>;
-export {};
+/** the shape particles store — opaque, as far as the union is concerned */
+type ParticlesState = Record<string, unknown>;
+/** the tag particle fields are stored under; never a union member */
+export declare const PARTICLE_FIELD_TAG = "particles/ParticleField";
+/** instantiate a non-union entity. Particles only. */
+export declare const particlesEscapeInstantiate: (runner: Runner["Service"], state: ParticlesState) => Effect.Effect<Instance.Instance, never, Runner>;
+/** read a non-union entity's state. Particles only. */
+export declare const particlesEscapeRead: <T>(runner: Runner["Service"], instance: Instance.Instance) => T | null;
+/** write a non-union entity's state. Particles only. */
+export declare const particlesEscapeWrite: <T>(runner: Runner["Service"], instance: Instance.Instance, state: T) => void;