@tsparticles/preset-matrix 4.2.0 → 4.3.0

package/tsparticles.preset.matrix.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);
-/* Preset v4.2.0 */
+/* Preset v4.3.0 */
 (function (global, factory) {
     typeof exports === 'object' && typeof module !== 'undefined' ? factory(exports) :
     typeof define === 'function' && define.amd ? define(['exports'], factory) :
@@ -358,29 +358,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];
@@ -796,7 +794,7 @@
             return this.#domArray;
         }
         get version() {
-            return "4.2.0";
+            return "4.3.0";
         }
         addEventListener(type, listener) {
             this.#eventDispatcher.addEventListener(type, listener);
@@ -1029,6 +1027,18 @@
         AnimationStatus["decreasing"] = "decreasing";
     })(AnimationStatus || (AnimationStatus = {}));
 
+    var DrawLayer;
+    (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";
+    })(DrawLayer || (DrawLayer = {}));
+
     class OptionLoader {
         load(data) {
             if (isNull(data)) {
@@ -1182,6 +1192,8 @@
 
     class Background extends OptionLoader {
         color;
+        draw;
+        element;
         image = "";
         opacity = 1;
         position = "";
@@ -1196,6 +1208,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);
@@ -1741,7 +1755,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) {
@@ -1881,6 +1895,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
+            ? 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 {
@@ -1890,8 +1915,9 @@
             r: rgbResult.r,
         };
     }
-    function getRandomRgbColor(min) {
-        const fixedMin = defaultRgbMin, fixedMax = rgbMax + identity, getRgbInRangeValue = () => Math.floor(getRandomInRange(fixedMin, fixedMax));
+    function getRandomRgbColor(min, hdr) {
+        const fixedMin = defaultRgbMin;
+        const fixedMax = rgbMax + identity, getRgbInRangeValue = () => Math.floor(getRandomInRange(fixedMin, fixedMax));
         return {
             b: getRgbInRangeValue(),
             g: getRgbInRangeValue(),
@@ -1899,7 +1925,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) {
@@ -1910,9 +1936,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 getHslFromAnimation(animation) {
@@ -1975,7 +2001,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))) {
@@ -1988,7 +2014,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 === AnimationStatus.increasing) {
             data.value += velocity;
             if (data.value > max) {
@@ -2015,14 +2041,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 {
@@ -2072,7 +2098,7 @@
     }
 
     async function loadBlendPlugin(engine) {
-        engine.checkVersion("4.2.0");
+        engine.checkVersion("4.3.0");
         await engine.pluginManager.register(e => {
             e.pluginManager.addPlugin(new BlendPlugin());
         });
@@ -2109,7 +2135,7 @@
     }
 
     async function loadCircleShape(engine) {
-        engine.checkVersion("4.2.0");
+        engine.checkVersion("4.3.0");
         await engine.pluginManager.register(e => {
             e.pluginManager.addShape(["circle"], () => {
                 return Promise.resolve(new CircleDrawer());
@@ -2157,7 +2183,7 @@
     }
 
     async function loadHexColorPlugin(engine) {
-        engine.checkVersion("4.2.0");
+        engine.checkVersion("4.3.0");
         await engine.pluginManager.register(e => {
             e.pluginManager.addColorManager("hex", new HexColorManager());
         });
@@ -2210,7 +2236,7 @@
     }
 
     async function loadHslColorPlugin(engine) {
-        engine.checkVersion("4.2.0");
+        engine.checkVersion("4.3.0");
         await engine.pluginManager.register(e => {
             e.pluginManager.addColorManager("hsl", new HslColorManager());
         });
@@ -2234,7 +2260,7 @@
     }
 
     async function loadMovePlugin(engine) {
-        engine.checkVersion("4.2.0");
+        engine.checkVersion("4.3.0");
         await engine.pluginManager.register(e => {
             const moveEngine = e, movePluginManager = moveEngine.pluginManager;
             movePluginManager.initializers.pathGenerators ??= new Map();
@@ -2444,7 +2470,7 @@
     }
 
     async function loadOpacityUpdater(engine) {
-        engine.checkVersion("4.2.0");
+        engine.checkVersion("4.3.0");
         await engine.pluginManager.register(e => {
             e.pluginManager.addParticleUpdater("opacity", container => {
                 return Promise.resolve(new OpacityUpdater(container));
@@ -2789,7 +2815,7 @@
     }
 
     async function loadOutModesUpdater(engine) {
-        engine.checkVersion("4.2.0");
+        engine.checkVersion("4.3.0");
         await engine.pluginManager.register(e => {
             e.pluginManager.addParticleUpdater("outModes", container => {
                 return Promise.resolve(new OutOfCanvasUpdater(container));
@@ -2854,13 +2880,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.0");
+        engine.checkVersion("4.3.0");
         await engine.pluginManager.register(e => {
             e.pluginManager.addParticleUpdater("paint", container => {
                 return Promise.resolve(new PaintUpdater(e.pluginManager, container));
@@ -2915,7 +2941,7 @@
     }
 
     async function loadRgbColorPlugin(engine) {
-        engine.checkVersion("4.2.0");
+        engine.checkVersion("4.3.0");
         await engine.pluginManager.register(e => {
             e.pluginManager.addColorManager("rgb", new RgbColorManager());
         });
@@ -3000,7 +3026,7 @@
     }
 
     async function loadSizeUpdater(engine) {
-        engine.checkVersion("4.2.0");
+        engine.checkVersion("4.3.0");
         await engine.pluginManager.register(e => {
             e.pluginManager.addParticleUpdater("size", container => {
                 return Promise.resolve(new SizeUpdater(container));
@@ -3009,7 +3035,7 @@
     }
 
     async function loadBasic(engine) {
-        engine.checkVersion("4.2.0");
+        engine.checkVersion("4.3.0");
         await engine.pluginManager.register(async (e) => {
             await Promise.all([
                 loadBlendPlugin(e),
@@ -3241,7 +3267,7 @@
     }
 
     async function loadMatrixShape(engine) {
-        engine.checkVersion("4.2.0");
+        engine.checkVersion("4.3.0");
         await engine.pluginManager.register(e => {
             e.pluginManager.addShape(["matrix"], () => Promise.resolve(new MatrixDrawer()));
         });
@@ -3286,7 +3312,7 @@
     }
 
     async function loadPoissonDiscPlugin(engine) {
-        engine.checkVersion("4.2.0");
+        engine.checkVersion("4.3.0");
         await engine.pluginManager.register(e => {
             e.pluginManager.addPlugin(new PoissonDiscPlugin());
         });
@@ -3324,7 +3350,7 @@
     }
 
     async function loadShadowEffect(engine) {
-        engine.checkVersion("4.2.0");
+        engine.checkVersion("4.3.0");
         await engine.pluginManager.register(e => {
             e.pluginManager.addEffect("shadow", container => {
                 return Promise.resolve(new ShadowDrawer(e.pluginManager, container));
@@ -3388,7 +3414,7 @@
     }
 
     async function loadTrailPlugin(engine) {
-        engine.checkVersion("4.2.0");
+        engine.checkVersion("4.3.0");
         await engine.pluginManager.register(e => {
             e.pluginManager.addPlugin(new TrailPlugin(e.pluginManager));
         });
@@ -3498,10 +3524,10 @@
         }
     }
     class RenderManager {
+        #backgroundElement;
+        #backgroundWarnings;
         #canvasClearPlugins;
         #canvasManager;
-        #canvasPaintPlugins;
-        #clearDrawPlugins;
         #colorPlugins;
         #container;
         #context;
@@ -3509,9 +3535,7 @@
         #drawParticlePlugins;
         #drawParticlesCleanupPlugins;
         #drawParticlesSetupPlugins;
-        #drawPlugins;
-        #drawSettingsCleanupPlugins;
-        #drawSettingsSetupPlugins;
+        #layers;
         #pluginManager;
         #postDrawUpdaters;
         #preDrawUpdaters;
@@ -3523,18 +3547,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;
@@ -3548,32 +3579,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(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(DrawLayer)) {
+                if (typeof layer === "number") {
+                    this.#layers[layer] = [];
+                }
+            }
         }
         draw(cb) {
             const ctx = this.#context;
@@ -3630,21 +3667,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(DrawLayer.BackgroundMask)) {
+                    plugin.canvasPaint?.();
+                }
+                for (const plugin of this.#getLayerPlugins(DrawLayer.CanvasSetup)) {
                     plugin.drawSettingsSetup?.(ctx, delta);
                 }
-                for (const plugin of this.#drawPlugins) {
+                for (const plugin of this.#getLayerPlugins(DrawLayer.PluginContent)) {
                     plugin.draw?.(ctx, delta);
                 }
                 particles.drawParticles(delta);
-                for (const plugin of this.#clearDrawPlugins) {
+                for (const plugin of this.#getLayerPlugins(DrawLayer.CanvasCleanup)) {
                     plugin.clearDraw?.(ctx, delta);
-                }
-                for (const plugin of this.#drawSettingsCleanupPlugins) {
                     plugin.drawSettingsCleanup?.(ctx, delta);
                 }
             });
@@ -3652,29 +3708,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(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);
                 }
@@ -3684,17 +3735,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(DrawLayer.BackgroundMask).push(plugin);
                 }
                 if (plugin.drawSettingsSetup) {
-                    this.#drawSettingsSetupPlugins.push(plugin);
+                    this.#getLayerPlugins(DrawLayer.CanvasSetup).push(plugin);
                 }
-                if (plugin.drawSettingsCleanup) {
-                    this.#drawSettingsCleanupPlugins.push(plugin);
+                if (plugin.draw) {
+                    this.#getLayerPlugins(DrawLayer.PluginContent).push(plugin);
                 }
-                if (plugin.clearDraw) {
-                    this.#clearDrawPlugins.push(plugin);
+                if (plugin.clearDraw ?? plugin.drawSettingsCleanup) {
+                    this.#getLayerPlugins(DrawLayer.CanvasCleanup).push(plugin);
                 }
             }
         }
@@ -3712,7 +3766,7 @@
         }
         paint() {
             let handled = false;
-            for (const plugin of this.#canvasPaintPlugins) {
+            for (const plugin of this.#getLayerPlugins(DrawLayer.BackgroundMask)) {
                 handled = plugin.canvasPaint?.() ?? false;
                 if (handled) {
                     break;
@@ -3885,6 +3939,9 @@
             }
             drawer.beforeDraw(data);
         }
+        #getLayerPlugins(layer) {
+            return this.#layers[layer];
+        }
         #getPluginParticleColors(particle) {
             let fColor, sColor;
             for (const plugin of this.#colorPlugins) {
@@ -3902,6 +3959,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) => {
@@ -4478,7 +4568,6 @@
     }
     class Particle {
         backColor;
-        bubble;
         destroyed;
         direction;
         effect;
@@ -4512,7 +4601,6 @@
         shapeData;
         sides;
         size;
-        slow;
         spawning;
         strokeColor;
         strokeOpacity;
@@ -4534,18 +4622,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) {
@@ -4567,13 +4662,16 @@
             return this.rotation + (this.pathRotation ? this.velocity.angle : defaultAngle);
         }
         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;
         }
+        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;
@@ -4586,7 +4684,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();
@@ -4595,7 +4693,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;
@@ -4615,13 +4713,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();
@@ -4661,11 +4752,29 @@
         isVisible() {
             return !this.destroyed && !this.spawning && this.isInsideCanvas();
         }
+        removeModifier(id) {
+            const idx = this.#modifiers.findIndex(m => m.id === id);
+            if (idx >= defaultAngle) {
+                this.#modifiers.splice(idx, identity);
+            }
+        }
         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;
@@ -5767,6 +5876,7 @@
     });
 
     class BlendPluginInstance {
+        layer = DrawLayer.CanvasSetup;
         #container;
         #defaultCompositeValue;
         constructor(container) {
@@ -5912,7 +6022,8 @@
         particle.lastPathTime -= pathDelay;
     }
     function getProximitySpeedFactor(particle) {
-        return particle.slow.inRange ? particle.slow.factor : identity;
+        const mod = particle.getModifier("slow");
+        return mod?.enabled ? (mod.speedFactor ?? identity) : identity;
     }
     function initSpin(container, particle) {
         const options = particle.options, spinOptions = options.move.spin;
@@ -6090,6 +6201,7 @@
 
     const minimumLength = 0;
     class TrailPluginInstance {
+        layer = DrawLayer.PluginContent;
         #container;
         #pluginManager;
         #trailFill;