fireworks-engine 1.0.1 → 1.0.2

package/README.md

@@ -85,6 +85,53 @@ 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

@@ -192,6 +192,23 @@ export interface FireworksRocketLaunchOptions extends FireworksBurstOverrideOpti
 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;
@@ -636,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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fireworks-engine",
-  "version": "1.0.1",
+  "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 && node --test test/burst-events.test.js"
+    "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

@@ -4,15 +4,18 @@ export function isCurrentRun(engine, generation) {
     return engine.runGeneration === generation;
 }
 
-export function createBurstEvent(engine, x, y) {
-    return { generation: engine.runGeneration, x, y, notified: false };
+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 });
+        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,4 +1,5 @@
 import { createBurstEvent, isCurrentRun, notifyBurst } from './burstEvents.js';
+import { BURST_WORK } from './burstSequence.js';
 import {
     BURST_FLASH_ATTACK_UNIT,
     DEFAULT_BURST_SINGLE_COLOR,
@@ -264,7 +265,7 @@ function spawnBurstExtras(engine, burst, flashOptions, cloudOptions) {
     return isCurrentRun(engine, burst.generation);
 }
 
-function enqueueBurst(engine, x, y, options = {}) {
+function enqueueBurst(engine, x, y, options = {}, work) {
     if (!engine.running) {
         return false;
     }
@@ -274,7 +275,7 @@ function enqueueBurst(engine, x, y, options = {}) {
         resolveBurstCurrentConfig(engine),
     );
     const requests = createBurstRequests(x, y, burstOptions, options);
-    const burst = createBurstEvent(engine, x, y);
+    const burst = createBurstEvent(engine, x, y, work);
     requests.forEach((request) => { request.burstEvent = burst; });
 
     if (requests.length === 0) {
@@ -611,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) {
@@ -622,7 +623,7 @@ export function launchBurst(engine, x, y, options = {}) {
         normalizedOptions,
         resolveBurstCurrentConfig(engine),
     );
-    const burst = createBurstEvent(engine, x, y);
+    const burst = createBurstEvent(engine, x, y, options[BURST_WORK]);
     if (!spawnBurstExtras(engine, burst, normalizedOptions, normalizedOptions)) return true;
     const requests = createBurstRequests(x, y, burstOptions);
     for (const request of requests) {

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,
@@ -333,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 {
@@ -520,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,
@@ -618,6 +628,12 @@ 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;
 }
@@ -696,7 +712,10 @@ 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;
@@ -716,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,
@@ -422,6 +426,9 @@ 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;
@@ -446,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);
 
@@ -460,6 +471,7 @@ export class FireworksEngine {
                 }
             }
 
+            if (!launched) discardBurstSequence(this, launchOptions[BURST_SEQUENCE]);
             return launched;
         }
 
@@ -611,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 (
@@ -732,6 +745,7 @@ export class FireworksEngine {
     }
 
     stop(clearCanvas = true) {
+        invalidateBurstSequences(this);
         this.runGeneration += 1;
         const wasRunning = this.running;
         this.running = false;