effect-motion 0.2.0

package/dist/particles/ParticleField.d.ts

@@ -0,0 +1,170 @@
+import * as Schema from "effect/Schema";
+import * as Entity from "../Entity";
+export declare const ParticleField: Entity.Entity<"particles/ParticleField", Schema.Struct<{
+    x: Schema.withConstructorDefault<Schema.Number>;
+    y: Schema.withConstructorDefault<Schema.Number>;
+    opacity: Schema.withConstructorDefault<Schema.Number>;
+    speed: Schema.withConstructorDefault<Schema.Tuple<readonly [Schema.Number, Schema.Number]>>;
+    angle: Schema.withConstructorDefault<Schema.Tuple<readonly [Schema.Number, Schema.Number]>>;
+    life: Schema.withConstructorDefault<Schema.Tuple<readonly [Schema.Number, Schema.Number]>>;
+    size: Schema.withConstructorDefault<Schema.Tuple<readonly [Schema.Number, Schema.Number]>>;
+    opacityRange: Schema.withConstructorDefault<Schema.Tuple<readonly [Schema.Number, Schema.Number]>>;
+    gravity: Schema.withConstructorDefault<Schema.Number>;
+    palette: Schema.withConstructorDefault<Schema.$Array<Schema.String>>;
+    region: Schema.optionalKey<Schema.Struct<{
+        readonly w: Schema.Number;
+        readonly h: Schema.Number;
+    }>>;
+    drift: Schema.optionalKey<Schema.Tuple<readonly [Schema.Number, Schema.Number]>>;
+    sizeOverLife: Schema.optionalKey<Schema.Struct<{
+        readonly from: Schema.Number;
+        readonly to: Schema.Number;
+        readonly ease: Schema.optionalKey<Schema.String>;
+    }>>;
+    opacityOverLife: Schema.optionalKey<Schema.Struct<{
+        readonly from: Schema.Number;
+        readonly to: Schema.Number;
+        readonly ease: Schema.optionalKey<Schema.String>;
+    }>>;
+    capacity: Schema.withConstructorDefault<Schema.Number>;
+    buffer: Schema.withConstructorDefault<Schema.$Array<Schema.Struct<{
+        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: Schema.String;
+        readonly rng: Schema.Number;
+        readonly alive: Schema.Boolean;
+        readonly wrap: Schema.Boolean;
+    }>>>;
+}>, {
+    readonly "~position": Entity.TraitLens<{
+        readonly x: number;
+        readonly y: number;
+        readonly opacity: number;
+        readonly speed: readonly [number, number];
+        readonly angle: readonly [number, number];
+        readonly life: readonly [number, number];
+        readonly size: readonly [number, number];
+        readonly opacityRange: readonly [number, number];
+        readonly gravity: number;
+        readonly palette: readonly string[];
+        readonly region?: Schema.Struct.ReadonlySide<{
+            readonly w: Schema.Number;
+            readonly h: Schema.Number;
+        }, "Type">;
+        readonly drift?: readonly [number, number];
+        readonly sizeOverLife?: {
+            readonly from: number;
+            readonly to: number;
+            readonly ease?: string;
+        };
+        readonly opacityOverLife?: {
+            readonly from: number;
+            readonly to: number;
+            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: Schema.String;
+            readonly rng: Schema.Number;
+            readonly alive: Schema.Boolean;
+            readonly wrap: Schema.Boolean;
+        }, "Type">[];
+    }, Entity.Position>;
+    readonly "~opacity": Entity.TraitLens<{
+        readonly x: number;
+        readonly y: number;
+        readonly opacity: number;
+        readonly speed: readonly [number, number];
+        readonly angle: readonly [number, number];
+        readonly life: readonly [number, number];
+        readonly size: readonly [number, number];
+        readonly opacityRange: readonly [number, number];
+        readonly gravity: number;
+        readonly palette: readonly string[];
+        readonly region?: Schema.Struct.ReadonlySide<{
+            readonly w: Schema.Number;
+            readonly h: Schema.Number;
+        }, "Type">;
+        readonly drift?: readonly [number, number];
+        readonly sizeOverLife?: {
+            readonly from: number;
+            readonly to: number;
+            readonly ease?: string;
+        };
+        readonly opacityOverLife?: {
+            readonly from: number;
+            readonly to: number;
+            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: Schema.String;
+            readonly rng: Schema.Number;
+            readonly alive: Schema.Boolean;
+            readonly wrap: Schema.Boolean;
+        }, "Type">[];
+    }, number>;
+}, {
+    readonly x?: number;
+    readonly y?: number;
+    readonly opacity?: number;
+    readonly speed?: readonly [number, number];
+    readonly angle?: readonly [number, number];
+    readonly life?: readonly [number, number];
+    readonly size?: readonly [number, number];
+    readonly opacityRange?: readonly [number, number];
+    readonly gravity?: number;
+    readonly palette?: readonly string[];
+    readonly region?: Schema.Struct.ReadonlyMakeIn<{
+        readonly w: Schema.Number;
+        readonly h: Schema.Number;
+    }>;
+    readonly drift?: readonly [number, number];
+    readonly sizeOverLife?: {
+        readonly from: number;
+        readonly to: number;
+        readonly ease?: string;
+    };
+    readonly opacityOverLife?: {
+        readonly from: number;
+        readonly to: number;
+        readonly ease?: string;
+    };
+    readonly capacity?: number;
+    readonly buffer?: readonly Schema.Struct.ReadonlyMakeIn<{
+        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: Schema.String;
+        readonly rng: Schema.Number;
+        readonly alive: Schema.Boolean;
+        readonly wrap: Schema.Boolean;
+    }>[];
+}>;

package/dist/particles/ParticleField.js

@@ -0,0 +1,69 @@
+import * as Effect from "effect/Effect";
+import * as Schema from "effect/Schema";
+import * as Entity from "../Entity";
+import * as Shape2D from "../shapes/Shape2D";
+/**
+ * A ParticleField is ONE entity/instance backing many particles. Its data
+ * holds the emitter config plus a fixed-capacity buffer of live particle
+ * state; the `simulate` animator advances it one frame at a time, so N
+ * particles cost one fiber and one phaser party — O(1) on the barrier.
+ *
+ * The buffer lives in the entity data (so the Runner owns it like any
+ * instance state and it round-trips through the seeded, deterministic
+ * scene). Its representation is the field's private business — see
+ * particles/step.ts.
+ */
+const Range = Schema.Tuple([Schema.Number, Schema.Number]);
+// a Range with a constructor default, so a mode that doesn't use this prop
+// can omit it and still construct valid field data
+const defaultedRange = (value) => Range.pipe(Schema.withConstructorDefault(Effect.sync(() => [value[0], value[1]])));
+const OverLifeSchema = Schema.Struct({
+    from: Schema.Number,
+    to: Schema.Number,
+    ease: Schema.optionalKey(Schema.String),
+});
+const ParticleSchema = Schema.Struct({
+    x: Schema.Number,
+    y: Schema.Number,
+    vx: Schema.Number,
+    vy: Schema.Number,
+    age: Schema.Number,
+    life: Schema.Number,
+    size: Schema.Number,
+    opacity: Schema.Number,
+    color: Schema.String,
+    rng: Schema.Number,
+    alive: Schema.Boolean,
+    wrap: Schema.Boolean,
+});
+export const ParticleField = Entity.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,
+    // 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.
+    speed: defaultedRange([0, 0]),
+    angle: defaultedRange([0, 0]),
+    life: defaultedRange([1, 1]),
+    size: defaultedRange([2, 2]),
+    // per-particle birth opacity range (0..1), drawn at birth; the over-life
+    // 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),
+    palette: Schema.Array(Schema.String).pipe(Schema.withConstructorDefault(Effect.sync(() => ["white"]))),
+    // fill mode: the region particles spread across and wrap within
+    // (defaults to the frame in `simulate`) and their drift speed range
+    region: Schema.optionalKey(Schema.Struct({ w: Schema.Number, h: Schema.Number })),
+    drift: Schema.optionalKey(Range),
+    sizeOverLife: Schema.optionalKey(OverLifeSchema),
+    opacityOverLife: Schema.optionalKey(OverLifeSchema),
+    // lifecycle state
+    capacity: Shape2D.defaultedNumber(1024),
+    buffer: Schema.Array(ParticleSchema).pipe(Schema.withConstructorDefault(Effect.sync(() => []))),
+}, {
+    "~position": Shape2D.positionLens(),
+    "~opacity": Shape2D.opacityLens(),
+});

package/dist/particles/Prng.d.ts

@@ -0,0 +1,28 @@
+/**
+ * A plain, seedable pseudo-random generator carried BY each particle.
+ *
+ * Why not the scene's `Random` service? That service is fiber-scoped —
+ * reading it needs an Effect and a running fiber. A particle is data in a
+ * buffer, not a fiber; it can't `yield*`. So each particle carries its own
+ * generator state (a single uint32) advanced by pure arithmetic. The
+ * generator's SEED is drawn once from the scene's seeded `Random` at birth
+ * (see Particle.emit), so the whole thing stays deterministic under the
+ * scene seed while every particle's stream is independent: consuming one
+ * particle's randomness cannot shift another's.
+ *
+ * The algorithm is mulberry32 — a well-known 32-bit generator: one
+ * multiply-xor-shift chain per draw, good enough for visual scatter and
+ * byte-identical across platforms (all math forced through `| 0` / `>>> 0`
+ * so it stays in 32-bit integer space).
+ *
+ * State is a bare number so it packs into a particle buffer with no object
+ * overhead; `next` returns the new state alongside the drawn value rather
+ * than mutating, keeping the per-frame step a pure fold.
+ */
+export type PrngState = number;
+/** derive a well-mixed uint32 seed from an arbitrary number in [0, 1) or any float */
+export declare const seedFrom: (value: number) => PrngState;
+/** advance the state; returns the next state and a float in [0, 1) */
+export declare const next: (state: PrngState) => readonly [PrngState, number];
+/** advance the state; returns the next state and a float in [min, max) */
+export declare const nextBetween: (state: PrngState, min: number, max: number) => readonly [PrngState, number];

package/dist/particles/Prng.js

@@ -0,0 +1,43 @@
+/**
+ * A plain, seedable pseudo-random generator carried BY each particle.
+ *
+ * Why not the scene's `Random` service? That service is fiber-scoped —
+ * reading it needs an Effect and a running fiber. A particle is data in a
+ * buffer, not a fiber; it can't `yield*`. So each particle carries its own
+ * generator state (a single uint32) advanced by pure arithmetic. The
+ * generator's SEED is drawn once from the scene's seeded `Random` at birth
+ * (see Particle.emit), so the whole thing stays deterministic under the
+ * scene seed while every particle's stream is independent: consuming one
+ * particle's randomness cannot shift another's.
+ *
+ * The algorithm is mulberry32 — a well-known 32-bit generator: one
+ * multiply-xor-shift chain per draw, good enough for visual scatter and
+ * byte-identical across platforms (all math forced through `| 0` / `>>> 0`
+ * so it stays in 32-bit integer space).
+ *
+ * State is a bare number so it packs into a particle buffer with no object
+ * overhead; `next` returns the new state alongside the drawn value rather
+ * than mutating, keeping the per-frame step a pure fold.
+ */
+/** derive a well-mixed uint32 seed from an arbitrary number in [0, 1) or any float */
+export const seedFrom = (value) => {
+    // spread the input across the 32-bit range, then mix once so nearby
+    // seeds (e.g. 0.0001 apart) don't produce correlated first draws
+    let s = (Math.floor(value * 0x100000000) ^ 0x9e3779b9) >>> 0;
+    s = Math.imul(s ^ (s >>> 16), 0x45d9f3b) >>> 0;
+    return s >>> 0;
+};
+/** advance the state; returns the next state and a float in [0, 1) */
+export const next = (state) => {
+    let t = (state + 0x6d2b79f5) | 0;
+    const nextState = t >>> 0;
+    t = Math.imul(t ^ (t >>> 15), 1 | t);
+    t = (t + Math.imul(t ^ (t >>> 7), 61 | t)) ^ t;
+    const value = ((t ^ (t >>> 14)) >>> 0) / 0x100000000;
+    return [nextState, value];
+};
+/** advance the state; returns the next state and a float in [min, max) */
+export const nextBetween = (state, min, max) => {
+    const [nextState, value] = next(state);
+    return [nextState, min + value * (max - min)];
+};

package/dist/particles/constructors.d.ts

@@ -0,0 +1,78 @@
+import type * as Effect from "effect/Effect";
+import type * as Instance from "../Instance";
+import type * as Runner from "../Runner";
+import type { Range } from "./Particle";
+import { ParticleField } from "./ParticleField";
+/**
+ * Two typed front doors onto the SAME `ParticleField` entity. The field's
+ * emission model is chosen at `simulate`, but the properties that make sense
+ * differ by model — a fountain has speed/angle/life, a floating field has
+ * drift/region. These constructors gate which props an author may set and
+ * brand the returned instance so `simulate` only accepts the matching
+ * emission (see simulate.ts). The brand is compile-time only; both build an
+ * ordinary ParticleField instance with identical runtime data.
+ */
+declare const EmitterBrand: unique symbol;
+declare const FloatBrand: unique symbol;
+type BaseField = Instance.Of<typeof ParticleField>;
+/** an emitter (source) field — simulate with `{ burst }` or `{ rate }` */
+export type EmitterField = BaseField & {
+    readonly [EmitterBrand]: true;
+};
+/** a floating field — simulate with `{ fill }` */
+export type FloatField = BaseField & {
+    readonly [FloatBrand]: true;
+};
+/** an over-life curve `{ from, to, ease? }` (see Particle.OverLife) */
+interface OverLifeInput {
+    readonly from: number;
+    readonly to: number;
+    readonly ease?: string;
+}
+/** props shared by both field kinds */
+interface CommonInput {
+    readonly x?: number;
+    readonly y?: number;
+    /** birth size range (px radius) */
+    readonly size?: Range;
+    /** per-particle birth opacity range (0..1); over-life curve multiplies it */
+    readonly opacityRange?: Range;
+    /** colors drawn from uniformly at birth */
+    readonly palette?: ReadonlyArray<string>;
+    /** shared downward acceleration (px/sec²) */
+    readonly gravity?: number;
+    readonly sizeOverLife?: OverLifeInput;
+    readonly opacityOverLife?: OverLifeInput;
+    /** fixed particle capacity */
+    readonly capacity?: number;
+}
+/** props unique to a source emitter (launched particles with a lifetime) */
+export interface EmitterInput extends CommonInput {
+    /** launch speed range (px/sec) */
+    readonly speed: Range;
+    /** launch angle range (degrees; 0 = up, clockwise-positive) */
+    readonly angle: Range;
+    /** lifetime range (seconds) */
+    readonly life: Range;
+}
+/** props unique to a floating field (scattered, drifting, wrapping) */
+export interface FieldInput extends CommonInput {
+    /** drift speed range (px/sec); direction is uniform-random */
+    readonly drift: Range;
+    /** spread/wrap region in local coords; defaults to the whole frame */
+    readonly region?: {
+        readonly w: number;
+        readonly h: number;
+    };
+}
+/**
+ * Create a source emitter field. Simulate it with `{ burst: n }` (all at
+ * once) or `{ rate: n }` (a continuous stream).
+ */
+export declare const emitter: (props: EmitterInput) => Effect.Effect<EmitterField, unknown, typeof ParticleField | Runner.Runner>;
+/**
+ * Create a floating field: particles spread evenly across the region,
+ * drifting and wrapping at the edges. Simulate it with `{ fill: n }`.
+ */
+export declare const field: (props: FieldInput) => Effect.Effect<FloatField, unknown, typeof ParticleField | Runner.Runner>;
+export {};

package/dist/particles/constructors.js

@@ -0,0 +1,15 @@
+import * as Scene from "../Scene";
+import { ParticleField } from "./ParticleField";
+/**
+ * Create a source emitter field. Simulate it with `{ burst: n }` (all at
+ * once) or `{ rate: n }` (a continuous stream).
+ */
+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);
+/**
+ * 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);

package/dist/particles/index.d.ts

@@ -0,0 +1,6 @@
+export * from "./constructors";
+export * from "./Particle";
+export * from "./ParticleField";
+export * as Prng from "./Prng";
+export { particleField as render } from "./render";
+export * from "./simulate";

package/dist/particles/index.js

@@ -0,0 +1,6 @@
+export * from "./constructors";
+export * from "./Particle";
+export * from "./ParticleField";
+export * as Prng from "./Prng";
+export { particleField as render } from "./render";
+export * from "./simulate";

package/dist/particles/overLife.d.ts

@@ -0,0 +1,16 @@
+import type { OverLife, Particle } from "./Particle";
+/**
+ * Evaluate an over-life curve at a particle's current age. Purely a
+ * function of `age/life` (clamped to [0,1]) eased by the configured timing
+ * function — no randomness after birth, so two particles at the same age
+ * always agree.
+ */
+export declare const evalOverLife: (curve: OverLife, particle: Particle) => number;
+/** rendered radius: drawn size, optionally scaled by the size-over-life curve */
+export declare const renderSize: (particle: Particle, curve: OverLife | undefined) => number;
+/**
+ * Rendered opacity: the particle's baseline opacity (drawn at birth),
+ * multiplied by the opacity-over-life curve when one is set. So a field can
+ * randomize per-particle opacity, fade over life, or both.
+ */
+export declare const renderOpacity: (particle: Particle, curve: OverLife | undefined) => number;

package/dist/particles/overLife.js

@@ -0,0 +1,21 @@
+import * as Timing from "../Timing";
+/**
+ * Evaluate an over-life curve at a particle's current age. Purely a
+ * function of `age/life` (clamped to [0,1]) eased by the configured timing
+ * function — no randomness after birth, so two particles at the same age
+ * always agree.
+ */
+export const evalOverLife = (curve, particle) => {
+    const t = particle.life > 0 ? Math.min(1, particle.age / particle.life) : 1;
+    // ease is stored as a plain string (schema data); resolve validates it
+    const eased = Timing.resolve((curve.ease ?? "linear"))(t);
+    return curve.from + (curve.to - curve.from) * eased;
+};
+/** rendered radius: drawn size, optionally scaled by the size-over-life curve */
+export const renderSize = (particle, curve) => curve ? particle.size * evalOverLife(curve, particle) : particle.size;
+/**
+ * Rendered opacity: the particle's baseline opacity (drawn at birth),
+ * multiplied by the opacity-over-life curve when one is set. So a field can
+ * randomize per-particle opacity, fade over life, or both.
+ */
+export const renderOpacity = (particle, curve) => curve ? particle.opacity * evalOverLife(curve, particle) : particle.opacity;

package/dist/particles/render.d.ts

@@ -0,0 +1,13 @@
+import type * as Renderer from "../Renderer";
+import type { SvgNode } from "../svg/SvgNode";
+import type { ParticleField } from "./ParticleField";
+/**
+ * Render a ParticleField: one <g> whose children are one <circle> per LIVE
+ * particle, each sized/faded by the over-life curves. Dead slots emit
+ * nothing. This is where the O(1)-simulation buffer expands back into N
+ * SVG nodes.
+ * ponytail: N SVG nodes is the RENDERING ceiling (the DOM/string cost), not
+ * the simulation ceiling. A batched/instanced sink is the upgrade path if
+ * node count becomes the wall.
+ */
+export declare const particleField: Renderer.RenderFunction<SvgNode, typeof ParticleField>;

package/dist/particles/render.js

@@ -0,0 +1,33 @@
+import * as Effect from "effect/Effect";
+import { renderOpacity, renderSize } from "./overLife";
+/**
+ * Render a ParticleField: one <g> whose children are one <circle> per LIVE
+ * particle, each sized/faded by the over-life curves. Dead slots emit
+ * nothing. This is where the O(1)-simulation buffer expands back into N
+ * SVG nodes.
+ * ponytail: N SVG nodes is the RENDERING ceiling (the DOM/string cost), not
+ * the simulation ceiling. A batched/instanced sink is the upgrade path if
+ * node count becomes the wall.
+ */
+export const particleField = ({ data }) => Effect.succeed({
+    tag: "g",
+    props: data.x !== 0 || data.y !== 0
+        ? { transform: `translate(${data.x} ${data.y})` }
+        : {},
+    children: data.buffer
+        .filter((p) => p.alive)
+        .map((p) => {
+        const r = renderSize(p, data.sizeOverLife);
+        const opacity = renderOpacity(p, data.opacityOverLife);
+        return {
+            tag: "circle",
+            props: {
+                cx: p.x,
+                cy: p.y,
+                r,
+                fill: p.color,
+                ...(opacity !== 1 ? { opacity } : {}),
+            },
+        };
+    }),
+});

package/dist/particles/simulate.d.ts

@@ -0,0 +1,39 @@
+import type * as Duration from "effect/Duration";
+import * as Effect from "effect/Effect";
+import * as Runner from "../Runner";
+import type { EmitterField, FloatField } from "./constructors";
+/**
+ * Emission model for a single `simulate` call:
+ * - `{ burst: n }` — birth `n` particles on the FIRST frame, then none
+ * - `{ rate: n }`  — birth `n` particles per second, continuously
+ * - `{ fill: n }`  — seed `n` particles EVENLY across the region on the
+ *   first frame; they drift and wrap at the edges forever (no source, no
+ *   lifecycle). This is the "floating field" model.
+ */
+export type EmitterEmission = {
+    readonly burst: number;
+} | {
+    readonly rate: number;
+};
+export type FillEmission = {
+    readonly fill: number;
+};
+export type Emission = EmitterEmission | FillEmission;
+/**
+ * Advance a `ParticleField` for `duration`, running its per-frame step
+ * (emit, integrate, kill) once per frame and arriving at the phaser once
+ * per frame — O(1) on the barrier regardless of live particle count.
+ *
+ * Dual: `simulate(field, duration, emission)` or
+ * `field.pipe(simulate(duration, emission))`. The emission is constrained by
+ * how the field was created: a `Particles.emitter(...)` takes `{ burst }` or
+ * `{ rate }`, a `Particles.field(...)` takes `{ fill }`. Resolves with the
+ * field so calls chain.
+ */
+export interface Simulate {
+    (field: EmitterField, duration: Duration.Input, emission: EmitterEmission): Effect.Effect<EmitterField, never, Runner.Runner>;
+    (field: FloatField, duration: Duration.Input, emission: FillEmission): Effect.Effect<FloatField, never, Runner.Runner>;
+    (duration: Duration.Input, emission: EmitterEmission): (field: EmitterField) => Effect.Effect<EmitterField, never, Runner.Runner>;
+    (duration: Duration.Input, emission: FillEmission): (field: FloatField) => Effect.Effect<FloatField, never, Runner.Runner>;
+}
+export declare const simulate: Simulate;

package/dist/particles/simulate.js

@@ -0,0 +1,81 @@
+import * as Effect from "effect/Effect";
+import { dual } from "effect/Function";
+import * as Random from "effect/Random";
+import * as Instance from "../Instance";
+import * as Runner from "../Runner";
+import * as Scene from "../Scene";
+import * as Time from "../Time";
+import * as Prng from "./Prng";
+import { step } from "./step";
+// how many particles to birth on frame `i` (1-based) of this call
+const birthsForFrame = (emission, i, fps) => {
+    if ("burst" in emission) {
+        return i === 1 ? emission.burst : 0;
+    }
+    if ("fill" in emission) {
+        // fill seeds the whole field once, up front, like a burst
+        return i === 1 ? emission.fill : 0;
+    }
+    // stream: rate/sec → per-frame, accumulating fractional remainder so the
+    // long-run average matches `rate` exactly (deterministic, no drift)
+    const perFrame = emission.rate / fps;
+    const before = Math.floor(perFrame * (i - 1));
+    const now = Math.floor(perFrame * i);
+    return now - before;
+};
+// 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
+// the whole subtree at render time.
+const configOf = (data, region) => ({
+    x: 0, // emitter origin is the field's own transform; particles are local
+    y: 0,
+    speed: data.speed,
+    angle: data.angle,
+    life: data.life,
+    size: data.size,
+    gravity: data.gravity,
+    palette: data.palette,
+    region,
+    ...(data.opacityRange ? { opacity: data.opacityRange } : {}),
+    ...(data.drift ? { drift: data.drift } : {}),
+    ...(data.sizeOverLife ? { sizeOverLife: data.sizeOverLife } : {}),
+    ...(data.opacityOverLife ? { opacityOverLife: data.opacityOverLife } : {}),
+});
+const run = Effect.fnUntraced(function* (instance, duration, emission) {
+    const runner = yield* Runner.Runner;
+    const fps = runner.settings.frameRate;
+    const frames = Math.max(1, Time.toFrames(duration, fps));
+    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);
+    const region = {
+        w: current.region?.w ?? runner.settings.width,
+        h: current.region?.h ?? runner.settings.height,
+    };
+    for (let i = 1; i <= frames; i++) {
+        const n = birthsForFrame(emission, i, fps);
+        // draw one seed per birth from the scene's seeded Random — the ONLY
+        // entropy; each seeds a particle's own independent PRNG
+        const seeds = [];
+        for (let s = 0; s < n; s++) {
+            seeds.push(Prng.seedFrom(yield* Random.next));
+        }
+        yield* Scene.update(instance, (data) => {
+            // 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 };
+        });
+        yield* Scene.tick;
+    }
+    return instance;
+});
+const firstArgIsInstance = (args) => Instance.isInstance(args[0]);
+// the untyped runtime dual; the public `simulate` below narrows it per brand
+const simulateImpl = dual(firstArgIsInstance, (instance, duration, emission) => run(instance, duration, emission));
+export const simulate = simulateImpl;

package/dist/particles/step.d.ts

@@ -0,0 +1,24 @@
+import type { EmitterConfig, Particle } from "./Particle";
+import * as Prng from "./Prng";
+/** birth one particle from a seed + config (fixed draw order). */
+export declare const birth: (seed: Prng.PrngState, config: EmitterConfig) => Particle;
+/**
+ * Birth a `fill`-mode particle: scattered at a random point in the region
+ * (not at the origin), given a small isotropic drift velocity (not a
+ * launch), and marked to wrap forever instead of aging out. This is what
+ * makes an evenly-spread floating field rather than a fountain. Same fixed
+ * draw order — position x, position y, drift direction, drift speed, size,
+ * color — so seeded output is stable.
+ */
+export declare const birthFill: (seed: Prng.PrngState, config: EmitterConfig) => Particle;
+/**
+ * Advance the buffer one frame. `dt` is seconds per frame. `seeds` are the
+ * per-particle seeds to birth this frame (already drawn upstream). The
+ * buffer is mutated in place and returned — it is the field's private
+ * representation, owned by one instance, so in-place is safe and flat.
+ * ponytail: array-of-structs, mutated in place. SoA + typed arrays is the
+ * upgrade path if a capacity-target benchmark shows this is the wall.
+ */
+export declare const step: (buffer: Particle[], capacity: number, dt: number, seeds: ReadonlyArray<Prng.PrngState>, config: EmitterConfig, mode?: "emit" | "fill") => Particle[];
+/** count of currently-live particles */
+export declare const liveCount: (buffer: ReadonlyArray<Particle>) => number;