effect-motion 0.4.0 → 0.6.0

package/dist/Timing.d.ts

@@ -1,20 +1,90 @@
 /**
- * Timing (easing) functions: map linear progress t in [0, 1] to eased
- * progress. Every non-periodic easing satisfies f(0) = 0 and f(1) = 1,
- * so tweens land exactly on their target. `sin`/`cos` are periodic
- * helpers over one full cycle and deliberately do NOT end at 1.
- * Back/Elastic curves overshoot outside [0, 1] mid-animation by design —
- * consumers must extrapolate, not clamp.
+ * Easing curves — the shape of an animation's pacing over its duration.
+ *
+ * @remarks
+ * An easing maps linear progress `t` (0 → 1) to eased progress. It changes
+ * only WHEN a value gets where it's going, never where it ends up, so
+ * swapping curves restyles motion without touching its endpoints.
+ *
+ * Pass any of these to an animator by name — `"easeOutCubic"` — which
+ * autocompletes and is the usual form. A `TimingFunction` of your own is
+ * accepted anywhere a name is.
+ *
+ * Choosing one, in short:
+ *
+ * - `linear` — mechanical, constant speed. Good for continuous motion
+ *   (rotation, scrolling), stiff for anything that starts or stops.
+ * - `easeOut*` — fast then settling. The default instinct for something
+ *   ARRIVING; the motion is legible immediately.
+ * - `easeIn*` — slow then accelerating. For something LEAVING.
+ * - `easeInOut*` — eased at both ends; the natural choice for a move
+ *   between two resting states.
+ * - Within each family, `Sine` is the gentlest and `Quad` → `Cubic` →
+ *   `Quart` → `Quint` → `Expo` progressively more pronounced. `Circ` is
+ *   sharper still near the ends.
+ * - `Back`, `Elastic`, `Bounce` — overshoot and oscillation, for character.
+ *   These are how you get spring-LIKE motion in a fixed duration; for true
+ *   physics with an emergent duration, use `Physics` instead.
+ *
+ * Every non-periodic easing satisfies f(0) = 0 and f(1) = 1, which is what
+ * guarantees a tween lands exactly on its target. `Back` and `Elastic`
+ * deliberately leave [0, 1] mid-animation — that overshoot IS the effect, so
+ * consumers extrapolate rather than clamp. `Bounce` stays within [0, 1]: it
+ * rebounds AWAY from the target rather than past it. `sin` and `cos` are the
+ * exceptions to the endpoint rule: they trace a full periodic cycle and
+ * return to where they started.
+ *
+ * @example
+ * By name, and with a custom curve.
+ * ```typescript
+ * yield* box.pipe(Motion.moveTo({ x: 400 }, "1 second", "easeInOutCubic"));
+ * yield* box.pipe(Motion.moveTo({ x: 0 }, "1 second", (t) => t * t));
+ * ```
  */
 export type TimingFunction = (t: number) => number;
+/**
+ * No easing: constant speed from start to finish.
+ *
+ * @remarks
+ * The default when no timing is given. Right for continuous motion that
+ * neither starts nor stops on screen; abrupt for anything that does.
+ *
+ * @see {@link TimingFunction} for choosing among the families.
+ */
 export declare const linear: TimingFunction;
-/** one full sine cycle: 0 → 1 → 0 */
+/**
+ * One full sine cycle: 0 → 1 → 0.
+ *
+ * @remarks
+ * Periodic, so it deliberately RETURNS to its starting value instead of
+ * ending at 1 — a tween using it finishes where it began. That makes it a
+ * there-and-back helper (a pulse, a sway), not a transition between two
+ * states.
+ */
 export declare const sin: TimingFunction;
-/** one full cosine cycle: 1 → 0 → 1 */
+/**
+ * One full cosine cycle: 1 → 0 → 1.
+ *
+ * @remarks
+ * {@link sin} phase-shifted: starts at the far end, dips, and comes back.
+ * Also periodic, so it does not end at 1.
+ */
 export declare const cos: TimingFunction;
+/**
+ * The Sine family — the gentlest easing. Barely-there acceleration, for
+ * motion that should feel eased without drawing attention.
+ *
+ * @see {@link TimingFunction} for choosing among the families.
+ */
 export declare const easeInSine: TimingFunction;
 export declare const easeOutSine: TimingFunction;
 export declare const easeInOutSine: TimingFunction;
+/**
+ * The polynomial families, from gentlest to most pronounced: Quad (t²),
+ * Cubic (t³), Quart (t⁴), Quint (t⁵). Cubic is the everyday workhorse.
+ *
+ * @see {@link TimingFunction} for choosing among the families.
+ */
 export declare const easeInQuad: TimingFunction;
 export declare const easeOutQuad: TimingFunction;
 export declare const easeInOutQuad: TimingFunction;
@@ -27,25 +97,100 @@ export declare const easeInOutQuart: TimingFunction;
 export declare const easeInQuint: TimingFunction;
 export declare const easeOutQuint: TimingFunction;
 export declare const easeInOutQuint: TimingFunction;
+/**
+ * The Expo family — the most extreme of the smooth curves: near-motionless
+ * at the slow end, very fast at the other. For dramatic arrivals and exits.
+ *
+ * @see {@link TimingFunction} for choosing among the families.
+ */
 export declare const easeInExpo: TimingFunction;
 export declare const easeOutExpo: TimingFunction;
 export declare const easeInOutExpo: TimingFunction;
+/**
+ * The Circ family — a quarter-circle arc. Sharper at the ends than the
+ * polynomials, with a distinctly mechanical, geometric feel.
+ *
+ * @see {@link TimingFunction} for choosing among the families.
+ */
 export declare const easeInCirc: TimingFunction;
 export declare const easeOutCirc: TimingFunction;
 export declare const easeInOutCirc: TimingFunction;
-/** `s` is the overshoot amount */
+/**
+ * Build a Back easing with a custom overshoot amount.
+ *
+ * @remarks
+ * Back curves pull slightly PAST the target and come back — the
+ * anticipation that makes an entrance feel deliberate. Use the ready-made
+ * {@link easeInBack} / {@link easeOutBack} / {@link easeInOutBack} unless
+ * you specifically want a different amount of overshoot.
+ *
+ * @param s - Overshoot amount; larger goes further past the target.
+ * @defaultValue `1.70158` — the canonical ~10% overshoot
+ * @returns A {@link TimingFunction} to pass to any animator.
+ *
+ * @example
+ * ```typescript
+ * const subtle = Timing.createEaseOutBack(0.7);
+ * yield* card.pipe(Motion.moveTo({ y: 100 }, "600 millis", subtle));
+ * ```
+ */
 export declare const createEaseInBack: (s?: number) => TimingFunction;
 export declare const createEaseOutBack: (s?: number) => TimingFunction;
 export declare const createEaseInOutBack: (s?: number, v?: number) => TimingFunction;
-/** `s` is the angular frequency (default 2π/3) */
+/**
+ * Build an Elastic easing with a custom oscillation frequency.
+ *
+ * @remarks
+ * Elastic curves overshoot and ring like a plucked string before settling.
+ * Prefer {@link easeInElastic} / {@link easeOutElastic} /
+ * {@link easeInOutElastic} unless you want a different wobble rate.
+ *
+ * @param s - Angular frequency; higher oscillates more times.
+ * @defaultValue `2.094395` (2π/3)
+ * @returns A {@link TimingFunction} to pass to any animator.
+ */
 export declare const createEaseInElastic: (s?: number) => TimingFunction;
 export declare const createEaseOutElastic: (s?: number) => TimingFunction;
-/** `s` is the angular frequency (default 2π/4.5) */
+/**
+ * Build an in-out Elastic easing with a custom oscillation frequency.
+ *
+ * @param s - Angular frequency; higher oscillates more times.
+ * @defaultValue `1.39626` (2π/4.5)
+ * @returns A {@link TimingFunction} to pass to any animator.
+ */
 export declare const createEaseInOutElastic: (s?: number) => TimingFunction;
-/** `n` is the bounce stiffness, `d` the interval divisor */
+/**
+ * Build a Bounce easing with custom stiffness and bounce spacing.
+ *
+ * @remarks
+ * Bounce curves imitate a ball hitting a surface: a series of ever-smaller
+ * rebounds. Unlike Elastic, they never go PAST the target — they arrive and
+ * rebound away from it. Prefer {@link easeOutBounce} and its siblings unless
+ * tuning the character.
+ *
+ * The offsets are derived from the parameters, so f(1) = 1 holds for any
+ * stiffness and a tween still lands exactly.
+ *
+ * @param n - Bounce stiffness.
+ * @param d - Interval divisor, setting how the bounces are spaced.
+ * @defaultValue `n` — `7.5625`; `d` — `2.75` (the canonical CSS bounce)
+ * @returns A {@link TimingFunction} to pass to any animator.
+ */
 export declare const createEaseOutBounce: (n?: number, d?: number) => TimingFunction;
 export declare const createEaseInBounce: (n?: number, d?: number) => TimingFunction;
 export declare const createEaseInOutBounce: (n?: number, d?: number) => TimingFunction;
+/**
+ * The ready-made overshoot and oscillation curves, at their canonical
+ * parameters — `Back` anticipates past the target, `Elastic` rings like a
+ * string, `Bounce` rebounds like a dropped ball.
+ *
+ * @remarks
+ * These are how you get spring-LIKE character in a fixed, known duration.
+ * For real physics whose length emerges from the simulation, use `Physics`.
+ *
+ * @see {@link createEaseInBack}, {@link createEaseInElastic},
+ *   {@link createEaseOutBounce} to tune the parameters.
+ */
 export declare const easeInBack: TimingFunction;
 export declare const easeOutBack: TimingFunction;
 export declare const easeInOutBack: TimingFunction;
@@ -55,6 +200,14 @@ export declare const easeInOutElastic: TimingFunction;
 export declare const easeInBounce: TimingFunction;
 export declare const easeOutBounce: TimingFunction;
 export declare const easeInOutBounce: TimingFunction;
+/**
+ * Every built-in easing, by name — the lookup behind the string form.
+ *
+ * @remarks
+ * You rarely touch this directly: passing `"easeOutCubic"` to an animator
+ * resolves through it. Useful for building a curve picker, or iterating the
+ * whole set.
+ */
 export declare const timingFunctions: {
     readonly linear: TimingFunction;
     readonly sin: TimingFunction;
@@ -90,7 +243,11 @@ export declare const timingFunctions: {
     readonly easeOutBounce: TimingFunction;
     readonly easeInOutBounce: TimingFunction;
 };
+/** The name of a built-in easing — what animators autocomplete. */
 export type TimingFunctionName = keyof typeof timingFunctions;
-/** a built-in name (autocompleted) or a custom timing function */
+/**
+ * What animators accept for pacing: a built-in easing name, or your own
+ * `(t: number) => number`.
+ */
 export type TimingInput = TimingFunctionName | TimingFunction;
 export declare const resolve: (input: TimingInput) => TimingFunction;

package/dist/Timing.js

@@ -1,14 +1,49 @@
+/**
+ * No easing: constant speed from start to finish.
+ *
+ * @remarks
+ * The default when no timing is given. Right for continuous motion that
+ * neither starts nor stops on screen; abrupt for anything that does.
+ *
+ * @see {@link TimingFunction} for choosing among the families.
+ */
 export const linear = (t) => t;
-/** one full sine cycle: 0 → 1 → 0 */
+/**
+ * One full sine cycle: 0 → 1 → 0.
+ *
+ * @remarks
+ * Periodic, so it deliberately RETURNS to its starting value instead of
+ * ending at 1 — a tween using it finishes where it began. That makes it a
+ * there-and-back helper (a pulse, a sway), not a transition between two
+ * states.
+ */
 export const sin = (t) => (1 - Math.cos(2 * Math.PI * t)) / 2;
-/** one full cosine cycle: 1 → 0 → 1 */
+/**
+ * One full cosine cycle: 1 → 0 → 1.
+ *
+ * @remarks
+ * {@link sin} phase-shifted: starts at the far end, dips, and comes back.
+ * Also periodic, so it does not end at 1.
+ */
 export const cos = (t) => (1 + Math.cos(2 * Math.PI * t)) / 2;
+/**
+ * The Sine family — the gentlest easing. Barely-there acceleration, for
+ * motion that should feel eased without drawing attention.
+ *
+ * @see {@link TimingFunction} for choosing among the families.
+ */
 export const easeInSine = (t) => 1 - Math.cos((t * Math.PI) / 2);
 export const easeOutSine = (t) => Math.sin((t * Math.PI) / 2);
 export const easeInOutSine = (t) => -(Math.cos(Math.PI * t) - 1) / 2;
 const easeInPow = (p) => (t) => t ** p;
 const easeOutPow = (p) => (t) => 1 - (1 - t) ** p;
 const easeInOutPow = (p) => (t) => t < 0.5 ? 2 ** (p - 1) * t ** p : 1 - (-2 * t + 2) ** p / 2;
+/**
+ * The polynomial families, from gentlest to most pronounced: Quad (t²),
+ * Cubic (t³), Quart (t⁴), Quint (t⁵). Cubic is the everyday workhorse.
+ *
+ * @see {@link TimingFunction} for choosing among the families.
+ */
 export const easeInQuad = easeInPow(2);
 export const easeOutQuad = easeOutPow(2);
 export const easeInOutQuad = easeInOutPow(2);
@@ -21,6 +56,12 @@ export const easeInOutQuart = easeInOutPow(4);
 export const easeInQuint = easeInPow(5);
 export const easeOutQuint = easeOutPow(5);
 export const easeInOutQuint = easeInOutPow(5);
+/**
+ * The Expo family — the most extreme of the smooth curves: near-motionless
+ * at the slow end, very fast at the other. For dramatic arrivals and exits.
+ *
+ * @see {@link TimingFunction} for choosing among the families.
+ */
 export const easeInExpo = (t) => t === 0 ? 0 : 2 ** (10 * t - 10);
 export const easeOutExpo = (t) => t === 1 ? 1 : 1 - 2 ** (-10 * t);
 export const easeInOutExpo = (t) => t === 0
@@ -30,12 +71,36 @@ export const easeInOutExpo = (t) => t === 0
         : t < 0.5
             ? 2 ** (20 * t - 10) / 2
             : (2 - 2 ** (-20 * t + 10)) / 2;
+/**
+ * The Circ family — a quarter-circle arc. Sharper at the ends than the
+ * polynomials, with a distinctly mechanical, geometric feel.
+ *
+ * @see {@link TimingFunction} for choosing among the families.
+ */
 export const easeInCirc = (t) => 1 - Math.sqrt(1 - t ** 2);
 export const easeOutCirc = (t) => Math.sqrt(1 - (t - 1) ** 2);
 export const easeInOutCirc = (t) => t < 0.5
     ? (1 - Math.sqrt(1 - (2 * t) ** 2)) / 2
     : (Math.sqrt(1 - (-2 * t + 2) ** 2) + 1) / 2;
-/** `s` is the overshoot amount */
+/**
+ * Build a Back easing with a custom overshoot amount.
+ *
+ * @remarks
+ * Back curves pull slightly PAST the target and come back — the
+ * anticipation that makes an entrance feel deliberate. Use the ready-made
+ * {@link easeInBack} / {@link easeOutBack} / {@link easeInOutBack} unless
+ * you specifically want a different amount of overshoot.
+ *
+ * @param s - Overshoot amount; larger goes further past the target.
+ * @defaultValue `1.70158` — the canonical ~10% overshoot
+ * @returns A {@link TimingFunction} to pass to any animator.
+ *
+ * @example
+ * ```typescript
+ * const subtle = Timing.createEaseOutBack(0.7);
+ * yield* card.pipe(Motion.moveTo({ y: 100 }, "600 millis", subtle));
+ * ```
+ */
 export const createEaseInBack = (s = 1.70158) => (t) => (s + 1) * t ** 3 - s * t ** 2;
 export const createEaseOutBack = (s = 1.70158) => (t) => 1 + (s + 1) * (t - 1) ** 3 + s * (t - 1) ** 2;
 export const createEaseInOutBack = (s = 1.70158, v = 1.525) => {
@@ -44,7 +109,18 @@ export const createEaseInOutBack = (s = 1.70158, v = 1.525) => {
         ? ((2 * t) ** 2 * ((c + 1) * 2 * t - c)) / 2
         : ((2 * t - 2) ** 2 * ((c + 1) * (2 * t - 2) + c) + 2) / 2;
 };
-/** `s` is the angular frequency (default 2π/3) */
+/**
+ * Build an Elastic easing with a custom oscillation frequency.
+ *
+ * @remarks
+ * Elastic curves overshoot and ring like a plucked string before settling.
+ * Prefer {@link easeInElastic} / {@link easeOutElastic} /
+ * {@link easeInOutElastic} unless you want a different wobble rate.
+ *
+ * @param s - Angular frequency; higher oscillates more times.
+ * @defaultValue `2.094395` (2π/3)
+ * @returns A {@link TimingFunction} to pass to any animator.
+ */
 export const createEaseInElastic = (s = 2.094395) => (t) => t === 0
     ? 0
     : t === 1
@@ -55,7 +131,13 @@ export const createEaseOutElastic = (s = 2.094395) => (t) => t === 0
     : t === 1
         ? 1
         : 2 ** (-10 * t) * Math.sin((t * 10 - 0.75) * s) + 1;
-/** `s` is the angular frequency (default 2π/4.5) */
+/**
+ * Build an in-out Elastic easing with a custom oscillation frequency.
+ *
+ * @param s - Angular frequency; higher oscillates more times.
+ * @defaultValue `1.39626` (2π/4.5)
+ * @returns A {@link TimingFunction} to pass to any animator.
+ */
 export const createEaseInOutElastic = (s = 1.39626) => (t) => t === 0
     ? 0
     : t === 1
@@ -63,7 +145,23 @@ export const createEaseInOutElastic = (s = 1.39626) => (t) => t === 0
         : t < 0.5
             ? -(2 ** (20 * t - 10) * Math.sin((20 * t - 11.125) * s)) / 2
             : (2 ** (-20 * t + 10) * Math.sin((20 * t - 11.125) * s)) / 2 + 1;
-/** `n` is the bounce stiffness, `d` the interval divisor */
+/**
+ * Build a Bounce easing with custom stiffness and bounce spacing.
+ *
+ * @remarks
+ * Bounce curves imitate a ball hitting a surface: a series of ever-smaller
+ * rebounds. Unlike Elastic, they never go PAST the target — they arrive and
+ * rebound away from it. Prefer {@link easeOutBounce} and its siblings unless
+ * tuning the character.
+ *
+ * The offsets are derived from the parameters, so f(1) = 1 holds for any
+ * stiffness and a tween still lands exactly.
+ *
+ * @param n - Bounce stiffness.
+ * @param d - Interval divisor, setting how the bounces are spaced.
+ * @defaultValue `n` — `7.5625`; `d` — `2.75` (the canonical CSS bounce)
+ * @returns A {@link TimingFunction} to pass to any animator.
+ */
 export const createEaseOutBounce = (n = 7.5625, d = 2.75) => {
     // segment offsets derived from the parameters so f(1) = 1 holds for
     // any stiffness (defaults yield the canonical 0.75/0.9375/0.984375)
@@ -94,6 +192,18 @@ export const createEaseInOutBounce = (n = 7.5625, d = 2.75) => {
     const out = createEaseOutBounce(n, d);
     return (t) => (t < 0.5 ? (1 - out(1 - 2 * t)) / 2 : (1 + out(2 * t - 1)) / 2);
 };
+/**
+ * The ready-made overshoot and oscillation curves, at their canonical
+ * parameters — `Back` anticipates past the target, `Elastic` rings like a
+ * string, `Bounce` rebounds like a dropped ball.
+ *
+ * @remarks
+ * These are how you get spring-LIKE character in a fixed, known duration.
+ * For real physics whose length emerges from the simulation, use `Physics`.
+ *
+ * @see {@link createEaseInBack}, {@link createEaseInElastic},
+ *   {@link createEaseOutBounce} to tune the parameters.
+ */
 export const easeInBack = createEaseInBack();
 export const easeOutBack = createEaseOutBack();
 export const easeInOutBack = createEaseInOutBack();
@@ -103,6 +213,14 @@ export const easeInOutElastic = createEaseInOutElastic();
 export const easeInBounce = createEaseInBounce();
 export const easeOutBounce = createEaseOutBounce();
 export const easeInOutBounce = createEaseInOutBounce();
+/**
+ * Every built-in easing, by name — the lookup behind the string form.
+ *
+ * @remarks
+ * You rarely touch this directly: passing `"easeOutCubic"` to an animator
+ * resolves through it. Useful for building a curve picker, or iterating the
+ * whole set.
+ */
 export const timingFunctions = {
     linear,
     sin,

package/dist/Tree.d.ts

@@ -0,0 +1,39 @@
+import * as Entity from "./Entity.js";
+/**
+ * The runner's scene graph: id → entry, plus parent/child bookkeeping.
+ *
+ * An entry holds the entity's current state as a member of the closed union
+ * (`Entity.ts`), so reading a field means narrowing on `_tag` rather than
+ * casting from `{}`. The entity DEFINITION is not stored — it is resolved
+ * from the state's tag when construction is needed.
+ */
+/** conventional id of the implicit root group every instance attaches to */
+export declare const ROOT_ID = "root";
+export interface Entry<Tag extends Entity.EntityTag = Entity.EntityTag> {
+    readonly id: string;
+    state: Entity.EntityByTag<Tag>;
+    parentId: string | null;
+}
+export type Entryish = Entry | string;
+export declare class Tree {
+    private idCounter;
+    readonly map: Record<string, Entry>;
+    /**
+     * Returns a plain `Entry`, not `Entry<Tag>`: `state` is mutable, so a
+     * tagged entry is invariant and cannot live in a map of mixed tags. The
+     * tag lives on the caller's `Instance<Tag>` instead, which is immutable
+     * and where the narrowing is actually wanted.
+     */
+    createNode: (state: Entity.Entity, id?: string) => Entry;
+    getEntry: (entryish: Entryish) => Entry | null;
+    /**
+     * Frames snapshot `entry.state` by reference, so a child-list update must
+     * produce a FRESH object — mutating in place would rewrite frames that
+     * were already emitted.
+     */
+    private setChildren;
+    removeFromParent: (entryish: Entryish) => void;
+    appendChild: (parentish: Entryish, childish: Entryish) => void;
+    insertBefore: (childish: Entryish, beforeish: Entryish) => void;
+    remove: (entryish: Entryish) => void;
+}

package/dist/Tree.js

@@ -0,0 +1,127 @@
+import * as Entity from "./Entity.js";
+/**
+ * The runner's scene graph: id → entry, plus parent/child bookkeeping.
+ *
+ * An entry holds the entity's current state as a member of the closed union
+ * (`Entity.ts`), so reading a field means narrowing on `_tag` rather than
+ * casting from `{}`. The entity DEFINITION is not stored — it is resolved
+ * from the state's tag when construction is needed.
+ */
+/** conventional id of the implicit root group every instance attaches to */
+export const ROOT_ID = "root";
+const idOf = (entryish) => typeof entryish === "string" ? entryish : entryish.id;
+const nodeNotFound = (entryish) => {
+    throw new Error(`Runner: node "${idOf(entryish)}" not found`);
+};
+/**
+ * A parent that cannot hold children. Under the closed union this is knowable
+ * from the tag, so the message names what the entity actually is.
+ */
+const notAContainer = (entry) => {
+    throw new Error(`Runner: parent "${entry.id}" is a ${entry.state._tag}, which cannot have children`);
+};
+/** the entry's children, or a loud failure if its entity is not a container */
+const childrenOrDie = (entry) => Entity.isContainer(entry.state) ? entry.state.children : notAContainer(entry);
+export class Tree {
+    idCounter = 0;
+    map = {
+        [ROOT_ID]: {
+            id: ROOT_ID,
+            state: Entity.Group.make({}),
+            parentId: null,
+        },
+    };
+    /**
+     * Returns a plain `Entry`, not `Entry<Tag>`: `state` is mutable, so a
+     * tagged entry is invariant and cannot live in a map of mixed tags. The
+     * tag lives on the caller's `Instance<Tag>` instead, which is immutable
+     * and where the narrowing is actually wanted.
+     */
+    createNode = (state, 
+    // engine-owned singletons (the built-in camera) claim a fixed id
+    id = `${state._tag}_${this.idCounter++}`) => {
+        const entry = { id, state, parentId: null };
+        this.map[id] = entry;
+        return entry;
+    };
+    getEntry = (entryish) => this.map[idOf(entryish)] ?? null;
+    /**
+     * Frames snapshot `entry.state` by reference, so a child-list update must
+     * produce a FRESH object — mutating in place would rewrite frames that
+     * were already emitted.
+     */
+    setChildren = (parent, children) => {
+        const state = parent.state;
+        // switch, not a cast: spreading a UNION member widens back to the union
+        // and loses the tag, so narrow to the concrete tag first and let each
+        // branch produce a well-typed Group/Hud.
+        switch (state._tag) {
+            case "Group":
+                parent.state = { ...state, children };
+                return;
+            case "Hud":
+                parent.state = { ...state, children };
+                return;
+            default:
+                notAContainer(parent);
+        }
+    };
+    removeFromParent = (entryish) => {
+        const entry = this.getEntry(entryish) ?? nodeNotFound(entryish);
+        if (entry.parentId === null) {
+            return;
+        }
+        // a parent that was itself removed: nothing to filter, just detach
+        const parent = this.getEntry(entry.parentId);
+        if (parent !== null) {
+            this.setChildren(parent, childrenOrDie(parent).filter((childId) => childId !== entry.id));
+        }
+        entry.parentId = null;
+    };
+    appendChild = (parentish, childish) => {
+        const child = this.getEntry(childish) ?? nodeNotFound(childish);
+        this.removeFromParent(child);
+        const parent = this.getEntry(parentish) ?? nodeNotFound(parentish);
+        this.setChildren(parent, [...childrenOrDie(parent), child.id]);
+        child.parentId = parent.id;
+    };
+    insertBefore = (childish, beforeish) => {
+        const child = this.getEntry(childish) ?? nodeNotFound(childish);
+        const before = this.getEntry(beforeish) ?? nodeNotFound(beforeish);
+        this.removeFromParent(child);
+        if (before.parentId === null) {
+            throw new Error(`Runner: before "${before.id}" is not a child`);
+        }
+        const parent = this.getEntry(before.parentId) ?? nodeNotFound(before.parentId);
+        const children = [];
+        let inserted = false;
+        for (const childId of childrenOrDie(parent)) {
+            if (childId === before.id) {
+                children.push(child.id);
+                inserted = true;
+            }
+            children.push(childId);
+        }
+        if (!inserted) {
+            children.push(child.id);
+        }
+        this.setChildren(parent, children);
+        child.parentId = parent.id;
+    };
+    remove = (entryish) => {
+        const entry = this.getEntry(entryish) ?? nodeNotFound(entryish);
+        this.removeFromParent(entry);
+        delete this.map[entry.id];
+        // orphan its children, and backstop-scan child lists: stays correct even
+        // after manual reparenting via raw data updates (which bypass parentId)
+        for (const other of Object.values(this.map)) {
+            if (other.parentId === entry.id) {
+                other.parentId = null;
+            }
+            if (Entity.isContainer(other.state) &&
+                other.state.children.includes(entry.id)) {
+                this.setChildren(other, other.state.children.filter((childId) => childId !== entry.id));
+            }
+        }
+    };
+}

package/dist/index.d.ts

@@ -1,14 +1,63 @@
-export * as Camera from "./CameraHelpers.js";
+/**
+ * effect-motion — deterministic, frame-exact motion graphics in code.
+ *
+ * @remarks
+ * Scenes are pure descriptions of animation: the same scene produces the
+ * same frames on every run and every machine, because time is counted in
+ * frames rather than read from a clock and randomness comes from a seed.
+ *
+ * Where to start:
+ *
+ * - `Scene` — declare a scene, create entities, compose animations, run it.
+ * - `Motion` — animate over a duration, with easing.
+ * - `Physics` — animate with springs, whose length emerges from the sim.
+ * - `Entity` — the shapes, and `vec3` for positions.
+ * - `Color`, `Timing` — the palette and the easing curves.
+ * - `Camera` — aiming, orbiting, and dollying the viewpoint.
+ *
+ * Prefer deep per-actor imports over this barrel:
+ *
+ * ```typescript
+ * import * as Motion from "effect-motion/Motion";
+ * import * as Scene from "effect-motion/Scene";
+ * ```
+ *
+ * @example
+ * A complete scene.
+ * ```typescript
+ * import * as Color from "effect-motion/Color";
+ * import * as Motion from "effect-motion/Motion";
+ * import * as Scene from "effect-motion/Scene";
+ *
+ * export const scene = Scene.make(
+ * 	function* () {
+ * 		const dot = yield* Scene.instantiate("Circle", {
+ * 			radius: 24,
+ * 			fillColor: Color.hex("#7f5af0"),
+ * 		});
+ * 		yield* dot.pipe(
+ * 			Motion.moveTo({ x: 430 }, "1 second", "easeInOutCubic"),
+ * 			Motion.fadeTo(0, "400 millis"),
+ * 		);
+ * 	},
+ * 	{ width: 500, height: 300, backgroundColor: Color.rgba(22, 22, 29) },
+ * );
+ * ```
+ *
+ * @packageDocumentation
+ */
+export * as Camera from "./Camera.js";
 export * as Color from "./Color.js";
+export { EffectMotionError } from "./EffectMotionError.js";
 export * as Entity from "./Entity.js";
-export * as Fonts from "./Fonts.js";
-export * as Images from "./Images.js";
+export * as Font from "./Font.js";
+export * as Image from "./Image.js";
 export * as Instance from "./Instance.js";
 export * as Motion from "./Motion.js";
 export * as Phaser from "./Phaser.js";
 export * as Physics from "./Physics.js";
 export * as Particles from "./particles/index.js";
-export * as Renderer from "./Renderer.js";
+export * as Resource from "./Resource.js";
+export * as Runner from "./Runner.js";
 export * as Scene from "./Scene.js";
-export * as Shapes from "./Shapes.js";
 export * as Timing from "./Timing.js";