melonjs 19.2.0 → 19.3.0

package/build/index.js

@@ -1,5 +1,5 @@
 /*!
- * melonJS Game Engine - 19.2.0
+ * melonJS Game Engine - 19.3.0
  * http://www.melonjs.org
  * melonjs is licensed under the MIT License.
  * http://www.opensource.org/licenses/mit-license
@@ -750,8 +750,8 @@ var require_weak_map_basic_detection = __commonJS({
     "use strict";
     var globalThis2 = require_global_this();
     var isCallable = require_is_callable();
-    var WeakMap = globalThis2.WeakMap;
-    module.exports = isCallable(WeakMap) && /native code/.test(String(WeakMap));
+    var WeakMap2 = globalThis2.WeakMap;
+    module.exports = isCallable(WeakMap2) && /native code/.test(String(WeakMap2));
   }
 });
 
@@ -790,7 +790,7 @@ var require_internal_state = __commonJS({
     var hiddenKeys = require_hidden_keys();
     var OBJECT_ALREADY_INITIALIZED = "Object already initialized";
     var TypeError2 = globalThis2.TypeError;
-    var WeakMap = globalThis2.WeakMap;
+    var WeakMap2 = globalThis2.WeakMap;
     var set;
     var get2;
     var has2;
@@ -807,7 +807,7 @@ var require_internal_state = __commonJS({
       };
     };
     if (NATIVE_WEAK_MAP || shared.state) {
-      store = shared.state || (shared.state = new WeakMap());
+      store = shared.state || (shared.state = new WeakMap2());
       store.get = store.get;
       store.has = store.has;
       store.set = store.set;
@@ -4639,6 +4639,7 @@ var pointPool = createPool((x, y) => {
 });
 
 // src/physics/bounds.ts
+var _addFrameScratch = new Point();
 var Bounds = class _Bounds {
   _center;
   type;
@@ -4865,20 +4866,41 @@ var Bounds = class _Bounds {
     this.max.y = Math.max(this.max.y, p.y);
   }
   /**
-   * Adds the given quad coordinates to this bounds definition, multiplied by the given matrix.
+   * Expands this bounds to include the axis-aligned bounding box of
+   * the given rect's four corners, optionally transformed through `m`
+   * first. With a non-identity `m` (rotation, scale, etc.) the result
+   * is the AABB of the transformed quad, not a transformed AABB.
    * @param x0 - The left x coordinate of the quad.
    * @param y0 - The top y coordinate of the quad.
    * @param x1 - The right x coordinate of the quad.
    * @param y1 - The bottom y coordinate of the quad.
-   * @param [m] - An optional transform to apply to the given coordinates.
+   * @param [m] - An optional transform applied to each corner before inclusion.
    */
   addFrame(x0, y0, x1, y1, m) {
-    const v = pointPool.get();
+    if (m === void 0 || m.isIdentity()) {
+      const minX = Math.min(x0, x1);
+      const maxX = Math.max(x0, x1);
+      const minY = Math.min(y0, y1);
+      const maxY = Math.max(y0, y1);
+      if (minX < this.min.x) {
+        this.min.x = minX;
+      }
+      if (maxX > this.max.x) {
+        this.max.x = maxX;
+      }
+      if (minY < this.min.y) {
+        this.min.y = minY;
+      }
+      if (maxY > this.max.y) {
+        this.max.y = maxY;
+      }
+      return;
+    }
+    const v = _addFrameScratch;
     this.addPoint(v.set(x0, y0), m);
     this.addPoint(v.set(x1, y0), m);
     this.addPoint(v.set(x0, y1), m);
     this.addPoint(v.set(x1, y1), m);
-    pointPool.release(v);
   }
   contains(xOrVectorOrBounds, y) {
     let _x1;
@@ -14138,10 +14160,10 @@ var Container = class _Container extends Renderable {
   draw(renderer2, viewport) {
     const bounds = this.getBounds();
     this.drawCount = 0;
-    if (this.root === false && this.clipping === true && bounds.isFinite() === true) {
-      renderer2.clipRect(bounds.left, bounds.top, bounds.width, bounds.height);
-    }
     renderer2.translate(this.pos.x, this.pos.y);
+    if (this.root === false && this.clipping === true && bounds.isFinite() === true && Number.isFinite(this.width) === true && Number.isFinite(this.height) === true) {
+      renderer2.clipRect(0, 0, this.width, this.height);
+    }
     if (this.backgroundColor.alpha > 1 / 255) {
       renderer2.clearColor(this.backgroundColor);
     }
@@ -15366,6 +15388,32 @@ var RenderState = class {
     }
     this._stackDepth = depth + 1;
   }
+  /**
+   * Inspect the scissor box that the next `restore()` would install,
+   * without mutating any state. Lets renderers detect whether a
+   * pending `restore()` will actually change the scissor (and
+   * decide, e.g., whether to flush GPU work first).
+   *
+   * Returns:
+   * - `Int32Array` (length 4) — `[x, y, width, height]` of the
+   *   saved scissor when scissor was active at the matching `save()`
+   *   call.
+   * - `null` — when the saved state had scissor disabled, or the
+   *   stack is empty. Treat this as "next scissor will be inactive".
+   *
+   * The returned array is a **live reference into the internal
+   * stack** — zero allocation on a hot path. Callers MUST treat it
+   * as read-only; mutating it corrupts subsequent `restore()` calls.
+   * @ignore
+   * @returns {Int32Array | null}
+   */
+  peekScissor() {
+    const depth = this._stackDepth - 1;
+    if (depth < 0 || !this._scissorActive[depth]) {
+      return null;
+    }
+    return this._scissorStack[depth];
+  }
   /**
    * Restore state from the stack.
    * Color, tint, transform, and scissor are restored in place.
@@ -15466,6 +15514,8 @@ var Renderer = class {
     this.maskLevel = 0;
     this.projectionMatrix = new Matrix3d();
     this.uvOffset = 0;
+    this.currentNormalMap = null;
+    this.activeLightCount = 0;
   }
   /**
    * @type {string}
@@ -15686,6 +15736,62 @@ var Renderer = class {
   setBlendMode(mode = "normal") {
     this.currentBlendMode = mode;
   }
+  /**
+   * Upload the active scene lights to the lit sprite pipeline.
+   *
+   * Called once per camera per frame by `Camera2d.draw()` (after the
+   * FBO is bound, before the world tree walk fires `Sprite.draw` for
+   * any normal-mapped sprite). The WebGL renderer overrides this to
+   * pack the lights into the lit shader's uniform buffers; the Canvas
+   * renderer cannot do per-pixel normal-map lighting and silently
+   * ignores the call. The first time a non-empty light list is passed
+   * in Canvas mode, a one-shot console warning is emitted.
+   *
+   * Stage stays renderer-agnostic by passing the raw scene data —
+   * lights iterable and ambient color — and letting the renderer
+   * decide how to encode them.
+   * @param {Iterable<object>} [lights] - active `Light2d` instances; falsy/empty no-ops
+   * @param {object} [ambient] - ambient lighting color (0..255 RGB)
+   * @param {number} [translateX=0] - world-to-screen X translate (matches `Camera2d.draw()`)
+   * @param {number} [translateY=0] - world-to-screen Y translate
+   */
+  // eslint-disable-next-line no-unused-vars, @typescript-eslint/no-unused-vars
+  setLightUniforms(lights, ambient, translateX, translateY) {
+    if (this._litPipelineWarned || !lights) {
+      return;
+    }
+    const hasAny = typeof lights.size === "number" && lights.size > 0 || typeof lights.length === "number" && lights.length > 0 || typeof lights[Symbol.iterator] === "function" && !lights[Symbol.iterator]().next().done;
+    if (hasAny) {
+      this._litPipelineWarned = true;
+      console.warn(
+        "melonJS: Light2d normal-map lighting requires the WebGL renderer; the Canvas fallback renders sprites without per-pixel lighting. Switch to `video.WEBGL` or `video.AUTO` to enable the lit pipeline."
+      );
+    }
+  }
+  /**
+   * Render a `Light2d` instance.
+   *
+   * Each renderer implements its own strategy: the WebGL renderer
+   * draws lights as quads through a shared procedural radial-falloff
+   * fragment shader (no per-light texture, color and intensity
+   * encoded in the per-vertex tint so consecutive draws batch); the
+   * Canvas renderer caches a small `Gradient` config object per
+   * light in a `WeakMap` (rebuilt only when the light's radii /
+   * color / intensity change), rasterizes it with `Gradient.toCanvas()`
+   * into a single shared `CanvasRenderTarget`, and composites the
+   * result via `drawImage`. The base implementation is a no-op so
+   * renderers without a lighting path can be polymorphically
+   * substituted.
+   *
+   * Light2d itself is renderer-agnostic — it just calls
+   * `renderer.drawLight(this)` and relies on the renderer to pick
+   * the right machinery.
+   * @param {object} light - the Light2d instance to render
+   * @see Light2d
+   */
+  // eslint-disable-next-line no-unused-vars, @typescript-eslint/no-unused-vars
+  drawLight(light) {
+  }
   /**
    * Set the current fill & stroke style color.
    * By default, or upon reset, the value is set to #000000.
@@ -16206,7 +16312,7 @@ var TextureAtlas = class {
   /**
    * @param {object|object[]} atlases - atlas information. See {@link loader.getJSON}
    * @param {HTMLImageElement|HTMLCanvasElement|OffscreenCanvas|CompressedImage|string|OffscreenCanvas[]|HTMLImageElement[]|HTMLCanvasElement[]|string[]} [src=atlas.meta.image] - Image source
-   * @param {boolean} [cache=false] - Use true to skip caching this Texture
+   * @param {boolean|object} [options] - either a boolean (legacy `cache` flag — `false` disables `TextureCache` registration; default behavior is to cache) or an options object `{ cache?: boolean, normalMap?: HTMLImageElement|HTMLCanvasElement|OffscreenCanvas|ImageBitmap|string }`. When `normalMap` is provided, the atlas exposes a paired normal-map texture sharing the same UVs as the color texture (used by the WebGL renderer's lit pipeline). `HTMLVideoElement` is intentionally not supported as a normal map (would freeze on frame 0 due to per-image GL texture caching).
    * @example
    * // create a texture atlas from a JSON Object
    * game.texture = new me.TextureAtlas(
@@ -16228,10 +16334,22 @@ var TextureAtlas = class {
    *         anchorPoint : new me.Vector2d(0.5, 0.5)
    *     },
    *     me.loader.getImage("spritesheet")
+   * );
+   *
+   * // SpriteIlluminator workflow: pair the color atlas with its normal map
+   * game.texture = new me.TextureAtlas(
+   *     me.loader.getJSON("scene"),
+   *     me.loader.getImage("scene"),
+   *     { normalMap: me.loader.getImage("scene_n") }
+   * );
    */
-  constructor(atlases, src, cache2) {
+  constructor(atlases, src, options) {
+    const opts = typeof options === "boolean" ? { cache: options } : options || {};
+    const cache2 = opts.cache;
+    const normalMap = opts.normalMap;
     this.format = null;
     this.sources = /* @__PURE__ */ new Map();
+    this.normalSources = /* @__PURE__ */ new Map();
     this.atlases = /* @__PURE__ */ new Map();
     this.activeAtlas = void 0;
     this._uvCache = { sx: -1, sy: -1, sw: -1, sh: -1, uvs: null };
@@ -16321,6 +16439,31 @@ var TextureAtlas = class {
         game.renderer.cache.set(source, this);
       });
     }
+    if (typeof normalMap !== "undefined" && normalMap !== null) {
+      let resolved;
+      if (typeof normalMap === "string") {
+        resolved = getImage(normalMap);
+        if (!resolved) {
+          throw new Error(
+            "TextureAtlas: normal map image '" + normalMap + "' not found"
+          );
+        }
+      } else if (typeof normalMap === "object" && typeof normalMap.width === "number" && typeof normalMap.height === "number") {
+        if (typeof normalMap.videoWidth === "number") {
+          throw new TypeError(
+            "TextureAtlas: options.normalMap does not support HTMLVideoElement (the lit pipeline caches the texture per image reference and would freeze on frame 0)"
+          );
+        }
+        resolved = normalMap;
+      } else {
+        throw new TypeError(
+          "TextureAtlas: options.normalMap must be an image-like, a loader key string, or null/undefined; got " + typeof normalMap
+        );
+      }
+      this.sources.forEach((_source, key) => {
+        this.normalSources.set(key, resolved);
+      });
+    }
   }
   /**
    * return the default or specified atlas dictionnary
@@ -16353,6 +16496,22 @@ var TextureAtlas = class {
       return this.sources.get(this.activeAtlas);
     }
   }
+  /**
+   * Return the paired normal-map texture for the given region, or `null`
+   * if no normal map was provided to this atlas. The normal map shares
+   * the same UV layout as the color texture returned by {@link TextureAtlas#getTexture}.
+   * @param {object} [region] - region name in case of multipack textures
+   * @returns {HTMLImageElement|HTMLCanvasElement|OffscreenCanvas|ImageBitmap|null}
+   */
+  getNormalTexture(region) {
+    if (this.normalSources.size === 0) {
+      return null;
+    }
+    if (typeof region === "object" && typeof region.texture === "string") {
+      return this.normalSources.get(region.texture) ?? null;
+    }
+    return this.normalSources.get(this.activeAtlas) ?? null;
+  }
   /**
    * add a region to the atlas
    * @param {string} name - region mame
@@ -16851,6 +17010,7 @@ var CanvasRenderer = class extends Renderer {
   reset() {
     super.reset();
     this.clearColor(this.currentColor, this.settings.transparent !== true);
+    this._lightCache = void 0;
   }
   /**
    * Reset the canvas transform to identity
@@ -17044,6 +17204,59 @@ var CanvasRenderer = class extends Renderer {
     }
     context.drawImage(source, sx, sy, sw, sh, dx, dy, dw, dh);
   }
+  /**
+   * @inheritdoc
+   *
+   * Renders the light by drawing a cached radial `Gradient` via
+   * `Gradient.toCanvas()`. The Gradient instance is cached per-Light2d
+   * in a `WeakMap` and rebuilt only when the light's radii / color /
+   * intensity change. `toCanvas` itself shares a single
+   * `CanvasRenderTarget` across all gradients in the engine, so memory
+   * stays at O(1) regardless of how many lights are active.
+   *
+   * The cached Gradient is always circular (outer radius =
+   * `max(radiusX, radiusY)`) — `drawImage`'s non-uniform stretch
+   * produces the elliptical falloff for non-square lights, matching
+   * the procedural shader's behavior on WebGL.
+   * @param {object} light - the Light2d instance to render
+   */
+  drawLight(light) {
+    if (this._lightCache === void 0) {
+      this._lightCache = /* @__PURE__ */ new WeakMap();
+    }
+    let entry = this._lightCache.get(light);
+    const c = light.color;
+    if (entry === void 0 || entry.radiusX !== light.radiusX || entry.radiusY !== light.radiusY || entry.r !== c.r || entry.g !== c.g || entry.b !== c.b || entry.intensity !== light.intensity) {
+      const r = Math.max(light.radiusX, light.radiusY);
+      const gradient = this.createRadialGradient(r, r, 0, r, r, r);
+      gradient.addColorStop(0, c.toRGBA(light.intensity));
+      gradient.addColorStop(1, c.toRGBA(0));
+      entry = {
+        gradient,
+        radius: r,
+        radiusX: light.radiusX,
+        radiusY: light.radiusY,
+        r: c.r,
+        g: c.g,
+        b: c.b,
+        intensity: light.intensity
+      };
+      this._lightCache.set(light, entry);
+    }
+    const r2 = entry.radius * 2;
+    const canvas = entry.gradient.toCanvas(this, 0, 0, r2, r2);
+    this.drawImage(
+      canvas,
+      0,
+      0,
+      r2,
+      r2,
+      light.pos.x,
+      light.pos.y,
+      light.width,
+      light.height
+    );
+  }
   /**
    * Draw a pattern within the given rectangle.
    * @param {CanvasPattern} pattern - Pattern object
@@ -17778,14 +17991,15 @@ var CanvasRenderer = class extends Renderer {
       if (typeof mask !== "undefined") {
         context.beginPath();
       }
+      this._maskInvertOuterAdded = false;
     }
     if (typeof mask !== "undefined") {
       switch (mask.type) {
         // RoundRect
         case "RoundRect":
           context.roundRect(
-            mask.top,
             mask.left,
+            mask.top,
             mask.width,
             mask.height,
             mask.radius
@@ -17794,7 +18008,7 @@ var CanvasRenderer = class extends Renderer {
         // Rect or Bounds
         case "Rectangle":
         case "Bounds":
-          context.rect(mask.top, mask.left, mask.width, mask.height);
+          context.rect(mask.left, mask.top, mask.width, mask.height);
           break;
         // Polygon or Line
         case "Polygon":
@@ -17837,7 +18051,10 @@ var CanvasRenderer = class extends Renderer {
     }
     this.maskLevel++;
     if (invert === true) {
-      context.rect(0, 0, this.getCanvas().width, this.getCanvas().height);
+      if (this._maskInvertOuterAdded !== true) {
+        context.rect(0, 0, this.getCanvas().width, this.getCanvas().height);
+        this._maskInvertOuterAdded = true;
+      }
       context.clip("evenodd");
     } else {
       context.clip();
@@ -21354,6 +21571,7 @@ var Sprite = class extends Renderable {
    * @param {number} [settings.flipX] - flip the sprite on the horizontal axis
    * @param {number} [settings.flipY] - flip the sprite on the vertical axis
    * @param {Vector2d} [settings.anchorPoint={x:0.5, y:0.5}] - Anchor point to draw the frame at (defaults to the center of the frame).
+   * @param {HTMLImageElement|HTMLCanvasElement|OffscreenCanvas|ImageBitmap|string} [settings.normalMap] - optional normal-map texture used for per-pixel lighting (SpriteIlluminator-style). Same layout/UVs as `settings.image`. When omitted (default), the sprite renders unlit and pays no extra cost. Ignored by the Canvas renderer. Note: `HTMLVideoElement` is intentionally not supported — normal maps encode static surface directions in RGB, and the engine caches the GL texture per image reference (a video would freeze on frame 0).
    * @example
    * // create a single sprite from a standalone image, with anchor in the center
    * let sprite = new me.Sprite(0, 0, {
@@ -21390,6 +21608,7 @@ var Sprite = class extends Renderable {
     this.offset = vector2dPool.get(0, 0);
     this.isVideo = false;
     this.source = null;
+    this._normalMap = null;
     this.anim = {};
     this.resetAnim = void 0;
     this.current = {
@@ -21463,6 +21682,25 @@ var Sprite = class extends Renderable {
         this.textureAtlas = this.source.getAtlas();
       }
     }
+    if (settings.image instanceof TextureAtlas && typeof settings.image.getNormalTexture === "function") {
+      const fromAtlas = settings.image.getNormalTexture();
+      if (fromAtlas) {
+        this.normalMap = fromAtlas;
+      }
+    }
+    if (this.normalMap === null && typeof settings.normalMap !== "undefined" && settings.normalMap !== null) {
+      if (typeof settings.normalMap === "string") {
+        const resolved = getImage(settings.normalMap);
+        if (!resolved) {
+          throw new Error(
+            "me.Sprite: '" + settings.normalMap + "' normal map image not found!"
+          );
+        }
+        this.normalMap = resolved;
+      } else {
+        this.normalMap = settings.normalMap;
+      }
+    }
     if (typeof settings.atlas !== "undefined") {
       this.textureAtlas = settings.atlas;
       this.atlasIndices = settings.atlasIndices;
@@ -21505,6 +21743,37 @@ var Sprite = class extends Renderable {
       this.setCurrentAnimation("default");
     }
   }
+  /**
+   * The optional normal-map image paired with this sprite's color
+   * texture (SpriteIlluminator workflow). When set, the WebGL
+   * renderer's lit pipeline samples this texture for per-pixel
+   * lighting using `Stage._activeLights`. `null` when unlit.
+   * Setting any non-image value (or anything without numeric
+   * `width`/`height`) throws — assign `null` to clear.
+   *
+   * Silently ignored by the Canvas renderer.
+   * @type {HTMLImageElement|HTMLCanvasElement|OffscreenCanvas|ImageBitmap|null}
+   */
+  get normalMap() {
+    return this._normalMap;
+  }
+  set normalMap(value) {
+    if (value === null || value === void 0) {
+      this._normalMap = null;
+      return;
+    }
+    if (typeof value !== "object" || typeof value.width !== "number" || typeof value.height !== "number") {
+      throw new TypeError(
+        "Sprite.normalMap must be null or an image-like object with numeric width/height (HTMLImageElement, HTMLCanvasElement, OffscreenCanvas, ImageBitmap)"
+      );
+    }
+    if (typeof value.videoWidth === "number") {
+      throw new TypeError(
+        "Sprite.normalMap does not support HTMLVideoElement (the lit pipeline caches the texture per image reference and would freeze on frame 0)"
+      );
+    }
+    this._normalMap = value;
+  }
   /**
    * return the flickering state of the object
    * @returns {boolean}
@@ -21854,9 +22123,32 @@ var Sprite = class extends Renderable {
     }
     return super.update(dt);
   }
+  /**
+   * Prepare the rendering context before drawing this sprite (automatically called by melonJS).
+   * Extends `Renderable.preDraw` to publish this sprite's `normalMap` (if any)
+   * on the renderer so the WebGL lit pipeline can pair it with the next
+   * `drawImage` call. Cleared back in `postDraw`.
+   * @param {Renderer} renderer - a renderer instance
+   */
+  preDraw(renderer2) {
+    super.preDraw(renderer2);
+    if (this._normalMap !== null) {
+      renderer2.currentNormalMap = this._normalMap;
+    }
+  }
+  /**
+   * restore the rendering context after drawing this sprite (automatically called by melonJS).
+   * @param {Renderer} renderer - a renderer instance
+   */
+  postDraw(renderer2) {
+    if (this._normalMap !== null) {
+      renderer2.currentNormalMap = null;
+    }
+    super.postDraw(renderer2);
+  }
   /**
    * draw this sprite (automatically called by melonJS)
-   * @param {CanvasRenderer|WebGLRenderer} renderer - a renderer instance
+   * @param {Renderer} renderer - a renderer instance
    * @param {Camera2d} [viewport] - the viewport to (re)draw
    */
   draw(renderer2) {
@@ -21915,6 +22207,7 @@ var Sprite = class extends Renderable {
       this.image.currentTime = 0;
     }
     this.image = void 0;
+    this._normalMap = null;
     super.destroy();
   }
 };
@@ -22343,8 +22636,6 @@ var GLShader = class {
           stride,
           element.offset
         );
-      } else {
-        gl.disableVertexAttribArray(index);
       }
     }
   }
@@ -23308,6 +23599,13 @@ var Camera2d = class extends Renderable {
     } else {
       renderer2.setProjection(this.projectionMatrix);
     }
+    const stage = state_default.current();
+    renderer2.setLightUniforms(
+      stage?._activeLights,
+      stage?.ambientLightingColor,
+      translateX,
+      translateY
+    );
     container.preDraw(r);
     if (isNonDefault) {
       const view = this.worldView;
@@ -23324,6 +23622,9 @@ var Camera2d = class extends Renderable {
     this.drawFX(renderer2);
     container.postDraw(r);
     this.postDraw(r);
+    if (stage) {
+      stage.drawLighting(renderer2, this, translateX, translateY);
+    }
     r.endPostEffect(this);
     if (this._colorMatrixEffect) {
       const idx = this.postEffects.indexOf(this._colorMatrixEffect);
@@ -23361,28 +23662,50 @@ var Stage = class {
   cameras;
   /**
    * The list of active lights in this stage.
-   * (Note: Canvas Rendering mode will only properly support one light per stage)
+   *
+   * Since 19.3.0, `Light2d` is a first-class world Renderable — the
+   * recommended pattern is to add lights directly to `app.world` (or any
+   * container, including a sprite, so the light follows it via parent
+   * transforms). The `lights` Map remains for backward compatibility:
+   * any entry added via `this.lights.set(name, light)` in
+   * `onResetEvent()` is automatically adopted into the world tree at
+   * stage reset time so it renders normally.
    * @see Light2d
    * @see Stage.ambientLight
    * @example
-   * // create a white spot light
-   * const whiteLight = new Light2d(0, 0, 140, "#fff", 0.7);
-   * // and add the light to this current stage
+   * // recommended:
+   * const whiteLight = new Light2d(100, 100, 140, 140, "#fff", 0.7);
+   * app.world.addChild(whiteLight);
+   *
+   * // legacy (still works, auto-adopted into world):
    * this.lights.set("whiteLight", whiteLight);
-   * // set a dark ambient light
+   *
    * this.ambientLight.parseCSS("#1117");
-   * // make the light follow the mouse
-   * input.registerPointerEvent("pointermove", app.viewport, (event) => {
-   *    whiteLight.centerOn(event.gameX, event.gameY);
-   * });
    */
   lights;
+  /**
+   * Internal set of active lights, auto-populated by `Light2d`'s
+   * `onActivateEvent` / `onDeactivateEvent` hooks. Used by Camera2d's
+   * ambient-overlay pass to compute the cutouts.
+   * @ignore
+   */
+  _activeLights;
   /**
    * an ambient light that will be added to the stage rendering
    * @default "#000000"
    * @see Light2d
    */
   ambientLight;
+  /**
+   * Base light level applied to every normal-mapped sprite in the
+   * lit rendering path. Unlike {@link Stage#ambientLight} (which is
+   * the dark overlay punched by each light's cutout), this color is
+   * added to every lit pixel so unlit areas don't render pure
+   * black. Defaults to black (0, 0, 0) — sprites without a
+   * `normalMap` ignore it entirely.
+   * @default "#000000"
+   */
+  ambientLightingColor;
   /**
    * The given constructor options
    */
@@ -23396,9 +23719,26 @@ var Stage = class {
   constructor(settings) {
     this.cameras = /* @__PURE__ */ new Map();
     this.lights = /* @__PURE__ */ new Map();
+    this._activeLights = /* @__PURE__ */ new Set();
     this.ambientLight = new Color(0, 0, 0, 0);
+    this.ambientLightingColor = new Color(0, 0, 0, 1);
     this.settings = Object.assign({}, default_settings, settings || {});
   }
+  /**
+   * Called by `Light2d.onActivateEvent` to register the light with the
+   * stage's ambient-overlay cutout list. Users normally don't call this.
+   * @ignore
+   */
+  _registerLight(light) {
+    this._activeLights.add(light);
+  }
+  /**
+   * Called by `Light2d.onDeactivateEvent` to deregister the light.
+   * @ignore
+   */
+  _unregisterLight(light) {
+    this._activeLights.delete(light);
+  }
   /**
    * Object reset function
    * @ignore
@@ -23419,6 +23759,13 @@ var Stage = class {
     }
     emit(STAGE_RESET, this);
     this.onResetEvent(app, ...extraArgs);
+    if (app && app.world) {
+      this.lights.forEach((light) => {
+        if (!light.ancestor) {
+          app.world.addChild(light);
+        }
+      });
+    }
   }
   /**
    * update function
@@ -23433,40 +23780,60 @@ var Stage = class {
         isDirty = true;
       }
     });
-    this.lights.forEach((light) => {
-      if (light.update()) {
-        isDirty = true;
-      }
-    });
     return isDirty;
   }
   /**
    * draw the current stage
+   *
+   * Lights are rendered as part of the world tree (they're now first-class
+   * Renderables) and the ambient overlay pass runs inside each Camera's
+   * post-effect FBO bracket via {@link Stage#drawLighting}.
    * @ignore
    * @param renderer - the renderer object to draw with
    * @param world - the world object to draw
    */
   draw(renderer2, world) {
-    const r = renderer2;
     this.cameras.forEach((camera) => {
       camera.draw(renderer2, world);
-      if (this.ambientLight.alpha !== 0) {
-        r.save();
-        this.lights.forEach((light) => {
-          r.setMask(light.getVisibleArea(), true);
-        });
-        r.setColor(this.ambientLight);
-        r.fillRect(0, 0, camera.width, camera.height);
-        r.clearMask();
-        r.restore();
-      }
-      this.lights.forEach((light) => {
-        light.preDraw(r);
-        light.draw(r);
-        light.postDraw(r);
-      });
     });
   }
+  /**
+   * Draw the stage's ambient-light overlay with cutouts for each active
+   * light. Called from each `Camera2d` inside its post-effect FBO bracket —
+   * lights themselves render via the world tree (they're standard
+   * Renderables); this pass only paints the dark fill that the lights cut
+   * holes through.
+   *
+   * Subclasses can override this method to implement custom lighting (e.g.
+   * per-pixel normal-mapped lighting via a custom shader). Called once per
+   * camera per frame.
+   * @param renderer - the active renderer
+   * @param camera - the camera currently rendering this stage
+   * @param translateX - the same world-to-screen X translate that
+   *   `Camera2d.draw()` applies to the world container (i.e.
+   *   `camera.pos.x + camera.offset.x` for the default camera, plus
+   *   the container's own offset for non-default cameras)
+   * @param translateY - the world-to-screen Y translate (see `translateX`)
+   */
+  drawLighting(renderer2, camera, translateX = camera.pos.x + camera.offset.x, translateY = camera.pos.y + camera.offset.y) {
+    if (this.ambientLight.alpha === 0) {
+      return;
+    }
+    const r = renderer2;
+    r.save();
+    const tx = translateX;
+    const ty = translateY;
+    if (tx !== 0 || ty !== 0) {
+      r.translate(-tx, -ty);
+    }
+    this._activeLights.forEach((light) => {
+      r.setMask(light.getVisibleArea(), true);
+    });
+    r.setColor(this.ambientLight);
+    r.fillRect(tx, ty, camera.width, camera.height);
+    r.clearMask();
+    r.restore();
+  }
   /**
    * destroy function
    * @ignore
@@ -23474,9 +23841,12 @@ var Stage = class {
   destroy(app) {
     this.cameras.clear();
     this.lights.forEach((light) => {
-      light.destroy();
+      if (!light.ancestor) {
+        light.destroy();
+      }
     });
     this.lights.clear();
+    this._activeLights.clear();
     this.onDestroyEvent(app);
   }
   /**
@@ -26825,64 +27195,33 @@ var ImageLayer = class extends Sprite {
 };
 
 // src/renderable/light2d.js
-function createGradient(light) {
-  const context = light.texture.context;
-  const x1 = light.texture.width / 2;
-  const y1 = light.texture.height / 2;
-  const radiusX = light.radiusX;
-  const radiusY = light.radiusY;
-  let scaleX;
-  let scaleY;
-  let invScaleX;
-  let invScaleY;
-  let gradient;
-  light.texture.clear();
-  if (radiusX >= radiusY) {
-    scaleX = 1;
-    invScaleX = 1;
-    scaleY = radiusY / radiusX;
-    invScaleY = radiusX / radiusY;
-    gradient = context.createRadialGradient(
-      x1,
-      y1 * invScaleY,
-      0,
-      x1,
-      radiusY * invScaleY,
-      radiusX
-    );
-  } else {
-    scaleY = 1;
-    invScaleY = 1;
-    scaleX = radiusX / radiusY;
-    invScaleX = radiusY / radiusX;
-    gradient = context.createRadialGradient(
-      x1 * invScaleX,
-      y1,
-      0,
-      x1 * invScaleX,
-      y1,
-      radiusY
-    );
-  }
-  gradient.addColorStop(0, light.color.toRGBA(light.intensity));
-  gradient.addColorStop(1, light.color.toRGBA(0));
-  context.fillStyle = gradient;
-  context.setTransform(scaleX, 0, 0, scaleY, 0, 0);
-  context.fillRect(
-    0,
-    0,
-    light.texture.width * invScaleX,
-    light.texture.height * invScaleY
-  );
-}
 var Light2d = class extends Renderable {
   /**
-   * @param {number} x - The horizontal position of the light.
-   * @param {number} y - The vertical position of the light.
+   * Create a 2D point light.
+   *
+   * A `Light2d` is a first-class world Renderable: add it to a container
+   * with `app.world.addChild(light)` (or any sub-container, including a
+   * `Sprite`, so the light follows the parent via its transform). On
+   * activation, the light auto-registers with the active `Stage`'s
+   * lighting set so the ambient overlay (`Stage.ambientLight`) cuts a
+   * hole at the light's visible area, and a radial gradient from the
+   * given `color` (full intensity at center → fully transparent at the
+   * radius) is composited additively on top — producing a soft spot
+   * light. Rendering happens inside each `Camera2d`'s post-effect FBO
+   * bracket so any camera shader (vignette, color-matrix, scanlines,
+   * etc.) wraps the lighting output.
+   *
+   * Set `radiusY` to a different value than `radiusX` for a stretched
+   * (elliptical) light. The `intensity` parameter scales the gradient's
+   * inner alpha; the `Stage.ambientLight` color and alpha control how
+   * dark the unlit areas are. Use `light.blendMode` to override the
+   * default additive blend if needed.
+   * @param {number} x - The horizontal position of the light's center (matches `Ellipse(x, y, w, h)` conventions).
+   * @param {number} y - The vertical position of the light's center.
    * @param {number} radiusX - The horizontal radius of the light.
    * @param {number} [radiusY=radiusX] - The vertical radius of the light.
-   * @param {Color|string} [color="#FFF"] - the color of the light
-   * @param {number} [intensity=0.7] - The intensity of the light.
+   * @param {Color|string} [color="#FFF"] - The color of the light at full intensity.
+   * @param {number} [intensity=0.7] - The peak alpha of the radial gradient at the light's center (0–1).
    */
   constructor(x, y, radiusX, radiusY = radiusX, color = "#FFF", intensity = 0.7) {
     super(x, y, radiusX * 2, radiusY * 2);
@@ -26892,32 +27231,77 @@ var Light2d = class extends Renderable {
     this.intensity = intensity;
     this.blendMode = "lighter";
     this.visibleArea = ellipsePool.get(
-      this.centerX,
-      this.centerY,
+      this.pos.x,
+      this.pos.y,
       this.width,
       this.height
     );
-    this.texture = new canvasrendertarget_default(this.width, this.height, {
-      offscreenCanvas: false
-    });
-    this.anchorPoint.set(0, 0);
-    createGradient(this);
+    this.anchorPoint.set(0.5, 0.5);
+    this.illuminationOnly = false;
+    this.lightHeight = Math.max(radiusX, radiusY) * 0.075;
   }
   /**
-   * returns a geometry representing the visible area of this light
+   * the horizontal coordinate of this light's center.
+   * Overrides Rect's getter, which assumes `pos` is the bbox top-left and
+   * returns `pos.x + width/2`. Light2d uses `anchorPoint = (0.5, 0.5)`, so
+   * `pos` already IS the center.
+   * @type {number}
+   */
+  get centerX() {
+    return this.pos.x;
+  }
+  set centerX(value) {
+    this.pos.x = value;
+    this.recalc();
+    this.updateBounds();
+  }
+  /**
+   * the vertical coordinate of this light's center.
+   * @see Light2d#centerX
+   * @type {number}
+   */
+  get centerY() {
+    return this.pos.y;
+  }
+  set centerY(value) {
+    this.pos.y = value;
+    this.recalc();
+    this.updateBounds();
+  }
+  /**
+   * Set new radii for this light.
+   *
+   * Updates `radiusX`/`radiusY` and the underlying bbox (via
+   * `Renderable.resize(width, height)`) so `getBounds()` and
+   * `getVisibleArea()` — which feed the ambient-cutout pass — track the
+   * new size. The Canvas renderer's gradient cache auto-invalidates on
+   * next draw via its property comparison; the WebGL procedural shader
+   * adapts to the new dimensions automatically.
+   *
+   * Named `setRadii` (not `resize`) so it does not shadow
+   * `Renderable.resize(width, height)` — code that operates on a
+   * generic `Renderable` and calls `.resize(w, h)` keeps working when
+   * the instance happens to be a `Light2d`.
+   * @param {number} radiusX - new horizontal radius
+   * @param {number} [radiusY=radiusX] - new vertical radius
+   */
+  setRadii(radiusX, radiusY = radiusX) {
+    this.radiusX = radiusX;
+    this.radiusY = radiusY;
+    this.resize(radiusX * 2, radiusY * 2);
+  }
+  /**
+   * returns a geometry representing the visible area of this light, in
+   * world-space coordinates (so it aligns with the rendered gradient
+   * regardless of camera scroll or container parenting).
    * @returns {Ellipse} the light visible mask
    */
   getVisibleArea() {
-    return this.visibleArea.setShape(
-      this.getBounds().centerX,
-      this.getBounds().centerY,
-      this.width,
-      this.height
-    );
+    const b = this.getBounds();
+    return this.visibleArea.setShape(b.centerX, b.centerY, b.width, b.height);
   }
   /**
    * update function
-   * @param {number} dt - time since the last update in milliseconds.
    * @returns {boolean} true if dirty
    */
   update() {
@@ -26925,25 +27309,50 @@ var Light2d = class extends Renderable {
   }
   /**
    * preDraw this Light2d (automatically called by melonJS)
-   * Note: The renderer should set the blend mode again (after drawing other Light2d objects)
-   * to ensure colors blend correctly in the CanvasRenderer.
-   * @param {CanvasRenderer|WebGLRenderer} renderer - a renderer instance
+   * @param {Renderer} renderer - a renderer instance
    */
   preDraw(renderer2) {
     super.preDraw(renderer2);
     renderer2.setBlendMode(this.blendMode);
   }
   /**
-   * draw this Light2d (automatically called by melonJS)
-   * @param {CanvasRenderer|WebGLRenderer} renderer - a renderer instance
-   * @param {Camera2d} [viewport] - the viewport to (re)draw
+   * draw this Light2d (automatically called by melonJS).
+   *
+   * Delegates to `renderer.drawLight(this)` — each renderer picks its
+   * own implementation (procedural shader on WebGL; cached `Gradient`
+   * rasterized into a shared `CanvasRenderTarget` on Canvas). Light2d
+   * itself doesn't know which path is used.
+   * @param {Renderer} renderer - a renderer instance
    */
   draw(renderer2) {
-    renderer2.drawImage(
-      this.texture.canvas,
-      this.getBounds().x,
-      this.getBounds().y
-    );
+    if (this.illuminationOnly) {
+      return;
+    }
+    renderer2.drawLight(this);
+  }
+  /**
+   * Auto-register this light with the active Stage's lighting set when
+   * added to a container. The Stage uses that set to build the ambient
+   * overlay cutouts; rendering the light itself is handled normally as
+   * part of the world tree walk.
+   * @ignore
+   */
+  onActivateEvent() {
+    const stage = state_default.current();
+    if (stage && typeof stage._registerLight === "function") {
+      stage._registerLight(this);
+    }
+  }
+  /**
+   * Auto-deregister this light from the active Stage's lighting set when
+   * removed from a container.
+   * @ignore
+   */
+  onDeactivateEvent() {
+    const stage = state_default.current();
+    if (stage && typeof stage._unregisterLight === "function") {
+      stage._unregisterLight(this);
+    }
   }
   /**
    * Destroy function<br>
@@ -26952,9 +27361,6 @@ var Light2d = class extends Renderable {
   destroy() {
     colorPool.release(this.color);
     this.color = void 0;
-    const renderer2 = this.parentApp?.renderer ?? game.renderer;
-    this.texture.destroy(renderer2);
-    this.texture = void 0;
     ellipsePool.release(this.visibleArea);
     this.visibleArea = void 0;
     super.destroy();
@@ -27406,7 +27812,7 @@ var Trigger = class extends Renderable {
 };
 
 // src/version.ts
-var version = "19.2.0";
+var version = "19.3.0";
 
 // src/system/bootstrap.ts
 var initialized = false;
@@ -30008,114 +30414,92 @@ function generateJoinCircles(centers, radius) {
   return verts;
 }
 
-// src/video/webgl/shaders/mesh.frag
-var mesh_default = "uniform sampler2D uSampler;\nvarying vec4 vColor;\nvarying vec2 vRegion;\n\nvoid main(void) {\n    gl_FragColor = texture2D(uSampler, vRegion) * vColor;\n}\n";
-
-// src/video/webgl/shaders/mesh.vert
-var mesh_default2 = "// Current vertex point (3D position for mesh rendering)\nattribute vec3 aVertex;\nattribute vec2 aRegion;\nattribute vec4 aColor;\n\n// Projection matrix\nuniform mat4 uProjectionMatrix;\n\nvarying vec2 vRegion;\nvarying vec4 vColor;\n\nvoid main(void) {\n    // Transform the vertex position by the projection matrix\n    gl_Position = uProjectionMatrix * vec4(aVertex, 1.0);\n    // Pass the remaining attributes to the fragment shader\n    vColor = vec4(aColor.bgr * aColor.a, aColor.a);\n    vRegion = aRegion;\n}\n";
+// src/video/webgl/lighting/constants.ts
+var MAX_LIGHTS = 8;
 
-// src/video/buffer/vertex.js
-var VertexArrayBuffer = class {
-  constructor(vertexSize, maxVertex) {
-    this.vertexSize = vertexSize;
-    this.maxVertex = maxVertex;
-    this.vertexCount = 0;
-    this.buffer = new ArrayBuffer(
-      this.maxVertex * this.vertexSize * Float32Array.BYTES_PER_ELEMENT
-    );
-    this.bufferF32 = new Float32Array(this.buffer);
-    this.bufferU32 = new Uint32Array(this.buffer);
-  }
-  /**
-   * clear the vertex array buffer
-   * @ignore
-   */
-  clear() {
-    this.vertexCount = 0;
-  }
-  /**
-   * return true if full
-   * @ignore
-   */
-  isFull(vertex) {
-    return this.vertexCount + vertex >= this.maxVertex;
-  }
-  /**
-   * push a new vertex to the buffer
-   * @param {number} x - x position
-   * @param {number} y - y position
-   * @param {number} u - texture U coordinate
-   * @param {number} v - texture V coordinate
-   * @param {number} tint - tint color in UINT32 (argb) format
-   * @param {number} [textureId] - texture unit index for multi-texture batching
-   * @ignore
-   */
-  push(x, y, u, v, tint, textureId) {
-    const offset = this.vertexCount * this.vertexSize;
-    this.bufferF32[offset] = x;
-    this.bufferF32[offset + 1] = y;
-    this.bufferF32[offset + 2] = u;
-    this.bufferF32[offset + 3] = v;
-    this.bufferU32[offset + 4] = tint;
-    if (this.vertexSize > 5) {
-      this.bufferF32[offset + 5] = textureId || 0;
-    }
-    this.vertexCount++;
-    return this;
-  }
-  /**
-   * push a new vertex with all-float data to the buffer
-   * @param {ArrayLike<number>} data - float values for one vertex
-   * @param {number} srcOffset - start index in the source data
-   * @param {number} count - number of floats to copy (should equal vertexSize)
-   * @ignore
-   */
-  pushFloats(data2, srcOffset, count) {
-    const offset = this.vertexCount * this.vertexSize;
-    for (let i = 0; i < count; i++) {
-      this.bufferF32[offset + i] = data2[srcOffset + i];
-    }
-    this.vertexCount++;
-    return this;
-  }
-  /**
-   * push a new vertex to the buffer (mesh format: x, y, z, u, v, tint)
-   * @ignore
-   */
-  pushMesh(x, y, z, u, v, tint) {
-    const offset = this.vertexCount * this.vertexSize;
-    this.bufferF32[offset] = x;
-    this.bufferF32[offset + 1] = y;
-    this.bufferF32[offset + 2] = z;
-    this.bufferF32[offset + 3] = u;
-    this.bufferF32[offset + 4] = v;
-    this.bufferU32[offset + 5] = tint;
-    this.vertexCount++;
-    return this;
-  }
-  /**
-   * return a reference to the data in Float32 format
-   * @ignore
-   */
-  toFloat32(begin, end) {
-    if (typeof end !== "undefined") {
-      return this.bufferF32.subarray(begin, end);
+// src/video/webgl/shaders/multitexture-lit.js
+function buildSamplerSelect(varName, samplerPrefix, count, target) {
+  const lines = [];
+  for (let i = 0; i < count; i++) {
+    if (i === 0) {
+      lines.push("    if (" + varName + " < 0.5) {");
     } else {
-      return this.bufferF32;
+      lines.push("    } else if (" + varName + " < " + (i + 0.5) + ") {");
     }
+    lines.push(
+      "        " + target + " = texture2D(" + samplerPrefix + i + ", vRegion);"
+    );
   }
-  /**
-   * return a reference to the data in Uint32 format
-   * @ignore
-   */
-  toUint32(begin, end) {
-    if (typeof end !== "undefined") {
-      return this.bufferU32.subarray(begin, end);
-    } else {
-      return this.bufferU32;
-    }
+  lines.push("    } else {");
+  lines.push(
+    "        " + target + " = texture2D(" + samplerPrefix + "0, vRegion);"
+  );
+  lines.push("    }");
+  return lines;
+}
+function buildLitMultiTextureFragment(maxTextures) {
+  const count = Math.max(maxTextures, 1);
+  const lines = [];
+  for (let i = 0; i < count; i++) {
+    lines.push("uniform sampler2D uSampler" + i + ";");
   }
-};
+  for (let i = 0; i < count; i++) {
+    lines.push("uniform sampler2D uNormalSampler" + i + ";");
+  }
+  lines.push("uniform int uLightCount;");
+  lines.push("uniform vec4 uLightPos[" + MAX_LIGHTS + "];");
+  lines.push("uniform vec3 uLightColor[" + MAX_LIGHTS + "];");
+  lines.push("uniform float uLightHeight[" + MAX_LIGHTS + "];");
+  lines.push("uniform vec3 uAmbient;");
+  lines.push("varying vec4 vColor;");
+  lines.push("varying vec2 vRegion;");
+  lines.push("varying float vTextureId;");
+  lines.push("varying float vNormalTextureId;");
+  lines.push("varying vec2 vWorldPos;");
+  lines.push("");
+  lines.push("void main(void) {");
+  lines.push("    vec4 color;");
+  lines.push(...buildSamplerSelect("vTextureId", "uSampler", count, "color"));
+  lines.push("    if (vNormalTextureId < -0.5) {");
+  lines.push("        gl_FragColor = color * vColor;");
+  lines.push("        return;");
+  lines.push("    }");
+  lines.push("    vec4 normalSample;");
+  lines.push(
+    ...buildSamplerSelect(
+      "vNormalTextureId",
+      "uNormalSampler",
+      count,
+      "normalSample"
+    )
+  );
+  lines.push(
+    "    vec3 normal = normalize(normalSample.rgb * 2.0 - vec3(1.0));"
+  );
+  lines.push("    normal.y = -normal.y;");
+  lines.push("    vec3 lighting = uAmbient;");
+  lines.push("    for (int i = 0; i < " + MAX_LIGHTS + "; i++) {");
+  lines.push("        if (i >= uLightCount) break;");
+  lines.push("        vec4 lp = uLightPos[i];");
+  lines.push("        vec2 toLight = lp.xy - vWorldPos;");
+  lines.push("        float dist = length(toLight);");
+  lines.push("        float linear = max(0.0, 1.0 - dist / max(lp.z, 1.0));");
+  lines.push("        float att = linear * linear;");
+  lines.push(
+    "        vec3 lightDir = normalize(vec3(toLight, uLightHeight[i]));"
+  );
+  lines.push("        float NdotL = max(0.0, dot(normal, lightDir));");
+  lines.push("        lighting += uLightColor[i] * (lp.w * att * NdotL);");
+  lines.push("    }");
+  lines.push(
+    "    gl_FragColor = vec4(color.rgb * lighting, color.a) * vColor;"
+  );
+  lines.push("}");
+  return lines.join("\n");
+}
+
+// src/video/webgl/shaders/quad-multi-lit.vert
+var quad_multi_lit_default = "// Lit-aware vertex shader used by `LitQuadBatcher` (the SpriteIlluminator\n// path). Carries a paired `aNormalTextureId` per vertex so the fragment\n// shader knows which `uNormalSampler<n>` to read, and `vWorldPos` so the\n// lit math can compute per-fragment `lightPos - pos` deltas.\nattribute vec2 aVertex;\nattribute vec2 aRegion;\nattribute vec4 aColor;\nattribute float aTextureId;\nattribute float aNormalTextureId;\n\nuniform mat4 uProjectionMatrix;\n\nvarying vec2 vRegion;\nvarying vec4 vColor;\nvarying float vTextureId;\nvarying float vNormalTextureId;\n// Pre-projection vertex position (in the renderer's pre-projection\n// space \u2014 typically camera-local for default cameras with the world\n// container's translate applied). Used by the lit fragment path to\n// compute `lightPos - fragmentPos` for each Light2d.\nvarying vec2 vWorldPos;\n\nvoid main(void) {\n    gl_Position = uProjectionMatrix * vec4(aVertex, 0.0, 1.0);\n    vColor = vec4(aColor.bgr * aColor.a, aColor.a);\n    vRegion = aRegion;\n    vTextureId = aTextureId;\n    vNormalTextureId = aNormalTextureId;\n    vWorldPos = aVertex;\n}\n";
 
 // src/video/buffer/index.js
 var IndexBuffer = class {
@@ -30216,6 +30600,145 @@ var WebGLIndexBuffer = class extends IndexBuffer {
   }
 };
 
+// src/video/webgl/shaders/multitexture.js
+function buildMultiTextureFragment(maxTextures) {
+  const count = Math.max(maxTextures, 1);
+  const lines = [];
+  for (let i = 0; i < count; i++) {
+    lines.push("uniform sampler2D uSampler" + i + ";");
+  }
+  lines.push("varying vec4 vColor;");
+  lines.push("varying vec2 vRegion;");
+  lines.push("varying float vTextureId;");
+  lines.push("");
+  lines.push("void main(void) {");
+  lines.push("    vec4 color;");
+  for (let i = 0; i < count; i++) {
+    if (i === 0) {
+      lines.push("    if (vTextureId < 0.5) {");
+    } else {
+      lines.push("    } else if (vTextureId < " + (i + 0.5) + ") {");
+    }
+    lines.push("        color = texture2D(uSampler" + i + ", vRegion);");
+  }
+  lines.push("    } else {");
+  lines.push("        color = texture2D(uSampler0, vRegion);");
+  lines.push("    }");
+  lines.push("    gl_FragColor = color * vColor;");
+  lines.push("}");
+  return lines.join("\n");
+}
+
+// src/video/webgl/shaders/quad-multi.vert
+var quad_multi_default = "// Current vertex point\nattribute vec2 aVertex;\nattribute vec2 aRegion;\nattribute vec4 aColor;\nattribute float aTextureId;\n\n// Projection matrix\nuniform mat4 uProjectionMatrix;\n\nvarying vec2 vRegion;\nvarying vec4 vColor;\nvarying float vTextureId;\n\nvoid main(void) {\n    // Transform the vertex position by the projection matrix\n    gl_Position = uProjectionMatrix * vec4(aVertex, 0.0, 1.0);\n    // Pass the remaining attributes to the fragment shader\n    vColor = vec4(aColor.bgr * aColor.a, aColor.a);\n    vRegion = aRegion;\n    vTextureId = aTextureId;\n}\n";
+
+// src/video/buffer/vertex.js
+var VertexArrayBuffer = class {
+  constructor(vertexSize, maxVertex) {
+    this.vertexSize = vertexSize;
+    this.maxVertex = maxVertex;
+    this.vertexCount = 0;
+    this.buffer = new ArrayBuffer(
+      this.maxVertex * this.vertexSize * Float32Array.BYTES_PER_ELEMENT
+    );
+    this.bufferF32 = new Float32Array(this.buffer);
+    this.bufferU32 = new Uint32Array(this.buffer);
+  }
+  /**
+   * clear the vertex array buffer
+   * @ignore
+   */
+  clear() {
+    this.vertexCount = 0;
+  }
+  /**
+   * return true if full
+   * @ignore
+   */
+  isFull(vertex) {
+    return this.vertexCount + vertex >= this.maxVertex;
+  }
+  /**
+   * push a new vertex to the buffer
+   * @param {number} x - x position
+   * @param {number} y - y position
+   * @param {number} u - texture U coordinate
+   * @param {number} v - texture V coordinate
+   * @param {number} tint - tint color in UINT32 (argb) format
+   * @param {number} [textureId] - texture unit index for multi-texture batching
+   * @param {number} [normalTextureId] - paired normal-map texture unit index, or `-1` for unlit quads
+   * @ignore
+   */
+  push(x, y, u, v, tint, textureId, normalTextureId) {
+    const offset = this.vertexCount * this.vertexSize;
+    this.bufferF32[offset] = x;
+    this.bufferF32[offset + 1] = y;
+    this.bufferF32[offset + 2] = u;
+    this.bufferF32[offset + 3] = v;
+    this.bufferU32[offset + 4] = tint;
+    if (this.vertexSize > 5) {
+      this.bufferF32[offset + 5] = textureId || 0;
+      if (this.vertexSize > 6) {
+        this.bufferF32[offset + 6] = typeof normalTextureId === "number" ? normalTextureId : -1;
+      }
+    }
+    this.vertexCount++;
+    return this;
+  }
+  /**
+   * push a new vertex with all-float data to the buffer
+   * @param {ArrayLike<number>} data - float values for one vertex
+   * @param {number} srcOffset - start index in the source data
+   * @param {number} count - number of floats to copy (should equal vertexSize)
+   * @ignore
+   */
+  pushFloats(data2, srcOffset, count) {
+    const offset = this.vertexCount * this.vertexSize;
+    for (let i = 0; i < count; i++) {
+      this.bufferF32[offset + i] = data2[srcOffset + i];
+    }
+    this.vertexCount++;
+    return this;
+  }
+  /**
+   * push a new vertex to the buffer (mesh format: x, y, z, u, v, tint)
+   * @ignore
+   */
+  pushMesh(x, y, z, u, v, tint) {
+    const offset = this.vertexCount * this.vertexSize;
+    this.bufferF32[offset] = x;
+    this.bufferF32[offset + 1] = y;
+    this.bufferF32[offset + 2] = z;
+    this.bufferF32[offset + 3] = u;
+    this.bufferF32[offset + 4] = v;
+    this.bufferU32[offset + 5] = tint;
+    this.vertexCount++;
+    return this;
+  }
+  /**
+   * return a reference to the data in Float32 format
+   * @ignore
+   */
+  toFloat32(begin, end) {
+    if (typeof end !== "undefined") {
+      return this.bufferF32.subarray(begin, end);
+    } else {
+      return this.bufferF32;
+    }
+  }
+  /**
+   * return a reference to the data in Uint32 format
+   * @ignore
+   */
+  toUint32(begin, end) {
+    if (typeof end !== "undefined") {
+      return this.bufferU32.subarray(begin, end);
+    } else {
+      return this.bufferU32;
+    }
+  }
+};
+
 // src/video/webgl/batchers/batcher.js
 var DEFAULT_MAX_VERTICES = 4096;
 var Batcher = class {
@@ -30314,6 +30837,25 @@ var Batcher = class {
       this.useShader(this.defaultShader);
     }
   }
+  /**
+   * called by the WebGL renderer when this batcher is being replaced by another.
+   * Disables this batcher's vertex attribute locations so they don't leak across
+   * (otherwise stale stride/offset state can cause INVALID_OPERATION on the next draw).
+   */
+  unbind() {
+    if (this.currentShader === void 0) {
+      return;
+    }
+    const gl = this.gl;
+    for (let i = 0; i < this.attributes.length; ++i) {
+      const location = this.currentShader.getAttribLocation(
+        this.attributes[i].name
+      );
+      if (location !== -1) {
+        gl.disableVertexAttribArray(location);
+      }
+    }
+  }
   /**
    * Select the shader to use for compositing
    * @see GLShader
@@ -30322,6 +30864,9 @@ var Batcher = class {
   useShader(shader) {
     if (this.currentShader !== shader || this.renderer.currentProgram !== shader.program) {
       this.flush();
+      if (this.currentShader && this.currentShader !== shader) {
+        this.unbind();
+      }
       shader.bind();
       shader.setUniform(this.projectionUniform, this.renderer.projectionMatrix);
       shader.setVertexAttributes(this.gl, this.attributes, this.stride);
@@ -30667,6 +31212,514 @@ var MaterialBatcher = class extends Batcher {
   }
 };
 
+// src/video/webgl/batchers/quad_batcher.js
+var V_ARRAY = [
+  new Vector2d(),
+  new Vector2d(),
+  new Vector2d(),
+  new Vector2d()
+];
+var QuadBatcher = class extends MaterialBatcher {
+  /**
+   * Initialize the compositor
+   * @ignore
+   */
+  init(renderer2) {
+    this.maxBatchTextures = Math.min(renderer2.maxTextures, 16);
+    super.init(renderer2, {
+      attributes: [
+        {
+          name: "aVertex",
+          size: 2,
+          type: renderer2.gl.FLOAT,
+          normalized: false,
+          offset: 0 * Float32Array.BYTES_PER_ELEMENT
+        },
+        {
+          name: "aRegion",
+          size: 2,
+          type: renderer2.gl.FLOAT,
+          normalized: false,
+          offset: 2 * Float32Array.BYTES_PER_ELEMENT
+        },
+        {
+          name: "aColor",
+          size: 4,
+          type: renderer2.gl.UNSIGNED_BYTE,
+          normalized: true,
+          offset: 4 * Float32Array.BYTES_PER_ELEMENT
+        },
+        {
+          name: "aTextureId",
+          size: 1,
+          type: renderer2.gl.FLOAT,
+          normalized: false,
+          offset: 5 * Float32Array.BYTES_PER_ELEMENT
+        }
+      ],
+      shader: {
+        vertex: quad_multi_default,
+        fragment: buildMultiTextureFragment(this.maxBatchTextures)
+      }
+    });
+    this.bindColorSamplers();
+    this.useMultiTexture = true;
+    this.createIndexBuffer();
+  }
+  /**
+   * (Re-)create the index buffer for quad batching (4 verts + 6 indices per quad).
+   * Called from `init` and `reset` (after context loss).
+   * @ignore
+   */
+  createIndexBuffer() {
+    const maxQuads = this.vertexData.maxVertex / 4;
+    this.indexBuffer = new WebGLIndexBuffer(
+      this.gl,
+      maxQuads * 6,
+      this.renderer.WebGLVersion > 1
+    );
+    this.indexBuffer.fillQuadPattern(maxQuads);
+  }
+  /**
+   * Bind the color sampler uniforms (`uSampler0..uSamplerN-1`) to their
+   * respective texture units. Called from `init` and `reset`.
+   * @ignore
+   */
+  bindColorSamplers() {
+    for (let i = 0; i < this.maxBatchTextures; i++) {
+      this.defaultShader.setUniform("uSampler" + i, i);
+    }
+  }
+  /**
+   * Select the shader to use for compositing.
+   * Multi-texture batching is automatically enabled when the default
+   * shader is active, and disabled for custom ShaderEffect shaders.
+   * @see GLShader
+   * @see ShaderEffect
+   * @param {GLShader|ShaderEffect} shader - a reference to a GLShader or ShaderEffect instance
+   */
+  useShader(shader) {
+    super.useShader(shader);
+    this.useMultiTexture = shader === this.defaultShader;
+  }
+  /**
+   * Reset compositor internal state
+   * @ignore
+   */
+  reset() {
+    super.reset();
+    this.createIndexBuffer();
+    this.bindColorSamplers();
+    this.useMultiTexture = true;
+  }
+  /**
+   * Flush batched texture data to the GPU using indexed drawing.
+   * @param {number} [mode=gl.TRIANGLES] - the GL drawing mode
+   */
+  flush(mode = this.mode) {
+    const vertex = this.vertexData;
+    const vertexCount = vertex.vertexCount;
+    if (vertexCount > 0) {
+      const gl = this.gl;
+      const vertexSize = vertex.vertexSize;
+      this.indexBuffer.bind();
+      if (this.renderer.WebGLVersion > 1) {
+        gl.bufferData(
+          gl.ARRAY_BUFFER,
+          vertex.toFloat32(),
+          gl.STREAM_DRAW,
+          0,
+          vertexCount * vertexSize
+        );
+      } else {
+        gl.bufferData(
+          gl.ARRAY_BUFFER,
+          vertex.toFloat32(0, vertexCount * vertexSize),
+          gl.STREAM_DRAW
+        );
+      }
+      const indexCount = vertexCount / 4 * 6;
+      gl.drawElements(mode, indexCount, this.indexBuffer.type, 0);
+      vertex.clear();
+    }
+  }
+  /**
+   * Draw a screen-aligned quad with the given raw WebGL texture through the given shader.
+   * Binds the texture to unit 0, pushes 4 vertices (Y-flipped UVs), flushes,
+   * then unbinds the texture.
+   * @param {WebGLTexture} source - the raw GL texture to blit
+   * @param {number} x - destination x
+   * @param {number} y - destination y
+   * @param {number} width - destination width
+   * @param {number} height - destination height
+   * @param {GLShader|ShaderEffect} shader - the shader effect to apply
+   */
+  blitTexture(source, x, y, width, height, shader) {
+    const gl = this.gl;
+    this.useShader(shader);
+    gl.activeTexture(gl.TEXTURE0);
+    gl.bindTexture(gl.TEXTURE_2D, source);
+    this.currentTextureUnit = 0;
+    this.boundTextures[0] = source;
+    shader.setUniform("uSampler", 0);
+    const m = this.viewMatrix;
+    const vec0 = V_ARRAY[0].set(x, y);
+    const vec1 = V_ARRAY[1].set(x + width, y);
+    const vec2 = V_ARRAY[2].set(x, y + height);
+    const vec3 = V_ARRAY[3].set(x + width, y + height);
+    if (m && !m.isIdentity()) {
+      m.apply(vec0);
+      m.apply(vec1);
+      m.apply(vec2);
+      m.apply(vec3);
+    }
+    const tint = 4294967295;
+    this.vertexData.push(vec0.x, vec0.y, 0, 1, tint, 0);
+    this.vertexData.push(vec1.x, vec1.y, 1, 1, tint, 0);
+    this.vertexData.push(vec2.x, vec2.y, 0, 0, tint, 0);
+    this.vertexData.push(vec3.x, vec3.y, 1, 0, tint, 0);
+    this.flush();
+    gl.activeTexture(gl.TEXTURE0);
+    gl.bindTexture(gl.TEXTURE_2D, null);
+    this.currentTextureUnit = -1;
+    delete this.boundTextures[0];
+    this.useShader(this.defaultShader);
+  }
+  /**
+   * Add a textured quad
+   * @param {TextureAtlas} texture - Source texture atlas
+   * @param {number} x - Destination x-coordinate
+   * @param {number} y - Destination y-coordinate
+   * @param {number} w - Destination width
+   * @param {number} h - Destination height
+   * @param {number} u0 - Texture UV (u0) value.
+   * @param {number} v0 - Texture UV (v0) value.
+   * @param {number} u1 - Texture UV (u1) value.
+   * @param {number} v1 - Texture UV (v1) value.
+   * @param {number} tint - tint color to be applied to the texture in UINT32 (argb) format
+   * @param {boolean} [reupload=false] - Force the texture to be reuploaded even if already bound
+   */
+  addQuad(texture, x, y, w, h, u0, v0, u1, v1, tint, reupload = false) {
+    const vertexData = this.vertexData;
+    if (vertexData.isFull(4)) {
+      this.flush();
+    }
+    let unit;
+    if (this.useMultiTexture) {
+      unit = this.uploadTexture(texture, w, h, reupload, false);
+      if (unit >= this.maxBatchTextures) {
+        this.flush();
+        this.renderer.cache.resetUnitAssignments();
+        unit = this.uploadTexture(texture, w, h, reupload, false);
+      }
+    } else {
+      unit = this.uploadTexture(texture, w, h, reupload);
+      if (unit !== this.currentSamplerUnit) {
+        this.currentShader.setUniform("uSampler", unit);
+        this.currentSamplerUnit = unit;
+      }
+    }
+    const m = this.viewMatrix;
+    const vec0 = V_ARRAY[0].set(x, y);
+    const vec1 = V_ARRAY[1].set(x + w, y);
+    const vec2 = V_ARRAY[2].set(x, y + h);
+    const vec3 = V_ARRAY[3].set(x + w, y + h);
+    if (!m.isIdentity()) {
+      m.apply(vec0);
+      m.apply(vec1);
+      m.apply(vec2);
+      m.apply(vec3);
+    }
+    const textureId = this.useMultiTexture ? unit : 0;
+    vertexData.push(vec0.x, vec0.y, u0, v0, tint, textureId);
+    vertexData.push(vec1.x, vec1.y, u1, v0, tint, textureId);
+    vertexData.push(vec2.x, vec2.y, u0, v1, tint, textureId);
+    vertexData.push(vec3.x, vec3.y, u1, v1, tint, textureId);
+  }
+};
+
+// src/video/webgl/batchers/lit_quad_batcher.js
+var LitQuadBatcher = class extends QuadBatcher {
+  /**
+   * @ignore
+   */
+  init(renderer2) {
+    const halved = Math.min(
+      Math.max(1, Math.floor(renderer2.maxTextures / 2)),
+      16
+    );
+    this.maxBatchTextures = halved;
+    Object.getPrototypeOf(QuadBatcher.prototype).init.call(this, renderer2, {
+      attributes: [
+        {
+          name: "aVertex",
+          size: 2,
+          type: renderer2.gl.FLOAT,
+          normalized: false,
+          offset: 0 * Float32Array.BYTES_PER_ELEMENT
+        },
+        {
+          name: "aRegion",
+          size: 2,
+          type: renderer2.gl.FLOAT,
+          normalized: false,
+          offset: 2 * Float32Array.BYTES_PER_ELEMENT
+        },
+        {
+          name: "aColor",
+          size: 4,
+          type: renderer2.gl.UNSIGNED_BYTE,
+          normalized: true,
+          offset: 4 * Float32Array.BYTES_PER_ELEMENT
+        },
+        {
+          name: "aTextureId",
+          size: 1,
+          type: renderer2.gl.FLOAT,
+          normalized: false,
+          offset: 5 * Float32Array.BYTES_PER_ELEMENT
+        },
+        {
+          name: "aNormalTextureId",
+          size: 1,
+          type: renderer2.gl.FLOAT,
+          normalized: false,
+          offset: 6 * Float32Array.BYTES_PER_ELEMENT
+        }
+      ],
+      shader: {
+        vertex: quad_multi_lit_default,
+        fragment: buildLitMultiTextureFragment(halved)
+      }
+    });
+    this.bindColorSamplers();
+    this.bindNormalSamplers();
+    this.createIndexBuffer();
+    this.useMultiTexture = true;
+    this.boundNormalMaps = new Array(halved).fill(null);
+    this.normalMapTextures = /* @__PURE__ */ new Map();
+    this._lightCount = 0;
+    this._maxLights = MAX_LIGHTS;
+    this.defaultShader.setUniform("uLightCount", 0);
+    this.defaultShader.setUniform("uAmbient", [0, 0, 0]);
+  }
+  /**
+   * Bind the paired normal sampler uniforms (`uNormalSampler0..N-1`)
+   * to texture units `maxBatchTextures..2*maxBatchTextures-1`. Called
+   * from `init` and `reset`.
+   * @ignore
+   */
+  bindNormalSamplers() {
+    for (let i = 0; i < this.maxBatchTextures; i++) {
+      this.defaultShader.setUniform(
+        "uNormalSampler" + i,
+        this.maxBatchTextures + i
+      );
+    }
+  }
+  /**
+   * @ignore
+   */
+  reset() {
+    super.reset();
+    this.bindNormalSamplers();
+    this.boundNormalMaps.fill(null);
+    this.normalMapTextures.clear();
+    this._lightCount = 0;
+    this.defaultShader.setUniform("uLightCount", 0);
+    this.defaultShader.setUniform("uAmbient", [0, 0, 0]);
+  }
+  /**
+   * Upload per-frame Light2d uniforms used by the lit fragment path.
+   * Called once per camera per frame (before the world tree walk).
+   * Lights past `MAX_LIGHTS` are silently ignored.
+   *
+   * Coordinates must be supplied in the same space as the renderer's
+   * pre-projection vertex coords (i.e. camera-local / FBO-local),
+   * matching `Stage.drawLighting`'s convention.
+   * @param {object} uniforms
+   * @param {Float32Array} uniforms.positions - flat array of `[x, y, radius, intensity]` per light, length = 4 * count
+   * @param {Float32Array} uniforms.colors - flat array of `[r, g, b]` per light, length = 3 * count
+   * @param {Float32Array} [uniforms.heights] - flat array of per-light height, length = MAX_LIGHTS
+   * @param {number} uniforms.count - number of lights to render (clamped to MAX_LIGHTS)
+   * @param {number[]} [uniforms.ambient] - `[r, g, b]` ambient floor (0..1 each)
+   */
+  setLightUniforms(uniforms) {
+    const shader = this.defaultShader;
+    const count = Math.min(uniforms.count | 0, this._maxLights);
+    this._lightCount = count;
+    shader.setUniform("uLightCount", count);
+    if (count > 0) {
+      shader.setUniform("uLightPos", uniforms.positions);
+      shader.setUniform("uLightColor", uniforms.colors);
+      if (uniforms.heights) {
+        shader.setUniform("uLightHeight", uniforms.heights);
+      }
+    }
+    if (uniforms.ambient) {
+      shader.setUniform("uAmbient", uniforms.ambient);
+    }
+  }
+  /**
+   * Bind a normal-map image to the given GL texture unit. Uploads on
+   * first use (via `uploadNormalMap`) and rebinds the cached
+   * `WebGLTexture` on subsequent calls. Mirrors the
+   * `bindTexture2D` / `createTexture2D` split used by `MaterialBatcher`,
+   * but for normal-map textures which live outside the color
+   * `TextureCache` (cached per-image in `normalMapTextures`).
+   * @param {HTMLImageElement|HTMLCanvasElement|OffscreenCanvas|ImageBitmap} image - normal-map source
+   * @param {number} unit - GL texture unit (already offset by `maxBatchTextures`)
+   */
+  bindNormalMap(image, unit) {
+    const cached = this.normalMapTextures.get(image);
+    if (typeof cached !== "undefined") {
+      this.bindTexture2D(cached, unit, false);
+      return;
+    }
+    this.uploadNormalMap(image, unit);
+  }
+  /**
+   * Upload a normal-map image to GL and cache the resulting `WebGLTexture`
+   * for future `bindNormalMap` calls. Not meant to be called directly —
+   * `bindNormalMap` invokes this on the first use of a given image.
+   *
+   * `premultipliedAlpha = false` — normal maps store linear-encoded
+   * surface normals; multiplying through alpha would corrupt the
+   * encoding for any non-opaque texel.
+   * @param {HTMLImageElement|HTMLCanvasElement|OffscreenCanvas|ImageBitmap} image - normal-map source
+   * @param {number} unit - GL texture unit (already offset by `maxBatchTextures`)
+   */
+  uploadNormalMap(image, unit) {
+    const gl = this.gl;
+    this.createTexture2D(
+      unit,
+      image,
+      this.renderer.settings.antiAlias ? gl.LINEAR : gl.NEAREST,
+      "no-repeat",
+      image.width,
+      image.height,
+      false,
+      void 0,
+      void 0,
+      false
+    );
+    this.normalMapTextures.set(image, this.boundTextures[unit]);
+  }
+  /**
+   * Add a textured quad with optional paired normal map.
+   * @param {TextureAtlas} texture - Source texture atlas
+   * @param {number} x - Destination x-coordinate
+   * @param {number} y - Destination y-coordinate
+   * @param {number} w - Destination width
+   * @param {number} h - Destination height
+   * @param {number} u0 - Texture UV (u0) value
+   * @param {number} v0 - Texture UV (v0) value
+   * @param {number} u1 - Texture UV (u1) value
+   * @param {number} v1 - Texture UV (v1) value
+   * @param {number} tint - tint color (UINT32 argb)
+   * @param {boolean} [reupload=false] - Force the texture to be reuploaded
+   * @param {HTMLImageElement|HTMLCanvasElement|null} [normalMap=null] - paired normal-map (SpriteIlluminator workflow)
+   */
+  addQuad(texture, x, y, w, h, u0, v0, u1, v1, tint, reupload = false, normalMap = null) {
+    const vertexData = this.vertexData;
+    if (vertexData.isFull(4)) {
+      this.flush();
+    }
+    let unit;
+    if (this.useMultiTexture) {
+      unit = this.uploadTexture(texture, w, h, reupload, false);
+      if (unit >= this.maxBatchTextures) {
+        this.flush();
+        this.renderer.cache.resetUnitAssignments();
+        this.boundNormalMaps.fill(null);
+        unit = this.uploadTexture(texture, w, h, reupload, false);
+      }
+    } else {
+      unit = this.uploadTexture(texture, w, h, reupload);
+      if (unit !== this.currentSamplerUnit) {
+        this.currentShader.setUniform("uSampler", unit);
+        this.currentSamplerUnit = unit;
+      }
+    }
+    let normalTextureId = -1;
+    if (normalMap !== null && this.useMultiTexture) {
+      const normalUnit = this.maxBatchTextures + unit;
+      const prev = this.boundNormalMaps[unit];
+      if (prev !== normalMap) {
+        if (prev !== null) {
+          this.flush();
+        }
+        this.bindNormalMap(normalMap, normalUnit);
+        this.boundNormalMaps[unit] = normalMap;
+      }
+      normalTextureId = unit;
+    }
+    const m = this.viewMatrix;
+    const vec0 = V_ARRAY[0].set(x, y);
+    const vec1 = V_ARRAY[1].set(x + w, y);
+    const vec2 = V_ARRAY[2].set(x, y + h);
+    const vec3 = V_ARRAY[3].set(x + w, y + h);
+    if (!m.isIdentity()) {
+      m.apply(vec0);
+      m.apply(vec1);
+      m.apply(vec2);
+      m.apply(vec3);
+    }
+    const textureId = this.useMultiTexture ? unit : 0;
+    vertexData.push(vec0.x, vec0.y, u0, v0, tint, textureId, normalTextureId);
+    vertexData.push(vec1.x, vec1.y, u1, v0, tint, textureId, normalTextureId);
+    vertexData.push(vec2.x, vec2.y, u0, v1, tint, textureId, normalTextureId);
+    vertexData.push(vec3.x, vec3.y, u1, v1, tint, textureId, normalTextureId);
+  }
+  /**
+   * Override `blitTexture` so the FBO blit pushes `-1` as the unlit
+   * sentinel (this batcher's vertex layout includes `aNormalTextureId`).
+   * @param {WebGLTexture} source - the raw GL texture to blit
+   * @param {number} x - destination x
+   * @param {number} y - destination y
+   * @param {number} width - destination width
+   * @param {number} height - destination height
+   * @param {GLShader|ShaderEffect} shader - the shader effect to apply
+   */
+  blitTexture(source, x, y, width, height, shader) {
+    const gl = this.gl;
+    this.useShader(shader);
+    gl.activeTexture(gl.TEXTURE0);
+    gl.bindTexture(gl.TEXTURE_2D, source);
+    this.currentTextureUnit = 0;
+    this.boundTextures[0] = source;
+    shader.setUniform("uSampler", 0);
+    const m = this.viewMatrix;
+    const vec0 = V_ARRAY[0].set(x, y);
+    const vec1 = V_ARRAY[1].set(x + width, y);
+    const vec2 = V_ARRAY[2].set(x, y + height);
+    const vec3 = V_ARRAY[3].set(x + width, y + height);
+    if (m && !m.isIdentity()) {
+      m.apply(vec0);
+      m.apply(vec1);
+      m.apply(vec2);
+      m.apply(vec3);
+    }
+    const tint = 4294967295;
+    this.vertexData.push(vec0.x, vec0.y, 0, 1, tint, 0, -1);
+    this.vertexData.push(vec1.x, vec1.y, 1, 1, tint, 0, -1);
+    this.vertexData.push(vec2.x, vec2.y, 0, 0, tint, 0, -1);
+    this.vertexData.push(vec3.x, vec3.y, 1, 0, tint, 0, -1);
+    this.flush();
+    gl.activeTexture(gl.TEXTURE0);
+    gl.bindTexture(gl.TEXTURE_2D, null);
+    this.currentTextureUnit = -1;
+    delete this.boundTextures[0];
+    this.useShader(this.defaultShader);
+  }
+};
+
+// src/video/webgl/shaders/mesh.frag
+var mesh_default = "uniform sampler2D uSampler;\nvarying vec4 vColor;\nvarying vec2 vRegion;\n\nvoid main(void) {\n    gl_FragColor = texture2D(uSampler, vRegion) * vColor;\n}\n";
+
+// src/video/webgl/shaders/mesh.vert
+var mesh_default2 = "// Current vertex point (3D position for mesh rendering)\nattribute vec3 aVertex;\nattribute vec2 aRegion;\nattribute vec4 aColor;\n\n// Projection matrix\nuniform mat4 uProjectionMatrix;\n\nvarying vec2 vRegion;\nvarying vec4 vColor;\n\nvoid main(void) {\n    // Transform the vertex position by the projection matrix\n    gl_Position = uProjectionMatrix * vec4(aVertex, 1.0);\n    // Pass the remaining attributes to the fragment shader\n    vColor = vec4(aColor.bgr * aColor.a, aColor.a);\n    vRegion = aRegion;\n}\n";
+
 // src/video/webgl/batchers/mesh_batcher.js
 var _v = new Vector2d();
 var MeshBatcher = class extends MaterialBatcher {
@@ -30940,241 +31993,122 @@ var PrimitiveBatcher = class extends Batcher {
   }
 };
 
-// src/video/webgl/shaders/multitexture.js
-function buildMultiTextureFragment(maxTextures) {
-  const count = Math.max(maxTextures, 1);
-  const lines = [];
-  for (let i = 0; i < count; i++) {
-    lines.push("uniform sampler2D uSampler" + i + ";");
-  }
-  lines.push("varying vec4 vColor;");
-  lines.push("varying vec2 vRegion;");
-  lines.push("varying float vTextureId;");
-  lines.push("");
-  lines.push("void main(void) {");
-  lines.push("    vec4 color;");
-  for (let i = 0; i < count; i++) {
-    if (i === 0) {
-      lines.push("    if (vTextureId < 0.5) {");
-    } else {
-      lines.push("    } else if (vTextureId < " + (i + 0.5) + ") {");
-    }
-    lines.push("        color = texture2D(uSampler" + i + ", vRegion);");
-  }
-  lines.push("    } else {");
-  lines.push("        color = texture2D(uSampler0, vRegion);");
-  lines.push("    }");
-  lines.push("    gl_FragColor = color * vColor;");
-  lines.push("}");
-  return lines.join("\n");
-}
-
-// src/video/webgl/shaders/quad-multi.vert
-var quad_multi_default = "// Current vertex point\nattribute vec2 aVertex;\nattribute vec2 aRegion;\nattribute vec4 aColor;\nattribute float aTextureId;\n\n// Projection matrix\nuniform mat4 uProjectionMatrix;\n\nvarying vec2 vRegion;\nvarying vec4 vColor;\nvarying float vTextureId;\n\nvoid main(void) {\n    // Transform the vertex position by the projection matrix\n    gl_Position = uProjectionMatrix * vec4(aVertex, 0.0, 1.0);\n    // Pass the remaining attributes to the fragment shader\n    vColor = vec4(aColor.bgr * aColor.a, aColor.a);\n    vRegion = aRegion;\n    vTextureId = aTextureId;\n}\n";
-
-// src/video/webgl/batchers/quad_batcher.js
-var V_ARRAY = [
-  new Vector2d(),
-  new Vector2d(),
-  new Vector2d(),
-  new Vector2d()
-];
-var QuadBatcher = class extends MaterialBatcher {
+// src/video/webgl/effects/radialGradient.js
+var RadialGradientEffect = class extends ShaderEffect {
   /**
-   * Initialize the compositor
-   * @ignore
+   * @param {WebGLRenderer} renderer - the current renderer instance
+   * @param {object} [options] - initial uniform values
+   * @param {Color} [options.color] - center color (0..255 RGB); defaults to white
+   * @param {number} [options.intensity=1] - peak alpha at the center (0..1+)
    */
-  init(renderer2) {
-    this.maxBatchTextures = Math.min(renderer2.maxTextures, 16);
-    super.init(renderer2, {
-      attributes: [
-        {
-          name: "aVertex",
-          size: 2,
-          type: renderer2.gl.FLOAT,
-          normalized: false,
-          offset: 0 * Float32Array.BYTES_PER_ELEMENT
-        },
-        {
-          name: "aRegion",
-          size: 2,
-          type: renderer2.gl.FLOAT,
-          normalized: false,
-          offset: 2 * Float32Array.BYTES_PER_ELEMENT
-        },
-        {
-          name: "aColor",
-          size: 4,
-          type: renderer2.gl.UNSIGNED_BYTE,
-          normalized: true,
-          offset: 4 * Float32Array.BYTES_PER_ELEMENT
-        },
-        {
-          name: "aTextureId",
-          size: 1,
-          type: renderer2.gl.FLOAT,
-          normalized: false,
-          offset: 5 * Float32Array.BYTES_PER_ELEMENT
-        }
-      ],
-      shader: {
-        vertex: quad_multi_default,
-        fragment: buildMultiTextureFragment(this.maxBatchTextures)
-      }
-    });
-    for (let i = 0; i < this.maxBatchTextures; i++) {
-      this.defaultShader.setUniform("uSampler" + i, i);
-    }
-    this.useMultiTexture = true;
-    const maxQuads = this.vertexData.maxVertex / 4;
-    this.indexBuffer = new WebGLIndexBuffer(
-      this.gl,
-      maxQuads * 6,
-      this.renderer.WebGLVersion > 1
-    );
-    this.indexBuffer.fillQuadPattern(maxQuads);
-  }
-  /**
-   * Select the shader to use for compositing.
-   * Multi-texture batching is automatically enabled when the default
-   * shader is active, and disabled for custom ShaderEffect shaders.
-   * @see GLShader
-   * @see ShaderEffect
-   * @param {GLShader|ShaderEffect} shader - a reference to a GLShader or ShaderEffect instance
-   */
-  useShader(shader) {
-    super.useShader(shader);
-    this.useMultiTexture = shader === this.defaultShader;
-  }
-  /**
-   * Reset compositor internal state
-   * @ignore
-   */
-  reset() {
-    super.reset();
-    const maxQuads = this.vertexData.maxVertex / 4;
-    this.indexBuffer = new WebGLIndexBuffer(
-      this.gl,
-      maxQuads * 6,
-      this.renderer.WebGLVersion > 1
+  constructor(renderer2, options = {}) {
+    super(
+      renderer2,
+      `
+			uniform vec3 uColor;
+			uniform float uIntensity;
+			vec4 apply(vec4 color, vec2 uv) {
+				// recenter to [-1, 1] across the quad. The quad's own aspect
+				// ratio handles elliptical falloffs naturally \u2014 length(c) == 1
+				// lies on the inscribed ellipse in world space.
+				vec2 c = uv * 2.0 - 1.0;
+				float d = length(c);
+				// linear ramp matches Canvas createRadialGradient's two-stop output
+				float f = clamp(1.0 - d, 0.0, 1.0);
+				// 'color' is the per-vertex tint, already premultiplied by
+				// alpha in the vertex shader (vColor = vec4(aColor.bgr *
+				// aColor.a, aColor.a)). For standalone use the tint is
+				// (1,1,1,1) and the uniforms drive the look; for the Light2d
+				// batching path the uniforms stay at default and the tint
+				// carries the per-light color + intensity.
+				vec3 rgb = color.rgb * uColor * uIntensity * f;
+				float a = color.a * uIntensity * f;
+				return vec4(rgb, a);
+			}
+			`
     );
-    this.indexBuffer.fillQuadPattern(maxQuads);
-    for (let i = 0; i < this.maxBatchTextures; i++) {
-      this.defaultShader.setUniform("uSampler" + i, i);
+    this._colorBuf = new Float32Array(3);
+    const color = options.color;
+    if (color) {
+      this.setColor(color);
+    } else {
+      this._colorBuf[0] = 1;
+      this._colorBuf[1] = 1;
+      this._colorBuf[2] = 1;
+      this.setUniform("uColor", this._colorBuf);
     }
-    this.useMultiTexture = true;
+    this.setIntensity(options.intensity ?? 1);
   }
   /**
-   * Flush batched texture data to the GPU using indexed drawing.
-   * @param {number} [mode=gl.TRIANGLES] - the GL drawing mode
+   * Set the center color. RGB only — alpha is ignored (the radial
+   * falloff supplies the per-pixel alpha).
+   * @param {Color} color - 0..255 RGB color
    */
-  flush(mode = this.mode) {
-    const vertex = this.vertexData;
-    const vertexCount = vertex.vertexCount;
-    if (vertexCount > 0) {
-      const gl = this.gl;
-      const vertexSize = vertex.vertexSize;
-      this.indexBuffer.bind();
-      if (this.renderer.WebGLVersion > 1) {
-        gl.bufferData(
-          gl.ARRAY_BUFFER,
-          vertex.toFloat32(),
-          gl.STREAM_DRAW,
-          0,
-          vertexCount * vertexSize
-        );
-      } else {
-        gl.bufferData(
-          gl.ARRAY_BUFFER,
-          vertex.toFloat32(0, vertexCount * vertexSize),
-          gl.STREAM_DRAW
-        );
-      }
-      const indexCount = vertexCount / 4 * 6;
-      gl.drawElements(mode, indexCount, this.indexBuffer.type, 0);
-      vertex.clear();
-    }
+  setColor(color) {
+    this._colorBuf[0] = color.r / 255;
+    this._colorBuf[1] = color.g / 255;
+    this._colorBuf[2] = color.b / 255;
+    this.setUniform("uColor", this._colorBuf);
   }
   /**
-   * Draw a screen-aligned quad with the given raw WebGL texture through the given shader.
-   * Binds the texture to unit 0, pushes 4 vertices (Y-flipped UVs), flushes,
-   * then unbinds the texture.
-   * @param {WebGLTexture} source - the raw GL texture to blit
-   * @param {number} x - destination x
-   * @param {number} y - destination y
-   * @param {number} width - destination width
-   * @param {number} height - destination height
-   * @param {GLShader|ShaderEffect} shader - the shader effect to apply
+   * Set the peak intensity. Acts as a brightness multiplier on the
+   * falloff curve; values above 1 over-saturate the center of the gradient.
+   * @param {number} intensity - 0..1+ multiplier
    */
-  blitTexture(source, x, y, width, height, shader) {
-    const gl = this.gl;
-    this.useShader(shader);
-    gl.activeTexture(gl.TEXTURE0);
-    gl.bindTexture(gl.TEXTURE_2D, source);
-    shader.setUniform("uSampler", 0);
-    const tint = 4294967295;
-    this.vertexData.push(x, y, 0, 1, tint, 0);
-    this.vertexData.push(x + width, y, 1, 1, tint, 0);
-    this.vertexData.push(x, y + height, 0, 0, tint, 0);
-    this.vertexData.push(x + width, y + height, 1, 0, tint, 0);
-    this.flush();
-    gl.activeTexture(gl.TEXTURE0);
-    gl.bindTexture(gl.TEXTURE_2D, null);
-    delete this.boundTextures[0];
-    this.useShader(this.defaultShader);
+  setIntensity(intensity) {
+    this.setUniform("uIntensity", intensity);
   }
-  /**
-   * Add a textured quad
-   * @param {TextureAtlas} texture - Source texture atlas
-   * @param {number} x - Destination x-coordinate
-   * @param {number} y - Destination y-coordinate
-   * @param {number} w - Destination width
-   * @param {number} h - Destination height
-   * @param {number} u0 - Texture UV (u0) value.
-   * @param {number} v0 - Texture UV (v0) value.
-   * @param {number} u1 - Texture UV (u1) value.
-   * @param {number} v1 - Texture UV (v1) value.
-   * @param {number} tint - tint color to be applied to the texture in UINT32 (argb) format
-   * @param {boolean} reupload - Force the texture to be reuploaded even if already bound
-   */
-  addQuad(texture, x, y, w, h, u0, v0, u1, v1, tint, reupload = false) {
-    const vertexData = this.vertexData;
-    if (vertexData.isFull(4)) {
-      this.flush();
-    }
-    let unit;
-    if (this.useMultiTexture) {
-      unit = this.uploadTexture(texture, w, h, reupload, false);
-      if (unit >= this.maxBatchTextures) {
-        this.flush();
-        this.renderer.cache.resetUnitAssignments();
-        unit = this.uploadTexture(texture, w, h, reupload, false);
-      }
-    } else {
-      unit = this.uploadTexture(texture, w, h, reupload);
-      if (unit !== this.currentSamplerUnit) {
-        this.currentShader.setUniform("uSampler", unit);
-        this.currentSamplerUnit = unit;
+};
+
+// src/video/webgl/lighting/pack.ts
+function createLightUniformScratch() {
+  return {
+    positions: new Float32Array(MAX_LIGHTS * 4),
+    colors: new Float32Array(MAX_LIGHTS * 3),
+    heights: new Float32Array(MAX_LIGHTS),
+    ambient: [0, 0, 0]
+  };
+}
+function packLights(lights, ambient, translateX, translateY, scratch) {
+  scratch.positions.fill(0);
+  scratch.colors.fill(0);
+  scratch.heights.fill(0);
+  let i = 0;
+  if (lights) {
+    for (const light of lights) {
+      if (i >= MAX_LIGHTS) {
+        break;
       }
+      const b = light.getBounds();
+      const radius = Math.max(b.width, b.height) / 2;
+      scratch.positions[i * 4 + 0] = b.centerX - translateX;
+      scratch.positions[i * 4 + 1] = b.centerY - translateY;
+      scratch.positions[i * 4 + 2] = radius;
+      scratch.positions[i * 4 + 3] = light.intensity;
+      scratch.colors[i * 3 + 0] = light.color.r / 255;
+      scratch.colors[i * 3 + 1] = light.color.g / 255;
+      scratch.colors[i * 3 + 2] = light.color.b / 255;
+      scratch.heights[i] = light.lightHeight;
+      i++;
     }
-    const m = this.viewMatrix;
-    const vec0 = V_ARRAY[0].set(x, y);
-    const vec1 = V_ARRAY[1].set(x + w, y);
-    const vec2 = V_ARRAY[2].set(x, y + h);
-    const vec3 = V_ARRAY[3].set(x + w, y + h);
-    if (!m.isIdentity()) {
-      m.apply(vec0);
-      m.apply(vec1);
-      m.apply(vec2);
-      m.apply(vec3);
-    }
-    const textureId = this.useMultiTexture ? unit : 0;
-    vertexData.push(vec0.x, vec0.y, u0, v0, tint, textureId);
-    vertexData.push(vec1.x, vec1.y, u1, v0, tint, textureId);
-    vertexData.push(vec2.x, vec2.y, u0, v1, tint, textureId);
-    vertexData.push(vec3.x, vec3.y, u1, v1, tint, textureId);
   }
-};
+  if (ambient) {
+    scratch.ambient[0] = ambient.r / 255;
+    scratch.ambient[1] = ambient.g / 255;
+    scratch.ambient[2] = ambient.b / 255;
+  } else {
+    scratch.ambient[0] = 0;
+    scratch.ambient[1] = 0;
+    scratch.ambient[2] = 0;
+  }
+  return {
+    positions: scratch.positions,
+    colors: scratch.colors,
+    heights: scratch.heights,
+    ambient: scratch.ambient,
+    count: i
+  };
+}
 
 // src/video/webgl/webgl_renderer.js
 var _tempMatrix = new Matrix3d();
@@ -31205,6 +32139,7 @@ var WebGLRenderer = class extends Renderer {
     this._rectTriangles = Array.from({ length: 6 }, () => {
       return { x: 0, y: 0 };
     });
+    this._clipAABB = new Bounds();
     this._polyVerts = [];
     this._currentGradient = null;
     this.currentTransform = this.renderState.currentTransform;
@@ -31214,6 +32149,9 @@ var WebGLRenderer = class extends Renderer {
     this.gl.bindBuffer(this.gl.ARRAY_BUFFER, this.vertexBuffer);
     const CustomBatcher = this.settings.batcher || this.settings.compositor;
     this.addBatcher(new (CustomBatcher || QuadBatcher)(this), "quad", true);
+    if (!CustomBatcher) {
+      this.addBatcher(new LitQuadBatcher(this), "litQuad");
+    }
     this.addBatcher(new (CustomBatcher || PrimitiveBatcher)(this), "primitive");
     this.addBatcher(new MeshBatcher(this), "mesh");
     this.gl.disable(this.gl.DEPTH_TEST);
@@ -31332,6 +32270,16 @@ var WebGLRenderer = class extends Renderer {
     this.gl.disable(this.gl.SCISSOR_TEST);
     this._scissorActive = false;
     this._renderTargetPool.destroy();
+    if (this._lightShader !== void 0) {
+      this._lightShader.destroy?.();
+      this._lightShader = void 0;
+    }
+    if (this._lightAtlas !== void 0) {
+      this._lightAtlas.sources.forEach((source) => {
+        this.cache.delete?.(source);
+      });
+      this._lightAtlas = void 0;
+    }
   }
   /**
    * add a new batcher to this renderer
@@ -31359,21 +32307,21 @@ var WebGLRenderer = class extends Renderer {
     if (typeof batcher === "undefined") {
       throw new Error("Invalid Batcher");
     }
-    if (this.currentBatcher === batcher && typeof shader !== "object") {
+    const targetShader = shader != null ? shader : batcher.defaultShader;
+    if (this.currentBatcher === batcher && batcher.currentShader === targetShader) {
       return this.currentBatcher;
     }
     if (this.currentBatcher !== batcher) {
       if (this.currentBatcher !== void 0) {
         this.currentBatcher.flush();
+        this.currentBatcher.unbind();
       }
       this.gl.bindBuffer(this.gl.ARRAY_BUFFER, this.vertexBuffer);
       this.currentBatcher = batcher;
       this.currentBatcher.bind();
       this.currentBatcher.setProjection(this.projectionMatrix);
     }
-    if (typeof shader === "object") {
-      this.currentBatcher.useShader(shader);
-    }
+    this.currentBatcher.useShader(targetShader);
     return this.currentBatcher;
   }
   /**
@@ -31418,6 +32366,109 @@ var WebGLRenderer = class extends Renderer {
   flush() {
     this.currentBatcher.flush();
   }
+  /**
+   * Upload per-frame Light2d uniforms used by the lit sprite pipeline.
+   *
+   * Packs the active lights into pre-allocated scratch buffers, then
+   * forwards to `LitQuadBatcher`. Light positions are translated from
+   * world-space (where `light.getBounds().centerX/Y` lives) into the
+   * renderer's pre-projection coords by subtracting `(translateX, translateY)`,
+   * matching what `Stage.drawLighting` does for the cutout pass — so
+   * the lit fragment's `lightPos - vWorldPos` math lines up with the
+   * camera's view.
+   *
+   * Lights past `MAX_LIGHTS` (8) are silently dropped. Also caches the
+   * active light count on the renderer so `drawImage` can dispatch
+   * normal-mapped sprites to the lit batcher only when there's
+   * something to light them with.
+   * @param {Iterable<object>} [lights] - active `Light2d` instances; falsy/empty no-ops the lit pipeline
+   * @param {object} [ambient] - ambient lighting color (0..255 RGB); defaults to black
+   * @param {number} [translateX=0] - world-to-screen X translate (matches `Camera2d.draw()`)
+   * @param {number} [translateY=0] - world-to-screen Y translate
+   */
+  setLightUniforms(lights, ambient, translateX = 0, translateY = 0) {
+    if (this._lightUniformsScratch === void 0) {
+      this._lightUniformsScratch = createLightUniformScratch();
+    }
+    const u = packLights(
+      lights,
+      ambient,
+      translateX,
+      translateY,
+      this._lightUniformsScratch
+    );
+    this.activeLightCount = u.count;
+    const lit = this.batchers.get("litQuad");
+    if (lit && typeof lit.setLightUniforms === "function") {
+      lit.setLightUniforms(u);
+      if (this.currentBatcher && this.currentBatcher !== lit) {
+        const shader = this.currentBatcher.currentShader || this.currentBatcher.defaultShader;
+        if (shader) {
+          this.gl.useProgram(shader.program);
+          this.currentProgram = shader.program;
+        }
+      }
+    }
+  }
+  /**
+   * @inheritdoc
+   *
+   * Renders the light as a quad through a shared
+   * {@link RadialGradientEffect} fragment shader (procedural — no
+   * per-light texture). The shader and a shared 1×1 white-pixel atlas
+   * are lazy-allocated on first call and reused for every Light2d on
+   * this renderer. Each light's color and intensity are encoded into
+   * the per-vertex tint so consecutive `drawLight` calls accumulate
+   * into the quad batcher's buffer and flush together — N lights
+   * become 1 program switch + 1 flush instead of 2N + N.
+   * @param {object} light - the Light2d instance to render
+   */
+  drawLight(light) {
+    if (this._lightShader === void 0) {
+      this._lightShader = new RadialGradientEffect(this);
+    }
+    const batcher = this.setBatcher("quad", this._lightShader);
+    batcher.addQuad(
+      this._getLightAtlas(),
+      light.pos.x,
+      light.pos.y,
+      light.width,
+      light.height,
+      0,
+      0,
+      1,
+      1,
+      // pack the light's color (RGB) and intensity (A) into the
+      // vertex tint — the shader's `apply()` reads `color.rgb` and
+      // `color.a` as the per-light values.
+      light.color.toUint32(light.intensity)
+    );
+  }
+  /**
+   * Lazy-init a shared 1×1 white `TextureAtlas` used as the source
+   * texture for `drawLight`'s procedural shader. The shader ignores
+   * the sampled color, but `addQuad`'s vertex format includes a
+   * texture-unit attribute so we still need a real texture; sharing
+   * one across every light keeps them on the same multi-texture slot
+   * (no flush on light switch).
+   * @returns {TextureAtlas}
+   * @ignore
+   */
+  _getLightAtlas() {
+    if (this._lightAtlas === void 0) {
+      const canvas = globalThis.document ? globalThis.document.createElement("canvas") : new OffscreenCanvas(1, 1);
+      canvas.width = 1;
+      canvas.height = 1;
+      const ctx = canvas.getContext("2d");
+      ctx.fillStyle = "#fff";
+      ctx.fillRect(0, 0, 1, 1);
+      this._lightAtlas = new TextureAtlas(
+        createAtlas(1, 1, "lightWhite", "no-repeat"),
+        canvas
+      );
+    }
+    return this._lightAtlas;
+  }
   /**
    * Begin capturing rendering to an offscreen FBO for post-effect processing.
    * @param {Renderable} renderable - the renderable requesting post-effect processing
@@ -31602,19 +32653,22 @@ var WebGLRenderer = class extends Renderer {
    */
   enableScissor(x, y, width, height) {
     const gl = this.gl;
+    const canvas = this.getCanvas();
+    const aabb = this._clipAABB;
+    aabb.clear();
+    aabb.addFrame(x, y, x + width, y + height, this.currentTransform);
+    const sx = Math.floor(aabb.min.x);
+    const sy = Math.floor(aabb.min.y);
+    const sw = Math.ceil(aabb.max.x - sx);
+    const sh = Math.ceil(aabb.max.y - sy);
     this.flush();
     gl.enable(gl.SCISSOR_TEST);
     this._scissorActive = true;
-    gl.scissor(
-      x + this.currentTransform.tx,
-      this.getCanvas().height - height - y - this.currentTransform.ty,
-      width,
-      height
-    );
-    this.currentScissor[0] = x;
-    this.currentScissor[1] = y;
-    this.currentScissor[2] = width;
-    this.currentScissor[3] = height;
+    gl.scissor(sx, canvas.height - sh - sy, sw, sh);
+    this.currentScissor[0] = sx;
+    this.currentScissor[1] = sy;
+    this.currentScissor[2] = sw;
+    this.currentScissor[3] = sh;
   }
   /**
    * Disable the scissor test, allowing rendering to the full viewport.
@@ -31721,27 +32775,45 @@ var WebGLRenderer = class extends Renderer {
       dx |= 0;
       dy |= 0;
     }
-    this.setBatcher("quad");
+    const useLit = this.batchers.has("litQuad") && this.activeLightCount > 0 && this.currentNormalMap !== null;
+    this.setBatcher(useLit ? "litQuad" : "quad");
     const shader = this.customShader;
-    if (typeof shader === "object") {
+    if (shader != null) {
       this.currentBatcher.useShader(shader);
     }
     const reupload = typeof image.videoWidth !== "undefined";
     const texture = this.cache.get(image);
     const uvs = texture.getUVs(sx, sy, sw, sh);
-    this.currentBatcher.addQuad(
-      texture,
-      dx,
-      dy,
-      dw,
-      dh,
-      uvs[0],
-      uvs[1],
-      uvs[2],
-      uvs[3],
-      this.currentTint.toUint32(this.getGlobalAlpha()),
-      reupload
-    );
+    if (useLit) {
+      this.currentBatcher.addQuad(
+        texture,
+        dx,
+        dy,
+        dw,
+        dh,
+        uvs[0],
+        uvs[1],
+        uvs[2],
+        uvs[3],
+        this.currentTint.toUint32(this.getGlobalAlpha()),
+        reupload,
+        this.currentNormalMap
+      );
+    } else {
+      this.currentBatcher.addQuad(
+        texture,
+        dx,
+        dy,
+        dw,
+        dh,
+        uvs[0],
+        uvs[1],
+        uvs[2],
+        uvs[3],
+        this.currentTint.toUint32(this.getGlobalAlpha()),
+        reupload
+      );
+    }
     if (typeof shader === "object") {
       this.currentBatcher.useShader(this.currentBatcher.defaultShader);
     }
@@ -31781,7 +32853,7 @@ var WebGLRenderer = class extends Renderer {
   drawMesh(mesh) {
     const gl = this.gl;
     this.setBatcher("mesh");
-    if (typeof this.customShader === "object") {
+    if (this.customShader != null) {
       this.currentBatcher.useShader(this.customShader);
     }
     gl.enable(gl.DEPTH_TEST);
@@ -31806,7 +32878,7 @@ var WebGLRenderer = class extends Renderer {
     gl.enable(gl.BLEND);
     gl.disable(gl.DEPTH_TEST);
     gl.depthMask(false);
-    if (typeof this.customShader === "object") {
+    if (this.customShader != null) {
       this.currentBatcher.useShader(this.currentBatcher.defaultShader);
     }
   }
@@ -32041,23 +33113,33 @@ var WebGLRenderer = class extends Renderer {
    */
   restore() {
     const canvas = this.getCanvas();
+    const peek = this.renderState.peekScissor();
+    const cur = this.currentScissor;
+    const curActive = this._scissorActive === true;
+    const willBeActive = peek !== null;
+    const scissorChanging = curActive !== willBeActive || willBeActive && (cur[0] !== peek[0] || cur[1] !== peek[1] || cur[2] !== peek[2] || cur[3] !== peek[3]);
+    if (scissorChanging) {
+      this.flush();
+    }
     const result = this.renderState.restore(canvas.width, canvas.height);
     if (result !== null) {
       this.setBlendMode(result.blendMode);
-      if (result.scissorActive) {
+      if (scissorChanging) {
         const gl = this.gl;
-        const s = this.currentScissor;
-        gl.enable(gl.SCISSOR_TEST);
-        this._scissorActive = true;
-        gl.scissor(
-          s[0] + this.currentTransform.tx,
-          canvas.height - s[3] - s[1] - this.currentTransform.ty,
-          s[2],
-          s[3]
-        );
-      } else {
-        this.gl.disable(this.gl.SCISSOR_TEST);
-        this._scissorActive = false;
+        if (result.scissorActive) {
+          const next = this.currentScissor;
+          gl.enable(gl.SCISSOR_TEST);
+          this._scissorActive = true;
+          gl.scissor(
+            next[0],
+            canvas.height - next[3] - next[1],
+            next[2],
+            next[3]
+          );
+        } else {
+          gl.disable(gl.SCISSOR_TEST);
+          this._scissorActive = false;
+        }
       }
     }
     this._currentGradient = this.renderState.currentGradient;
@@ -32726,31 +33808,42 @@ var WebGLRenderer = class extends Renderer {
   clipRect(x, y, width, height) {
     const canvas = this.getCanvas();
     const gl = this.gl;
-    if (x !== 0 || y !== 0 || width !== canvas.width || height !== canvas.height) {
-      const currentScissor = this.currentScissor;
+    const m = this.currentTransform;
+    if (!Number.isFinite(m.tx) || !Number.isFinite(m.ty)) {
       if (this._scissorActive) {
-        if (currentScissor[0] === x && currentScissor[1] === y && currentScissor[2] === width && currentScissor[3] === height) {
-          return;
-        }
+        this.flush();
+        gl.disable(gl.SCISSOR_TEST);
+        this._scissorActive = false;
       }
-      this.flush();
-      gl.enable(this.gl.SCISSOR_TEST);
-      this._scissorActive = true;
-      gl.scissor(
-        // scissor does not account for currentTransform, so manually adjust
-        x + this.currentTransform.tx,
-        canvas.height - height - y - this.currentTransform.ty,
-        width,
-        height
-      );
-      currentScissor[0] = x;
-      currentScissor[1] = y;
-      currentScissor[2] = width;
-      currentScissor[3] = height;
-    } else {
-      gl.disable(gl.SCISSOR_TEST);
-      this._scissorActive = false;
+      return;
+    }
+    const aabb = this._clipAABB;
+    aabb.clear();
+    aabb.addFrame(x, y, x + width, y + height, m);
+    const sx = Math.floor(aabb.min.x);
+    const sy = Math.floor(aabb.min.y);
+    const sw = Math.ceil(aabb.max.x - sx);
+    const sh = Math.ceil(aabb.max.y - sy);
+    if (sx <= 0 && sy <= 0 && sx + sw >= canvas.width && sy + sh >= canvas.height) {
+      if (this._scissorActive) {
+        this.flush();
+        gl.disable(gl.SCISSOR_TEST);
+        this._scissorActive = false;
+      }
+      return;
+    }
+    const cs = this.currentScissor;
+    if (this._scissorActive && cs[0] === sx && cs[1] === sy && cs[2] === sw && cs[3] === sh) {
+      return;
     }
+    this.flush();
+    gl.enable(gl.SCISSOR_TEST);
+    this._scissorActive = true;
+    gl.scissor(sx, canvas.height - sh - sy, sw, sh);
+    cs[0] = sx;
+    cs[1] = sy;
+    cs[2] = sw;
+    cs[3] = sh;
   }
   /**
    * A mask limits rendering elements to the shape and position of the given mask object.
@@ -32769,15 +33862,16 @@ var WebGLRenderer = class extends Renderer {
     }
     this.maskLevel++;
     gl.colorMask(false, false, false, false);
-    gl.stencilFunc(gl.EQUAL, this.maskLevel, 1);
-    gl.stencilOp(gl.REPLACE, gl.REPLACE, gl.REPLACE);
+    gl.stencilMask(255);
+    gl.stencilFunc(gl.ALWAYS, 0, 255);
+    gl.stencilOp(gl.KEEP, gl.KEEP, gl.INCR);
     this.fill(mask);
     this.flush();
     gl.colorMask(true, true, true, true);
     if (invert === true) {
-      gl.stencilFunc(gl.EQUAL, this.maskLevel + 1, 1);
+      gl.stencilFunc(gl.EQUAL, 0, 255);
     } else {
-      gl.stencilFunc(gl.NOTEQUAL, this.maskLevel + 1, 1);
+      gl.stencilFunc(gl.EQUAL, this.maskLevel, 255);
     }
     gl.stencilOp(gl.KEEP, gl.KEEP, gl.KEEP);
   }