@basmilius/sparkle 2.0.0 → 2.2.0

package/src/scene.ts

@@ -0,0 +1,201 @@
+import { LimitedFrameRateCanvas } from './canvas';
+import { applyEdgeFade } from './fade';
+import type { SimulationLayer } from './layer';
+
+/**
+ * Internal canvas runner that drives all layers in a Scene.
+ */
+class SceneCanvas extends LimitedFrameRateCanvas {
+    readonly #layers: SimulationLayer[];
+    readonly #contextOptions: CanvasRenderingContext2DSettings;
+    #offscreen: HTMLCanvasElement | null = null;
+    #offscreenCtx: CanvasRenderingContext2D | null = null;
+
+    constructor(canvas: HTMLCanvasElement, layers: SimulationLayer[], frameRate: number, options: CanvasRenderingContext2DSettings) {
+        super(canvas, frameRate, options);
+        this.#layers = layers;
+        this.#contextOptions = options;
+
+        canvas.style.position = 'absolute';
+        canvas.style.top = '0';
+        canvas.style.left = '0';
+        canvas.style.height = '100%';
+        canvas.style.width = '100%';
+    }
+
+    start(): void {
+        for (const layer of this.#layers) {
+            layer.onMount(this.canvas);
+        }
+        super.start();
+    }
+
+    destroy(): void {
+        for (const layer of this.#layers) {
+            layer.onUnmount(this.canvas);
+        }
+        super.destroy();
+    }
+
+    draw(): void {
+        this.canvas.height = this.height;
+        this.canvas.width = this.width;
+
+        const ctx = this.context;
+        ctx.clearRect(0, 0, this.width, this.height);
+
+        for (const layer of this.#layers) {
+            if (layer.fade) {
+                const offCtx = this.#getOffscreenCtx(this.width, this.height);
+                offCtx.clearRect(0, 0, this.width, this.height);
+                layer.draw(offCtx, this.width, this.height);
+                applyEdgeFade(offCtx, this.width, this.height, layer.fade);
+                ctx.drawImage(this.#offscreen!, 0, 0);
+            } else {
+                ctx.save();
+                layer.draw(ctx, this.width, this.height);
+                ctx.restore();
+            }
+        }
+    }
+
+    tick(): void {
+        const dt = (this.delta > 0 && this.delta < 200 ? this.delta / (1000 / 60) : 1) * this.speed * LimitedFrameRateCanvas.globalSpeed;
+
+        for (const layer of this.#layers) {
+            layer.tick(dt, this.width, this.height);
+        }
+    }
+
+    onResize(): void {
+        super.onResize();
+
+        if (this.#offscreen) {
+            this.#offscreen.width = this.width;
+            this.#offscreen.height = this.height;
+        }
+
+        for (const layer of this.#layers) {
+            layer.onResize(this.width, this.height);
+        }
+    }
+
+    #getOffscreenCtx(width: number, height: number): CanvasRenderingContext2D {
+        if (!this.#offscreen) {
+            this.#offscreen = document.createElement('canvas');
+            this.#offscreen.width = width;
+            this.#offscreen.height = height;
+            this.#offscreenCtx = this.#offscreen.getContext('2d', this.#contextOptions)!;
+        }
+
+        return this.#offscreenCtx!;
+    }
+}
+
+/**
+ * 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();
+ */
+export class Scene {
+    readonly #layers: SimulationLayer[] = [];
+    readonly #frameRate: number;
+    readonly #defaultOptions: CanvasRenderingContext2DSettings;
+    #runner: SceneCanvas | null = null;
+
+    constructor(frameRate: number = 60, options: CanvasRenderingContext2DSettings = {colorSpace: 'display-p3'}) {
+        this.#frameRate = frameRate;
+        this.#defaultOptions = options;
+    }
+
+    /**
+     * Mount the scene to a canvas element or CSS selector.
+     */
+    mount(canvas: HTMLCanvasElement | string, options?: CanvasRenderingContext2DSettings): this {
+        if (typeof canvas === 'string') {
+            const el = document.querySelector<HTMLCanvasElement>(canvas);
+
+            if (!el) {
+                throw new Error(`Scene.mount(): no element found for selector "${canvas}".`);
+            }
+
+            canvas = el;
+        }
+
+        this.#runner?.destroy();
+        this.#runner = new SceneCanvas(canvas, this.#layers, this.#frameRate, options ?? this.#defaultOptions);
+        return 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 {
+        this.#layers.push(effect);
+
+        if (this.#runner?.isTicking) {
+            effect.onMount(this.#runner.canvas);
+        }
+
+        return this;
+    }
+
+    /**
+     * Start the render loop.
+     */
+    start(): this {
+        this.#runner?.start();
+        return this;
+    }
+
+    /**
+     * Pause rendering without destroying state. Use resume() to continue.
+     */
+    pause(): this {
+        this.#runner?.pause();
+        return this;
+    }
+
+    /**
+     * Resume rendering after pause().
+     */
+    resume(): this {
+        this.#runner?.resume();
+        return this;
+    }
+
+    /**
+     * Stop and destroy all layers.
+     */
+    destroy(): void {
+        this.#runner?.destroy();
+        this.#runner = null;
+    }
+
+    get speed(): number {
+        return this.#runner?.speed ?? 1;
+    }
+
+    set speed(value: number) {
+        if (this.#runner) {
+            this.#runner.speed = value;
+        }
+    }
+
+    get isTicking(): boolean {
+        return this.#runner?.isTicking ?? false;
+    }
+}
+
+/**
+ * Factory alternative to `new Scene()`. Call .mount() and .layer() on the returned instance.
+ */
+export function createScene(frameRate?: number, options?: CanvasRenderingContext2DSettings): Scene {
+    return new Scene(frameRate, options);
+}

package/src/shooting-stars/index.ts

@@ -0,0 +1,3 @@
+export { ShootingStarSystem } from './system';
+export type { ShootingStarSystemConfig } from './system';
+export type { ShootingStar } from './types';

package/src/shooting-stars/system.ts

@@ -0,0 +1,151 @@
+import type { ShootingStar } from './types';
+
+export interface ShootingStarSystemConfig {
+    readonly interval: [number, number];
+    readonly color?: [number, number, number];
+    readonly trailLength?: number;
+    readonly trailAlphaFactor?: number;
+    readonly speed?: number;
+    readonly scale?: number;
+    readonly alphaMin?: number;
+    readonly alphaRange?: number;
+    readonly decayMin?: number;
+    readonly decayRange?: number;
+}
+
+export class ShootingStarSystem {
+    readonly #interval: [number, number];
+    readonly #color: [number, number, number];
+    readonly #trailLength: number;
+    readonly #trailAlphaFactor: number;
+    readonly #speed: number;
+    readonly #scale: number;
+    readonly #alphaMin: number;
+    readonly #alphaRange: number;
+    readonly #decayMin: number;
+    readonly #decayRange: number;
+    readonly #rng: () => number;
+    #cooldown: number;
+    #stars: ShootingStar[] = [];
+
+    constructor(config: ShootingStarSystemConfig, rng: () => number) {
+        this.#interval = config.interval;
+        this.#color = config.color ?? [200, 230, 255];
+        this.#trailLength = config.trailLength ?? 18;
+        this.#trailAlphaFactor = config.trailAlphaFactor ?? 0.5;
+        this.#speed = config.speed ?? 1;
+        this.#scale = config.scale ?? 1;
+        this.#alphaMin = config.alphaMin ?? 0.7;
+        this.#alphaRange = config.alphaRange ?? 0.3;
+        this.#decayMin = config.decayMin ?? 0.008;
+        this.#decayRange = config.decayRange ?? 0.01;
+        this.#rng = rng;
+        this.#cooldown = this.#interval[0] + this.#rng() * (this.#interval[1] - this.#interval[0]);
+    }
+
+    tick(dt: number, width: number, height: number): void {
+        this.#cooldown -= dt;
+
+        if (this.#cooldown <= 0) {
+            this.#stars.push(this.#create(width, height));
+            this.#cooldown = this.#interval[0] + this.#rng() * (this.#interval[1] - this.#interval[0]);
+        }
+
+        let alive = 0;
+
+        for (let i = 0; i < this.#stars.length; i++) {
+            const star = this.#stars[i];
+
+            const trail = star.trail;
+            const maxLen = this.#trailLength;
+
+            if (trail.length < maxLen) {
+                trail.push({x: star.x, y: star.y});
+                star.trailHead = trail.length - 1;
+            } else {
+                const next = (star.trailHead + 1) % maxLen;
+                trail[next].x = star.x;
+                trail[next].y = star.y;
+                star.trailHead = next;
+            }
+
+            star.x += star.vx * this.#speed * dt;
+            star.y += star.vy * this.#speed * dt;
+            star.alpha -= star.decay * dt;
+
+            const inBounds = star.alpha > 0 && star.x > -50 && star.x < width + 50 && star.y < height + 50;
+
+            if (inBounds) {
+                this.#stars[alive++] = star;
+            }
+        }
+
+        this.#stars.length = alive;
+    }
+
+    draw(ctx: CanvasRenderingContext2D): void {
+        const [cr, cg, cb] = this.#color;
+
+        ctx.globalCompositeOperation = 'lighter';
+
+        for (const star of this.#stars) {
+            const trail = star.trail;
+            const trailLen = trail.length;
+            const isFull = trailLen === this.#trailLength;
+            const oldest = isFull ? (star.trailHead + 1) % trailLen : 0;
+
+            for (let t = 0; t < trailLen; t++) {
+                const progress = t / trailLen;
+                const trailAlpha = star.alpha * progress * this.#trailAlphaFactor;
+                const trailSize = star.size * progress * this.#scale;
+
+                if (trailAlpha < 0.01) {
+                    continue;
+                }
+
+                const idx = (oldest + t) % trailLen;
+
+                ctx.globalAlpha = trailAlpha;
+                ctx.beginPath();
+                ctx.arc(trail[idx].x, trail[idx].y, trailSize, 0, Math.PI * 2);
+                ctx.fillStyle = `rgb(${cr}, ${cg}, ${cb})`;
+                ctx.fill();
+            }
+
+            const alpha = star.alpha;
+            const headSize = star.size * 2 * this.#scale;
+            const glow = ctx.createRadialGradient(star.x, star.y, 0, star.x, star.y, headSize);
+            glow.addColorStop(0, `rgba(${cr}, ${cg}, ${cb}, ${alpha})`);
+            glow.addColorStop(0.5, `rgba(${cr}, ${cg}, ${cb}, ${alpha * 0.3})`);
+            glow.addColorStop(1, `rgba(${cr}, ${cg}, ${cb}, 0)`);
+
+            ctx.globalAlpha = 1;
+            ctx.beginPath();
+            ctx.arc(star.x, star.y, headSize, 0, Math.PI * 2);
+            ctx.fillStyle = glow;
+            ctx.fill();
+        }
+
+        ctx.globalCompositeOperation = 'source-over';
+        ctx.globalAlpha = 1;
+    }
+
+    #create(width: number, height: number): ShootingStar {
+        const startX = this.#rng() * width * 0.8;
+        const startY = this.#rng() * height * 0.4;
+        const angle = 0.3 + this.#rng() * 0.5;
+        const speed = 8 + this.#rng() * 12;
+
+        return {
+            x: startX,
+            y: startY,
+            vx: Math.cos(angle) * speed * this.#scale,
+            vy: Math.sin(angle) * speed * this.#scale,
+            alpha: this.#alphaMin + this.#rng() * this.#alphaRange,
+            size: 1.5 + this.#rng() * 2,
+            decay: this.#decayMin + this.#rng() * this.#decayRange,
+            trail: [],
+            trailHead: 0
+        };
+    }
+}

package/src/shooting-stars/types.ts

@@ -0,0 +1,11 @@
+export type ShootingStar = {
+    x: number;
+    y: number;
+    vx: number;
+    vy: number;
+    alpha: number;
+    size: number;
+    decay: number;
+    trail: { x: number; y: number }[];
+    trailHead: number;
+};

package/src/simulation-canvas.ts

@@ -0,0 +1,83 @@
+import { LimitedFrameRateCanvas } from './canvas';
+import { applyEdgeFade } from './fade';
+import type { EdgeFade, SimulationLayer } from './layer';
+
+export class SimulationCanvas extends LimitedFrameRateCanvas {
+    readonly #simulation: SimulationLayer;
+    readonly #contextOptions: CanvasRenderingContext2DSettings;
+    #offscreen: HTMLCanvasElement | null = null;
+    #offscreenCtx: CanvasRenderingContext2D | null = null;
+
+    constructor(canvas: HTMLCanvasElement, simulation: SimulationLayer, frameRate: number = 60, options: CanvasRenderingContext2DSettings = {colorSpace: 'display-p3'}) {
+        super(canvas, frameRate, options);
+        this.#simulation = simulation;
+        this.#contextOptions = options;
+
+        canvas.style.position = 'absolute';
+        canvas.style.top = '0';
+        canvas.style.left = '0';
+        canvas.style.height = '100%';
+        canvas.style.width = '100%';
+    }
+
+    withFade(fade: EdgeFade): this {
+        this.#simulation.fade = fade;
+        return this;
+    }
+
+    start(): void {
+        this.#simulation.onMount(this.canvas);
+        super.start();
+    }
+
+    destroy(): void {
+        this.#simulation.onUnmount(this.canvas);
+        super.destroy();
+    }
+
+    draw(): void {
+        this.canvas.height = this.height;
+        this.canvas.width = this.width;
+
+        const ctx = this.context;
+
+        if (this.#simulation.fade) {
+            const offCtx = this.#getOffscreenCtx(this.width, this.height);
+            offCtx.clearRect(0, 0, this.width, this.height);
+            this.#simulation.draw(offCtx, this.width, this.height);
+            applyEdgeFade(offCtx, this.width, this.height, this.#simulation.fade);
+            ctx.drawImage(this.#offscreen!, 0, 0);
+        } else {
+            ctx.save();
+            this.#simulation.draw(ctx, this.width, this.height);
+            ctx.restore();
+        }
+    }
+
+    tick(): void {
+        const dt = (this.delta > 0 && this.delta < 200 ? this.delta / (1000 / 60) : 1) * this.speed * LimitedFrameRateCanvas.globalSpeed;
+        this.#simulation.tick(dt, this.width, this.height);
+    }
+
+    onResize(): void {
+        super.onResize();
+
+        if (this.#offscreen) {
+            this.#offscreen.width = this.width;
+            this.#offscreen.height = this.height;
+        }
+
+        this.#simulation.onResize(this.width, this.height);
+    }
+
+    #getOffscreenCtx(width: number, height: number): CanvasRenderingContext2D {
+        if (!this.#offscreen) {
+            this.#offscreen = document.createElement('canvas');
+            this.#offscreen.width = width;
+            this.#offscreen.height = height;
+            this.#offscreenCtx = this.#offscreen.getContext('2d', this.#contextOptions)!;
+        }
+
+        return this.#offscreenCtx!;
+    }
+}

package/src/snow/consts.ts

@@ -1,3 +1,3 @@
-import { mulberry32 } from '@basmilius/utils';
+import { type Mulberry32, mulberry32 } from '@basmilius/utils';
 
-export const MULBERRY = mulberry32(13);
+export const MULBERRY: Mulberry32 = mulberry32(13);

package/src/snow/index.ts

@@ -1,2 +1,9 @@
-export { SnowSimulation } from './simulation';
-export type { SnowSimulationConfig } from './simulation';
+import { Snow } from './layer';
+import type { SnowConfig } from './layer';
+import type { Effect } from '../effect';
+
+export function createSnow(config?: SnowConfig): Effect<SnowConfig> {
+    return new Snow(config);
+}
+
+export type { SnowConfig };