fireworks-engine 1.0.0 → 1.0.1

package/README.md

@@ -52,6 +52,37 @@ Always call `destroy()` when the owning UI unmounts.
 fireworks.destroy();
 ```
 
+## Burst notifications
+
+Pass `onBurst` when creating the engine to synchronize another effect with each
+logical explosion:
+
+```js
+const fireworks = createFireworksEngine({
+    onBurst: ({ x, y }) => {
+        // Trigger an already prepared effect at these canvas coordinates.
+    },
+});
+```
+
+The callback runs synchronously after the first visual component is created,
+once per logical burst, including rocket detonations and cascade children.
+Queued bursts notify on materialization, not enqueue, and particle batches,
+trails, and later twinkles do not produce additional notifications. Flash-only
+and twinkle-only bursts also notify; a twinkle cloud notifies when created even
+if its twinkles appear later. Completely empty bursts do not notify. This is a
+component-creation signal, not a pixel visibility or audio hardware timestamp.
+
+`onBurst` is constructor-only: `start`, launch methods, and `updateOptions` neither
+replace nor reset it. Exceptions in the callback are isolated from rendering.
+Calling `stop()` or `destroy()` from the callback cancels the rest of that run;
+starting a replacement effect leaves the new run intact. Ordinary additive
+launches remain part of the current run. Call `destroy()` when the owner unmounts.
+
+TypeScript exports `FireworksBurstEvent`, `FireworksBurstCallback`, and
+`FireworksEngineCreationOptions`; existing `FireworksEngineOptions` still work
+for both construction and start/update configuration.
+
 ## Public API
 
 Primary exports:

package/index.d.ts

@@ -189,6 +189,18 @@ export interface FireworksRocketLaunchOptions extends FireworksBurstOverrideOpti
     rocketTailEmbers?: FireworksRocketTailEmbersOptions;
 }
 
+export interface FireworksBurstEvent {
+    x: number;
+    y: number;
+}
+
+export type FireworksBurstCallback = (event: FireworksBurstEvent) => void;
+
+/** Options accepted only when creating an engine. */
+export interface FireworksEngineCreationOptions extends FireworksEngineOptions {
+    onBurst?: FireworksBurstCallback | null;
+}
+
 export interface FireworksEngineOptions extends FireworksRocketLaunchOptions {
     canvas?: FireworksCanvasOptions;
     runtime?: FireworksRuntimeOptions;
@@ -506,7 +518,7 @@ export interface FireworksBurstRequest {
 export interface FireworksPresetConfig extends FireworksEngineOptions { }
 
 export declare class FireworksEngine {
-    constructor(options?: FireworksEngineOptions);
+    constructor(options?: FireworksEngineCreationOptions);
 
     documentRef: Document | null | undefined;
     windowRef: Window | null | undefined;
@@ -677,7 +689,7 @@ export interface FireworksRocketExplicitTarget {
  * @param options Initial engine configuration.
  * @returns A new fireworks engine instance.
  */
-export declare function createFireworksEngine(options?: FireworksEngineOptions): FireworksEngine;
+export declare function createFireworksEngine(options?: FireworksEngineCreationOptions): FireworksEngine;
 
 /**
  * Resolves a preset name to a fully expanded engine configuration.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fireworks-engine",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "license": "BSD-2-Clause",
   "description": "Reusable canvas fireworks runtime package for standalone integrations and demos.",
   "author": "coinexplain",
@@ -41,7 +41,7 @@
   "scripts": {
     "smoke": "node --check src/index.js && node --input-type=module -e \"const mod = await import('./src/index.js'); if (typeof mod.createFireworksEngine !== 'function' || typeof mod.resolveFireworksEnginePreset !== 'function' || typeof mod.default !== 'function') throw new Error('package smoke failed'); console.log('package smoke ok');\"",
     "typecheck": "tsc --noEmit --project tsconfig.types.json",
-    "test": "npm run smoke && npm run typecheck"
+    "test": "npm run smoke && npm run typecheck && node --test test/burst-events.test.js"
   },
   "devDependencies": {
     "typescript": "^5.9.3"

package/src/burstEvents.js

@@ -0,0 +1,19 @@
+// A stop invalidates every stack/timer belonging to the previous run. Additive
+// launches deliberately keep the generation, including cascade children.
+export function isCurrentRun(engine, generation) {
+    return engine.runGeneration === generation;
+}
+
+export function createBurstEvent(engine, x, y) {
+    return { generation: engine.runGeneration, x, y, notified: false };
+}
+
+export function notifyBurst(engine, burst) {
+    if (burst.notified || !isCurrentRun(engine, burst.generation)) return;
+    burst.notified = true;
+    try {
+        engine.onBurstCallback?.({ x: burst.x, y: burst.y });
+    } catch {
+        // Consumer code must not interrupt rendering or lifecycle cleanup.
+    }
+}

package/src/burstSpawn.js

@@ -1,3 +1,4 @@
+import { createBurstEvent, isCurrentRun, notifyBurst } from './burstEvents.js';
 import {
     BURST_FLASH_ATTACK_UNIT,
     DEFAULT_BURST_SINGLE_COLOR,
@@ -252,6 +253,17 @@ function createBurstRequests(x, y, options, flashOptions = options) {
     return requests;
 }
 
+function spawnBurstExtras(engine, burst, flashOptions, cloudOptions) {
+    if (spawnBurstCenterFlash(engine, burst.x, burst.y, flashOptions)) {
+        notifyBurst(engine, burst);
+    }
+    if (!isCurrentRun(engine, burst.generation)) return false;
+    if (spawnBurstTwinkleCloud(engine, burst.x, burst.y, cloudOptions)) {
+        notifyBurst(engine, burst);
+    }
+    return isCurrentRun(engine, burst.generation);
+}
+
 function enqueueBurst(engine, x, y, options = {}) {
     if (!engine.running) {
         return false;
@@ -262,10 +274,11 @@ function enqueueBurst(engine, x, y, options = {}) {
         resolveBurstCurrentConfig(engine),
     );
     const requests = createBurstRequests(x, y, burstOptions, options);
+    const burst = createBurstEvent(engine, x, y);
+    requests.forEach((request) => { request.burstEvent = burst; });
 
     if (requests.length === 0) {
-        spawnBurstCenterFlash(engine, x, y, options);
-        spawnBurstTwinkleCloud(engine, x, y, burstOptions);
+        spawnBurstExtras(engine, burst, options, burstOptions);
         return true;
     }
 
@@ -554,6 +567,7 @@ function spawnBurstParticles(engine, request, startIndex, count) {
 }
 
 export function drainBurstQueue(engine) {
+    const generation = engine.runGeneration;
     let remainingBudget = engine.maxBurstParticlesPerFrame;
 
     while (remainingBudget > 0 && engine.burstQueue.length > 0) {
@@ -567,14 +581,22 @@ export function drainBurstQueue(engine) {
 
         const spawnCount = Math.min(remainingBudget, remainingParticles);
         if (request.spawnBurstCenterFlash && !request.flashSpawned) {
-            spawnBurstCenterFlash(engine, request.x, request.y, request.flashOptions ?? request.options);
             request.flashSpawned = true;
+            if (spawnBurstCenterFlash(engine, request.x, request.y, request.flashOptions ?? request.options)) {
+                notifyBurst(engine, request.burstEvent);
+            }
+            if (!isCurrentRun(engine, generation)) return;
         }
         if (request.spawnBurstTwinkleCloud && !request.twinkleCloudSpawned) {
-            spawnBurstTwinkleCloud(engine, request.x, request.y, request.options);
             request.twinkleCloudSpawned = true;
+            if (spawnBurstTwinkleCloud(engine, request.x, request.y, request.options)) {
+                notifyBurst(engine, request.burstEvent);
+            }
+            if (!isCurrentRun(engine, generation)) return;
         }
         spawnBurstParticles(engine, request, request.nextIndex, spawnCount);
+        notifyBurst(engine, request.burstEvent);
+        if (!isCurrentRun(engine, generation)) return;
         request.nextIndex += spawnCount;
         remainingBudget -= spawnCount;
 
@@ -600,12 +622,14 @@ export function launchBurst(engine, x, y, options = {}) {
         normalizedOptions,
         resolveBurstCurrentConfig(engine),
     );
-    spawnBurstCenterFlash(engine, x, y, normalizedOptions);
-    spawnBurstTwinkleCloud(engine, x, y, normalizedOptions);
+    const burst = createBurstEvent(engine, x, y);
+    if (!spawnBurstExtras(engine, burst, normalizedOptions, normalizedOptions)) return true;
     const requests = createBurstRequests(x, y, burstOptions);
-    requests.forEach((request) => {
+    for (const request of requests) {
         spawnBurstParticles(engine, request, 0, request.totalCount);
-    });
+        notifyBurst(engine, burst);
+        if (!isCurrentRun(engine, burst.generation)) return true;
+    }
     return true;
 }
 
@@ -669,6 +693,7 @@ function spawnBurstCenterFlash(engine, x, y, options = {}) {
         color,
         innerStop,
     });
+    return true;
 }
 
 function spawnBurstTwinkleCloud(engine, x, y, options = {}) {
@@ -761,4 +786,5 @@ function spawnBurstTwinkleCloud(engine, x, y, options = {}) {
         spawnSpread,
         twinkles,
     });
+    return true;
 }

package/src/presets.js

@@ -346,6 +346,7 @@ function runAchievementUnlock(engine, targetX, targetY, options) {
 }
 
 function runSnowfall(engine, _targetX, _targetY, options) {
+    const generation = engine.runGeneration;
     const flakesPerWave = 6;
     const waveDelayMs = 1500;
 
@@ -355,6 +356,7 @@ function runSnowfall(engine, _targetX, _targetY, options) {
             const x = randomRange(0, stageWidth);
             const y = -10 - randomRange(0, 40);
             engine.burst(x, y, options);
+            if (engine.runGeneration !== generation) return;
         }
 
         scheduleTimeout(engine, () => {
@@ -372,6 +374,7 @@ function runSnowfall(engine, _targetX, _targetY, options) {
 }
 
 function runLeafFall(engine, _targetX, _targetY, options) {
+    const generation = engine.runGeneration;
     const leavesPerWave = 5;
     const waveDelayMs = 1200;
 
@@ -381,6 +384,7 @@ function runLeafFall(engine, _targetX, _targetY, options) {
             const x = randomRange(0, stageWidth);
             const y = -16 - randomRange(0, 60);
             engine.burst(x, y, options);
+            if (engine.runGeneration !== generation) return;
         }
 
         scheduleTimeout(engine, () => {
@@ -398,6 +402,7 @@ function runLeafFall(engine, _targetX, _targetY, options) {
 }
 
 function runAmbientSparkle(engine, targetX, targetY, options) {
+    const generation = engine.runGeneration;
     const pulseDelayMs = 8000;
 
     const launchPulse = () => {
@@ -405,6 +410,7 @@ function runAmbientSparkle(engine, targetX, targetY, options) {
         const centerY = Number.isFinite(targetY) ? targetY : engine.height * 0.5;
 
         engine.launchRocketAt(centerX, centerY, options);
+        if (engine.runGeneration !== generation) return;
         engine.launchRocketAt(
             centerX,
             centerY,
@@ -415,6 +421,7 @@ function runAmbientSparkle(engine, targetX, targetY, options) {
             }),
         );
 
+        if (engine.runGeneration !== generation) return;
         scheduleTimeout(engine, () => {
             if (!engine.running) {
                 return;
@@ -430,6 +437,7 @@ function runAmbientSparkle(engine, targetX, targetY, options) {
 }
 
 function runConfettiPop(engine, _targetX, _targetY, options) {
+    const generation = engine.runGeneration;
     const stageWidth = engine.width;
     const stageHeight = engine.height;
     const cannons = [
@@ -437,7 +445,7 @@ function runConfettiPop(engine, _targetX, _targetY, options) {
         { x: 1.01, y: 0.5, directionDeg: 135 },
     ];
 
-    cannons.forEach(({ x, y, directionDeg }) => {
+    for (const { x, y, directionDeg } of cannons) {
         engine.confetti(
             stageWidth * x,
             stageHeight * y,
@@ -447,7 +455,8 @@ function runConfettiPop(engine, _targetX, _targetY, options) {
                 },
             }),
         );
-    });
+        if (engine.runGeneration !== generation) return true;
+    }
 
     return true;
 }

package/src/renderer.js

@@ -800,6 +800,7 @@ function drawFormParticle(engine, particle) {
 }
 
 export function loop(engine, now) {
+    const generation = engine.runGeneration;
     if (!engine.running || !engine.ctx) {
         return;
     }
@@ -817,6 +818,7 @@ export function loop(engine, now) {
 
     ctx.clearRect(0, 0, engine.width, engine.height);
     updateRockets(engine, dt);
+    if (engine.runGeneration !== generation) return;
     updateParticles(engine, dt);
     updateFlashes(engine, dt);
     updateTwinkleClouds(engine, dt);
@@ -854,6 +856,7 @@ export function loop(engine, now) {
     }
 
     drainBurstQueue(engine);
+    if (engine.runGeneration !== generation) return;
     clearRenderCachesWhenIdle(engine);
 
     const requestAnimationFrameFn = getRequestAnimationFrame(engine);

package/src/rocketLaunch.js

@@ -317,6 +317,7 @@ function launchRocketWithExplicitTarget(engine, options, explicitTarget) {
         return false;
     }
 
+    const generation = engine.runGeneration;
     const wasRunning = engine.running;
     if (!startLoop(engine)) {
         return false;
@@ -324,7 +325,7 @@ function launchRocketWithExplicitTarget(engine, options, explicitTarget) {
 
     createRocket(engine, options, explicitTarget);
 
-    if (!wasRunning) {
+    if (engine.runGeneration === generation && !wasRunning) {
         engine.finishWhenDone();
     }
 
@@ -622,10 +623,12 @@ function createRocket(engine, options = {}, explicitTarget = null) {
 }
 
 export function launchRocket(engine, options = {}) {
+    const generation = engine.runGeneration;
     const count = options.count ?? 1;
 
     for (let index = 0; index < count; index += 1) {
         createRocket(engine, options);
+        if (engine.runGeneration !== generation) return;
     }
 }
 
@@ -659,6 +662,7 @@ export function launchRocketFromTo(engine, startX, startY, targetX, targetY, opt
 }
 
 export function scheduleCascadeBursts(engine, rocket) {
+    const generation = engine.runGeneration;
     const cascade = rocket.cascade ?? {};
     const cascadeMode = resolveRocketCascadeMode(cascade.mode);
     const cascadeBurstCount = cascade.bursts ?? 0;
@@ -693,6 +697,7 @@ export function scheduleCascadeBursts(engine, rocket) {
                 distance,
             );
             launchRocketFromTo(engine, originX, originY, x, y, childLaunchOptions);
+            if (engine.runGeneration !== generation) return;
         }
         return;
     }

package/src/runtime.js

@@ -285,6 +285,8 @@ function mergePresetLaunchOptions(presetOptions = {}, launchOverrides = {}) {
 
 export class FireworksEngine {
     constructor(options = {}) {
+        this.runGeneration = 0;
+        this.onBurstCallback = typeof options?.onBurst === 'function' ? options.onBurst : null;
         const normalizedOptions = normalizeGroupedPublicOptions(options);
         this.explicitLaunchOptions = extractExplicitLaunchOptions(options);
         const engineConfig = buildEngineConfig(normalizedOptions);
@@ -420,6 +422,7 @@ export class FireworksEngine {
     }
 
     launchPresetAt(name, targetX, targetY, options = {}) {
+        const generation = this.runGeneration;
         if (shouldSkipHiddenLaunch(this)) {
             return false;
         }
@@ -452,7 +455,7 @@ export class FireworksEngine {
                     ? launchPreset.run(this, targetX, targetY, launchOptions)
                     : false;
                 launched = launched || nextLaunched;
-                if (!nextLaunched) {
+                if (this.runGeneration !== generation || !nextLaunched) {
                     break;
                 }
             }
@@ -485,7 +488,7 @@ export class FireworksEngine {
         for (let index = 0; index < count; index += 1) {
             const nextLaunched = launchRocketAt(this, targetX, targetY, launchOptions);
             launched = launched || nextLaunched;
-            if (!nextLaunched) {
+            if (this.runGeneration !== generation || !nextLaunched) {
                 break;
             }
         }
@@ -623,8 +626,9 @@ export class FireworksEngine {
     // Note: Renderer logic is decoupled; use engine directly in renderer for performance.
 
     finishWhenDone() {
+        const generation = this.runGeneration;
         const check = () => {
-            if (!this.running) {
+            if (this.runGeneration !== generation || !this.running) {
                 return;
             }
 
@@ -639,7 +643,7 @@ export class FireworksEngine {
                     this.finishLifecycleNotified = true;
                     invokeLifecycleHook(this.activeLifecycleHooks.onFinish, this);
                 }
-                this.stop(false);
+                if (this.runGeneration === generation) this.stop(false);
                 return;
             }
 
@@ -728,6 +732,7 @@ export class FireworksEngine {
     }
 
     stop(clearCanvas = true) {
+        this.runGeneration += 1;
         const wasRunning = this.running;
         this.running = false;
         lifecycle.clearPendingStart(this);

package/src/runtimeLifecycle.js

@@ -160,10 +160,12 @@ export function removeResizeObserver(engine) {
 }
 
 export function scheduleTimeout(engine, callback, delay = 0) {
+    const generation = engine.runGeneration;
     const schedule = typeof engine.setTimeoutRef === 'function' ? engine.setTimeoutRef : setTimeout;
 
     let timeoutId = null;
     const runWhenVisible = () => {
+        if (engine.runGeneration !== generation) return;
         if (timeoutId !== null) {
             engine.timeoutIds.delete(timeoutId);
         }

package/src/update.js

@@ -90,6 +90,7 @@ function randomBetween(min, max) {
 }
 
 export function updateRockets(engine, dt) {
+    const generation = engine.runGeneration;
     const rockets = engine.rockets;
     let writeIndex = 0;
 
@@ -124,7 +125,9 @@ export function updateRockets(engine, dt) {
             rocket.x = burstX;
             rocket.y = burstY;
             launchBurst(engine, burstX, burstY, rocket.burst);
+            if (engine.runGeneration !== generation) return;
             scheduleCascadeBursts(engine, rocket);
+            if (engine.runGeneration !== generation) return;
             continue;
         }