@tsparticles/ribbons 4.2.1 → 4.3.0

package/tsparticles.ribbons.bundle.js

@@ -1,5 +1,5 @@
 (function(g){g.__tsParticlesInternals=g.__tsParticlesInternals||{};g.__tsParticlesInternals.bundles=g.__tsParticlesInternals.bundles||{};g.__tsParticlesInternals.effects=g.__tsParticlesInternals.effects||{};g.__tsParticlesInternals.engine=g.__tsParticlesInternals.engine||{};g.__tsParticlesInternals.interactions=g.__tsParticlesInternals.interactions||{};g.__tsParticlesInternals.palettes=g.__tsParticlesInternals.palettes||{};g.__tsParticlesInternals.paths=g.__tsParticlesInternals.paths||{};g.__tsParticlesInternals.plugins=g.__tsParticlesInternals.plugins||{};g.__tsParticlesInternals.plugins=g.__tsParticlesInternals.plugins||{};g.__tsParticlesInternals.plugins.emittersShapes=g.__tsParticlesInternals.plugins.emittersShapes||{};g.__tsParticlesInternals.presets=g.__tsParticlesInternals.presets||{};g.__tsParticlesInternals.shapes=g.__tsParticlesInternals.shapes||{};g.__tsParticlesInternals.updaters=g.__tsParticlesInternals.updaters||{};g.__tsParticlesInternals.utils=g.__tsParticlesInternals.utils||{};g.__tsParticlesInternals.canvas=g.__tsParticlesInternals.canvas||{};g.__tsParticlesInternals.canvas=g.__tsParticlesInternals.canvas||{};g.__tsParticlesInternals.canvas.utils=g.__tsParticlesInternals.canvas.utils||{};g.__tsParticlesInternals.path=g.__tsParticlesInternals.path||{};g.__tsParticlesInternals.path=g.__tsParticlesInternals.path||{};g.__tsParticlesInternals.path.utils=g.__tsParticlesInternals.path.utils||{};var __tsProxyFactory=typeof Proxy!=="undefined"?function(obj){return new Proxy(obj,{get:function(target,key){if(!(key in target)){target[key]={};}return target[key];}});}:function(obj){return obj;};g.__tsParticlesInternals.bundles=__tsProxyFactory(g.__tsParticlesInternals.bundles);g.__tsParticlesInternals.effects=__tsProxyFactory(g.__tsParticlesInternals.effects);g.__tsParticlesInternals.interactions=__tsProxyFactory(g.__tsParticlesInternals.interactions);g.__tsParticlesInternals.palettes=__tsProxyFactory(g.__tsParticlesInternals.palettes);g.__tsParticlesInternals.paths=__tsProxyFactory(g.__tsParticlesInternals.paths);g.__tsParticlesInternals.plugins=__tsProxyFactory(g.__tsParticlesInternals.plugins);g.__tsParticlesInternals.plugins.emittersShapes=__tsProxyFactory(g.__tsParticlesInternals.plugins.emittersShapes);g.__tsParticlesInternals.presets=__tsProxyFactory(g.__tsParticlesInternals.presets);g.__tsParticlesInternals.shapes=__tsProxyFactory(g.__tsParticlesInternals.shapes);g.__tsParticlesInternals.updaters=__tsProxyFactory(g.__tsParticlesInternals.updaters);g.__tsParticlesInternals.utils=__tsProxyFactory(g.__tsParticlesInternals.utils);g.__tsParticlesInternals.canvas=__tsProxyFactory(g.__tsParticlesInternals.canvas);g.__tsParticlesInternals.path=__tsProxyFactory(g.__tsParticlesInternals.path);g.tsparticlesInternalExports=g.tsparticlesInternalExports||{};})(typeof globalThis!=="undefined"?globalThis:typeof window!=="undefined"?window:this);
-/* tsParticles v4.2.1 */
+/* tsParticles v4.3.0 */
 (function (global, factory) {
     typeof exports === 'object' && typeof module !== 'undefined' ? factory(exports) :
     typeof define === 'function' && define.amd ? define(['exports'], factory) :
@@ -398,29 +398,27 @@
                 }
             }
             else if (!isObject(destination) || Array.isArray(destination)) {
-                destination = {};
+                destination = Object.create(null);
             }
-            const sourceKeys = Object.keys(source), dangerousKeys = new Set(["__proto__", "constructor", "prototype"]), hasNested = sourceKeys.some(k => {
+            const sourceKeys = Object.keys(source), hasNested = sourceKeys.some(k => {
                 const v = source[k];
                 return isObject(v) || Array.isArray(v);
             });
             if (!hasNested) {
                 const sourceDict = source, destDict = destination;
                 for (const key of sourceKeys) {
-                    if (dangerousKeys.has(key)) {
+                    if (key === "__proto__" || key === "constructor" || key === "prototype") {
                         continue;
                     }
-                    if (key in sourceDict) {
-                        const v = sourceDict[key];
-                        if (v !== undefined) {
-                            destDict[key] = v;
-                        }
+                    const v = sourceDict[key];
+                    if (v !== undefined) {
+                        destDict[key] = v;
                     }
                 }
                 continue;
             }
             for (const key of sourceKeys) {
-                if (dangerousKeys.has(key)) {
+                if (key === "__proto__" || key === "constructor" || key === "prototype") {
                     continue;
                 }
                 const sourceDict = source, destDict = destination, value = sourceDict[key];
@@ -879,7 +877,7 @@
             return this.#domArray;
         }
         get version() {
-            return "4.2.1";
+            return "4.3.0";
         }
         addEventListener(type, listener) {
             this.#eventDispatcher.addEventListener(type, listener);
@@ -1112,6 +1110,18 @@
         AnimationStatus["decreasing"] = "decreasing";
     })(exports.AnimationStatus || (exports.AnimationStatus = {}));
 
+    exports.DrawLayer = void 0;
+    (function (DrawLayer) {
+        DrawLayer[DrawLayer["BackgroundElement"] = 0] = "BackgroundElement";
+        DrawLayer[DrawLayer["BackgroundDraw"] = 1] = "BackgroundDraw";
+        DrawLayer[DrawLayer["BackgroundMask"] = 2] = "BackgroundMask";
+        DrawLayer[DrawLayer["CanvasSetup"] = 3] = "CanvasSetup";
+        DrawLayer[DrawLayer["PluginContent"] = 4] = "PluginContent";
+        DrawLayer[DrawLayer["Particles"] = 5] = "Particles";
+        DrawLayer[DrawLayer["CanvasCleanup"] = 6] = "CanvasCleanup";
+        DrawLayer[DrawLayer["Foreground"] = 7] = "Foreground";
+    })(exports.DrawLayer || (exports.DrawLayer = {}));
+
     class OptionLoader {
         load(data) {
             if (isNull(data)) {
@@ -1270,6 +1280,8 @@
 
     class Background extends OptionLoader {
         color;
+        draw;
+        element;
         image = "";
         opacity = 1;
         position = "";
@@ -1284,6 +1296,8 @@
             if (data.color !== undefined) {
                 this.color = OptionsColor.create(this.color, data.color);
             }
+            loadProperty(this, "element", data.element);
+            loadProperty(this, "draw", data.draw);
             loadProperty(this, "image", data.image);
             loadProperty(this, "position", data.position);
             loadProperty(this, "repeat", data.repeat);
@@ -1829,7 +1843,7 @@
         }
     }
 
-    const styleCache = new Map(), maxStyleCacheSize = 2000, rgbFixedPrecision = 2, hslFixedPrecision = 2, sdrReferenceWhiteNits = 203;
+    const styleCache = new Map(), maxStyleCacheSize = 2000, rgbFixedPrecision = 2, hslFixedPrecision = 2, hdrRgbFixedPrecision = 4, hdrHslFixedPrecision = 4, sdrReferenceWhiteNits = 203, hdrAnimationScale = sdrReferenceWhiteNits / maxNits;
     function getCachedStyle(key, generator) {
         let cached = styleCache.get(key);
         if (!cached) {
@@ -1972,6 +1986,17 @@
             : lNormalized + sNormalized - lNormalized * sNormalized, temp2 = double * lNormalized - temp1, phaseThird = phaseNumerator / triple, red = Math.min(rgbMax, rgbMax * hslChannel(temp2, temp1, hNormalized + phaseThird)), green = Math.min(rgbMax, rgbMax * hslChannel(temp2, temp1, hNormalized)), blue = Math.min(rgbMax, rgbMax * hslChannel(temp2, temp1, hNormalized - phaseThird));
         return { r: Math.round(red), g: Math.round(green), b: Math.round(blue) };
     }
+    function hslToRgbFloat(hsl) {
+        const h = ((hsl.h % hMax) + hMax) % hMax, s = Math.max(sMin, Math.min(sMax, hsl.s)), l = Math.max(lMin, Math.min(lMax, hsl.l)), hNormalized = h / hMax, sNormalized = s / sMax, lNormalized = l / lMax;
+        if (s === sMin) {
+            const grayscaleValue = lNormalized * rgbMax;
+            return { r: grayscaleValue, g: grayscaleValue, b: grayscaleValue };
+        }
+        const temp1 = lNormalized < half$1
+            ? lNormalized * (sNormalizedOffset + sNormalized)
+            : lNormalized + sNormalized - lNormalized * sNormalized, temp2 = double * lNormalized - temp1, phaseThird = phaseNumerator / triple, red = Math.min(rgbMax, rgbMax * hslChannel(temp2, temp1, hNormalized + phaseThird)), green = Math.min(rgbMax, rgbMax * hslChannel(temp2, temp1, hNormalized)), blue = Math.min(rgbMax, rgbMax * hslChannel(temp2, temp1, hNormalized - phaseThird));
+        return { r: red, g: green, b: blue };
+    }
     function hslaToRgba(hsla) {
         const rgbResult = hslToRgb(hsla);
         return {
@@ -1981,8 +2006,16 @@
             r: rgbResult.r,
         };
     }
-    function getRandomRgbColor(min) {
-        const fixedMin = min ?? defaultRgbMin, fixedMax = rgbMax + identity$2, getRgbInRangeValue = () => Math.floor(getRandomInRange(fixedMin, fixedMax));
+    function getRandomRgbColor(min, hdr) {
+        const fixedMin = min ?? defaultRgbMin;
+        if (hdr) {
+            return {
+                r: getRandomInRange(fixedMin, rgbMax),
+                g: getRandomInRange(fixedMin, rgbMax),
+                b: getRandomInRange(fixedMin, rgbMax),
+            };
+        }
+        const fixedMax = rgbMax + identity$2, getRgbInRangeValue = () => Math.floor(getRandomInRange(fixedMin, fixedMax));
         return {
             b: getRgbInRangeValue(),
             g: getRgbInRangeValue(),
@@ -1990,7 +2023,7 @@
         };
     }
     function getStyleFromRgb(color, hdr, opacity) {
-        const op = opacity ?? defaultOpacity$1, key = `rgb-${color.r.toFixed(rgbFixedPrecision)}-${color.g.toFixed(rgbFixedPrecision)}-${color.b.toFixed(rgbFixedPrecision)}-${hdr ? "hdr" : "sdr"}-${op.toString()}`;
+        const rgbPrecision = hdr ? hdrRgbFixedPrecision : rgbFixedPrecision, op = opacity ?? defaultOpacity$1, key = `rgb-${color.r.toFixed(rgbPrecision)}-${color.g.toFixed(rgbPrecision)}-${color.b.toFixed(rgbPrecision)}-${hdr ? "hdr" : "sdr"}-${op.toString()}`;
         return getCachedStyle(key, () => (hdr ? getHdrStyleFromRgb(color, opacity) : getSdrStyleFromRgb(color, opacity)));
     }
     function getHdrStyleFromRgb(color, opacity, peakNits = maxNits) {
@@ -2001,9 +2034,9 @@
         return `rgba(${color.r.toString()}, ${color.g.toString()}, ${color.b.toString()}, ${(opacity ?? defaultOpacity$1).toString()})`;
     }
     function getStyleFromHsl(color, hdr, opacity) {
-        const op = opacity ?? defaultOpacity$1, key = `hsl-${color.h.toFixed(hslFixedPrecision)}-${color.s.toFixed(hslFixedPrecision)}-${color.l.toFixed(hslFixedPrecision)}-${hdr ? "hdr" : "sdr"}-${op.toString()}`;
+        const hslPrecision = hdr ? hdrHslFixedPrecision : hslFixedPrecision, op = opacity ?? defaultOpacity$1, key = `hsl-${color.h.toFixed(hslPrecision)}-${color.s.toFixed(hslPrecision)}-${color.l.toFixed(hslPrecision)}-${hdr ? "hdr" : "sdr"}-${op.toString()}`;
         return getCachedStyle(key, () => hdr
-            ? getStyleFromRgb(hslToRgb(color), true, opacity)
+            ? getStyleFromRgb(hslToRgbFloat(color), true, opacity)
             : `hsla(${color.h.toString()}, ${color.s.toString()}%, ${color.l.toString()}%, ${op.toString()})`);
     }
     function colorMix(color1, color2, size1, size2) {
@@ -2123,7 +2156,7 @@
             colorValue.velocity = defaultVelocity;
         }
     }
-    function updateColorValue(data, decrease, delta) {
+    function updateColorValue(data, decrease, delta, hdr) {
         const minLoops = 0, minDelay = 0, identity = 1, minVelocity = 0, minOffset = 0, velocityFactor = 3.6;
         if (!data.enable ||
             ((data.maxLoops ?? minLoops) > minLoops && (data.loops ?? minLoops) > (data.maxLoops ?? minLoops))) {
@@ -2136,7 +2169,7 @@
         if ((data.delayTime ?? minDelay) > minDelay && data.time < (data.delayTime ?? minDelay)) {
             return;
         }
-        const offset = data.offset ? randomInRangeValue(data.offset) : minOffset, velocity = (data.velocity ?? minVelocity) * delta.factor + offset * velocityFactor, decay = data.decay ?? identity, max = data.max, min = data.min;
+        const offset = data.offset ? randomInRangeValue(data.offset) : minOffset, velocity = ((data.velocity ?? minVelocity) * delta.factor + offset * velocityFactor) * (hdr ? hdrAnimationScale : identity), decay = data.decay ?? identity, max = data.max, min = data.min;
         if (!decrease || data.status === exports.AnimationStatus.increasing) {
             data.value += velocity;
             if (data.value > max) {
@@ -2163,14 +2196,14 @@
         }
         data.value = clamp(data.value, min, max);
     }
-    function updateColor(color, delta) {
+    function updateColor(color, delta, hdr) {
         if (!color) {
             return;
         }
         const { h, s, l } = color;
-        updateColorValue(h, false, delta);
-        updateColorValue(s, true, delta);
-        updateColorValue(l, true, delta);
+        updateColorValue(h, false, delta, hdr);
+        updateColorValue(s, true, delta, hdr);
+        updateColorValue(l, true, delta, hdr);
     }
     function alterHsl(color, type, value) {
         return {
@@ -2220,7 +2253,7 @@
     }
 
     async function loadBlendPlugin(engine) {
-        engine.checkVersion("4.2.1");
+        engine.checkVersion("4.3.0");
         await engine.pluginManager.register(e => {
             e.pluginManager.addPlugin(new BlendPlugin());
         });
@@ -2257,7 +2290,7 @@
     }
 
     async function loadCircleShape(engine) {
-        engine.checkVersion("4.2.1");
+        engine.checkVersion("4.3.0");
         await engine.pluginManager.register(e => {
             e.pluginManager.addShape(["circle"], () => {
                 return Promise.resolve(new CircleDrawer());
@@ -2305,7 +2338,7 @@
     }
 
     async function loadHexColorPlugin(engine) {
-        engine.checkVersion("4.2.1");
+        engine.checkVersion("4.3.0");
         await engine.pluginManager.register(e => {
             e.pluginManager.addColorManager("hex", new HexColorManager());
         });
@@ -2358,7 +2391,7 @@
     }
 
     async function loadHslColorPlugin(engine) {
-        engine.checkVersion("4.2.1");
+        engine.checkVersion("4.3.0");
         await engine.pluginManager.register(e => {
             e.pluginManager.addColorManager("hsl", new HslColorManager());
         });
@@ -2382,7 +2415,7 @@
     }
 
     async function loadMovePlugin(engine) {
-        engine.checkVersion("4.2.1");
+        engine.checkVersion("4.3.0");
         await engine.pluginManager.register(e => {
             const moveEngine = e, movePluginManager = moveEngine.pluginManager;
             movePluginManager.initializers.pathGenerators ??= new Map();
@@ -2592,7 +2625,7 @@
     }
 
     async function loadOpacityUpdater(engine) {
-        engine.checkVersion("4.2.1");
+        engine.checkVersion("4.3.0");
         await engine.pluginManager.register(e => {
             e.pluginManager.addParticleUpdater("opacity", container => {
                 return Promise.resolve(new OpacityUpdater(container));
@@ -2937,7 +2970,7 @@
     }
 
     async function loadOutModesUpdater(engine) {
-        engine.checkVersion("4.2.1");
+        engine.checkVersion("4.3.0");
         await engine.pluginManager.register(e => {
             e.pluginManager.addParticleUpdater("outModes", container => {
                 return Promise.resolve(new OutOfCanvasUpdater(container));
@@ -3002,13 +3035,13 @@
             if (!this.isEnabled(particle)) {
                 return;
             }
-            updateColor(particle.fillColor, delta);
-            updateColor(particle.strokeColor, delta);
+            updateColor(particle.fillColor, delta, this.#container.hdr);
+            updateColor(particle.strokeColor, delta, this.#container.hdr);
         }
     }
 
     async function loadPaintUpdater(engine) {
-        engine.checkVersion("4.2.1");
+        engine.checkVersion("4.3.0");
         await engine.pluginManager.register(e => {
             e.pluginManager.addParticleUpdater("paint", container => {
                 return Promise.resolve(new PaintUpdater(e.pluginManager, container));
@@ -3063,7 +3096,7 @@
     }
 
     async function loadRgbColorPlugin(engine) {
-        engine.checkVersion("4.2.1");
+        engine.checkVersion("4.3.0");
         await engine.pluginManager.register(e => {
             e.pluginManager.addColorManager("rgb", new RgbColorManager());
         });
@@ -3148,7 +3181,7 @@
     }
 
     async function loadSizeUpdater(engine) {
-        engine.checkVersion("4.2.1");
+        engine.checkVersion("4.3.0");
         await engine.pluginManager.register(e => {
             e.pluginManager.addParticleUpdater("size", container => {
                 return Promise.resolve(new SizeUpdater(container));
@@ -3157,7 +3190,7 @@
     }
 
     async function loadBasic(engine) {
-        engine.checkVersion("4.2.1");
+        engine.checkVersion("4.3.0");
         await engine.pluginManager.register(async (e) => {
             await Promise.all([
                 loadBlendPlugin(e),
@@ -3397,7 +3430,7 @@
     })(EmitterClickMode || (EmitterClickMode = {}));
 
     async function loadEmittersPluginSimple(engine) {
-        engine.checkVersion("4.2.1");
+        engine.checkVersion("4.3.0");
         await engine.pluginManager.register(async (e) => {
             const instancesManager = await getEmittersInstancesManager(e);
             await addEmittersShapesManager(e);
@@ -3485,7 +3518,7 @@
     }
 
     async function loadEmittersShapeSquare(engine) {
-        engine.checkVersion("4.2.1");
+        engine.checkVersion("4.3.0");
         await engine.pluginManager.register((e) => {
             ensureEmittersPluginLoaded(e);
             e.pluginManager.addEmitterShapeGenerator?.("square", new EmittersSquareShapeGenerator());
@@ -3629,7 +3662,7 @@
     }
 
     async function loadLifeUpdater(engine) {
-        engine.checkVersion("4.2.1");
+        engine.checkVersion("4.3.0");
         await engine.pluginManager.register(e => {
             e.pluginManager.addParticleUpdater("life", container => {
                 return Promise.resolve(new LifeUpdater(container));
@@ -3683,7 +3716,7 @@
     }
 
     async function loadMotionPlugin(engine) {
-        engine.checkVersion("4.2.1");
+        engine.checkVersion("4.3.0");
         await engine.pluginManager.register(e => {
             e.pluginManager.addPlugin(new MotionPlugin());
         });
@@ -4081,7 +4114,7 @@
     }
 
     async function loadRibbonShape(engine) {
-        engine.checkVersion("4.2.1");
+        engine.checkVersion("4.3.0");
         await engine.pluginManager.register(e => {
             e.pluginManager.addShape(["ribbon"], (container) => Promise.resolve(new RibbonDrawer(container)));
         });
@@ -4401,7 +4434,7 @@
 
     let initPromise = null;
     async function doInitPlugins(engine) {
-        engine.checkVersion("4.2.1");
+        engine.checkVersion("4.3.0");
         await engine.pluginManager.register(async (e) => {
             const emittersRegister = async (engine) => {
                 await loadEmittersPluginSimple(engine);
@@ -4468,7 +4501,7 @@
     ribbons.init = async () => {
         await initPlugins(tsParticles);
     };
-    ribbons.version = "4.2.1";
+    ribbons.version = "4.3.0";
     globalThis.ribbons = ribbons;
 
     const globalObject = globalThis;
@@ -4483,10 +4516,10 @@
         }
     }
     class RenderManager {
+        #backgroundElement;
+        #backgroundWarnings;
         #canvasClearPlugins;
         #canvasManager;
-        #canvasPaintPlugins;
-        #clearDrawPlugins;
         #colorPlugins;
         #container;
         #context;
@@ -4494,9 +4527,7 @@
         #drawParticlePlugins;
         #drawParticlesCleanupPlugins;
         #drawParticlesSetupPlugins;
-        #drawPlugins;
-        #drawSettingsCleanupPlugins;
-        #drawSettingsSetupPlugins;
+        #layers;
         #pluginManager;
         #postDrawUpdaters;
         #preDrawUpdaters;
@@ -4508,18 +4539,25 @@
             this.#container = container;
             this.#canvasManager = canvasManager;
             this.#context = null;
+            this.#backgroundElement = null;
+            this.#backgroundWarnings = new Set();
             this.#preDrawUpdaters = [];
             this.#postDrawUpdaters = [];
-            this.#colorPlugins = [];
             this.#canvasClearPlugins = [];
-            this.#canvasPaintPlugins = [];
-            this.#clearDrawPlugins = [];
+            this.#colorPlugins = [];
             this.#drawParticlePlugins = [];
             this.#drawParticlesCleanupPlugins = [];
             this.#drawParticlesSetupPlugins = [];
-            this.#drawPlugins = [];
-            this.#drawSettingsSetupPlugins = [];
-            this.#drawSettingsCleanupPlugins = [];
+            this.#layers = {
+                0: [],
+                1: [],
+                2: [],
+                3: [],
+                4: [],
+                5: [],
+                6: [],
+                7: [],
+            };
         }
         get settings() {
             return this.#contextSettings;
@@ -4533,32 +4571,38 @@
             });
         }
         clear() {
-            let pluginHandled = false;
             for (const plugin of this.#canvasClearPlugins) {
-                pluginHandled = plugin.canvasClear?.() ?? false;
-                if (pluginHandled) {
-                    break;
+                if (plugin.canvasClear?.() ?? false) {
+                    return;
                 }
             }
-            if (pluginHandled) {
-                return;
+            for (const layer of Object.values(exports.DrawLayer)) {
+                if (typeof layer === "number") {
+                    for (const plugin of this.#getLayerPlugins(layer)) {
+                        if (plugin.canvasClear?.() ?? false) {
+                            return;
+                        }
+                    }
+                }
             }
             this.canvasClear();
         }
         destroy() {
             this.stop();
+            this.#backgroundElement = null;
+            this.#backgroundWarnings.clear();
             this.#preDrawUpdaters = [];
             this.#postDrawUpdaters = [];
-            this.#colorPlugins = [];
             this.#canvasClearPlugins = [];
-            this.#canvasPaintPlugins = [];
-            this.#clearDrawPlugins = [];
+            this.#colorPlugins = [];
             this.#drawParticlePlugins = [];
             this.#drawParticlesCleanupPlugins = [];
             this.#drawParticlesSetupPlugins = [];
-            this.#drawPlugins = [];
-            this.#drawSettingsSetupPlugins = [];
-            this.#drawSettingsCleanupPlugins = [];
+            for (const layer of Object.values(exports.DrawLayer)) {
+                if (typeof layer === "number") {
+                    this.#layers[layer] = [];
+                }
+            }
         }
         draw(cb) {
             const ctx = this.#context;
@@ -4615,21 +4659,40 @@
             });
         }
         drawParticles(delta) {
-            const { particles } = this.#container;
+            const { particles, actualOptions } = this.#container;
             this.clear();
             particles.update(delta);
             this.draw(ctx => {
-                for (const plugin of this.#drawSettingsSetupPlugins) {
+                const width = this.#canvasManager.size.width, height = this.#canvasManager.size.height;
+                if (this.#backgroundElement) {
+                    try {
+                        ctx.drawImage(this.#backgroundElement, originPoint.x, originPoint.y, width, height);
+                    }
+                    catch {
+                        this.#warnOnce("background-element-draw-error", "Error drawing background element onto canvas");
+                    }
+                }
+                const background = actualOptions.background;
+                if (background.draw) {
+                    try {
+                        background.draw(ctx, delta);
+                    }
+                    catch {
+                        this.#warnOnce("background-draw-error", "Error in background.draw callback");
+                    }
+                }
+                for (const plugin of this.#getLayerPlugins(exports.DrawLayer.BackgroundMask)) {
+                    plugin.canvasPaint?.();
+                }
+                for (const plugin of this.#getLayerPlugins(exports.DrawLayer.CanvasSetup)) {
                     plugin.drawSettingsSetup?.(ctx, delta);
                 }
-                for (const plugin of this.#drawPlugins) {
+                for (const plugin of this.#getLayerPlugins(exports.DrawLayer.PluginContent)) {
                     plugin.draw?.(ctx, delta);
                 }
                 particles.drawParticles(delta);
-                for (const plugin of this.#clearDrawPlugins) {
+                for (const plugin of this.#getLayerPlugins(exports.DrawLayer.CanvasCleanup)) {
                     plugin.clearDraw?.(ctx, delta);
-                }
-                for (const plugin of this.#drawSettingsCleanupPlugins) {
                     plugin.drawSettingsCleanup?.(ctx, delta);
                 }
             });
@@ -4637,29 +4700,24 @@
         init() {
             this.initUpdaters();
             this.initPlugins();
+            this.#resolveBackgroundElement();
             this.paint();
         }
         initPlugins() {
-            this.#colorPlugins = [];
             this.#canvasClearPlugins = [];
-            this.#canvasPaintPlugins = [];
-            this.#clearDrawPlugins = [];
+            this.#colorPlugins = [];
             this.#drawParticlePlugins = [];
             this.#drawParticlesSetupPlugins = [];
             this.#drawParticlesCleanupPlugins = [];
-            this.#drawPlugins = [];
-            this.#drawSettingsSetupPlugins = [];
-            this.#drawSettingsCleanupPlugins = [];
+            for (const layer of Object.values(exports.DrawLayer)) {
+                if (typeof layer === "number") {
+                    this.#layers[layer] = [];
+                }
+            }
             for (const plugin of this.#container.plugins) {
                 if (plugin.particleFillColor ?? plugin.particleStrokeColor) {
                     this.#colorPlugins.push(plugin);
                 }
-                if (plugin.canvasClear) {
-                    this.#canvasClearPlugins.push(plugin);
-                }
-                if (plugin.canvasPaint) {
-                    this.#canvasPaintPlugins.push(plugin);
-                }
                 if (plugin.drawParticle) {
                     this.#drawParticlePlugins.push(plugin);
                 }
@@ -4669,17 +4727,20 @@
                 if (plugin.drawParticleCleanup) {
                     this.#drawParticlesCleanupPlugins.push(plugin);
                 }
-                if (plugin.draw) {
-                    this.#drawPlugins.push(plugin);
+                if (plugin.canvasClear) {
+                    this.#canvasClearPlugins.push(plugin);
+                }
+                if (plugin.canvasPaint) {
+                    this.#getLayerPlugins(exports.DrawLayer.BackgroundMask).push(plugin);
                 }
                 if (plugin.drawSettingsSetup) {
-                    this.#drawSettingsSetupPlugins.push(plugin);
+                    this.#getLayerPlugins(exports.DrawLayer.CanvasSetup).push(plugin);
                 }
-                if (plugin.drawSettingsCleanup) {
-                    this.#drawSettingsCleanupPlugins.push(plugin);
+                if (plugin.draw) {
+                    this.#getLayerPlugins(exports.DrawLayer.PluginContent).push(plugin);
                 }
-                if (plugin.clearDraw) {
-                    this.#clearDrawPlugins.push(plugin);
+                if (plugin.clearDraw ?? plugin.drawSettingsCleanup) {
+                    this.#getLayerPlugins(exports.DrawLayer.CanvasCleanup).push(plugin);
                 }
             }
         }
@@ -4697,7 +4758,7 @@
         }
         paint() {
             let handled = false;
-            for (const plugin of this.#canvasPaintPlugins) {
+            for (const plugin of this.#getLayerPlugins(exports.DrawLayer.BackgroundMask)) {
                 handled = plugin.canvasPaint?.() ?? false;
                 if (handled) {
                     break;
@@ -4870,6 +4931,9 @@
             }
             drawer.beforeDraw(data);
         }
+        #getLayerPlugins(layer) {
+            return this.#layers[layer];
+        }
         #getPluginParticleColors(particle) {
             let fColor, sColor;
             for (const plugin of this.#colorPlugins) {
@@ -4887,6 +4951,39 @@
             this.#reusablePluginColors[sColorIndex] = sColor;
             return this.#reusablePluginColors;
         }
+        #resolveBackgroundElement() {
+            const background = this.#container.actualOptions.background;
+            this.#backgroundElement = null;
+            if (!background.element) {
+                return;
+            }
+            if (typeof background.element === "string") {
+                if (typeof document !== "undefined") {
+                    const node = document.querySelector(background.element);
+                    if (node instanceof HTMLCanvasElement || node instanceof HTMLVideoElement || node instanceof HTMLImageElement) {
+                        this.#backgroundElement = node;
+                    }
+                    else if (node) {
+                        this.#warnOnce("background-element-not-supported", `Background element "${background.element}" is not a supported drawable element (canvas, video, or img)`);
+                    }
+                    else {
+                        this.#warnOnce("background-element-not-found", `Background element selector "${background.element}" not found`);
+                    }
+                }
+            }
+            else if (background.element instanceof HTMLCanvasElement ||
+                background.element instanceof OffscreenCanvas ||
+                background.element instanceof HTMLVideoElement ||
+                background.element instanceof HTMLImageElement) {
+                this.#backgroundElement = background.element;
+            }
+        }
+        #warnOnce(key, message) {
+            if (!this.#backgroundWarnings.has(key)) {
+                this.#backgroundWarnings.add(key);
+                getLogger().warning(message);
+            }
+        }
     }
 
     const transferredCanvases = new WeakMap(), getTransferredCanvas = (canvas) => {
@@ -5463,7 +5560,6 @@
     }
     class Particle {
         backColor;
-        bubble;
         destroyed;
         direction;
         effect;
@@ -5497,7 +5593,6 @@
         shapeData;
         sides;
         size;
-        slow;
         spawning;
         strokeColor;
         strokeOpacity;
@@ -5519,18 +5614,25 @@
             d: 1,
         };
         #container;
+        #modifiers = [];
         #pluginManager;
         constructor(pluginManager, container) {
             this.#pluginManager = pluginManager;
             this.#container = container;
         }
+        addModifier(modifier) {
+            this.#modifiers.push(modifier);
+            this.#modifiers.sort((a, b) => a.priority - b.priority);
+        }
+        clearModifiers() {
+            this.#modifiers.length = 0;
+        }
         destroy(override) {
             if (this.unbreakable || this.destroyed) {
                 return;
             }
             this.destroyed = true;
-            this.bubble.inRange = false;
-            this.slow.inRange = false;
+            this.clearModifiers();
             const container = this.#container, shapeDrawer = this.shape ? container.shapeDrawers.get(this.shape) : undefined;
             shapeDrawer?.particleDestroy?.(this);
             for (const plugin of container.particleDestroyedPlugins) {
@@ -5552,13 +5654,16 @@
             return this.rotation + (this.pathRotation ? this.velocity.angle : defaultAngle$1);
         }
         getFillColor() {
-            return this.#getRollColor(this.bubble.color ?? getHslFromAnimation(this.fillColor));
+            return this.#getRollColor(this.#applyModifiers(getHslFromAnimation(this.fillColor), m => m.fillColor));
         }
         getMass() {
             return this.getRadius() ** squareExp * Math.PI * half$1;
         }
+        getModifier(id) {
+            return this.#modifiers.find(m => m.id === id);
+        }
         getOpacity() {
-            const zIndexOptions = this.options.zIndex, zIndexFactor = zIndexFactorOffset - this.zIndexFactor, zOpacityFactor = zIndexFactor ** zIndexOptions.opacityRate, opacity = this.bubble.opacity ?? getRangeValue(this.opacity?.value ?? defaultOpacity$1), fillOpacity = this.fillOpacity ?? defaultOpacity$1, strokeOpacity = this.strokeOpacity ?? defaultOpacity$1;
+            const zIndexOptions = this.options.zIndex, zIndexFactor = zIndexFactorOffset - this.zIndexFactor, zOpacityFactor = zIndexFactor ** zIndexOptions.opacityRate, baseOpacity = getRangeValue(this.opacity?.value ?? defaultOpacity$1), modifierOpacity = this.#applyModifiers(undefined, m => m.opacity), opacity = modifierOpacity ?? baseOpacity, fillOpacity = this.fillOpacity ?? defaultOpacity$1, strokeOpacity = this.strokeOpacity ?? defaultOpacity$1;
             this.#cachedOpacityData.fillOpacity = opacity * fillOpacity * zOpacityFactor;
             this.#cachedOpacityData.opacity = opacity * zOpacityFactor;
             this.#cachedOpacityData.strokeOpacity = opacity * strokeOpacity * zOpacityFactor;
@@ -5571,7 +5676,7 @@
             return this.#cachedPosition;
         }
         getRadius() {
-            return this.bubble.radius ?? this.size.value;
+            return this.#applyModifiers(this.size.value, m => m.radius);
         }
         getRotateData() {
             const angle = this.getAngle();
@@ -5580,7 +5685,7 @@
             return this.#cachedRotateData;
         }
         getStrokeColor() {
-            return this.#getRollColor(this.bubble.color ?? getHslFromAnimation(this.strokeColor));
+            return this.#getRollColor(this.#applyModifiers(getHslFromAnimation(this.strokeColor), m => m.strokeColor));
         }
         getTransformData(externalTransform) {
             const rotateData = this.getRotateData(), rotating = this.isRotating;
@@ -5600,13 +5705,6 @@
             this.options = resolveParticleOptions(this, container, this.#pluginManager, overrideOptions);
             container.retina.initParticle(this);
             runUpdaterPreInit(container.particleUpdaters, this);
-            this.bubble = {
-                inRange: false,
-            };
-            this.slow = {
-                inRange: false,
-                factor: 1,
-            };
             this.#initPosition(position);
             this.initialVelocity = this.#calculateVelocity();
             this.velocity = this.initialVelocity.copy();
@@ -5646,11 +5744,29 @@
         isVisible() {
             return !this.destroyed && !this.spawning && this.isInsideCanvas();
         }
+        removeModifier(id) {
+            const idx = this.#modifiers.findIndex(m => m.id === id);
+            if (idx >= defaultAngle$1) {
+                this.#modifiers.splice(idx, identity$2);
+            }
+        }
         reset() {
             for (const updater of this.#container.particleUpdaters) {
                 updater.reset?.(this);
             }
         }
+        #applyModifiers(base, getter) {
+            let value = base;
+            for (const mod of this.#modifiers) {
+                if (mod.enabled) {
+                    const override = getter(mod);
+                    if (override !== undefined) {
+                        value = override;
+                    }
+                }
+            }
+            return value;
+        }
         #calcPosition(position, zIndex) {
             let tryCount = defaultRetryCount, posVec = position ? Vector3d.create(position.x, position.y, zIndex) : undefined;
             const container = this.#container, plugins = container.particlePositionPlugins, outModes = this.options.move.outModes, radius = this.getRadius(), canvasSize = container.canvas.size;
@@ -6752,6 +6868,7 @@
     });
 
     class BlendPluginInstance {
+        layer = exports.DrawLayer.CanvasSetup;
         #container;
         #defaultCompositeValue;
         constructor(container) {
@@ -6897,7 +7014,8 @@
         particle.lastPathTime -= pathDelay;
     }
     function getProximitySpeedFactor(particle) {
-        return particle.slow.inRange ? particle.slow.factor : identity$2;
+        const mod = particle.getModifier("slow");
+        return mod?.enabled ? (mod.speedFactor ?? identity$2) : identity$2;
     }
     function initSpin(container, particle) {
         const options = particle.options, spinOptions = options.move.spin;
@@ -7682,6 +7800,7 @@
     exports.hPhase = hPhase;
     exports.half = half$1;
     exports.hslToRgb = hslToRgb;
+    exports.hslToRgbFloat = hslToRgbFloat;
     exports.hslaToRgba = hslaToRgba;
     exports.identity = identity$2;
     exports.inverseFactorNumerator = inverseFactorNumerator;