effect-motion 0.4.0 → 0.5.0

package/dist/Entity.d.ts

@@ -1,41 +1,685 @@
 import * as Schema from "effect/Schema";
-import type { AnyStructSchema } from "effect/unstable/workflow/Workflow";
-export declare const TypeId: "~motion/Entity";
-/**
- * A trait is a complete get/set lens over the entity's data — all or
- * nothing: a lone getter or setter is unrepresentable. `set` receives
- * the whole data and returns a new immutable whole with the change
- * applied, so each entity owns its semantics (e.g. Line's position
- * translates both endpoints).
- */
-export interface TraitLens<Data, Value> {
-    readonly get: (data: Data) => Value;
-    readonly set: (data: Data, value: Value) => Data;
-}
-/**
- * a type alias (not interface) so it satisfies Record constraints.
- * Position is 3D: `z` is depth (0 = the screen plane). 2D shapes default
- * z to 0 and read as plain-2D; the camera projects x/y/z to screen.
- */
-export type Position = {
-    readonly x: number;
-    readonly y: number;
-    readonly z: number;
-};
-export type EntityTraits<Data> = {
-    readonly "~position": TraitLens<Data, Position>;
-    readonly "~opacity": TraitLens<Data, number>;
+import * as Color from "./Color.js";
+/**
+ * The closed entity world.
+ *
+ * Every entity the library knows is a member of one tagged union, declared
+ * here. There is deliberately no way to define an entity outside this module:
+ * an entity's complete field set is derivable from its `_tag` alone, which
+ * is what lets the runner, the animators, and the renderer narrow instead
+ * of casting.
+ *
+ * Shared fields come from mixins, never from per-entity declarations, so no
+ * entity can quietly omit or rename one. An `Instance` is a REFERENCE to a
+ * live entity in the runner tree — see `Instance.ts`.
+ */
+/**
+ * A point or offset in 3D space.
+ *
+ * @remarks
+ * Scene coordinates with depth: `x` right, `y` UP (the mathematical
+ * convention), `z` toward the viewer, origin at the viewport center — a
+ * right-handed frame. Every axis defaults to 0, so `vec3({ x: 100 })` is a
+ * valid horizontal offset.
+ *
+ * At `z = 0` content renders exactly as flat 2D. Non-zero `z` is only
+ * meaningful under a perspective camera, where it changes apparent size and
+ * parallax.
+ */
+export declare const Vec3: Schema.TaggedStruct<"Vec3", {
+    readonly x: Schema.withConstructorDefault<Schema.Number>;
+    readonly y: Schema.withConstructorDefault<Schema.Number>;
+    readonly z: Schema.withConstructorDefault<Schema.Number>;
+}>;
+export type Vec3 = typeof Vec3.Type;
+/**
+ * Build a {@link Vec3}; omitted axes are 0.
+ *
+ * @example
+ * ```typescript
+ * Entity.vec3({ x: 100, y: 50 })
+ * ```
+ */
+export declare const vec3: (input: {
+    readonly _tag?: "Vec3";
+    readonly x?: number;
+    readonly y?: number;
+    readonly z?: number;
+}, options?: Schema.MakeOptions) => Schema.Struct.ReadonlySide<{
+    readonly _tag: Schema.tag<"Vec3">;
+    readonly x: Schema.withConstructorDefault<Schema.Number>;
+    readonly y: Schema.withConstructorDefault<Schema.Number>;
+    readonly z: Schema.withConstructorDefault<Schema.Number>;
+}, "Type">;
+export declare const PathCommand: Schema.TaggedUnion<{
+    readonly L: Schema.TaggedStruct<"L", {
+        x: Schema.Number;
+        y: Schema.Number;
+        z: Schema.optionalKey<Schema.Number>;
+    }>;
+    readonly M: Schema.TaggedStruct<"M", {
+        x: Schema.Number;
+        y: Schema.Number;
+        z: Schema.optionalKey<Schema.Number>;
+    }>;
+    readonly Z: Schema.TaggedStruct<"Z", {}>;
+}>;
+export type PathCommand = typeof PathCommand.Type;
+/**
+ * A segment. `start`/`end` are offsets from `position`, so moving the line
+ * translates it rigidly — no endpoint compensation anywhere in the system.
+ * Skeletal: parametrized by its endpoints, never by an anchor plus size.
+ */
+export declare const Line: Schema.TaggedStruct<"Line", {
+    readonly position: Schema.withConstructorDefault<Schema.TaggedStruct<"Vec3", {
+        readonly x: Schema.withConstructorDefault<Schema.Number>;
+        readonly y: Schema.withConstructorDefault<Schema.Number>;
+        readonly z: Schema.withConstructorDefault<Schema.Number>;
+    }>>;
+    readonly rotation: Schema.withConstructorDefault<Schema.TaggedStruct<"Vec3", {
+        readonly x: Schema.withConstructorDefault<Schema.Number>;
+        readonly y: Schema.withConstructorDefault<Schema.Number>;
+        readonly z: Schema.withConstructorDefault<Schema.Number>;
+    }>>;
+    readonly scale: Schema.withConstructorDefault<Schema.TaggedStruct<"Vec3", {
+        readonly x: Schema.withConstructorDefault<Schema.Number>;
+        readonly y: Schema.withConstructorDefault<Schema.Number>;
+        readonly z: Schema.withConstructorDefault<Schema.Number>;
+    }>>;
+    readonly opacity: Schema.withConstructorDefault<Schema.Number>;
+    readonly visible: Schema.withConstructorDefault<Schema.Boolean>;
+    readonly strokeWidth: Schema.withConstructorDefault<Schema.Number>;
+    readonly strokeColor: Schema.withConstructorDefault<typeof Color.Color>;
+    readonly start: Schema.withConstructorDefault<Schema.TaggedStruct<"Vec3", {
+        readonly x: Schema.withConstructorDefault<Schema.Number>;
+        readonly y: Schema.withConstructorDefault<Schema.Number>;
+        readonly z: Schema.withConstructorDefault<Schema.Number>;
+    }>>;
+    readonly end: Schema.withConstructorDefault<Schema.TaggedStruct<"Vec3", {
+        readonly x: Schema.withConstructorDefault<Schema.Number>;
+        readonly y: Schema.withConstructorDefault<Schema.Number>;
+        readonly z: Schema.withConstructorDefault<Schema.Number>;
+    }>>;
+}>;
+/**
+ * A polyline/polygon. Command points are relative to `position` (see
+ * `point`). The first command must be `M` — an open vocabulary of M/L/Z;
+ * curves and arcs arrive later via deterministic flattening.
+ */
+export declare const Path: Schema.TaggedStruct<"Path", {
+    readonly position: Schema.withConstructorDefault<Schema.TaggedStruct<"Vec3", {
+        readonly x: Schema.withConstructorDefault<Schema.Number>;
+        readonly y: Schema.withConstructorDefault<Schema.Number>;
+        readonly z: Schema.withConstructorDefault<Schema.Number>;
+    }>>;
+    readonly rotation: Schema.withConstructorDefault<Schema.TaggedStruct<"Vec3", {
+        readonly x: Schema.withConstructorDefault<Schema.Number>;
+        readonly y: Schema.withConstructorDefault<Schema.Number>;
+        readonly z: Schema.withConstructorDefault<Schema.Number>;
+    }>>;
+    readonly scale: Schema.withConstructorDefault<Schema.TaggedStruct<"Vec3", {
+        readonly x: Schema.withConstructorDefault<Schema.Number>;
+        readonly y: Schema.withConstructorDefault<Schema.Number>;
+        readonly z: Schema.withConstructorDefault<Schema.Number>;
+    }>>;
+    readonly opacity: Schema.withConstructorDefault<Schema.Number>;
+    readonly visible: Schema.withConstructorDefault<Schema.Boolean>;
+    readonly strokeWidth: Schema.withConstructorDefault<Schema.Number>;
+    readonly strokeColor: Schema.withConstructorDefault<typeof Color.Color>;
+    readonly fillColor: Schema.withConstructorDefault<typeof Color.Color>;
+    readonly commands: Schema.NonEmptyArray<Schema.TaggedUnion<{
+        readonly L: Schema.TaggedStruct<"L", {
+            x: Schema.Number;
+            y: Schema.Number;
+            z: Schema.optionalKey<Schema.Number>;
+        }>;
+        readonly M: Schema.TaggedStruct<"M", {
+            x: Schema.Number;
+            y: Schema.Number;
+            z: Schema.optionalKey<Schema.Number>;
+        }>;
+        readonly Z: Schema.TaggedStruct<"Z", {}>;
+    }>>;
+}>;
+/**
+ * The canonical 2.5D plane. All-zero rotation is a camera-facing billboard;
+ * non-zero tilts it as a real plane in 3D.
+ */
+export declare const Rect: Schema.TaggedStruct<"Rect", {
+    readonly position: Schema.withConstructorDefault<Schema.TaggedStruct<"Vec3", {
+        readonly x: Schema.withConstructorDefault<Schema.Number>;
+        readonly y: Schema.withConstructorDefault<Schema.Number>;
+        readonly z: Schema.withConstructorDefault<Schema.Number>;
+    }>>;
+    readonly rotation: Schema.withConstructorDefault<Schema.TaggedStruct<"Vec3", {
+        readonly x: Schema.withConstructorDefault<Schema.Number>;
+        readonly y: Schema.withConstructorDefault<Schema.Number>;
+        readonly z: Schema.withConstructorDefault<Schema.Number>;
+    }>>;
+    readonly scale: Schema.withConstructorDefault<Schema.TaggedStruct<"Vec3", {
+        readonly x: Schema.withConstructorDefault<Schema.Number>;
+        readonly y: Schema.withConstructorDefault<Schema.Number>;
+        readonly z: Schema.withConstructorDefault<Schema.Number>;
+    }>>;
+    readonly opacity: Schema.withConstructorDefault<Schema.Number>;
+    readonly visible: Schema.withConstructorDefault<Schema.Boolean>;
+    readonly strokeWidth: Schema.withConstructorDefault<Schema.Number>;
+    readonly strokeColor: Schema.withConstructorDefault<typeof Color.Color>;
+    readonly fillColor: Schema.withConstructorDefault<typeof Color.Color>;
+    readonly width: Schema.withConstructorDefault<Schema.Number>;
+    readonly height: Schema.withConstructorDefault<Schema.Number>;
+}>;
+/** A filled circle of a given `radius`, centered on its `position`. */
+export declare const Circle: Schema.TaggedStruct<"Circle", {
+    readonly position: Schema.withConstructorDefault<Schema.TaggedStruct<"Vec3", {
+        readonly x: Schema.withConstructorDefault<Schema.Number>;
+        readonly y: Schema.withConstructorDefault<Schema.Number>;
+        readonly z: Schema.withConstructorDefault<Schema.Number>;
+    }>>;
+    readonly rotation: Schema.withConstructorDefault<Schema.TaggedStruct<"Vec3", {
+        readonly x: Schema.withConstructorDefault<Schema.Number>;
+        readonly y: Schema.withConstructorDefault<Schema.Number>;
+        readonly z: Schema.withConstructorDefault<Schema.Number>;
+    }>>;
+    readonly scale: Schema.withConstructorDefault<Schema.TaggedStruct<"Vec3", {
+        readonly x: Schema.withConstructorDefault<Schema.Number>;
+        readonly y: Schema.withConstructorDefault<Schema.Number>;
+        readonly z: Schema.withConstructorDefault<Schema.Number>;
+    }>>;
+    readonly opacity: Schema.withConstructorDefault<Schema.Number>;
+    readonly visible: Schema.withConstructorDefault<Schema.Boolean>;
+    readonly strokeWidth: Schema.withConstructorDefault<Schema.Number>;
+    readonly strokeColor: Schema.withConstructorDefault<typeof Color.Color>;
+    readonly fillColor: Schema.withConstructorDefault<typeof Color.Color>;
+    readonly radius: Schema.withConstructorDefault<Schema.Number>;
+}>;
+/** An ellipse with independent `radiusX` and `radiusY`. */
+export declare const Ellipse: Schema.TaggedStruct<"Ellipse", {
+    readonly position: Schema.withConstructorDefault<Schema.TaggedStruct<"Vec3", {
+        readonly x: Schema.withConstructorDefault<Schema.Number>;
+        readonly y: Schema.withConstructorDefault<Schema.Number>;
+        readonly z: Schema.withConstructorDefault<Schema.Number>;
+    }>>;
+    readonly rotation: Schema.withConstructorDefault<Schema.TaggedStruct<"Vec3", {
+        readonly x: Schema.withConstructorDefault<Schema.Number>;
+        readonly y: Schema.withConstructorDefault<Schema.Number>;
+        readonly z: Schema.withConstructorDefault<Schema.Number>;
+    }>>;
+    readonly scale: Schema.withConstructorDefault<Schema.TaggedStruct<"Vec3", {
+        readonly x: Schema.withConstructorDefault<Schema.Number>;
+        readonly y: Schema.withConstructorDefault<Schema.Number>;
+        readonly z: Schema.withConstructorDefault<Schema.Number>;
+    }>>;
+    readonly opacity: Schema.withConstructorDefault<Schema.Number>;
+    readonly visible: Schema.withConstructorDefault<Schema.Boolean>;
+    readonly strokeWidth: Schema.withConstructorDefault<Schema.Number>;
+    readonly strokeColor: Schema.withConstructorDefault<typeof Color.Color>;
+    readonly fillColor: Schema.withConstructorDefault<typeof Color.Color>;
+    readonly radiusX: Schema.withConstructorDefault<Schema.Number>;
+    readonly radiusY: Schema.withConstructorDefault<Schema.Number>;
+}>;
+/**
+ * A plain-string text leaf. The engine cannot measure text, so `text` has
+ * no dimensional fields — layout is the renderer's business. Inline
+ * formatting is expressed by composing several Texts, not by a rich tree.
+ */
+export declare const Text: Schema.TaggedStruct<"Text", {
+    readonly position: Schema.withConstructorDefault<Schema.TaggedStruct<"Vec3", {
+        readonly x: Schema.withConstructorDefault<Schema.Number>;
+        readonly y: Schema.withConstructorDefault<Schema.Number>;
+        readonly z: Schema.withConstructorDefault<Schema.Number>;
+    }>>;
+    readonly rotation: Schema.withConstructorDefault<Schema.TaggedStruct<"Vec3", {
+        readonly x: Schema.withConstructorDefault<Schema.Number>;
+        readonly y: Schema.withConstructorDefault<Schema.Number>;
+        readonly z: Schema.withConstructorDefault<Schema.Number>;
+    }>>;
+    readonly scale: Schema.withConstructorDefault<Schema.TaggedStruct<"Vec3", {
+        readonly x: Schema.withConstructorDefault<Schema.Number>;
+        readonly y: Schema.withConstructorDefault<Schema.Number>;
+        readonly z: Schema.withConstructorDefault<Schema.Number>;
+    }>>;
+    readonly opacity: Schema.withConstructorDefault<Schema.Number>;
+    readonly visible: Schema.withConstructorDefault<Schema.Boolean>;
+    readonly fillColor: Schema.withConstructorDefault<typeof Color.Color>;
+    readonly text: Schema.String;
+    readonly fontSize: Schema.withConstructorDefault<Schema.Number>;
+    readonly fontFamily: Schema.withConstructorDefault<Schema.TaggedStruct<"effect-motion/Resources/Font", {
+        readonly id: Schema.String;
+    }>>;
+    readonly textAnchor: Schema.optionalKey<Schema.Literals<readonly ["start", "middle", "end"]>>;
+    readonly baseline: Schema.optionalKey<Schema.Literals<readonly ["auto", "middle", "hanging"]>>;
+}>;
+/**
+ * A container: positions and structures its children, paints nothing
+ * itself. Its transform composes down the subtree like any entity's.
+ *
+ * It carries no composition bounds. `width`/`height`/`backgroundColor` used
+ * to live here so `Scene.play` could copy a nested scene's dimensions onto
+ * the mount group; a Scene owns those itself, and a render-to-texture
+ * boundary is `Scene.play`'s business, not a field on every group.
+ */
+export declare const Group: Schema.TaggedStruct<"Group", {
+    readonly position: Schema.withConstructorDefault<Schema.TaggedStruct<"Vec3", {
+        readonly x: Schema.withConstructorDefault<Schema.Number>;
+        readonly y: Schema.withConstructorDefault<Schema.Number>;
+        readonly z: Schema.withConstructorDefault<Schema.Number>;
+    }>>;
+    readonly rotation: Schema.withConstructorDefault<Schema.TaggedStruct<"Vec3", {
+        readonly x: Schema.withConstructorDefault<Schema.Number>;
+        readonly y: Schema.withConstructorDefault<Schema.Number>;
+        readonly z: Schema.withConstructorDefault<Schema.Number>;
+    }>>;
+    readonly scale: Schema.withConstructorDefault<Schema.TaggedStruct<"Vec3", {
+        readonly x: Schema.withConstructorDefault<Schema.Number>;
+        readonly y: Schema.withConstructorDefault<Schema.Number>;
+        readonly z: Schema.withConstructorDefault<Schema.Number>;
+    }>>;
+    readonly opacity: Schema.withConstructorDefault<Schema.Number>;
+    readonly visible: Schema.withConstructorDefault<Schema.Boolean>;
+    readonly children: Schema.withConstructorDefault<Schema.$Array<Schema.String>>;
+}>;
+/**
+ * A screen-space container: its subtree is projected through the identity
+ * camera rather than the active one, so HUD content ignores camera
+ * movement, zoom, and shake, and always paints on top.
+ *
+ * `position.z` is depth WITHIN the HUD tier — z consistently means depth in
+ * the entity's own coordinate space, world for world content and screen for
+ * HUD content. A Hud must be a top-level child of the root (or of another
+ * Hud); nesting one inside world content is a loud defect.
+ */
+export declare const Hud: Schema.TaggedStruct<"Hud", {
+    readonly position: Schema.withConstructorDefault<Schema.TaggedStruct<"Vec3", {
+        readonly x: Schema.withConstructorDefault<Schema.Number>;
+        readonly y: Schema.withConstructorDefault<Schema.Number>;
+        readonly z: Schema.withConstructorDefault<Schema.Number>;
+    }>>;
+    readonly rotation: Schema.withConstructorDefault<Schema.TaggedStruct<"Vec3", {
+        readonly x: Schema.withConstructorDefault<Schema.Number>;
+        readonly y: Schema.withConstructorDefault<Schema.Number>;
+        readonly z: Schema.withConstructorDefault<Schema.Number>;
+    }>>;
+    readonly scale: Schema.withConstructorDefault<Schema.TaggedStruct<"Vec3", {
+        readonly x: Schema.withConstructorDefault<Schema.Number>;
+        readonly y: Schema.withConstructorDefault<Schema.Number>;
+        readonly z: Schema.withConstructorDefault<Schema.Number>;
+    }>>;
+    readonly opacity: Schema.withConstructorDefault<Schema.Number>;
+    readonly visible: Schema.withConstructorDefault<Schema.Boolean>;
+    readonly children: Schema.withConstructorDefault<Schema.$Array<Schema.String>>;
+}>;
+/**
+ * A raster/vector image leaf. `image` is an Image resource reference; the
+ * bytes live in the scene's requirements, never in frame data.
+ *
+ * `width`/`height` are optional and undefaulted: set BOTH to draw at that
+ * size (numeric, so they tween), leave both absent for the source's natural
+ * size. A lone dimension is ignored — aspect math needs the natural size,
+ * which frame data never sees.
+ */
+export declare const Image: Schema.TaggedStruct<"Image", {
+    readonly position: Schema.withConstructorDefault<Schema.TaggedStruct<"Vec3", {
+        readonly x: Schema.withConstructorDefault<Schema.Number>;
+        readonly y: Schema.withConstructorDefault<Schema.Number>;
+        readonly z: Schema.withConstructorDefault<Schema.Number>;
+    }>>;
+    readonly rotation: Schema.withConstructorDefault<Schema.TaggedStruct<"Vec3", {
+        readonly x: Schema.withConstructorDefault<Schema.Number>;
+        readonly y: Schema.withConstructorDefault<Schema.Number>;
+        readonly z: Schema.withConstructorDefault<Schema.Number>;
+    }>>;
+    readonly scale: Schema.withConstructorDefault<Schema.TaggedStruct<"Vec3", {
+        readonly x: Schema.withConstructorDefault<Schema.Number>;
+        readonly y: Schema.withConstructorDefault<Schema.Number>;
+        readonly z: Schema.withConstructorDefault<Schema.Number>;
+    }>>;
+    readonly opacity: Schema.withConstructorDefault<Schema.Number>;
+    readonly visible: Schema.withConstructorDefault<Schema.Boolean>;
+    readonly image: Schema.TaggedStruct<"effect-motion/Resources/Image", {
+        readonly id: Schema.String;
+    }>;
+    readonly width: Schema.optionalKey<Schema.Number>;
+    readonly height: Schema.optionalKey<Schema.Number>;
+}>;
+/**
+ * The viewpoint — the one entity that is never drawn.
+ *
+ * @remarks
+ * A camera is view state rather than content, so it carries `position` and
+ * `rotation` but no `scale`, `opacity`, or `visible`, and is absent from the
+ * frame's instance map. Every scene has one already; reach for it with
+ * `Scene.camera`.
+ *
+ * `focalLength` sets the perspective strength — a longer lens flattens
+ * depth, a shorter one exaggerates it. It and the resting `z` are
+ * width-relative and filled in by the runner at instantiate time (only the
+ * runner knows the composition width), so the zero defaults here are
+ * placeholders that are always overwritten. The resting values are chosen so
+ * content at `z = 0` renders exactly as flat 2D.
+ *
+ * `poi` is an optional point of interest: when set, the camera auto-aims at
+ * that world point and any explicit `rotation` composes on top of the aim.
+ * The `Camera` module's helpers are the ergonomic way to drive it.
+ *
+ * `aperture` and `focusDistance` describe depth of field. They are carried
+ * on the frame but currently have NO visual effect — depth-of-field
+ * rendering is not implemented, and every frame renders sharp.
+ */
+export declare const Camera: Schema.TaggedStruct<"Camera", {
+    readonly position: Schema.withConstructorDefault<Schema.TaggedStruct<"Vec3", {
+        readonly x: Schema.withConstructorDefault<Schema.Number>;
+        readonly y: Schema.withConstructorDefault<Schema.Number>;
+        readonly z: Schema.withConstructorDefault<Schema.Number>;
+    }>>;
+    readonly rotation: Schema.withConstructorDefault<Schema.TaggedStruct<"Vec3", {
+        readonly x: Schema.withConstructorDefault<Schema.Number>;
+        readonly y: Schema.withConstructorDefault<Schema.Number>;
+        readonly z: Schema.withConstructorDefault<Schema.Number>;
+    }>>;
+    readonly focalLength: Schema.withConstructorDefault<Schema.Number>;
+    readonly focusDistance: Schema.withConstructorDefault<Schema.Number>;
+    readonly aperture: Schema.withConstructorDefault<Schema.Number>;
+    readonly poi: Schema.withConstructorDefault<Schema.NullOr<Schema.TaggedStruct<"Vec3", {
+        readonly x: Schema.withConstructorDefault<Schema.Number>;
+        readonly y: Schema.withConstructorDefault<Schema.Number>;
+        readonly z: Schema.withConstructorDefault<Schema.Number>;
+    }>>>;
+}>;
+export declare const EntityMap: {
+    readonly Line: Schema.TaggedStruct<"Line", {
+        readonly position: Schema.withConstructorDefault<Schema.TaggedStruct<"Vec3", {
+            readonly x: Schema.withConstructorDefault<Schema.Number>;
+            readonly y: Schema.withConstructorDefault<Schema.Number>;
+            readonly z: Schema.withConstructorDefault<Schema.Number>;
+        }>>;
+        readonly rotation: Schema.withConstructorDefault<Schema.TaggedStruct<"Vec3", {
+            readonly x: Schema.withConstructorDefault<Schema.Number>;
+            readonly y: Schema.withConstructorDefault<Schema.Number>;
+            readonly z: Schema.withConstructorDefault<Schema.Number>;
+        }>>;
+        readonly scale: Schema.withConstructorDefault<Schema.TaggedStruct<"Vec3", {
+            readonly x: Schema.withConstructorDefault<Schema.Number>;
+            readonly y: Schema.withConstructorDefault<Schema.Number>;
+            readonly z: Schema.withConstructorDefault<Schema.Number>;
+        }>>;
+        readonly opacity: Schema.withConstructorDefault<Schema.Number>;
+        readonly visible: Schema.withConstructorDefault<Schema.Boolean>;
+        readonly strokeWidth: Schema.withConstructorDefault<Schema.Number>;
+        readonly strokeColor: Schema.withConstructorDefault<typeof Color.Color>;
+        readonly start: Schema.withConstructorDefault<Schema.TaggedStruct<"Vec3", {
+            readonly x: Schema.withConstructorDefault<Schema.Number>;
+            readonly y: Schema.withConstructorDefault<Schema.Number>;
+            readonly z: Schema.withConstructorDefault<Schema.Number>;
+        }>>;
+        readonly end: Schema.withConstructorDefault<Schema.TaggedStruct<"Vec3", {
+            readonly x: Schema.withConstructorDefault<Schema.Number>;
+            readonly y: Schema.withConstructorDefault<Schema.Number>;
+            readonly z: Schema.withConstructorDefault<Schema.Number>;
+        }>>;
+    }>;
+    readonly Path: Schema.TaggedStruct<"Path", {
+        readonly position: Schema.withConstructorDefault<Schema.TaggedStruct<"Vec3", {
+            readonly x: Schema.withConstructorDefault<Schema.Number>;
+            readonly y: Schema.withConstructorDefault<Schema.Number>;
+            readonly z: Schema.withConstructorDefault<Schema.Number>;
+        }>>;
+        readonly rotation: Schema.withConstructorDefault<Schema.TaggedStruct<"Vec3", {
+            readonly x: Schema.withConstructorDefault<Schema.Number>;
+            readonly y: Schema.withConstructorDefault<Schema.Number>;
+            readonly z: Schema.withConstructorDefault<Schema.Number>;
+        }>>;
+        readonly scale: Schema.withConstructorDefault<Schema.TaggedStruct<"Vec3", {
+            readonly x: Schema.withConstructorDefault<Schema.Number>;
+            readonly y: Schema.withConstructorDefault<Schema.Number>;
+            readonly z: Schema.withConstructorDefault<Schema.Number>;
+        }>>;
+        readonly opacity: Schema.withConstructorDefault<Schema.Number>;
+        readonly visible: Schema.withConstructorDefault<Schema.Boolean>;
+        readonly strokeWidth: Schema.withConstructorDefault<Schema.Number>;
+        readonly strokeColor: Schema.withConstructorDefault<typeof Color.Color>;
+        readonly fillColor: Schema.withConstructorDefault<typeof Color.Color>;
+        readonly commands: Schema.NonEmptyArray<Schema.TaggedUnion<{
+            readonly L: Schema.TaggedStruct<"L", {
+                x: Schema.Number;
+                y: Schema.Number;
+                z: Schema.optionalKey<Schema.Number>;
+            }>;
+            readonly M: Schema.TaggedStruct<"M", {
+                x: Schema.Number;
+                y: Schema.Number;
+                z: Schema.optionalKey<Schema.Number>;
+            }>;
+            readonly Z: Schema.TaggedStruct<"Z", {}>;
+        }>>;
+    }>;
+    readonly Rect: Schema.TaggedStruct<"Rect", {
+        readonly position: Schema.withConstructorDefault<Schema.TaggedStruct<"Vec3", {
+            readonly x: Schema.withConstructorDefault<Schema.Number>;
+            readonly y: Schema.withConstructorDefault<Schema.Number>;
+            readonly z: Schema.withConstructorDefault<Schema.Number>;
+        }>>;
+        readonly rotation: Schema.withConstructorDefault<Schema.TaggedStruct<"Vec3", {
+            readonly x: Schema.withConstructorDefault<Schema.Number>;
+            readonly y: Schema.withConstructorDefault<Schema.Number>;
+            readonly z: Schema.withConstructorDefault<Schema.Number>;
+        }>>;
+        readonly scale: Schema.withConstructorDefault<Schema.TaggedStruct<"Vec3", {
+            readonly x: Schema.withConstructorDefault<Schema.Number>;
+            readonly y: Schema.withConstructorDefault<Schema.Number>;
+            readonly z: Schema.withConstructorDefault<Schema.Number>;
+        }>>;
+        readonly opacity: Schema.withConstructorDefault<Schema.Number>;
+        readonly visible: Schema.withConstructorDefault<Schema.Boolean>;
+        readonly strokeWidth: Schema.withConstructorDefault<Schema.Number>;
+        readonly strokeColor: Schema.withConstructorDefault<typeof Color.Color>;
+        readonly fillColor: Schema.withConstructorDefault<typeof Color.Color>;
+        readonly width: Schema.withConstructorDefault<Schema.Number>;
+        readonly height: Schema.withConstructorDefault<Schema.Number>;
+    }>;
+    readonly Circle: Schema.TaggedStruct<"Circle", {
+        readonly position: Schema.withConstructorDefault<Schema.TaggedStruct<"Vec3", {
+            readonly x: Schema.withConstructorDefault<Schema.Number>;
+            readonly y: Schema.withConstructorDefault<Schema.Number>;
+            readonly z: Schema.withConstructorDefault<Schema.Number>;
+        }>>;
+        readonly rotation: Schema.withConstructorDefault<Schema.TaggedStruct<"Vec3", {
+            readonly x: Schema.withConstructorDefault<Schema.Number>;
+            readonly y: Schema.withConstructorDefault<Schema.Number>;
+            readonly z: Schema.withConstructorDefault<Schema.Number>;
+        }>>;
+        readonly scale: Schema.withConstructorDefault<Schema.TaggedStruct<"Vec3", {
+            readonly x: Schema.withConstructorDefault<Schema.Number>;
+            readonly y: Schema.withConstructorDefault<Schema.Number>;
+            readonly z: Schema.withConstructorDefault<Schema.Number>;
+        }>>;
+        readonly opacity: Schema.withConstructorDefault<Schema.Number>;
+        readonly visible: Schema.withConstructorDefault<Schema.Boolean>;
+        readonly strokeWidth: Schema.withConstructorDefault<Schema.Number>;
+        readonly strokeColor: Schema.withConstructorDefault<typeof Color.Color>;
+        readonly fillColor: Schema.withConstructorDefault<typeof Color.Color>;
+        readonly radius: Schema.withConstructorDefault<Schema.Number>;
+    }>;
+    readonly Ellipse: Schema.TaggedStruct<"Ellipse", {
+        readonly position: Schema.withConstructorDefault<Schema.TaggedStruct<"Vec3", {
+            readonly x: Schema.withConstructorDefault<Schema.Number>;
+            readonly y: Schema.withConstructorDefault<Schema.Number>;
+            readonly z: Schema.withConstructorDefault<Schema.Number>;
+        }>>;
+        readonly rotation: Schema.withConstructorDefault<Schema.TaggedStruct<"Vec3", {
+            readonly x: Schema.withConstructorDefault<Schema.Number>;
+            readonly y: Schema.withConstructorDefault<Schema.Number>;
+            readonly z: Schema.withConstructorDefault<Schema.Number>;
+        }>>;
+        readonly scale: Schema.withConstructorDefault<Schema.TaggedStruct<"Vec3", {
+            readonly x: Schema.withConstructorDefault<Schema.Number>;
+            readonly y: Schema.withConstructorDefault<Schema.Number>;
+            readonly z: Schema.withConstructorDefault<Schema.Number>;
+        }>>;
+        readonly opacity: Schema.withConstructorDefault<Schema.Number>;
+        readonly visible: Schema.withConstructorDefault<Schema.Boolean>;
+        readonly strokeWidth: Schema.withConstructorDefault<Schema.Number>;
+        readonly strokeColor: Schema.withConstructorDefault<typeof Color.Color>;
+        readonly fillColor: Schema.withConstructorDefault<typeof Color.Color>;
+        readonly radiusX: Schema.withConstructorDefault<Schema.Number>;
+        readonly radiusY: Schema.withConstructorDefault<Schema.Number>;
+    }>;
+    readonly Text: Schema.TaggedStruct<"Text", {
+        readonly position: Schema.withConstructorDefault<Schema.TaggedStruct<"Vec3", {
+            readonly x: Schema.withConstructorDefault<Schema.Number>;
+            readonly y: Schema.withConstructorDefault<Schema.Number>;
+            readonly z: Schema.withConstructorDefault<Schema.Number>;
+        }>>;
+        readonly rotation: Schema.withConstructorDefault<Schema.TaggedStruct<"Vec3", {
+            readonly x: Schema.withConstructorDefault<Schema.Number>;
+            readonly y: Schema.withConstructorDefault<Schema.Number>;
+            readonly z: Schema.withConstructorDefault<Schema.Number>;
+        }>>;
+        readonly scale: Schema.withConstructorDefault<Schema.TaggedStruct<"Vec3", {
+            readonly x: Schema.withConstructorDefault<Schema.Number>;
+            readonly y: Schema.withConstructorDefault<Schema.Number>;
+            readonly z: Schema.withConstructorDefault<Schema.Number>;
+        }>>;
+        readonly opacity: Schema.withConstructorDefault<Schema.Number>;
+        readonly visible: Schema.withConstructorDefault<Schema.Boolean>;
+        readonly fillColor: Schema.withConstructorDefault<typeof Color.Color>;
+        readonly text: Schema.String;
+        readonly fontSize: Schema.withConstructorDefault<Schema.Number>;
+        readonly fontFamily: Schema.withConstructorDefault<Schema.TaggedStruct<"effect-motion/Resources/Font", {
+            readonly id: Schema.String;
+        }>>;
+        readonly textAnchor: Schema.optionalKey<Schema.Literals<readonly ["start", "middle", "end"]>>;
+        readonly baseline: Schema.optionalKey<Schema.Literals<readonly ["auto", "middle", "hanging"]>>;
+    }>;
+    readonly Group: Schema.TaggedStruct<"Group", {
+        readonly position: Schema.withConstructorDefault<Schema.TaggedStruct<"Vec3", {
+            readonly x: Schema.withConstructorDefault<Schema.Number>;
+            readonly y: Schema.withConstructorDefault<Schema.Number>;
+            readonly z: Schema.withConstructorDefault<Schema.Number>;
+        }>>;
+        readonly rotation: Schema.withConstructorDefault<Schema.TaggedStruct<"Vec3", {
+            readonly x: Schema.withConstructorDefault<Schema.Number>;
+            readonly y: Schema.withConstructorDefault<Schema.Number>;
+            readonly z: Schema.withConstructorDefault<Schema.Number>;
+        }>>;
+        readonly scale: Schema.withConstructorDefault<Schema.TaggedStruct<"Vec3", {
+            readonly x: Schema.withConstructorDefault<Schema.Number>;
+            readonly y: Schema.withConstructorDefault<Schema.Number>;
+            readonly z: Schema.withConstructorDefault<Schema.Number>;
+        }>>;
+        readonly opacity: Schema.withConstructorDefault<Schema.Number>;
+        readonly visible: Schema.withConstructorDefault<Schema.Boolean>;
+        readonly children: Schema.withConstructorDefault<Schema.$Array<Schema.String>>;
+    }>;
+    readonly Hud: Schema.TaggedStruct<"Hud", {
+        readonly position: Schema.withConstructorDefault<Schema.TaggedStruct<"Vec3", {
+            readonly x: Schema.withConstructorDefault<Schema.Number>;
+            readonly y: Schema.withConstructorDefault<Schema.Number>;
+            readonly z: Schema.withConstructorDefault<Schema.Number>;
+        }>>;
+        readonly rotation: Schema.withConstructorDefault<Schema.TaggedStruct<"Vec3", {
+            readonly x: Schema.withConstructorDefault<Schema.Number>;
+            readonly y: Schema.withConstructorDefault<Schema.Number>;
+            readonly z: Schema.withConstructorDefault<Schema.Number>;
+        }>>;
+        readonly scale: Schema.withConstructorDefault<Schema.TaggedStruct<"Vec3", {
+            readonly x: Schema.withConstructorDefault<Schema.Number>;
+            readonly y: Schema.withConstructorDefault<Schema.Number>;
+            readonly z: Schema.withConstructorDefault<Schema.Number>;
+        }>>;
+        readonly opacity: Schema.withConstructorDefault<Schema.Number>;
+        readonly visible: Schema.withConstructorDefault<Schema.Boolean>;
+        readonly children: Schema.withConstructorDefault<Schema.$Array<Schema.String>>;
+    }>;
+    readonly Image: Schema.TaggedStruct<"Image", {
+        readonly position: Schema.withConstructorDefault<Schema.TaggedStruct<"Vec3", {
+            readonly x: Schema.withConstructorDefault<Schema.Number>;
+            readonly y: Schema.withConstructorDefault<Schema.Number>;
+            readonly z: Schema.withConstructorDefault<Schema.Number>;
+        }>>;
+        readonly rotation: Schema.withConstructorDefault<Schema.TaggedStruct<"Vec3", {
+            readonly x: Schema.withConstructorDefault<Schema.Number>;
+            readonly y: Schema.withConstructorDefault<Schema.Number>;
+            readonly z: Schema.withConstructorDefault<Schema.Number>;
+        }>>;
+        readonly scale: Schema.withConstructorDefault<Schema.TaggedStruct<"Vec3", {
+            readonly x: Schema.withConstructorDefault<Schema.Number>;
+            readonly y: Schema.withConstructorDefault<Schema.Number>;
+            readonly z: Schema.withConstructorDefault<Schema.Number>;
+        }>>;
+        readonly opacity: Schema.withConstructorDefault<Schema.Number>;
+        readonly visible: Schema.withConstructorDefault<Schema.Boolean>;
+        readonly image: Schema.TaggedStruct<"effect-motion/Resources/Image", {
+            readonly id: Schema.String;
+        }>;
+        readonly width: Schema.optionalKey<Schema.Number>;
+        readonly height: Schema.optionalKey<Schema.Number>;
+    }>;
+    readonly Camera: Schema.TaggedStruct<"Camera", {
+        readonly position: Schema.withConstructorDefault<Schema.TaggedStruct<"Vec3", {
+            readonly x: Schema.withConstructorDefault<Schema.Number>;
+            readonly y: Schema.withConstructorDefault<Schema.Number>;
+            readonly z: Schema.withConstructorDefault<Schema.Number>;
+        }>>;
+        readonly rotation: Schema.withConstructorDefault<Schema.TaggedStruct<"Vec3", {
+            readonly x: Schema.withConstructorDefault<Schema.Number>;
+            readonly y: Schema.withConstructorDefault<Schema.Number>;
+            readonly z: Schema.withConstructorDefault<Schema.Number>;
+        }>>;
+        readonly focalLength: Schema.withConstructorDefault<Schema.Number>;
+        readonly focusDistance: Schema.withConstructorDefault<Schema.Number>;
+        readonly aperture: Schema.withConstructorDefault<Schema.Number>;
+        readonly poi: Schema.withConstructorDefault<Schema.NullOr<Schema.TaggedStruct<"Vec3", {
+            readonly x: Schema.withConstructorDefault<Schema.Number>;
+            readonly y: Schema.withConstructorDefault<Schema.Number>;
+            readonly z: Schema.withConstructorDefault<Schema.Number>;
+        }>>>;
+    }>;
 };
-export type TraitKey = keyof EntityTraits<unknown>;
-export interface Entity<Name extends string = string, Data extends Schema.Top = Schema.Top, Traits extends Partial<EntityTraits<Data["Type"]>> = {}> {
-    readonly [TypeId]: typeof TypeId;
-    readonly name: Name;
-    readonly data: Data;
-    readonly traits: Traits;
-}
-export type AnyEntity = Entity<any, any, any>;
-/** the entity's trait lens, or a defect naming entity and trait */
-export declare const traitOrDie: <Data, Value>(entity: AnyEntity, key: TraitKey) => TraitLens<Data, Value>;
-type NormalizeStructLike<T extends Schema.Struct.Fields | AnyStructSchema> = T extends AnyStructSchema ? T : T extends Schema.Struct.Fields ? Schema.Struct<T> : never;
-export declare const make: <Name extends string, Data extends Schema.Struct.Fields | AnyStructSchema, const Traits extends Partial<EntityTraits<NormalizeStructLike<Data>["Type"]>> = {}>(name: Name, data: Data, traits?: Traits) => Entity<Name, NormalizeStructLike<Data>, Traits>;
+/**
+ * Any entity's data — the union of every kind the library knows.
+ *
+ * @remarks
+ * Closed by design: `_tag` identifies the member, so the runner, the
+ * animators, and renderers all narrow on it instead of casting. Consumers
+ * switch on `_tag` and get the exact field set for that entity.
+ */
+export type Entity = (typeof EntityMap)[keyof typeof EntityMap]["Type"];
+/**
+ * Every entity kind's name — `"Circle"`, `"Rect"`, `"Text"`, and the rest.
+ * This is what you pass to `Scene.instantiate`.
+ */
+export type EntityTag = Entity["_tag"];
+/** The data type of one entity kind, selected by its tag. */
+export type EntityByTag<Tag extends EntityTag> = Extract<Entity, {
+    _tag: Tag;
+}>;
+/** the definition (schema) of one entity, by tag */
+type EntityDefinitionByTag<Tag extends EntityTag> = (typeof EntityMap)[Tag];
+export declare const getEntityDefinitionByTag: <Tag extends EntityTag>(tag: Tag) => EntityDefinitionByTag<Tag>;
+/**
+ * The constructor input for one entity: what `make` accepts, with defaulted
+ * fields optional. This is the authoring surface — `instantiate` widens
+ * `children` on top of it (see Runner.InstantiateProps).
+ */
+export type MakeInput<Tag extends EntityTag> = EntityDefinitionByTag<Tag>["~type.make.in"];
+/**
+ * Tags whose entity carries a given field — how animators state their
+ * requirements now that traits are gone. `TagsWith<"opacity">` is every
+ * paintable entity; `fade` constrains on it, so fading a Camera is a
+ * compile error naming the missing field rather than a runtime defect.
+ */
+export type TagsWith<Field extends string> = Extract<Entity, Record<Field, unknown>>["_tag"];
+/** The entity kinds that can hold children: `Group` and `Hud`. */
+export type ContainerTag = TagsWith<"children">;
+/** entity data narrowed to a container */
+type ContainerEntity = Extract<Entity, {
+    children: ReadonlyArray<string>;
+}>;
+/**
+ * Whether an entity can hold children. Previously this was "does its data
+ * have a `children` field", answerable only at runtime because entity shapes
+ * were unknowable; now it is a property of the tag.
+ */
+export declare const isContainer: (entity: Entity) => entity is ContainerEntity;
 export {};