effect-motion 0.4.0 → 0.6.0

package/dist/index.js

@@ -1,14 +1,65 @@
-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";
+// the closed entity world: the union and its tags
 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";
+// a reference to a live entity in the runner tree
 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";

package/dist/particles/Particle.d.ts

@@ -57,7 +57,7 @@ export interface EmitterConfig {
     readonly y: number;
     /** launch speed range (px/sec) */
     readonly speed: Range;
-    /** launch angle range (degrees; 0 = up, clockwise-positive) */
+    /** launch angle range (degrees; 0 = up, counterclockwise-positive) */
     readonly angle: Range;
     /** lifetime range (seconds) */
     readonly life: Range;
@@ -66,7 +66,7 @@ export interface EmitterConfig {
     /** birth opacity range (0..1), drawn per particle; the over-life opacity
      * curve (if any) multiplies this baseline. Omit → every particle 1. */
     readonly opacity?: Range;
-    /** shared downward acceleration (px/sec²); not ranged */
+    /** shared screen-downward (-y) acceleration (px/sec²); not ranged */
     readonly gravity: number;
     /** colors drawn from uniformly at birth */
     readonly palette: ReadonlyArray<Color.Color>;

package/dist/particles/ParticleField.d.ts

@@ -1,7 +1,7 @@
 import * as Schema from "effect/Schema";
 import * as Color from "../Color.js";
-import * as Entity from "../Entity.js";
-export declare const ParticleField: Entity.Entity<"particles/ParticleField", Schema.Struct<{
+import * as Legacy from "./legacy.js";
+export declare const ParticleField: Legacy.Entity<"particles/ParticleField", {
     x: Schema.withConstructorDefault<Schema.Number>;
     y: Schema.withConstructorDefault<Schema.Number>;
     z: Schema.withConstructorDefault<Schema.Number>;
@@ -43,8 +43,9 @@ export declare const ParticleField: Entity.Entity<"particles/ParticleField", Sch
         readonly alive: Schema.Boolean;
         readonly wrap: Schema.Boolean;
     }>>>;
-}>, {
-    readonly "~position": Entity.TraitLens<{
+}, {
+    readonly "~position": Legacy.TraitLens<{
+        readonly "~visible": boolean;
         readonly x: number;
         readonly y: number;
         readonly z: number;
@@ -56,10 +57,10 @@ export declare const ParticleField: Entity.Entity<"particles/ParticleField", Sch
         readonly opacityRange: readonly [number, number];
         readonly gravity: number;
         readonly palette: readonly Color.Color[];
-        readonly region?: Schema.Struct.ReadonlySide<{
-            readonly w: Schema.Number;
-            readonly h: Schema.Number;
-        }, "Type">;
+        readonly region?: {
+            readonly w: number;
+            readonly h: number;
+        };
         readonly drift?: readonly [number, number];
         readonly sizeOverLife?: {
             readonly from: number;
@@ -72,22 +73,23 @@ export declare const ParticleField: Entity.Entity<"particles/ParticleField", Sch
             readonly ease?: string;
         };
         readonly capacity: number;
-        readonly buffer: readonly Schema.Struct.ReadonlySide<{
-            readonly x: Schema.Number;
-            readonly y: Schema.Number;
-            readonly vx: Schema.Number;
-            readonly vy: Schema.Number;
-            readonly age: Schema.Number;
-            readonly life: Schema.Number;
-            readonly size: Schema.Number;
-            readonly opacity: Schema.Number;
-            readonly color: typeof Color.Color;
-            readonly rng: Schema.Number;
-            readonly alive: Schema.Boolean;
-            readonly wrap: Schema.Boolean;
-        }, "Type">[];
-    }, Entity.Position>;
-    readonly "~opacity": Entity.TraitLens<{
+        readonly buffer: readonly {
+            readonly x: number;
+            readonly y: number;
+            readonly vx: number;
+            readonly vy: number;
+            readonly age: number;
+            readonly life: number;
+            readonly size: number;
+            readonly opacity: number;
+            readonly color: Color.Color;
+            readonly rng: number;
+            readonly alive: boolean;
+            readonly wrap: boolean;
+        }[];
+    }, Legacy.Position>;
+    readonly "~opacity": Legacy.TraitLens<{
+        readonly "~visible": boolean;
         readonly x: number;
         readonly y: number;
         readonly z: number;
@@ -99,10 +101,10 @@ export declare const ParticleField: Entity.Entity<"particles/ParticleField", Sch
         readonly opacityRange: readonly [number, number];
         readonly gravity: number;
         readonly palette: readonly Color.Color[];
-        readonly region?: Schema.Struct.ReadonlySide<{
-            readonly w: Schema.Number;
-            readonly h: Schema.Number;
-        }, "Type">;
+        readonly region?: {
+            readonly w: number;
+            readonly h: number;
+        };
         readonly drift?: readonly [number, number];
         readonly sizeOverLife?: {
             readonly from: number;
@@ -115,19 +117,19 @@ export declare const ParticleField: Entity.Entity<"particles/ParticleField", Sch
             readonly ease?: string;
         };
         readonly capacity: number;
-        readonly buffer: readonly Schema.Struct.ReadonlySide<{
-            readonly x: Schema.Number;
-            readonly y: Schema.Number;
-            readonly vx: Schema.Number;
-            readonly vy: Schema.Number;
-            readonly age: Schema.Number;
-            readonly life: Schema.Number;
-            readonly size: Schema.Number;
-            readonly opacity: Schema.Number;
-            readonly color: typeof Color.Color;
-            readonly rng: Schema.Number;
-            readonly alive: Schema.Boolean;
-            readonly wrap: Schema.Boolean;
-        }, "Type">[];
+        readonly buffer: readonly {
+            readonly x: number;
+            readonly y: number;
+            readonly vx: number;
+            readonly vy: number;
+            readonly age: number;
+            readonly life: number;
+            readonly size: number;
+            readonly opacity: number;
+            readonly color: Color.Color;
+            readonly rng: number;
+            readonly alive: boolean;
+            readonly wrap: boolean;
+        }[];
     }, number>;
 }>;

package/dist/particles/ParticleField.js

@@ -1,8 +1,7 @@
 import * as Effect from "effect/Effect";
 import * as Schema from "effect/Schema";
 import * as Color from "../Color.js";
-import * as Entity from "../Entity.js";
-import * as Shape2D from "../shapes/Shape2D.js";
+import * as Legacy from "./legacy.js";
 /**
  * A ParticleField is ONE entity/instance backing many particles. Its data
  * holds the emitter config plus a fixed-capacity buffer of live particle
@@ -37,11 +36,11 @@ const ParticleSchema = Schema.Struct({
     alive: Schema.Boolean,
     wrap: Schema.Boolean,
 });
-export const ParticleField = Entity.make("particles/ParticleField", {
+export const ParticleField = Legacy.make("particles/ParticleField", {
     // emitter origin doubles as the field's position (x/y), so the field
     // participates in the position trait like any shape
-    ...Shape2D.position,
-    ...Shape2D.opacity,
+    ...Legacy.position,
+    ...Legacy.opacity,
     // emitter config. speed/angle/life are emitter-mode props; the typed
     // `emitter()`/`field()` constructors gate which an author may set, but
     // the underlying schema defaults them so ONE struct serves both modes.
@@ -53,7 +52,7 @@ export const ParticleField = Entity.make("particles/ParticleField", {
     // opacity curve multiplies it. Named distinctly from the field's own
     // `opacity` (the ~opacity trait above, which fades the whole field).
     opacityRange: defaultedRange([1, 1]),
-    gravity: Shape2D.defaultedNumber(0),
+    gravity: Legacy.defaultedNumber(0),
     palette: Schema.Array(Color.Color).pipe(Schema.withConstructorDefault(Effect.sync(() => [Color.white]))),
     // fill mode: the region particles spread across and wrap within
     // (defaults to the frame in `simulate`) and their drift speed range
@@ -62,9 +61,9 @@ export const ParticleField = Entity.make("particles/ParticleField", {
     sizeOverLife: Schema.optionalKey(OverLifeSchema),
     opacityOverLife: Schema.optionalKey(OverLifeSchema),
     // lifecycle state
-    capacity: Shape2D.defaultedNumber(1024),
+    capacity: Legacy.defaultedNumber(1024),
     buffer: Schema.Array(ParticleSchema).pipe(Schema.withConstructorDefault(Effect.sync(() => []))),
 }, {
-    "~position": Shape2D.positionLens(),
-    "~opacity": Shape2D.opacityLens(),
+    "~position": Legacy.positionLens(),
+    "~opacity": Legacy.opacityLens(),
 });

package/dist/particles/constructors.d.ts

@@ -1,9 +1,8 @@
-import type * as Effect from "effect/Effect";
+import * as Effect from "effect/Effect";
 import type * as Color from "../Color.js";
 import type * as Instance from "../Instance.js";
-import type * as Runner from "../Runner.js";
+import * as Runner from "../Runner.js";
 import type { Range } from "./Particle.js";
-import { ParticleField } from "./ParticleField.js";
 /**
  * Two typed front doors onto the SAME `ParticleField` entity. The field's
  * emission model is chosen at `simulate`, but the properties that make sense
@@ -15,7 +14,7 @@ import { ParticleField } from "./ParticleField.js";
  */
 declare const EmitterBrand: unique symbol;
 declare const FloatBrand: unique symbol;
-type BaseField = Instance.Of<typeof ParticleField>;
+type BaseField = Instance.Instance;
 /** an emitter (source) field — simulate with `{ burst }` or `{ rate }` */
 export type EmitterField = BaseField & {
     readonly [EmitterBrand]: true;
@@ -40,7 +39,7 @@ interface CommonInput {
     readonly opacityRange?: Range;
     /** colors drawn from uniformly at birth */
     readonly palette?: ReadonlyArray<Color.Color>;
-    /** shared downward acceleration (px/sec²) */
+    /** shared screen-downward (-y) acceleration (px/sec²) */
     readonly gravity?: number;
     readonly sizeOverLife?: OverLifeInput;
     readonly opacityOverLife?: OverLifeInput;
@@ -51,7 +50,7 @@ interface CommonInput {
 export interface EmitterInput extends CommonInput {
     /** launch speed range (px/sec) */
     readonly speed: Range;
-    /** launch angle range (degrees; 0 = up, clockwise-positive) */
+    /** launch angle range (degrees; 0 = up, counterclockwise-positive) */
     readonly angle: Range;
     /** lifetime range (seconds) */
     readonly life: Range;

package/dist/particles/constructors.js

@@ -1,4 +1,5 @@
-import * as Scene from "../Scene.js";
+import * as Effect from "effect/Effect";
+import * as Runner from "../Runner.js";
 import { ParticleField } from "./ParticleField.js";
 /**
  * Create a source emitter field. Simulate it with `{ burst: n }` (all at
@@ -7,9 +8,13 @@ import { ParticleField } from "./ParticleField.js";
 export const emitter = (props) => 
 // the entity schema is one struct with defaults; the branded return type
 // is a compile-time cast, runtime data is a plain ParticleField
-Scene.instantiate(ParticleField, props);
+// ponytail: particles are outside the entity union (design D10) — this
+// goes through the escape hatch until the particle system is rewritten
+Effect.flatMap(Runner.Runner, (runner) => Runner.particlesEscapeInstantiate(runner, ParticleField.data.make(props)));
 /**
  * Create a floating field: particles spread evenly across the region,
  * drifting and wrapping at the edges. Simulate it with `{ fill: n }`.
  */
-export const field = (props) => Scene.instantiate(ParticleField, props);
+export const field = (props) => 
+// ponytail: see `emitter` above — the same D10 escape hatch
+Effect.flatMap(Runner.Runner, (runner) => Runner.particlesEscapeInstantiate(runner, ParticleField.data.make(props)));

package/dist/particles/legacy.d.ts

@@ -0,0 +1,58 @@
+import * as Schema from "effect/Schema";
+/**
+ * ponytail: the pre-union entity machinery, kept alive for the particle
+ * system ALONE (design D10).
+ *
+ * ParticleField is not a member of the closed entity union. It is slated for
+ * a full rewrite, so porting it to a model it will not keep would be
+ * throwaway work — but six example scenes depend on it, so it cannot be
+ * deleted either. This file is the entire remnant of `Entity.ts` and
+ * `shapes/Legacy.ts`, scoped to `particles/` and reachable from nowhere
+ * else.
+ *
+ * Upgrade path: fold ParticleField into the union (or justify its
+ * exclusion) as part of the particles rewrite, then delete this file.
+ */
+export declare const TypeId: "~motion/Entity";
+export interface TraitLens<Data, Value> {
+    readonly get: (data: Data) => Value;
+    readonly set: (data: Data, value: Value) => Data;
+}
+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>;
+};
+export type EntityData<Data extends Schema.Struct.Fields> = Schema.Struct<Data & {
+    readonly "~visible": Schema.withConstructorDefault<Schema.Boolean>;
+}>;
+export type PartialTraits<Data extends Schema.Struct.Fields> = Partial<EntityTraits<EntityData<Data>["Type"]>>;
+export interface Entity<Name extends string = string, Data extends Schema.Struct.Fields = {}, Traits extends PartialTraits<Data> = {}> {
+    readonly [TypeId]: typeof TypeId;
+    readonly name: Name;
+    readonly data: EntityData<Data>;
+    readonly traits: Traits;
+}
+export declare const make: <Name extends string, Data extends Schema.Struct.Fields = {}, const Traits extends PartialTraits<Data> = {}>(name: Name, data: Data, traits?: Traits) => Entity<Name, Data, Traits>;
+export declare const is: (u: unknown) => u is Entity<string, {}, {}>;
+export declare const defaultedNumber: (value: number) => Schema.withConstructorDefault<Schema.Number>;
+export declare const position: {
+    x: Schema.withConstructorDefault<Schema.Number>;
+    y: Schema.withConstructorDefault<Schema.Number>;
+    z: Schema.withConstructorDefault<Schema.Number>;
+};
+export declare const opacity: {
+    opacity: Schema.withConstructorDefault<Schema.Number>;
+};
+export declare const positionLens: <Data extends {
+    x: number;
+    y: number;
+    z: number;
+}>() => TraitLens<Data, Position>;
+export declare const opacityLens: <Data extends {
+    opacity: number;
+}>() => TraitLens<Data, number>;

package/dist/particles/legacy.js

@@ -0,0 +1,46 @@
+import { Predicate } from "effect";
+import * as Effect from "effect/Effect";
+import * as Schema from "effect/Schema";
+/**
+ * ponytail: the pre-union entity machinery, kept alive for the particle
+ * system ALONE (design D10).
+ *
+ * ParticleField is not a member of the closed entity union. It is slated for
+ * a full rewrite, so porting it to a model it will not keep would be
+ * throwaway work — but six example scenes depend on it, so it cannot be
+ * deleted either. This file is the entire remnant of `Entity.ts` and
+ * `shapes/Legacy.ts`, scoped to `particles/` and reachable from nowhere
+ * else.
+ *
+ * Upgrade path: fold ParticleField into the union (or justify its
+ * exclusion) as part of the particles rewrite, then delete this file.
+ */
+export const TypeId = "~motion/Entity";
+export const make = (name, data, traits) => ({
+    [TypeId]: TypeId,
+    name,
+    data: Schema.Struct({
+        ...data,
+        "~visible": Schema.Boolean.pipe(Schema.withConstructorDefault(Effect.succeed(true))),
+    }),
+    traits: traits ?? {},
+});
+export const is = (u) => Predicate.hasProperty(u, TypeId);
+// ── the Shape2D field helpers particles use ──────────────────────────────
+export const defaultedNumber = (value) => Schema.Number.pipe(Schema.withConstructorDefault(Effect.succeed(value)));
+export const position = {
+    x: defaultedNumber(0),
+    y: defaultedNumber(0),
+    z: defaultedNumber(0),
+};
+export const opacity = {
+    opacity: defaultedNumber(1),
+};
+export const positionLens = () => ({
+    get: (data) => ({ x: data.x, y: data.y, z: data.z }),
+    set: (data, value) => ({ ...data, x: value.x, y: value.y, z: value.z }),
+});
+export const opacityLens = () => ({
+    get: (data) => data.opacity,
+    set: (data, opacity) => ({ ...data, opacity }),
+});

package/dist/particles/simulate.js

@@ -23,6 +23,9 @@ const birthsForFrame = (emission, i, fps) => {
     const now = Math.floor(perFrame * i);
     return now - before;
 };
+const unreachableField = (id) => {
+    throw new Error(`Particles: field "${id}" was destroyed mid-simulation`);
+};
 // read the field's current config out of its data. `region` is the fill
 // area (defaulted to the frame by the caller); particles are positioned in
 // the field's LOCAL space (origin 0,0) — the field's x/y transform offsets
@@ -49,7 +52,10 @@ const run = Effect.fnUntraced(function* (instance, duration, emission) {
     const dt = 1 / fps;
     const mode = "fill" in emission ? "fill" : "emit";
     // fill spreads across a region: the field's own if set, else the frame
-    const current = yield* Scene.data(instance);
+    // ponytail: particles are outside the entity union (design D10) — read
+    // and write go through the escape hatch until the system is rewritten
+    const current = Runner.particlesEscapeRead(runner, instance) ??
+        unreachableField(instance.id);
     const region = {
         w: current.region?.w ?? runner.comp.width,
         h: current.region?.h ?? runner.comp.height,
@@ -62,14 +68,16 @@ const run = Effect.fnUntraced(function* (instance, duration, emission) {
         for (let s = 0; s < n; s++) {
             seeds.push(Prng.seedFrom(yield* Random.next));
         }
-        yield* Scene.update(instance, (data) => {
+        yield* Effect.sync(() => {
+            const data = Runner.particlesEscapeRead(runner, instance) ??
+                unreachableField(instance.id);
             // buffer is the field's private mutable representation; clone the
             // array reference so setDataUnsafe stores a fresh value
             const buffer = [
                 ...data.buffer,
             ];
             step(buffer, data.capacity, dt, seeds, configOf(data, region), mode);
-            return { ...data, buffer };
+            Runner.particlesEscapeWrite(runner, instance, { ...data, buffer });
         });
         yield* Scene.tick;
     }

package/dist/particles/step.js

@@ -41,14 +41,15 @@ export const birth = (seed, config) => {
     [rng, colorPick] = Prng.nextBetween(rng, 0, config.palette.length);
     let opacity;
     [rng, opacity] = drawOpacity(rng, config);
-    // angle 0 = straight up; clockwise-positive
+    // angle 0 = straight up (+y); counterclockwise-positive (the scene
+    // rotation convention)
     const rad = angle * DEG;
     const color = config.palette[Math.min(config.palette.length - 1, Math.floor(colorPick))] ?? Color.white;
     return {
         x: config.x,
         y: config.y,
-        vx: Math.sin(rad) * speed,
-        vy: -Math.cos(rad) * speed,
+        vx: -Math.sin(rad) * speed,
+        vy: Math.cos(rad) * speed,
         age: 0,
         life,
         size,
@@ -89,9 +90,11 @@ export const birthFill = (seed, config) => {
     const rad = dir * DEG;
     const color = config.palette[Math.min(config.palette.length - 1, Math.floor(colorPick))] ?? Color.white;
     return {
-        // scattered across the region, offset by the field's own origin
-        x: config.x + px,
-        y: config.y + py,
+        // scattered across the region, CENTERED on the field's own origin
+        // (same [0, w) draw as before — only the interpretation shifts, so
+        // seeded streams are unchanged)
+        x: config.x + px - w / 2,
+        y: config.y + py - h / 2,
         vx: Math.cos(rad) * dspeed,
         vy: Math.sin(rad) * dspeed,
         age: 0,
@@ -123,16 +126,17 @@ export const step = (buffer, capacity, dt, seeds, config, mode = "emit") => {
         if (!p.alive) {
             continue;
         }
-        p.vy += config.gravity * dt;
+        // positive gravity pulls toward the bottom of the screen (-y)
+        p.vy -= config.gravity * dt;
         p.x += p.vx * dt;
         p.y += p.vy * dt;
         if (p.wrap) {
-            // wrap within the region, which sits at the field origin (config.x/y)
+            // wrap within the region, CENTERED on the field origin (config.x/y)
             if (rw > 0) {
-                p.x = config.x + mod(p.x - config.x, rw);
+                p.x = config.x + mod(p.x - config.x + rw / 2, rw) - rw / 2;
             }
             if (rh > 0) {
-                p.y = config.y + mod(p.y - config.y, rh);
+                p.y = config.y + mod(p.y - config.y + rh / 2, rh) - rh / 2;
             }
             continue;
         }

package/dist/types.d.ts

@@ -0,0 +1,5 @@
+export type IsLiteral<T> = string extends T ? false : true;
+export interface UnexpectedType<Message extends string> {
+    readonly message: Message;
+}
+export type EnsureLiteral<T, Message extends string> = IsLiteral<T> extends true ? T : UnexpectedType<Message> & string;

package/dist/types.js

@@ -0,0 +1 @@
+export {};