@basmilius/sparkle 2.0.0 → 2.2.0

package/package.json

@@ -1,12 +1,13 @@
 {
     "name": "@basmilius/sparkle",
     "license": "MIT",
-    "version": "2.0.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"
@@ -43,11 +44,15 @@
         "@basmilius/utils": "^3.15.0"
     },
     "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/consts.ts

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

package/src/aurora/index.ts

@@ -0,0 +1,10 @@
+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

@@ -0,0 +1,180 @@
+import { hexToRGB } from '@basmilius/utils';
+import { Effect } from '../effect';
+import { MULBERRY } from './consts';
+import type { AuroraBand } from './types';
+
+const DEFAULT_COLORS = ['#9922ff', '#4455ff', '#0077ee', '#00aabb', '#22ddff'];
+const TOP_HUE = 265;
+
+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: AuroraConfig = {}) {
+        super();
+
+        const bandCount = config.bands ?? 5;
+        const colors = config.colors ?? DEFAULT_COLORS;
+        this.#speed = config.speed ?? 1;
+        this.#intensity = config.intensity ?? 0.8;
+        this.#waveAmplitude = config.waveAmplitude ?? 1;
+        this.#verticalPosition = config.verticalPosition ?? 0.68;
+
+        // Two loose clusters (left + right), rays within each cluster overlap into a whole
+        const clusterCenters = [0.35, 0.65];
+
+        for (let i = 0; i < bandCount; i++) {
+            const color = colors[i % colors.length];
+            const [r, g, b] = hexToRGB(color);
+            const hue = this.#rgbToHue(r, g, b);
+            const cluster = clusterCenters[i % clusterCenters.length];
+
+            this.#bands.push({
+                x: cluster + (MULBERRY.next() - 0.5) * 0.22,
+                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,
+                hue,
+                opacity: 0.5 + MULBERRY.next() * 0.3
+            });
+        }
+    }
+
+    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 * this.#speed * dt;
+            band.phase2 += 0.008 * band.speed * this.#speed * dt;
+        }
+    }
+
+    draw(ctx: CanvasRenderingContext2D, width: number, height: number): void {
+        // Dark sky background gradient
+        const bg = ctx.createLinearGradient(0, 0, 0, height);
+        bg.addColorStop(0, '#000000');
+        bg.addColorStop(0.5, '#050012');
+        bg.addColorStop(1, '#0a0025');
+        ctx.fillStyle = bg;
+        ctx.fillRect(0, 0, width, height);
+
+        // Aurora curtain rays — vertical bands with Gaussian horizontal falloff
+        ctx.globalCompositeOperation = 'screen';
+
+        const step = 4;
+        const scale = width / 1920;
+
+        for (const band of this.#bands) {
+            const swayX = band.amplitude1 * width * Math.sin(band.phase1);
+            const cx = band.x * width + swayX;
+            const baseY = (this.#verticalPosition + band.baseY) * height;
+            const rayHeight = band.height * height * (height / 800);
+            const sigma = band.sigma * scale;
+            const cutoff = sigma * 3.5;
+            const sigmaSq2 = 2 * sigma * sigma;
+            const midHue = (band.hue + TOP_HUE) / 2;
+            const waveRange = height * 0.035 * this.#waveAmplitude;
+
+            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);
+
+                if (alpha < 0.015) {
+                    continue;
+                }
+
+                const waveOffset = Math.sin(band.frequency1 * x + band.phase2) * waveRange;
+                const colBase = baseY + waveOffset;
+                const colTop = colBase - rayHeight;
+                const fadeBottom = colBase + rayHeight * 0.1;
+
+                ctx.globalAlpha = alpha * band.opacity * this.#intensity;
+                ctx.fillRect(x, colTop, step, fadeBottom - colTop + 1);
+            }
+
+            ctx.globalAlpha = 1;
+        }
+
+        ctx.globalCompositeOperation = 'source-over';
+    }
+
+    #rgbToHue(r: number, g: number, b: number): number {
+        r /= 255;
+        g /= 255;
+        b /= 255;
+        const max = Math.max(r, g, b);
+        const min = Math.min(r, g, b);
+        const delta = max - min;
+
+        if (delta === 0) {
+            return 0;
+        }
+
+        let hue: number;
+
+        if (max === r) {
+            hue = ((g - b) / delta) % 6;
+        } else if (max === g) {
+            hue = (b - r) / delta + 2;
+        } else {
+            hue = (r - g) / delta + 4;
+        }
+
+        hue = Math.round(hue * 60);
+
+        if (hue < 0) {
+            hue += 360;
+        }
+
+        return hue;
+    }
+}

package/src/aurora/types.ts

@@ -0,0 +1,13 @@
+export type AuroraBand = {
+    x: number;
+    baseY: number;
+    height: number;
+    sigma: number;
+    phase1: number;
+    phase2: number;
+    amplitude1: number;
+    frequency1: number;
+    speed: number;
+    hue: number;
+    opacity: number;
+};

package/src/balloons/consts.ts

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

package/src/balloons/index.ts

@@ -0,0 +1,12 @@
+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 type { BalloonsConfig };
+export type { BalloonParticleConfig } from './particle';
+export type { Balloon } from './types';

package/src/balloons/layer.ts

@@ -0,0 +1,169 @@
+import { hexToRGB } from '@basmilius/utils';
+import { Effect } from '../effect';
+import { MULBERRY } from './consts';
+import type { Balloon } from './types';
+
+const DEFAULT_COLORS = ['#ff4444', '#4488ff', '#44cc44', '#ffcc00', '#ff88cc', '#8844ff'];
+
+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;
+    #speed: number;
+    #driftAmount: number;
+    #stringLengthMul: number;
+    readonly #sizeRange: [number, number];
+    readonly #colorRGBs: [number, number, number][];
+    #maxCount: number;
+    #time: number = 0;
+    #balloons: Balloon[] = [];
+
+    constructor(config: BalloonsConfig = {}) {
+        super();
+
+        this.#scale = config.scale ?? 1;
+        this.#maxCount = config.count ?? 15;
+        this.#sizeRange = config.sizeRange ?? [25, 45];
+        this.#speed = config.speed ?? 1;
+        this.#driftAmount = config.driftAmount ?? 1;
+        this.#stringLengthMul = config.stringLength ?? 1;
+
+        const colors = config.colors ?? DEFAULT_COLORS;
+        this.#colorRGBs = colors.map(c => hexToRGB(c));
+
+        if (innerWidth < 991) {
+            this.#maxCount = Math.floor(this.#maxCount / 2);
+        }
+
+        for (let i = 0; i < this.#maxCount; ++i) {
+            this.#balloons.push(this.#createBalloon(true));
+        }
+    }
+
+    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;
+
+        for (let i = 0; i < this.#balloons.length; i++) {
+            const balloon = this.#balloons[i];
+
+            balloon.y -= (balloon.riseSpeed * this.#speed * dt) / (height * 1.2);
+
+            const drift = Math.sin(this.#time * balloon.driftFreq + balloon.driftPhase) * balloon.driftAmp * this.#driftAmount;
+            balloon.x += drift * dt / (width * 5);
+
+            balloon.rotation = Math.sin(this.#time * balloon.rotationSpeed + balloon.driftPhase) * 0.08;
+
+            if (balloon.y < -0.2) {
+                this.#balloons[i] = this.#createBalloon(false);
+            }
+        }
+    }
+
+    draw(ctx: CanvasRenderingContext2D, width: number, height: number): void {
+
+        for (const balloon of this.#balloons) {
+            const px = balloon.x * width;
+            const py = balloon.y * height;
+            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.setTransform(cos, sin, -sin, cos, px, py);
+
+            const gradient = ctx.createRadialGradient(
+                -rx * 0.3, -ry * 0.3, rx * 0.1,
+                0, 0, Math.max(rx, ry)
+            );
+            gradient.addColorStop(0, `rgba(${Math.min(255, r + 80)}, ${Math.min(255, g + 80)}, ${Math.min(255, b + 80)}, 0.95)`);
+            gradient.addColorStop(0.6, `rgba(${r}, ${g}, ${b}, 0.9)`);
+            gradient.addColorStop(1, `rgba(${Math.max(0, r - 40)}, ${Math.max(0, g - 40)}, ${Math.max(0, b - 40)}, 0.85)`);
+
+            ctx.beginPath();
+            ctx.ellipse(0, 0, rx, ry, 0, 0, Math.PI * 2);
+            ctx.fillStyle = gradient;
+            ctx.fill();
+
+            ctx.beginPath();
+            ctx.ellipse(-rx * 0.25, -ry * 0.3, rx * 0.2, ry * 0.15, -0.3, 0, Math.PI * 2);
+            ctx.fillStyle = `rgba(255, 255, 255, 0.35)`;
+            ctx.fill();
+
+            const knotY = ry + 2 * this.#scale;
+            ctx.beginPath();
+            ctx.moveTo(-3 * this.#scale, knotY);
+            ctx.lineTo(0, knotY + 5 * this.#scale);
+            ctx.lineTo(3 * this.#scale, knotY);
+            ctx.closePath();
+            ctx.fillStyle = `rgba(${Math.max(0, r - 30)}, ${Math.max(0, g - 30)}, ${Math.max(0, b - 30)}, 0.9)`;
+            ctx.fill();
+
+            const stringLen = balloon.stringLength * this.#scale * this.#stringLengthMul;
+            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, 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.resetTransform();
+    }
+
+    #createBalloon(initialSpread: boolean): Balloon {
+        const colorIndex = Math.floor(MULBERRY.next() * this.#colorRGBs.length);
+        const baseRadius = this.#sizeRange[0] + MULBERRY.next() * (this.#sizeRange[1] - this.#sizeRange[0]);
+
+        return {
+            x: 0.1 + MULBERRY.next() * 0.8,
+            y: initialSpread ? MULBERRY.next() * 1.2 : 1.2 + MULBERRY.next() * 0.2,
+            radiusX: baseRadius * 0.85,
+            radiusY: baseRadius,
+            color: this.#colorRGBs[colorIndex],
+            driftPhase: MULBERRY.next() * Math.PI * 2,
+            driftFreq: 0.5 + MULBERRY.next() * 1,
+            driftAmp: 0.3 + MULBERRY.next() * 0.7,
+            riseSpeed: 0.3 + MULBERRY.next() * 0.7,
+            rotation: 0,
+            rotationSpeed: 0.5 + MULBERRY.next() * 1.5,
+            stringLength: 30 + MULBERRY.next() * 40
+        };
+    }
+}

package/src/balloons/particle.ts

@@ -0,0 +1,110 @@
+import type { Point } from '../point';
+
+export interface BalloonParticleConfig {
+    readonly driftAmp?: number;
+    readonly driftFreq?: number;
+    readonly driftPhase?: number;
+    readonly radiusX?: number;
+    readonly radiusY?: number;
+    readonly riseSpeed?: number;
+    readonly rotationSpeed?: number;
+    readonly scale?: number;
+    readonly stringLength?: number;
+}
+
+export class BalloonParticle {
+    readonly #color: [number, number, number];
+    readonly #driftAmp: number;
+    readonly #driftFreq: number;
+    readonly #driftPhase: number;
+    readonly #radiusX: number;
+    readonly #radiusY: number;
+    readonly #riseSpeed: number;
+    readonly #rotationSpeed: number;
+    readonly #scale: number;
+    readonly #stringLength: number;
+    #x: number;
+    #y: number;
+    #rotation: number = 0;
+    #time: number = 0;
+
+    get isDone(): boolean {
+        return this.#y < -(this.#radiusY * 2 + this.#stringLength);
+    }
+
+    get position(): Point {
+        return {x: this.#x, y: this.#y};
+    }
+
+    constructor(position: Point, color: [number, number, number], config: BalloonParticleConfig = {}) {
+        this.#x = position.x;
+        this.#y = position.y;
+        this.#color = color;
+        this.#driftAmp = config.driftAmp ?? (0.3 + Math.random() * 0.7);
+        this.#driftFreq = config.driftFreq ?? (0.5 + Math.random() * 1);
+        this.#driftPhase = config.driftPhase ?? (Math.random() * Math.PI * 2);
+        this.#radiusX = (config.radiusX ?? (25 + Math.random() * 20)) * (config.scale ?? 1);
+        this.#radiusY = (config.radiusY ?? (config.radiusX ? config.radiusX * (1 / 0.85) : 30 + Math.random() * 23)) * (config.scale ?? 1);
+        this.#riseSpeed = config.riseSpeed ?? (0.5 + Math.random() * 0.8);
+        this.#rotationSpeed = config.rotationSpeed ?? (0.5 + Math.random() * 1.5);
+        this.#scale = config.scale ?? 1;
+        this.#stringLength = (config.stringLength ?? (30 + Math.random() * 40)) * this.#scale;
+    }
+
+    draw(ctx: CanvasRenderingContext2D): void {
+        const [r, g, b] = this.#color;
+        const rx = this.#radiusX;
+        const ry = this.#radiusY;
+
+        ctx.save();
+        ctx.translate(this.#x, this.#y);
+        ctx.rotate(this.#rotation);
+
+        const gradient = ctx.createRadialGradient(-rx * 0.3, -ry * 0.3, rx * 0.1, 0, 0, Math.max(rx, ry));
+        gradient.addColorStop(0, `rgba(${Math.min(255, r + 80)}, ${Math.min(255, g + 80)}, ${Math.min(255, b + 80)}, 0.95)`);
+        gradient.addColorStop(0.6, `rgba(${r}, ${g}, ${b}, 0.9)`);
+        gradient.addColorStop(1, `rgba(${Math.max(0, r - 40)}, ${Math.max(0, g - 40)}, ${Math.max(0, b - 40)}, 0.85)`);
+
+        ctx.beginPath();
+        ctx.ellipse(0, 0, rx, ry, 0, 0, Math.PI * 2);
+        ctx.fillStyle = gradient;
+        ctx.fill();
+
+        ctx.beginPath();
+        ctx.ellipse(-rx * 0.25, -ry * 0.3, rx * 0.2, ry * 0.15, -0.3, 0, Math.PI * 2);
+        ctx.fillStyle = 'rgba(255, 255, 255, 0.35)';
+        ctx.fill();
+
+        const knotY = ry + 2 * this.#scale;
+        ctx.beginPath();
+        ctx.moveTo(-3 * this.#scale, knotY);
+        ctx.lineTo(0, knotY + 5 * this.#scale);
+        ctx.lineTo(3 * this.#scale, knotY);
+        ctx.closePath();
+        ctx.fillStyle = `rgba(${Math.max(0, r - 30)}, ${Math.max(0, g - 30)}, ${Math.max(0, b - 30)}, 0.9)`;
+        ctx.fill();
+
+        const stringDrift = Math.sin(this.#time * 2 + this.#driftPhase) * 8 * this.#scale;
+        ctx.beginPath();
+        ctx.moveTo(0, knotY + 5 * this.#scale);
+        ctx.quadraticCurveTo(
+            stringDrift,
+            knotY + 5 * this.#scale + this.#stringLength * 0.5,
+            -stringDrift * 0.5,
+            knotY + 5 * this.#scale + this.#stringLength
+        );
+        ctx.strokeStyle = `rgba(${r}, ${g}, ${b}, 0.4)`;
+        ctx.lineWidth = 1;
+        ctx.stroke();
+
+        ctx.restore();
+    }
+
+    tick(dt: number = 1): void {
+        this.#time += 0.015 * dt;
+
+        this.#y -= this.#riseSpeed * dt;
+        this.#x += Math.sin(this.#time * this.#driftFreq + this.#driftPhase) * this.#driftAmp * dt;
+        this.#rotation = Math.sin(this.#time * this.#rotationSpeed + this.#driftPhase) * 0.08;
+    }
+}

package/src/balloons/types.ts

@@ -0,0 +1,14 @@
+export type Balloon = {
+    x: number;
+    y: number;
+    radiusX: number;
+    radiusY: number;
+    color: [number, number, number];
+    driftPhase: number;
+    driftFreq: number;
+    driftAmp: number;
+    riseSpeed: number;
+    rotation: number;
+    rotationSpeed: number;
+    stringLength: number;
+};

package/src/bubbles/consts.ts

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

package/src/bubbles/index.ts

@@ -0,0 +1,10 @@
+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';