melonjs 20.1.1 → 20.2.0

package/build/index.js

@@ -1,5 +1,5 @@
 /*!
- * melonJS Game Engine - 20.1.1
+ * melonJS Game Engine - 20.2.0
  * http://www.melonjs.org
  * melonjs is licensed under the MIT License.
  * http://www.opensource.org/licenses/mit-license
@@ -7770,6 +7770,20 @@ var CanvasRenderTarget = class extends RenderTarget {
    * @param {CanvasRenderer|WebGLRenderer} renderer - the renderer to which this canvas texture is attached
    */
   invalidate(renderer) {
+    const busy = renderer._advancedBlendBusy;
+    if (typeof busy === "number") {
+      renderer._advancedBlendBusy = busy + 1;
+    }
+    try {
+      this.#invalidate(renderer);
+    } finally {
+      if (typeof busy === "number") {
+        renderer._advancedBlendBusy = busy;
+      }
+    }
+  }
+  /** @ignore */
+  #invalidate(renderer) {
     if (renderer.type.startsWith("WebGL")) {
       renderer.flush();
       renderer.setBatcher("quad");
@@ -10807,11 +10821,10 @@ var Renderer = class _Renderer {
     return this.currentBlendMode;
   }
   /**
-   * set the current blend mode.
-   * Subclasses (CanvasRenderer, WebGLRenderer, WebGPURenderer once it
-   * lands) implement the actual backend logic.
+   * set the current blend mode. Every renderer supports the same set —
+   * see {@link CanvasRenderer#setBlendMode} for the list and what each does.
    * @param {string} [mode="normal"] - blend mode
-   * @param {boolean} [premultipliedAlpha=true] - whether textures use premultiplied alpha (GPU renderers only)
+   * @param {boolean} [premultipliedAlpha=true] - whether textures use premultiplied alpha
    */
   setBlendMode(mode = "normal") {
     this.currentBlendMode = mode;
@@ -17552,6 +17565,8 @@ var Body = class {
 };
 
 // src/renderable/renderable.js
+var _chain = [];
+var _level = new Matrix3d();
 var Renderable = class _Renderable extends Rect {
   /**
    * @param {number} x - position of the renderable object (accessible through inherited pos.x property)
@@ -17986,13 +18001,33 @@ var Renderable = class _Renderable extends Rect {
     }
   }
   /**
-   * return the renderable absolute position in the game world. The
-   * returned vector is a {@link Vector3d} so the z component is summed
-   * across the ancestor chain too — important for {@link Camera3d}'s
-   * frustum culling, which previously read `obj.depth` (local
-   * `pos.z`) and mis-culled children nested under a container with
-   * its own non-zero depth.
-   * @returns {Vector3d}
+   * Where this renderable IS in the game world — its own `pos` plus every
+   * ancestor's, as a {@link Vector3d} so the z component is summed across
+   * the chain too (important for {@link Camera3d}'s frustum culling, which
+   * previously read `obj.depth` — local `pos.z` — and mis-culled children
+   * nested under a container with its own non-zero depth).
+   *
+   * **Reach for this** for anything positional: culling, distance checks,
+   * hit tests, placing one renderable relative to another. It is cheap, and
+   * it is what the engine's own culling uses.
+   *
+   * **Reach for {@link Renderable#getWorldTransform} instead** when a
+   * position is not enough — when rotation, scale or flip along the ancestor
+   * chain matters, or when you need to map an arbitrary point rather than
+   * just the origin. This method sums translations only, so under a rotated
+   * or scaled ancestor it reports where the renderable's *pivot* is and
+   * nothing about how its content is oriented.
+   *
+   * Note the two also frame the question differently. This one is "where am
+   * I"; `getWorldTransform()` is "what space is my content drawn in". For a
+   * {@link Container} those coincide, because a container offsets its
+   * children by its own position. For a leaf they differ by exactly that
+   * position, which a leaf applies inside its own `draw()`.
+   *
+   * The returned vector is pooled and reused — copy it if you need to hold
+   * onto the value across another call.
+   * @returns {Vector3d} this renderable's absolute position
+   * @see Renderable#getWorldTransform
    */
   getAbsolutePosition() {
     if (typeof this._absPos === "undefined") {
@@ -18004,6 +18039,121 @@ var Renderable = class _Renderable extends Rect {
     }
     return this._absPos;
   }
+  /**
+   * The transform this renderable interposes between its ancestor's frame
+   * and the frame its own content is drawn in — a mirror of what
+   * {@link Renderable#preDraw} applies to the renderer, as a matrix.
+   *
+   * **This is not {@link Renderable#currentTransform}.** A renderable's
+   * placement is split across two members: `pos` holds where it is, and
+   * `currentTransform` holds only what `rotate()` / `scale()` / `translate()`
+   * accumulate — it never contains the position. `preDraw` composes the two
+   * by conjugation, so a rotation pivots about the renderable's position
+   * rather than the origin. On a renderable you never rotated,
+   * `currentTransform` is therefore the *identity* and says nothing about
+   * where its content lands, while this method returns the translation that
+   * actually places it.
+   *
+   * {@link Container} extends this with the offset it applies to its
+   * children, which a leaf renderable does not have: a leaf's own `draw()`
+   * places itself from `pos`.
+   * @protected
+   * @param {Matrix3d} out - matrix to write into; nothing is stored on the
+   * renderable itself, so callers own the lifetime
+   * @returns {Matrix3d} `out`, for chaining
+   * @see Renderable#getWorldTransform
+   */
+  getLocalTransform(out) {
+    const ax = Number.isFinite(this.width) ? this.width * this.anchorPoint.x : 0;
+    const ay = Number.isFinite(this.height) ? this.height * this.anchorPoint.y : 0;
+    out.identity();
+    if (this._flip.x || this._flip.y) {
+      const dx = this._flip.x ? this.centerX - ax : 0;
+      const dy = this._flip.y ? this.centerY - ay : 0;
+      out.translate(dx, dy);
+      out.scale(this._flip.x ? -1 : 1, this._flip.y ? -1 : 1);
+      out.translate(-dx, -dy);
+    }
+    if (this.autoTransform === true && !this.currentTransform.isIdentity()) {
+      out.translate(this.pos.x, this.pos.y);
+      out.multiply(this.currentTransform);
+      out.translate(-this.pos.x, -this.pos.y);
+    }
+    if (this.applyAnchorTransform !== false) {
+      out.translate(-ax, -ay);
+    }
+    return out;
+  }
+  /**
+   * The space this renderable's content is drawn IN, as a matrix — the full
+   * form of {@link Renderable#getAbsolutePosition}, which sums positions up
+   * the ancestor chain and therefore cannot represent the rotation, scale or
+   * flip accumulated along the way.
+   *
+   * **Reach for `getAbsolutePosition()` instead** for ordinary positional
+   * work — culling, distance checks, hit tests. It is cheaper and it is what
+   * the engine culls with. **Use this** when a position is not enough:
+   *
+   * - an ancestor is rotated or scaled, so a translation cannot describe the
+   *   result
+   * - you need to map an arbitrary point, not just the origin — a corner, a
+   *   click position, one renderable's coordinates into another's space
+   * - you need to compose or invert the transform (`inv(A) · B` converts
+   *   between two frames, which is how `ParticleEmitter.referenceSpace`
+   *   measures particles against a container that is not their parent)
+   *
+   * The two also frame the question differently, and it shows on a leaf.
+   * `getAbsolutePosition()` is "where am I"; this is "what space is my
+   * content drawn in". For a {@link Container} those coincide, because a
+   * container offsets its children by its own position. For a leaf they
+   * differ by exactly that position, which a leaf applies inside its own
+   * `draw()`. So with no rotation, scale or flip anywhere, a container's
+   * translation column equals its `getAbsolutePosition()` while a leaf's
+   * equals its PARENT's.
+   *
+   * The walk stops at a `floating` ancestor, because a floating renderable
+   * draws in screen space: {@link Container#draw} resets the transform
+   * outright for those, so the chain genuinely ends there rather than
+   * continuing to the root.
+   *
+   * The camera needs no special handling — {@link Camera2d} folds its view
+   * transform into the root container's `currentTransform`, so it is picked
+   * up like any other level.
+   * @param {Matrix3d} out - matrix to write into; nothing is stored on the
+   * renderable itself, so callers own the lifetime
+   * @returns {Matrix3d} `out`, for chaining
+   * @see Renderable#getAbsolutePosition
+   * @example
+   * // map a point from one renderable's space into another's
+   * const from = a.getWorldTransform(new Matrix3d());
+   * const into = b.getWorldTransform(new Matrix3d()).invert();
+   * const point = new Vector2d(10, 20);       // in a's space
+   * from.apply(point);                        // -> world
+   * into.apply(point);                        // -> b's space
+   * @example
+   * // just need to know where something is? use the cheaper call
+   * const where = renderable.getAbsolutePosition();
+   */
+  getWorldTransform(out) {
+    _chain.length = 0;
+    _chain.push(this);
+    if (this.floating !== true) {
+      let node = this.ancestor;
+      while (typeof node !== "undefined" && node !== null) {
+        _chain.push(node);
+        if (node.floating === true) {
+          break;
+        }
+        node = node.ancestor;
+      }
+    }
+    out.identity();
+    for (let i = _chain.length; i-- > 0; ) {
+      out.multiply(_chain[i].getLocalTransform(_level));
+    }
+    _chain.length = 0;
+    return out;
+  }
   /**
    * Prepare the rendering context before drawing (automatically called by melonJS).
    * This will apply any defined transforms, anchor point, tint or blend mode and translate the context accordingly to this renderable position.
@@ -18298,6 +18448,7 @@ function compileProgram(gl, vertex, fragment2, attributes) {
     throw new Error(error_msg);
   }
   gl.useProgram(program);
+  gl.__meCurrentProgram = program;
   gl.deleteShader(vertShader);
   gl.deleteShader(fragShader);
   return program;
@@ -18595,6 +18746,7 @@ var GLShader = class _GLShader {
       return;
     }
     this.gl.useProgram(this.program);
+    this.gl.__meCurrentProgram = this.program;
   }
   /**
    * returns the location of an attribute variable in this shader program
@@ -26779,6 +26931,20 @@ var Container = class _Container extends Renderable {
     }
     return super.update(dt);
   }
+  /**
+   * A container additionally offsets its children by its own position — the
+   * `translate()` at the top of {@link Container#draw} — which is what makes
+   * a child's coordinates mean "relative to my parent" rather than naming a
+   * place in the world. A leaf renderable has no such term.
+   * @protected
+   * @param {Matrix3d} out - matrix to write into
+   * @returns {Matrix3d} `out`, for chaining
+   */
+  getLocalTransform(out) {
+    super.getLocalTransform(out);
+    out.translate(this.pos.x, this.pos.y);
+    return out;
+  }
   /**
    * draw this renderable (automatically called by melonJS)
    * @param {CanvasRenderer|WebGLRenderer} renderer - a renderer instance
@@ -35760,7 +35926,7 @@ var CanvasRenderer = class extends Renderer {
   }
   /**
    * set the current blend mode for this renderer. <br>
-   * All renderers support: <br>
+   * Every renderer supports the full set: <br>
    * - "normal" : draws new content on top of the existing content <br>
    * <img src="../images/normal-blendmode.png" width="180"/> <br>
    * - "add", "additive", or "lighter" : color values are added together <br>
@@ -35769,26 +35935,30 @@ var CanvasRenderer = class extends Renderer {
    * <img src="../images/multiply-blendmode.png" width="180"/> <br>
    * - "screen" : pixels are inverted, multiplied, and inverted again (opposite of multiply) <br>
    * <img src="../images/screen-blendmode.png" width="180"/> <br>
-   * Canvas (browser-dependent) and WebGL2: <br>
    * - "darken" : retains the darkest pixels of both layers <br>
    * <img src="../images/darken-blendmode.png" width="180"/> <br>
    * - "lighten" : retains the lightest pixels of both layers <br>
    * <img src="../images/lighten-blendmode.png" width="180"/> <br>
-   * Canvas only, browser-dependent (falls back to "normal" if unsupported or in WebGL): <br>
-   * - "overlay" <br>
+   * - "overlay" : multiplies or screens, depending on the backdrop <br>
    * <img src="../images/overlay-blendmode.png" width="180"/> <br>
-   * - "color-dodge" <br>
-   * <img src="../images/color-dodge-blendmode.png" width="180"/> <br>
-   * - "color-burn" <br>
-   * <img src="../images/color-burn-blendmode.png" width="180"/> <br>
-   * - "hard-light" <br>
+   * - "hard-light" : overlay with the layers swapped — a harsh spotlight <br>
    * <img src="../images/hard-light-blendmode.png" width="180"/> <br>
-   * - "soft-light" <br>
+   * - "soft-light" : a diffused spotlight, gentler than hard-light <br>
    * <img src="../images/soft-light-blendmode.png" width="180"/> <br>
-   * - "difference" <br>
+   * - "color-dodge" : brightens the backdrop to reflect the source <br>
+   * <img src="../images/color-dodge-blendmode.png" width="180"/> <br>
+   * - "color-burn" : darkens the backdrop to reflect the source <br>
+   * <img src="../images/color-burn-blendmode.png" width="180"/> <br>
+   * - "difference" : the absolute difference of the two layers <br>
    * <img src="../images/difference-blendmode.png" width="180"/> <br>
-   * - "exclusion" <br>
+   * - "exclusion" : like difference, but lower in contrast <br>
    * <img src="../images/exclusion-blendmode.png" width="180"/> <br>
+   * - "none" : blending disabled — the source replaces the destination
+   * outright, alpha included <br>
+   * A few draw types cannot honour every mode — 3D meshes, and fills using
+   * a {@link Gradient} — and fall back to "normal" with a one-time console
+   * warning. `setBlendMode` returns what it actually applied, so comparing
+   * the result against your request detects that case.
    * @see https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/globalCompositeOperation
    * @param {string} [mode="normal"] - blend mode
    * @returns {string} the blend mode actually applied (may differ if the requested mode is unsupported)
@@ -36661,11 +36831,11 @@ var CanvasRenderer = class extends Renderer {
    * Reset (overrides) the renderer transformation matrix to the
    * identity one, and then apply the given transformation matrix.
    * @param {Matrix2d|Matrix3d|number} a - a matrix to transform by, or the a component to multiply the current matrix by
-   * @param {number} b - the b component to multiply the current matrix by
-   * @param {number} c - the c component to multiply the current matrix by
-   * @param {number} d - the d component to multiply the current matrix by
-   * @param {number} e - the e component to multiply the current matrix by
-   * @param {number} f - the f component to multiply the current matrix by
+   * @param {number} [b] - the b component to multiply the current matrix by; omitted when `a` is a matrix
+   * @param {number} [c] - the c component to multiply the current matrix by; omitted when `a` is a matrix
+   * @param {number} [d] - the d component to multiply the current matrix by; omitted when `a` is a matrix
+   * @param {number} [e] - the e component to multiply the current matrix by; omitted when `a` is a matrix
+   * @param {number} [f] - the f component to multiply the current matrix by; omitted when `a` is a matrix
    */
   setTransform(a, b, c, d, e, f) {
     this.resetTransform();
@@ -36675,11 +36845,11 @@ var CanvasRenderer = class extends Renderer {
    * Multiply given matrix into the renderer tranformation matrix
    * @see {@link CanvasRenderer.setTransform} which will reset the current transform matrix prior to performing the new transformation
    * @param {Matrix2d|Matrix3d|number} a - a matrix to transform by, or the a component to multiply the current matrix by
-   * @param {number} b - the b component to multiply the current matrix by
-   * @param {number} c - the c component to multiply the current matrix by
-   * @param {number} d - the d component to multiply the current matrix by
-   * @param {number} e - the e component to multiply the current matrix by
-   * @param {number} f - the f component to multiply the current matrix by
+   * @param {number} [b] - the b component to multiply the current matrix by; omitted when `a` is a matrix
+   * @param {number} [c] - the c component to multiply the current matrix by; omitted when `a` is a matrix
+   * @param {number} [d] - the d component to multiply the current matrix by; omitted when `a` is a matrix
+   * @param {number} [e] - the e component to multiply the current matrix by; omitted when `a` is a matrix
+   * @param {number} [f] - the f component to multiply the current matrix by; omitted when `a` is a matrix
    */
   transform(a, b, c, d, e, f) {
     if (typeof a === "object") {
@@ -37725,7 +37895,7 @@ var WebGLBatcher = class extends Batcher {
     const gl = this.gl;
     this.vertexState.bind();
     gl.bindBuffer(gl.ARRAY_BUFFER, this.uploadBuffer);
-    if (this.renderer.currentProgram !== this.defaultShader.program) {
+    if (this.currentShader !== this.defaultShader || this.renderer.currentProgram !== this.defaultShader.program) {
       this.useShader(this.defaultShader);
     }
   }
@@ -38985,6 +39155,222 @@ var QuadBatcher = class extends MaterialBatcher {
   }
 };
 
+// src/video/blendmodes.js
+var ADVANCED_BLEND_MODES = [
+  "difference",
+  "overlay",
+  "hard-light",
+  "color-dodge",
+  "color-burn",
+  "soft-light",
+  // `darken` and `lighten` joined the shader path in 20.2: fixed-function
+  // MIN/MAX compute `min(src, dst)` and nothing else, so there is nowhere to
+  // put the `(1 - srcAlpha) * dst` term source-over contributes after the
+  // blend. A translucent source lost the backdrop's share entirely — a white
+  // `lighten` glow over a light backdrop rendered invisible. APPENDED, never
+  // inserted: the index is the shader's branch value.
+  "darken",
+  "lighten"
+];
+function isAdvancedBlendMode(mode) {
+  return ADVANCED_BLEND_MODES.indexOf(mode) !== -1;
+}
+function advancedBlendModeIndex(mode) {
+  return ADVANCED_BLEND_MODES.indexOf(mode);
+}
+function normalizeBlendMode(mode) {
+  switch (mode) {
+    case "none":
+    case "multiply":
+    case "screen":
+    case "exclusion":
+    case "normal":
+      return mode;
+    case "additive":
+    case "add":
+    case "lighter":
+      return "additive";
+    default:
+      return "normal";
+  }
+}
+function isSupportedBlendMode(mode) {
+  return isAdvancedBlendMode(mode) || mode === "normal" || normalizeBlendMode(mode) !== "normal";
+}
+function reportedBlendMode(mode) {
+  return isSupportedBlendMode(mode) ? mode : "normal";
+}
+function blendStateFor(mode, premultipliedAlpha) {
+  const src = premultipliedAlpha ? "one" : "src-alpha";
+  switch (mode) {
+    case "none":
+      return void 0;
+    case "additive":
+      return { operation: "add", srcFactor: src, dstFactor: "one" };
+    case "multiply":
+      return {
+        operation: "add",
+        srcFactor: "dst",
+        dstFactor: "one-minus-src-alpha"
+      };
+    case "exclusion":
+      return {
+        operation: "add",
+        srcFactor: "one-minus-dst",
+        dstFactor: "one-minus-src"
+      };
+    case "screen":
+      return {
+        operation: "add",
+        srcFactor: "one",
+        dstFactor: "one-minus-src"
+      };
+    default:
+      return {
+        operation: "add",
+        srcFactor: src,
+        dstFactor: "one-minus-src-alpha"
+      };
+  }
+}
+
+// src/video/effects/blendEffect.js
+var wgslFragment2 = `
+struct BlendUniforms {
+	uBlendMode : f32,
+};
+@group(3) @binding(0) var<uniform> fx : BlendUniforms;
+@group(3) @binding(1) var backdrop : texture_2d<f32>;
+@group(3) @binding(2) var backdrop_sampler : sampler;
+
+// HardLight(Cb, Cs) \u2014 also the kernel for Overlay, which the W3C spec
+// defines as HardLight with the arguments swapped
+fn ME_hardLight(b : vec3f, s : vec3f) -> vec3f {
+	let lo = 2.0 * b * s;
+	let hi = 1.0 - 2.0 * (1.0 - b) * (1.0 - s);
+	return mix(lo, hi, step(vec3f(0.5), s));
+}
+
+fn ME_softLight(b : vec3f, s : vec3f) -> vec3f {
+	let d = mix(((16.0 * b - 12.0) * b + 4.0) * b, sqrt(b), step(vec3f(0.25), b));
+	let lo = b - (1.0 - 2.0 * s) * b * (1.0 - b);
+	let hi = b + (2.0 * s - 1.0) * (d - b);
+	return mix(lo, hi, step(vec3f(0.5), s));
+}
+
+// Cb == 0 wins over Cs == 1, so it is applied last
+fn ME_colorDodge(b : vec3f, s : vec3f) -> vec3f {
+	var r = min(vec3f(1.0), b / max(1.0 - s, vec3f(1e-4)));
+	r = mix(r, vec3f(1.0), step(vec3f(1.0), s));
+	return mix(r, vec3f(0.0), step(b, vec3f(0.0)));
+}
+
+// Cb == 1 wins over Cs == 0, so it is applied last
+fn ME_colorBurn(b : vec3f, s : vec3f) -> vec3f {
+	var r = 1.0 - min(vec3f(1.0), (1.0 - b) / max(s, vec3f(1e-4)));
+	r = mix(r, vec3f(0.0), step(s, vec3f(0.0)));
+	return mix(r, vec3f(1.0), step(vec3f(1.0), b));
+}
+
+fn ME_blend(b : vec3f, s : vec3f) -> vec3f {
+	if (fx.uBlendMode < 0.5) { return abs(b - s); }
+	if (fx.uBlendMode < 1.5) { return ME_hardLight(s, b); }
+	if (fx.uBlendMode < 2.5) { return ME_hardLight(b, s); }
+	if (fx.uBlendMode < 3.5) { return ME_colorDodge(b, s); }
+	if (fx.uBlendMode < 4.5) { return ME_colorBurn(b, s); }
+	if (fx.uBlendMode < 5.5) { return ME_softLight(b, s); }
+	if (fx.uBlendMode < 6.5) { return min(b, s); }
+	return max(b, s);
+}
+
+fn apply(color : vec4f, uv : vec2f) -> vec4f {
+	// sampled BEFORE any branch, so plain textureSampleLevel is safe here
+	let Cb = textureSampleLevel(backdrop, backdrop_sampler, screen_uv, 0.0).rgb;
+	let a = color.a;
+	let Cs = color.rgb / max(a, 1e-4);
+	let B = clamp(ME_blend(Cb, Cs), vec3f(0.0), vec3f(1.0));
+	return vec4f(a * B, a);
+}
+`;
+var BlendEffect = class extends ShaderEffect {
+  /**
+   * @param {import("../webgl/webgl_renderer.js").default|import("../webgpu/webgpu_renderer.js").default} renderer - the renderer that owns this effect
+   */
+  constructor(renderer) {
+    super(renderer, {
+      glsl: `
+			uniform sampler2D backdrop;
+			uniform float uBlendMode;
+
+			// HardLight(Cb, Cs) \u2014 also the kernel for Overlay, which the W3C
+			// spec defines as HardLight with the arguments swapped
+			vec3 ME_hardLight(vec3 b, vec3 s) {
+				vec3 lo = 2.0 * b * s;
+				vec3 hi = 1.0 - 2.0 * (1.0 - b) * (1.0 - s);
+				return mix(lo, hi, step(vec3(0.5), s));
+			}
+
+			vec3 ME_softLight(vec3 b, vec3 s) {
+				vec3 d = mix(((16.0 * b - 12.0) * b + 4.0) * b, sqrt(b), step(vec3(0.25), b));
+				vec3 lo = b - (1.0 - 2.0 * s) * b * (1.0 - b);
+				vec3 hi = b + (2.0 * s - 1.0) * (d - b);
+				return mix(lo, hi, step(vec3(0.5), s));
+			}
+
+			// Cb == 0 wins over Cs == 1, so it is applied last
+			vec3 ME_colorDodge(vec3 b, vec3 s) {
+				vec3 r = min(vec3(1.0), b / max(1.0 - s, vec3(1e-4)));
+				r = mix(r, vec3(1.0), step(vec3(1.0), s));
+				return mix(r, vec3(0.0), step(b, vec3(0.0)));
+			}
+
+			// Cb == 1 wins over Cs == 0, so it is applied last
+			vec3 ME_colorBurn(vec3 b, vec3 s) {
+				vec3 r = 1.0 - min(vec3(1.0), (1.0 - b) / max(s, vec3(1e-4)));
+				r = mix(r, vec3(0.0), step(s, vec3(0.0)));
+				return mix(r, vec3(1.0), step(vec3(1.0), b));
+			}
+
+			vec3 ME_blend(vec3 b, vec3 s) {
+				if (uBlendMode < 0.5) { return abs(b - s); }
+				if (uBlendMode < 1.5) { return ME_hardLight(s, b); }
+				if (uBlendMode < 2.5) { return ME_hardLight(b, s); }
+				if (uBlendMode < 3.5) { return ME_colorDodge(b, s); }
+				if (uBlendMode < 4.5) { return ME_colorBurn(b, s); }
+				if (uBlendMode < 5.5) { return ME_softLight(b, s); }
+				if (uBlendMode < 6.5) { return min(b, s); }
+				return max(b, s);
+			}
+
+			vec4 apply(vec4 color, vec2 uv) {
+				vec3 Cb = texture2D(backdrop, screen_uv).rgb;
+				float a = color.a;
+				vec3 Cs = color.rgb / max(a, 1e-4);
+				vec3 B = clamp(ME_blend(Cb, Cs), 0.0, 1.0);
+				return vec4(a * B, a);
+			}
+			`,
+      wgsl: wgslFragment2
+    });
+    this.setUniform("uBlendMode", 0);
+  }
+  /**
+   * Select which of the six formulas the shader evaluates.
+   * @param {string} mode - one of the modes in {@link ADVANCED_BLEND_MODES}
+   * @returns {boolean} false when the mode is not an advanced blend mode, in
+   * which case the uniform is left untouched
+   * @ignore
+   */
+  setBlendMode(mode) {
+    const index = advancedBlendModeIndex(mode);
+    if (index === -1) {
+      return false;
+    }
+    this.setUniform("uBlendMode", index);
+    return true;
+  }
+};
+
 // src/video/effects/radialGradient.js
 var RadialGradientEffect = class extends ShaderEffect {
   /**
@@ -42690,7 +43076,30 @@ var GLSamplerCache = class {
 var _tempMatrix = new Matrix3d();
 var _savedTransform = new Matrix3d();
 var _savedProjection = new Matrix3d();
-var WebGLRenderer = class extends Renderer {
+var GL_BLEND_OP;
+var GL_BLEND_FACTOR;
+function initBlendEnums(gl) {
+  GL_BLEND_OP = {
+    add: gl.FUNC_ADD,
+    subtract: gl.FUNC_SUBTRACT,
+    "reverse-subtract": gl.FUNC_REVERSE_SUBTRACT,
+    min: gl.MIN,
+    max: gl.MAX
+  };
+  GL_BLEND_FACTOR = {
+    zero: gl.ZERO,
+    one: gl.ONE,
+    src: gl.SRC_COLOR,
+    "one-minus-src": gl.ONE_MINUS_SRC_COLOR,
+    "src-alpha": gl.SRC_ALPHA,
+    "one-minus-src-alpha": gl.ONE_MINUS_SRC_ALPHA,
+    dst: gl.DST_COLOR,
+    "one-minus-dst": gl.ONE_MINUS_DST_COLOR,
+    "dst-alpha": gl.DST_ALPHA,
+    "one-minus-dst-alpha": gl.ONE_MINUS_DST_ALPHA
+  };
+}
+var WebGLRenderer = class _WebGLRenderer extends Renderer {
   /**
    * @param {ApplicationSettings} [options] - optional parameters for the renderer
    */
@@ -42707,6 +43116,14 @@ var WebGLRenderer = class extends Renderer {
     });
     this._effectProjectionStack = [];
     this._effectPassDepth = 0;
+    this._advancedBlendEffect = void 0;
+    this._advancedBlendCapture = void 0;
+    this._advancedBlendTarget = void 0;
+    this._advancedBlendOpen = false;
+    this._advancedBlendBusy = 0;
+    this._advancedBlendParent = null;
+    this._advancedBlendStencil = false;
+    this._advancedBlendWarned = /* @__PURE__ */ new Set();
     this.lineWidth = 1;
     this.lineJoin = "round";
     this.vertexBuffer = this.gl.createBuffer();
@@ -42885,6 +43302,14 @@ var WebGLRenderer = class extends Renderer {
     off(GAME_RESET, this.onGameReset);
     off(ONCONTEXT_RESTORED, this.onContextRestoredInvalidate);
     off(CANVAS_ONRESIZE, this.onCanvasResize);
+    this._advancedBlendEffect?.destroy();
+    this._advancedBlendEffect = void 0;
+    this._advancedBlendCapture?.destroy();
+    this._advancedBlendCapture = void 0;
+    this._advancedBlendTarget?.destroy?.();
+    this._advancedBlendTarget = void 0;
+    this._advancedBlendOpen = false;
+    this._advancedBlendBusy = 0;
     releaseShadowQuads(this);
     if (this.batchers) {
       this.batchers.forEach((batcher) => {
@@ -43013,6 +43438,18 @@ var WebGLRenderer = class extends Renderer {
     if (typeof batcher === "undefined") {
       throw new Error("Invalid Batcher");
     }
+    if (this._advancedBlendBusy === 0) {
+      if (this._advancedBlendOpen === true) {
+        this._closeAdvancedBlend();
+      }
+      if (isAdvancedBlendMode(this.currentBlendMode) === true) {
+        if (name === "mesh" || name === "litMesh") {
+          this._warnAdvancedBlendFallback("3D meshes");
+        } else {
+          this._openAdvancedBlend();
+        }
+      }
+    }
     const targetShader = shader != null ? shader : batcher.defaultShader;
     if (this.currentBatcher === batcher && batcher.currentShader === targetShader) {
       return this.currentBatcher;
@@ -43082,6 +43519,10 @@ var WebGLRenderer = class extends Renderer {
    * Flush the batcher to the frame buffer
    */
   flush() {
+    if (this._advancedBlendOpen === true && this._advancedBlendBusy === 0) {
+      this._closeAdvancedBlend();
+      return;
+    }
     this.currentBatcher.flush();
   }
   /**
@@ -43257,6 +43698,16 @@ var WebGLRenderer = class extends Renderer {
    * }
    */
   toFrameTexture(options = {}) {
+    const busy = this._advancedBlendBusy;
+    this._advancedBlendBusy = (busy ?? 0) + 1;
+    try {
+      return _WebGLRenderer.prototype._toFrameTexture.call(this, options);
+    } finally {
+      this._advancedBlendBusy = busy;
+    }
+  }
+  /** @ignore */
+  _toFrameTexture(options = {}) {
     const gl = this.gl;
     const canvas = this.getCanvas();
     let x = 0;
@@ -43492,6 +43943,125 @@ var WebGLRenderer = class extends Renderer {
     );
     this.currentBatcher.setProjection(this.projectionMatrix);
   }
+  /**
+   * Say once, per excluded path and mode, that an advanced blend mode is
+   * falling back to `"normal"`. A silent data-dependent fallback is exactly
+   * what the advanced-blend work exists to remove, so the exclusions are
+   * loud.
+   * @param {string} what - the excluded path, named for the message
+   * @ignore
+   */
+  _warnAdvancedBlendFallback(what) {
+    const key = `${what}:${this.currentBlendMode}`;
+    if (this._advancedBlendWarned.has(key)) {
+      return;
+    }
+    this._advancedBlendWarned.add(key);
+    console.warn(
+      `WebGLRenderer: blend mode "${this.currentBlendMode}" is not supported for ${what} and falls back to "normal"`
+    );
+  }
+  /**
+   * Close a pending advanced-blend bracket, if one is open and we are not
+   * already inside the bracket machinery. The safe form to call from any
+   * path that is about to disturb the destination.
+   * @ignore
+   */
+  _drainAdvancedBlend() {
+    if (this._advancedBlendOpen === true && this._advancedBlendBusy === 0) {
+      this._closeAdvancedBlend();
+    }
+  }
+  /**
+   * Open an advanced-blend bracket: capture the destination, then redirect
+   * this draw into an offscreen target. Closed by {@link _closeAdvancedBlend}
+   * at the next draw, flush or clear.
+   * @returns {boolean} false when the effect could not be realized, in which
+   * case the draw proceeds unbracketed (plain source-over)
+   * @ignore
+   */
+  _openAdvancedBlend() {
+    const gl = this.gl;
+    const canvas = this.getCanvas();
+    const w = canvas.width;
+    const h = canvas.height;
+    this._advancedBlendBusy++;
+    if (typeof this._advancedBlendEffect === "undefined") {
+      this._advancedBlendEffect = new BlendEffect(this);
+    }
+    if (this._advancedBlendEffect.enabled !== true) {
+      this._advancedBlendBusy--;
+      this._warnAdvancedBlendFallback("this device");
+      return false;
+    }
+    this._advancedBlendEffect.setBlendMode(this.currentBlendMode);
+    this.currentBatcher.flush();
+    this._advancedBlendCapture = this.toFrameTexture({
+      target: this._advancedBlendCapture ?? null
+    });
+    this._advancedBlendEffect.setTexture(
+      "backdrop",
+      this._advancedBlendCapture
+    );
+    this._advancedBlendParent = this._effectPassDepth > 0 ? this._renderTargetPool.getCaptureTarget() : null;
+    if (typeof this._advancedBlendTarget === "undefined") {
+      this._advancedBlendTarget = new WebGLRenderTarget(gl, w, h, {
+        samples: 0
+      });
+    } else {
+      this._advancedBlendTarget.resize(w, h);
+    }
+    this.invalidateTextureUnit(0);
+    this._advancedBlendTarget.bind();
+    this.setViewport(0, 0, w, h);
+    this.clearRenderTarget();
+    this._advancedBlendStencil = gl.isEnabled(gl.STENCIL_TEST);
+    if (this._advancedBlendStencil === true) {
+      gl.disable(gl.STENCIL_TEST);
+    }
+    this._advancedBlendOpen = true;
+    this._advancedBlendBusy--;
+    return true;
+  }
+  /**
+   * Close an advanced-blend bracket: drain the offscreen, return to the
+   * parent target, and composite through {@link BlendEffect}.
+   * @ignore
+   */
+  _closeAdvancedBlend() {
+    const gl = this.gl;
+    const canvas = this.getCanvas();
+    const w = canvas.width;
+    const h = canvas.height;
+    this._advancedBlendBusy++;
+    this._advancedBlendOpen = false;
+    this.currentBatcher.flush();
+    this._advancedBlendTarget.unbind();
+    if (this._advancedBlendParent !== null) {
+      this._advancedBlendParent.bind();
+    }
+    this._advancedBlendParent = null;
+    this.invalidateTextureUnit(0);
+    this.setViewport(0, 0, w, h);
+    emit(RENDER_TARGET_CHANGED, this);
+    if (this._advancedBlendStencil === true) {
+      gl.enable(gl.STENCIL_TEST);
+    }
+    const mode = this.currentBlendMode;
+    this.setBlendMode("normal", true);
+    this.blitEffect(
+      this._advancedBlendTarget.texture,
+      0,
+      0,
+      w,
+      h,
+      this._advancedBlendEffect,
+      true
+    );
+    this.currentBatcher.flush();
+    this.currentBlendMode = mode;
+    this._advancedBlendBusy--;
+  }
   /**
    * Blit a texture to the screen through a shader effect.
    * Draws a screen-aligned quad using the given texture as source
@@ -43505,6 +44075,7 @@ var WebGLRenderer = class extends Renderer {
    * @param {boolean} [keepBlend=false] - if true, keep current blend mode (for sprite compositing)
    */
   blitEffect(source, x, y, width, height, shader, keepBlend = false) {
+    this._advancedBlendBusy++;
     this.flush();
     const batcher = this.setBatcher("quad");
     _savedTransform.copy(this.currentTransform);
@@ -43522,6 +44093,7 @@ var WebGLRenderer = class extends Renderer {
     this.currentTransform.copy(_savedTransform);
     this.projectionMatrix.copy(_savedProjection);
     batcher.setProjection(this.projectionMatrix);
+    this._advancedBlendBusy--;
   }
   /**
    * set/change the current projection matrix (WebGL only)
@@ -43608,6 +44180,7 @@ var WebGLRenderer = class extends Renderer {
    * Clear the frame buffer
    */
   clear() {
+    this._drainAdvancedBlend();
     const gl = this.gl;
     const clearColor = this.backgroundColor.toArray();
     gl.clearColor(clearColor[0], clearColor[1], clearColor[2], clearColor[3]);
@@ -43621,6 +44194,7 @@ var WebGLRenderer = class extends Renderer {
    * @param {boolean} [opaque=false] - Allow transparency [default] or clear the surface completely [true]
    */
   clearColor(color = "#000000", opaque = false) {
+    this._drainAdvancedBlend();
     let glArray;
     const gl = this.gl;
     if (color instanceof Color) {
@@ -43985,12 +44559,31 @@ var WebGLRenderer = class extends Renderer {
    * return a reference to the system 2d Context
    * @returns {WebGLRenderingContext} the current WebGL context
    */
+  /**
+   * The shader program the GL context actually has bound.
+   *
+   * Backed by the CONTEXT rather than by a field on this renderer, because
+   * `GLShader` binds programs too — writing a uniform calls `useProgram`,
+   * and a freshly linked program is left bound — and it is constructed with
+   * a bare `gl`, so it cannot reach a renderer-owned cache. A field here
+   * would silently drift out of step with GL, and every batcher that
+   * compares against it (`syncProgram`, the mesh and primitive paths) would
+   * skip a rebind it actually needed, drawing a pending batch through the
+   * wrong program.
+   * @type {WebGLProgram|undefined}
+   */
+  get currentProgram() {
+    return this.gl.__meCurrentProgram;
+  }
+  set currentProgram(value) {
+    this.gl.__meCurrentProgram = value;
+  }
   getContext() {
     return this.gl;
   }
   /**
    * set the current blend mode for this renderer. <br>
-   * All renderers support: <br>
+   * Every renderer supports the full set: <br>
    * - "normal" : draws new content on top of the existing content <br>
    * <img src="../images/normal-blendmode.png" width="180"/> <br>
    * - "add", "additive", or "lighter" : color values are added together <br>
@@ -43999,71 +44592,58 @@ var WebGLRenderer = class extends Renderer {
    * <img src="../images/multiply-blendmode.png" width="180"/> <br>
    * - "screen" : pixels are inverted, multiplied, and inverted again (opposite of multiply) <br>
    * <img src="../images/screen-blendmode.png" width="180"/> <br>
-   * WebGL2 additionally supports: <br>
    * - "darken" : retains the darkest pixels of both layers <br>
    * <img src="../images/darken-blendmode.png" width="180"/> <br>
    * - "lighten" : retains the lightest pixels of both layers <br>
    * <img src="../images/lighten-blendmode.png" width="180"/> <br>
+   * - "overlay" : multiplies or screens, depending on the backdrop <br>
+   * <img src="../images/overlay-blendmode.png" width="180"/> <br>
+   * - "hard-light" : overlay with the layers swapped — a harsh spotlight <br>
+   * <img src="../images/hard-light-blendmode.png" width="180"/> <br>
+   * - "soft-light" : a diffused spotlight, gentler than hard-light <br>
+   * <img src="../images/soft-light-blendmode.png" width="180"/> <br>
+   * - "color-dodge" : brightens the backdrop to reflect the source <br>
+   * <img src="../images/color-dodge-blendmode.png" width="180"/> <br>
+   * - "color-burn" : darkens the backdrop to reflect the source <br>
+   * <img src="../images/color-burn-blendmode.png" width="180"/> <br>
+   * - "difference" : the absolute difference of the two layers <br>
+   * <img src="../images/difference-blendmode.png" width="180"/> <br>
+   * - "exclusion" : like difference, but lower in contrast <br>
+   * <img src="../images/exclusion-blendmode.png" width="180"/> <br>
    * - "none" : blending disabled — the source replaces the destination
-   * outright, alpha included (matches the WebGPU renderer's "none") <br>
-   * Other CSS blend modes ("overlay", "color-dodge", "color-burn", "hard-light", "soft-light",
-   * "difference", "exclusion") may be supported by the Canvas renderer (browser-dependent)
-   * and will always fall back to "normal" in WebGL. <br>
+   * outright, alpha included <br>
+   * A few draw types cannot honour every mode — 3D meshes, and fills using
+   * a {@link Gradient} — and fall back to "normal" with a one-time console
+   * warning. `setBlendMode` returns what it actually applied, so comparing
+   * the result against your request detects that case.
    * @see https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/globalCompositeOperation
    * @param {string} [mode="normal"] - blend mode
-   * @param {boolean} [premultipliedAlpha=true] - whether textures use premultiplied alpha (affects source blend factor)
+   * @param {boolean} [premultipliedAlpha=true] - whether textures use premultiplied alpha (affects the source blend factor)
    * @returns {string} the blend mode actually applied (may differ if the requested mode is unsupported)
    */
   setBlendMode(mode = "normal", premultipliedAlpha = true) {
     if (this.currentBlendMode !== mode || this.currentPremultipliedAlpha !== premultipliedAlpha) {
       const gl = this.gl;
+      this._drainAdvancedBlend();
       this.flush();
-      gl.enable(gl.BLEND);
       this.currentBlendMode = mode;
       this.currentPremultipliedAlpha = premultipliedAlpha;
-      const srcAlpha = premultipliedAlpha ? gl.ONE : gl.SRC_ALPHA;
-      switch (mode) {
-        case "screen":
-          gl.blendEquation(gl.FUNC_ADD);
-          gl.blendFunc(gl.ONE, gl.ONE_MINUS_SRC_COLOR);
-          break;
-        // exclusion(a, b) = a + b - 2ab. Unlike the other CSS advanced
-        // modes this needs no per-pixel branch — it falls straight out
-        // of `src * sfactor + dst * dfactor`:
-        //   s*(1-d) + d*(1-s) = s + d - 2sd
-        // Same caveat as `screen` above: the identity is exact for an
-        // opaque source and approximate for a translucent one, because
-        // the factors act on the premultiplied colour.
-        case "exclusion":
-          gl.blendEquation(gl.FUNC_ADD);
-          gl.blendFunc(gl.ONE_MINUS_DST_COLOR, gl.ONE_MINUS_SRC_COLOR);
-          break;
-        case "lighter":
-        case "additive":
-        case "add":
-          gl.blendEquation(gl.FUNC_ADD);
-          gl.blendFunc(srcAlpha, gl.ONE);
-          break;
-        case "multiply":
-          gl.blendEquation(gl.FUNC_ADD);
-          gl.blendFunc(gl.DST_COLOR, gl.ONE_MINUS_SRC_ALPHA);
-          break;
-        case "darken":
-          gl.blendEquation(gl.MIN);
-          gl.blendFunc(gl.ONE, gl.ONE);
-          break;
-        case "lighten":
-          gl.blendEquation(gl.MAX);
-          gl.blendFunc(gl.ONE, gl.ONE);
-          break;
-        case "none":
-          gl.disable(gl.BLEND);
-          break;
-        default:
-          gl.blendEquation(gl.FUNC_ADD);
-          gl.blendFunc(srcAlpha, gl.ONE_MINUS_SRC_ALPHA);
-          this.currentBlendMode = "normal";
-          break;
+      if (typeof GL_BLEND_OP === "undefined") {
+        initBlendEnums(gl);
+      }
+      const state3 = blendStateFor(normalizeBlendMode(mode), premultipliedAlpha);
+      if (typeof state3 === "undefined") {
+        gl.disable(gl.BLEND);
+      } else {
+        gl.enable(gl.BLEND);
+        gl.blendEquation(GL_BLEND_OP[state3.operation]);
+        gl.blendFunc(
+          GL_BLEND_FACTOR[state3.srcFactor],
+          GL_BLEND_FACTOR[state3.dstFactor]
+        );
+      }
+      if (isSupportedBlendMode(mode) === false) {
+        this.currentBlendMode = "normal";
       }
     }
     return this.currentBlendMode;
@@ -44704,6 +45284,12 @@ var WebGLRenderer = class extends Renderer {
     const grad = this._currentGradient;
     const hasMask = this.maskLevel > 0;
     this._currentGradient = null;
+    const bracketed = isAdvancedBlendMode(this.currentBlendMode);
+    if (bracketed === true) {
+      this._warnAdvancedBlendFallback("gradient fills");
+      this._drainAdvancedBlend();
+    }
+    this._advancedBlendBusy++;
     this.flush();
     gl.enable(gl.STENCIL_TEST);
     gl.colorMask(false, false, false, false);
@@ -44740,16 +45326,17 @@ var WebGLRenderer = class extends Renderer {
     } else {
       gl.disable(gl.STENCIL_TEST);
     }
+    this._advancedBlendBusy--;
   }
   /**
    * Reset (overrides) the renderer transformation matrix to the
    * identity one, and then apply the given transformation matrix.
    * @param {Matrix2d|Matrix3d|number} a - a matrix to transform by, or the a component to multiply the current matrix by
-   * @param {number} b - the b component to multiply the current matrix by
-   * @param {number} c - the c component to multiply the current matrix by
-   * @param {number} d - the d component to multiply the current matrix by
-   * @param {number} e - the e component to multiply the current matrix by
-   * @param {number} f - the f component to multiply the current matrix by
+   * @param {number} [b] - the b component to multiply the current matrix by; omitted when `a` is a matrix
+   * @param {number} [c] - the c component to multiply the current matrix by; omitted when `a` is a matrix
+   * @param {number} [d] - the d component to multiply the current matrix by; omitted when `a` is a matrix
+   * @param {number} [e] - the e component to multiply the current matrix by; omitted when `a` is a matrix
+   * @param {number} [f] - the f component to multiply the current matrix by; omitted when `a` is a matrix
    */
   setTransform(a, b, c, d, e, f) {
     this.resetTransform();
@@ -44759,11 +45346,11 @@ var WebGLRenderer = class extends Renderer {
    * Multiply given matrix into the renderer tranformation matrix
    * @see {@link WebGLRenderer.setTransform} which will reset the current transform matrix prior to performing the new transformation
    * @param {Matrix2d|Matrix3d|number} a - a matrix to transform by, or the a component to multiply the current matrix by
-   * @param {number} b - the b component to multiply the current matrix by
-   * @param {number} c - the c component to multiply the current matrix by
-   * @param {number} d - the d component to multiply the current matrix by
-   * @param {number} e - the e component to multiply the current matrix by
-   * @param {number} f - the f component to multiply the current matrix by
+   * @param {number} [b] - the b component to multiply the current matrix by; omitted when `a` is a matrix
+   * @param {number} [c] - the c component to multiply the current matrix by; omitted when `a` is a matrix
+   * @param {number} [d] - the d component to multiply the current matrix by; omitted when `a` is a matrix
+   * @param {number} [e] - the e component to multiply the current matrix by; omitted when `a` is a matrix
+   * @param {number} [f] - the f component to multiply the current matrix by; omitted when `a` is a matrix
    */
   transform(a, b, c, d, e, f) {
     if (typeof a === "object") {
@@ -45752,6 +46339,9 @@ function dispatchEvent(normalizedEvents2) {
       }
       lastTimeStamp = pointer2.event.timeStamp;
     }
+    const worldOffset = _app2.world.pos;
+    const absoluteWorldX = pointer2.gameWorldX + worldOffset.x;
+    const absoluteWorldY = pointer2.gameWorldY + worldOffset.y;
     currentPointer.pos.set(pointer2.gameWorldX, pointer2.gameWorldY);
     currentPointer.setSize(pointer2.width, pointer2.height);
     if (POINTER_MOVE.includes(pointer2.type)) {
@@ -45764,6 +46354,22 @@ function dispatchEvent(normalizedEvents2) {
       (a, b) => _app2.world._sortReverseZ(a, b),
       void 0
     );
+    if (worldOffset.x !== 0 || worldOffset.y !== 0) {
+      currentPointer.pos.set(absoluteWorldX, absoluteWorldY);
+      const absoluteCandidates = _app2.world.broadphase.retrieve(
+        currentPointer,
+        (a, b) => _app2.world._sortReverseZ(a, b),
+        void 0
+      );
+      for (const candidate of candidates) {
+        if (candidate.isFloating === true && !absoluteCandidates.includes(candidate)) {
+          absoluteCandidates.push(candidate);
+        }
+      }
+      candidates = absoluteCandidates.sort(
+        (a, b) => _app2.world._sortReverseZ(a, b)
+      );
+    }
     candidates = candidates.concat([_app2.viewport]);
     for (let c = candidates.length, candidate; c--, candidate = candidates[c]; ) {
       if (eventHandlers.has(candidate) && candidate.isKinematic !== true) {
@@ -45780,10 +46386,15 @@ function dispatchEvent(normalizedEvents2) {
         }
         if (typeof ancestor !== "undefined") {
           const parentBounds = ancestor.getBounds();
-          pointer2.gameLocalX = pointer2.gameX - parentBounds.x;
-          pointer2.gameLocalY = pointer2.gameY - parentBounds.y;
+          if (region.isFloating === true) {
+            pointer2.gameLocalX = pointer2.gameX - parentBounds.x;
+            pointer2.gameLocalY = pointer2.gameY - parentBounds.y;
+          } else {
+            pointer2.gameLocalX = absoluteWorldX - parentBounds.x;
+            pointer2.gameLocalY = absoluteWorldY - parentBounds.y;
+          }
         }
-        const eventInBounds = bounds.contains(pointer2.gameX, pointer2.gameY);
+        const eventInBounds = region.isFloating === true ? bounds.contains(pointer2.gameX, pointer2.gameY) : bounds.contains(absoluteWorldX, absoluteWorldY);
         switch (pointer2.type) {
           case POINTER_MOVE[0]:
           case POINTER_MOVE[1]:
@@ -49468,6 +50079,7 @@ var Light2d = class extends Renderable {
 };
 
 // src/particles/particle.ts
+var _spawn = new Vector2d();
 var Particle = class extends Renderable {
   vel;
   image;
@@ -49479,7 +50091,6 @@ var Particle = class extends Renderable {
   wind;
   followTrajectory;
   onlyInViewport;
-  accurateBounds;
   _deltaInv;
   _halfW;
   _halfH;
@@ -49499,13 +50110,40 @@ var Particle = class extends Renderable {
     this.vel = vector2dPool.get();
     this.onResetEvent(emitter, true);
   }
+  /**
+   * Whether the bounds need recomputing before anyone reads them.
+   *
+   * A `Renderable` refreshes its bounds eagerly, from a callback fired on
+   * every `pos` assignment. That is the right trade for a scene object, and
+   * the wrong one for a particle: `update()` writes `pos.x` and `pos.y`
+   * separately, so the callback fires TWICE per particle per frame, and both
+   * runs happen before `currentTransform` is rebuilt — deriving bounds from
+   * the previous frame's matrix and then throwing that away. Measured, the
+   * redundant pass was about two thirds of the whole particle update loop.
+   *
+   * So a particle invalidates instead of recomputing, and pays once, on
+   * read, for particles something actually looks at.
+   *
+   * Deliberately not a `#private` field: `updateBounds()` is reached from the
+   * base constructor chain (`Polygon.setVertices`) before a subclass's field
+   * initializers have run, and writing an undeclared private field throws.
+   * @ignore
+   */
+  _boundsDirty = true;
   /**
    * @ignore
    */
   onResetEvent(emitter, newInstance = false) {
     const image = emitter.settings.image;
-    if (!newInstance) {
+    const map = emitter._spawnMap;
+    if (typeof map !== "undefined") {
+      _spawn.set(emitter.getRandomPointX(), emitter.getRandomPointY());
+      map.apply(_spawn);
+      this.pos.set(_spawn.x, _spawn.y);
+    } else {
       this.pos.set(emitter.getRandomPointX(), emitter.getRandomPointY());
+    }
+    if (!newInstance) {
       this.resize(image.width, image.height);
       this.currentTransform.identity();
     }
@@ -49513,7 +50151,13 @@ var Particle = class extends Renderable {
     this._halfW = this.width / 2;
     this._halfH = this.height / 2;
     this.alwaysUpdate = true;
+    this.pos.setCallback(() => {
+      this._boundsDirty = true;
+      this.isDirty = true;
+    });
+    this._boundsDirty = true;
     this.anchorPoint.set(0, 0);
+    this.autoTransform = false;
     if (typeof emitter.settings.tint === "string") {
       this.tint.parseCSS(emitter.settings.tint);
     }
@@ -49538,7 +50182,6 @@ var Particle = class extends Renderable {
     this.wind = emitter.settings.wind;
     this.followTrajectory = emitter.settings.followTrajectory;
     this.onlyInViewport = emitter.settings.onlyInViewport;
-    this.accurateBounds = emitter.settings.accurateBounds;
     this._deltaInv = emitter._deltaInv;
     if (!emitter.settings.followTrajectory) {
       this._angle = randomFloat(
@@ -49603,12 +50246,108 @@ var Particle = class extends Renderable {
       0,
       1
     );
-    if (this.accurateBounds) {
-      this.updateBounds();
-    }
     this.isDirty = this.inViewport || !this.onlyInViewport;
     return super.update(dt);
   }
+  /**
+   * `autoTransform` is off (see `onResetEvent`), so the base `preDraw` will
+   * not apply the matrix — append it here instead, unconjugated. Appending
+   * after `super` rather than splicing into it is order-equivalent for a
+   * particle specifically: no flip, no mask, and the anchor is zeroed, so
+   * nothing the base method emits interacts with this.
+   * @ignore
+   */
+  preDraw(renderer) {
+    super.preDraw(renderer);
+    if (!this.currentTransform.isIdentity()) {
+      renderer.transform(this.currentTransform);
+    }
+  }
+  /**
+   * `currentTransform` already places the particle, so the frame it
+   * produces is positioned — only the ancestors' contribution is still
+   * missing. The base implementation would add this particle's own `pos` on
+   * top of a matrix that already contains it, counting it twice.
+   * @ignore
+   */
+  /**
+   * Bounds are recomputed here rather than when `pos` moves, so a particle
+   * nothing looks at this frame pays nothing at all.
+   *
+   * `updateBounds()` deliberately keeps its eager contract — a caller that
+   * asks for a recompute, such as {@link Container} aggregating child bounds
+   * under `enableChildBoundsUpdate`, still gets fresh values back.
+   * @ignore
+   */
+  getBounds() {
+    const bounds = super.getBounds();
+    if (this._boundsDirty) {
+      this.updateBounds();
+    }
+    return bounds;
+  }
+  updateBounds(absolute = true) {
+    this._boundsDirty = false;
+    if (!this.isRenderable) {
+      return super.updateBounds(absolute);
+    }
+    const bounds = this.getBounds();
+    bounds.clear();
+    bounds.addFrame(0, 0, this.width, this.height, this.currentTransform);
+    if (absolute && this.ancestor) {
+      const absPos = this.#frameOrigin().getAbsolutePosition();
+      bounds.centerOn(
+        absPos.x + bounds.x + bounds.width / 2,
+        absPos.y + bounds.y + bounds.height / 2
+      );
+    }
+    return bounds;
+  }
+  /**
+   * The container this particle's position is measured from — its emitter
+   * under the default local reference space, something else otherwise.
+   * @ignore
+   */
+  #frameOrigin() {
+    const emitter = this.ancestor;
+    const space = emitter?.settings?.referenceSpace;
+    if (typeof space === "undefined" || space === "local") {
+      return emitter;
+    }
+    if (space === "world") {
+      return emitter.ancestor ?? emitter;
+    }
+    const target = space;
+    return target && typeof target.pos !== "undefined" ? target : emitter;
+  }
+  /**
+   * A particle is positioned within its reference frame, which is not
+   * necessarily its parent — so summing up the ancestor chain, as the base
+   * implementation does, would measure from the wrong place.
+   * @ignore
+   */
+  getAbsolutePosition() {
+    const origin = this.#frameOrigin();
+    if (origin === this.ancestor) {
+      return super.getAbsolutePosition();
+    }
+    if (typeof this._absPos === "undefined") {
+      this._absPos = vector3dPool.get();
+    }
+    this._absPos.set(this.pos.x, this.pos.y, this.depth);
+    if (!this.floating) {
+      this._absPos.add(origin.getAbsolutePosition());
+    }
+    return this._absPos;
+  }
+  /**
+   * With the placement in `currentTransform` and `autoTransform` off, the
+   * base composition would describe a transform this class never applies.
+   * @ignore
+   */
+  getLocalTransform(out) {
+    return out.copy(this.currentTransform);
+  }
   /**
    * @ignore
    */
@@ -49847,6 +50586,27 @@ var Entity = class _Entity extends Renderable {
       );
     }
   }
+  /**
+   * An entity replaces {@link Renderable#preDraw} wholesale — no flip, no
+   * conjugation, no anchor offset, just its position biased by the body
+   * bounds — so the inherited composition would describe a transform this
+   * class never applies. Mirrors the `preDraw` above instead.
+   * @protected
+   * @param {Matrix3d} out - matrix to write into
+   * @returns {Matrix3d} `out`, for chaining
+   */
+  getLocalTransform(out) {
+    const bounds = this.body.getBounds();
+    out.identity();
+    out.translate(this.pos.x + bounds.x, this.pos.y + bounds.y);
+    if (this.renderable instanceof Renderable) {
+      out.translate(
+        this.anchorPoint.x * bounds.width,
+        this.anchorPoint.y * bounds.height
+      );
+    }
+    return out;
+  }
   /**
    * draw this entity (automatically called by melonJS)
    * @param {CanvasRenderer|WebGLRenderer} renderer - a renderer instance
@@ -50477,7 +51237,7 @@ var Trigger = class extends Renderable {
 };
 
 // src/version.ts
-var version = "20.1.1";
+var version = "20.2.0";
 
 // src/system/bootstrap.ts
 var initialized = false;
@@ -52593,72 +53353,12 @@ var FRAME_UNIFORM_SIZE = 80;
 var CLEAR_UNIFORM_SIZE = 16;
 
 // src/video/webgpu/pipeline/cache.js
+function gpuBlendState(mode, premultipliedAlpha) {
+  const component = blendStateFor(mode, premultipliedAlpha);
+  return typeof component === "undefined" ? void 0 : { color: component, alpha: component };
+}
 var MAX_QUAD_TEXTURES = 8;
 var DEPTH_STENCIL_FORMAT = "depth24plus-stencil8";
-function blendStateFor(mode, premultipliedAlpha) {
-  const src = premultipliedAlpha ? "one" : "src-alpha";
-  let component;
-  switch (mode) {
-    case "none":
-      return void 0;
-    case "additive":
-      component = { operation: "add", srcFactor: src, dstFactor: "one" };
-      break;
-    case "multiply":
-      component = {
-        operation: "add",
-        srcFactor: "dst",
-        dstFactor: "one-minus-src-alpha"
-      };
-      break;
-    case "exclusion":
-      component = {
-        operation: "add",
-        srcFactor: "one-minus-dst",
-        dstFactor: "one-minus-src"
-      };
-      break;
-    case "screen":
-      component = {
-        operation: "add",
-        srcFactor: "one",
-        dstFactor: "one-minus-src"
-      };
-      break;
-    case "darken":
-      component = { operation: "min", srcFactor: "one", dstFactor: "one" };
-      break;
-    case "lighten":
-      component = { operation: "max", srcFactor: "one", dstFactor: "one" };
-      break;
-    default:
-      component = {
-        operation: "add",
-        srcFactor: src,
-        dstFactor: "one-minus-src-alpha"
-      };
-      break;
-  }
-  return { color: component, alpha: component };
-}
-function normalizeBlendMode(mode) {
-  switch (mode) {
-    case "none":
-    case "multiply":
-    case "screen":
-    case "darken":
-    case "lighten":
-    case "exclusion":
-    case "normal":
-      return mode;
-    case "additive":
-    case "add":
-    case "lighter":
-      return "additive";
-    default:
-      return "normal";
-  }
-}
 var STENCIL_STATES = {
   none: {
     stencil: {
@@ -53004,7 +53704,7 @@ var WebGPUPipelineCache = class _WebGPUPipelineCache {
           targets: [
             {
               format: this.format,
-              blend: shaderKey === "clear" ? void 0 : blendStateFor(blend, pma),
+              blend: shaderKey === "clear" ? void 0 : gpuBlendState(blend, pma),
               writeMask: stencil.colorWriteMask
             }
           ]
@@ -53085,9 +53785,16 @@ var WebGPUQuadBatcher = class extends WebGPUBatcher {
       },
       onEvict: (slot) => {
         this.segmentEntries[slot] = void 0;
+        if (this._memoSlot === slot) {
+          this._memoView = null;
+        }
       }
     });
     this.segmentEntries = [];
+    this._memoView = null;
+    this._memoFilter = null;
+    this._memoWrap = null;
+    this._memoSlot = 0;
     this.segmentGroup = null;
     this.composedGroups = /* @__PURE__ */ new Map();
     this.resourceIds = /* @__PURE__ */ new WeakMap();
@@ -53186,17 +53893,24 @@ var WebGPUQuadBatcher = class extends WebGPUBatcher {
     const record = store.getResidentRecord(texture, { force: reupload });
     const wrap = texture.repeat ?? "no-repeat";
     const filter = typeof texture.filter === "string" ? texture.filter : renderer.getDefaultTextureFilter();
+    if (record.view === this._memoView && filter === this._memoFilter && wrap === this._memoWrap) {
+      return this._memoSlot;
+    }
     const slotKey = `${this.resourceId(record.view)}|${filter}|${wrap}`;
-    if (this.slotTable.peek(slotKey) === void 0) {
-      const slot = this.slotTable.slotFor(slotKey);
-      this.segmentEntries[slot] = {
+    let resolved = this.slotTable.peek(slotKey);
+    if (resolved === void 0) {
+      resolved = this.slotTable.slotFor(slotKey);
+      this.segmentEntries[resolved] = {
         view: record.view,
         sampler: store.getSampler(filter, wrap)
       };
       this.segmentGroup = null;
-      return slot;
     }
-    return this.slotTable.peek(slotKey);
+    this._memoView = record.view;
+    this._memoFilter = filter;
+    this._memoWrap = wrap;
+    this._memoSlot = resolved;
+    return resolved;
   }
   /**
    * a stable id for a GPU resource object (bind-group composition keys)
@@ -55236,7 +55950,7 @@ function resolveDepthOps(meshDepthActive, pendingDepthClear) {
     depthStoreOp: "store"
   };
 }
-var WebGPURenderer = class extends Renderer {
+var WebGPURenderer = class _WebGPURenderer extends Renderer {
   /**
    * @param {ApplicationSettings} options - The renderer parameters
    */
@@ -55273,6 +55987,13 @@ var WebGPURenderer = class extends Renderer {
     this.commandEncoder = null;
     this.renderPass = null;
     this.currentRenderTarget = null;
+    this._advancedBlendEffect = void 0;
+    this._advancedBlendCapture = void 0;
+    this._advancedBlendTarget = void 0;
+    this._advancedBlendOpen = false;
+    this._advancedBlendBusy = 0;
+    this._advancedBlendParent = null;
+    this._advancedBlendWarned = /* @__PURE__ */ new Set();
     this.pendingColorClear = false;
     this.pendingClearValue = null;
     this.pendingStencilClear = false;
@@ -55811,6 +56532,16 @@ var WebGPURenderer = class extends Renderer {
    *   frame, or null when no device is available
    */
   toFrameTexture(options = {}) {
+    const busy = this._advancedBlendBusy;
+    this._advancedBlendBusy = (busy ?? 0) + 1;
+    try {
+      return _WebGPURenderer.prototype._toFrameTexture.call(this, options);
+    } finally {
+      this._advancedBlendBusy = busy;
+    }
+  }
+  /** @ignore */
+  _toFrameTexture(options = {}) {
     if (typeof this.device === "undefined") {
       return null;
     }
@@ -56026,6 +56757,7 @@ var WebGPURenderer = class extends Renderer {
    * @override
    */
   blitEffect(source, x, y, width, height, effect, keepBlend = false) {
+    this._advancedBlendBusy++;
     const batcher = this.setBatcher("quad");
     blitSavedProjection.copy(this.projectionMatrix);
     this.projectionMatrix.ortho(0, width, height, 0, -1, 1);
@@ -56033,6 +56765,106 @@ var WebGPURenderer = class extends Renderer {
     batcher.blitTexture(source, x, y, width, height, effect, keepBlend);
     this.projectionMatrix.copy(blitSavedProjection);
     this.pushFrameGlobals();
+    this._advancedBlendBusy--;
+  }
+  /**
+   * Say once, per excluded path and mode, that an advanced blend mode is
+   * falling back to `"normal"`. A silent data-dependent fallback is exactly
+   * what the advanced-blend work exists to remove, so the exclusions are
+   * loud.
+   * @param {string} what - the excluded path, named for the message
+   * @ignore
+   */
+  _warnAdvancedBlendFallback(what) {
+    const key = `${what}:${this.currentBlendMode}`;
+    if (this._advancedBlendWarned.has(key)) {
+      return;
+    }
+    this._advancedBlendWarned.add(key);
+    console.warn(
+      `WebGPURenderer: blend mode "${this.currentBlendMode}" is not supported for ${what} and falls back to "normal"`
+    );
+  }
+  /**
+   * Close a pending advanced-blend bracket, if one is open and we are not
+   * already inside the bracket machinery.
+   * @ignore
+   */
+  _drainAdvancedBlend() {
+    if (this._advancedBlendOpen === true && this._advancedBlendBusy === 0) {
+      this._closeAdvancedBlend();
+    }
+  }
+  /**
+   * Open an advanced-blend bracket: capture the destination, then redirect
+   * this draw into an offscreen target.
+   * @returns {boolean} false when the effect could not be realized, in which
+   * case the draw proceeds unbracketed (plain source-over)
+   * @ignore
+   */
+  _openAdvancedBlend() {
+    const canvas = this.getCanvas();
+    const w = canvas.width;
+    const h = canvas.height;
+    this._advancedBlendBusy++;
+    if (typeof this._advancedBlendEffect === "undefined") {
+      this._advancedBlendEffect = new BlendEffect(this);
+    }
+    if (this._advancedBlendEffect.enabled !== true) {
+      this._advancedBlendBusy--;
+      this._warnAdvancedBlendFallback("this device");
+      return false;
+    }
+    this._advancedBlendEffect.setBlendMode(this.currentBlendMode);
+    this.currentBatcher?.flush();
+    this._advancedBlendCapture = this.toFrameTexture({
+      target: this._advancedBlendCapture ?? null
+    });
+    this._advancedBlendEffect.setTexture(
+      "backdrop",
+      this._advancedBlendCapture
+    );
+    this._advancedBlendParent = this.currentRenderTarget;
+    if (typeof this._advancedBlendTarget === "undefined") {
+      this._advancedBlendTarget = new WebGPURenderTarget(this, w, h, {
+        sampleCount: 1
+      });
+    } else {
+      this._advancedBlendTarget.resize(w, h);
+    }
+    this.setRenderTarget(this._advancedBlendTarget, { clear: true });
+    this._advancedBlendOpen = true;
+    this._advancedBlendBusy--;
+    return true;
+  }
+  /**
+   * Close an advanced-blend bracket: drain the offscreen, retarget to the
+   * parent, and composite through {@link BlendEffect}.
+   * @ignore
+   */
+  _closeAdvancedBlend() {
+    const canvas = this.getCanvas();
+    const w = canvas.width;
+    const h = canvas.height;
+    this._advancedBlendBusy++;
+    this._advancedBlendOpen = false;
+    this.currentBatcher?.flush();
+    this.setRenderTarget(this._advancedBlendParent);
+    this._advancedBlendParent = null;
+    const mode = this.currentBlendMode;
+    this.setBlendMode("normal", true);
+    this.blitEffect(
+      this._advancedBlendTarget,
+      0,
+      0,
+      w,
+      h,
+      this._advancedBlendEffect,
+      true
+    );
+    this.currentBatcher?.flush();
+    this.currentBlendMode = mode;
+    this._advancedBlendBusy--;
   }
   /**
    * a draw is about to be recorded outside the clear()/flush() bracket
@@ -56056,6 +56888,9 @@ var WebGPURenderer = class extends Renderer {
    * @override
    */
   flush() {
+    if (this._advancedBlendOpen === true && this._advancedBlendBusy === 0) {
+      this._closeAdvancedBlend();
+    }
     this.currentBatcher?.flush();
     if (this.renderPass !== null) {
       this.renderPass.end();
@@ -56090,6 +56925,9 @@ var WebGPURenderer = class extends Renderer {
     this.pendingColorClear = false;
     this.pendingDepthClear = false;
     this.currentPipeline = null;
+    for (const batcher of this.batchers.values()) {
+      batcher.reset();
+    }
     this.destroyRetiredTextures();
   }
   /**
@@ -56145,6 +56983,7 @@ var WebGPURenderer = class extends Renderer {
     if (typeof this.device === "undefined") {
       return;
     }
+    this._drainAdvancedBlend();
     this.currentBatcher?.flush();
     const pass = this.ensurePass();
     let rgba;
@@ -56241,6 +57080,18 @@ var WebGPURenderer = class extends Renderer {
     if (typeof batcher === "undefined") {
       throw new Error("Invalid Batcher");
     }
+    if (this._advancedBlendBusy === 0) {
+      if (this._advancedBlendOpen === true) {
+        this._closeAdvancedBlend();
+      }
+      if (isAdvancedBlendMode(this.currentBlendMode) === true) {
+        if (name === "mesh" || name === "litMesh") {
+          this._warnAdvancedBlendFallback("3D meshes");
+        } else {
+          this._openAdvancedBlend();
+        }
+      }
+    }
     if (this.currentBatcher !== batcher) {
       if (name !== "mesh" && name !== "litMesh" && // see WebGLRenderer#_canDrainShadows: a transition raised while
       // a mask is being stencilled in (colour writes off) or inside a
@@ -56477,22 +57328,56 @@ var WebGPURenderer = class extends Renderer {
     }
   }
   /**
-   * Set the blend mode for subsequent draws. Under WebGPU blending is
-   * pipeline state: the change is recorded (after draining vertices
-   * queued under the previous mode) and the next batcher flush picks the
-   * matching pipeline variant.
-   * @param {string} [mode="normal"] - blend mode ("normal", "multiply", "additive"/"lighter", "screen", "darken", "lighten", "none")
+   * set the current blend mode for this renderer. <br>
+   * Every renderer supports the full set: <br>
+   * - "normal" : draws new content on top of the existing content <br>
+   * <img src="../images/normal-blendmode.png" width="180"/> <br>
+   * - "add", "additive", or "lighter" : color values are added together <br>
+   * <img src="../images/add-blendmode.png" width="180"/> <br>
+   * - "multiply" : pixels are multiplied, resulting in a darker picture <br>
+   * <img src="../images/multiply-blendmode.png" width="180"/> <br>
+   * - "screen" : pixels are inverted, multiplied, and inverted again (opposite of multiply) <br>
+   * <img src="../images/screen-blendmode.png" width="180"/> <br>
+   * - "darken" : retains the darkest pixels of both layers <br>
+   * <img src="../images/darken-blendmode.png" width="180"/> <br>
+   * - "lighten" : retains the lightest pixels of both layers <br>
+   * <img src="../images/lighten-blendmode.png" width="180"/> <br>
+   * - "overlay" : multiplies or screens, depending on the backdrop <br>
+   * <img src="../images/overlay-blendmode.png" width="180"/> <br>
+   * - "hard-light" : overlay with the layers swapped — a harsh spotlight <br>
+   * <img src="../images/hard-light-blendmode.png" width="180"/> <br>
+   * - "soft-light" : a diffused spotlight, gentler than hard-light <br>
+   * <img src="../images/soft-light-blendmode.png" width="180"/> <br>
+   * - "color-dodge" : brightens the backdrop to reflect the source <br>
+   * <img src="../images/color-dodge-blendmode.png" width="180"/> <br>
+   * - "color-burn" : darkens the backdrop to reflect the source <br>
+   * <img src="../images/color-burn-blendmode.png" width="180"/> <br>
+   * - "difference" : the absolute difference of the two layers <br>
+   * <img src="../images/difference-blendmode.png" width="180"/> <br>
+   * - "exclusion" : like difference, but lower in contrast <br>
+   * <img src="../images/exclusion-blendmode.png" width="180"/> <br>
+   * - "none" : blending disabled — the source replaces the destination
+   * outright, alpha included <br>
+   * A few draw types cannot honour every mode — 3D meshes, and fills using
+   * a {@link Gradient} — and fall back to "normal" with a one-time console
+   * warning. `setBlendMode` returns what it actually applied, so comparing
+   * the result against your request detects that case.
+   * @see https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/globalCompositeOperation
+   * @param {string} [mode="normal"] - blend mode
    * @param {boolean} [premultipliedAlpha=true] - whether textures use premultiplied alpha (affects the source blend factor)
-   * @returns {string} the blend mode actually applied
+   * @returns {string} the blend mode actually applied (may differ if the requested mode is unsupported)
    */
   setBlendMode(mode = "normal", premultipliedAlpha = true) {
     const normalized = normalizeBlendMode(mode);
-    if (this.currentBlendMode !== normalized || this.premultipliedAlpha !== premultipliedAlpha) {
+    const advanced = isAdvancedBlendMode(mode);
+    const tracked = advanced === true ? mode : normalized;
+    if (this.currentBlendMode !== tracked || this.premultipliedAlpha !== premultipliedAlpha) {
+      this._drainAdvancedBlend();
       this.currentBatcher?.flush();
-      this.currentBlendMode = normalized;
+      this.currentBlendMode = tracked;
       this.premultipliedAlpha = premultipliedAlpha;
     }
-    return normalized === "normal" && mode !== "normal" ? "normal" : mode;
+    return reportedBlendMode(mode);
   }
   /**
    * Set the projection matrix — pushes a fresh frame-globals slot so
@@ -56980,6 +57865,11 @@ var WebGPURenderer = class extends Renderer {
     const grad = this.currentGradient;
     const hasMask = this.maskLevel > 0;
     this.currentGradient = null;
+    if (isAdvancedBlendMode(this.currentBlendMode) === true) {
+      this._warnAdvancedBlendFallback("gradient fills");
+      this._drainAdvancedBlend();
+    }
+    this._advancedBlendBusy++;
     this.currentBatcher?.flush();
     const visibleRef = this.maskVisibleRef;
     let markRef = 1;
@@ -57015,6 +57905,7 @@ var WebGPURenderer = class extends Renderer {
       this.stencilMode = "none";
     }
     this.ensurePass().setStencilReference(this.maskVisibleRef);
+    this._advancedBlendBusy--;
   }
   /**
    * Stroke an arc at the specified coordinates with given radius, start and end points
@@ -57672,6 +58563,14 @@ var WebGPURenderer = class extends Renderer {
    * @override
    */
   destroy() {
+    this._advancedBlendEffect?.destroy();
+    this._advancedBlendEffect = void 0;
+    this._advancedBlendCapture?.destroy();
+    this._advancedBlendCapture = void 0;
+    this._advancedBlendTarget?.destroy?.();
+    this._advancedBlendTarget = void 0;
+    this._advancedBlendOpen = false;
+    this._advancedBlendBusy = 0;
     releaseShadowQuads(this);
     off(GAME_RESET, this.onGameReset);
     off(CANVAS_ONRESIZE, this.onCanvasResize);
@@ -58552,6 +59451,7 @@ var defaultParticleEmitterSettings = {
   blendMode: "normal",
   onlyInViewport: true,
   floating: false,
+  referenceSpace: "local",
   maxParticles: 10,
   frequency: 100,
   duration: Infinity,
@@ -58563,6 +59463,10 @@ var defaultParticleEmitterSettings = {
 var settings_default = defaultParticleEmitterSettings;
 
 // src/particles/emitter.ts
+var _m1 = new Matrix3d();
+var _m2 = new Matrix3d();
+var _correction = new Matrix3d();
+var _rebase = new Vector2d();
 function createDefaultParticleTexture(w = 8, h = 8) {
   const defaultParticleTexture = new canvasrendertarget_default(w, h, {
     offscreenCanvas: true
@@ -58595,6 +59499,12 @@ var ParticleEmitter = class extends Container {
   _dt;
   /** @ignore */
   _defaultParticle;
+  /**
+   * The blend mode last fanned out to the particles, so a change to
+   * {@link ParticleEmitter#blendMode} can be detected per frame.
+   * @ignore
+   */
+  #appliedBlendMode = "normal";
   /**
    * whether at least one particle has been spawned by this emitter — used as
    * the precondition for completion detection (a brand-new emitter with zero
@@ -58608,6 +59518,19 @@ var ParticleEmitter = class extends Container {
    * @ignore
    */
   _deltaInv;
+  /**
+   * Maps an emitter-local spawn point into the reference frame the particles
+   * live in, so a particle is BORN where the emitter is even though its
+   * position is thereafter measured from somewhere else. `undefined` in
+   * local mode, where the two frames coincide and no mapping is needed.
+   *
+   * Held per emitter (not a module scratch) because particles read it during
+   * their own reset, after `addParticles` has computed it. One matrix per
+   * emitter that actually uses a non-local space — emitters are few, unlike
+   * particles, which allocate nothing.
+   * @ignore
+   */
+  _spawnMap;
   /**
    * @param x - x position of the particle emitter
    * @param y - y position of the particle emitter
@@ -58654,11 +59577,8 @@ var ParticleEmitter = class extends Container {
     this._deltaInv = timer_default.maxfps / 1e3;
     this.reset(settings);
   }
-  /**
-   * Reset the emitter with particle emitter settings.
-   * @param settings - object with emitter settings. See {@link ParticleEmitterSettings}
-   */
   reset(settings = {}) {
+    const previousFrame = this.#frameOf(this.settings?.referenceSpace);
     Object.assign(this.settings, settings_default, settings);
     clampMinToMax(this.settings, "minLife", "maxLife");
     clampMinToMax(this.settings, "minStartScale", "maxStartScale");
@@ -58677,8 +59597,131 @@ var ParticleEmitter = class extends Container {
       this.settings.image = this._defaultParticle.canvas;
     }
     this.floating = this.settings.floating;
+    this.blendMode = this.settings.blendMode;
+    this.#appliedBlendMode = this.settings.blendMode;
+    this.#rebase(previousFrame);
+    this.isDirty = true;
+  }
+  /**
+   * What a particle's position is measured against — see
+   * {@link ParticleEmitterSettings.referenceSpace}.
+   *
+   * Assigning this re-bases every particle already alive into the new frame,
+   * so nothing jumps: the cloud stays exactly where it is on screen and only
+   * its subsequent motion differs. Passing it through
+   * {@link ParticleEmitter#reset} does the same.
+   * @default "local"
+   * @example
+   * emitter.referenceSpace = "world";   // start leaving a trail
+   */
+  get referenceSpace() {
+    return this.settings.referenceSpace;
+  }
+  set referenceSpace(space) {
+    if (space === this.settings.referenceSpace) {
+      return;
+    }
+    const previous = this.#frameOf(this.settings.referenceSpace);
+    this.settings.referenceSpace = space;
+    this.#rebase(previous);
+  }
+  /**
+   * Map the particles already alive out of the frame they were simulating
+   * in and into the current one, so a change of reference space is
+   * invisible at the instant it happens: the cloud stays exactly where it
+   * is on screen and only its subsequent motion differs.
+   *
+   * Called from the accessor and from {@link ParticleEmitter#reset} alike —
+   * `reset()` assigns `settings` wholesale and would otherwise leave live
+   * particles holding coordinates measured against a frame that is no
+   * longer theirs, teleporting the lot.
+   * @ignore
+   * @param previous - the frame the live particles are currently in
+   */
+  #rebase(previous) {
+    const next = this.#frameOf(this.settings.referenceSpace);
+    if (previous !== next) {
+      _m1.identity();
+      _m1.multiply(this.#worldFrame(next, _m2).invert());
+      _m1.multiply(this.#worldFrame(previous, _m2));
+      for (const particle of this.getChildren()) {
+        _rebase.set(particle.pos.x, particle.pos.y);
+        _m1.apply(_rebase);
+        particle.pos.x = _rebase.x;
+        particle.pos.y = _rebase.y;
+      }
+    }
+    this._spawnMap = void 0;
     this.isDirty = true;
   }
+  /**
+   * Resolve a reference-space value to the container whose frame the
+   * particles live in. Returns `this` whenever the answer is "the emitter
+   * itself" — including the degenerate cases (`"world"` on an emitter with no
+   * parent, or a custom target that IS the emitter), which then take the
+   * local fast path with no correction at all.
+   * @ignore
+   */
+  #frameOf(space) {
+    if (space === "local") {
+      return this;
+    }
+    if (space === "world") {
+      return this.ancestor ?? this;
+    }
+    if (!space || typeof space.pos === "undefined") {
+      return this;
+    }
+    return space;
+  }
+  /**
+   * The world transform of a reference frame — i.e. of the space that
+   * container's children are drawn in.
+   * @ignore
+   */
+  #worldFrame(frame, out) {
+    return frame.getWorldTransform(out);
+  }
+  /**
+   * The transform to insert before walking the children so they are drawn in
+   * the reference frame instead of the emitter's own.
+   *
+   * At the insertion point the renderer holds `W_ancestor · preContrib`, and
+   * `Container.draw` appends `T(pos)` afterwards, so what we need is
+   *
+   * ```
+   * K = inv(preContrib) · inv(W_ancestor) · W_target · T(−pos)
+   * ```
+   *
+   * expressed below via `inv(preContrib) = T(pos) · inv(L)`. Note this is
+   * NOT `inv(W_emitter) · W_target` — matrices do not commute, and that form
+   * only coincides with this one when both chains share the same linear
+   * part, which hides the difference until something upstream is rotated.
+   *
+   * When the target is the emitter's own parent — the `"world"` case — the
+   * whole ancestor chain cancels and no walk happens at all.
+   * @ignore
+   * @returns the correction, or `undefined` in local mode
+   */
+  #correctionMatrix() {
+    const target = this.#frameOf(this.settings.referenceSpace);
+    if (target === this) {
+      return void 0;
+    }
+    _correction.identity();
+    _correction.translate(this.pos.x, this.pos.y);
+    _correction.multiply(this.getLocalTransform(_m1).invert());
+    if (target !== this.ancestor) {
+      if (this.ancestor) {
+        _correction.multiply(
+          this.ancestor.getWorldTransform(_m1).invert()
+        );
+      }
+      _correction.multiply(target.getWorldTransform(_m2));
+    }
+    _correction.translate(-this.pos.x, -this.pos.y);
+    return _correction;
+  }
   /**
    * returns a random point on the x axis within the bounds of this emitter
    * @returns a random x position within the emitter bounds
@@ -58693,10 +59736,39 @@ var ParticleEmitter = class extends Container {
   getRandomPointY() {
     return randomFloat(0, this.getBounds().height);
   }
+  /**
+   * Draw the particles in their reference frame rather than the emitter's.
+   *
+   * The correction goes in before `super.draw()` because that is where the
+   * child walk happens; translations and the correction compose, and in
+   * local mode there is no correction and this is the inherited path
+   * untouched.
+   * @ignore
+   */
+  draw(renderer, viewport) {
+    const correction = this.#correctionMatrix();
+    if (correction !== void 0) {
+      renderer.transform(correction);
+    }
+    super.draw(renderer, viewport);
+  }
   // Add count particles in the game world
   /** @ignore */
   addParticles(count) {
     const z = this.depth;
+    const target = this.#frameOf(this.settings.referenceSpace);
+    if (target === this) {
+      this._spawnMap = void 0;
+    } else {
+      const map = this._spawnMap ?? (this._spawnMap = new Matrix3d());
+      if (target === this.ancestor) {
+        map.copy(this.getLocalTransform(_m1));
+      } else {
+        map.identity();
+        map.multiply(target.getWorldTransform(_m1).invert());
+        map.multiply(this.getWorldTransform(_m2));
+      }
+    }
     for (let i = 0; i < count; i++) {
       this.addChild(particlePool.get(this), z);
     }
@@ -58744,6 +59816,14 @@ var ParticleEmitter = class extends Container {
    * @ignore
    */
   update(dt) {
+    if (this.blendMode !== this.#appliedBlendMode) {
+      this.#appliedBlendMode = this.blendMode;
+      this.settings.blendMode = this.blendMode;
+      for (const particle of this.children ?? []) {
+        particle.blendMode = this.blendMode;
+      }
+      this.isDirty = true;
+    }
     if (this.settings.framesToSkip > 0) {
       if (++this._updateCount > this.settings.framesToSkip) {
         this._updateCount = 0;
@@ -58757,6 +59837,9 @@ var ParticleEmitter = class extends Container {
     }
     const childrenDirty = super.update(dt);
     this.isDirty = this.isDirty || childrenDirty;
+    if (this.#frameOf(this.settings.referenceSpace) !== this && this.getChildren().length > 0) {
+      this.inViewport = true;
+    }
     if (this._enabled && this._stream) {
       if (this._durationTimer !== Infinity) {
         this._durationTimer -= dt;
@@ -58800,6 +59883,8 @@ var ParticleEmitter = class extends Container {
       this._defaultParticle = void 0;
     }
     this.settings.image = void 0;
+    this.settings.referenceSpace = "local";
+    this._spawnMap = void 0;
   }
 };
 
@@ -60383,7 +61468,7 @@ var UITextButton = class extends UIBaseElement {
 };
 
 // src/video/effects/blur.js
-var wgslFragment2 = `
+var wgslFragment3 = `
 struct BlurUniforms {
 	uBlurStrength : f32,
 	uTextureSize : vec2f,
@@ -60434,7 +61519,7 @@ var BlurEffect = class extends ShaderEffect {
 				return (sum / 9.0) * vColor;
 			}
 			`,
-      wgsl: wgslFragment2
+      wgsl: wgslFragment3
     });
     this.strength = options.strength ?? 1;
     const texSize = options.textureSize ?? [256, 256];
@@ -60460,7 +61545,7 @@ var BlurEffect = class extends ShaderEffect {
 };
 
 // src/video/effects/chromaticAberration.js
-var wgslFragment3 = `
+var wgslFragment4 = `
 struct AberrationUniforms {
 	uOffset : f32,
 	uTextureSize : vec2f,
@@ -60497,7 +61582,7 @@ var ChromaticAberrationEffect = class extends ShaderEffect {
 				return vec4(r, g, b, a) * vColor;
 			}
 			`,
-      wgsl: wgslFragment3
+      wgsl: wgslFragment4
     });
     this.offset = options.offset ?? 3;
     const texSize = options.textureSize ?? [256, 256];
@@ -60545,7 +61630,7 @@ var DesaturateEffect = class extends ColorMatrixEffect {
 };
 
 // src/video/effects/dissolve.js
-var wgslFragment4 = `
+var wgslFragment5 = `
 struct DissolveUniforms {
 	uDissolveProgress : f32,
 	uEdgeColor : vec3f,
@@ -60657,7 +61742,7 @@ var DissolveEffect = class extends ShaderEffect {
 				return color;
 			}
 			`,
-      wgsl: wgslFragment4
+      wgsl: wgslFragment5
     });
     this.progress = options.progress ?? 0;
     this.setUniform("uDissolveProgress", this.progress);
@@ -60685,7 +61770,7 @@ var DissolveEffect = class extends ShaderEffect {
 };
 
 // src/video/effects/dropShadow.js
-var wgslFragment5 = `
+var wgslFragment6 = `
 struct ShadowUniforms {
 	uShadowOffset : vec2f,
 	uShadowColor : vec3f,
@@ -60749,7 +61834,7 @@ var DropShadowEffect = class extends ShaderEffect {
 				return color;
 			}
 			`,
-      wgsl: wgslFragment5
+      wgsl: wgslFragment6
     });
     const texSize = options.textureSize ?? [256, 256];
     this.setUniform(
@@ -60783,7 +61868,7 @@ var DropShadowEffect = class extends ShaderEffect {
 };
 
 // src/video/effects/flash.js
-var wgslFragment6 = `
+var wgslFragment7 = `
 struct FlashUniforms {
 	uFlashColor : vec3f,
 	uFlashIntensity : f32,
@@ -60810,7 +61895,7 @@ var FlashEffect = class extends ShaderEffect {
 				return vec4(mix(color.rgb, uFlashColor * color.a, uFlashIntensity), color.a);
 			}
 			`,
-      wgsl: wgslFragment6
+      wgsl: wgslFragment7
     });
     const color = options.color ?? [1, 1, 1];
     this.intensity = options.intensity ?? 0;
@@ -60835,7 +61920,7 @@ var FlashEffect = class extends ShaderEffect {
 };
 
 // src/video/effects/glow.js
-var wgslFragment7 = `
+var wgslFragment8 = `
 struct GlowUniforms {
 	uGlowColor : vec3f,
 	uGlowWidth : f32,
@@ -60896,7 +61981,7 @@ var GlowEffect = class extends ShaderEffect {
 				return color;
 			}
 			`,
-      wgsl: wgslFragment7
+      wgsl: wgslFragment8
     });
     const color = options.color ?? [1, 1, 1];
     const width = options.width ?? 3;
@@ -60933,7 +62018,7 @@ var GlowEffect = class extends ShaderEffect {
 };
 
 // src/video/effects/hologram.js
-var wgslFragment8 = `
+var wgslFragment9 = `
 struct HologramUniforms {
 	uHoloColor : vec3f,
 	uHoloIntensity : f32,
@@ -60976,7 +62061,7 @@ var HologramEffect = class extends ShaderEffect {
 				return vec4(holo, color.a * flicker);
 			}
 			`,
-      wgsl: wgslFragment8
+      wgsl: wgslFragment9
     });
     const color = options.color ?? [0.1, 0.7, 1];
     this.setUniform("uHoloColor", new Float32Array(color));
@@ -61015,7 +62100,7 @@ var InvertEffect = class extends ColorMatrixEffect {
 };
 
 // src/video/effects/outline.js
-var wgslFragment9 = `
+var wgslFragment10 = `
 struct OutlineUniforms {
 	uOutlineColor : vec3f,
 	uOutlineWidth : f32,
@@ -61079,7 +62164,7 @@ var OutlineEffect = class extends ShaderEffect {
 				return color;
 			}
 			`,
-      wgsl: wgslFragment9
+      wgsl: wgslFragment10
     });
     const color = options.color ?? [1, 1, 1];
     const width = options.width ?? 1;
@@ -61113,7 +62198,7 @@ var OutlineEffect = class extends ShaderEffect {
 };
 
 // src/video/effects/pixelate.js
-var wgslFragment10 = `
+var wgslFragment11 = `
 struct PixelateUniforms {
 	uPixelSize : f32,
 	uTextureSize : vec2f,
@@ -61144,7 +62229,7 @@ var PixelateEffect = class extends ShaderEffect {
 				return texture2D(uSampler, snapped) * vColor;
 			}
 			`,
-      wgsl: wgslFragment10
+      wgsl: wgslFragment11
     });
     this.size = options.size ?? 4;
     const texSize = options.textureSize ?? [256, 256];
@@ -61170,7 +62255,7 @@ var PixelateEffect = class extends ShaderEffect {
 };
 
 // src/video/effects/scanline.js
-var wgslFragment11 = `
+var wgslFragment12 = `
 struct ScanlineUniforms {
 	uScanlineOpacity : f32,
 	uCurvature : f32,
@@ -61249,7 +62334,7 @@ var ScanlineEffect = class extends ShaderEffect {
 				return color;
 			}
 			`,
-      wgsl: wgslFragment11
+      wgsl: wgslFragment12
     });
     this.setUniform("uScanlineOpacity", options.opacity ?? 0.25);
     this.setUniform("uCurvature", options.curvature ?? 0);
@@ -61301,7 +62386,7 @@ var SepiaEffect = class extends ColorMatrixEffect {
 };
 
 // src/video/effects/shine.js
-var wgslFragment12 = `
+var wgslFragment13 = `
 struct ShineUniforms {
 	uShineColor : vec3f,
 	uShineWidth : f32,
@@ -61397,7 +62482,7 @@ var ShineEffect = class extends ShaderEffect {
 				return vec4(result, color.a);
 			}
 			`,
-      wgsl: wgslFragment12
+      wgsl: wgslFragment13
     });
     this.setUniform(
       "uShineColor",
@@ -61444,7 +62529,7 @@ var ShineEffect = class extends ShaderEffect {
 };
 
 // src/video/effects/tintPulse.js
-var wgslFragment13 = `
+var wgslFragment14 = `
 struct TintPulseUniforms {
 	uPulseColor : vec3f,
 	uPulseSpeed : f32,
@@ -61478,7 +62563,7 @@ var TintPulseEffect = class extends ShaderEffect {
 				return vec4(mix(color.rgb, uPulseColor * color.a, pulse), color.a);
 			}
 			`,
-      wgsl: wgslFragment13
+      wgsl: wgslFragment14
     });
     const color = options.color ?? [1, 0, 0];
     this.setUniform("uPulseColor", new Float32Array(color));
@@ -61512,7 +62597,7 @@ var fragment = `
 				return vec4(color.rgb * v, color.a);
 			}
 			`;
-var wgslFragment14 = `
+var wgslFragment15 = `
 struct VignetteUniforms {
 	uStrength : f32,
 	uSize : f32,
@@ -61533,7 +62618,7 @@ var VignetteEffect = class extends ShaderEffect {
    * @param {number} [options.size=25.0] - vignette spread multiplier (higher = smaller dark area)
    */
   constructor(renderer, options = {}) {
-    super(renderer, { glsl: fragment, wgsl: wgslFragment14 });
+    super(renderer, { glsl: fragment, wgsl: wgslFragment15 });
     this.strength = options.strength ?? 0.15;
     this.size = options.size ?? 25;
     this.setUniform("uStrength", this.strength);
@@ -61558,7 +62643,7 @@ var VignetteEffect = class extends ShaderEffect {
 };
 
 // src/video/effects/wave.js
-var wgslFragment15 = `
+var wgslFragment16 = `
 struct WaveUniforms {
 	uAmplitude : f32,
 	uFrequency : f32,
@@ -61594,7 +62679,7 @@ var WaveEffect = class extends ShaderEffect {
 				return texture2D(uSampler, distorted) * vColor;
 			}
 			`,
-      wgsl: wgslFragment15
+      wgsl: wgslFragment16
     });
     this.setUniform("uAmplitude", options.amplitude ?? 0.01);
     this.setUniform("uFrequency", options.frequency ?? 10);