@basmilius/sparkle 2.1.0 → 2.2.0

package/src/donuts/layer.ts

@@ -1,18 +1,33 @@
-import { SimulationLayer } from '../layer';
+import { Effect } from '../effect';
 import { DEFAULT_CONFIG, MULBERRY } from './consts';
 import type { Donut } from './donut';
-import type { DonutSimulationConfig } from './simulation';
 
-export class DonutLayer extends SimulationLayer {
+export interface DonutsConfig {
+    readonly background?: string;
+    readonly collisionPadding?: number;
+    readonly colors?: string[];
+    readonly count?: number;
+    readonly mouseAvoidance?: boolean;
+    readonly mouseAvoidanceRadius?: number;
+    readonly mouseAvoidanceStrength?: number;
+    readonly radiusRange?: [number, number];
+    readonly repulsionStrength?: number;
+    readonly rotationSpeedRange?: [number, number];
+    readonly scale?: number;
+    readonly speedRange?: [number, number];
+    readonly thickness?: number;
+}
+
+export class Donuts extends Effect<DonutsConfig> {
     readonly #background: string;
     readonly #collisionPadding: number;
     readonly #colors: string[];
     readonly #count: number;
-    readonly #mouseAvoidance: boolean;
-    readonly #mouseAvoidanceRadius: number;
-    readonly #mouseAvoidanceStrength: number;
+    #mouseAvoidance: boolean;
+    #mouseAvoidanceRadius: number;
+    #mouseAvoidanceStrength: number;
     readonly #radiusRange: [number, number];
-    readonly #repulsionStrength: number;
+    #repulsionStrength: number;
     readonly #rotationSpeedRange: [number, number];
     readonly #scale: number;
     readonly #speedRange: [number, number];
@@ -27,7 +42,7 @@ export class DonutLayer extends SimulationLayer {
     #height: number = 540;
     #initialized: boolean = false;
 
-    constructor(config: DonutSimulationConfig = {}) {
+    constructor(config: DonutsConfig = {}) {
         super();
 
         const scale = config.scale ?? 1;
@@ -82,6 +97,21 @@ export class DonutLayer extends SimulationLayer {
         canvas.removeEventListener('mouseleave', this.#onMouseLeaveBound);
     }
 
+    configure(config: Partial<DonutsConfig>): void {
+        if (config.mouseAvoidance !== undefined) {
+            this.#mouseAvoidance = config.mouseAvoidance;
+        }
+        if (config.mouseAvoidanceRadius !== undefined) {
+            this.#mouseAvoidanceRadius = config.mouseAvoidanceRadius;
+        }
+        if (config.mouseAvoidanceStrength !== undefined) {
+            this.#mouseAvoidanceStrength = config.mouseAvoidanceStrength;
+        }
+        if (config.repulsionStrength !== undefined) {
+            this.#repulsionStrength = config.repulsionStrength;
+        }
+    }
+
     tick(dt: number, width: number, height: number): void {
         this.#width = width;
         this.#height = height;
@@ -103,9 +133,9 @@ export class DonutLayer extends SimulationLayer {
         ctx.fillRect(0, 0, width, height);
 
         for (const donut of this.#donuts) {
-            ctx.save();
-            ctx.translate(donut.x, donut.y);
-            ctx.rotate(donut.angle);
+            const cos = Math.cos(donut.angle);
+            const sin = Math.sin(donut.angle);
+            ctx.setTransform(cos, sin, -sin, cos, donut.x, donut.y);
 
             ctx.beginPath();
             ctx.arc(0, 0, donut.outerRadius, 0, Math.PI * 2);
@@ -114,8 +144,9 @@ export class DonutLayer extends SimulationLayer {
 
             ctx.fillStyle = donut.color;
             ctx.fill();
-            ctx.restore();
         }
+
+        ctx.resetTransform();
     }
 
     #updateDonut(donut: Donut, dt: number): void {

package/src/effect.ts

@@ -0,0 +1,107 @@
+import { SimulationCanvas } from './simulation-canvas';
+import type { EdgeFade, EdgeFadeSide, SimulationLayer } from './layer';
+
+export type { EdgeFade, EdgeFadeSide };
+
+/**
+ * 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();
+ */
+export abstract class Effect<TConfig = Record<string, unknown>> implements SimulationLayer {
+    #canvas: SimulationCanvas | null = null;
+    fade: EdgeFade | null = 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 {
+        this.fade = fade;
+        return this;
+    }
+
+    /**
+     * 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 = {colorSpace: 'display-p3'}): this {
+        if (typeof canvas === 'string') {
+            const el = document.querySelector<HTMLCanvasElement>(canvas);
+
+            if (!el) {
+                throw new Error(`Effect.mount(): no element found for selector "${canvas}".`);
+            }
+
+            canvas = el;
+        }
+
+        this.#canvas = new SimulationCanvas(canvas, this as unknown as SimulationLayer, 60, options);
+        return this;
+    }
+
+    /**
+     * Remove this effect from its canvas and clean up the render loop.
+     */
+    unmount(): this {
+        this.#canvas?.destroy();
+        this.#canvas = null;
+        return this;
+    }
+
+    /**
+     * Start the render loop. Call mount() first.
+     */
+    start(): this {
+        this.#canvas?.start();
+        return this;
+    }
+
+    /**
+     * Pause rendering without destroying state. Use resume() to continue.
+     */
+    pause(): this {
+        this.#canvas?.pause();
+        return this;
+    }
+
+    /**
+     * Resume rendering after a pause().
+     */
+    resume(): this {
+        this.#canvas?.resume();
+        return this;
+    }
+
+    /**
+     * Stop rendering and call onUnmount(). Safe to call multiple times.
+     */
+    destroy(): void {
+        this.unmount();
+    }
+}

package/src/fade.ts

@@ -0,0 +1,87 @@
+import type { EdgeFade, EdgeFadeSide } from './layer';
+
+function parseSide(side: EdgeFadeSide): [number, number] {
+    return typeof side === 'number' ? [0, side] : side;
+}
+
+export function applyEdgeFade(ctx: CanvasRenderingContext2D, width: number, height: number, fade: EdgeFade): void {
+    ctx.globalCompositeOperation = 'destination-out';
+
+    if (fade.top !== undefined) {
+        const [near, far] = parseSide(fade.top);
+        const nearPx = near * height;
+        const farPx = far * height;
+
+        if (nearPx > 0) {
+            ctx.fillStyle = 'rgba(0,0,0,1)';
+            ctx.fillRect(0, 0, width, nearPx);
+        }
+
+        if (farPx > nearPx) {
+            const gradient = ctx.createLinearGradient(0, nearPx, 0, farPx);
+            gradient.addColorStop(0, 'rgba(0,0,0,1)');
+            gradient.addColorStop(1, 'rgba(0,0,0,0)');
+            ctx.fillStyle = gradient;
+            ctx.fillRect(0, nearPx, width, farPx - nearPx);
+        }
+    }
+
+    if (fade.bottom !== undefined) {
+        const [near, far] = parseSide(fade.bottom);
+        const nearPx = near * height;
+        const farPx = far * height;
+
+        if (nearPx > 0) {
+            ctx.fillStyle = 'rgba(0,0,0,1)';
+            ctx.fillRect(0, height - nearPx, width, nearPx);
+        }
+
+        if (farPx > nearPx) {
+            const gradient = ctx.createLinearGradient(0, height - farPx, 0, height - nearPx);
+            gradient.addColorStop(0, 'rgba(0,0,0,0)');
+            gradient.addColorStop(1, 'rgba(0,0,0,1)');
+            ctx.fillStyle = gradient;
+            ctx.fillRect(0, height - farPx, width, farPx - nearPx);
+        }
+    }
+
+    if (fade.left !== undefined) {
+        const [near, far] = parseSide(fade.left);
+        const nearPx = near * width;
+        const farPx = far * width;
+
+        if (nearPx > 0) {
+            ctx.fillStyle = 'rgba(0,0,0,1)';
+            ctx.fillRect(0, 0, nearPx, height);
+        }
+
+        if (farPx > nearPx) {
+            const gradient = ctx.createLinearGradient(nearPx, 0, farPx, 0);
+            gradient.addColorStop(0, 'rgba(0,0,0,1)');
+            gradient.addColorStop(1, 'rgba(0,0,0,0)');
+            ctx.fillStyle = gradient;
+            ctx.fillRect(nearPx, 0, farPx - nearPx, height);
+        }
+    }
+
+    if (fade.right !== undefined) {
+        const [near, far] = parseSide(fade.right);
+        const nearPx = near * width;
+        const farPx = far * width;
+
+        if (nearPx > 0) {
+            ctx.fillStyle = 'rgba(0,0,0,1)';
+            ctx.fillRect(width - nearPx, 0, nearPx, height);
+        }
+
+        if (farPx > nearPx) {
+            const gradient = ctx.createLinearGradient(width - farPx, 0, width - nearPx, 0);
+            gradient.addColorStop(0, 'rgba(0,0,0,0)');
+            gradient.addColorStop(1, 'rgba(0,0,0,1)');
+            ctx.fillStyle = gradient;
+            ctx.fillRect(width - farPx, 0, farPx - nearPx, height);
+        }
+    }
+
+    ctx.globalCompositeOperation = 'source-over';
+}

package/src/fireflies/index.ts

@@ -1,6 +1,12 @@
-export { FireflyLayer } from './layer';
+import { Fireflies } from './layer';
+import type { FirefliesConfig } from './layer';
+import type { Effect } from '../effect';
+
+export function createFireflies(config?: FirefliesConfig): Effect<FirefliesConfig> {
+    return new Fireflies(config);
+}
+
 export { FireflyParticle, createFireflySprite } from './particle';
-export { FireflySimulation } from './simulation';
+export type { FirefliesConfig };
 export type { FireflyParticleConfig } from './particle';
-export type { FireflySimulationConfig } from './simulation';
 export type { Firefly } from './types';

package/src/fireflies/layer.ts

@@ -1,23 +1,31 @@
-import { SimulationLayer } from '../layer';
+import { Effect } from '../effect';
 import { MULBERRY } from './consts';
-import type { FireflySimulationConfig } from './simulation';
 import type { Firefly } from './types';
 
 const SPRITE_SIZE = 64;
 const SPRITE_CENTER = SPRITE_SIZE / 2;
 const SPRITE_RADIUS = SPRITE_SIZE / 2;
 
-export class FireflyLayer extends SimulationLayer {
+export interface FirefliesConfig {
+    readonly count?: number;
+    readonly color?: string;
+    readonly size?: number;
+    readonly speed?: number;
+    readonly glowSpeed?: number;
+    readonly scale?: number;
+}
+
+export class Fireflies extends Effect<FirefliesConfig> {
     readonly #scale: number;
     readonly #size: number;
-    readonly #speed: number;
-    readonly #glowSpeed: number;
+    #speed: number;
+    #glowSpeed: number;
     #maxCount: number;
     #time: number = 0;
     #fireflies: Firefly[] = [];
     #sprite: HTMLCanvasElement;
 
-    constructor(config: FireflySimulationConfig = {}) {
+    constructor(config: FirefliesConfig = {}) {
         super();
 
         this.#scale = config.scale ?? 1;
@@ -39,15 +47,24 @@ export class FireflyLayer extends SimulationLayer {
         }
     }
 
+    configure(config: Partial<FirefliesConfig>): void {
+        if (config.speed !== undefined) {
+            this.#speed = config.speed;
+        }
+        if (config.glowSpeed !== undefined) {
+            this.#glowSpeed = config.glowSpeed;
+        }
+    }
+
     tick(dt: number, _width: number, _height: number): void {
         this.#time += 0.02 * dt * this.#speed;
 
         for (const firefly of this.#fireflies) {
             const moveX = Math.sin(this.#time * firefly.freqX1 + firefly.phaseX1) * firefly.amplitudeX
-                        + Math.sin(this.#time * firefly.freqX2 + firefly.phaseX2) * firefly.amplitudeX * 0.5;
+                + Math.sin(this.#time * firefly.freqX2 + firefly.phaseX2) * firefly.amplitudeX * 0.5;
 
             const moveY = Math.sin(this.#time * firefly.freqY1 + firefly.phaseY1) * firefly.amplitudeY
-                        + Math.sin(this.#time * firefly.freqY2 + firefly.phaseY2) * firefly.amplitudeY * 0.5;
+                + Math.sin(this.#time * firefly.freqY2 + firefly.phaseY2) * firefly.amplitudeY * 0.5;
 
             firefly.x += moveX * dt / (3000 * (1 / this.#speed));
             firefly.y += moveY * dt / (3000 * (1 / this.#speed));
@@ -94,7 +111,7 @@ export class FireflyLayer extends SimulationLayer {
         ctx.globalAlpha = 1;
     }
 
-    #parseColor(color: string): {r: number; g: number; b: number} {
+    #parseColor(color: string): { r: number; g: number; b: number } {
         const canvas = document.createElement('canvas');
         canvas.width = 1;
         canvas.height = 1;

package/src/fireflies/particle.ts

@@ -101,10 +101,10 @@ export class FireflyParticle {
         this.#time += 0.02 * dt * this.#speed;
 
         const moveX = Math.sin(this.#time * this.#freqX1 + this.#phaseX1) * this.#amplitudeX * this.#bounds.width
-                    + Math.sin(this.#time * this.#freqX2 + this.#phaseX2) * this.#amplitudeX * this.#bounds.width * 0.5;
+            + Math.sin(this.#time * this.#freqX2 + this.#phaseX2) * this.#amplitudeX * this.#bounds.width * 0.5;
 
         const moveY = Math.sin(this.#time * this.#freqY1 + this.#phaseY1) * this.#amplitudeY * this.#bounds.height
-                    + Math.sin(this.#time * this.#freqY2 + this.#phaseY2) * this.#amplitudeY * this.#bounds.height * 0.5;
+            + Math.sin(this.#time * this.#freqY2 + this.#phaseY2) * this.#amplitudeY * this.#bounds.height * 0.5;
 
         this.#x += (moveX / 3000) * dt;
         this.#y += (moveY / 3000) * dt;

package/src/firepit/index.ts

@@ -1,4 +1,10 @@
-export { FirepitLayer } from './layer';
-export { FirepitSimulation } from './simulation';
-export type { FirepitSimulationConfig } from './simulation';
+import { Firepit } from './layer';
+import type { FirepitConfig } from './layer';
+import type { Effect } from '../effect';
+
+export function createFirepit(config?: FirepitConfig): Effect<FirepitConfig> {
+    return new Firepit(config);
+}
+
+export type { FirepitConfig };
 export type { Ember, FlameLayer } from './types';

package/src/firepit/layer.ts

@@ -1,19 +1,26 @@
-import { SimulationLayer } from '../layer';
+import { Effect } from '../effect';
 import { MULBERRY } from './consts';
-import type { FirepitSimulationConfig } from './simulation';
 import type { Ember, FlameLayer } from './types';
 
-export class FirepitLayer extends SimulationLayer {
+export interface FirepitConfig {
+    readonly embers?: number;
+    readonly flameWidth?: number;
+    readonly flameHeight?: number;
+    readonly intensity?: number;
+    readonly scale?: number;
+}
+
+export class Firepit extends Effect<FirepitConfig> {
     readonly #scale: number;
-    readonly #flameWidth: number;
-    readonly #flameHeight: number;
-    readonly #intensity: number;
+    #flameWidth: number;
+    #flameHeight: number;
+    #intensity: number;
     #maxEmbers: number;
     #time: number = 0;
     #embers: Ember[] = [];
     #flameLayers: FlameLayer[] = [];
 
-    constructor(config: FirepitSimulationConfig = {}) {
+    constructor(config: FirepitConfig = {}) {
         super();
 
         this.#scale = config.scale ?? 1;
@@ -38,6 +45,18 @@ export class FirepitLayer extends SimulationLayer {
         }
     }
 
+    configure(config: Partial<FirepitConfig>): void {
+        if (config.intensity !== undefined) {
+            this.#intensity = config.intensity;
+        }
+        if (config.flameWidth !== undefined) {
+            this.#flameWidth = config.flameWidth;
+        }
+        if (config.flameHeight !== undefined) {
+            this.#flameHeight = config.flameHeight;
+        }
+    }
+
     tick(dt: number, _width: number, _height: number): void {
         this.#time += 0.03 * dt * this.#intensity;