fireworks-engine 1.0.0 → 1.0.2

package/README.md

@@ -52,8 +52,86 @@ 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
 
+### Tracked victory boundaries
+
+For the supported game victory configuration, opt in per launch:
+
+```js
+const fireworks = createFireworksEngine({
+    onBurst: ({ x, y, sequence }) => {
+        // sequence is available on tracked victory bursts only.
+        // It describes this explosion now, never a delayed completion signal.
+        if (sequence?.isFirst || sequence?.isLast) {
+            // Trigger a prepared sound here.
+        }
+    },
+});
+fireworks.launchPresetAt('victory-finale', 210, 90, {
+    trackBurstSequence: true,
+    sizeScale: 1.05,
+    timeScale: 0.95,
+});
+```
+
+`sequence` contains an opaque symbol `id`, zero-based materialization `index`,
+and boolean `isFirst`/`isLast`. Each additive launch has its own identity and
+boundaries. Future rocket and delayed cascade bursts are reserved before the
+first explosion; particles fading after their first appearance do not count
+as future bursts. A final burst is flagged during its own normal `onBurst`
+callback, not when the animation later becomes idle. A one-burst sequence has
+both flags; no extra callbacks are generated for cancellation or empty work.
+
+This deliberately narrow opt-in accepts only `victory-finale`, `count` omitted
+or exactly `1`, `sizeScale: 1.05`, `timeScale: 0.95`, and no other launch keys.
+Effective engine visual and performance settings must match defaults (including
+`sizeScale: 1`, burst components, rocket/tail settings and performance budgets;
+default queue throttling is **off**). Constructor canvas/runtime references and
+callbacks may be customized. Engine timeScale may differ because the launch
+explicitly sets it. Other tracking configurations, including `count: 0/2` and
+queued engines, return `false` before creating a canvas, scheduling work,
+changing timeScale, drawing random numbers or notifying callbacks. Calls without
+`trackBurstSequence: true` keep their existing behavior and `{ x, y }` payload.
+
+Changing effective visual/performance configuration via `updateOptions` during
+a sequence interrupts its tracking permanently, even if defaults are restored.
+The visual effect continues normally, with subsequent callbacks lacking
+`sequence`. `stop`, `destroy` and replacement starts invalidate all old tracking;
+no synthetic final sound should be added. Do not mutate engine internals directly.
+This is a component-creation synchronization signal, not an audio-output timestamp.
+
 Primary exports:
 
 - `FireworksEngine`

package/index.d.ts

@@ -189,6 +189,35 @@ export interface FireworksRocketLaunchOptions extends FireworksBurstOverrideOpti
     rocketTailEmbers?: FireworksRocketTailEmbersOptions;
 }
 
+export interface FireworksBurstEvent {
+    x: number;
+    y: number;
+    /** Present only for an opted-in, supported victory-finale launch. */
+    sequence?: {
+        /** Opaque identity, unique per launch within this engine. */
+        id: symbol;
+        index: number;
+        isFirst: boolean;
+        isLast: boolean;
+    };
+}
+
+export interface FireworksPresetLaunchOptions extends FireworksRocketLaunchOptions {
+    /** Only victory-finale with count=1, sizeScale=1.05, timeScale=0.95 and
+     * default effective visual/performance engine configuration is supported.
+     * Unsupported tracking requests return false before launch side effects.
+     * Changing that configuration during a launch interrupts its tracking.
+     */
+    trackBurstSequence?: boolean;
+}
+
+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 +535,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;
@@ -624,7 +653,7 @@ export declare class FireworksEngine {
         name: FireworksEnginePresetName | FireworksLaunchPresetName | string,
         targetX: number,
         targetY: number,
-        options?: FireworksRocketLaunchOptions,
+        options?: FireworksPresetLaunchOptions,
     ): boolean;
     /**
      * Launches a rocket from a specific start point toward a target point.
@@ -677,7 +706,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.2",
   "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 test/burst-sequence.test.js"
   },
   "devDependencies": {
     "typescript": "^5.9.3"

package/src/burstEvents.js

@@ -0,0 +1,22 @@
+// 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;
+}
+
+import { materializeBurstWork } from './burstSequence.js';
+
+export function createBurstEvent(engine, x, y, work) {
+    return { generation: engine.runGeneration, x, y, notified: false, work };
+}
+
+export function notifyBurst(engine, burst) {
+    if (burst.notified || !isCurrentRun(engine, burst.generation)) return;
+    burst.notified = true;
+    const sequence = materializeBurstWork(engine, burst.work);
+    try {
+        engine.onBurstCallback?.({ x: burst.x, y: burst.y, ...(sequence ? { sequence } : {}) });
+    } catch {
+        // Consumer code must not interrupt rendering or lifecycle cleanup.
+    }
+}

package/src/burstSequence.js

@@ -0,0 +1,67 @@
+import { buildEngineConfig } from './configBuilder.js';
+
+// Internal launch context; never normalized into public visual options.
+export const BURST_SEQUENCE = Symbol('burstSequence');
+export const BURST_WORK = Symbol('burstWork');
+const defaults = buildEngineConfig();
+const groups = ['rocket', 'rocketTailEmbers', 'burstForms', 'burstSparks',
+    'burstCenterFlash', 'burstTwinkleCloud', 'performance'];
+const allowed = new Set(['trackBurstSequence', 'sizeScale', 'timeScale', 'count']);
+const sequencesByEngine = new WeakMap();
+
+export function invalidateBurstSequences(engine) {
+    const sequences = sequencesByEngine.get(engine);
+    if (!sequences) return;
+    for (const sequence of sequences) sequence.active = false;
+    sequences.clear();
+}
+
+export function supportsSequenceConfig(engine) {
+    return engine.sizeScale === defaults.sizeScale
+        && engine.enableBurstQueueThrottling === defaults.toggles.enableBurstQueueThrottling
+        && engine.maxBurstParticlesPerFrame === defaults.performance.maxBurstParticlesPerFrame
+        && groups.every((key) => JSON.stringify(engine[key]) === JSON.stringify(defaults[key]));
+}
+
+export function supportsSequenceLaunch(engine, name, options) {
+    return name === 'victory-finale' && options.sizeScale === 1.05 && options.timeScale === 0.95
+        && (options.count === undefined || options.count === 1)
+        && Object.keys(options).every((key) => allowed.has(key))
+        && supportsSequenceConfig(engine);
+}
+
+export function createBurstSequence(engine) {
+    const sequence = { id: Symbol('victory-finale'), generation: engine.runGeneration,
+        pending: 0, index: 0, active: true };
+    if (!sequencesByEngine.has(engine)) sequencesByEngine.set(engine, new Set());
+    sequencesByEngine.get(engine).add(sequence);
+    return sequence;
+}
+
+export function discardBurstSequence(engine, sequence) {
+    if (!sequence) return;
+    sequence.active = false;
+    sequencesByEngine.get(engine)?.delete(sequence);
+}
+
+export function reserveBurstWork(sequence, children = []) {
+    sequence.pending += 1;
+    return { sequence, children, materialized: false };
+}
+
+export function materializeBurstWork(engine, work) {
+    if (!work || work.materialized) return null;
+    const sequence = work.sequence;
+    if (!sequence.active || engine.runGeneration !== sequence.generation) return null;
+    // Configuration changes during a launch interrupt its tracking, not its visuals.
+    if (!supportsSequenceConfig(engine)) {
+        sequence.active = false;
+        sequencesByEngine.get(engine)?.delete(sequence);
+        return null;
+    }
+    work.materialized = true;
+    sequence.pending -= 1;
+    const index = sequence.index++;
+    if (sequence.pending === 0) sequencesByEngine.get(engine)?.delete(sequence);
+    return { id: sequence.id, index, isFirst: index === 0, isLast: sequence.pending === 0 };
+}

package/src/burstSpawn.js

@@ -1,3 +1,5 @@
+import { createBurstEvent, isCurrentRun, notifyBurst } from './burstEvents.js';
+import { BURST_WORK } from './burstSequence.js';
 import {
     BURST_FLASH_ATTACK_UNIT,
     DEFAULT_BURST_SINGLE_COLOR,
@@ -252,7 +254,18 @@ function createBurstRequests(x, y, options, flashOptions = options) {
     return requests;
 }
 
-function enqueueBurst(engine, x, y, options = {}) {
+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 = {}, work) {
     if (!engine.running) {
         return false;
     }
@@ -262,10 +275,11 @@ function enqueueBurst(engine, x, y, options = {}) {
         resolveBurstCurrentConfig(engine),
     );
     const requests = createBurstRequests(x, y, burstOptions, options);
+    const burst = createBurstEvent(engine, x, y, work);
+    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 +568,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 +582,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;
 
@@ -589,7 +612,7 @@ export function drainBurstQueue(engine) {
 export function launchBurst(engine, x, y, options = {}) {
     const normalizedOptions = normalizeGroupedPublicOptions(options);
     if (engine.enableBurstQueueThrottling) {
-        return enqueueBurst(engine, x, y, normalizedOptions);
+        return enqueueBurst(engine, x, y, normalizedOptions, options[BURST_WORK]);
     }
 
     if (!engine.running) {
@@ -600,12 +623,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, options[BURST_WORK]);
+    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 +694,7 @@ function spawnBurstCenterFlash(engine, x, y, options = {}) {
         color,
         innerStop,
     });
+    return true;
 }
 
 function spawnBurstTwinkleCloud(engine, x, y, options = {}) {
@@ -761,4 +787,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

@@ -20,6 +20,7 @@ import {
     normalizeHexColor,
 } from './colorUtils.js';
 import { buildBurstOptions } from './burstConfigBuilder.js';
+import { BURST_SEQUENCE, BURST_WORK, reserveBurstWork } from './burstSequence.js';
 import {
     launchBurst,
     resolveBurstBaseColor,
@@ -317,6 +318,7 @@ function launchRocketWithExplicitTarget(engine, options, explicitTarget) {
         return false;
     }
 
+    const generation = engine.runGeneration;
     const wasRunning = engine.running;
     if (!startLoop(engine)) {
         return false;
@@ -324,7 +326,7 @@ function launchRocketWithExplicitTarget(engine, options, explicitTarget) {
 
     createRocket(engine, options, explicitTarget);
 
-    if (!wasRunning) {
+    if (engine.runGeneration === generation && !wasRunning) {
         engine.finishWhenDone();
     }
 
@@ -332,6 +334,23 @@ function launchRocketWithExplicitTarget(engine, options, explicitTarget) {
 }
 
 
+function resolveCascadeCount(count, sizeScale) {
+    return clamp(Math.floor((count ?? 0) * sizeScale), 0, ROCKET_CASCADE_LIMITS.burstCountMax);
+}
+
+// Only the validated victory recipe reaches this boundary: rocket children,
+// followed by their finite direct-burst cascades. Reserve before any callback.
+function reserveVictoryWork(sequence, rocket) {
+    const childOptions = resolveDefaultCascadeChildLaunchOptions(rocket, rocket.cascade);
+    const normalizedChild = normalizeGroupedPublicOptions(childOptions);
+    const leafCount = resolveCascadeCount(normalizedChild.rocket.cascade.bursts, normalizedChild.sizeScale);
+    const children = Array.from({ length: rocket.cascade.bursts }, () => {
+        const leaves = Array.from({ length: leafCount }, () => reserveBurstWork(sequence));
+        return reserveBurstWork(sequence, leaves);
+    });
+    return reserveBurstWork(sequence, children);
+}
+
 function createRocket(engine, options = {}, explicitTarget = null) {
     const normalizedOptions = normalizeGroupedPublicOptions(options);
     const {
@@ -519,16 +538,8 @@ function createRocket(engine, options = {}, explicitTarget = null) {
             burstCurrentConfig,
         )
         : null;
-    const cascadeBurstCount = clamp(
-        Math.floor((rocketCascadeInput.bursts ?? 0) * sizeScale),
-        0,
-        ROCKET_CASCADE_LIMITS.burstCountMax,
-    );
-    const cascadeChildBurstCount = clamp(
-        Math.floor((rocketCascadeInput.childBursts ?? rocketCascadeInput.bursts ?? 0) * sizeScale),
-        0,
-        ROCKET_CASCADE_LIMITS.burstCountMax,
-    );
+    const cascadeBurstCount = resolveCascadeCount(rocketCascadeInput.bursts, sizeScale);
+    const cascadeChildBurstCount = resolveCascadeCount(rocketCascadeInput.childBursts ?? rocketCascadeInput.bursts, sizeScale);
     const burstCascadeDelayMs = resolveScaledOverride(
         rocketCascadeInput.delay,
         ROCKET_CASCADE_LIMITS.defaultDelayMs,
@@ -617,15 +628,23 @@ function createRocket(engine, options = {}, explicitTarget = null) {
         simple: !!normalizedOptions.simple,
     };
 
+    const work = options[BURST_WORK]
+        ?? (options[BURST_SEQUENCE] ? reserveVictoryWork(options[BURST_SEQUENCE], rocket) : null);
+    if (work) {
+        rocket.sequenceWork = work;
+        rocket.burst = { ...rocket.burst, [BURST_WORK]: work };
+    }
     engine.rockets.push(rocket);
     return rocket;
 }
 
 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 +678,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;
@@ -692,7 +712,11 @@ export function scheduleCascadeBursts(engine, rocket) {
                 cascade,
                 distance,
             );
-            launchRocketFromTo(engine, originX, originY, x, y, childLaunchOptions);
+            launchRocketFromTo(engine, originX, originY, x, y, {
+                ...childLaunchOptions,
+                ...(rocket.sequenceWork ? { [BURST_WORK]: rocket.sequenceWork.children[index] } : {}),
+            });
+            if (engine.runGeneration !== generation) return;
         }
         return;
     }
@@ -711,7 +735,9 @@ export function scheduleCascadeBursts(engine, rocket) {
                 spreadY,
             );
 
-            launchBurst(engine, x, y, burstOptions);
+            launchBurst(engine, x, y, rocket.sequenceWork
+                ? { ...burstOptions, [BURST_WORK]: rocket.sequenceWork.children[index] }
+                : burstOptions);
         }, resolveScaledDelay(engine, delay * (index + 1)));
     }
 }

package/src/runtime.js

@@ -4,6 +4,10 @@ import {
     normalizeGroupedPublicOptions,
 } from './valueNormalizers.js';
 import { buildEngineConfig } from './configBuilder.js';
+import {
+    BURST_SEQUENCE, createBurstSequence, discardBurstSequence, invalidateBurstSequences,
+    supportsSequenceConfig, supportsSequenceLaunch,
+} from './burstSequence.js';
 import {
     resolveFireworksEnginePreset,
     resolveFireworksLaunchPreset,
@@ -285,6 +289,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 +426,10 @@ export class FireworksEngine {
     }
 
     launchPresetAt(name, targetX, targetY, options = {}) {
+        if (options?.trackBurstSequence === true && !supportsSequenceLaunch(this, name, options)) {
+            return false;
+        }
+        const generation = this.runGeneration;
         if (shouldSkipHiddenLaunch(this)) {
             return false;
         }
@@ -443,6 +453,10 @@ export class FireworksEngine {
 
             const launchOptions = { ...mergedOptions };
             delete launchOptions.count;
+            delete launchOptions.trackBurstSequence;
+            if (options.trackBurstSequence === true) {
+                launchOptions[BURST_SEQUENCE] = createBurstSequence(this);
+            }
 
             applyTimeScaleFromLaunchOptions(this, launchOptions);
 
@@ -452,11 +466,12 @@ export class FireworksEngine {
                     ? launchPreset.run(this, targetX, targetY, launchOptions)
                     : false;
                 launched = launched || nextLaunched;
-                if (!nextLaunched) {
+                if (this.runGeneration !== generation || !nextLaunched) {
                     break;
                 }
             }
 
+            if (!launched) discardBurstSequence(this, launchOptions[BURST_SEQUENCE]);
             return launched;
         }
 
@@ -485,7 +500,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;
             }
         }
@@ -608,6 +623,7 @@ export class FireworksEngine {
             this.maxBurstParticlesPerFrame = this.performance.maxBurstParticlesPerFrame;
             this.particlePressureThreshold = this.performance.particlePressureThreshold;
             this.fastRectRadiusThreshold = this.performance.fastRectRadiusThreshold;
+            if (!supportsSequenceConfig(this)) invalidateBurstSequences(this);
         }
 
         if (
@@ -623,8 +639,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 +656,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 +745,8 @@ export class FireworksEngine {
     }
 
     stop(clearCanvas = true) {
+        invalidateBurstSequences(this);
+        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;
         }