@basmilius/sparkle 2.1.0 → 2.2.0

package/dist/index.d.mts

@@ -6,57 +6,77 @@ type EdgeFade = {
   readonly left?: EdgeFadeSide;
   readonly right?: EdgeFadeSide;
 };
-declare abstract class SimulationLayer {
+/**
+* Internal interface implemented by all Effect subclasses. Used by SimulationCanvas
+* and Scene to drive rendering without depending on the generic Effect<TConfig> type.
+*/
+interface SimulationLayer {
+  fade: EdgeFade | null;
+  tick(dt: number, width: number, height: number): void;
+  draw(ctx: CanvasRenderingContext2D, width: number, height: number): void;
+  onResize(width: number, height: number): void;
+  onMount(canvas: HTMLCanvasElement): void;
+  onUnmount(canvas: HTMLCanvasElement): void;
+}
+//#endregion
+//#region src/effect.d.ts
+/**
+* Base class for all visual effects. Implements the internal SimulationLayer interface
+* so that effects can be used both standalone (via mount()) and composed in a Scene.
+*
+* @example Standalone usage
+* const snow = new Snow({ particles: 200 });
+* snow.mount(canvas).start();
+*
+* @example Scene composition
+* const scene = new Scene()
+*     .mount(canvas)
+*     .layer(new Aurora())
+*     .layer(new Snow())
+*     .start();
+*/
+declare abstract class Effect<TConfig = Record<string, unknown>> implements SimulationLayer {
+  #private;
   fade: EdgeFade | null;
   abstract tick(dt: number, width: number, height: number): void;
   abstract draw(ctx: CanvasRenderingContext2D, width: number, height: number): void;
+  configure(_config: Partial<TConfig>): void;
   onResize(_width: number, _height: number): void;
   onMount(_canvas: HTMLCanvasElement): void;
   onUnmount(_canvas: HTMLCanvasElement): void;
+  /**
+  * Apply an edge fade mask when rendering this effect standalone or in a Scene.
+  */
   withFade(fade: EdgeFade): this;
-}
-//#endregion
-//#region src/canvas.d.ts
-declare class LimitedFrameRateCanvas {
-  #private;
-  static get globalSpeed(): number;
-  static set globalSpeed(value: number);
-  get canvas(): HTMLCanvasElement;
-  get context(): CanvasRenderingContext2D;
-  get delta(): number;
-  get deltaFactor(): number;
-  get speed(): number;
-  set speed(value: number);
-  get frameRate(): number;
-  get isSmall(): boolean;
-  get isTicking(): boolean;
-  get ticks(): number;
-  get height(): number;
-  get width(): number;
-  constructor(canvas: HTMLCanvasElement, frameRate: number, options?: CanvasRenderingContext2DSettings);
-  loop(): void;
-  start(): void;
-  stop(): void;
-  draw(): void;
-  tick(): void;
+  /**
+  * Mount this effect to a canvas element or CSS selector, creating the render loop.
+  * Must be called before start().
+  */
+  mount(canvas: HTMLCanvasElement | string, options?: CanvasRenderingContext2DSettings): this;
+  /**
+  * Remove this effect from its canvas and clean up the render loop.
+  */
+  unmount(): this;
+  /**
+  * Start the render loop. Call mount() first.
+  */
+  start(): this;
+  /**
+  * Pause rendering without destroying state. Use resume() to continue.
+  */
+  pause(): this;
+  /**
+  * Resume rendering after a pause().
+  */
+  resume(): this;
+  /**
+  * Stop rendering and call onUnmount(). Safe to call multiple times.
+  */
   destroy(): void;
-  onResize(): void;
-  onVisibilityChange(): void;
 }
 //#endregion
-//#region src/simulation-canvas.d.ts
-declare class SimulationCanvas extends LimitedFrameRateCanvas {
-  #private;
-  constructor(canvas: HTMLCanvasElement, simulation: SimulationLayer, frameRate?: number, options?: CanvasRenderingContext2DSettings);
-  start(): void;
-  destroy(): void;
-  draw(): void;
-  tick(): void;
-  onResize(): void;
-}
-//#endregion
-//#region src/aurora/simulation.d.ts
-interface AuroraSimulationConfig {
+//#region src/aurora/layer.d.ts
+interface AuroraConfig {
   readonly bands?: number;
   readonly colors?: string[];
   readonly speed?: number;
@@ -64,18 +84,6 @@ interface AuroraSimulationConfig {
   readonly waveAmplitude?: number;
   readonly verticalPosition?: number;
   readonly scale?: number;
-  readonly canvasOptions?: CanvasRenderingContext2DSettings;
-}
-declare class AuroraSimulation extends SimulationCanvas {
-  constructor(canvas: HTMLCanvasElement, config?: AuroraSimulationConfig);
-}
-//#endregion
-//#region src/aurora/layer.d.ts
-declare class AuroraLayer extends SimulationLayer {
-  #private;
-  constructor(config?: AuroraSimulationConfig);
-  tick(dt: number, width: number, height: number): void;
-  draw(ctx: CanvasRenderingContext2D, width: number, height: number): void;
 }
 //#endregion
 //#region src/aurora/types.d.ts
@@ -93,16 +101,11 @@ type AuroraBand = {
   opacity: number;
 };
 //#endregion
-//#region src/color.d.ts
-declare function parseColor(fillStyle: string): {
-  r: number;
-  g: number;
-  b: number;
-  a: number;
-};
+//#region src/aurora/index.d.ts
+declare function createAurora(config?: AuroraConfig): Effect<AuroraConfig>;
 //#endregion
-//#region src/balloons/simulation.d.ts
-interface BalloonSimulationConfig {
+//#region src/balloons/layer.d.ts
+interface BalloonsConfig {
   readonly count?: number;
   readonly colors?: string[];
   readonly sizeRange?: [number, number];
@@ -110,18 +113,6 @@ interface BalloonSimulationConfig {
   readonly driftAmount?: number;
   readonly stringLength?: number;
   readonly scale?: number;
-  readonly canvasOptions?: CanvasRenderingContext2DSettings;
-}
-declare class BalloonSimulation extends SimulationCanvas {
-  constructor(canvas: HTMLCanvasElement, config?: BalloonSimulationConfig);
-}
-//#endregion
-//#region src/balloons/layer.d.ts
-declare class BalloonLayer extends SimulationLayer {
-  #private;
-  constructor(config?: BalloonSimulationConfig);
-  tick(dt: number, width: number, height: number): void;
-  draw(ctx: CanvasRenderingContext2D, width: number, height: number): void;
 }
 //#endregion
 //#region src/point.d.ts
@@ -167,8 +158,11 @@ type Balloon = {
   stringLength: number;
 };
 //#endregion
-//#region src/bubbles/simulation.d.ts
-interface BubbleSimulationConfig {
+//#region src/balloons/index.d.ts
+declare function createBalloons(config?: BalloonsConfig): Effect<BalloonsConfig>;
+//#endregion
+//#region src/bubbles/layer.d.ts
+interface BubblesConfig {
   readonly count?: number;
   readonly sizeRange?: [number, number];
   readonly speed?: number;
@@ -177,20 +171,6 @@ interface BubbleSimulationConfig {
   readonly colors?: string[];
   readonly wobbleAmount?: number;
   readonly scale?: number;
-  readonly canvasOptions?: CanvasRenderingContext2DSettings;
-}
-declare class BubbleSimulation extends SimulationCanvas {
-  constructor(canvas: HTMLCanvasElement, config?: BubbleSimulationConfig);
-}
-//#endregion
-//#region src/bubbles/layer.d.ts
-declare class BubbleLayer extends SimulationLayer {
-  #private;
-  constructor(config?: BubbleSimulationConfig);
-  onMount(canvas: HTMLCanvasElement): void;
-  onUnmount(canvas: HTMLCanvasElement): void;
-  tick(dt: number, width: number, height: number): void;
-  draw(ctx: CanvasRenderingContext2D, width: number, height: number): void;
 }
 //#endregion
 //#region src/bubbles/types.d.ts
@@ -215,6 +195,47 @@ type PopParticle = {
   decay: number;
 };
 //#endregion
+//#region src/bubbles/index.d.ts
+declare function createBubbles(config?: BubblesConfig): Effect<BubblesConfig>;
+//#endregion
+//#region src/canvas.d.ts
+declare class LimitedFrameRateCanvas {
+  #private;
+  static get globalSpeed(): number;
+  static set globalSpeed(value: number);
+  get canvas(): HTMLCanvasElement;
+  get context(): CanvasRenderingContext2D;
+  get delta(): number;
+  get deltaFactor(): number;
+  get speed(): number;
+  set speed(value: number);
+  get frameRate(): number;
+  get isSmall(): boolean;
+  get isTicking(): boolean;
+  get ticks(): number;
+  get height(): number;
+  get width(): number;
+  constructor(canvas: HTMLCanvasElement, frameRate: number, options?: CanvasRenderingContext2DSettings);
+  loop(): void;
+  start(): void;
+  stop(): void;
+  pause(): void;
+  resume(): void;
+  draw(): void;
+  tick(): void;
+  destroy(): void;
+  onResize(): void;
+  onVisibilityChange(): void;
+}
+//#endregion
+//#region src/color.d.ts
+declare function parseColor(fillStyle: string): {
+  r: number;
+  g: number;
+  b: number;
+  a: number;
+};
+//#endregion
 //#region src/confetti/types.d.ts
 type Config = {
   readonly angle: number;
@@ -233,26 +254,9 @@ type Config = {
 type Palette = "classic" | "pastel" | "vibrant" | "warm";
 type Shape = "bowtie" | "circle" | "crescent" | "diamond" | "heart" | "hexagon" | "ribbon" | "ring" | "square" | "star" | "triangle";
 //#endregion
-//#region src/confetti/simulation.d.ts
-interface ConfettiSimulationConfig {
-  readonly scale?: number;
-  readonly canvasOptions?: CanvasRenderingContext2DSettings;
-}
-declare class ConfettiSimulation extends SimulationCanvas {
-  #private;
-  constructor(canvas: HTMLCanvasElement, config?: ConfettiSimulationConfig);
-  fire(config: Partial<Config>): void;
-}
-//#endregion
 //#region src/confetti/layer.d.ts
-declare class ConfettiLayer extends SimulationLayer {
-  #private;
-  constructor(config?: ConfettiSimulationConfig);
-  onResize(width: number, height: number): void;
-  fire(config: Partial<Config>): void;
-  get hasParticles(): boolean;
-  tick(dt: number, _width: number, _height: number): void;
-  draw(ctx: CanvasRenderingContext2D, width: number, height: number): void;
+interface ConfettiConfig {
+  readonly scale?: number;
 }
 //#endregion
 //#region src/confetti/particle.d.ts
@@ -279,10 +283,15 @@ declare const PALETTES: Record<Palette, string[]>;
 //#region src/confetti/shapes.d.ts
 declare const SHAPE_PATHS: Record<Shape, Path2D>;
 //#endregion
-//#region src/donuts/simulation.d.ts
-interface DonutSimulationConfig {
+//#region src/confetti/index.d.ts
+interface ConfettiInstance extends Effect<ConfettiConfig> {
+  burst(config: Partial<Config>): void;
+}
+declare function createConfetti(config?: ConfettiConfig): ConfettiInstance;
+//#endregion
+//#region src/donuts/layer.d.ts
+interface DonutsConfig {
   readonly background?: string;
-  readonly canvasOptions?: CanvasRenderingContext2DSettings;
   readonly collisionPadding?: number;
   readonly colors?: string[];
   readonly count?: number;
@@ -296,41 +305,18 @@ interface DonutSimulationConfig {
   readonly speedRange?: [number, number];
   readonly thickness?: number;
 }
-declare class DonutSimulation extends SimulationCanvas {
-  constructor(canvas: HTMLCanvasElement, config?: DonutSimulationConfig);
-}
 //#endregion
-//#region src/donuts/layer.d.ts
-declare class DonutLayer extends SimulationLayer {
-  #private;
-  constructor(config?: DonutSimulationConfig);
-  onResize(width: number, height: number): void;
-  onMount(canvas: HTMLCanvasElement): void;
-  onUnmount(canvas: HTMLCanvasElement): void;
-  tick(dt: number, width: number, height: number): void;
-  draw(ctx: CanvasRenderingContext2D, width: number, height: number): void;
-}
+//#region src/donuts/index.d.ts
+declare function createDonuts(config?: DonutsConfig): Effect<DonutsConfig>;
 //#endregion
-//#region src/fireflies/simulation.d.ts
-interface FireflySimulationConfig {
+//#region src/fireflies/layer.d.ts
+interface FirefliesConfig {
   readonly count?: number;
   readonly color?: string;
   readonly size?: number;
   readonly speed?: number;
   readonly glowSpeed?: number;
   readonly scale?: number;
-  readonly canvasOptions?: CanvasRenderingContext2DSettings;
-}
-declare class FireflySimulation extends SimulationCanvas {
-  constructor(canvas: HTMLCanvasElement, config?: FireflySimulationConfig);
-}
-//#endregion
-//#region src/fireflies/layer.d.ts
-declare class FireflyLayer extends SimulationLayer {
-  #private;
-  constructor(config?: FireflySimulationConfig);
-  tick(dt: number, _width: number, _height: number): void;
-  draw(ctx: CanvasRenderingContext2D, width: number, height: number): void;
 }
 //#endregion
 //#region src/fireflies/particle.d.ts
@@ -374,25 +360,16 @@ type Firefly = {
   amplitudeY: number;
 };
 //#endregion
-//#region src/firepit/simulation.d.ts
-interface FirepitSimulationConfig {
+//#region src/fireflies/index.d.ts
+declare function createFireflies(config?: FirefliesConfig): Effect<FirefliesConfig>;
+//#endregion
+//#region src/firepit/layer.d.ts
+interface FirepitConfig {
   readonly embers?: number;
   readonly flameWidth?: number;
   readonly flameHeight?: number;
   readonly intensity?: number;
   readonly scale?: number;
-  readonly canvasOptions?: CanvasRenderingContext2DSettings;
-}
-declare class FirepitSimulation extends SimulationCanvas {
-  constructor(canvas: HTMLCanvasElement, config?: FirepitSimulationConfig);
-}
-//#endregion
-//#region src/firepit/layer.d.ts
-declare class FirepitLayer extends SimulationLayer {
-  #private;
-  constructor(config?: FirepitSimulationConfig);
-  tick(dt: number, _width: number, _height: number): void;
-  draw(ctx: CanvasRenderingContext2D, width: number, height: number): void;
 }
 //#endregion
 //#region src/firepit/types.d.ts
@@ -416,6 +393,9 @@ type FlameLayer = {
   height: number;
 };
 //#endregion
+//#region src/firepit/index.d.ts
+declare function createFirepit(config?: FirepitConfig): Effect<FirepitConfig>;
+//#endregion
 //#region src/fireworks/types.d.ts
 type ExplosionType = "peony" | "chrysanthemum" | "willow" | "ring" | "palm" | "crackle" | "crossette" | "dahlia" | "brocade" | "horsetail" | "strobe" | "heart" | "spiral" | "flower";
 type FireworkVariant = ExplosionType | "saturn" | "concentric";
@@ -436,10 +416,10 @@ interface ExplosionConfig {
   readonly spread3d: boolean;
   readonly glowSize: number;
 }
-interface FireworkSimulationConfig {
+interface FireworksConfig {
   readonly scale?: number;
   readonly autoSpawn?: boolean;
-  readonly canvasOptions?: CanvasRenderingContext2DSettings;
+  readonly variants?: FireworkVariant[];
 }
 declare const FIREWORK_VARIANTS: FireworkVariant[];
 declare const EXPLOSION_CONFIGS: Record<ExplosionType, ExplosionConfig>;
@@ -459,6 +439,23 @@ declare class Explosion {
   tick(dt: number): void;
 }
 //#endregion
+//#region src/fireworks/create-explosion.d.ts
+/**
+* Creates an array of {@link Explosion} particles for the given firework variant.
+* Use this to fire a fully formed explosion burst in your own render loop without
+* needing a {@link Fireworks} instance.
+*
+* @param variant - The firework variant to create.
+* @param position - The center position of the explosion in canvas pixels.
+* @param hue - Base hue in degrees (0–360).
+* @param options - Optional overrides for `lineWidth` (default `5`) and `scale` (default `1`).
+* @param rng - RNG function returning values in [0, 1). Defaults to `Math.random`.
+*/
+declare function createExplosion(variant: FireworkVariant, position: Point, hue: number, options?: {
+  lineWidth?: number;
+  scale?: number;
+}, rng?: () => number): Explosion[];
+//#endregion
 //#region src/fireworks/spark.d.ts
 declare class Spark {
   #private;
@@ -480,25 +477,14 @@ declare class Firework extends EventTarget {
   tick(dt: number): void;
 }
 //#endregion
-//#region src/fireworks/layer.d.ts
-declare class FireworkLayer extends SimulationLayer {
-  #private;
-  constructor(config?: FireworkSimulationConfig);
-  onResize(width: number, height: number): void;
-  fireExplosion(variant: FireworkVariant, position?: Point): void;
-  tick(dt: number, width: number, height: number): void;
-  draw(ctx: CanvasRenderingContext2D, width: number, height: number): void;
-}
-//#endregion
-//#region src/fireworks/simulation.d.ts
-declare class FireworkSimulation extends SimulationCanvas {
-  #private;
-  constructor(canvas: HTMLCanvasElement, config?: FireworkSimulationConfig);
-  fireExplosion(variant: FireworkVariant, position?: Point): void;
+//#region src/fireworks/index.d.ts
+interface FireworksInstance extends Effect<FireworksConfig> {
+  launch(variant: FireworkVariant, position?: Point): void;
 }
+declare function createFireworks(config?: FireworksConfig): FireworksInstance;
 //#endregion
-//#region src/glitter/simulation.d.ts
-interface GlitterSimulationConfig {
+//#region src/glitter/types.d.ts
+interface GlitterConfig {
   readonly count?: number;
   readonly colors?: string[];
   readonly size?: number;
@@ -506,21 +492,7 @@ interface GlitterSimulationConfig {
   readonly groundLevel?: number;
   readonly maxSettled?: number;
   readonly scale?: number;
-  readonly canvasOptions?: CanvasRenderingContext2DSettings;
-}
-declare class GlitterSimulation extends SimulationCanvas {
-  constructor(canvas: HTMLCanvasElement, config?: GlitterSimulationConfig);
 }
-//#endregion
-//#region src/glitter/layer.d.ts
-declare class GlitterLayer extends SimulationLayer {
-  #private;
-  constructor(config?: GlitterSimulationConfig);
-  tick(dt: number, _width: number, _height: number): void;
-  draw(ctx: CanvasRenderingContext2D, width: number, height: number): void;
-}
-//#endregion
-//#region src/glitter/types.d.ts
 type FallingGlitter = {
   x: number;
   y: number;
@@ -544,28 +516,17 @@ type SettledGlitter = {
   colorIndex: number;
 };
 //#endregion
-//#region src/lanterns/simulation.d.ts
-interface LanternSimulationConfig {
+//#region src/glitter/index.d.ts
+declare function createGlitter(config?: GlitterConfig): Effect<GlitterConfig>;
+//#endregion
+//#region src/lanterns/types.d.ts
+interface LanternsConfig {
   readonly count?: number;
   readonly colors?: string[];
   readonly size?: number;
   readonly speed?: number;
   readonly scale?: number;
-  readonly canvasOptions?: CanvasRenderingContext2DSettings;
-}
-declare class LanternSimulation extends SimulationCanvas {
-  constructor(canvas: HTMLCanvasElement, config?: LanternSimulationConfig);
 }
-//#endregion
-//#region src/lanterns/layer.d.ts
-declare class LanternLayer extends SimulationLayer {
-  #private;
-  constructor(config?: LanternSimulationConfig);
-  tick(dt: number, width: number, height: number): void;
-  draw(ctx: CanvasRenderingContext2D, width: number, height: number): void;
-}
-//#endregion
-//#region src/lanterns/types.d.ts
 type Lantern = {
   x: number;
   y: number;
@@ -581,42 +542,18 @@ type Lantern = {
   opacity: number;
 };
 //#endregion
-//#region src/layered.d.ts
-declare class LayeredSimulation extends LimitedFrameRateCanvas {
-  #private;
-  constructor(canvas: HTMLCanvasElement, frameRate?: number, options?: CanvasRenderingContext2DSettings);
-  add(layer: SimulationLayer): this;
-  start(): void;
-  destroy(): void;
-  draw(): void;
-  tick(): void;
-  onResize(): void;
-}
+//#region src/lanterns/index.d.ts
+declare function createLanterns(config?: LanternsConfig): Effect<LanternsConfig>;
 //#endregion
-//#region src/leaves/simulation.d.ts
-interface LeafSimulationConfig {
+//#region src/leaves/types.d.ts
+interface LeavesConfig {
   readonly count?: number;
   readonly colors?: string[];
   readonly size?: number;
   readonly speed?: number;
   readonly wind?: number;
   readonly scale?: number;
-  readonly canvasOptions?: CanvasRenderingContext2DSettings;
-}
-declare class LeafSimulation extends SimulationCanvas {
-  constructor(canvas: HTMLCanvasElement, config?: LeafSimulationConfig);
-}
-//#endregion
-//#region src/leaves/layer.d.ts
-declare class LeafLayer extends SimulationLayer {
-  #private;
-  constructor(config?: LeafSimulationConfig);
-  onResize(_width: number, height: number): void;
-  tick(dt: number, _width: number, height: number): void;
-  draw(ctx: CanvasRenderingContext2D, width: number, height: number): void;
 }
-//#endregion
-//#region src/leaves/types.d.ts
 type Leaf = {
   x: number;
   y: number;
@@ -634,26 +571,34 @@ type Leaf = {
   colorIndex: number;
 };
 //#endregion
-//#region src/lightning/simulation.d.ts
-interface LightningSimulationConfig {
+//#region src/leaves/index.d.ts
+declare function createLeaves(config?: LeavesConfig): Effect<LeavesConfig>;
+//#endregion
+//#region src/lightning/types.d.ts
+interface LightningConfig {
   readonly frequency?: number;
   readonly color?: string;
   readonly branches?: boolean;
   readonly flash?: boolean;
   readonly scale?: number;
-  readonly canvasOptions?: CanvasRenderingContext2DSettings;
-}
-declare class LightningSimulation extends SimulationCanvas {
-  constructor(canvas: HTMLCanvasElement, config?: LightningSimulationConfig);
-}
-//#endregion
-//#region src/lightning/layer.d.ts
-declare class LightningLayer extends SimulationLayer {
-  #private;
-  constructor(config?: LightningSimulationConfig);
-  tick(dt: number, _width: number, _height: number): void;
-  draw(ctx: CanvasRenderingContext2D, width: number, height: number): void;
 }
+type LightningBranch = {
+  segments: {
+    x: number;
+    y: number;
+  }[];
+  alpha: number;
+};
+type LightningBolt = {
+  segments: {
+    x: number;
+    y: number;
+  }[];
+  branches: LightningBranch[];
+  alpha: number;
+  lifetime: number;
+  ticksAlive: number;
+};
 //#endregion
 //#region src/lightning/system.d.ts
 interface LightningSystemConfig {
@@ -672,49 +617,18 @@ declare class LightningSystem {
   draw(ctx: CanvasRenderingContext2D, width: number, height: number): void;
 }
 //#endregion
-//#region src/lightning/types.d.ts
-type LightningBranch = {
-  segments: {
-    x: number;
-    y: number;
-  }[];
-  alpha: number;
-};
-type LightningBolt = {
-  segments: {
-    x: number;
-    y: number;
-  }[];
-  branches: LightningBranch[];
-  alpha: number;
-  lifetime: number;
-  ticksAlive: number;
-};
+//#region src/lightning/index.d.ts
+declare function createLightning(config?: LightningConfig): Effect<LightningConfig>;
 //#endregion
-//#region src/matrix/simulation.d.ts
-interface MatrixSimulationConfig {
+//#region src/matrix/types.d.ts
+interface MatrixConfig {
   readonly columns?: number;
   readonly speed?: number;
   readonly color?: string;
   readonly fontSize?: number;
   readonly trailLength?: number;
   readonly scale?: number;
-  readonly canvasOptions?: CanvasRenderingContext2DSettings;
 }
-declare class MatrixSimulation extends SimulationCanvas {
-  constructor(canvas: HTMLCanvasElement, config?: MatrixSimulationConfig);
-}
-//#endregion
-//#region src/matrix/layer.d.ts
-declare class MatrixLayer extends SimulationLayer {
-  #private;
-  constructor(config?: MatrixSimulationConfig);
-  onResize(width: number, height: number): void;
-  tick(dt: number, width: number, height: number): void;
-  draw(ctx: CanvasRenderingContext2D, width: number, height: number): void;
-}
-//#endregion
-//#region src/matrix/types.d.ts
 type MatrixColumn = {
   x: number;
   y: number;
@@ -724,8 +638,11 @@ type MatrixColumn = {
   headBrightness: number;
 };
 //#endregion
-//#region src/orbits/simulation.d.ts
-interface OrbitSimulationConfig {
+//#region src/matrix/index.d.ts
+declare function createMatrix(config?: MatrixConfig): Effect<MatrixConfig>;
+//#endregion
+//#region src/orbits/types.d.ts
+interface OrbitsConfig {
   readonly centers?: number;
   readonly orbitersPerCenter?: number;
   readonly speed?: number;
@@ -733,22 +650,7 @@ interface OrbitSimulationConfig {
   readonly trailLength?: number;
   readonly showCenters?: boolean;
   readonly scale?: number;
-  readonly canvasOptions?: CanvasRenderingContext2DSettings;
 }
-declare class OrbitSimulation extends SimulationCanvas {
-  constructor(canvas: HTMLCanvasElement, config?: OrbitSimulationConfig);
-}
-//#endregion
-//#region src/orbits/layer.d.ts
-declare class OrbitLayer extends SimulationLayer {
-  #private;
-  constructor(config?: OrbitSimulationConfig);
-  onResize(_width: number, _height: number): void;
-  tick(dt: number, width: number, height: number): void;
-  draw(ctx: CanvasRenderingContext2D, width: number, height: number): void;
-}
-//#endregion
-//#region src/orbits/types.d.ts
 type OrbitalCenter = {
   x: number;
   y: number;
@@ -766,8 +668,12 @@ type Orbiter = {
     x: number;
     y: number;
   }[];
+  trailHead: number;
 };
 //#endregion
+//#region src/orbits/index.d.ts
+declare function createOrbits(config?: OrbitsConfig): Effect<OrbitsConfig>;
+//#endregion
 //#region src/particles/types.d.ts
 type ParticleMouseMode = "attract" | "repel" | "connect" | "none";
 type NetworkParticle = {
@@ -779,8 +685,8 @@ type NetworkParticle = {
   baseSpeed: number;
 };
 //#endregion
-//#region src/particles/simulation.d.ts
-interface ParticleSimulationConfig {
+//#region src/particles/layer.d.ts
+interface ParticlesConfig {
   readonly count?: number;
   readonly color?: string;
   readonly lineColor?: string;
@@ -795,43 +701,19 @@ interface ParticleSimulationConfig {
   readonly glow?: boolean;
   readonly background?: string | null;
   readonly scale?: number;
-  readonly canvasOptions?: CanvasRenderingContext2DSettings;
-}
-declare class ParticleSimulation extends SimulationCanvas {
-  constructor(canvas: HTMLCanvasElement, config?: ParticleSimulationConfig);
 }
 //#endregion
-//#region src/particles/layer.d.ts
-declare class ParticleLayer extends SimulationLayer {
-  #private;
-  constructor(config?: ParticleSimulationConfig);
-  onResize(width: number, height: number): void;
-  onMount(canvas: HTMLCanvasElement): void;
-  onUnmount(canvas: HTMLCanvasElement): void;
-  tick(dt: number, width: number, height: number): void;
-  draw(ctx: CanvasRenderingContext2D, width: number, height: number): void;
-}
+//#region src/particles/index.d.ts
+declare function createParticles(config?: ParticlesConfig): Effect<ParticlesConfig>;
 //#endregion
-//#region src/petals/simulation.d.ts
-interface PetalSimulationConfig {
+//#region src/petals/layer.d.ts
+interface PetalsConfig {
   readonly count?: number;
   readonly colors?: string[];
   readonly size?: number;
   readonly speed?: number;
   readonly wind?: number;
   readonly scale?: number;
-  readonly canvasOptions?: CanvasRenderingContext2DSettings;
-}
-declare class PetalSimulation extends SimulationCanvas {
-  constructor(canvas: HTMLCanvasElement, config?: PetalSimulationConfig);
-}
-//#endregion
-//#region src/petals/layer.d.ts
-declare class PetalLayer extends SimulationLayer {
-  #private;
-  constructor(config?: PetalSimulationConfig);
-  tick(dt: number, _width: number, height: number): void;
-  draw(ctx: CanvasRenderingContext2D, width: number, height: number): void;
 }
 //#endregion
 //#region src/petals/types.d.ts
@@ -851,6 +733,9 @@ type Petal = {
   colorIndex: number;
 };
 //#endregion
+//#region src/petals/index.d.ts
+declare function createPetals(config?: PetalsConfig): Effect<PetalsConfig>;
+//#endregion
 //#region src/plasma/types.d.ts
 type PlasmaColor = {
   r: number;
@@ -858,25 +743,16 @@ type PlasmaColor = {
   b: number;
 };
 //#endregion
-//#region src/plasma/simulation.d.ts
-interface PlasmaSimulationConfig {
+//#region src/plasma/layer.d.ts
+interface PlasmaConfig {
   readonly speed?: number;
   readonly scale?: number;
   readonly resolution?: number;
   readonly palette?: PlasmaColor[];
-  readonly canvasOptions?: CanvasRenderingContext2DSettings;
-}
-declare class PlasmaSimulation extends SimulationCanvas {
-  constructor(canvas: HTMLCanvasElement, config?: PlasmaSimulationConfig);
 }
 //#endregion
-//#region src/plasma/layer.d.ts
-declare class PlasmaLayer extends SimulationLayer {
-  #private;
-  constructor(config?: PlasmaSimulationConfig);
-  tick(dt: number, _width: number, _height: number): void;
-  draw(ctx: CanvasRenderingContext2D, width: number, height: number): void;
-}
+//#region src/plasma/index.d.ts
+declare function createPlasma(config?: PlasmaConfig): Effect<PlasmaConfig>;
 //#endregion
 //#region src/rain/types.d.ts
 type RainVariant = "drizzle" | "downpour" | "thunderstorm";
@@ -900,8 +776,8 @@ type Splash = {
   gravity: number;
 };
 //#endregion
-//#region src/rain/simulation.d.ts
-interface RainSimulationConfig {
+//#region src/rain/layer.d.ts
+interface RainConfig {
   readonly variant?: RainVariant;
   readonly drops?: number;
   readonly wind?: number;
@@ -910,18 +786,6 @@ interface RainSimulationConfig {
   readonly color?: string;
   readonly groundLevel?: number;
   readonly scale?: number;
-  readonly canvasOptions?: CanvasRenderingContext2DSettings;
-}
-declare class RainSimulation extends SimulationCanvas {
-  constructor(canvas: HTMLCanvasElement, config?: RainSimulationConfig);
-}
-//#endregion
-//#region src/rain/layer.d.ts
-declare class RainLayer extends SimulationLayer {
-  #private;
-  constructor(config?: RainSimulationConfig);
-  tick(dt: number, width: number, height: number): void;
-  draw(ctx: CanvasRenderingContext2D, width: number, height: number): void;
 }
 //#endregion
 //#region src/rain/particle.d.ts
@@ -954,26 +818,17 @@ declare class SplashParticle {
   tick(dt?: number): void;
 }
 //#endregion
-//#region src/sandstorm/simulation.d.ts
-interface SandstormSimulationConfig {
+//#region src/rain/index.d.ts
+declare function createRain(config?: RainConfig): Effect<RainConfig>;
+//#endregion
+//#region src/sandstorm/layer.d.ts
+interface SandstormConfig {
   readonly count?: number;
   readonly wind?: number;
   readonly turbulence?: number;
   readonly color?: string;
   readonly hazeOpacity?: number;
   readonly scale?: number;
-  readonly canvasOptions?: CanvasRenderingContext2DSettings;
-}
-declare class SandstormSimulation extends SimulationCanvas {
-  constructor(canvas: HTMLCanvasElement, config?: SandstormSimulationConfig);
-}
-//#endregion
-//#region src/sandstorm/layer.d.ts
-declare class SandstormLayer extends SimulationLayer {
-  #private;
-  constructor(config?: SandstormSimulationConfig);
-  tick(dt: number, width: number, height: number): void;
-  draw(ctx: CanvasRenderingContext2D, width: number, height: number): void;
 }
 //#endregion
 //#region src/sandstorm/types.d.ts
@@ -988,6 +843,57 @@ type SandGrain = {
   turbulenceOffset: number;
 };
 //#endregion
+//#region src/sandstorm/index.d.ts
+declare function createSandstorm(config?: SandstormConfig): Effect<SandstormConfig>;
+//#endregion
+//#region src/scene.d.ts
+/**
+* Composable canvas that renders multiple Effect layers in order (first = bottom, last = top).
+*
+* @example
+* const scene = new Scene()
+*     .mount(canvas)
+*     .layer(new Aurora({ bands: 5 }))
+*     .layer(new Stars().withFade({ bottom: 0.4 }))
+*     .start();
+*/
+declare class Scene {
+  #private;
+  constructor(frameRate?: number, options?: CanvasRenderingContext2DSettings);
+  /**
+  * Mount the scene to a canvas element or CSS selector.
+  */
+  mount(canvas: HTMLCanvasElement | string, options?: CanvasRenderingContext2DSettings): this;
+  /**
+  * Add an effect layer. Layers are rendered in the order they are added.
+  * If the scene is already running, the layer is mounted immediately.
+  */
+  layer(effect: SimulationLayer): this;
+  /**
+  * Start the render loop.
+  */
+  start(): this;
+  /**
+  * Pause rendering without destroying state. Use resume() to continue.
+  */
+  pause(): this;
+  /**
+  * Resume rendering after pause().
+  */
+  resume(): this;
+  /**
+  * Stop and destroy all layers.
+  */
+  destroy(): void;
+  get speed(): number;
+  set speed(value: number);
+  get isTicking(): boolean;
+}
+/**
+* Factory alternative to `new Scene()`. Call .mount() and .layer() on the returned instance.
+*/
+declare function createScene(frameRate?: number, options?: CanvasRenderingContext2DSettings): Scene;
+//#endregion
 //#region src/shooting-stars/system.d.ts
 interface ShootingStarSystemConfig {
   readonly interval: [number, number];
@@ -1000,7 +906,6 @@ interface ShootingStarSystemConfig {
   readonly alphaRange?: number;
   readonly decayMin?: number;
   readonly decayRange?: number;
-  readonly verticalFade?: [number, number];
 }
 declare class ShootingStarSystem {
   #private;
@@ -1022,32 +927,23 @@ type ShootingStar = {
     x: number;
     y: number;
   }[];
+  trailHead: number;
 };
 //#endregion
-//#region src/snow/simulation.d.ts
-interface SnowSimulationConfig {
+//#region src/snow/layer.d.ts
+interface SnowConfig {
   readonly fillStyle?: string;
   readonly particles?: number;
   readonly scale?: number;
   readonly size?: number;
   readonly speed?: number;
-  readonly canvasOptions?: CanvasRenderingContext2DSettings;
-}
-declare class SnowSimulation extends SimulationCanvas {
-  constructor(canvas: HTMLCanvasElement, config?: SnowSimulationConfig);
 }
 //#endregion
-//#region src/snow/layer.d.ts
-declare class SnowLayer extends SimulationLayer {
-  #private;
-  constructor(config?: SnowSimulationConfig);
-  onResize(_width: number, height: number): void;
-  tick(dt: number, _width: number, height: number): void;
-  draw(ctx: CanvasRenderingContext2D, width: number, height: number): void;
-}
+//#region src/snow/index.d.ts
+declare function createSnow(config?: SnowConfig): Effect<SnowConfig>;
 //#endregion
-//#region src/sparklers/simulation.d.ts
-interface SparklerSimulationConfig {
+//#region src/sparklers/layer.d.ts
+interface SparklersConfig {
   readonly emitRate?: number;
   readonly maxSparks?: number;
   readonly colors?: string[];
@@ -1058,23 +954,6 @@ interface SparklerSimulationConfig {
   readonly trailLength?: number;
   readonly hoverMode?: boolean;
   readonly scale?: number;
-  readonly canvasOptions?: CanvasRenderingContext2DSettings;
-}
-declare class SparklerSimulation extends SimulationCanvas {
-  #private;
-  constructor(canvas: HTMLCanvasElement, config?: SparklerSimulationConfig);
-  setPosition(x: number, y: number): void;
-}
-//#endregion
-//#region src/sparklers/layer.d.ts
-declare class SparklerLayer extends SimulationLayer {
-  #private;
-  constructor(config?: SparklerSimulationConfig);
-  setPosition(x: number, y: number): void;
-  onMount(canvas: HTMLCanvasElement): void;
-  onUnmount(canvas: HTMLCanvasElement): void;
-  tick(dt: number, width: number, height: number): void;
-  draw(ctx: CanvasRenderingContext2D, width: number, height: number): void;
 }
 //#endregion
 //#region src/sparklers/particle.d.ts
@@ -1108,6 +987,12 @@ type SparklerSpark = {
   trail: Point[];
 };
 //#endregion
+//#region src/sparklers/index.d.ts
+interface SparklersInstance extends Effect<SparklersConfig> {
+  moveTo(x: number, y: number): void;
+}
+declare function createSparklers(config?: SparklersConfig): SparklersInstance;
+//#endregion
 //#region src/stars/types.d.ts
 type StarMode = "sky" | "shooting" | "both";
 type Star = {
@@ -1119,8 +1004,8 @@ type Star = {
   brightness: number;
 };
 //#endregion
-//#region src/stars/simulation.d.ts
-interface StarSimulationConfig {
+//#region src/stars/layer.d.ts
+interface StarsConfig {
   readonly mode?: StarMode;
   readonly starCount?: number;
   readonly shootingInterval?: [number, number];
@@ -1130,40 +1015,17 @@ interface StarSimulationConfig {
   readonly shootingColor?: string;
   readonly trailLength?: number;
   readonly scale?: number;
-  readonly verticalFade?: [number, number];
-  readonly canvasOptions?: CanvasRenderingContext2DSettings;
-}
-declare class StarSimulation extends SimulationCanvas {
-  constructor(canvas: HTMLCanvasElement, config?: StarSimulationConfig);
 }
 //#endregion
-//#region src/stars/layer.d.ts
-declare class StarLayer extends SimulationLayer {
-  #private;
-  constructor(config?: StarSimulationConfig);
-  tick(dt: number, width: number, height: number): void;
-  draw(ctx: CanvasRenderingContext2D, width: number, height: number): void;
-}
+//#region src/stars/index.d.ts
+declare function createStars(config?: StarsConfig): Effect<StarsConfig>;
 //#endregion
-//#region src/streamers/simulation.d.ts
-interface StreamerSimulationConfig {
+//#region src/streamers/layer.d.ts
+interface StreamersConfig {
   readonly count?: number;
   readonly colors?: string[];
   readonly speed?: number;
   readonly scale?: number;
-  readonly canvasOptions?: CanvasRenderingContext2DSettings;
-}
-declare class StreamerSimulation extends SimulationCanvas {
-  constructor(canvas: HTMLCanvasElement, config?: StreamerSimulationConfig);
-}
-//#endregion
-//#region src/streamers/layer.d.ts
-declare class StreamerLayer extends SimulationLayer {
-  #private;
-  constructor(config?: StreamerSimulationConfig);
-  onResize(width: number, height: number): void;
-  tick(dt: number, width: number, height: number): void;
-  draw(ctx: CanvasRenderingContext2D, width: number, height: number): void;
 }
 //#endregion
 //#region src/streamers/types.d.ts
@@ -1185,6 +1047,9 @@ type Streamer = {
   depth: number;
 };
 //#endregion
+//#region src/streamers/index.d.ts
+declare function createStreamers(config?: StreamersConfig): Effect<StreamersConfig>;
+//#endregion
 //#region src/trail.d.ts
 interface TrailConfig {
   readonly acceleration?: number;
@@ -1206,26 +1071,14 @@ declare class Trail {
   tick(dt?: number): void;
 }
 //#endregion
-//#region src/waves/simulation.d.ts
-interface WaveSimulationConfig {
+//#region src/waves/layer.d.ts
+interface WavesConfig {
   readonly layers?: number;
   readonly speed?: number;
   readonly colors?: string[];
   readonly foamColor?: string;
   readonly foamAmount?: number;
   readonly scale?: number;
-  readonly canvasOptions?: CanvasRenderingContext2DSettings;
-}
-declare class WaveSimulation extends SimulationCanvas {
-  constructor(canvas: HTMLCanvasElement, config?: WaveSimulationConfig);
-}
-//#endregion
-//#region src/waves/layer.d.ts
-declare class WaveLayer extends SimulationLayer {
-  #private;
-  constructor(config?: WaveSimulationConfig);
-  tick(dt: number, width: number, height: number): void;
-  draw(ctx: CanvasRenderingContext2D, width: number, height: number): void;
 }
 //#endregion
 //#region src/waves/types.d.ts
@@ -1237,8 +1090,12 @@ type Wave = {
   baseY: number;
   color: string;
   foamThreshold: number;
+  rgb: [number, number, number];
 };
 //#endregion
+//#region src/waves/index.d.ts
+declare function createWaves(config?: WavesConfig): Effect<WavesConfig>;
+//#endregion
 //#region src/wormhole/types.d.ts
 type WormholeDirection = "inward" | "outward";
 type WormholeParticle = {
@@ -1250,27 +1107,17 @@ type WormholeParticle = {
   trail: number;
 };
 //#endregion
-//#region src/wormhole/simulation.d.ts
-interface WormholeSimulationConfig {
+//#region src/wormhole/layer.d.ts
+interface WormholeConfig {
   readonly count?: number;
   readonly speed?: number;
   readonly color?: string;
   readonly direction?: WormholeDirection;
   readonly scale?: number;
-  readonly canvasOptions?: CanvasRenderingContext2DSettings;
-}
-declare class WormholeSimulation extends SimulationCanvas {
-  constructor(canvas: HTMLCanvasElement, config?: WormholeSimulationConfig);
 }
 //#endregion
-//#region src/wormhole/layer.d.ts
-declare class WormholeLayer extends SimulationLayer {
-  #private;
-  constructor(config?: WormholeSimulationConfig);
-  onResize(width: number, height: number): void;
-  tick(dt: number, width: number, height: number): void;
-  draw(ctx: CanvasRenderingContext2D, width: number, height: number): void;
-}
+//#region src/wormhole/index.d.ts
+declare function createWormhole(config?: WormholeConfig): Effect<WormholeConfig>;
 //#endregion
-export { AuroraBand, AuroraLayer, AuroraSimulation, AuroraSimulationConfig, Balloon, BalloonLayer, BalloonParticle, BalloonParticleConfig, BalloonSimulation, BalloonSimulationConfig, Bubble, BubbleLayer, BubbleSimulation, BubbleSimulationConfig, ConfettiLayer, ConfettiParticle, type ConfettiParticleConfig, type Shape as ConfettiShape, ConfettiSimulation, type ConfettiSimulationConfig, DonutLayer, DonutSimulation, DonutSimulationConfig, EXPLOSION_CONFIGS, EdgeFade, EdgeFadeSide, Ember, Explosion, ExplosionConfig, ExplosionType, FIREWORK_VARIANTS, FallingGlitter, Firefly, FireflyLayer, FireflyParticle, FireflyParticleConfig, FireflySimulation, FireflySimulationConfig, FirepitLayer, FirepitSimulation, FirepitSimulationConfig, Firework, FireworkLayer, FireworkSimulation, FireworkSimulationConfig, FireworkVariant, FlameLayer, GlitterLayer, GlitterSimulation, GlitterSimulationConfig, Lantern, LanternLayer, LanternSimulation, LanternSimulationConfig, LayeredSimulation, Leaf, LeafLayer, LeafSimulation, LeafSimulationConfig, LightningBolt, LightningBranch, LightningLayer, LightningSimulation, LightningSimulationConfig, LightningSystem, LightningSystemConfig, LimitedFrameRateCanvas, MatrixColumn, MatrixLayer, MatrixSimulation, MatrixSimulationConfig, NetworkParticle, OrbitLayer, OrbitSimulation, OrbitSimulationConfig, OrbitalCenter, Orbiter, PALETTES, type Palette, ParticleLayer, ParticleMouseMode, ParticleShape, ParticleSimulation, ParticleSimulationConfig, Petal, PetalLayer, PetalSimulation, PetalSimulationConfig, PlasmaColor, PlasmaLayer, PlasmaSimulation, PlasmaSimulationConfig, PopParticle, RainLayer, RainSimulation, RainSimulationConfig, RainVariant, Raindrop, RaindropParticle, RaindropParticleConfig, SHAPE_PATHS, SandGrain, SandstormLayer, SandstormSimulation, SandstormSimulationConfig, SettledGlitter, type ShootingStar, ShootingStarSystem, ShootingStarSystemConfig, SimulationCanvas, SimulationLayer, SnowLayer, SnowSimulation, SnowSimulationConfig, Spark, SparklerLayer, SparklerParticle, SparklerParticleConfig, SparklerSimulation, SparklerSimulationConfig, SparklerSpark, Splash, SplashParticle, SplashParticleConfig, Star, StarLayer, StarMode, StarSimulation, StarSimulationConfig, Streamer, StreamerLayer, StreamerSimulation, StreamerSimulationConfig, Trail, TrailConfig, Wave, WaveLayer, WaveSimulation, WaveSimulationConfig, WormholeDirection, WormholeLayer, WormholeParticle, WormholeSimulation, WormholeSimulationConfig, createFireflySprite, parseColor };
+export { type AuroraBand, type AuroraConfig, type Balloon, BalloonParticle, type BalloonParticleConfig, type BalloonsConfig, type Bubble, type BubblesConfig, type Config as ConfettiBurstConfig, type ConfettiConfig, ConfettiInstance, ConfettiParticle, type ConfettiParticleConfig, type Shape as ConfettiShape, type DonutsConfig, EXPLOSION_CONFIGS, type EdgeFade, type EdgeFadeSide, Effect, type Ember, Explosion, type ExplosionConfig, type ExplosionType, FIREWORK_VARIANTS, type FallingGlitter, type FirefliesConfig, type Firefly, FireflyParticle, type FireflyParticleConfig, type FirepitConfig, Firework, type FireworkVariant, type FireworksConfig, FireworksInstance, type FlameLayer, type GlitterConfig, type Lantern, type LanternsConfig, type Leaf, type LeavesConfig, type LightningBolt, type LightningBranch, type LightningConfig, LightningSystem, type LightningSystemConfig, LimitedFrameRateCanvas, type MatrixColumn, type MatrixConfig, type NetworkParticle, type OrbitalCenter, type Orbiter, type OrbitsConfig, PALETTES, type Palette, type ParticleMouseMode, type ParticleShape, type ParticlesConfig, type Petal, type PetalsConfig, type PlasmaColor, type PlasmaConfig, type PopParticle, type RainConfig, type RainVariant, type Raindrop, RaindropParticle, type RaindropParticleConfig, SHAPE_PATHS, type SandGrain, type SandstormConfig, Scene, type SettledGlitter, type ShootingStar, ShootingStarSystem, ShootingStarSystemConfig, type SnowConfig, Spark, SparklerParticle, type SparklerParticleConfig, type SparklerSpark, type SparklersConfig, SparklersInstance, type Splash, SplashParticle, type SplashParticleConfig, type Star, type StarMode, type StarsConfig, type Streamer, type StreamersConfig, Trail, TrailConfig, type Wave, type WavesConfig, type WormholeConfig, type WormholeDirection, type WormholeParticle, createAurora, createBalloons, createBubbles, createConfetti, createDonuts, createExplosion, createFireflies, createFireflySprite, createFirepit, createFireworks, createGlitter, createLanterns, createLeaves, createLightning, createMatrix, createOrbits, createParticles, createPetals, createPlasma, createRain, createSandstorm, createScene, createSnow, createSparklers, createStars, createStreamers, createWaves, createWormhole, parseColor };
 //# sourceMappingURL=index.d.mts.map