@basmilius/sparkle 2.1.0 → 2.2.0

package/package.json

@@ -1,12 +1,13 @@
 {
     "name": "@basmilius/sparkle",
     "license": "MIT",
-    "version": "2.1.0",
+    "version": "2.2.0",
     "author": {
         "email": "bas@mili.us",
         "name": "Bas Milius",
         "url": "https://bas.dev"
     },
+    "homepage": "https://sparkle.graphics",
     "repository": {
         "type": "git",
         "url": "https://github.com/basmilius/sparkle.git"
@@ -44,11 +45,14 @@
     },
     "devDependencies": {
         "@types/node": "^25.5.0",
+        "@vitejs/plugin-vue": "^5.2.1",
         "tsdown": "^0.21.4",
         "typescript": "^6.0.2",
         "vite": "^8.0.3",
         "vitepress": "^1.6.3",
         "vitepress-plugin-example": "^1.4.0",
-        "vitepress-plugin-render": "^1.4.0"
+        "vitepress-plugin-render": "^1.4.0",
+        "vue": "^3.5.13",
+        "vue-router": "^4.5.0"
     }
 }

package/src/aurora/index.ts

@@ -1,4 +1,10 @@
-export { AuroraLayer } from './layer';
-export { AuroraSimulation } from './simulation';
-export type { AuroraSimulationConfig } from './simulation';
+import { Aurora } from './layer';
+import type { AuroraConfig } from './layer';
+import type { Effect } from '../effect';
+
+export function createAurora(config?: AuroraConfig): Effect<AuroraConfig> {
+    return new Aurora(config);
+}
+
+export type { AuroraConfig };
 export type { AuroraBand } from './types';

package/src/aurora/layer.ts

@@ -1,21 +1,29 @@
 import { hexToRGB } from '@basmilius/utils';
-import { SimulationLayer } from '../layer';
+import { Effect } from '../effect';
 import { MULBERRY } from './consts';
-import type { AuroraSimulationConfig } from './simulation';
 import type { AuroraBand } from './types';
 
 const DEFAULT_COLORS = ['#9922ff', '#4455ff', '#0077ee', '#00aabb', '#22ddff'];
 const TOP_HUE = 265;
 
-export class AuroraLayer extends SimulationLayer {
-    readonly #speed: number;
-    readonly #intensity: number;
-    readonly #waveAmplitude: number;
-    readonly #verticalPosition: number;
-    #time: number = 0;
+export interface AuroraConfig {
+    readonly bands?: number;
+    readonly colors?: string[];
+    readonly speed?: number;
+    readonly intensity?: number;
+    readonly waveAmplitude?: number;
+    readonly verticalPosition?: number;
+    readonly scale?: number;
+}
+
+export class Aurora extends Effect<AuroraConfig> {
+    #speed: number;
+    #intensity: number;
+    #waveAmplitude: number;
+    #verticalPosition: number;
     #bands: AuroraBand[] = [];
 
-    constructor(config: AuroraSimulationConfig = {}) {
+    constructor(config: AuroraConfig = {}) {
         super();
 
         const bandCount = config.bands ?? 5;
@@ -36,26 +44,39 @@ export class AuroraLayer extends SimulationLayer {
 
             this.#bands.push({
                 x: cluster + (MULBERRY.next() - 0.5) * 0.22,
-                baseY: this.#verticalPosition + (MULBERRY.next() - 0.5) * 0.08,
+                baseY: (MULBERRY.next() - 0.5) * 0.08,
                 height: 0.5 + MULBERRY.next() * 0.3,
                 sigma: 160 + MULBERRY.next() * 110,
                 phase1: MULBERRY.next() * Math.PI * 2,
                 phase2: MULBERRY.next() * Math.PI * 2,
                 amplitude1: 0.015 + MULBERRY.next() * 0.025,
                 frequency1: 0.003 + MULBERRY.next() * 0.004,
-                speed: (0.4 + MULBERRY.next() * 0.6) * this.#speed,
+                speed: 0.4 + MULBERRY.next() * 0.6,
                 hue,
-                opacity: (0.5 + MULBERRY.next() * 0.3) * this.#intensity
+                opacity: 0.5 + MULBERRY.next() * 0.3
             });
         }
     }
 
-    tick(dt: number, width: number, height: number): void {
-        this.#time += 0.016 * dt * this.#speed;
+    configure(config: Partial<AuroraConfig>): void {
+        if (config.speed !== undefined) {
+            this.#speed = config.speed;
+        }
+        if (config.intensity !== undefined) {
+            this.#intensity = config.intensity;
+        }
+        if (config.waveAmplitude !== undefined) {
+            this.#waveAmplitude = config.waveAmplitude;
+        }
+        if (config.verticalPosition !== undefined) {
+            this.#verticalPosition = config.verticalPosition;
+        }
+    }
 
+    tick(dt: number, _width: number, _height: number): void {
         for (const band of this.#bands) {
-            band.phase1 += 0.005 * band.speed * dt;
-            band.phase2 += 0.008 * band.speed * dt;
+            band.phase1 += 0.005 * band.speed * this.#speed * dt;
+            band.phase2 += 0.008 * band.speed * this.#speed * dt;
         }
     }
 
@@ -77,7 +98,7 @@ export class AuroraLayer extends SimulationLayer {
         for (const band of this.#bands) {
             const swayX = band.amplitude1 * width * Math.sin(band.phase1);
             const cx = band.x * width + swayX;
-            const baseY = band.baseY * height;
+            const baseY = (this.#verticalPosition + band.baseY) * height;
             const rayHeight = band.height * height * (height / 800);
             const sigma = band.sigma * scale;
             const cutoff = sigma * 3.5;
@@ -88,6 +109,21 @@ export class AuroraLayer extends SimulationLayer {
             const xStart = Math.max(0, Math.floor((cx - cutoff) / step) * step);
             const xEnd = Math.min(width, Math.ceil((cx + cutoff) / step) * step);
 
+            const centreWave = Math.sin(band.frequency1 * cx + band.phase2) * waveRange;
+            const centreBase = baseY + centreWave;
+            const centreTop = centreBase - rayHeight;
+            const centreFadeBottom = centreBase + rayHeight * 0.1;
+
+            const gradient = ctx.createLinearGradient(0, centreFadeBottom, 0, centreTop);
+            gradient.addColorStop(0, `hsla(${band.hue}, 100%, 90%, 0)`);
+            gradient.addColorStop(0.04, `hsla(${band.hue}, 100%, 90%, 0.55)`);
+            gradient.addColorStop(0.1, `hsla(${band.hue}, 90%, 72%, 1)`);
+            gradient.addColorStop(0.32, `hsla(${band.hue}, 85%, 62%, 0.75)`);
+            gradient.addColorStop(0.62, `hsla(${midHue}, 80%, 56%, 0.35)`);
+            gradient.addColorStop(0.86, `hsla(${TOP_HUE}, 75%, 50%, 0.12)`);
+            gradient.addColorStop(1, `hsla(${TOP_HUE}, 70%, 45%, 0)`);
+            ctx.fillStyle = gradient;
+
             for (let x = xStart; x < xEnd; x += step) {
                 const dx = x - cx;
                 const alpha = Math.exp(-dx * dx / sigmaSq2);
@@ -100,20 +136,12 @@ export class AuroraLayer extends SimulationLayer {
                 const colBase = baseY + waveOffset;
                 const colTop = colBase - rayHeight;
                 const fadeBottom = colBase + rayHeight * 0.1;
-                const eff = alpha * band.opacity;
-
-                const gradient = ctx.createLinearGradient(0, fadeBottom, 0, colTop);
-                gradient.addColorStop(0, `hsla(${band.hue}, 100%, 90%, 0)`);
-                gradient.addColorStop(0.04, `hsla(${band.hue}, 100%, 90%, ${eff * 0.55})`);
-                gradient.addColorStop(0.1, `hsla(${band.hue}, 90%, 72%, ${eff})`);
-                gradient.addColorStop(0.32, `hsla(${band.hue}, 85%, 62%, ${eff * 0.75})`);
-                gradient.addColorStop(0.62, `hsla(${midHue}, 80%, 56%, ${eff * 0.35})`);
-                gradient.addColorStop(0.86, `hsla(${TOP_HUE}, 75%, 50%, ${eff * 0.12})`);
-                gradient.addColorStop(1, `hsla(${TOP_HUE}, 70%, 45%, 0)`);
-
-                ctx.fillStyle = gradient;
+
+                ctx.globalAlpha = alpha * band.opacity * this.#intensity;
                 ctx.fillRect(x, colTop, step, fadeBottom - colTop + 1);
             }
+
+            ctx.globalAlpha = 1;
         }
 
         ctx.globalCompositeOperation = 'source-over';

package/src/balloons/index.ts

@@ -1,6 +1,12 @@
-export { BalloonLayer } from './layer';
+import { Balloons } from './layer';
+import type { BalloonsConfig } from './layer';
+import type { Effect } from '../effect';
+
+export function createBalloons(config?: BalloonsConfig): Effect<BalloonsConfig> {
+    return new Balloons(config);
+}
+
 export { BalloonParticle } from './particle';
-export { BalloonSimulation } from './simulation';
+export type { BalloonsConfig };
 export type { BalloonParticleConfig } from './particle';
-export type { BalloonSimulationConfig } from './simulation';
 export type { Balloon } from './types';

package/src/balloons/layer.ts

@@ -1,23 +1,32 @@
 import { hexToRGB } from '@basmilius/utils';
-import { SimulationLayer } from '../layer';
+import { Effect } from '../effect';
 import { MULBERRY } from './consts';
-import type { BalloonSimulationConfig } from './simulation';
 import type { Balloon } from './types';
 
 const DEFAULT_COLORS = ['#ff4444', '#4488ff', '#44cc44', '#ffcc00', '#ff88cc', '#8844ff'];
 
-export class BalloonLayer extends SimulationLayer {
+export interface BalloonsConfig {
+    readonly count?: number;
+    readonly colors?: string[];
+    readonly sizeRange?: [number, number];
+    readonly speed?: number;
+    readonly driftAmount?: number;
+    readonly stringLength?: number;
+    readonly scale?: number;
+}
+
+export class Balloons extends Effect<BalloonsConfig> {
     readonly #scale: number;
-    readonly #speed: number;
-    readonly #driftAmount: number;
-    readonly #stringLengthMul: number;
+    #speed: number;
+    #driftAmount: number;
+    #stringLengthMul: number;
     readonly #sizeRange: [number, number];
     readonly #colorRGBs: [number, number, number][];
     #maxCount: number;
     #time: number = 0;
     #balloons: Balloon[] = [];
 
-    constructor(config: BalloonSimulationConfig = {}) {
+    constructor(config: BalloonsConfig = {}) {
         super();
 
         this.#scale = config.scale ?? 1;
@@ -39,6 +48,18 @@ export class BalloonLayer extends SimulationLayer {
         }
     }
 
+    configure(config: Partial<BalloonsConfig>): void {
+        if (config.speed !== undefined) {
+            this.#speed = config.speed;
+        }
+        if (config.driftAmount !== undefined) {
+            this.#driftAmount = config.driftAmount;
+        }
+        if (config.stringLength !== undefined) {
+            this.#stringLengthMul = config.stringLength;
+        }
+    }
+
     tick(dt: number, width: number, height: number): void {
         this.#time += 0.015 * dt * this.#speed;
 
@@ -66,10 +87,10 @@ export class BalloonLayer extends SimulationLayer {
             const rx = balloon.radiusX * this.#scale;
             const ry = balloon.radiusY * this.#scale;
             const [r, g, b] = balloon.color;
+            const cos = Math.cos(balloon.rotation);
+            const sin = Math.sin(balloon.rotation);
 
-            ctx.save();
-            ctx.translate(px, py);
-            ctx.rotate(balloon.rotation);
+            ctx.setTransform(cos, sin, -sin, cos, px, py);
 
             const gradient = ctx.createRadialGradient(
                 -rx * 0.3, -ry * 0.3, rx * 0.1,
@@ -99,21 +120,31 @@ export class BalloonLayer extends SimulationLayer {
             ctx.fill();
 
             const stringLen = balloon.stringLength * this.#scale * this.#stringLengthMul;
-            const drift = Math.sin(this.#time * 2 + balloon.driftPhase) * 8 * this.#scale * this.#driftAmount;
+            const knotBaseY = knotY + 5 * this.#scale;
+            const ph = balloon.driftPhase;
+            const fr = balloon.driftFreq;
+            const swingAmt = 10 * this.#scale * this.#driftAmount;
+
+            // Each control point lags further behind the balloon's lateral oscillation,
+            // so the string trails the direction of movement like a real hanging string.
+            const midSwing = Math.sin(this.#time * fr + ph - 0.3) * swingAmt * 0.55;
+            const tipSwing = Math.sin(this.#time * fr + ph - 0.8) * swingAmt;
+            // Subtle high-frequency flutter at the tip for lightness.
+            const flutter = Math.sin(this.#time * fr * 2.5 + ph * 1.4 + 1.8) * 2.5 * this.#scale;
+
             ctx.beginPath();
-            ctx.moveTo(0, knotY + 5 * this.#scale);
-            ctx.quadraticCurveTo(
-                drift,
-                knotY + 5 * this.#scale + stringLen * 0.5,
-                -drift * 0.5,
-                knotY + 5 * this.#scale + stringLen
+            ctx.moveTo(0, knotBaseY);
+            ctx.bezierCurveTo(
+                midSwing * 0.35, knotBaseY + stringLen * 0.3,
+                midSwing + flutter * 0.5, knotBaseY + stringLen * 0.65,
+                tipSwing + flutter, knotBaseY + stringLen
             );
             ctx.strokeStyle = `rgba(${r}, ${g}, ${b}, 0.4)`;
             ctx.lineWidth = 1;
             ctx.stroke();
-
-            ctx.restore();
         }
+
+        ctx.resetTransform();
     }
 
     #createBalloon(initialSpread: boolean): Balloon {

package/src/bubbles/index.ts

@@ -1,4 +1,10 @@
-export { BubbleLayer } from './layer';
-export { BubbleSimulation } from './simulation';
-export type { BubbleSimulationConfig } from './simulation';
+import { Bubbles } from './layer';
+import type { BubblesConfig } from './layer';
+import type { Effect } from '../effect';
+
+export function createBubbles(config?: BubblesConfig): Effect<BubblesConfig> {
+    return new Bubbles(config);
+}
+
+export type { BubblesConfig };
 export type { Bubble, PopParticle } from './types';

package/src/bubbles/layer.ts

@@ -1,15 +1,26 @@
-import { SimulationLayer } from '../layer';
+import { parseColor } from '../color';
+import { Effect } from '../effect';
 import { MULBERRY } from './consts';
-import type { BubbleSimulationConfig } from './simulation';
 import type { Bubble, PopParticle } from './types';
 
 const DEFAULT_COLORS = ['#88ccff', '#aaddff', '#ccbbff'];
 
-export class BubbleLayer extends SimulationLayer {
+export interface BubblesConfig {
+    readonly count?: number;
+    readonly sizeRange?: [number, number];
+    readonly speed?: number;
+    readonly popOnClick?: boolean;
+    readonly popRadius?: number;
+    readonly colors?: string[];
+    readonly wobbleAmount?: number;
+    readonly scale?: number;
+}
+
+export class Bubbles extends Effect<BubblesConfig> {
     readonly #scale: number;
-    readonly #speed: number;
+    #speed: number;
     readonly #sizeRange: [number, number];
-    readonly #wobbleAmount: number;
+    #wobbleAmount: number;
     readonly #popOnClick: boolean;
     readonly #popRadius: number;
     readonly #baseHues: number[];
@@ -20,7 +31,7 @@ export class BubbleLayer extends SimulationLayer {
     #popParticles: PopParticle[] = [];
     #canvas: HTMLCanvasElement | null = null;
 
-    constructor(config: BubbleSimulationConfig = {}) {
+    constructor(config: BubblesConfig = {}) {
         super();
 
         this.#scale = config.scale ?? 1;
@@ -58,6 +69,15 @@ export class BubbleLayer extends SimulationLayer {
         this.#canvas = null;
     }
 
+    configure(config: Partial<BubblesConfig>): void {
+        if (config.speed !== undefined) {
+            this.#speed = config.speed;
+        }
+        if (config.wobbleAmount !== undefined) {
+            this.#wobbleAmount = config.wobbleAmount;
+        }
+    }
+
     tick(dt: number, width: number, height: number): void {
         this.#time += 0.01 * dt;
 
@@ -193,17 +213,10 @@ export class BubbleLayer extends SimulationLayer {
     }
 
     #colorToHue(color: string): number {
-        const canvas = document.createElement('canvas');
-        canvas.width = 1;
-        canvas.height = 1;
-        const ctx = canvas.getContext('2d')!;
-        ctx.fillStyle = color;
-        ctx.fillRect(0, 0, 1, 1);
-        const data = ctx.getImageData(0, 0, 1, 1).data;
-
-        let r = data[0] / 255;
-        let g = data[1] / 255;
-        let b = data[2] / 255;
+        const {r: r255, g: g255, b: b255} = parseColor(color);
+        let r = r255 / 255;
+        let g = g255 / 255;
+        let b = b255 / 255;
         const max = Math.max(r, g, b);
         const min = Math.min(r, g, b);
         const delta = max - min;

package/src/canvas.ts

@@ -120,6 +120,18 @@ export class LimitedFrameRateCanvas {
         cancelAnimationFrame(this.#frame);
     }
 
+    pause(): void {
+        this.#isStopped = true;
+        cancelAnimationFrame(this.#frame);
+    }
+
+    resume(): void {
+        if (this.#isStopped) {
+            this.#isStopped = false;
+            this.#frame = requestAnimationFrame(this.loop.bind(this));
+        }
+    }
+
     draw(): void {
         throw new Error('LimitedFrameRateCanvas::draw() should be overwritten.');
     }

package/src/color.ts

@@ -1,4 +1,11 @@
-export function parseColor(fillStyle: string): {r: number; g: number; b: number; a: number} {
+const cache = new Map<string, { r: number; g: number; b: number; a: number }>();
+
+export function parseColor(fillStyle: string): { r: number; g: number; b: number; a: number } {
+    const cached = cache.get(fillStyle);
+    if (cached) {
+        return cached;
+    }
+
     const canvas = document.createElement('canvas');
     canvas.width = 1;
     canvas.height = 1;
@@ -6,5 +13,7 @@ export function parseColor(fillStyle: string): {r: number; g: number; b: number;
     ctx.fillStyle = fillStyle;
     ctx.fillRect(0, 0, 1, 1);
     const data = ctx.getImageData(0, 0, 1, 1).data;
-    return {r: data[0], g: data[1], b: data[2], a: data[3] / 255};
+    const result = {r: data[0], g: data[1], b: data[2], a: data[3] / 255};
+    cache.set(fillStyle, result);
+    return result;
 }

package/src/confetti/index.ts

@@ -1,8 +1,20 @@
-export { ConfettiLayer } from './layer';
+import { Confetti } from './layer';
+import type { ConfettiConfig } from './layer';
+import type { Config as ConfettiBurstConfig } from './types';
+import type { Effect } from '../effect';
+
+export interface ConfettiInstance extends Effect<ConfettiConfig> {
+    burst(config: Partial<ConfettiBurstConfig>): void;
+}
+
+export function createConfetti(config?: ConfettiConfig): ConfettiInstance {
+    return new Confetti(config) as ConfettiInstance;
+}
+
 export { ConfettiParticle } from './particle';
-export { ConfettiSimulation } from './simulation';
 export { PALETTES } from './consts';
 export { SHAPE_PATHS } from './shapes';
+export type { ConfettiConfig };
+export type { ConfettiBurstConfig };
 export type { ConfettiParticleConfig } from './particle';
-export type { ConfettiSimulationConfig } from './simulation';
 export type { Palette, Shape as ConfettiShape } from './types';

package/src/confetti/layer.ts

@@ -1,20 +1,23 @@
 import { hexToRGB } from '@basmilius/utils';
-import { SimulationLayer } from '../layer';
+import { Effect } from '../effect';
 import { DEFAULT_CONFIG, MULBERRY, PALETTES } from './consts';
 import { SHAPE_PATHS } from './shapes';
-import type { ConfettiSimulationConfig } from './simulation';
 import type { Config, Particle, ParticleConfig } from './types';
 
 const TWO_PI = Math.PI * 2;
 
-export class ConfettiLayer extends SimulationLayer {
+export interface ConfettiConfig {
+    readonly scale?: number;
+}
+
+export class Confetti extends Effect<ConfettiConfig> {
     readonly #scale: number;
     #particles: Particle[] = [];
     #width: number = 0;
     #height: number = 0;
     #isFiring: boolean = false;
 
-    constructor(config: ConfettiSimulationConfig = {}) {
+    constructor(config: ConfettiConfig = {}) {
         super();
         this.#scale = config.scale ?? 1;
     }
@@ -24,7 +27,7 @@ export class ConfettiLayer extends SimulationLayer {
         this.#height = height;
     }
 
-    fire(config: Partial<Config>): void {
+    burst(config: Partial<Config>): void {
         const width = this.#width;
         const height = this.#height;
 

package/src/confetti/particle.ts

@@ -1,4 +1,5 @@
 import type { Point } from '../point';
+import { MULBERRY } from './consts';
 import { SHAPE_PATHS } from './shapes';
 import type { Shape } from './types';
 
@@ -47,29 +48,29 @@ export class ConfettiParticle {
         const startVelocity = (config.startVelocity ?? 45) * scale;
         const launchAngle = -(direction * Math.PI / 180)
             + (0.5 * spread * Math.PI / 180)
-            - (Math.random() * spread * Math.PI / 180);
-        const speed = startVelocity * (0.5 + Math.random());
-        const rotAngle = Math.random() * Math.PI * 2;
+            - (MULBERRY.next() * spread * Math.PI / 180);
+        const speed = startVelocity * (0.5 + MULBERRY.next());
+        const rotAngle = MULBERRY.next() * Math.PI * 2;
 
         this.#colorStr = color;
         this.#gravity = (config.gravity ?? 1) * scale;
         this.#shape = shape;
-        this.#size = (5 + Math.random() * 5) * scale;
+        this.#size = (5 + MULBERRY.next() * 5) * scale;
         this.#totalTicks = config.ticks ?? 200;
         this.#x = position.x;
         this.#y = position.y;
         this.#vx = Math.cos(launchAngle) * speed;
         this.#vy = Math.sin(launchAngle) * speed;
-        this.#decay = (config.decay ?? 0.9) - 0.05 + Math.random() * 0.1;
-        this.#flipAngle = Math.random() * Math.PI * 2;
-        this.#flipSpeed = 0.03 + Math.random() * 0.05;
+        this.#decay = (config.decay ?? 0.9) - 0.05 + MULBERRY.next() * 0.1;
+        this.#flipAngle = MULBERRY.next() * Math.PI * 2;
+        this.#flipSpeed = 0.03 + MULBERRY.next() * 0.05;
         this.#rotAngle = rotAngle;
         this.#rotCos = Math.cos(rotAngle);
         this.#rotSin = Math.sin(rotAngle);
-        this.#rotSpeed = (Math.random() - 0.5) * 0.06;
-        this.#swing = Math.random() * Math.PI * 2;
-        this.#swingAmp = 0.5 + Math.random() * 1.5;
-        this.#swingSpeed = 0.025 + Math.random() * 0.035;
+        this.#rotSpeed = (MULBERRY.next() - 0.5) * 0.06;
+        this.#swing = MULBERRY.next() * Math.PI * 2;
+        this.#swingAmp = 0.5 + MULBERRY.next() * 1.5;
+        this.#swingSpeed = 0.025 + MULBERRY.next() * 0.035;
     }
 
     draw(ctx: CanvasRenderingContext2D): void {

package/src/donuts/consts.ts

@@ -1,9 +1,9 @@
 import { type Mulberry32, mulberry32 } from '@basmilius/utils';
-import type { DonutSimulationConfig } from './simulation';
+import type { DonutsConfig } from './layer';
 
 export const MULBERRY: Mulberry32 = mulberry32(13);
 
-export const DEFAULT_CONFIG: DonutSimulationConfig = {
+export const DEFAULT_CONFIG: DonutsConfig = {
     background: '#a51955',
     collisionPadding: 20,
     colors: ['#bd1961', '#da287c'],

package/src/donuts/index.ts

@@ -1,3 +1,9 @@
-export { DonutLayer } from './layer';
-export { DonutSimulation } from './simulation';
-export type { DonutSimulationConfig } from './simulation';
+import { Donuts } from './layer';
+import type { DonutsConfig } from './layer';
+import type { Effect } from '../effect';
+
+export function createDonuts(config?: DonutsConfig): Effect<DonutsConfig> {
+    return new Donuts(config);
+}
+
+export type { DonutsConfig };