fireworks-engine 1.0.0

package/src/runtimeCapabilities.js

@@ -0,0 +1,7 @@
+export function prefersReducedMotion() {
+    if (typeof window === 'undefined' || typeof window.matchMedia !== 'function') {
+        return false;
+    }
+
+    return window.matchMedia('(prefers-reduced-motion: reduce)').matches;
+}

package/src/runtimeLifecycle.js

@@ -0,0 +1,330 @@
+import { prefersReducedMotion as defaultPrefersReducedMotion } from './runtimeCapabilities.js';
+
+const HIDDEN_DOCUMENT_TIMEOUT_RETRY_MS = 250;
+
+function resolveEngineRef(value, fallback) {
+    if (value !== undefined) {
+        return value;
+    }
+
+    if (fallback !== undefined) {
+        return fallback;
+    }
+
+    return null;
+}
+
+function resolveFrameFunction(engine, refKey, methodName) {
+    const engineFn = engine[refKey];
+    if (typeof engineFn === 'function') {
+        return engineFn;
+    }
+
+    const win = getWindow(engine);
+    const winFn = win?.[methodName];
+    if (typeof winFn === 'function') {
+        return winFn.bind(win);
+    }
+
+    const globalFn = globalThis[methodName];
+    if (typeof globalFn === 'function') {
+        return globalFn.bind(globalThis);
+    }
+
+    return null;
+}
+
+export function getDocument(engine) {
+    return resolveEngineRef(engine.documentRef, globalThis.document);
+}
+
+export function getWindow(engine) {
+    return resolveEngineRef(engine.windowRef, globalThis.window);
+}
+
+export function getRequestAnimationFrame(engine) {
+    return resolveFrameFunction(engine, 'requestAnimationFrameRef', 'requestAnimationFrame');
+}
+
+export function getCancelAnimationFrame(engine) {
+    return resolveFrameFunction(engine, 'cancelAnimationFrameRef', 'cancelAnimationFrame');
+}
+
+
+export function getNow(engine) {
+    const nowRef = engine.nowRef;
+    if (typeof nowRef === 'function') {
+        return nowRef();
+    }
+
+    const performanceNow = globalThis.performance?.now;
+    if (typeof performanceNow === 'function') {
+        return performanceNow.call(globalThis.performance);
+    }
+
+    return Date.now();
+}
+
+export function isDocumentHidden(engine) {
+    const doc = getDocument(engine);
+    return doc?.hidden === true || doc?.visibilityState === 'hidden';
+}
+
+export function shouldReduceMotion(engine) {
+    if (typeof engine.prefersReducedMotionRef === 'function') {
+        return !!engine.prefersReducedMotionRef();
+    }
+
+    return defaultPrefersReducedMotion();
+}
+
+export function resolveRoot(engine) {
+    const doc = getDocument(engine);
+
+    if (typeof engine.rootRef === 'function') {
+        return engine.rootRef({ document: doc, window: getWindow(engine) }) || null;
+    }
+
+    if (engine.rootRef) {
+        return engine.rootRef;
+    }
+
+    return doc?.body || doc?.documentElement || null;
+}
+
+export function usesElementScopedCanvas(engine) {
+    const doc = getDocument(engine);
+    const root = resolveRoot(engine);
+    return !!root && root !== doc?.body && root !== doc?.documentElement;
+}
+
+export function addResizeListener(engine) {
+    if (engine.hasResizeListener) {
+        return;
+    }
+
+    const win = getWindow(engine);
+    if (typeof win?.addEventListener !== 'function') {
+        return;
+    }
+
+    win.addEventListener('resize', engine.resize, { passive: true });
+    engine.hasResizeListener = true;
+}
+
+export function removeResizeListener(engine) {
+    if (!engine.hasResizeListener) {
+        return;
+    }
+
+    const win = getWindow(engine);
+    win?.removeEventListener?.('resize', engine.resize);
+    engine.hasResizeListener = false;
+}
+
+export function addResizeObserver(engine) {
+    if (engine.hasResizeObserver) {
+        return true;
+    }
+
+    const ResizeObserverCtor = globalThis.ResizeObserver;
+    if (typeof ResizeObserverCtor !== 'function') {
+        return false;
+    }
+
+    const root = resolveRoot(engine);
+    if (!root || typeof root.nodeType !== 'number') {
+        return false;
+    }
+
+    const observer = new ResizeObserverCtor(() => {
+        if (engine.canvas && engine.ctx) {
+            engine.resize();
+        }
+    });
+
+    observer.observe(root);
+    engine.resizeObserver = observer;
+    engine.hasResizeObserver = true;
+    return true;
+}
+
+export function removeResizeObserver(engine) {
+    if (!engine.hasResizeObserver) {
+        return;
+    }
+
+    engine.resizeObserver?.disconnect?.();
+    engine.resizeObserver = null;
+    engine.hasResizeObserver = false;
+}
+
+export function scheduleTimeout(engine, callback, delay = 0) {
+    const schedule = typeof engine.setTimeoutRef === 'function' ? engine.setTimeoutRef : setTimeout;
+
+    let timeoutId = null;
+    const runWhenVisible = () => {
+        if (timeoutId !== null) {
+            engine.timeoutIds.delete(timeoutId);
+        }
+
+        if (isDocumentHidden(engine)) {
+            timeoutId = schedule(runWhenVisible, HIDDEN_DOCUMENT_TIMEOUT_RETRY_MS);
+            engine.timeoutIds.add(timeoutId);
+            return;
+        }
+
+        callback();
+    };
+
+    timeoutId = schedule(runWhenVisible, delay);
+
+    engine.timeoutIds.add(timeoutId);
+    return timeoutId;
+}
+
+export function resolveScaledDelay(engine, delay = 0) {
+    const baseDelay = Number.isFinite(delay) ? Math.max(0, delay) : 0;
+    const timeScale = Number.isFinite(engine.timeScale) && engine.timeScale > 0
+        ? engine.timeScale
+        : 1;
+    return baseDelay / timeScale;
+}
+
+export function clearScheduledTimeouts(engine) {
+    const clear = typeof engine.clearTimeoutRef === 'function' ? engine.clearTimeoutRef : clearTimeout;
+    engine.timeoutIds.forEach((timeoutId) => {
+        clear(timeoutId);
+    });
+    engine.timeoutIds.clear();
+}
+
+export function clearPendingStart(engine) {
+    if (engine.hasDomReadyListener) {
+        getDocument(engine)?.removeEventListener?.('DOMContentLoaded', engine.handleDOMContentLoaded);
+    }
+    engine.hasDomReadyListener = false;
+    engine.pendingStartConfig = null;
+}
+
+export function handleDOMContentLoaded(engine) {
+    engine.hasDomReadyListener = false;
+    const nextConfig = engine.pendingStartConfig;
+    engine.pendingStartConfig = null;
+
+    if (nextConfig) {
+        engine.start(nextConfig);
+    }
+}
+
+export function schedulePendingStart(engine, config) {
+    const doc = getDocument(engine);
+    engine.pendingStartConfig = config;
+
+    if (doc?.readyState !== 'loading' || engine.hasDomReadyListener) {
+        return false;
+    }
+
+    doc.addEventListener('DOMContentLoaded', engine.handleDOMContentLoaded, { once: true });
+    engine.hasDomReadyListener = true;
+    return true;
+}
+
+export function ensureCanvas(engine) {
+    if (engine.canvas && engine.ctx) {
+        return true;
+    }
+
+    const doc = getDocument(engine);
+    const root = resolveRoot(engine);
+    if (!doc || !root || typeof doc.createElement !== 'function' || typeof root.appendChild !== 'function') {
+        return false;
+    }
+
+    const canvas = doc.createElement('canvas');
+    const ctx = canvas.getContext?.('2d', { alpha: true });
+    if (!ctx) {
+        return false;
+    }
+
+    if (usesElementScopedCanvas(engine)) {
+        canvas.style.position = 'absolute';
+        canvas.style.inset = '0';
+        canvas.style.width = '100%';
+        canvas.style.height = '100%';
+    } else {
+        canvas.style.position = 'fixed';
+        canvas.style.left = '0';
+        canvas.style.top = '0';
+        canvas.style.width = '100vw';
+        canvas.style.height = '100vh';
+    }
+
+    canvas.style.pointerEvents = 'none';
+    canvas.style.zIndex = String(engine.canvasZIndex);
+    canvas.style.display = 'none';
+
+    root.appendChild(canvas);
+
+    engine.canvas = canvas;
+    engine.ctx = ctx;
+    if (usesElementScopedCanvas(engine)) {
+        if (!addResizeObserver(engine)) {
+            addResizeListener(engine);
+        }
+    } else {
+        addResizeListener(engine);
+    }
+    resizeCanvas(engine);
+
+    return true;
+}
+
+export function startLoop(engine) {
+    if (!engine.canvas) {
+        return false;
+    }
+
+    const requestAnimationFrameFn = getRequestAnimationFrame(engine);
+    if (typeof requestAnimationFrameFn !== 'function') {
+        return false;
+    }
+
+    engine.canvas.style.display = 'block';
+
+    if (engine.running) {
+        return true;
+    }
+
+    clearPendingStart(engine);
+    engine.running = true;
+    engine.lastTime = getNow(engine);
+    engine.rafId = requestAnimationFrameFn(engine.loopFrame);
+    return true;
+}
+
+export function resizeCanvas(engine) {
+    if (!engine.canvas || !engine.ctx) {
+        return;
+    }
+
+    const win = getWindow(engine);
+    const doc = getDocument(engine);
+    const root = resolveRoot(engine);
+    const rootRect = usesElementScopedCanvas(engine) && typeof root?.getBoundingClientRect === 'function'
+        ? root.getBoundingClientRect()
+        : null;
+    const viewportWidth = Number(win?.innerWidth) || Number(doc?.documentElement?.clientWidth) || 1;
+    const viewportHeight = Number(win?.innerHeight) || Number(doc?.documentElement?.clientHeight) || 1;
+    const renderWidth = Number(rootRect?.width) || viewportWidth;
+    const renderHeight = Number(rootRect?.height) || viewportHeight;
+    const devicePixelRatio = Number(win?.devicePixelRatio) || 1;
+    const dpr = Math.min(Math.max(devicePixelRatio, 1), engine.maxDevicePixelRatio);
+
+    engine.dpr = dpr;
+    engine.width = Math.max(1, Math.floor(renderWidth));
+    engine.height = Math.max(1, Math.floor(renderHeight));
+    engine.canvas.width = Math.floor(engine.width * dpr);
+    engine.canvas.height = Math.floor(engine.height * dpr);
+    engine.ctx.setTransform(dpr, 0, 0, dpr, 0, 0);
+}

package/src/update.js

@@ -0,0 +1,307 @@
+import {
+    scheduleCascadeBursts,
+    spawnRocketTailEmbers,
+} from './rocketLaunch.js';
+import { launchBurst } from './burstSpawn.js';
+
+const MIN_DISTANCE_SQUARED_EPSILON = 0.0001;
+
+const TAIL_EMBER_ACCUMULATION = {
+    timeDensityFactor: 8,
+    travelDensityFactor: 0.04,
+    maxSpawnBudget: 6,
+};
+
+const FORM_SPIN_UPDATE_TUNING = {
+    velocitySpinScale: 0.004,
+    maxVelocityFactor: 1.6,
+    rateWaveFactorMin: 0.2,
+    rateWaveFactorMax: 1.8,
+    activeHoldMinFallback: 0.75,
+    activeHoldMaxFallback: 3.4,
+    inactiveHoldMinFallback: 0.55,
+    inactiveHoldMaxFallback: 3.8,
+    blendResponse: 5.5,
+};
+
+const FORM_WOBBLE_UPDATE_TUNING = {
+    velocityWobbleScale: 0.0035,
+    maxVelocityFactor: 1.8,
+    targetHoldMin: 0.14,
+    targetHoldMax: 0.48,
+    targetResponse: 3.2,
+    calmChance: 0.35,
+    sameDirectionBias: 0.48,
+    targetContinuity: 0.4,
+    maxVelocityDeltaPerSecond: 88,
+};
+
+const FORM_VERTICAL_MOTION_TUNING = {
+    // Keep prior confetti look while making vertical damping consistent
+    // across all form particles (instead of random per-particle drag).
+    perFrameDrag: 0.9735,
+};
+
+const PARTICLE_PHYSICS_TUNING = {
+    dragReferenceDtSeconds: 1 / 60,
+    offscreenBottomMargin: 120,
+};
+
+function hasRocketReachedTarget(rocket) {
+    const totalDx = rocket.totalDx ?? (rocket.targetX - rocket.startX);
+    const totalDy = rocket.totalDy ?? (rocket.targetY - rocket.startY);
+    const totalDistanceSq = rocket.totalDistanceSq ?? ((totalDx * totalDx) + (totalDy * totalDy));
+
+    if (totalDistanceSq <= MIN_DISTANCE_SQUARED_EPSILON) {
+        return true;
+    }
+
+    const travelDx = rocket.x - rocket.startX;
+    const travelDy = rocket.y - rocket.startY;
+    const traveledProjection = (travelDx * totalDx) + (travelDy * totalDy);
+
+    return traveledProjection >= totalDistanceSq;
+}
+
+function releaseParticle(engine, particle) {
+    if (particle.type === 'form') {
+        engine.formPool.push(particle);
+    } else if (particle.type === 'burstSpark') {
+        engine.sparkPool.push(particle);
+    } else {
+        engine.emberPool.push(particle);
+    }
+}
+
+function isParticleBelowCanvas(engine, particle) {
+    const radius = Number.isFinite(particle.radius) ? particle.radius : 0;
+    const sparkLength = Number.isFinite(particle.sparkLength) ? particle.sparkLength : 0;
+    const margin = Math.max(
+        PARTICLE_PHYSICS_TUNING.offscreenBottomMargin,
+        radius * 8,
+        sparkLength * 2,
+    );
+
+    return particle.vy >= 0 && particle.y - margin > engine.height;
+}
+
+function randomBetween(min, max) {
+    return min + (Math.random() * (max - min));
+}
+
+export function updateRockets(engine, dt) {
+    const rockets = engine.rockets;
+    let writeIndex = 0;
+
+    for (let index = 0; index < rockets.length; index += 1) {
+        const rocket = rockets[index];
+        const previousX = rocket.x;
+        const previousY = rocket.y;
+
+        rocket.life -= dt;
+        rocket.x += rocket.vx * dt;
+        rocket.y += rocket.vy * dt;
+        rocket.trailTimer += dt;
+        rocket.prevX = previousX;
+        rocket.prevY = previousY;
+
+        if (rocket.tailEmbers?.enabled) {
+            const travelDistance = rocket.travelSpeed * dt;
+            const tailEmberDensity = Math.max(1, rocket.tailEmbers.count ?? engine.rocketTailEmbers.count);
+            rocket.tailEmberAccumulator += (dt * tailEmberDensity * TAIL_EMBER_ACCUMULATION.timeDensityFactor)
+                + (travelDistance * tailEmberDensity * TAIL_EMBER_ACCUMULATION.travelDensityFactor);
+            const emberBudget = Math.min(TAIL_EMBER_ACCUMULATION.maxSpawnBudget, Math.floor(rocket.tailEmberAccumulator));
+
+            if (emberBudget > 0) {
+                rocket.tailEmberAccumulator -= emberBudget;
+                spawnRocketTailEmbers(engine, rocket, emberBudget);
+            }
+        }
+
+        if (rocket.life <= 0 || hasRocketReachedTarget(rocket)) {
+            const burstX = rocket.hasExplicitTarget ? rocket.targetX : rocket.x;
+            const burstY = rocket.hasExplicitTarget ? rocket.targetY : rocket.y;
+            rocket.x = burstX;
+            rocket.y = burstY;
+            launchBurst(engine, burstX, burstY, rocket.burst);
+            scheduleCascadeBursts(engine, rocket);
+            continue;
+        }
+
+        if (writeIndex !== index) {
+            rockets[writeIndex] = rocket;
+        }
+        writeIndex += 1;
+    }
+
+    rockets.length = writeIndex;
+}
+
+export function updateParticles(engine, dt) {
+    const particles = engine.particles;
+    let writeIndex = 0;
+    const dragExponent = dt / PARTICLE_PHYSICS_TUNING.dragReferenceDtSeconds;
+    const formVerticalDragFactor = Math.pow(FORM_VERTICAL_MOTION_TUNING.perFrameDrag, dragExponent);
+
+    for (let index = 0; index < particles.length; index += 1) {
+        const particle = particles[index];
+
+        particle.life -= dt;
+        if (particle.life <= 0) {
+            releaseParticle(engine, particle);
+            continue;
+        }
+
+        const dragFactor = Math.pow(particle.drag, dragExponent);
+        particle.vx *= dragFactor;
+        if (particle.type === 'form') {
+            particle.vy *= formVerticalDragFactor;
+        } else {
+            particle.vy *= dragFactor;
+        }
+        particle.vy += particle.gravity * dt;
+        let wobbleVelocity = 0;
+        if (particle.type === 'form' && particle.formWobble > 0) {
+            const wobbleVelocityFactor = Math.min(
+                FORM_WOBBLE_UPDATE_TUNING.maxVelocityFactor,
+                1 + (Math.abs(particle.vy) * FORM_WOBBLE_UPDATE_TUNING.velocityWobbleScale),
+            );
+            const timerRate = 0.6 + (0.4 * wobbleVelocityFactor);
+            particle.formWobbleTargetTimer -= dt * timerRate;
+            if (particle.formWobbleTargetTimer <= 0) {
+                particle.formWobbleTargetTimer = FORM_WOBBLE_UPDATE_TUNING.targetHoldMin
+                    + (Math.random()
+                        * (FORM_WOBBLE_UPDATE_TUNING.targetHoldMax - FORM_WOBBLE_UPDATE_TUNING.targetHoldMin));
+                const maxLateralSpeed = particle.formWobbleLateralSpeed;
+                const hasCalmWindow = Math.random() < FORM_WOBBLE_UPDATE_TUNING.calmChance;
+                let nextTarget = hasCalmWindow
+                    ? 0
+                    : ((Math.random() * 2) - 1) * maxLateralSpeed;
+                if (Math.random() < FORM_WOBBLE_UPDATE_TUNING.sameDirectionBias && particle.formWobbleTarget !== 0) {
+                    nextTarget = Math.sign(particle.formWobbleTarget) * Math.abs(nextTarget);
+                }
+                nextTarget = (particle.formWobbleTarget * FORM_WOBBLE_UPDATE_TUNING.targetContinuity)
+                    + (nextTarget * (1 - FORM_WOBBLE_UPDATE_TUNING.targetContinuity));
+                particle.formWobbleTarget = nextTarget;
+            }
+            const response = Math.min(1, FORM_WOBBLE_UPDATE_TUNING.targetResponse * dt * wobbleVelocityFactor);
+            const targetVelocity = particle.formWobbleVelocity
+                + ((particle.formWobbleTarget - particle.formWobbleVelocity) * response);
+            const maxDelta = FORM_WOBBLE_UPDATE_TUNING.maxVelocityDeltaPerSecond * dt;
+            const velocityDelta = targetVelocity - particle.formWobbleVelocity;
+            if (velocityDelta > maxDelta) {
+                particle.formWobbleVelocity += maxDelta;
+            } else if (velocityDelta < -maxDelta) {
+                particle.formWobbleVelocity -= maxDelta;
+            } else {
+                particle.formWobbleVelocity = targetVelocity;
+            }
+            wobbleVelocity = particle.formWobbleVelocity * wobbleVelocityFactor;
+        }
+        particle.x += (particle.vx + wobbleVelocity) * dt;
+        particle.y += particle.vy * dt;
+        if (particle.type === 'form' && particle.formSpin > 0) {
+            if (particle.formSpinBudget <= 0) {
+                particle.formSpinActive = false;
+            } else {
+                particle.formSpinToggleTimer -= dt;
+                if (particle.formSpinToggleTimer <= 0) {
+                    particle.formSpinActive = !particle.formSpinActive;
+                    particle.formSpinToggleTimer = particle.formSpinActive
+                        ? randomBetween(
+                            particle.formSpinActiveHoldMin ?? FORM_SPIN_UPDATE_TUNING.activeHoldMinFallback,
+                            particle.formSpinActiveHoldMax ?? FORM_SPIN_UPDATE_TUNING.activeHoldMaxFallback,
+                        )
+                        : randomBetween(
+                            particle.formSpinInactiveHoldMin ?? FORM_SPIN_UPDATE_TUNING.inactiveHoldMinFallback,
+                            particle.formSpinInactiveHoldMax ?? FORM_SPIN_UPDATE_TUNING.inactiveHoldMaxFallback,
+                        );
+                }
+            }
+
+            const spinIsActive = particle.formSpinActive && particle.formSpinBudget > 0;
+            const blendTarget = spinIsActive ? 1 : 0;
+            const blendResponse = Math.min(1, FORM_SPIN_UPDATE_TUNING.blendResponse * dt);
+            particle.formSpinBlend += (blendTarget - particle.formSpinBlend) * blendResponse;
+
+            if (spinIsActive) {
+                particle.formSpinBudget = Math.max(0, particle.formSpinBudget - dt);
+                const velocityFactor = Math.min(
+                    FORM_SPIN_UPDATE_TUNING.maxVelocityFactor,
+                    1 + (Math.abs(particle.vy) * FORM_SPIN_UPDATE_TUNING.velocitySpinScale),
+                );
+                particle.formSpinRateWavePhase += particle.formSpinRateWaveSpeed * dt;
+                const rawRateWaveFactor = 1
+                    + (Math.sin(particle.formSpinRateWavePhase) * particle.formSpinRateWaveAmplitude);
+                const rateWaveFactor = Math.min(
+                    FORM_SPIN_UPDATE_TUNING.rateWaveFactorMax,
+                    Math.max(FORM_SPIN_UPDATE_TUNING.rateWaveFactorMin, rawRateWaveFactor),
+                );
+                const spinStep = velocityFactor * rateWaveFactor * dt;
+                particle.formSpinPhase += particle.formSpinPhaseSpeed * spinStep;
+                particle.formSpinAngle += particle.formSpinAngleSpeed * spinStep;
+                const flipWave = Math.abs(Math.sin(particle.formSpinPhase));
+                const shapedFlipWave = Math.pow(flipWave, particle.formSpinFlipExponent ?? 1);
+                particle.formWidthScale = particle.formSpinMinWidthScale
+                    + ((1 - particle.formSpinMinWidthScale) * shapedFlipWave);
+            } else if (particle.formSpinBlend <= 0.001) {
+                particle.formSpinBlend = 0;
+                particle.formWidthScale = 1;
+            }
+        }
+
+        if (isParticleBelowCanvas(engine, particle)) {
+            releaseParticle(engine, particle);
+            continue;
+        }
+
+        if (writeIndex !== index) {
+            particles[writeIndex] = particle;
+        }
+        writeIndex += 1;
+    }
+
+    particles.length = writeIndex;
+}
+
+export function updateFlashes(engine, dt) {
+    const flashes = engine.flashes;
+    let writeIndex = 0;
+
+    for (let index = 0; index < flashes.length; index += 1) {
+        const flash = flashes[index];
+
+        flash.age += dt;
+        if (flash.age >= flash.maxLife) {
+            continue;
+        }
+
+        if (writeIndex !== index) {
+            flashes[writeIndex] = flash;
+        }
+        writeIndex += 1;
+    }
+
+    flashes.length = writeIndex;
+}
+
+export function updateTwinkleClouds(engine, dt) {
+    const twinkleClouds = engine.twinkleClouds;
+    let writeIndex = 0;
+
+    for (let index = 0; index < twinkleClouds.length; index += 1) {
+        const cloud = twinkleClouds[index];
+
+        cloud.age += dt;
+        if (cloud.age >= cloud.maxLife) {
+            continue;
+        }
+
+        if (writeIndex !== index) {
+            twinkleClouds[writeIndex] = cloud;
+        }
+        writeIndex += 1;
+    }
+
+    twinkleClouds.length = writeIndex;
+}