fireworks-engine 1.0.0

package/src/colorUtils.js

@@ -0,0 +1,80 @@
+import { clamp } from './mathResolvers.js';
+
+export function parseHexColor(color) {
+    if (typeof color !== 'string') {
+        return null;
+    }
+
+    const match = color.trim().match(/^#([\da-f]{3}|[\da-f]{6})$/i);
+    if (!match) {
+        return null;
+    }
+
+    const normalized = match[1].length === 3
+        ? match[1].split('').map((channel) => `${channel}${channel}`).join('')
+        : match[1];
+
+    return {
+        r: Number.parseInt(normalized.slice(0, 2), 16),
+        g: Number.parseInt(normalized.slice(2, 4), 16),
+        b: Number.parseInt(normalized.slice(4, 6), 16),
+    };
+}
+
+export function toHexChannel(value) {
+    return clamp(Math.round(value), 0, 255).toString(16).padStart(2, '0');
+}
+
+
+export function normalizeHexColor(color, fallback = '#ffd166') {
+    const rgb = parseHexColor(color);
+    if (!rgb) {
+        return fallback;
+    }
+
+    return `#${toHexChannel(rgb.r)}${toHexChannel(rgb.g)}${toHexChannel(rgb.b)}`;
+}
+
+export function mixHexColor(color, targetColor, amount) {
+    const sourceRgb = parseHexColor(color);
+    const targetRgb = parseHexColor(targetColor);
+    if (!sourceRgb || !targetRgb) {
+        return color;
+    }
+
+    const safeAmount = clamp(amount, 0, 1);
+    const inverseAmount = 1 - safeAmount;
+    return `#${toHexChannel((sourceRgb.r * inverseAmount) + (targetRgb.r * safeAmount))}${
+        toHexChannel((sourceRgb.g * inverseAmount) + (targetRgb.g * safeAmount))
+    }${toHexChannel((sourceRgb.b * inverseAmount) + (targetRgb.b * safeAmount))}`;
+}
+
+export function boostHexColor(color, brightnessBoost, saturationBoost = 0) {
+    const rgb = parseHexColor(color);
+    if (!rgb) {
+        return color;
+    }
+
+    const safeSaturationBoost = Math.max(0, saturationBoost);
+    const gray = (rgb.r * 0.299) + (rgb.g * 0.587) + (rgb.b * 0.114);
+    const saturationScale = 1 + safeSaturationBoost;
+    const saturated = {
+        r: gray + ((rgb.r - gray) * saturationScale),
+        g: gray + ((rgb.g - gray) * saturationScale),
+        b: gray + ((rgb.b - gray) * saturationScale),
+    };
+    const brightnessScale = 1 + Math.max(0, brightnessBoost);
+
+    return `#${toHexChannel(saturated.r * brightnessScale)}${
+        toHexChannel(saturated.g * brightnessScale)
+    }${toHexChannel(saturated.b * brightnessScale)}`;
+}
+
+export function toAlphaColor(color, alpha) {
+    const rgb = parseHexColor(color);
+    if (!rgb) {
+        return color;
+    }
+
+    return `rgba(${rgb.r}, ${rgb.g}, ${rgb.b}, ${clamp(alpha, 0, 1)})`;
+}

package/src/configBuilder.js

@@ -0,0 +1,300 @@
+import {
+    DEFAULT_ENABLE_BURST_QUEUE_THROTTLING,
+    DEFAULT_TIME_SCALE,
+    DEFAULT_ROCKET_ENABLED,
+    DEFAULT_ROCKET_STREAK_LENGTH,
+    DEFAULT_ROCKET_FINAL_STREAK_LENGTH,
+    DEFAULT_ROCKET_THICKNESS,
+    DEFAULT_ROCKET_SPEED,
+    DEFAULT_ROCKET_TAIL_EMBERS_ENABLED,
+    DEFAULT_ROCKET_TAIL_EMBERS_COUNT,
+    DEFAULT_ROCKET_TAIL_EMBERS_BRIGHTNESS,
+    DEFAULT_ROCKET_TAIL_EMBERS_FADE,
+    DEFAULT_ROCKET_TAIL_EMBERS_SPREAD_X,
+    DEFAULT_ROCKET_TAIL_EMBERS_SPREAD_Y,
+    DEFAULT_ROCKET_TAIL_EMBERS_SPEED,
+    DEFAULT_ROCKET_TAIL_EMBERS_SIZE,
+    DEFAULT_BURST_COLOR_MODE,
+    DEFAULT_BURST_FORMS_ENABLED,
+    DEFAULT_BURST_FORMS_COUNT,
+    DEFAULT_BURST_FORMS_SPEED_MIN,
+    DEFAULT_BURST_FORMS_SPEED_MAX,
+    DEFAULT_BURST_FORMS_GRAVITY,
+    DEFAULT_BURST_FORMS_LIFE_MIN,
+    DEFAULT_BURST_FORMS_LIFE_MAX,
+    DEFAULT_BURST_FORMS_SIZE_MIN,
+    DEFAULT_BURST_FORMS_SIZE_MAX,
+    DEFAULT_BURST_FORMS_SPIN,
+    DEFAULT_BURST_FORMS_SPIN_COVERAGE,
+    DEFAULT_BURST_FORMS_SPIN_DURATION,
+    DEFAULT_BURST_FORMS_SPIN_PAUSE,
+    DEFAULT_BURST_FORMS_HIGHLIGHT,
+    DEFAULT_BURST_FORMS_HIGHLIGHT_ANGLE_DEG,
+    DEFAULT_BURST_FORMS_HIGHLIGHT_WIDTH,
+    DEFAULT_BURST_FORMS_WOBBLE,
+    DEFAULT_BURST_FORMS_DIRECTION_DEG,
+    DEFAULT_BURST_FORMS_CONE_DEG,
+    DEFAULT_BURST_FORMS_SHAPE,
+    DEFAULT_BURST_FORMS_GLYPH,
+    DEFAULT_BURST_SPARKS_ENABLED,
+    BURST_SPARK_COUNT_BASE,
+    DEFAULT_BURST_SPARK_LENGTH,
+    DEFAULT_BURST_SPARK_DIRECTION_DEG,
+    DEFAULT_BURST_SPARK_CONE_DEG,
+    DEFAULT_BURST_SPARK_TAIL_SCALE,
+    DEFAULT_BURST_SPARK_THICKNESS,
+    DEFAULT_BURST_SPARK_SHAPE,
+    BURST_SPARK_SPEED_MIN_BASE,
+    BURST_SPARK_SPEED_MAX_BASE,
+    DEFAULT_BURST_SPARK_GRAVITY,
+    BURST_SPARK_LIFE_MIN_BASE,
+    BURST_SPARK_LIFE_MAX_BASE,
+    DEFAULT_BURST_CENTER_FLASH_ENABLED,
+    DEFAULT_BURST_CENTER_FLASH_START_SIZE,
+    DEFAULT_BURST_CENTER_FLASH_END_SIZE,
+    DEFAULT_BURST_CENTER_FLASH_PEAK_ALPHA,
+    DEFAULT_BURST_CENTER_FLASH_ATTACK,
+    DEFAULT_BURST_CENTER_FLASH_FADE,
+    DEFAULT_BURST_CENTER_FLASH_COLOR_MODE,
+    DEFAULT_BURST_CENTER_FLASH_COLOR,
+    DEFAULT_BURST_CENTER_FLASH_INNER_STOP,
+    DEFAULT_BURST_TWINKLE_CLOUD_ENABLED,
+    DEFAULT_BURST_TWINKLE_CLOUD_COUNT,
+    DEFAULT_BURST_TWINKLE_CLOUD_RADIUS,
+    DEFAULT_BURST_TWINKLE_CLOUD_START_DELAY,
+    DEFAULT_BURST_TWINKLE_CLOUD_DURATION,
+    DEFAULT_BURST_TWINKLE_CLOUD_TWINKLE_LIFE,
+    DEFAULT_BURST_TWINKLE_CLOUD_BRIGHTNESS,
+    DEFAULT_BURST_TWINKLE_CLOUD_SIZE,
+    DEFAULT_BURST_TWINKLE_CLOUD_SPAWN_SPREAD,
+    DEFAULT_BURST_PALETTE,
+    DEFAULT_BURST_SINGLE_COLOR,
+} from './defaults.js';
+import {
+    resolveSizeScale,
+    resolveTimeScale,
+    resolveOptionalPositiveInteger,
+} from './mathResolvers.js';
+import {
+    resolveBurstFormShape,
+    normalizeBurstFormGlyph,
+    resolveBurstColorMode,
+    resolveBurstFlashColorMode,
+    resolveBurstSparkShape,
+} from './valueNormalizers.js';
+import { normalizeHexColor } from './colorUtils.js';
+
+const MIN_COUNT = 1;
+const MIN_MAX_BURST_PARTICLES_PER_FRAME = 1;
+const MIN_PARTICLE_PRESSURE_THRESHOLD = 1;
+
+function resolveBoolean(value, fallback) {
+    if (typeof value === 'boolean') {
+        return value;
+    }
+
+    return fallback;
+}
+
+function resolvePositiveIntegerOrDefault(value, minValue, fallback) {
+    return resolveOptionalPositiveInteger(value, minValue) ?? fallback;
+}
+
+function resolveRocketConfig(rocket = {}) {
+    return {
+        enabled: resolveBoolean(rocket.enabled, DEFAULT_ROCKET_ENABLED),
+        colorMode: resolveBurstColorMode(rocket.colorMode ?? DEFAULT_BURST_COLOR_MODE),
+        singleColor: normalizeHexColor(
+            rocket.singleColor ?? rocket.color,
+            DEFAULT_BURST_SINGLE_COLOR,
+        ),
+        palette: Array.isArray(rocket.palette) && rocket.palette.length > 0
+            ? rocket.palette
+            : null,
+        streakLength: rocket.streakLength ?? DEFAULT_ROCKET_STREAK_LENGTH,
+        finalStreakLength: rocket.finalStreakLength ?? DEFAULT_ROCKET_FINAL_STREAK_LENGTH,
+        thickness: rocket.thickness ?? DEFAULT_ROCKET_THICKNESS,
+        speed: rocket.speed ?? DEFAULT_ROCKET_SPEED,
+    };
+}
+
+function resolveRocketTailEmbersConfig(rocketTailEmbers = {}) {
+    return {
+        enabled: resolveBoolean(rocketTailEmbers.enabled, DEFAULT_ROCKET_TAIL_EMBERS_ENABLED),
+        count: resolvePositiveIntegerOrDefault(rocketTailEmbers.count, MIN_COUNT, DEFAULT_ROCKET_TAIL_EMBERS_COUNT),
+        brightness: rocketTailEmbers.brightness ?? DEFAULT_ROCKET_TAIL_EMBERS_BRIGHTNESS,
+        fade: rocketTailEmbers.fade ?? DEFAULT_ROCKET_TAIL_EMBERS_FADE,
+        spreadX: rocketTailEmbers.spreadX ?? DEFAULT_ROCKET_TAIL_EMBERS_SPREAD_X,
+        spreadY: rocketTailEmbers.spreadY ?? DEFAULT_ROCKET_TAIL_EMBERS_SPREAD_Y,
+        speed: rocketTailEmbers.speed ?? DEFAULT_ROCKET_TAIL_EMBERS_SPEED,
+        size: rocketTailEmbers.size ?? DEFAULT_ROCKET_TAIL_EMBERS_SIZE,
+    };
+}
+
+function resolveBurstFormsConfig(burstForms = {}) {
+    return {
+        enabled: resolveBoolean(burstForms.enabled, DEFAULT_BURST_FORMS_ENABLED),
+        count: resolvePositiveIntegerOrDefault(burstForms.count, MIN_COUNT, DEFAULT_BURST_FORMS_COUNT),
+        speedMin: burstForms.speedMin ?? DEFAULT_BURST_FORMS_SPEED_MIN,
+        speedMax: burstForms.speedMax ?? DEFAULT_BURST_FORMS_SPEED_MAX,
+        gravity: burstForms.gravity ?? DEFAULT_BURST_FORMS_GRAVITY,
+        lifeMin: burstForms.lifeMin ?? DEFAULT_BURST_FORMS_LIFE_MIN,
+        lifeMax: burstForms.lifeMax ?? DEFAULT_BURST_FORMS_LIFE_MAX,
+        sizeMin: burstForms.sizeMin ?? DEFAULT_BURST_FORMS_SIZE_MIN,
+        sizeMax: burstForms.sizeMax ?? DEFAULT_BURST_FORMS_SIZE_MAX,
+        spin: burstForms.spin ?? DEFAULT_BURST_FORMS_SPIN,
+        spinCoverage: burstForms.spinCoverage ?? DEFAULT_BURST_FORMS_SPIN_COVERAGE,
+        spinDuration: burstForms.spinDuration ?? DEFAULT_BURST_FORMS_SPIN_DURATION,
+        spinPause: burstForms.spinPause ?? DEFAULT_BURST_FORMS_SPIN_PAUSE,
+        highlight: burstForms.highlight ?? DEFAULT_BURST_FORMS_HIGHLIGHT,
+        highlightAngleDeg: burstForms.highlightAngleDeg ?? DEFAULT_BURST_FORMS_HIGHLIGHT_ANGLE_DEG,
+        highlightWidth: burstForms.highlightWidth ?? DEFAULT_BURST_FORMS_HIGHLIGHT_WIDTH,
+        wobble: burstForms.wobble ?? DEFAULT_BURST_FORMS_WOBBLE,
+        directionDeg: burstForms.directionDeg ?? DEFAULT_BURST_FORMS_DIRECTION_DEG,
+        coneDeg: burstForms.coneDeg ?? DEFAULT_BURST_FORMS_CONE_DEG,
+        colorMode: resolveBurstColorMode(burstForms.colorMode ?? DEFAULT_BURST_COLOR_MODE),
+        singleColor: normalizeHexColor(burstForms.singleColor, DEFAULT_BURST_SINGLE_COLOR),
+        shape: resolveBurstFormShape(burstForms.shape ?? DEFAULT_BURST_FORMS_SHAPE),
+        glyph: normalizeBurstFormGlyph(burstForms.glyph, DEFAULT_BURST_FORMS_GLYPH),
+        palette: Array.isArray(burstForms.palette) && burstForms.palette.length > 0
+            ? burstForms.palette
+            : DEFAULT_BURST_PALETTE,
+    };
+}
+
+function resolveBurstSparksConfig(burstSparks = {}) {
+    const burstSparksConfig = {
+        enabled: resolveBoolean(burstSparks.enabled, DEFAULT_BURST_SPARKS_ENABLED),
+        count: resolvePositiveIntegerOrDefault(burstSparks.count, MIN_COUNT, BURST_SPARK_COUNT_BASE),
+        length: burstSparks.length ?? DEFAULT_BURST_SPARK_LENGTH,
+        tailScale: burstSparks.tailScale ?? DEFAULT_BURST_SPARK_TAIL_SCALE,
+        thickness: burstSparks.thickness ?? DEFAULT_BURST_SPARK_THICKNESS,
+        speedMin: burstSparks.speedMin ?? BURST_SPARK_SPEED_MIN_BASE,
+        speedMax: burstSparks.speedMax ?? BURST_SPARK_SPEED_MAX_BASE,
+        gravity: burstSparks.gravity ?? DEFAULT_BURST_SPARK_GRAVITY,
+        lifeMin: burstSparks.lifeMin ?? BURST_SPARK_LIFE_MIN_BASE,
+        lifeMax: burstSparks.lifeMax ?? BURST_SPARK_LIFE_MAX_BASE,
+        directionDeg: burstSparks.directionDeg ?? DEFAULT_BURST_SPARK_DIRECTION_DEG,
+        coneDeg: burstSparks.coneDeg ?? DEFAULT_BURST_SPARK_CONE_DEG,
+        shape: resolveBurstSparkShape(burstSparks.shape ?? DEFAULT_BURST_SPARK_SHAPE),
+        colorMode: resolveBurstColorMode(burstSparks.colorMode ?? DEFAULT_BURST_COLOR_MODE),
+        singleColor: normalizeHexColor(burstSparks.singleColor, DEFAULT_BURST_SINGLE_COLOR),
+        palette: Array.isArray(burstSparks.palette) && burstSparks.palette.length > 0
+            ? burstSparks.palette
+            : null,
+    };
+    burstSparksConfig.speedMax = Math.max(burstSparksConfig.speedMin, burstSparksConfig.speedMax);
+    burstSparksConfig.lifeMax = Math.max(burstSparksConfig.lifeMin, burstSparksConfig.lifeMax);
+    return burstSparksConfig;
+}
+
+function resolveBurstCenterFlashConfig(burstCenterFlash = {}) {
+    return {
+        enabled: resolveBoolean(burstCenterFlash.enabled, DEFAULT_BURST_CENTER_FLASH_ENABLED),
+        startSize: burstCenterFlash.startSize ?? DEFAULT_BURST_CENTER_FLASH_START_SIZE,
+        endSize: burstCenterFlash.endSize ?? DEFAULT_BURST_CENTER_FLASH_END_SIZE,
+        peakAlpha: burstCenterFlash.peakAlpha ?? DEFAULT_BURST_CENTER_FLASH_PEAK_ALPHA,
+        attack: burstCenterFlash.attack ?? DEFAULT_BURST_CENTER_FLASH_ATTACK,
+        fade: burstCenterFlash.fade ?? DEFAULT_BURST_CENTER_FLASH_FADE,
+        colorMode: resolveBurstFlashColorMode(
+            burstCenterFlash.colorMode ?? DEFAULT_BURST_CENTER_FLASH_COLOR_MODE,
+        ),
+        color: normalizeHexColor(burstCenterFlash.color, DEFAULT_BURST_CENTER_FLASH_COLOR),
+        innerStop: burstCenterFlash.innerStop ?? DEFAULT_BURST_CENTER_FLASH_INNER_STOP,
+    };
+}
+
+function resolveBurstTwinkleCloudConfig(burstTwinkleCloud = {}) {
+    return {
+        enabled: resolveBoolean(burstTwinkleCloud.enabled, DEFAULT_BURST_TWINKLE_CLOUD_ENABLED),
+        count: resolvePositiveIntegerOrDefault(burstTwinkleCloud.count, MIN_COUNT, DEFAULT_BURST_TWINKLE_CLOUD_COUNT),
+        radius: burstTwinkleCloud.radius ?? DEFAULT_BURST_TWINKLE_CLOUD_RADIUS,
+        startDelay: burstTwinkleCloud.startDelay ?? DEFAULT_BURST_TWINKLE_CLOUD_START_DELAY,
+        duration: burstTwinkleCloud.duration ?? DEFAULT_BURST_TWINKLE_CLOUD_DURATION,
+        twinkleLife: burstTwinkleCloud.twinkleLife ?? DEFAULT_BURST_TWINKLE_CLOUD_TWINKLE_LIFE,
+        brightness: burstTwinkleCloud.brightness ?? DEFAULT_BURST_TWINKLE_CLOUD_BRIGHTNESS,
+        size: burstTwinkleCloud.size ?? DEFAULT_BURST_TWINKLE_CLOUD_SIZE,
+        spawnSpread: burstTwinkleCloud.spawnSpread ?? DEFAULT_BURST_TWINKLE_CLOUD_SPAWN_SPREAD,
+    };
+}
+
+function resolvePerformanceConfig(
+    performance = {},
+    enableBurstQueueThrottling,
+) {
+    return {
+        enableBurstQueueThrottling,
+        maxBurstParticlesPerFrame: resolvePositiveIntegerOrDefault(performance.maxBurstParticlesPerFrame, MIN_MAX_BURST_PARTICLES_PER_FRAME, 12),
+        particlePressureThreshold: resolvePositiveIntegerOrDefault(performance.particlePressureThreshold, MIN_PARTICLE_PRESSURE_THRESHOLD, 18),
+        fastRectRadiusThreshold: performance.fastRectRadiusThreshold ?? 1.45,
+    };
+}
+
+function resolveRefs(runtime = {}, canvas = {}) {
+    return {
+        documentRef: runtime.document,
+        windowRef: runtime.window,
+        rootRef: canvas.appendTarget ?? runtime.root,
+        prefersReducedMotionRef: runtime.prefersReducedMotion,
+        requestAnimationFrameRef: runtime.requestAnimationFrame,
+        cancelAnimationFrameRef: runtime.cancelAnimationFrame,
+        setTimeoutRef: runtime.setTimeout,
+        clearTimeoutRef: runtime.clearTimeout,
+        nowRef: runtime.now,
+        maxDevicePixelRatio: canvas.maxDevicePixelRatio ?? 2,
+        canvasZIndex: canvas.zIndex ?? 9999,
+    };
+}
+
+export function buildEngineConfig(normalizedOptions = {}) {
+    const safeOptions = normalizedOptions ?? {};
+    const {
+        canvas = {},
+        runtime = {},
+        performance = {},
+        rocket = {},
+        rocketTailEmbers = {},
+        burstForms = {},
+        burstSparks = {},
+        burstCenterFlash = {},
+        burstTwinkleCloud = {},
+    } = safeOptions;
+
+    const enableBurstQueueThrottling = resolveBoolean(
+        performance.enableBurstQueueThrottling,
+        DEFAULT_ENABLE_BURST_QUEUE_THROTTLING,
+    );
+
+    const sizeScale = resolveSizeScale(safeOptions.sizeScale, 1);
+    const timeScale = resolveTimeScale(safeOptions.timeScale, DEFAULT_TIME_SCALE);
+
+    const rocketConfig = resolveRocketConfig(rocket);
+    const rocketTailEmbersConfig = resolveRocketTailEmbersConfig(rocketTailEmbers);
+    const burstFormsConfig = resolveBurstFormsConfig(burstForms);
+    const burstSparksConfig = resolveBurstSparksConfig(burstSparks);
+    const burstCenterFlashConfig = resolveBurstCenterFlashConfig(burstCenterFlash);
+    const burstTwinkleCloudConfig = resolveBurstTwinkleCloudConfig(burstTwinkleCloud);
+    const performanceConfig = resolvePerformanceConfig(
+        performance,
+        enableBurstQueueThrottling,
+    );
+
+    const refs = resolveRefs(runtime, canvas);
+    const toggles = {
+        enableBurstQueueThrottling,
+    };
+
+    return {
+        refs,
+        toggles,
+        timeScale,
+        sizeScale,
+        rocket: rocketConfig,
+        rocketTailEmbers: rocketTailEmbersConfig,
+        burstForms: burstFormsConfig,
+        burstSparks: burstSparksConfig,
+        burstCenterFlash: burstCenterFlashConfig,
+        burstTwinkleCloud: burstTwinkleCloudConfig,
+        performance: performanceConfig,
+    };
+}

package/src/defaults.js

@@ -0,0 +1,87 @@
+export const DEFAULT_ENABLE_BURST_QUEUE_THROTTLING = false;
+export const DEFAULT_TIME_SCALE = 1;
+
+export const DEFAULT_ROCKET_STREAK_LENGTH = 5;
+export const DEFAULT_ROCKET_FINAL_STREAK_LENGTH = 48;
+export const DEFAULT_ROCKET_THICKNESS = 1.35;
+export const DEFAULT_ROCKET_SPEED = 0;
+export const DEFAULT_ROCKET_ENABLED = true;
+
+export const DEFAULT_ROCKET_TAIL_EMBERS_ENABLED = true;
+export const DEFAULT_ROCKET_TAIL_EMBERS_COUNT = 6;
+export const DEFAULT_ROCKET_TAIL_EMBERS_BRIGHTNESS = 2;
+export const DEFAULT_ROCKET_TAIL_EMBERS_FADE = 1;
+export const DEFAULT_ROCKET_TAIL_EMBERS_SPREAD_X = 1.5;
+export const DEFAULT_ROCKET_TAIL_EMBERS_SPREAD_Y = 40;
+export const DEFAULT_ROCKET_TAIL_EMBERS_SPEED = 2;
+export const DEFAULT_ROCKET_TAIL_EMBERS_SIZE = 0.6;
+
+export const DEFAULT_BURST_COLOR_MODE = 'palette';
+
+export const DEFAULT_BURST_FORMS_ENABLED = true;
+export const DEFAULT_BURST_FORMS_COUNT = 27;
+export const DEFAULT_BURST_FORMS_SPEED_MIN = 100;
+export const DEFAULT_BURST_FORMS_SPEED_MAX = 250;
+export const DEFAULT_BURST_FORMS_DIRECTION_DEG = 90;
+export const DEFAULT_BURST_FORMS_CONE_DEG = 360;
+export const DEFAULT_BURST_FORMS_GRAVITY = 90;
+export const DEFAULT_BURST_FORMS_LIFE_MIN = 0.6;
+export const DEFAULT_BURST_FORMS_LIFE_MAX = 1.5;
+export const DEFAULT_BURST_FORMS_SIZE_MIN = 1.5;
+export const DEFAULT_BURST_FORMS_SIZE_MAX = 2.5;
+export const DEFAULT_BURST_FORMS_SPIN = 0;
+export const DEFAULT_BURST_FORMS_SPIN_COVERAGE = 1;
+export const DEFAULT_BURST_FORMS_SPIN_DURATION = 2;
+export const DEFAULT_BURST_FORMS_SPIN_PAUSE = 2;
+export const DEFAULT_BURST_FORMS_HIGHLIGHT = 0;
+export const DEFAULT_BURST_FORMS_HIGHLIGHT_ANGLE_DEG = 0;
+export const DEFAULT_BURST_FORMS_HIGHLIGHT_WIDTH = 0.18;
+export const DEFAULT_BURST_FORMS_WOBBLE = 0;
+export const DEFAULT_BURST_FORMS_SHAPE = 'circle';
+export const DEFAULT_BURST_FORMS_GLYPH = '★';
+
+export const DEFAULT_BURST_SPARKS_ENABLED = true;
+export const DEFAULT_BURST_SPARK_COUNT_RATIO = 1;
+export const BURST_SPARK_COUNT_BASE = 80;
+export const DEFAULT_BURST_SPARK_LENGTH = 27;
+export const DEFAULT_BURST_SPARK_TAIL_SCALE = 1.5;
+export const DEFAULT_BURST_SPARK_THICKNESS = 1.3;
+export const BURST_SPARK_SPEED_MIN_BASE = 0;
+export const BURST_SPARK_SPEED_MAX_BASE = 320;
+export const DEFAULT_BURST_SPARK_DIRECTION_DEG = 90;
+export const DEFAULT_BURST_SPARK_CONE_DEG = 360;
+export const DEFAULT_BURST_SPARK_GRAVITY = 50;
+export const BURST_SPARK_LIFE_MIN_BASE = 0.5;
+export const BURST_SPARK_LIFE_MAX_BASE = 1.6;
+export const DEFAULT_BURST_SPARK_SHAPE = 'fade';
+export const BURST_SPARK_LENGTH_BASE = DEFAULT_BURST_SPARK_LENGTH;
+export const BURST_SPARK_THICKNESS_BASE = DEFAULT_BURST_SPARK_THICKNESS;
+
+export const DEFAULT_BURST_CENTER_FLASH_ENABLED = true;
+export const DEFAULT_BURST_CENTER_FLASH_START_SIZE = 35;
+export const DEFAULT_BURST_CENTER_FLASH_END_SIZE = 85;
+export const DEFAULT_BURST_CENTER_FLASH_PEAK_ALPHA = 0.3;
+export const DEFAULT_BURST_CENTER_FLASH_ATTACK = 0.1;
+export const DEFAULT_BURST_CENTER_FLASH_FADE = 0.1;
+export const DEFAULT_BURST_CENTER_FLASH_COLOR_MODE = 'rgb';
+export const DEFAULT_BURST_CENTER_FLASH_COLOR = '#00ffee';
+export const DEFAULT_BURST_CENTER_FLASH_INNER_STOP = 0.3;
+
+export const DEFAULT_BURST_TWINKLE_CLOUD_ENABLED = true;
+export const DEFAULT_BURST_TWINKLE_CLOUD_COUNT = 240;
+export const DEFAULT_BURST_TWINKLE_CLOUD_RADIUS = 110;
+export const DEFAULT_BURST_TWINKLE_CLOUD_START_DELAY = 0.4;
+export const DEFAULT_BURST_TWINKLE_CLOUD_DURATION = 0.5;
+export const DEFAULT_BURST_TWINKLE_CLOUD_TWINKLE_LIFE = 0.2;
+export const DEFAULT_BURST_TWINKLE_CLOUD_BRIGHTNESS = 2;
+export const DEFAULT_BURST_TWINKLE_CLOUD_SIZE = 1.2;
+export const DEFAULT_BURST_TWINKLE_CLOUD_SPAWN_SPREAD = 1;
+export const WHITE_BRIGHTNESS_REFERENCE = 2;
+
+export const DEFAULT_BURST_PALETTE = ['#ffd166', '#ff6b6b', '#4ecdc4', '#74c0fc', '#c77dff', '#ffffff'];
+export const DEFAULT_ROCKET_PALETTE = ['#ffd166', '#ff6b6b', '#74c0fc', '#ffffff'];
+export const DEFAULT_BURST_SINGLE_COLOR = '#ffd166';
+
+export const BURST_FLASH_ATTACK_UNIT = 0.01;
+export const GLYPH_SPRITE_SIZE_MIN = 8;
+export const GLYPH_SPRITE_RADIUS_SCALE = 3.2;

package/src/index.js

@@ -0,0 +1,13 @@
+import FireworksEngineDefault, {
+    FireworksEngine,
+    createFireworksEngine,
+} from './runtime.js';
+import { resolveFireworksEnginePreset } from './presets.js';
+
+export {
+    FireworksEngine,
+    createFireworksEngine,
+    resolveFireworksEnginePreset,
+};
+
+export default FireworksEngineDefault;

package/src/mathResolvers.js

@@ -0,0 +1,77 @@
+const MIN_SCALE_EPSILON = 0.0001;
+const SIZE_SCALE_MIN = MIN_SCALE_EPSILON;
+const TIME_SCALE_MIN = 0.05;
+
+export function resolveFinite(value, fallback) {
+    if (Number.isFinite(value)) {
+        return value;
+    }
+
+    if (Number.isFinite(fallback)) {
+        return fallback;
+    }
+
+    return 0;
+}
+
+export function clamp(value, min, max) {
+    return Math.min(Math.max(value, min), max);
+}
+
+export function randomRange(min, max) {
+    return Math.random() * (max - min) + min;
+}
+
+export function resolveScaledOverride(value, fallback, scale = 1) {
+    const base = resolveFinite(value, fallback);
+    const safeScale = Number.isFinite(scale) ? scale : 1;
+    const scaled = base * safeScale;
+    return Number.isFinite(scaled) ? scaled : resolveFinite(fallback, base);
+}
+
+export function resolveScaledInverseOverride(value, fallback, scale = 1) {
+    const numericScale = Number.isFinite(scale) ? scale : 1;
+    const safeScaleMagnitude = Math.max(Math.abs(numericScale), MIN_SCALE_EPSILON);
+    const safeScale = numericScale < 0 ? -safeScaleMagnitude : safeScaleMagnitude;
+    const base = resolveFinite(value, fallback);
+    const scaled = base / safeScale;
+    return Number.isFinite(scaled) ? scaled : resolveFinite(fallback, base);
+}
+
+export function resolveScaledInteger(value, fallback, min = 1, scale = 1) {
+    const safeMin = Number.isFinite(min) ? min : 1;
+    const base = resolveFinite(value, fallback);
+    const safeScale = Number.isFinite(scale) ? scale : 1;
+    const scaled = Math.floor(base * safeScale);
+    if (!Number.isFinite(scaled)) {
+        return Math.max(safeMin, Math.floor(resolveFinite(fallback, safeMin)));
+    }
+
+    return Math.max(safeMin, scaled);
+}
+
+
+export function resolveSizeScale(value, fallback = 1) {
+    return Math.max(SIZE_SCALE_MIN, resolveFinite(value, fallback));
+}
+
+export function resolveTimeScale(value, fallback = 1) {
+    return Math.max(TIME_SCALE_MIN, resolveFinite(value, fallback));
+}
+
+export function resolveEnvelopeTimeScale(sizeScale) {
+    return Math.sqrt(resolveSizeScale(sizeScale, 1));
+}
+
+export function resolveOptionalPositiveInteger(value, min = 1) {
+    if (!Number.isFinite(value) || value <= 0) {
+        return null;
+    }
+
+    const normalized = Math.floor(value);
+    if (!Number.isFinite(normalized)) {
+        return null;
+    }
+
+    return Math.max(min, normalized);
+}