melonjs 20.4.0 → 20.6.0

package/build/index.js

@@ -1,5 +1,5 @@
 /*!
- * melonJS Game Engine - 20.4.0
+ * melonJS Game Engine - 20.6.0
  * http://www.melonjs.org
  * melonjs is licensed under the MIT License.
  * http://www.opensource.org/licenses/mit-license
@@ -1843,17 +1843,33 @@ var Polygon = class {
    */
   edges;
   /**
-   * a list of indices for all vertices composing this polygon
+   * a list of indices for all vertices composing this polygon, filled in by
+   * {@link Polygon#getIndices} and invalidated by {@link Polygon#recalc}.
+   *
+   * A subclass may repurpose this name for geometry of its own: a
+   * {@link Mesh} holds a GPU index buffer here, a typed array rather than a
+   * plain one. `recalc` therefore only clears the slot when it owns it —
+   * anything else reading it should check what it got.
    */
   indices;
   /**
-   * The normals here are the direction of the normal for the `n`th edge of the polygon, relative
-   * to the position of the `n`th point. If you want to draw an edge normal, you must first
-   * translate to the position of the starting point.
+   * The normals here are the direction of the normal for the `n`th EDGE of the
+   * polygon, relative to the position of the `n`th point. If you want to draw
+   * an edge normal, you must first translate to the position of the starting
+   * point.
+   *
+   * Named for the edges rather than just `normals` because a subclass may
+   * carry normals of its own with a different meaning and a different type:
+   * a {@link Mesh} holds per-VERTEX normals as a `Float32Array`, and when
+   * that shadowed this one, {@link Polygon#recalc} walked it expecting
+   * `Vector2d`s. It allocates only into empty slots, and a typed array's
+   * slots are `0` rather than `undefined` — so it took the reuse branch and
+   * threw `Cannot create property 'x' on number '0'`, breaking `recalc`,
+   * `resize` and the `width`/`height` setters on every mesh.
    * @ignore
    * @internal
    */
-  normals;
+  edgeNormals;
   /**
    * The bounding rectangle for this shape
    * @ignore
@@ -1874,7 +1890,7 @@ var Polygon = class {
     this.points = [];
     this.edges = [];
     this.indices = [];
-    this.normals = [];
+    this.edgeNormals = [];
     this._bounds = boundsPool.get();
     this.setVertices(vertices);
   }
@@ -2016,7 +2032,7 @@ var Polygon = class {
    */
   recalc() {
     const edges = this.edges;
-    const normals = this.normals;
+    const normals = this.edgeNormals;
     const indices = this.indices;
     const points = this.points;
     const len = points.length;
@@ -2047,7 +2063,9 @@ var Polygon = class {
     }
     edges.length = len;
     normals.length = len;
-    indices.length = 0;
+    if (Array.isArray(indices)) {
+      indices.length = 0;
+    }
     return this;
   }
   /**
@@ -3097,6 +3115,7 @@ var save = {
     if (hasLocalStorage) {
       localStorage.setItem("me.save", JSON.stringify(Object.keys(data)));
     }
+    return save;
   },
   /**
    * Remove a key from localStorage
@@ -4255,11 +4274,22 @@ var Gradient = class {
     return this;
   }
   /**
-   * Get or create a native CanvasGradient for use with a 2D context.
+   * Get or create a native `CanvasGradient` for use with a 2D context.
+   *
+   * This is the one to reach for when baking a gradient into your own
+   * canvas — it hands back a value for `ctx.fillStyle` and touches no
+   * shared state, so two callers cannot clobber each other.
+   *
+   * The result is cached and reused until a stop changes.
    * @param {CanvasRenderingContext2D} context - the 2D context to create the gradient on
-   * @returns {CanvasGradient}
-   * @ignore
-   * @internal
+   * @returns {CanvasGradient} a native gradient bound to that context
+   * @example
+   * // bake a gradient into a standalone canvas
+   * const c = document.createElement("canvas");
+   * c.width = 64; c.height = 64;
+   * const ctx = c.getContext("2d");
+   * ctx.fillStyle = myGradient.toCanvasGradient(ctx);
+   * ctx.fillRect(0, 0, 64, 64);
    */
   toCanvasGradient(context) {
     if (this._canvasGradient && !this._dirty) {
@@ -4297,6 +4327,10 @@ var Gradient = class {
    * which is visually equivalent (linear stop interpolation × linear
    * texture filtering). The returned `width`/`height` describe the region
    * of the canvas the caller must use as the drawImage SOURCE rect.
+   * Internal: the bake target is SHARED across every gradient and valid only
+   * until the next call, which is a renderer implementation detail rather
+   * than something a caller should reason about. The public way to rasterise
+   * a gradient is {@link Gradient#toCanvasGradient}.
    * @param {CanvasRenderer|WebGLRenderer} renderer - the active renderer (used to invalidate the GPU texture)
    * @param {number} x - draw rect x
    * @param {number} y - draw rect y
@@ -6857,6 +6891,52 @@ var Renderer = class _Renderer {
    */
   flush() {
   }
+  /**
+   * Compile the backend's built-in shader programs up front, so the first
+   * frame that draws them does not stall while the driver builds them.
+   *
+   * A GPU backend does not finish a shader when you hand it the source. It
+   * finishes it the first time something is actually drawn with it, which
+   * puts the whole cost on the frame a scene first appears — the moment a
+   * level or stage comes up and its geometry arrives a beat late. Calling
+   * this while a loading screen is still on screen moves that cost to where
+   * nobody is waiting on a frame.
+   *
+   * Resolves immediately on a backend with nothing to compile (Canvas).
+   * What "ready" means is backend-specific and worth knowing: WebGL's link
+   * blocks, so a resolved promise there means the programs are genuinely
+   * built; WebGPU's `createShaderModule` returns before its compilation
+   * finishes, so a resolved promise there means the modules have been
+   * requested and validation is under way.
+   *
+   * **You normally do not call this.** `loader.preload()` calls it for you,
+   * once the assets are in and before `LOADER_COMPLETE` fires — so it runs
+   * while the loading screen is still up — whenever the application's
+   * `prewarm` setting is on, which it is by default. Every `preload()` warms,
+   * not just the first, so a per-level preload warms whatever that level
+   * brought with it.
+   *
+   * Two consequences worth knowing:
+   *
+   * - **A game that never calls `loader.preload()` is never warmed.** There
+   *   is no other hook. Call this yourself if you load assets some other way
+   *   and still want the warm-up.
+   * - It is deliberately NOT called from `Application.init()`. That runs
+   *   before anything is on screen, so warming there would only lengthen a
+   *   blank page instead of hiding behind a progress bar.
+   * @returns {Promise<void>} settles when the built-in programs are ready
+   * @example
+   * // the usual case: nothing to write. `preload()` warms on the way through
+   * await loader.preload(resources);
+   * @example
+   * // only needed if you do not use the preloader, or want a second warm-up
+   * // at a point of your own choosing
+   * await app.renderer.prewarm();
+   * state.change(state.PLAY);
+   */
+  prewarm() {
+    return Promise.resolve();
+  }
   /**
    * Mark the start of a screen-space (`floating`) draw, during which the
    * camera's screen projection is installed and world-space geometry cannot
@@ -6956,9 +7036,18 @@ var Renderer = class _Renderer {
     entry2.shader = this.customShader ?? null;
     const v = this.currentTransform.val;
     const m = modelMatrix.val;
-    const mx = m[12];
-    const my = m[13];
-    const mz = m[14];
+    let cx = 0;
+    let cy = 0;
+    let cz = 0;
+    if (typeof mesh?._updateLocalCenter === "function") {
+      mesh._updateLocalCenter();
+      cx = mesh._lcx;
+      cy = mesh._lcy;
+      cz = mesh._lcz;
+    }
+    const mx = m[0] * cx + m[4] * cy + m[8] * cz + m[12];
+    const my = m[1] * cx + m[5] * cy + m[9] * cz + m[13];
+    const mz = m[2] * cx + m[6] * cy + m[10] * cz + m[14];
     const dx = v[0] * mx + v[4] * my + v[8] * mz + v[12];
     const dy = v[1] * mx + v[5] * my + v[9] * mz + v[13];
     const dz = v[2] * mx + v[6] * my + v[10] * mz + v[14];
@@ -7761,6 +7850,31 @@ var Renderer = class _Renderer {
           );
         }
         break;
+      // Box3d — a 3D box has no 2D outline of its own, so draw the XY
+      // FOOTPRINT it already hands every 2D consumer through its own
+      // `getBounds()` (the body bounds, the broadphase pre-gate, and
+      // this). Without a case here it fell through to the `default`
+      // below, so switching on the debug panel's hitbox overlay threw
+      // "Invalid geometry for fill/stroke" on any body carrying one.
+      case "Box3d": {
+        const footprint = shape.getBounds();
+        if (fill) {
+          this.fillRect(
+            footprint.left,
+            footprint.top,
+            footprint.width,
+            footprint.height
+          );
+        } else {
+          this.strokeRect(
+            footprint.left,
+            footprint.top,
+            footprint.width,
+            footprint.height
+          );
+        }
+        break;
+      }
       // Rect or Bounds
       case "Rectangle":
       case "Bounds":
@@ -10411,14 +10525,16 @@ var Sound = class {
             sound2._node.gain.linearRampToValueAtTime(to, end);
           }
         }
-        this._startFadeInterval(
-          sound2,
-          from,
-          to,
-          len,
-          ids[i],
-          typeof id === "undefined"
-        );
+        const isGroup = typeof id === "undefined";
+        if (!(len > 0) || to === from) {
+          if (isGroup) {
+            this._volume = to;
+          }
+          this.volume(to, ids[i]);
+          this._emit("fade", ids[i]);
+          continue;
+        }
+        this._startFadeInterval(sound2, from, to, len, ids[i], isGroup);
       }
     }
     return this;
@@ -11269,13 +11385,14 @@ function tone(opts) {
     gain = 0.1,
     attack = 5e-3,
     pan = 0,
-    pitchSlide = 1
+    pitchSlide = 1,
+    delay = 0
   } = opts;
   const freqs = Array.isArray(freq) ? freq : [freq];
   if (freqs.length === 0) return;
   _resumeIfSuspended(ctx);
   const dur = Math.max(1e-3, duration2);
-  const t0 = ctx.currentTime;
+  const t0 = ctx.currentTime + Math.max(0, delay);
   const t1 = t0 + dur;
   const env = _buildGainEnvelope(ctx, t0, t1, attack, dur, gain);
   const panner2 = _connectToOutput(ctx, env, pan, t0);
@@ -11348,11 +11465,12 @@ function noise(opts) {
     attack = 5e-3,
     pan = 0,
     filter,
-    filterSweep = 1
+    filterSweep = 1,
+    delay = 0
   } = opts;
   _resumeIfSuspended(ctx);
   const dur = Math.max(1e-3, duration2);
-  const t0 = ctx.currentTime;
+  const t0 = ctx.currentTime + Math.max(0, delay);
   const t1 = t0 + dur;
   const env = _buildGainEnvelope(ctx, t0, t1, attack, dur, gain);
   const sampleCount = Math.max(1, Math.ceil(dur * ctx.sampleRate));
@@ -13357,7 +13475,7 @@ var input_exports = {};
 __export(input_exports, {
   GAMEPAD: () => GAMEPAD,
   KEY: () => KEY,
-  _app: () => _app2,
+  _app: () => _app3,
   bindGamepad: () => bindGamepad,
   bindKey: () => bindKey,
   bindPointer: () => bindPointer,
@@ -15216,7 +15334,7 @@ var Line = class _Line extends Polygon {
    */
   recalc() {
     const edges = this.edges;
-    const normals = this.normals;
+    const normals = this.edgeNormals;
     const indices = this.indices;
     const points = this.points;
     if (points.length !== 2) {
@@ -17271,6 +17389,9 @@ var Renderable = class _Renderable extends Rect {
   }
   /**
    * get the renderable alpha channel value<br>
+   *
+   * This is the renderable's OWN value. What it finally draws at is this
+   * multiplied by every ancestor's — see {@link Renderable#alpha}.
    * @returns {number} current opacity value between 0 and 1
    */
   getOpacity() {
@@ -17668,7 +17789,10 @@ var Renderable = class _Renderable extends Rect {
     if (this.applyAnchorTransform !== false) {
       renderer.translate(-ax, -ay);
     }
-    renderer.setTint(this.tint, this.getOpacity());
+    renderer.setTint(
+      this.tint,
+      this.getOpacity() * (renderer.currentTint?.alpha ?? 1)
+    );
     renderer.setDepth(this.depth);
     if (this.blendMode !== renderer.getBlendMode()) {
       renderer.setBlendMode(this.blendMode);
@@ -18260,9 +18384,14 @@ var GLShader = class _GLShader {
   /**
    * Set the uniform to the given value
    * @param {string} name - the uniform name
-   * @param {object|Float32Array} value - the value to assign to that uniform
+   * @param {number|boolean|number[]|Float32Array|object} value - the value to assign to that
+   * uniform. Scalars (`float`, `int`, `bool`) take a number or a boolean;
+   * vectors and matrices take an array, a `Float32Array`, or any object
+   * exposing `toArray()` — which is every {@link Vector2d},
+   * {@link Vector3d}, {@link Color} and {@link Matrix3d}.
    * @example
    * myShader.setUniform("uProjectionMatrix", this.projectionMatrix);
+   * myShader.setUniform("uStrength", 0.5); // a scalar is a plain number
    */
   setUniform(name, value) {
     if (this.destroyed) {
@@ -18547,11 +18676,78 @@ function buildGLSLProgram(fragmentBody) {
   return {
     vertex: buildEffectVertex(builtins),
     fragment: fragment2,
+    // the annotation-stripped body, so a mesh-hosted effect can be
+    // spliced into the engine's own mesh shader (#1658) without
+    // re-parsing. Additive: the quad `vertex`/`fragment` above are
+    // byte-identical to what they always were.
+    body: builtins.body,
+    builtins,
     screenTextures: builtins.screenTextures,
     noiseUV: builtins.noiseUV
   };
 }
 
+// src/video/effects/mesh_splice.js
+var HOOKS = [
+  {
+    pattern: /vec4\s+ME_effect\s*\(\s*vec4\s+c\s*,\s*vec2\s+uv\s*\)\s*\{[^}]*\}/,
+    replacement: "vec4 ME_effect(vec4 c, vec2 uv) { return apply(c, uv); }"
+  },
+  {
+    pattern: /fn\s+ME_effect\s*\(\s*c\s*:\s*vec4f\s*,\s*uv\s*:\s*vec2f\s*\)\s*->\s*vec4f\s*\{[^}]*\}/,
+    replacement: "fn ME_effect(c : vec4f, uv : vec2f) -> vec4f { return apply(c, uv); }"
+  }
+];
+var MESH_UNSUPPORTED = {
+  noiseUV: "`noise_uv` (derived from a quad's image and object size)",
+  screenUV: "`screen_uv` (needs the screen capture the quad tier takes)",
+  screenTexture: "`screen_texture` (needs the screen capture)"
+};
+function meshHostingBlocker(builtins, textures, language2) {
+  if (language2 === "wgsl" && builtins?.vColor === true) {
+    return "it reads `vColor`, which only the 2D quad tier exposes to an effect body";
+  }
+  if (Array.isArray(textures) && textures.length > 0) {
+    return "it declares its own texture samplers, which a mesh-hosted effect cannot bind yet \u2014 uniforms are supported, textures are not";
+  }
+  if (typeof builtins !== "object" || builtins === null) {
+    return null;
+  }
+  const blocked = Object.keys(MESH_UNSUPPORTED).filter((flag) => {
+    return builtins[flag] === true;
+  }).map((flag) => {
+    return MESH_UNSUPPORTED[flag];
+  });
+  return blocked.length === 0 ? null : `it uses ${blocked.join(" and ")}, which only the 2D quad tier provides`;
+}
+function hasSpliceMarkers(source) {
+  return typeof source === "string" && HOOKS.some((hook) => {
+    return hook.pattern.test(source);
+  });
+}
+function spliceEffect(source, body) {
+  if (typeof source !== "string" || typeof body !== "string") {
+    return null;
+  }
+  for (const hook of HOOKS) {
+    if (hook.pattern.test(source)) {
+      return source.replace(hook.pattern, () => {
+        return `${body}
+${hook.replacement}`;
+      });
+    }
+  }
+  return null;
+}
+function shiftGroup3(body, shift) {
+  return body.replace(
+    /@group\(\s*3\s*\)\s*@binding\(\s*(\d+)\s*\)/g,
+    (_match, binding) => {
+      return `@group(3) @binding(${Number(binding) + shift})`;
+    }
+  );
+}
+
 // src/video/effects/wgsl/layout.js
 var TYPE_LAYOUT = {
   f32: { align: 4, size: 4 },
@@ -18923,6 +19119,8 @@ var WGSLEffectRealization = class {
     if (!this.valid) {
       return;
     }
+    this.body = body;
+    this.parsed = parsed;
     this.layout = parsed.layout;
     this.structSize = parsed.structSize;
     this.textures = parsed.textures;
@@ -18930,6 +19128,7 @@ var WGSLEffectRealization = class {
     const module = buildWGSLModule(body, parsed);
     this.code = module.code;
     this.builtinBindings = module.bindings;
+    this.meshModules = /* @__PURE__ */ new Map();
     this.cpu = new ArrayBuffer(Math.max(this.structSize, 0));
     this.f32 = new Float32Array(this.cpu);
     this.i32 = new Int32Array(this.cpu);
@@ -19006,9 +19205,30 @@ var WGSLEffectRealization = class {
   releaseGPU() {
     this.gpu = null;
   }
+  /**
+   * This effect realized against the MESH contract: the engine's own mesh
+   * module with the body spliced in at its `ME_effect` hook, and the
+   * body's group-3 bindings shifted up one so `uMesh` keeps binding 0.
+   *
+   * The quad module (`this.code`) is untouched — a `Sprite` still gets the
+   * exact text it always did.
+   * @param {string} meshSource - the host mesh shader's WGSL text
+   * @returns {string} the spliced module
+   * @ignore
+   * @internal
+   */
+  meshModule(meshSource) {
+    let code = this.meshModules.get(meshSource);
+    if (typeof code === "undefined") {
+      code = spliceEffect(meshSource, shiftGroup3(this.body, 1));
+      this.meshModules.set(meshSource, code);
+    }
+    return code;
+  }
 };
 
 // src/video/effects/shadereffect.js
+var _nextEffectId = 0;
 var ShaderEffect = class _ShaderEffect {
   /**
    * whether this effect is active (false in Canvas mode, false after
@@ -19065,10 +19285,14 @@ var ShaderEffect = class _ShaderEffect {
       return;
     }
     this._extraTextures = /* @__PURE__ */ new Map();
+    this._uniformValues = /* @__PURE__ */ new Map();
+    this._effectId = _nextEffectId++;
     if (language2 === "glsl") {
       const program = buildGLSLProgram(source);
       this._screenTextureUniforms = program.screenTextures;
       this._hasNoiseUV = program.noiseUV;
+      this._meshBody = program.body;
+      this._meshBuiltins = program.builtins;
       this._shader = new GLShader(
         renderer.gl,
         program.vertex,
@@ -19138,12 +19362,23 @@ var ShaderEffect = class _ShaderEffect {
   /**
    * Set the uniform to the given value
    * @param {string} name - the uniform name
-   * @param {object|Float32Array} value - the value to assign to that uniform
+   * @param {number|boolean|number[]|Float32Array|object} value - the value to assign to that
+   * uniform. Scalars (`float`, `int`, `bool`) take a number or a boolean;
+   * vectors and matrices take an array, a `Float32Array`, or any object
+   * exposing `toArray()` — which is every {@link Vector2d},
+   * {@link Vector3d}, {@link Color} and {@link Matrix3d}.
+   * @example
+   * // a scalar the body declares as `uniform float uStrength;`
+   * fx.setUniform("uStrength", 0.5);
+   * // a vec3 — an array, or anything with toArray()
+   * fx.setUniform("uTint", [1.0, 0.82, 0.55]);
+   * fx.setUniform("uOrigin", new me.Vector2d(0.5, 0.5));
    */
   setUniform(name, value) {
     if (this.destroyed === true) {
       return;
     }
+    this._uniformValues?.set(name, value);
     if (typeof this._shader !== "undefined") {
       this._shader.setUniform(name, value);
     } else if (typeof this.wgslRealization !== "undefined") {
@@ -19174,7 +19409,12 @@ var ShaderEffect = class _ShaderEffect {
    * flow.setTime(me.timer.getTime() / 1000);
    */
   setTime(seconds) {
-    if (typeof this._shader !== "undefined" && this.destroyed !== true && !this._shader.suspended && typeof this._shader.uniforms.uTime !== "undefined") {
+    if (this.destroyed !== true) {
+      this._uniformValues?.set("uTime", seconds);
+    }
+    if (typeof this._shader !== "undefined" && this.destroyed !== true && !this._shader.suspended && // optional: the map is null on a shader with no live context
+    // behind it, which `suspended` alone does not cover
+    typeof this._shader.uniforms?.uTime !== "undefined") {
       this._shader.setUniform("uTime", seconds);
     } else if (typeof this.wgslRealization !== "undefined" && this.destroyed !== true && this.wgslRealization.hasUniform("uTime")) {
       this.wgslRealization.setUniform("uTime", seconds);
@@ -19862,6 +20102,8 @@ var Camera2d = class extends Renderable {
    * @internal
    */
   _zoom;
+  /** backing store for {@link Camera2d#roll} — see the accessor */
+  _roll;
   /**
    * the world-space projection matrix for non-default cameras (offset/zoomed).
    * Maps world coordinates to the camera's screen viewport.
@@ -19954,6 +20196,7 @@ var Camera2d = class extends Renderable {
     this.screenX = 0;
     this.screenY = 0;
     this.zoom = 1;
+    this._roll = 0;
     this.worldProjection = new Matrix3d();
     this.screenProjection = new Matrix3d();
     this._worldView = new Bounds();
@@ -20029,6 +20272,48 @@ var Camera2d = class extends Renderable {
    * // zoom out to show the full level in a 180x100 minimap
    * camera.zoom = Math.min(180 / levelWidth, 100 / levelHeight);
    */
+  /**
+   * Roll this camera in the screen plane, in radians — the 2D spelling of
+   * {@link Camera3d#roll}, so a helper that banks "a camera" works on either.
+   *
+   * Absolute and idempotent: assigning the same angle twice leaves the view
+   * where it was. It is a thin accessor over the camera's own
+   * `currentTransform`, which is what {@link Renderable#rotate} writes and
+   * what `worldToLocal` / `localToWorld` already undo — so picking under a
+   * rolled 2D camera stays correct for free.
+   *
+   * A 2D camera has no pitch or yaw, so a screen-plane rotation is its only
+   * rotation; on a `Camera3d` the roll is a real view angle instead, because
+   * a 3D view is built from its three angles and never reads
+   * `currentTransform`.
+   *
+   * This OWNS the camera's `currentTransform`: the setter rebuilds it rather
+   * than composing onto it, so assigning every frame cannot drift and
+   * `roll = 0` lands back on an exact identity. (A delta-based version does
+   * neither — a banking camera would accumulate float error across thousands
+   * of frames.) The cost is that a manual `rotate()` / `scale()` on the
+   * camera itself is discarded by the next assignment; a camera has `zoom`
+   * and `shake` for those jobs, and neither touches this matrix.
+   * @default 0
+   * @example
+   * camera.roll = Math.PI / 32; // a slight dutch angle
+   */
+  get roll() {
+    return this._roll;
+  }
+  set roll(value) {
+    if (value === this._roll) {
+      return;
+    }
+    this._roll = value;
+    this.currentTransform.identity();
+    if (value !== 0) {
+      this.currentTransform.rotate(value);
+    }
+    this.invCurrentTransform.copy(this.currentTransform).invert();
+    this.updateBounds();
+    this.isDirty = true;
+  }
   get zoom() {
     return this._zoom;
   }
@@ -20086,6 +20371,7 @@ var Camera2d = class extends Renderable {
     this.smoothFollow = true;
     this.damping = 1;
     this.currentTransform.identity();
+    this._roll = 0;
     this.invCurrentTransform.identity().invert();
     this.worldProjection.identity();
     this.screenProjection.identity();
@@ -20558,7 +20844,16 @@ var Camera2d = class extends Renderable {
       container.draw(r, this);
     }
     renderer.flushTransparent();
+    const hasCameraEffects = this.cameraEffects.length > 0;
+    if (hasCameraEffects) {
+      renderer.setProjection(this.screenProjection);
+    }
     this.drawFX(renderer);
+    if (hasCameraEffects) {
+      renderer.setProjection(
+        isNonDefault ? this.worldProjection : this.projectionMatrix
+      );
+    }
     container.postDraw(r);
     this.postDraw(r);
     if (stage) {
@@ -21855,9 +22150,8 @@ var Stage = class {
     }
   }
   /**
-   * update function
-   * @ignore
-   * @internal
+   * Update the stage. Override it to run your own per-frame logic, and call
+   * `super.update(dt)` so the world and cameras still advance.
    * @param dt - time since the last update in milliseconds.
    * @returns true if the stage needs to be redrawn
    */
@@ -21876,8 +22170,9 @@ var Stage = class {
    * 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
-   * @internal
+   *
+   * Override it to draw under or over the world, calling `super.draw(...)`
+   * where the world itself belongs in that order.
    * @param renderer - the renderer object to draw with
    * @param world - the world object to draw
    */
@@ -22051,6 +22346,13 @@ var DefaultLoadingScreen = class extends Stage {
    * @internal
    */
   #cleanedUp = false;
+  /**
+   * whether the preloader has reported done. Latched on LOADER_COMPLETE
+   * and read by the logo's own load callback — NOT a teardown signal.
+   * @ignore
+   * @internal
+   */
+  #loadingComplete = false;
   /**
    * Pin the loading screen to a Camera2d regardless of the
    * application's `cameraClass` setting. The loader must render
@@ -22070,13 +22372,14 @@ var DefaultLoadingScreen = class extends Stage {
     const barHeight = 8;
     this.#app = app;
     this.#cleanedUp = false;
+    this.#loadingComplete = false;
     app.world.backgroundColor.parseCSS("#202020");
     const { width, height } = app.renderer;
     this.progressBar = new ProgressBar(0, height / 2, width, barHeight);
     app.world.addChild(this.progressBar, 1);
-    once(LOADER_COMPLETE, this.#cleanup, this);
-    load2({ name: "melonjs_logo", type: "image", src: melonjs_logo_default }, () => {
-      if (this.#cleanedUp) {
+    once(LOADER_COMPLETE, this.#onLoaderComplete, this);
+    load2({ name: "melonjs_logo", type: "image", src: melonjs_logo_default }).then(() => {
+      if (this.#loadingComplete || this.#cleanedUp) {
         return;
       }
       this.logoSprite = new Sprite(width / 2, height / 2, {
@@ -22085,8 +22388,18 @@ var DefaultLoadingScreen = class extends Stage {
         frameheight: 256
       });
       app.world.addChild(this.logoSprite, 2);
+    }).catch(() => {
     });
   }
+  /**
+   * The preloader is done. Latched so a late-arriving logo is not added
+   * to a world that is about to be replaced; nothing is torn down here.
+   * @ignore
+   * @internal
+   */
+  #onLoaderComplete() {
+    this.#loadingComplete = true;
+  }
   /**
    * Remove loading screen children and unload the logo
    * @ignore
@@ -22114,8 +22427,8 @@ var DefaultLoadingScreen = class extends Stage {
    * @internal
    */
   onDestroyEvent() {
-    if (!this.#cleanedUp) {
-      off(LOADER_COMPLETE, this.#cleanup, this);
+    if (!this.#loadingComplete) {
+      off(LOADER_COMPLETE, this.#onLoaderComplete, this);
     }
     this.#cleanup();
   }
@@ -23080,6 +23393,9 @@ function preloadFontFace(data2, onload2, onerror) {
 }
 
 // src/lighting/light3d.ts
+function readVector(out, value) {
+  return Array.isArray(value) ? out.set(value[0], value[1], value[2]) : out.set(value.x, value.y, value.z);
+}
 var Light3d = class extends Renderable {
   /** `"directional"`, `"ambient"`, `"point"` or `"spot"`. */
   type;
@@ -23111,20 +23427,12 @@ var Light3d = class extends Renderable {
     this.type = options.type ?? "directional";
     this.direction = new Vector3d(0, 1, 0);
     if (options.direction) {
-      this.direction.set(
-        options.direction[0],
-        options.direction[1],
-        options.direction[2]
-      );
+      readVector(this.direction, options.direction);
     }
     this.direction.normalize();
     this.position = new Vector3d(0, 0, 0);
     if (options.position) {
-      this.position.set(
-        options.position[0],
-        options.position[1],
-        options.position[2]
-      );
+      readVector(this.position, options.position);
     }
     if (options.color instanceof Color) {
       this.color = options.color;
@@ -23505,6 +23813,7 @@ var Frustum = class {
 // src/camera/camera3d.ts
 var AXIS_X = new Vector3d(1, 0, 0);
 var AXIS_Y = new Vector3d(0, 1, 0);
+var AXIS_Z = new Vector3d(0, 0, 1);
 var _viewMatrix = new Matrix3d();
 var _viewProjection = new Matrix3d();
 var _wsPoint = new Vector3d();
@@ -23610,6 +23919,29 @@ var Camera3d = class extends Camera2d {
    * @default 0
    */
   yaw;
+  /**
+   * Z-axis rotation in radians (bank the horizon). Positive values
+   * roll the camera clockwise, so the world tilts anticlockwise —
+   * the view from a cockpit banking right.
+   *
+   * Completes the `pitch` / `yaw` / `roll` trio. Note this is NOT the
+   * inherited {@link Renderable#rotation}: a 3D camera builds its view
+   * from these three angles and never reads `currentTransform`, which
+   * is why `camera.rotate()` on a `Camera3d` is silently inert. A
+   * `Camera2d` is the other way round — it has no `roll` because a
+   * screen-plane rotation IS its only rotation, and `rotate()` already
+   * does it through `currentTransform`.
+   * @default 0
+   * @example
+   * // bank with the player's steering, as a flight game would
+   * camera.roll = (player.pos.x / PLAY_BOUND_X) * MAX_BANK;
+   */
+  get roll() {
+    return this._roll;
+  }
+  set roll(value) {
+    this._roll = value;
+  }
   /**
    * World-space offset from the followed target. When `target` is
    * set via {@link Camera2d#follow}, the camera position resolves to
@@ -23650,6 +23982,7 @@ var Camera3d = class extends Camera2d {
     });
     this.pitch = 0;
     this.yaw = 0;
+    this.roll = 0;
     this.followOffset = new Vector3d(0, 0, 0);
     this.lookAhead = new Vector3d(0, 0, 1);
     this.near = this.frustum.near;
@@ -23925,6 +24258,7 @@ var Camera3d = class extends Camera2d {
     _basis.identity();
     _basis.rotate(this.yaw, AXIS_Y);
     _basis.rotate(this.pitch, AXIS_X);
+    _basis.rotate(this.roll, AXIS_Z);
     const b = _basis.val;
     state4.heightAxis[0] = k * b[1];
     state4.heightAxis[1] = k * b[5];
@@ -23952,6 +24286,7 @@ var Camera3d = class extends Camera2d {
     _basis.identity();
     _basis.rotate(this.yaw, AXIS_Y);
     _basis.rotate(this.pitch, AXIS_X);
+    _basis.rotate(this.roll, AXIS_Z);
     const v = _basis.val;
     right.set(v[0], v[1], v[2]);
     up.set(v[4], v[5], v[6]);
@@ -24050,6 +24385,9 @@ var Camera3d = class extends Camera2d {
    * @internal
    */
   _applyContainerViewTransform(container, translateX, translateY) {
+    if (this.roll !== 0) {
+      container.rotate(-this.roll, AXIS_Z);
+    }
     if (this.pitch !== 0) {
       container.rotate(-this.pitch, AXIS_X);
     }
@@ -24076,6 +24414,9 @@ var Camera3d = class extends Camera2d {
     if (this.pitch !== 0) {
       container.rotate(this.pitch, AXIS_X);
     }
+    if (this.roll !== 0) {
+      container.rotate(this.roll, AXIS_Z);
+    }
   }
   /**
    * Point the camera at a world-space target by deriving pitch and
@@ -24276,6 +24617,9 @@ var Camera3d = class extends Camera2d {
    */
   worldToScreen(world, out = new Vector2d()) {
     _viewMatrix.identity();
+    if (this.roll !== 0) {
+      _viewMatrix.rotate(-this.roll, AXIS_Z);
+    }
     if (this.pitch !== 0) {
       _viewMatrix.rotate(-this.pitch, AXIS_X);
     }
@@ -24308,6 +24652,9 @@ var Camera3d = class extends Camera2d {
    */
   _rebuildFrustumPlanes() {
     _viewMatrix.identity();
+    if (this.roll !== 0) {
+      _viewMatrix.rotate(-this.roll, AXIS_Z);
+    }
     if (this.pitch !== 0) {
       _viewMatrix.rotate(-this.pitch, AXIS_X);
     }
@@ -24614,38 +24961,44 @@ function buildTextureGroups(groups, materials, shared, framewidth, frameheight)
   }
   return slices.length === 1 && slices[0].texture !== shared ? slices : void 0;
 }
+function declaredSize(settings) {
+  const width = settings.width;
+  const height = settings.height;
+  if (settings.normalize !== false || typeof settings.scale !== "number" || width > 0 && height > 0) {
+    return [width, height];
+  }
+  const vertices = typeof settings.model === "string" ? getOBJ(settings.model)?.vertices : settings.vertices;
+  if (!vertices || vertices.length < 3) {
+    return [width, height];
+  }
+  let minX = Infinity;
+  let maxX = -Infinity;
+  let minY = Infinity;
+  let maxY = -Infinity;
+  for (let i = 0; i < vertices.length; i += 3) {
+    if (vertices[i] < minX) {
+      minX = vertices[i];
+    }
+    if (vertices[i] > maxX) {
+      maxX = vertices[i];
+    }
+    if (vertices[i + 1] < minY) {
+      minY = vertices[i + 1];
+    }
+    if (vertices[i + 1] > maxY) {
+      maxY = vertices[i + 1];
+    }
+  }
+  return [
+    width > 0 ? width : (maxX - minX) * settings.scale,
+    height > 0 ? height : (maxY - minY) * settings.scale
+  ];
+}
 var Mesh = class _Mesh extends Renderable {
   /**
    * @param {number} x - the x screen position of the mesh object
    * @param {number} y - the y screen position of the mesh object
-   * @param {object} settings - Configuration parameters for the Mesh object
-   * @param {string} [settings.model] - name of a preloaded OBJ model (via loader.preload with type "obj"). Vertex normals come with it — authored `vn` when the file has them, generated from face geometry when it does not — so an OBJ model can be `lit`.
-   * @param {Float32Array|number[]} [settings.vertices] - vertex positions as x,y,z triplets (alternative to settings.model)
-   * @param {Float32Array|number[]} [settings.uvs] - texture coordinates as u,v pairs (alternative to settings.model)
-   * @param {Uint16Array|number[]} [settings.indices] - triangle vertex indices (alternative to settings.model)
-   * @param {HTMLImageElement|TextureAtlas|string} [settings.texture] - the texture to apply (image name, HTMLImageElement, or TextureAtlas). If omitted and settings.material is provided, the texture is resolved from the MTL material's map_Kd. Passing this pins ONE binding over the whole model, which on a multi-material model suppresses the per-material texture split — see {@link Mesh#textureGroups}.
-   * @param {string} [settings.material] - name of a preloaded MTL material (via loader.preload with type "mtl"). When provided, the diffuse texture (map_Kd), tint color (Kd), and opacity (d) are automatically applied. On a multi-material model each material's own `map_Kd` is bound for its own slice of the geometry (#1573) and each `Kd` is baked per-vertex, so one `Mesh` renders the whole model.
-   * @param {number} settings.width - display width in pixels. With normalization on (the default) the model is scaled to fit this size; with `normalize: false` this is the uniform pixels-per-unit scale applied to the raw geometry.
-   * @param {number} [settings.height] - display height in pixels (normalized models only; ignored when `normalize: false`)
-   * @param {boolean} [settings.cullBackFaces=true] - enable backface culling
-   * @param {boolean} [settings.normalize=true] - fit the source geometry into a `[-0.5, 0.5]` unit cube before scaling, so `width`/`height` behave like a Sprite. Set `false` to keep the geometry's real-world coordinates — required when several meshes share one coordinate space (e.g. nodes of an imported glTF scene) so their relative scale and layout are preserved.
-   * @param {number} [settings.scale] - world-space scale (pixels per source unit) for the Camera3d path; defaults to `width`. Set this when `width`/`height` describe the renderable's world bounds (frustum culling) rather than the geometry scale — see {@link Mesh#meshScale}.
-   * @param {boolean} [settings.rightHanded=false] - treat the source as right-handed (Y-up, e.g. glTF) under the `Camera3d` world path. The default Y-up→Y-down bridge negates Y only (a reflection, which mirrors the scene left/right); `true` negates Y **and** Z (a rotation) so chirality is preserved and the result matches the authoring tool. See {@link Mesh#rightHanded}.
-   * @param {string} [settings.textureRepeat] - texture wrap mode (`"repeat"` / `"repeat-x"` / `"repeat-y"` / `"no-repeat"`) this mesh samples its texture with (per-mesh — it does not modify the shared texture, so other meshes/sprites using the same image are unaffected). Use `"repeat"` when the geometry's UVs fall outside the `[0, 1]` range and rely on the texture tiling (e.g. glTF assets, whose default sampler wrap is REPEAT) — otherwise the texture clamps to its edge texels and looks flat. Ignored for the white-pixel fallback. Note: REPEAT on a non-power-of-two texture requires WebGL 2.
-   * @param {string} [settings.textureFilter] - texture magnification filter (`"nearest"` for crisp pixel-art upscaling, `"linear"` for smooth) applied to the resolved texture. Omit to keep the renderer's global `antiAlias` default. On the mesh path, linear filtering also samples a generated mip chain with trilinear minification and 4× anisotropy (distant geometry stops shimmering) — `"nearest"` opts out, keeping crisp pixel-art models on hard level-0 sampling. GPU backends only (ignored by the Canvas renderer).
-   * @param {number} [settings.alphaCutoff=0] - alpha cutout threshold. Fragments whose final alpha is below this value are discarded (hard-edged cutout — foliage, fences, decals — with no blending or sorting). `0` disables the cutout. Set automatically by the glTF loader from a material's `alphaMode: "MASK"`. GPU mesh path only (WebGL and WebGPU; the Canvas renderer ignores it).
-   * @param {number[]|Float32Array} [settings.emissive] - emissive (self-illumination) color `[r, g, b]` (0..1, may exceed 1 for HDR glow) added on top of the lit/unlit color so the surface glows regardless of scene lights (neon, lava, screens). Omit / all-zero for no emission. Set automatically by the glTF loader (`emissiveFactor`) and OBJ loader (MTL `Ke`). GPU mesh path only (WebGL and WebGPU; the Canvas renderer ignores it).
-   * @param {boolean} [settings.lit=false] - shade this mesh with the scene's {@link Light3d} lights (the lit mesh pipeline) instead of rendering fullbright. Set automatically by the glTF importer when the scene carries a directional, point or spot light. With `lit` on and no lights present the batcher uploads a white ambient, so the result is indistinguishable from unlit.
-   * @param {Uint32Array|Color[]|number[]} [settings.vertexColors] - per-vertex colour, one entry per vertex, multiplied into {@link Mesh#tint}. Either packed RGBA8 (`Uint32Array`, the form the batchers read — no conversion) or one {@link Color} per vertex. Omit for plain white. Lets a single mesh carry a gradient — fading a terrain toward the sky with distance, darkening a crease — which a per-object `tint` cannot express. An explicit value wins over the colours a multi-material OBJ bakes from its MTL.
-   * @param {number[]|Float32Array} [settings.normals] - per-vertex normals for the lit path. An explicit value wins over the ones an OBJ or glTF source supplies; omit it and they are taken from the model, or generated from the geometry when the mesh is `lit`. Generated normals average per vertex where faces share vertices (smooth shading) and equal the face normal where they do not (flat shading) — the geometry decides, not a flag.
-   * @param {number[]|Float32Array} [settings.specular] - specular color `[r, g, b]` (0..1) for the lit path. Set by the OBJ loader from MTL `Ks`, and derived from glTF metallic/roughness.
-   * @param {number} [settings.shininess=0] - specular exponent for the lit path (MTL `Ns`). `0` for a fully diffuse surface.
-   * @param {string|TextureAtlas|HTMLImageElement} [settings.alphaMap] - per-texel opacity map, sampled in addition to the diffuse texture (MTL `map_d`).
-   * @param {boolean} [settings.castGroundShadow] - give this mesh a blob ground shadow, overriding the application's `castGroundShadow` setting in both directions. Omit to inherit. Needs a GPU backend and a `Camera3d`.
-   * @param {boolean} [settings.transparent] - draw in the transparent pass (blended, back-to-front, no depth write). Omit and a mesh goes transparent whenever its draw alpha is fractional; `true` for soft-alpha textures; `false` to stay opaque however faded
-   * @param {boolean} [settings.fog] - set `false` to exempt this mesh from the camera's distance fog ({@link Camera3d#setFog}); omit to fog whenever the camera does
-   * @param {number} [settings.shadowGroundY] - world Y of the floor the shadow lands on. Omit and the blob sits at the object's own base at full strength; set it and the blob shrinks and fades as the object rises. Render space is Y-down, so the floor is a **greater** Y than the object above it.
-   * @param {number} [settings.shadowOpacity=0.45] - opacity of the shadow directly beneath the object, before any height fade.
+   * @param {MeshSettings} settings - Configuration parameters for the Mesh object
    * @example
    * // create from OBJ + MTL (texture auto-resolved from material)
    * let mesh = new me.Mesh(0, 0, {
@@ -24692,7 +25045,7 @@ var Mesh = class _Mesh extends Renderable {
    * mesh.rotate(Math.PI / 4);
    */
   constructor(x, y, settings) {
-    super(x, y, settings.width, settings.height);
+    super(x, y, ...declaredSize(settings));
     let objGroups = null;
     let sourceNormals = settings.normals;
     if (typeof settings.model === "string") {
@@ -25175,6 +25528,66 @@ var Mesh = class _Mesh extends Renderable {
     renderer?.deleteMeshGeometry?.(this);
     super.onDeactivateEvent(...args);
   }
+  /**
+   * The centre of this mesh's own geometry, in MODEL space, written into
+   * `_lcx` / `_lcy` / `_lcz`.
+   *
+   * The transparent pass needs a point that represents where a mesh
+   * actually is. Its origin does not: a mesh whose vertices run away from
+   * the origin — a ground plane authored from one corner, a river that
+   * trails behind the boat it is parented to — sits nowhere near it. Keyed
+   * on that origin, such a mesh sorts by an authoring choice rather than by
+   * its position.
+   *
+   * Cached against `_geometryVersion`, so the vertex walk happens once per
+   * geometry edit rather than once per queued draw. An origin-centred mesh
+   * — which is most of them — resolves to (0, 0, 0) and keys exactly as it
+   * did before.
+   * @ignore
+   * @internal
+   */
+  _updateLocalCenter() {
+    if (this._lcVersion === this._geometryVersion) {
+      return;
+    }
+    const v = this.originalVertices;
+    const n = this.vertexCount;
+    let minX = Infinity;
+    let minY = Infinity;
+    let minZ = Infinity;
+    let maxX = -Infinity;
+    let maxY = -Infinity;
+    let maxZ = -Infinity;
+    if (v !== void 0 && n > 0) {
+      for (let i = 0; i < n; i++) {
+        const x = v[i * 3];
+        const y = v[i * 3 + 1];
+        const z = v[i * 3 + 2];
+        if (x < minX) {
+          minX = x;
+        }
+        if (x > maxX) {
+          maxX = x;
+        }
+        if (y < minY) {
+          minY = y;
+        }
+        if (y > maxY) {
+          maxY = y;
+        }
+        if (z < minZ) {
+          minZ = z;
+        }
+        if (z > maxZ) {
+          maxZ = z;
+        }
+      }
+    }
+    this._lcx = Number.isFinite(minX) ? (minX + maxX) * 0.5 : 0;
+    this._lcy = Number.isFinite(minY) ? (minY + maxY) * 0.5 : 0;
+    this._lcz = Number.isFinite(minZ) ? (minZ + maxZ) * 0.5 : 0;
+    this._lcVersion = this._geometryVersion;
+  }
   /**
    * The mesh's world-space 3D axis-aligned bounding box. This is the 3D analog
    * of {@link Renderable#getBounds} (which returns a flat 2D box from
@@ -25587,10 +26000,7 @@ var InstancedMesh = class extends Mesh {
   /**
    * @param {number} x - the x coordinate of the group origin
    * @param {number} y - the y coordinate of the group origin
-   * @param {object} settings - every {@link Mesh} setting, plus those below
-   * @param {number} [settings.instanceCount=0] - number of instances to pre-allocate. Instances start at the group origin (identity transform) until placed; `addInstance` grows past this.
-   * @param {boolean} [settings.instanceColors=false] - give each instance its own colour (16 bytes per instance), multiplied into the mesh tint
-   * @param {boolean} [settings.instanceData=false] - give each instance an opaque `vec4` (16 bytes per instance). Read as emissive by the built-in lit shading, or as anything at all by a custom mesh shader.
+   * @param {InstancedMeshSettings} settings - every {@link Mesh} setting, plus the instancing ones
    */
   constructor(x, y, settings) {
     super(x, y, settings);
@@ -26652,9 +27062,16 @@ var Container = class _Container extends Renderable {
   }
   /**
    * Automatically set the specified property of all childs to the given value
+   *
+   * This ASSIGNS to the children — after it, their own property carries the
+   * value. To fade a subtree without touching what the children are, set
+   * {@link Renderable#alpha} on the container instead: opacity cascades at
+   * draw time and leaves every child's own value alone.
    * @param {string} prop - property name
-   * @param {object} value - property value
+   * @param {*} value - property value; whatever the named property holds, so a
+   * flag is a boolean and a colour is a string, not only an object
    * @param {boolean} [recursive=false] - recursively apply the value to child containers if true
+   * @see Renderable#alpha
    */
   setChildsProperty(prop, value, recursive) {
     this.forEach((child) => {
@@ -27053,6 +27470,13 @@ function linearToSrgb8(c) {
 
 // src/level/gltf/GLTFModel.js
 var IDENTITY16 = [1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1];
+var _rootScratch = new Array(16);
+function partAbsolutePosition() {
+  if (this._absPos === void 0) {
+    this._absPos = vector3dPool.get();
+  }
+  return this._absPos.set(this.pos.x, this.pos.y, this.depth);
+}
 var _t = [0, 0, 0];
 var _r = [0, 0, 0, 1];
 var _s = [1, 1, 1];
@@ -27060,7 +27484,7 @@ var _val = [0, 0, 0, 0];
 var _localScratch = new Array(16);
 var GLTFModel = class extends Container {
   /**
-   * @param {object} data - the parsed glTF descriptor (`{ graph, animations, bounds, ... }`)
+   * @param {import("../../loader/loader.js").GLTFData} data - the parsed glTF descriptor, as returned by {@link loader.getGLTF}
    * @param {object} [options]
    * @param {number} [options.scale=1] - pixels per glTF unit (uniform scene scale)
    * @param {boolean} [options.rightHanded=true] - glTF Y-up → engine Y-down via a rotation (no mirror)
@@ -27073,6 +27497,7 @@ var GLTFModel = class extends Container {
     this.scale = options.scale ?? 1;
     this._zSign = options.rightHanded !== false ? -1 : 1;
     this.autoDepth = false;
+    this.autoTransform = false;
     this.applyAnchorTransform = false;
     this._nodes = data2.graph.nodes;
     this._roots = data2.graph.roots;
@@ -27085,6 +27510,9 @@ var GLTFModel = class extends Container {
     const dz = b.max[2] - b.min[2];
     const radius = Math.hypot(dx, dy, dz) / 2 * this.scale;
     const boxSize = Math.max(radius, 1) * Math.SQRT2;
+    this._extent = Math.max(radius, 1);
+    this._extentX = (b.min[0] + b.max[0]) / 2 * this.scale;
+    this._extentY = -((b.min[1] + b.max[1]) / 2) * this.scale;
     const lit = options.lit === true;
     const rightHanded = options.rightHanded !== false;
     const castGroundShadow = typeof options.castGroundShadow === "boolean" ? options.castGroundShadow : void 0;
@@ -27142,6 +27570,7 @@ var GLTFModel = class extends Container {
           mesh.vertexColors = prim.colors;
         }
         mesh.name = node.name;
+        mesh.getAbsolutePosition = partAbsolutePosition;
         (this._meshByNode[idx] ??= []).push(mesh);
         this.addChild(mesh);
       }
@@ -27192,7 +27621,7 @@ var GLTFModel = class extends Container {
    * another clip when this one ends, a `function` legacy completion callback
    * (return `false` to hold the final pose), or an options object.
    * @param {string} name - animation clip id (see {@link GLTFModel#getAnimationNames})
-   * @param {string|Function|AnimationOptions} [options] - loop / chain / completion behavior
+   * @param {AnimationOptionsInput} [options] - loop / chain / completion behavior
    * @param {boolean} [preserveTime=false] - keep the current playback time instead of restarting at 0
    * @returns {GLTFModel} this, for chaining
    * @example
@@ -27259,7 +27688,7 @@ var GLTFModel = class extends Container {
    * (and start) it, or with no argument to resume after {@link GLTFModel#pause}.
    * Always clears the paused state.
    * @param {string} [name] - clip id to play; omit to just resume
-   * @param {string|Function|AnimationOptions} [options] - loop / chain / completion behavior (see {@link GLTFModel#setCurrentAnimation})
+   * @param {AnimationOptionsInput} [options] - loop / chain / completion behavior (see {@link GLTFModel#setCurrentAnimation})
    * @returns {GLTFModel} this, for chaining
    * @example
    * model.play("walk");                  // switch to + play "walk"
@@ -27362,6 +27791,52 @@ var GLTFModel = class extends Container {
   _isLive() {
     return this.pos !== void 0;
   }
+  /**
+   * {@link Container#draw} translates the renderer by `pos` so children draw
+   * in container-local space. This rig's children are already in world space,
+   * so that translation is undone here rather than doubling the placement.
+   * Paired with `autoTransform = false`, which suppresses the matching
+   * rotation fold.
+   * @param {CanvasRenderer|WebGLRenderer} renderer - a renderer instance
+   * @param {Camera2d} [viewport] - the camera rendering this frame
+   */
+  draw(renderer, viewport) {
+    renderer.translate(-this.pos.x, -this.pos.y);
+    super.draw(renderer, viewport);
+  }
+  /**
+   * Where this model is, as a 2D box — what culling, picking and the physics
+   * broadphase all read.
+   *
+   * A `Container` has no dimensions of its own, and one left that way reports
+   * an EMPTY bounds: a model claiming to be nowhere, which the broadphase
+   * cannot place. A rig's size is known at load from the glTF scene AABB, so
+   * this is a placement of a measurement taken once in the constructor rather
+   * than a walk of the parts — `Container#updateBounds` with
+   * `enableChildBoundsUpdate` would re-measure the whole rig on every call,
+   * and that flag is for a group whose extent really is its members' union.
+   *
+   * The box is the model's bounding SPHERE squared off, so a turned model
+   * still reports something that contains it. Generous bounds only cost
+   * broadphase pruning; tight ones lose contacts.
+   * @param {boolean} [absolute=true] - in world rather than local coordinates
+   * @returns {Bounds} this model's bounding box
+   */
+  updateBounds(absolute = true) {
+    const bounds = this.getBounds();
+    const e = this._extent;
+    bounds.setMinMax(
+      this._extentX - e,
+      this._extentY - e,
+      this._extentX + e,
+      this._extentY + e
+    );
+    if (absolute === true) {
+      const absPos = this.getAbsolutePosition();
+      bounds.translate(absPos.x, absPos.y);
+    }
+    return bounds;
+  }
   /**
    * @ignore
    * @internal
@@ -27369,9 +27844,47 @@ var GLTFModel = class extends Container {
   _pose() {
     const clip = this.current.name ? this.anim[this.current.name] : null;
     const t = this.current.time;
+    const parent = this._rootMatrix();
     for (const root of this._roots) {
-      this._visit(root, IDENTITY16, clip, t);
+      this._visit(root, parent, clip, t);
+    }
+  }
+  /**
+   * The model's own placement, as the parent transform every root node hangs
+   * from — so `pos`, `depth` and `currentTransform` move, turn and scale the
+   * whole rig the way they do for any other renderable.
+   *
+   * It has to be handed to the DFS in **glTF space**, because that is where
+   * the node matrices live and `_applyWorldToMesh` only bridges to engine
+   * space afterwards. The bridge is `D = diag(1, -1, zSign)` and a uniform
+   * `scale`, so the inverse trip is a division by `scale` for the translation
+   * and a conjugation `D · R · D` for the rotation/scale — `D` is its own
+   * inverse, which is what makes the conjugation this cheap.
+   * @returns {number[]} 16-element column-major matrix
+   * @ignore
+   * @internal
+   */
+  _rootMatrix() {
+    const { x, y, z } = this.pos;
+    const t = this.currentTransform.val;
+    const s = this.scale;
+    if (x === 0 && y === 0 && z === 0 && this.currentTransform.isIdentity()) {
+      return IDENTITY16;
+    }
+    const out = _rootScratch;
+    const zs = this._zSign;
+    for (let col = 0; col < 3; col++) {
+      const dc = col === 0 ? 1 : col === 1 ? -1 : zs;
+      out[col * 4] = t[col * 4] * dc;
+      out[col * 4 + 1] = -t[col * 4 + 1] * dc;
+      out[col * 4 + 2] = zs * t[col * 4 + 2] * dc;
+      out[col * 4 + 3] = 0;
     }
+    out[12] = x / s;
+    out[13] = -y / s;
+    out[14] = zs * z / s;
+    out[15] = 1;
+    return out;
   }
   /**
    * DFS one node: compose its local matrix, multiply by the parent world,
@@ -30203,13 +30716,47 @@ function createShapeObject(settings) {
 }
 
 // src/renderable/text/textstyle.js
+var VERTICAL_TOLERANCE = 0.1;
+function resolveFill(context, style) {
+  const gradient = style.fillGradient;
+  if (gradient === void 0) {
+    return style.fillStyle.toRGBA();
+  }
+  const lines = style._text?.length ?? 1;
+  if (style.gradientPerLine !== true || lines <= 1 || gradient.type !== "linear") {
+    return gradient.toCanvasGradient(context);
+  }
+  const [x0, y0, x1, y1] = gradient.coords;
+  const span = y1 - y0;
+  if (span === 0 || Math.abs(x1 - x0) > Math.abs(span) * VERTICAL_TOLERANCE) {
+    return gradient.toCanvasGradient(context);
+  }
+  const lineHeight = style.metrics.lineHeight();
+  const blockHeight = lines * lineHeight;
+  if (blockHeight <= 0) {
+    return gradient.toCanvasGradient(context);
+  }
+  const repeated = context.createLinearGradient(x0, 0, x1, blockHeight);
+  for (let line = 0; line < lines; line++) {
+    for (const stop2 of gradient.colorStops) {
+      const y = line * lineHeight + y0 + stop2.offset * span;
+      repeated.addColorStop(
+        Math.min(1, Math.max(0, y / blockHeight)),
+        stop2.color
+      );
+    }
+  }
+  return repeated;
+}
 function setContextStyle(context, style) {
+  const fill = resolveFill(context, style);
   context.font = style.font;
-  context.fillStyle = style.fillStyle.toRGBA();
+  context.fillStyle = fill;
   context.strokeStyle = style.strokeStyle.toRGBA();
   context.lineWidth = style.lineWidth;
   context.textAlign = style.textAlign;
   context.textBaseline = style.textBaseline;
+  return fill;
 }
 
 // src/renderable/text/text.js
@@ -30237,7 +30784,8 @@ var Text = class extends Renderable {
    * @param {object} settings - the text configuration
    * @param {string} settings.font - a CSS font family: a specific name (`"Arial"`), a generic keyword (`"sans-serif"`, `"monospace"`, …), or a web font loaded via the `fontface` loader (referenced by its family name)
    * @param {number|string} settings.size - the font size: a number in pixels, or a CSS size string with a unit (`"24px"` / `"1.5em"` / `"18pt"`)
-   * @param {Color|string} [settings.fillStyle="#000000"] - a CSS color value used to fill the glyphs
+   * @param {Color|Gradient|string} [settings.fillStyle="#000000"] - a CSS color value used to fill the glyphs, or a {@link Gradient} to ramp them
+   * @param {boolean} [settings.gradientPerLine=true] - restart a gradient fill on every line; `false` spans one ramp across the whole block, as a plain canvas does
    * @param {Color|string} [settings.strokeStyle="#000000"] - a CSS color value used for the glyph outline (drawn when `lineWidth` > 0)
    * @param {number} [settings.lineWidth=0] - outline width in pixels (0 = no stroke)
    * @param {string} [settings.textAlign="left"] - horizontal text alignment ("left", "center", "right")
@@ -30245,6 +30793,8 @@ var Text = class extends Renderable {
    * @param {number} [settings.lineHeight=1.0] - line spacing height
    * @param {string|Vector2d|{x:number,y:number}} [settings.anchorPoint={x:0.0, y:0.0}] - anchor point to draw the text at. Also accepts the named presets `"center"`, `"top"`, `"bottom"`, `"left"`, `"right"`, `"top-left"`, `"top-right"`, `"bottom-left"`, `"bottom-right"`.
    * @param {number} [settings.wordWrapWidth] - the maximum length in CSS pixels of a line before it wraps
+   * @param {boolean} [settings.bold=false] - render the face bold, as {@link Text#bold} does
+   * @param {boolean} [settings.italic=false] - render the face italic, as {@link Text#italic} does
    * @param {(string|string[])} [settings.text=""] - a string, or an array of strings
    * @example
    * // a styled, word-wrapped, multi-line label using a generic system font
@@ -30263,6 +30813,23 @@ var Text = class extends Renderable {
    * label.setOpacity(0.8);           // per-object transparency
    * app.world.addChild(label);
    * @example
+   * // a gradient fill: `fillStyle` takes a Gradient as well as a colour.
+   * // Its coordinates are the label's OWN bake, so (0, 0) is the top-left of
+   * // the render box and the ramp below runs down exactly one line.
+   * const ramp = app.renderer.createLinearGradient(0, 0, 0, 32);
+   * ramp.addColorStop(0, "#fffdf0");
+   * ramp.addColorStop(1, "#ffa71d");
+   *
+   * app.world.addChild(new Text(8, 8, {
+   *     font: "sans-serif",
+   *     size: 32,
+   *     fillStyle: ramp,             // ramps the glyphs...
+   *     strokeStyle: "#000000",      // ...while the outline keeps its own colour
+   *     lineWidth: 1,
+   *     text: "GAME\nOVER",          // every line restarts the ramp by default
+   *     // gradientPerLine: false,   // ...or span ONE ramp across both lines
+   * }));
+   * @example
    * // a web font (loaded via the fontface loader) is used by its family name
    * loader.preload(
    *     [{ name: "kenpixel", type: "fontface", src: "data/font/kenvector.woff2" }],
@@ -30294,11 +30861,16 @@ var Text = class extends Renderable {
     if (typeof this.fillStyle === "undefined") {
       this.fillStyle = colorPool.get(0, 0, 0);
     }
+    this.fillGradient = void 0;
+    this.gradientPerLine = true;
     if (typeof this.strokeStyle === "undefined") {
       this.strokeStyle = colorPool.get(0, 0, 0);
     }
+    this.fillGradient = void 0;
     if (typeof settings.fillStyle !== "undefined") {
-      if (settings.fillStyle instanceof Color) {
+      if (settings.fillStyle instanceof Gradient) {
+        this.fillGradient = settings.fillStyle;
+      } else if (settings.fillStyle instanceof Color) {
         this.fillStyle.copy(settings.fillStyle);
       } else {
         this.fillStyle.parseCSS(settings.fillStyle);
@@ -30311,6 +30883,9 @@ var Text = class extends Renderable {
         this.strokeStyle.parseCSS(settings.strokeStyle);
       }
     }
+    if (typeof settings.gradientPerLine === "boolean") {
+      this.gradientPerLine = settings.gradientPerLine;
+    }
     this.lineWidth = settings.lineWidth || 0;
     this.textAlign = settings.textAlign || "left";
     this.textBaseline = settings.textBaseline || "top";
@@ -30425,9 +31000,10 @@ var Text = class extends Renderable {
       true
     );
     const width = Math.ceil(this.metrics.width / 32) * 32;
-    const height = Math.ceil(this.metrics.height / 32) * 32;
+    const height = Math.ceil(
+      (this.metrics.height + this.metrics.inkPadTop + this.metrics.inkPadBottom) / 32
+    ) * 32;
     const renderer = this.parentApp?.renderer ?? game.renderer;
-    this.canvasTexture.invalidate(renderer);
     if (this.canvasTexture.width < width || this.canvasTexture.height < height) {
       this.canvasTexture.resize(width, height);
     }
@@ -30438,6 +31014,7 @@ var Text = class extends Renderable {
       this.pos.x - this.metrics.x,
       this.pos.y - this.metrics.y
     );
+    this.canvasTexture.invalidate(renderer);
     this.isDirty = true;
     return this;
   }
@@ -30464,9 +31041,18 @@ var Text = class extends Renderable {
   }
   /**
    * the ratio of visible characters (0.0 to 1.0).
-   * Setting this automatically updates {@link visibleCharacters}.
+   * Setting this automatically updates {@link Text#visibleCharacters}.
+   *
+   * This is the one to tween: it is independent of how many characters the
+   * label holds, so a reveal takes the same time whatever the string is.
    * @public
    * @type {number}
+   * @default 1.0
+   * @see Text#visibleCharacters
+   * @example
+   * // reveal over two seconds, regardless of length
+   * label.visibleRatio = 0;
+   * new Tween(label).to({ visibleRatio: 1.0 }, { duration: 2000 }).start();
    */
   get visibleRatio() {
     if (this._visibleCharacters === -1) {
@@ -30535,6 +31121,14 @@ var Text = class extends Renderable {
    * measure the given text size in pixels
    * @param {string} [text] - the text to be measured
    * @returns {TextMetrics} a TextMetrics object defining the dimensions of the given piece of text
+   * @example
+   * // size a panel around a label
+   * const size = label.measureText();
+   * panel.resize(size.width + 16, size.height + 16);
+   *
+   * // or measure a string the label does not currently hold, to reserve
+   * // room for the widest state a counter will reach
+   * const widest = label.measureText("00:00").width;
    */
   measureText(text = this._text) {
     return this.metrics.measureText(text, this.canvasTexture.context);
@@ -30544,8 +31138,8 @@ var Text = class extends Renderable {
    * @param {CanvasRenderer|WebGLRenderer} renderer - Reference to the destination renderer instance
    */
   draw(renderer) {
+    this.metrics.updateOrigin();
     if (this.isDirty) {
-      this.canvasTexture.invalidate(renderer);
       this.canvasTexture.clear();
       this._drawFont(
         this.canvasTexture.context,
@@ -30553,9 +31147,10 @@ var Text = class extends Renderable {
         this.pos.x - this.metrics.x,
         this.pos.y - this.metrics.y
       );
+      this.canvasTexture.invalidate(renderer);
     }
     let x = this.metrics.x;
-    let y = this.metrics.y;
+    let y = this.metrics.y - this.metrics.inkPadTop;
     if (renderer.settings.subPixel === false) {
       x = ~~x;
       y = ~~y;
@@ -30567,25 +31162,54 @@ var Text = class extends Renderable {
    * @internal
    */
   _drawFont(context, text, x, y) {
-    setContextStyle(context, this);
-    let remaining = this.visibleCharacters;
-    for (let i = 0; i < text.length; i++) {
-      let string = text[i].trimEnd();
-      if (remaining !== -1) {
-        if (remaining <= 0) {
-          break;
+    context.save();
+    context.translate(0, this.metrics.inkPadTop);
+    const fill = setContextStyle(context, this);
+    const fills = this.fillStyle.alpha > 0;
+    const strokes = this.lineWidth > 0 && this.strokeStyle.alpha > 0;
+    const masked = fills && this.fillGradient !== void 0;
+    const eachLine = (paint) => {
+      let remaining = this.visibleCharacters;
+      let lineY = y;
+      for (let i = 0; i < text.length; i++) {
+        let string = text[i].trimEnd();
+        if (remaining !== -1) {
+          if (remaining <= 0) {
+            break;
+          }
+          string = string.substring(0, remaining);
+          remaining -= string.length;
         }
-        string = string.substring(0, remaining);
-        remaining -= string.length;
+        paint(string, x, lineY);
+        lineY += this.metrics.lineHeight();
       }
-      if (this.fillStyle.alpha > 0) {
-        context.fillText(string, x, y);
-      }
-      if (this.lineWidth > 0 && this.strokeStyle.alpha > 0) {
-        context.strokeText(string, x, y);
+    };
+    if (fills) {
+      if (masked === true) {
+        context.fillStyle = "#000000";
       }
-      y += this.metrics.lineHeight();
+      eachLine((line, lineX, lineY) => {
+        context.fillText(line, lineX, lineY);
+      });
+    }
+    if (masked === true) {
+      const canvas = context.canvas;
+      context.globalCompositeOperation = "source-in";
+      context.fillStyle = fill;
+      context.fillRect(
+        -1,
+        -this.metrics.inkPadTop - 1,
+        canvas.width + 2,
+        canvas.height + 2
+      );
+      context.globalCompositeOperation = "source-over";
+    }
+    if (strokes) {
+      eachLine((line, lineX, lineY) => {
+        context.strokeText(line, lineX, lineY);
+      });
     }
+    context.restore();
     return this.metrics;
   }
   /**
@@ -30597,6 +31221,7 @@ var Text = class extends Renderable {
     const renderer = this.parentApp?.renderer ?? game.renderer;
     this.canvasTexture.destroy(renderer);
     this.canvasTexture = void 0;
+    this.fillGradient = void 0;
     colorPool.release(this.fillStyle);
     colorPool.release(this.strokeStyle);
     this.fillStyle = this.strokeStyle = void 0;
@@ -30607,6 +31232,8 @@ var Text = class extends Renderable {
 };
 
 // src/renderable/text/textmetrics.js
+var INK_SLACK = 1;
+var INK_GUESS = 0.25;
 var TextMetrics = class extends Bounds {
   /**
    * @param {Text|BitmapText} ancestor - the parent object that contains this TextMetrics object
@@ -30690,17 +31317,55 @@ var TextMetrics = class extends Bounds {
       this.glyphYOffset = fontData.glyphMinTop * scaleY;
       this.glyphMaxBottom = fontData.glyphMaxBottom * scaleY;
     }
+    this.inkPadTop = 0;
+    this.inkPadBottom = 0;
+    if (!isBitmapText && strings.length > 0 && typeof context !== "undefined") {
+      const style = this.ancestor;
+      const stroke = style.lineWidth > 0 && style.strokeStyle.alpha > 0 ? style.lineWidth / 2 : 0;
+      const first = context.measureText(strings[0].trimEnd());
+      const last = strings.length === 1 ? first : context.measureText(strings[strings.length - 1].trimEnd());
+      const above = first.actualBoundingBoxAscent;
+      const below = last.actualBoundingBoxDescent;
+      const measured = Number.isFinite(above) && Number.isFinite(below);
+      const top = measured ? above : style.fontSize * INK_GUESS;
+      const bottom = measured ? below : style.fontSize * INK_GUESS;
+      this.inkPadTop = Math.max(0, Math.ceil(top + stroke) + INK_SLACK);
+      this.inkPadBottom = Math.max(
+        0,
+        Math.ceil(this.inkPadTop + bottom + stroke - this.lineHeight()) + INK_SLACK
+      );
+    }
     this.width = Math.ceil(this.width);
     this.height = Math.ceil(this.height);
+    this.updateOrigin();
+    if (typeof context !== "undefined") {
+      context.restore();
+    }
+    return this;
+  }
+  /**
+   * Recompute the box's position from the ancestor's CURRENT `pos`.
+   *
+   * Split out of `measureText` because it depends on `pos` while everything
+   * else there depends only on the string and the font. A label that moves
+   * needs this refreshed — and nothing else — so the draw path can call it
+   * per frame without re-measuring a single glyph.
+   *
+   * The `Math.floor` is what puts the canvas on a whole pixel. The remainder
+   * it drops is not lost: `Text` bakes its glyphs at `pos - metrics`, so the
+   * sub-pixel part lands in the rasterization, where the font rasterizer can
+   * antialias it, instead of resampling the whole texture.
+   * @returns {TextMetrics} this instance for chaining
+   * @ignore
+   * @internal
+   */
+  updateOrigin() {
     this.x = Math.floor(
       this.ancestor.textAlign === "right" ? this.ancestor.pos.x - this.width : this.ancestor.textAlign === "center" ? this.ancestor.pos.x - this.width / 2 : this.ancestor.pos.x
     );
     this.y = Math.floor(
       this.ancestor.textBaseline.search(/^(top|hanging)$/) === 0 ? this.ancestor.pos.y : this.ancestor.textBaseline === "middle" ? this.ancestor.pos.y - this.lineHeight() / 2 : this.ancestor.pos.y - this.lineHeight()
     );
-    if (typeof context !== "undefined") {
-      context.restore();
-    }
     return this;
   }
   /**
@@ -30748,9 +31413,8 @@ var BitmapText = class extends Renderable {
    * @param {object} settings - the text configuration
    * @param {string|Image} settings.font - a font name to identify the corresponding source image
    * @param {string} [settings.fontData=settings.font] - the bitmap font data corresponding name, or the bitmap font data itself (AngelCode BMFont, `.fnt` text or `.xml`)
-   * @param {number} [settings.size] - size a scaling ratio
-   * @param {Color|string} [settings.fillStyle] - a CSS color value used to tint the bitmapText (@see BitmapText.tint)
-   * @param {number} [settings.lineWidth=1] - line width, in pixels, when drawing stroke
+   * @param {number} [settings.size=1.0] - a scaling RATIO applied to the font's authored size, not a pixel size: `2` draws it at double. ({@link Text} takes pixels here; this one does not.)
+   * @param {Color|string} [settings.fillStyle] - a CSS color value used to tint the glyphs, see {@link Renderable#tint}
    * @param {string} [settings.textAlign="left"] - horizontal text alignment
    * @param {string} [settings.textBaseline="top"] - the text baseline
    * @param {number} [settings.lineHeight=1.0] - line spacing height
@@ -30816,7 +31480,7 @@ var BitmapText = class extends Renderable {
   /**
    * change the font settings
    * @param {string} textAlign - ("left", "center", "right")
-   * @param {number} [scale]
+   * @param {number} [scale] - a scaling ratio, applied through {@link BitmapText#resize} when given
    * @returns {BitmapText} this object for chaining
    */
   set(textAlign, scale2) {
@@ -30941,10 +31605,27 @@ var BitmapText = class extends Renderable {
     return bounds;
   }
   /**
-   * defines the color used to tint the bitmap text
+   * defines the color used to tint the bitmap text.
+   *
+   * This is {@link Renderable#tint} under another name, so the same rule
+   * applies: white — `(255, 255, 255)` — is the absence of a tint, and any
+   * other colour tints away from there. A page image authored in white
+   * therefore keeps every colour available to it.
    * @public
    * @type {Color}
    * @see Renderable#tint
+   * @example
+   * // tint at construction...
+   * const score = new BitmapText(8, 8, {
+   *     font: "arial",
+   *     text: "1000",
+   *     fillStyle: "#ffd700",        // gold
+   * });
+   * app.world.addChild(score);
+   *
+   * // ...or at any point after it, from a CSS string or a Color
+   * score.fillStyle = "#ff4040";                  // flash red on damage
+   * score.fillStyle = new Color(255, 255, 255);   // back to untinted
    */
   get fillStyle() {
     return this.tint;
@@ -30958,8 +31639,14 @@ var BitmapText = class extends Renderable {
   }
   /**
    * change the font display size
-   * @param {number} scale - ratio
+   * @param {number} scale - a ratio against the font's authored size, NOT a
+   * pixel size: `1` is the page image at its native scale, `2` is double
    * @returns {BitmapText} this object for chaining
+   * @example
+   * // a bitmap font is pixel art — whole-number ratios stay crisp, and
+   * // fractional ones resample the page image
+   * title.resize(3);                 // three times its authored size
+   * title.set("center", 2);          // align and rescale in one call
    */
   resize(scale2) {
     this.fontScale.set(scale2, scale2);
@@ -30972,6 +31659,10 @@ var BitmapText = class extends Renderable {
    * measure the given text size in pixels
    * @param {string} [text]
    * @returns {TextMetrics} a TextMetrics object with two properties: `width` and `height`, defining the output dimensions
+   * @example
+   * // size a panel around a label, at the label's CURRENT scale
+   * const size = label.measureText();
+   * panel.resize(size.width + 16, size.height + 16);
    */
   measureText(text = this._text) {
     return this.metrics.measureText(text);
@@ -34510,6 +35201,21 @@ function initParsers() {
   setParser("shader", preloadShader);
   parserInitialized = true;
 }
+var _app2;
+on(GAME_INIT, (app) => {
+  _app2 = app;
+});
+function runShaderPrewarm() {
+  if (_app2 === void 0 || _app2.settings?.prewarm !== true) {
+    return Promise.resolve();
+  }
+  try {
+    return Promise.resolve(_app2.renderer?.prewarm?.()).catch(() => {
+    });
+  } catch {
+    return Promise.resolve();
+  }
+}
 function completeLoading(onloadcb) {
   const callback = onloadcb || onload;
   if (typeof callback === "function") {
@@ -34553,7 +35259,7 @@ function preload(assets, onloadcb, switchToLoadState = true) {
   if (switchToLoadState === true) {
     state_default.change(state_default.LOADING);
   }
-  return Promise.all(promises).then(() => {
+  return Promise.all(promises).then(runShaderPrewarm).then(() => {
     completeLoading(onload);
   });
 }
@@ -38399,6 +39105,18 @@ var WebGLBatcher = class extends Batcher {
       vertex.clear();
     }
   }
+  /**
+   * Build any shader variant this batcher compiles lazily.
+   *
+   * A batcher whose only program is the one built in its constructor has
+   * nothing to do here — which is every batcher but the mesh one.
+   * @returns {Promise<void>} settles once this batcher is warm
+   * @ignore
+   * @internal
+   */
+  prewarm() {
+    return Promise.resolve();
+  }
 };
 
 // src/video/gpu/primitives.ts
@@ -40544,7 +41262,7 @@ function writeLight3dBlock(out, packed) {
 }
 
 // src/video/webgl/shaders/mesh-lit.frag
-var mesh_lit_default = "#version 300 es\n// Lit mesh fragment shader: half-Lambert diffuse from directional lights\n// plus an ambient floor.\n//\n// GLSL ES 3.00 because the light data arrives in a uniform block, which does\n// not exist in ES 1.00. That is what lifted the light cap: uniform arrays are\n// charged against MAX_FRAGMENT_UNIFORM_VECTORS, a small driver-reported\n// budget, while a block is charged against MAX_UNIFORM_BLOCK_SIZE.\n//\n// `__MAX_LIGHTS__` is replaced with the MAX_LIGHTS constant\n// (src/video/webgl/lighting/constants.ts) by LitMeshBatcher._shaderSources at\n// load time, so the array size can't drift from the uniform packer. (Used\n// directly rather than via a #define so it survives the GLSL preprocessor\n// regardless of how it handles macros.)\n//\n// The block's layout is std140 and is written by\n// src/video/webgl/lighting/std140.ts. The two must agree byte for byte \u2014 a\n// mismatch does not fail to link, it silently shifts every light.\n//\n// No `precision` line here on purpose: `setPrecision` injects float and int\n// precision after `#version`, using whatever the device reports and the\n// application asked for, so shader files don't hardcode it.\n\nuniform sampler2D uSampler;\nuniform float uAlphaCutoff;               // alpha cutout threshold (0 = disabled)\nuniform vec3 uEmissive;                   // self-illumination color (0 = none)\nuniform vec3 uSpecular;                   // specular color (0 = purely diffuse)\nuniform float uShininess;                 // specular exponent (0 = no highlight)\nuniform vec3 uEyePosition;                // camera position, world space\nuniform sampler2D uAlphaMap;              // per-texel opacity (MTL map_d)\nuniform float uHasAlphaMap;               // 0 = uAlphaMap is filler, ignore it\n\n// One light, type inferred from sentinels (see std140.ts):\n// posRange.w < 0 -> directional (dirCone.xyz = surface->light, normalized);\n// otherwise positional at posRange.xyz with quadratic falloff over\n// posRange.w, plus a spot cone when dirCone.w > -1 (dirCone.xyz = the cone\n// axis / travel direction, w = cos(outer), colorInner.w = cos(inner)).\n// colorInner.rgb is premultiplied by intensity.\nstruct Light3dData {\n    vec4 posRange;\n    vec4 dirCone;\n    vec4 colorInner;\n};\n\nlayout(std140) uniform Light3dBlock {\n    // `count` is a float: mixing int and float members would stop the staging\n    // buffer being a single Float32Array view, and the cast below is free. The\n    // vec3 that follows aligns to 16 bytes, so the three floats after `count`\n    // are padding either way.\n    float uLightCount;\n    vec3 uAmbient;\n    Light3dData uLights[__MAX_LIGHTS__];\n};\n\nin vec4 vColor;\nin vec2 vRegion;\nin vec3 vNormal;\nin vec3 vWorldPos;\n#ifdef INSTANCE_DATA\n// per-instance custom slot \u2014 read as emissive by this built-in shading\nin vec4 vInstanceData;\n#endif\n\nout vec4 fragColor;\n\n// Distance fog is a COMPILED VARIANT, not a runtime branch: the batcher\n// injects `#define FOG` only while a camera has fog enabled. A software\n// rasterizer predicates both sides of a branch, so an `exp()` guarded at\n// runtime still costs every fragment of every scene \u2014 including the scenes\n// that never asked for fog.\n#ifdef FOG\nuniform vec3 uFogColor;   // straight (unpremultiplied) fog colour\nuniform vec4 uFogParams;  // x = mode (0 off / 1 linear / 2 exp2),\n                          // y = near, z = 1/(far - near), w = density\nin float vFogDepth;       // radial view-space distance, interpolated\n\n// Fold distance fog into a PREMULTIPLIED colour. Twin of the block in\n// mesh.frag \u2014 keep the two in step; they are duplicated rather than shared\n// because the production build loads each shader as raw text (no preprocessor\n// include), and this shader is ES 3.00 while its twin is ES 1.00.\n//\n// `rgb` is already multiplied by `a`, so the fog colour has to be scaled by\n// the fragment's own coverage. A plain mix toward uFogColor would paint\n// full-strength fog onto near-transparent fragments \u2014 grey halos around every\n// alpha-cutout leaf.\n//\n// Mode 0 returns the input untouched, so a scene with no fog is bit-identical\n// to one built before fog existed.\nvec3 applyFog(vec3 rgb, float a) {\n    float mode = uFogParams.x;\n    if (mode < 0.5) {\n        return rgb;\n    }\n    float f; // fraction of the scene colour that survives\n    if (mode < 1.5) {\n        f = 1.0 - clamp((vFogDepth - uFogParams.y) * uFogParams.z, 0.0, 1.0);\n    } else {\n        float dd = vFogDepth * uFogParams.w;\n        f = exp(-dd * dd);\n    }\n    return mix(uFogColor * a, rgb, f);\n}\n#endif\n\n\n\nvoid main(void) {\n    vec4 base = texture(uSampler, vRegion);\n\n    // per-texel opacity (MTL map_d) multiplies in BEFORE the cutout, so one\n    // material can cut out to the shape of a leaf rather than at a single\n    // threshold across the whole surface. Red channel: the format stores a\n    // greyscale map, and every channel carries the same value.\n    // Sampled unconditionally and WEIGHTED rather than branched: when no map\n    // is bound the second sampler is filler (the diffuse texture), so the\n    // value is thrown away \u2014 and both backends run the identical expression\n    // instead of one branching and the other not.\n    base.a *= mix(1.0, texture(uAlphaMap, vRegion).r, uHasAlphaMap);\n\n    // hard alpha cutout (glTF alphaMode MASK) \u2014 discard before any shading\n    // so cut-away texels cost nothing and never write depth.\n    // Thresholded on the MATERIAL's own alpha, deliberately BEFORE the tint\n    // multiply. The cutout describes the shape of the surface, and that shape\n    // does not change when the object fades: testing the drawn alpha instead\n    // makes a cutout mesh vanish completely the moment its opacity crosses its\n    // own threshold \u2014 and `Sprite3d` defaults that threshold to 0.5, so half a\n    // fade-out was a hard pop.\n    if (base.a < uAlphaCutoff) {\n        discard;\n    }\n    base *= vColor;\n\n    // A mesh marked `lit` with no usable normals \u2014 the 2D-camera path,\n    // which leaves world normals unwritten, or geometry that supplied none \u2014\n    // would normalize a zero vector to NaN and render BLACK. Degrade to\n    // unlit instead: wrong, but recognisably the model rather than a hole.\n    float nLength = length(vNormal);\n    if (nLength < 1e-6) {\n        // the emissive term is built exactly as the lit path below builds\n        // it, per-instance slot included \u2014 degrading to unlit must not also\n        // drop an instance's glow\n        vec3 unlitEmissive = uEmissive;\n#ifdef INSTANCE_DATA\n        unlitEmissive += vInstanceData.rgb;\n#endif\n#ifdef FOG\n        fragColor = vec4(applyFog(base.rgb + unlitEmissive, base.a), base.a);\n#else\n        fragColor = vec4(base.rgb + unlitEmissive, base.a);\n#endif\n        return;\n    }\n    vec3 N = vNormal / nLength;\n    vec3 lit = uAmbient;\n    // Blinn-Phong specular, accumulated alongside the diffuse term. Gated on\n    // the exponent rather than the colour: `Ns` of 0 is the format's \"no\n    // highlight\", and exporters happily write a non-black `Ks` next to it.\n    // The half-vector form (rather than reflect()) is the cheaper of the two\n    // and is what the fixed-function pipeline this format predates used.\n    vec3 specular = vec3(0.0);\n    bool hasSpecular = uShininess > 0.0;\n    vec3 V = hasSpecular ? normalize(uEyePosition - vWorldPos) : vec3(0.0);\n    // ES 3.00 allows a non-constant loop bound, so this runs exactly as many\n    // iterations as there are live lights \u2014 unused capacity costs nothing,\n    // which is what makes a larger cap safe.\n    // clamped to the array size, not just taken on trust: if the block ever\n    // read as something other than what the writer put there, an unbounded\n    // trip count would also index `uLights` out of range\n    int count = min(int(uLightCount), __MAX_LIGHTS__);\n    for (int i = 0; i < count; i++) {\n        vec4 pr = uLights[i].posRange;\n        vec4 dc = uLights[i].dirCone;\n        vec3 L;\n        float atten = 1.0;\n        if (pr.w < 0.0) {\n            // directional: dirCone.xyz is already the surface->light vector\n            L = dc.xyz;\n        } else {\n            // positional: quadratic falloff over range (the Light2d model \u2014\n            // stylized, not physical inverse-square, which is unusable in\n            // pixel-unit worlds with unit intensities)\n            vec3 toLight = pr.xyz - vWorldPos;\n            float dist = max(length(toLight), 1e-4);\n            L = toLight / dist;\n            float linearAtt = max(0.0, 1.0 - dist / pr.w);\n            atten = linearAtt * linearAtt;\n            if (dc.w > -1.0) {\n                // spot cone: -L is the light->surface direction; fade from\n                // the inner cone cosine to the outer\n                float cd = dot(-L, dc.xyz);\n                atten *= smoothstep(dc.w, uLights[i].colorInner.w, cd);\n            }\n        }\n        // Half-Lambert (\"wrap\") diffuse: dot * 0.5 + 0.5. Softens the\n        // terminator and lifts the shadowed side, for a gentler, more\n        // diffuse look than hard Lambert (which reads as harsh noon).\n        float ndl = dot(N, L) * 0.5 + 0.5;\n        lit += uLights[i].colorInner.rgb * (ndl * ndl * atten);\n        if (hasSpecular) {\n            // masked by the UNWRAPPED Lambert term: half-Lambert lifts the\n            // shadowed side, and a highlight on a surface facing away from\n            // the light reads as a rendering error\n            float facing = max(dot(N, L), 0.0);\n            vec3 H = normalize(L + V);\n            float spec = pow(max(dot(N, H), 0.0), uShininess);\n            specular += uLights[i].colorInner.rgb * (spec * facing * atten);\n        }\n    }\n\n    // emissive self-illuminates: added AFTER lighting so it glows at full\n    // strength regardless of the scene lights (neon, lava, glowing eyes).\n    vec3 emissive = uEmissive;\n#ifdef INSTANCE_DATA\n    emissive += vInstanceData.rgb;\n#endif\n#ifdef FOG\n    fragColor = vec4(\n        applyFog(base.rgb * lit + specular * uSpecular + emissive, base.a),\n        base.a\n    );\n#else\n    fragColor = vec4(base.rgb * lit + specular * uSpecular + emissive, base.a);\n#endif\n}\n";
+var mesh_lit_default = "#version 300 es\n// Lit mesh fragment shader: half-Lambert diffuse from directional lights\n// plus an ambient floor.\n//\n// GLSL ES 3.00 because the light data arrives in a uniform block, which does\n// not exist in ES 1.00. That is what lifted the light cap: uniform arrays are\n// charged against MAX_FRAGMENT_UNIFORM_VECTORS, a small driver-reported\n// budget, while a block is charged against MAX_UNIFORM_BLOCK_SIZE.\n//\n// `__MAX_LIGHTS__` is replaced with the MAX_LIGHTS constant\n// (src/video/webgl/lighting/constants.ts) by LitMeshBatcher._shaderSources at\n// load time, so the array size can't drift from the uniform packer. (Used\n// directly rather than via a #define so it survives the GLSL preprocessor\n// regardless of how it handles macros.)\n//\n// The block's layout is std140 and is written by\n// src/video/webgl/lighting/std140.ts. The two must agree byte for byte \u2014 a\n// mismatch does not fail to link, it silently shifts every light.\n//\n// No `precision` line here on purpose: `setPrecision` injects float and int\n// precision after `#version`, using whatever the device reports and the\n// application asked for, so shader files don't hardcode it.\n\nuniform sampler2D uSampler;\nuniform float uAlphaCutoff;               // alpha cutout threshold (0 = disabled)\nuniform vec3 uEmissive;                   // self-illumination color (0 = none)\nuniform vec3 uSpecular;                   // specular color (0 = purely diffuse)\nuniform float uShininess;                 // specular exponent (0 = no highlight)\nuniform vec3 uEyePosition;                // camera position, world space\nuniform sampler2D uAlphaMap;              // per-texel opacity (MTL map_d)\nuniform float uHasAlphaMap;               // 0 = uAlphaMap is filler, ignore it\n\n// One light, type inferred from sentinels (see std140.ts):\n// posRange.w < 0 -> directional (dirCone.xyz = surface->light, normalized);\n// otherwise positional at posRange.xyz with quadratic falloff over\n// posRange.w, plus a spot cone when dirCone.w > -1 (dirCone.xyz = the cone\n// axis / travel direction, w = cos(outer), colorInner.w = cos(inner)).\n// colorInner.rgb is premultiplied by intensity.\nstruct Light3dData {\n    vec4 posRange;\n    vec4 dirCone;\n    vec4 colorInner;\n};\n\nlayout(std140) uniform Light3dBlock {\n    // `count` is a float: mixing int and float members would stop the staging\n    // buffer being a single Float32Array view, and the cast below is free. The\n    // vec3 that follows aligns to 16 bytes, so the three floats after `count`\n    // are padding either way.\n    float uLightCount;\n    vec3 uAmbient;\n    Light3dData uLights[__MAX_LIGHTS__];\n};\n\nin vec4 vColor;\nin vec2 vRegion;\nin vec3 vNormal;\nin vec3 vWorldPos;\n#ifdef INSTANCE_DATA\n// per-instance custom slot \u2014 read as emissive by this built-in shading\nin vec4 vInstanceData;\n#endif\n\nout vec4 fragColor;\n\n// Distance fog is a COMPILED VARIANT, not a runtime branch: the batcher\n// injects `#define FOG` only while a camera has fog enabled. A software\n// rasterizer predicates both sides of a branch, so an `exp()` guarded at\n// runtime still costs every fragment of every scene \u2014 including the scenes\n// that never asked for fog.\n#ifdef FOG\nuniform vec3 uFogColor;   // straight (unpremultiplied) fog colour\nuniform vec4 uFogParams;  // x = mode (0 off / 1 linear / 2 exp2),\n                          // y = near, z = 1/(far - near), w = density\nin float vFogDepth;       // radial view-space distance, interpolated\n\n// Fold distance fog into a PREMULTIPLIED colour. Twin of the block in\n// mesh.frag \u2014 keep the two in step; they are duplicated rather than shared\n// because the production build loads each shader as raw text (no preprocessor\n// include), and this shader is ES 3.00 while its twin is ES 1.00.\n//\n// `rgb` is already multiplied by `a`, so the fog colour has to be scaled by\n// the fragment's own coverage. A plain mix toward uFogColor would paint\n// full-strength fog onto near-transparent fragments \u2014 grey halos around every\n// alpha-cutout leaf.\n//\n// Mode 0 returns the input untouched, so a scene with no fog is bit-identical\n// to one built before fog existed.\nvec3 applyFog(vec3 rgb, float a) {\n    float mode = uFogParams.x;\n    if (mode < 0.5) {\n        return rgb;\n    }\n    float f; // fraction of the scene colour that survives\n    if (mode < 1.5) {\n        f = 1.0 - clamp((vFogDepth - uFogParams.y) * uFogParams.z, 0.0, 1.0);\n    } else {\n        float dd = vFogDepth * uFogParams.w;\n        f = exp(-dd * dd);\n    }\n    return mix(uFogColor * a, rgb, f);\n}\n#endif\n\n\n\n// The mesh-hosted ShaderEffect hook (#1658). Identity by default \u2014 every\n// compiler inlines it away, so an un-effected mesh pays nothing. When an\n// effect is hosted, `spliceEffect` replaces this definition with one that\n// calls the effect's `apply()`, and pastes the effect body above it.\n//\n// Deliberately a FUNCTION and not a marker comment: the shader pipeline\n// strips comments, so a comment cannot be relied on to reach the splicer.\nvec4 ME_effect(vec4 c, vec2 uv) { return c; }\n\nvoid main(void) {\n    vec4 base = texture(uSampler, vRegion);\n\n    // per-texel opacity (MTL map_d) multiplies in BEFORE the cutout, so one\n    // material can cut out to the shape of a leaf rather than at a single\n    // threshold across the whole surface. Red channel: the format stores a\n    // greyscale map, and every channel carries the same value.\n    // Sampled unconditionally and WEIGHTED rather than branched: when no map\n    // is bound the second sampler is filler (the diffuse texture), so the\n    // value is thrown away \u2014 and both backends run the identical expression\n    // instead of one branching and the other not.\n    base.a *= mix(1.0, texture(uAlphaMap, vRegion).r, uHasAlphaMap);\n\n    // hard alpha cutout (glTF alphaMode MASK) \u2014 discard before any shading\n    // so cut-away texels cost nothing and never write depth.\n    // Thresholded on the MATERIAL's own alpha, deliberately BEFORE the tint\n    // multiply. The cutout describes the shape of the surface, and that shape\n    // does not change when the object fades: testing the drawn alpha instead\n    // makes a cutout mesh vanish completely the moment its opacity crosses its\n    // own threshold \u2014 and `Sprite3d` defaults that threshold to 0.5, so half a\n    // fade-out was a hard pop.\n    if (base.a < uAlphaCutoff) {\n        discard;\n    }\n    base *= vColor;\n    base = ME_effect(base, vRegion);\n\n    // A mesh marked `lit` with no usable normals \u2014 the 2D-camera path,\n    // which leaves world normals unwritten, or geometry that supplied none \u2014\n    // would normalize a zero vector to NaN and render BLACK. Degrade to\n    // unlit instead: wrong, but recognisably the model rather than a hole.\n    float nLength = length(vNormal);\n    if (nLength < 1e-6) {\n        // the emissive term is built exactly as the lit path below builds\n        // it, per-instance slot included \u2014 degrading to unlit must not also\n        // drop an instance's glow\n        vec3 unlitEmissive = uEmissive;\n#ifdef INSTANCE_DATA\n        unlitEmissive += vInstanceData.rgb;\n#endif\n#ifdef FOG\n        fragColor = vec4(applyFog(base.rgb + unlitEmissive, base.a), base.a);\n#else\n        fragColor = vec4(base.rgb + unlitEmissive, base.a);\n#endif\n        return;\n    }\n    vec3 N = vNormal / nLength;\n    vec3 lit = uAmbient;\n    // Blinn-Phong specular, accumulated alongside the diffuse term. Gated on\n    // the exponent rather than the colour: `Ns` of 0 is the format's \"no\n    // highlight\", and exporters happily write a non-black `Ks` next to it.\n    // The half-vector form (rather than reflect()) is the cheaper of the two\n    // and is what the fixed-function pipeline this format predates used.\n    vec3 specular = vec3(0.0);\n    bool hasSpecular = uShininess > 0.0;\n    vec3 V = hasSpecular ? normalize(uEyePosition - vWorldPos) : vec3(0.0);\n    // ES 3.00 allows a non-constant loop bound, so this runs exactly as many\n    // iterations as there are live lights \u2014 unused capacity costs nothing,\n    // which is what makes a larger cap safe.\n    // clamped to the array size, not just taken on trust: if the block ever\n    // read as something other than what the writer put there, an unbounded\n    // trip count would also index `uLights` out of range\n    int count = min(int(uLightCount), __MAX_LIGHTS__);\n    for (int i = 0; i < count; i++) {\n        vec4 pr = uLights[i].posRange;\n        vec4 dc = uLights[i].dirCone;\n        vec3 L;\n        float atten = 1.0;\n        if (pr.w < 0.0) {\n            // directional: dirCone.xyz is already the surface->light vector\n            L = dc.xyz;\n        } else {\n            // positional: quadratic falloff over range (the Light2d model \u2014\n            // stylized, not physical inverse-square, which is unusable in\n            // pixel-unit worlds with unit intensities)\n            vec3 toLight = pr.xyz - vWorldPos;\n            float dist = max(length(toLight), 1e-4);\n            L = toLight / dist;\n            float linearAtt = max(0.0, 1.0 - dist / pr.w);\n            atten = linearAtt * linearAtt;\n            if (dc.w > -1.0) {\n                // spot cone: -L is the light->surface direction; fade from\n                // the inner cone cosine to the outer\n                float cd = dot(-L, dc.xyz);\n                atten *= smoothstep(dc.w, uLights[i].colorInner.w, cd);\n            }\n        }\n        // Half-Lambert (\"wrap\") diffuse: dot * 0.5 + 0.5. Softens the\n        // terminator and lifts the shadowed side, for a gentler, more\n        // diffuse look than hard Lambert (which reads as harsh noon).\n        float ndl = dot(N, L) * 0.5 + 0.5;\n        lit += uLights[i].colorInner.rgb * (ndl * ndl * atten);\n        if (hasSpecular) {\n            // masked by the UNWRAPPED Lambert term: half-Lambert lifts the\n            // shadowed side, and a highlight on a surface facing away from\n            // the light reads as a rendering error\n            float facing = max(dot(N, L), 0.0);\n            vec3 H = normalize(L + V);\n            float spec = pow(max(dot(N, H), 0.0), uShininess);\n            specular += uLights[i].colorInner.rgb * (spec * facing * atten);\n        }\n    }\n\n    // emissive self-illuminates: added AFTER lighting so it glows at full\n    // strength regardless of the scene lights (neon, lava, glowing eyes).\n    vec3 emissive = uEmissive;\n#ifdef INSTANCE_DATA\n    emissive += vInstanceData.rgb;\n#endif\n#ifdef FOG\n    fragColor = vec4(\n        applyFog(base.rgb * lit + specular * uSpecular + emissive, base.a),\n        base.a\n    );\n#else\n    fragColor = vec4(base.rgb * lit + specular * uSpecular + emissive, base.a);\n#endif\n}\n";
 
 // src/video/webgl/shaders/mesh-lit.vert
 var mesh_lit_default2 = "#version 300 es\n// Lit mesh vertex shader (Camera3d + Light3d) \u2014 retained-mode.\n//\n// GLSL ES 3.00 because the fragment stage reads light data from a uniform\n// block, which does not exist in ES 1.00. Both stages of a program must share\n// a dialect, so the vertex shader follows.\n//\n// Same placement as mesh.vert (clip = projection \xD7 view \xD7 model \xD7 vertex,\n// vertices in MODEL space) plus a normal carried to the fragment shader in\n// world space for diffuse shading.\nin vec3 aVertex;\nin vec2 aRegion;\nin vec4 aColor;\n// Model-space normal, rotated into world space below.\nin vec3 aNormal;\n\nuniform mat4 uProjectionMatrix;\nuniform mat4 uViewMatrix;\nuniform mat4 uModelMatrix;\nuniform vec4 uTint;\n\nout vec2 vRegion;\nout vec4 vColor;\nout vec3 vNormal;\n// world-space fragment position \u2014 positional lights (point / spot) fall\n// off with distance, so the fragment stage needs where the surface IS\nout vec3 vWorldPos;\n#ifdef FOG\nout float vFogDepth;\n#endif\n\n#ifdef FOG\nuniform vec4 uFogHeight;  // xyz = falloff x world-up axis, in VIEW space;\n                          // w = exp(k * (cameraY - fogHeight)), pre-baked\n\n// How much the height falloff scales the fog along this view ray.\n//\n// Density falls off exponentially with altitude, and an exponential integrates\n// analytically along a straight segment, so the whole ray costs one `exp` and\n// no marching. The result multiplies the distance, which leaves both fog\n// curves exactly as they are.\n//\n// Takes the VIEW-space position, not a height. The only position this stage\n// has is pre-view \u2014 `uModelMatrix * position` \u2014 and that is the mesh's parent\n// space rather than the world, because `Container.draw` folds every ancestor\n// into the view matrix. Reading a height straight off it put the fog floor at\n// the wrong altitude for anything under a scaled container. Dotting the\n// view-space position against the world-up axis expressed in view space gives\n// the height above the camera whatever those ancestors did, since they are\n// inside the very matrix that produced this position. `uFogHeight.xyz`\n// carries the falloff too, so the exponent is one dot product.\n//\n// Render space is Y-DOWN: density rises as height INCREASES, the opposite\n// sign to every published form of this. The axis is signed that way round,\n// and there is a test that catches it being flipped.\n//\n// A falloff of 0 gives exactly 1: the axis is all zero, so `kdy` is 0, the\n// series limit is taken, and the pre-baked term is exp(0) \u2014 uniform fog is\n// not a special case, it is this with the dial at zero.\nfloat fogHeightFactor(vec3 viewPos) {\n    float kdy = dot(uFogHeight.xyz, viewPos);\n    // (exp(x) - 1) / x is 0/0 at x = 0, and a horizontal view ray \u2014 looking\n    // straight across a valley \u2014 is exactly that case. Take the limit rather\n    // than guarding, or the fog steps as the ray approaches horizontal.\n    float t = abs(kdy) < 1e-4 ? 1.0 : (exp(kdy) - 1.0) / kdy;\n    return uFogHeight.w * t;\n}\n#endif\n\nvoid main(void) {\n    vec4 worldPos = uModelMatrix * vec4(aVertex, 1.0);\n    gl_Position = uProjectionMatrix * uViewMatrix * worldPos;\n    vWorldPos = worldPos.xyz;\n#ifdef FOG\n    // Radial view-space distance for distance fog. Radial rather than view-space\n    // z, so fog holds steady as the camera turns instead of sliding across the\n    // scene. The clip position above keeps its own product: re-associating it\n    // could shift vertices by an ulp, and a scene without fog must be unchanged.\n    vec3 viewPos = (uViewMatrix * worldPos).xyz;\n    vFogDepth = length(viewPos) * fogHeightFactor(viewPos);\n#endif\n    vec4 tinted = aColor * uTint;\n    vColor = vec4(tinted.rgb * tinted.a, tinted.a);\n    vRegion = aRegion;\n    // Rotate the normal into world space with the model matrix's upper 3\xD73.\n    // Lighting is evaluated in world space, so the view transform is\n    // deliberately excluded. Uniform scale cancels when the fragment shader\n    // renormalizes; non-uniform scale is approximated \u2014 unchanged behaviour,\n    // an exact result would need the inverse-transpose.\n    vNormal = mat3(uModelMatrix) * aNormal;\n}\n";
@@ -40744,7 +41462,7 @@ function vertexDataExceedsUint16(indices) {
 }
 
 // src/video/webgl/shaders/mesh.frag
-var mesh_default = "uniform sampler2D uSampler;\nuniform float uAlphaCutoff;   // alpha cutout threshold (0 = disabled)\nuniform vec3 uEmissive;       // self-illumination color added on top (0 = none)\nuniform sampler2D uAlphaMap;  // per-texel opacity (MTL map_d)\nuniform float uHasAlphaMap;   // 0 = uAlphaMap is filler, ignore it\nvarying vec4 vColor;\nvarying vec2 vRegion;\n// Distance fog is a COMPILED VARIANT, not a runtime branch: the batcher\n// injects `#define FOG` only while a camera has fog enabled. A software\n// rasterizer predicates both sides of a branch, so an `exp()` guarded at\n// runtime still costs every fragment of every scene \u2014 including the scenes\n// that never asked for fog.\n#ifdef FOG\nuniform vec3 uFogColor;   // straight (unpremultiplied) fog colour\nuniform vec4 uFogParams;  // x = mode (0 off / 1 linear / 2 exp2),\n                          // y = near, z = 1/(far - near), w = density\nvarying float vFogDepth;  // radial view-space distance, interpolated\n\n// Fold distance fog into a PREMULTIPLIED colour.\n//\n// `rgb` here is already multiplied by `a` (the vertex stage premultiplies\n// vColor), so the fog colour has to be scaled by the fragment's own coverage.\n// A plain mix toward uFogColor would paint full-strength fog onto\n// near-transparent fragments \u2014 grey halos around every alpha-cutout leaf, and\n// unattenuated fog added on the blended shadow pass.\n//\n// Mode 0 returns the input untouched, so a scene with no fog is bit-identical\n// to one built before fog existed.\nvec3 applyFog(vec3 rgb, float a) {\n    float mode = uFogParams.x;\n    if (mode < 0.5) {\n        return rgb;\n    }\n    float f; // fraction of the scene colour that survives\n    if (mode < 1.5) {\n        // linear: 1 at `near`, reaching 0 at `far`\n        f = 1.0 - clamp((vFogDepth - uFogParams.y) * uFogParams.z, 0.0, 1.0);\n    } else {\n        // exponential squared: survival = exp(-(density * d)^2)\n        float dd = vFogDepth * uFogParams.w;\n        f = exp(-dd * dd);\n    }\n    return mix(uFogColor * a, rgb, f);\n}\n#endif\n\n\n#ifdef INSTANCE_DATA\n// per-instance custom slot. The built-in shading reads its rgb as emissive,\n// so a forest can glow per tree without a uniform per instance; a CUSTOM mesh\n// shader is free to read the same slot as anything else entirely.\nvarying vec4 vInstanceData;\n#endif\n\nvoid main(void) {\n    vec4 texel = texture2D(uSampler, vRegion);\n    // per-texel opacity (MTL map_d) multiplies in BEFORE the cutout, so one\n    // material can cut out to the shape of a leaf rather than at a single\n    // threshold across the whole surface. Red channel: the format stores a\n    // greyscale map, and every channel carries the same value.\n    // Sampled unconditionally and WEIGHTED rather than branched: when no map\n    // is bound the second sampler is filler (the diffuse texture), so the\n    // value is thrown away \u2014 and both backends run the identical expression\n    // instead of one branching and the other not.\n    texel.a *= mix(1.0, texture2D(uAlphaMap, vRegion).r, uHasAlphaMap);\n    // hard alpha cutout (glTF alphaMode MASK): drop fully-transparent texels\n    // so foliage / fences / decals read crisp without blending or sorting.\n    // Thresholded on the MATERIAL's own alpha, deliberately BEFORE the tint\n    // multiply. The cutout describes the shape of the surface, and that shape\n    // does not change when the object fades: testing the drawn alpha instead\n    // makes a cutout mesh vanish completely the moment its opacity crosses its\n    // own threshold \u2014 and `Sprite3d` defaults that threshold to 0.5, so half a\n    // fade-out was a hard pop.\n    if (texel.a < uAlphaCutoff) {\n        discard;\n    }\n    vec4 color = texel * vColor;\n    // emissive adds a self-lit color on top (neon, lava, screens); the unlit\n    // path has no lighting, so it's simply added to the base color.\n    vec3 emissive = uEmissive;\n#ifdef INSTANCE_DATA\n    emissive += vInstanceData.rgb;\n#endif\n#ifdef FOG\n    gl_FragColor = vec4(applyFog(color.rgb + emissive, color.a), color.a);\n#else\n    gl_FragColor = vec4(color.rgb + emissive, color.a);\n#endif\n}\n";
+var mesh_default = "uniform sampler2D uSampler;\nuniform float uAlphaCutoff;   // alpha cutout threshold (0 = disabled)\nuniform vec3 uEmissive;       // self-illumination color added on top (0 = none)\nuniform sampler2D uAlphaMap;  // per-texel opacity (MTL map_d)\nuniform float uHasAlphaMap;   // 0 = uAlphaMap is filler, ignore it\nvarying vec4 vColor;\nvarying vec2 vRegion;\n// Distance fog is a COMPILED VARIANT, not a runtime branch: the batcher\n// injects `#define FOG` only while a camera has fog enabled. A software\n// rasterizer predicates both sides of a branch, so an `exp()` guarded at\n// runtime still costs every fragment of every scene \u2014 including the scenes\n// that never asked for fog.\n#ifdef FOG\nuniform vec3 uFogColor;   // straight (unpremultiplied) fog colour\nuniform vec4 uFogParams;  // x = mode (0 off / 1 linear / 2 exp2),\n                          // y = near, z = 1/(far - near), w = density\nvarying float vFogDepth;  // radial view-space distance, interpolated\n\n// Fold distance fog into a PREMULTIPLIED colour.\n//\n// `rgb` here is already multiplied by `a` (the vertex stage premultiplies\n// vColor), so the fog colour has to be scaled by the fragment's own coverage.\n// A plain mix toward uFogColor would paint full-strength fog onto\n// near-transparent fragments \u2014 grey halos around every alpha-cutout leaf, and\n// unattenuated fog added on the blended shadow pass.\n//\n// Mode 0 returns the input untouched, so a scene with no fog is bit-identical\n// to one built before fog existed.\nvec3 applyFog(vec3 rgb, float a) {\n    float mode = uFogParams.x;\n    if (mode < 0.5) {\n        return rgb;\n    }\n    float f; // fraction of the scene colour that survives\n    if (mode < 1.5) {\n        // linear: 1 at `near`, reaching 0 at `far`\n        f = 1.0 - clamp((vFogDepth - uFogParams.y) * uFogParams.z, 0.0, 1.0);\n    } else {\n        // exponential squared: survival = exp(-(density * d)^2)\n        float dd = vFogDepth * uFogParams.w;\n        f = exp(-dd * dd);\n    }\n    return mix(uFogColor * a, rgb, f);\n}\n#endif\n\n\n#ifdef INSTANCE_DATA\n// per-instance custom slot. The built-in shading reads its rgb as emissive,\n// so a forest can glow per tree without a uniform per instance; a CUSTOM mesh\n// shader is free to read the same slot as anything else entirely.\nvarying vec4 vInstanceData;\n#endif\n\n// The mesh-hosted ShaderEffect hook (#1658). Identity by default \u2014 every\n// compiler inlines it away, so an un-effected mesh pays nothing. When an\n// effect is hosted, `spliceEffect` replaces this definition with one that\n// calls the effect's `apply()`, and pastes the effect body above it.\n//\n// Deliberately a FUNCTION and not a marker comment: the shader pipeline\n// strips comments, so a comment cannot be relied on to reach the splicer.\nvec4 ME_effect(vec4 c, vec2 uv) { return c; }\n\nvoid main(void) {\n    vec4 texel = texture2D(uSampler, vRegion);\n    // per-texel opacity (MTL map_d) multiplies in BEFORE the cutout, so one\n    // material can cut out to the shape of a leaf rather than at a single\n    // threshold across the whole surface. Red channel: the format stores a\n    // greyscale map, and every channel carries the same value.\n    // Sampled unconditionally and WEIGHTED rather than branched: when no map\n    // is bound the second sampler is filler (the diffuse texture), so the\n    // value is thrown away \u2014 and both backends run the identical expression\n    // instead of one branching and the other not.\n    texel.a *= mix(1.0, texture2D(uAlphaMap, vRegion).r, uHasAlphaMap);\n    // hard alpha cutout (glTF alphaMode MASK): drop fully-transparent texels\n    // so foliage / fences / decals read crisp without blending or sorting.\n    // Thresholded on the MATERIAL's own alpha, deliberately BEFORE the tint\n    // multiply. The cutout describes the shape of the surface, and that shape\n    // does not change when the object fades: testing the drawn alpha instead\n    // makes a cutout mesh vanish completely the moment its opacity crosses its\n    // own threshold \u2014 and `Sprite3d` defaults that threshold to 0.5, so half a\n    // fade-out was a hard pop.\n    if (texel.a < uAlphaCutoff) {\n        discard;\n    }\n    vec4 color = texel * vColor;\n    color = ME_effect(color, vRegion);\n    // emissive adds a self-lit color on top (neon, lava, screens); the unlit\n    // path has no lighting, so it's simply added to the base color.\n    vec3 emissive = uEmissive;\n#ifdef INSTANCE_DATA\n    emissive += vInstanceData.rgb;\n#endif\n#ifdef FOG\n    gl_FragColor = vec4(applyFog(color.rgb + emissive, color.a), color.a);\n#else\n    gl_FragColor = vec4(color.rgb + emissive, color.a);\n#endif\n}\n";
 
 // src/video/webgl/shaders/mesh.vert
 var mesh_default2 = "// Mesh vertex shader (retained-mode).\n//\n// Vertices arrive in MODEL space and are placed by uniforms rather than by\n// CPU-side transformation, so moving/rotating/scaling a mesh costs a uniform\n// update instead of re-uploading its geometry:\n//\n//   clip = projection \xD7 view \xD7 model \xD7 vertex\n//\n// `uModelMatrix` carries the mesh's own transform (including the Y/Z axis\n// bridge and mesh scale); `uViewMatrix` carries the camera view plus any\n// ancestor container transform. Both are always written before a draw \u2014 the\n// accumulation path (2D camera, vertices pre-projected on the CPU) pushes\n// identity explicitly. Note GLSL uniforms default to ZERO, not identity, so a\n// path that reached this shader without setting them would collapse every\n// vertex onto the origin rather than drawing untransformed.\nattribute vec3 aVertex;\nattribute vec2 aRegion;\nattribute vec4 aColor;\n\nuniform mat4 uProjectionMatrix;\nuniform mat4 uViewMatrix;\nuniform mat4 uModelMatrix;\n// Per-draw tint \xD7 global alpha. Kept out of the vertex data so that changing\n// a mesh's tint never invalidates its retained geometry.\nuniform vec4 uTint;\n\nvarying vec2 vRegion;\nvarying vec4 vColor;\n#ifdef FOG\nvarying float vFogDepth;\n#endif\n\n#ifdef FOG\nuniform vec4 uFogHeight;  // xyz = falloff x world-up axis, in VIEW space;\n                          // w = exp(k * (cameraY - fogHeight)), pre-baked\n\n// How much the height falloff scales the fog along this view ray.\n//\n// Density falls off exponentially with altitude, and an exponential integrates\n// analytically along a straight segment, so the whole ray costs one `exp` and\n// no marching. The result multiplies the distance, which leaves both fog\n// curves exactly as they are.\n//\n// Takes the VIEW-space position, not a height. The only position this stage\n// has is pre-view \u2014 `uModelMatrix * position` \u2014 and that is the mesh's parent\n// space rather than the world, because `Container.draw` folds every ancestor\n// into the view matrix. Reading a height straight off it put the fog floor at\n// the wrong altitude for anything under a scaled container. Dotting the\n// view-space position against the world-up axis expressed in view space gives\n// the height above the camera whatever those ancestors did, since they are\n// inside the very matrix that produced this position. `uFogHeight.xyz`\n// carries the falloff too, so the exponent is one dot product.\n//\n// Render space is Y-DOWN: density rises as height INCREASES, the opposite\n// sign to every published form of this. The axis is signed that way round,\n// and there is a test that catches it being flipped.\n//\n// A falloff of 0 gives exactly 1: the axis is all zero, so `kdy` is 0, the\n// series limit is taken, and the pre-baked term is exp(0) \u2014 uniform fog is\n// not a special case, it is this with the dial at zero.\nfloat fogHeightFactor(vec3 viewPos) {\n    float kdy = dot(uFogHeight.xyz, viewPos);\n    // (exp(x) - 1) / x is 0/0 at x = 0, and a horizontal view ray \u2014 looking\n    // straight across a valley \u2014 is exactly that case. Take the limit rather\n    // than guarding, or the fog steps as the ray approaches horizontal.\n    float t = abs(kdy) < 1e-4 ? 1.0 : (exp(kdy) - 1.0) / kdy;\n    return uFogHeight.w * t;\n}\n#endif\n\nvoid main(void) {\n    gl_Position =\n        uProjectionMatrix * uViewMatrix * uModelMatrix * vec4(aVertex, 1.0);\n#ifdef FOG\n    // Radial view-space distance for distance fog. Radial rather than view-space\n    // z, so fog holds steady as the camera turns instead of sliding across the\n    // scene. The clip position above keeps its own product: re-associating it\n    // could shift vertices by an ulp, and a scene without fog must be unchanged.\n    vec4 viewPos = uViewMatrix * uModelMatrix * vec4(aVertex, 1.0);\n    vFogDepth = length(viewPos.xyz) * fogHeightFactor(viewPos.xyz);\n#endif\n    // tint first, then premultiply \u2014 matches the fragment shader's expectation\n    vec4 tinted = aColor * uTint;\n    vColor = vec4(tinted.rgb * tinted.a, tinted.a);\n    vRegion = aRegion;\n}\n";
@@ -41314,6 +42032,99 @@ var MeshBatcher = class extends MaterialBatcher {
       fragmentDefines
     );
   }
+  /**
+   * The program that hosts a `ShaderEffect` on a mesh (#1658).
+   *
+   * A ShaderEffect is realized against the QUAD contract — its vertex stage
+   * projects straight from `uProjectionMatrix` and declares neither
+   * `uModelMatrix` nor `uViewMatrix` — so it cannot be bound to a mesh as-is:
+   * the geometry arrives in model space and would draw unplaced and without
+   * the camera (the very case `validateShaderLocations` warns about). Instead
+   * the body is spliced into THIS batcher's own mesh shader, so the mesh keeps
+   * its placement, alpha cutout, lighting and fog and the effect becomes a
+   * colour hook over the result.
+   *
+   * Keyed through the same variant map as every other permutation, so it is
+   * released on context loss and destroy along with the rest — and keyed on
+   * fog too, since the spliced source inherits the fog `#define`.
+   * @param {object} effect - the hosted ShaderEffect
+   * @returns {GLShader} the spliced program
+   * @ignore
+   * @internal
+   */
+  effectShaderFor(effect) {
+    const fog = this._fogDefine();
+    const sources = this._shaderSources();
+    const fragment2 = spliceEffect(sources.fragment, effect._meshBody);
+    if (fragment2 === null) {
+      return null;
+    }
+    const compat = /^\s*#version\s+300\s+es/m.test(sources.fragment) ? "#define texture2D texture\n" : "";
+    try {
+      return this.shaderVariant(
+        `effect|${effect._effectId}|${fog !== "" ? 1 : 0}`,
+        { vertex: sources.vertex, fragment: fragment2 },
+        fog,
+        fog + compat
+      );
+    } catch (error) {
+      if (this._meshEffectCompileWarned !== true) {
+        this._meshEffectCompileWarned = true;
+        console.warn(
+          `melonJS: this ShaderEffect failed to compile against the mesh shader \u2014 ${error instanceof Error ? error.message : String(error)}. The mesh draws with the built-in shading.`
+        );
+      }
+      return null;
+    }
+  }
+  /**
+   * Bring a spliced program up to date with the effect's uniforms.
+   *
+   * `ShaderEffect.setUniform` writes into the effect's OWN quad program;
+   * this one is a different program, so every value the effect has ever been
+   * given is replayed onto it. Unknown names are skipped rather than passed
+   * on: `GLShader.setUniform` throws on one, and a body is free to declare
+   * uniforms the spliced mesh source optimised away.
+   * @param {object} effect - the hosted ShaderEffect
+   * @param {GLShader} shader - the spliced program
+   * @ignore
+   * @internal
+   */
+  replayEffectUniforms(effect, shader) {
+    for (const [name, value] of effect._uniformValues) {
+      if (shader.uniforms[name] !== void 0) {
+        shader.setUniform(name, value);
+      }
+    }
+  }
+  /**
+   * Whether this batcher can host `effect`, warning once when it cannot.
+   * @param {object} effect - the candidate ShaderEffect
+   * @returns {boolean} true when the effect can be spliced in
+   * @ignore
+   * @internal
+   */
+  canHostEffect(effect) {
+    if (typeof effect._meshBody !== "string") {
+      return false;
+    }
+    if (!hasSpliceMarkers(this._shaderSources().fragment)) {
+      return false;
+    }
+    const blocker = meshHostingBlocker(effect._meshBuiltins, [
+      ...effect._extraTextures?.keys() ?? []
+    ]);
+    if (blocker === null) {
+      return true;
+    }
+    if (this._meshEffectBlockedWarned !== true) {
+      this._meshEffectBlockedWarned = true;
+      console.warn(
+        `melonJS: this ShaderEffect cannot be hosted on a Mesh \u2014 ${blocker}. The mesh draws with the built-in shading.`
+      );
+    }
+    return false;
+  }
   /**
    * `"#define FOG\n"` while the camera drawing has fog, `""` otherwise.
    *
@@ -41359,6 +42170,71 @@ var MeshBatcher = class extends MaterialBatcher {
     }
     return shader;
   }
+  /**
+   * Build every shader variant this batcher can reach, so none of them is
+   * compiled on the frame a scene first draws.
+   *
+   * The set is enumerable because each variant is a source permutation, not
+   * a runtime branch: fog on or off, and the three instance-record slots.
+   * That is 1 fogged mesh + 8 instanced + 2 ground-shadow programs; the
+   * plain mesh program is built in the constructor and is already here.
+   *
+   * Yields between programs. Linking is synchronous in WebGL and a dozen
+   * links in one task is a dropped frame — which on a loading screen is a
+   * stuttering progress bar, trading one visible hitch for another.
+   * @returns {Promise<void>} settles once every variant is linked
+   * @ignore
+   * @internal
+   */
+  async prewarm() {
+    const yieldToFrame = () => {
+      if (globalThis.document?.hidden === true) {
+        return Promise.resolve();
+      }
+      return new Promise((resolve) => {
+        setTimeout(resolve, 0);
+      });
+    };
+    const alive = () => {
+      return this.gl !== null && this.gl?.isContextLost?.() !== true;
+    };
+    const sources = this._shaderSources();
+    const instanced = this._instancedShaderSources();
+    for (const fogDefine of ["", "#define FOG\n"]) {
+      if (fogDefine !== "") {
+        this.shaderVariant("mesh|fog", sources, fogDefine, fogDefine);
+        await yieldToFrame();
+        if (!alive()) {
+          return;
+        }
+      }
+      for (const hasColor of [false, true]) {
+        for (const hasData of [false, true]) {
+          const key = (hasColor ? 1 : 0) | (hasData ? 2 : 0) | (fogDefine !== "" ? 4 : 0);
+          this.shaderVariant(
+            `instanced|${key}`,
+            instanced,
+            (hasColor ? "#define INSTANCE_COLORS\n" : "") + (hasData ? "#define INSTANCE_DATA\n" : "") + fogDefine,
+            (hasData ? "#define INSTANCE_DATA\n" : "") + fogDefine
+          );
+          await yieldToFrame();
+          if (!alive()) {
+            return;
+          }
+        }
+      }
+      this.shaderVariant(
+        fogDefine === "" ? "shadow" : "shadow|fog",
+        { vertex: mesh_shadow_instanced_default, fragment: mesh_default },
+        fogDefine,
+        fogDefine
+      );
+      await yieldToFrame();
+      if (!alive()) {
+        return;
+      }
+    }
+  }
   /**
    * Whether the bound program is one this batcher would pick for a plain
    * mesh — its own, or the fog variant of its own.
@@ -43632,6 +44508,7 @@ var WebGLRenderer = class _WebGLRenderer extends Renderer {
     this.onContextRestoredInvalidate = (renderer) => {
       if (renderer === this) {
         this.currentProgram = void 0;
+        this._prewarmed = void 0;
       }
     };
     this.onCanvasResize = (width, height) => {
@@ -43715,6 +44592,29 @@ var WebGLRenderer = class _WebGLRenderer extends Renderer {
       batcher.releaseRetained?.(mesh);
     });
   }
+  /**
+   * Compile every shader variant the built-in batchers can reach.
+   *
+   * A WebGL batcher builds its own program in its constructor, so the base
+   * programs are already linked by the time `init()` resolves. What is not
+   * is the mesh batcher's permutations — fog, and the three instance-record
+   * slots — which are built on first use and so land on the frame a 3D
+   * scene first draws.
+   * @returns {Promise<void>} settles once every variant is linked
+   * @see {@link Renderer#prewarm}
+   */
+  prewarm() {
+    if (this._prewarmed === void 0) {
+      this._prewarmed = Promise.all(
+        [...this.batchers.values()].map((batcher) => {
+          return batcher.prewarm();
+        })
+      ).then(() => {
+        this.setBatcher("quad");
+      });
+    }
+    return this._prewarmed;
+  }
   destroy() {
     off(GAME_RESET, this.onGameReset);
     off(ONCONTEXT_RESTORED, this.onContextRestoredInvalidate);
@@ -44841,8 +45741,14 @@ var WebGLRenderer = class _WebGLRenderer extends Renderer {
       return;
     }
     this.setBatcher(mesh.lit === true ? "litMesh" : "mesh");
-    const hostedShader = this.customShader != null && this.customShader.program != null;
+    const effectHosted = this.customShader != null && this.currentBatcher.canHostEffect?.(this.customShader) === true;
+    const spliced = effectHosted ? this.currentBatcher.effectShaderFor(this.customShader) : null;
+    let hostedShader = spliced !== null && spliced !== void 0;
     if (hostedShader) {
+      this.currentBatcher.useShader(spliced);
+      this.currentBatcher.replayEffectUniforms(this.customShader, spliced);
+    } else if (this.customShader != null && this.customShader.program != null) {
+      hostedShader = true;
       this.currentBatcher.useShader(this.customShader);
     } else if (this.customShader != null && this.customShader.isWebGL !== true && this._meshShaderWarned !== true) {
       this._meshShaderWarned = true;
@@ -46598,8 +47504,8 @@ var Pointer = class extends Bounds {
     this.isPrimary = typeof event.isPrimary !== "undefined" ? event.isPrimary : true;
     this.button = event.button || 0;
     this.type = event.type;
-    if (typeof _app2?.viewport !== "undefined") {
-      _app2.viewport.localToWorld(this.gameScreenX, this.gameScreenY, tmpVec);
+    if (typeof _app3?.viewport !== "undefined") {
+      _app3.viewport.localToWorld(this.gameScreenX, this.gameScreenY, tmpVec);
     }
     this.gameWorldX = tmpVec.x;
     this.gameWorldY = tmpVec.y;
@@ -46620,9 +47526,9 @@ var pointer_default = Pointer;
 var T_POINTERS = [];
 var eventHandlers = /* @__PURE__ */ new Map();
 var currentPointer;
-var _app2;
+var _app3;
 on(GAME_INIT, (app) => {
-  _app2 = app;
+  _app3 = app;
 });
 var pointerInitialized = false;
 var lastTimeStamp = 0;
@@ -46686,7 +47592,7 @@ function registerEventListener(eventList, callback) {
 }
 function enablePointerEvent() {
   if (!pointerInitialized) {
-    if (!_app2) {
+    if (!_app3) {
       throw new Error("Pointer events require an initialized Application");
     }
     currentPointer = new Rect(0, 0, 1, 1);
@@ -46694,7 +47600,7 @@ function enablePointerEvent() {
       T_POINTERS.push(new pointer_default());
     }
     if (pointerEventTarget === null || pointerEventTarget === void 0) {
-      pointerEventTarget = _app2.renderer.getCanvas();
+      pointerEventTarget = _app3.renderer.getCanvas();
     }
     if (pointerEvent) {
       activeEventList = pointerEventList;
@@ -46748,7 +47654,7 @@ function enablePointerEvent() {
       globalThis.document.addEventListener(
         POINTERLOCKCHANGE,
         () => {
-          locked = globalThis.document.pointerLockElement === _app2.getParentElement();
+          locked = globalThis.document.pointerLockElement === _app3.getParentElement();
           emit(POINTERLOCKCHANGE, locked);
         },
         true
@@ -46798,7 +47704,7 @@ function dispatchEvent(normalizedEvents2) {
       }
       lastTimeStamp = pointer2.event.timeStamp;
     }
-    const worldOffset = _app2.world.pos;
+    const worldOffset = _app3.world.pos;
     const absoluteWorldX = pointer2.gameWorldX + worldOffset.x;
     const absoluteWorldY = pointer2.gameWorldY + worldOffset.y;
     currentPointer.pos.set(pointer2.gameWorldX, pointer2.gameWorldY);
@@ -46808,16 +47714,16 @@ function dispatchEvent(normalizedEvents2) {
       pointer2.gameY = pointer2.gameLocalY = pointer2.gameScreenY;
       emit(POINTERMOVE, pointer2);
     }
-    let candidates = _app2.world.broadphase.retrieve(
+    let candidates = _app3.world.broadphase.retrieve(
       currentPointer,
-      (a, b) => _app2.world._sortReverseZ(a, b),
+      (a, b) => _app3.world._sortReverseZ(a, b),
       void 0
     );
     if (worldOffset.x !== 0 || worldOffset.y !== 0) {
       currentPointer.pos.set(absoluteWorldX, absoluteWorldY);
-      const absoluteCandidates = _app2.world.broadphase.retrieve(
+      const absoluteCandidates = _app3.world.broadphase.retrieve(
         currentPointer,
-        (a, b) => _app2.world._sortReverseZ(a, b),
+        (a, b) => _app3.world._sortReverseZ(a, b),
         void 0
       );
       for (const candidate of candidates) {
@@ -46826,10 +47732,10 @@ function dispatchEvent(normalizedEvents2) {
         }
       }
       candidates = absoluteCandidates.sort(
-        (a, b) => _app2.world._sortReverseZ(a, b)
+        (a, b) => _app3.world._sortReverseZ(a, b)
       );
     }
-    candidates = candidates.concat([_app2.viewport]);
+    candidates = candidates.concat([_app3.viewport]);
     for (let c = candidates.length, candidate; c--, candidate = candidates[c]; ) {
       if (eventHandlers.has(candidate) && candidate.isKinematic !== true) {
         const handlers = eventHandlers.get(candidate);
@@ -46992,11 +47898,11 @@ function hasRegisteredEvents() {
 }
 function globalToLocal(x, y, v) {
   v = v || vector2dPool.get();
-  const rect = getElementBounds(_app2.renderer.getCanvas());
+  const rect = getElementBounds(_app3.renderer.getCanvas());
   const pixelRatio = globalThis.devicePixelRatio || 1;
   x -= rect.left + (globalThis.pageXOffset || 0);
   y -= rect.top + (globalThis.pageYOffset || 0);
-  const scale2 = _app2.renderer.scaleRatio;
+  const scale2 = _app3.renderer.scaleRatio;
   if (scale2.x !== 1 || scale2.y !== 1) {
     x /= scale2.x;
     y /= scale2.y;
@@ -47088,7 +47994,7 @@ function releaseAllPointerEvents(region) {
 }
 function requestPointerLock() {
   if (hasPointerLockSupport) {
-    const element = _app2.getParentElement();
+    const element = _app3.getParentElement();
     void element.requestPointerLock();
     return true;
   }
@@ -48408,7 +49314,7 @@ function _computeShapeAbsPos(renderable, shape, outPos) {
 var _shapeAbs = new Vector2d(0, 0);
 function _raycastPolygon(fromX, fromY, dx, dy, shape, shapeAbsX, shapeAbsY) {
   const points = shape.points;
-  const normals = shape.normals;
+  const normals = shape.edgeNormals;
   const len = points.length;
   let bestT = Infinity;
   let bestNormalIdx = -1;
@@ -48649,10 +49555,10 @@ function vornoiRegion(line, point) {
 }
 function testPolygonPolygon(a, polyA, b, polyB, response) {
   const aPoints = polyA.points;
-  const aNormals = polyA.normals;
+  const aNormals = polyA.edgeNormals;
   const aLen = aNormals.length;
   const bPoints = polyB.points;
-  const bNormals = polyB.normals;
+  const bNormals = polyB.edgeNormals;
   const bLen = bNormals.length;
   const posA = T_VECTORS[--T_VECTORS_IDX].copy(a.pos).add(a.ancestor.getAbsolutePosition()).add(polyA.pos);
   const posB = T_VECTORS[--T_VECTORS_IDX].copy(b.pos).add(b.ancestor.getAbsolutePosition()).add(polyB.pos);
@@ -48792,7 +49698,7 @@ function testPolygonEllipse(a, polyA, b, ellipseB, response) {
         }
       }
     } else {
-      normal.copy(polyA.normals[i]);
+      normal.copy(polyA.edgeNormals[i]);
       dist = point.dot(normal);
       const distAbs = Math.abs(dist);
       if ((len === 1 || dist > 0) && distAbs > radius) {
@@ -51772,7 +52678,7 @@ var Trigger = class extends Renderable {
 };
 
 // src/version.ts
-var version = "20.4.0";
+var version = "20.6.0";
 
 // src/system/bootstrap.ts
 var initialized = false;
@@ -52222,7 +53128,7 @@ var LIT_INSTANCED = {
 };
 
 // src/video/webgpu/shaders/mesh-lit.wgsl
-var mesh_lit_default3 = "// melonJS WebGPU lit mesh shader \u2014 the WGSL port of mesh-lit.vert /\n// mesh-lit.frag: half-Lambert diffuse from directional Light3d lights plus\n// an ambient floor, over the mesh tier's uniform-driven placement.\n//\n// Vertex layout (48-byte stride, shared with the WebGL backend): the\n// 36-byte unlit layout plus\n//   @location(3) aNormal float32x3 offset 36\n// aNormal is MODEL-space on the retained path (rotated below by the model\n// matrix's upper 3\xD73) and world-space on the accumulated path \u2014 which\n// supplies an identity model matrix, so one shader serves both.\n//\n// The std140 Light3dBlock binds at group 2 with a dynamic offset \u2014 one\n// snapshot per light change per frame, per the queue-write ordering law.\n// Its layout is written by src/video/webgl/lighting/std140.ts and the two\n// must agree byte for byte \u2014 a mismatch does not fail validation, it\n// silently shifts every light.\n\nstruct FrameUniforms {\n	projection : mat4x4<f32>,\n	// unused by this shader; part of the shared frame-globals block\n	lineWidth : f32,\n};\n\nstruct MeshUniforms {\n	model : mat4x4<f32>,\n	view : mat4x4<f32>,\n	tint : vec4f,\n	// x = alpha cutout threshold (0 = disabled), y = 1 when an opacity map\n	// is bound (0 = the second sampler is filler); z, w reserved\n	params : vec4f,\n	// self-illumination added AFTER lighting (r, g, b; w reserved)\n	emissive : vec4f,\n	// specular color (rgb) and exponent (w); w = 0 means no highlight\n	specular : vec4f,\n	// the camera's world position (xyz; w reserved), for the specular\n	// half-vector \u2014 nothing else in this shader needs it\n	eye : vec4f,\n	// straight (unpremultiplied) fog colour (rgb; w reserved)\n	fogColor : vec4f,\n	// x = mode (0 off / 1 linear / 2 exp2), y = near, z = 1/(far - near),\n	// w = density\n	fogParams : vec4f,\n	// xyz = height falloff x the world-up axis, in VIEW space;\n	// w = exp(k * (cameraY - fogHeight)), pre-baked on the CPU\n	fogHeight : vec4f,\n};\n\n// One light, type inferred from sentinels (see std140.ts):\n// posRange.w < 0 \u2192 directional (dirCone.xyz = surface\u2192light, normalized);\n// otherwise positional at posRange.xyz with quadratic falloff over\n// posRange.w, plus a spot cone when dirCone.w > -1 (dirCone.xyz = the\n// cone axis / travel direction, w = cos(outer), colorInner.w =\n// cos(inner)). colorInner.rgb is premultiplied by intensity.\nstruct Light3dData {\n	posRange : vec4f,\n	dirCone : vec4f,\n	colorInner : vec4f,\n};\n\n// header = count + pad (vec4), ambient rgb + pad (vec4), then 32 lights\n// of 3 vec4 each \u2014 1568 bytes total (BLOCK3D_BYTES)\nstruct Light3dBlock {\n	countPad : vec4f,\n	ambient : vec4f,\n	lights : array<Light3dData, 32>,\n};\n\n@group(0) @binding(0) var<uniform> uFrame : FrameUniforms;\n@group(1) @binding(0) var uTexture : texture_2d<f32>;\n@group(1) @binding(1) var uSampler : sampler;\n// per-texel opacity (MTL map_d). When no map is bound this pair is filler \u2014\n// the diffuse texture again \u2014 and `params.y` is 0, so its sample is weighted\n// away rather than branched around.\n@group(1) @binding(2) var uAlphaMap : texture_2d<f32>;\n@group(1) @binding(3) var uAlphaSampler : sampler;\n@group(2) @binding(0) var<uniform> uLights : Light3dBlock;\n@group(3) @binding(0) var<uniform> uMesh : MeshUniforms;\n\nstruct VSOut {\n	@builtin(position) position : vec4f,\n	@location(0) vRegion : vec2f,\n	@location(1) vColor : vec4f,\n	@location(2) vNormal : vec3f,\n	// world-space fragment position \u2014 positional lights (point / spot)\n	// fall off with distance, so the fragment stage needs where the\n	// surface IS\n	@location(3) vWorldPos : vec3f,\n	// radial view-space distance for distance fog\n	@location(4) vFogDepth : f32,\n};\n\n// Distance fog is behind a PIPELINE-OVERRIDABLE CONSTANT rather than a plain\n// runtime test. `enable_fog` is fixed when the pipeline is created, so the\n// implementation can fold the branch and drop the dead side \u2014 the same result\n// the WebGL backend gets from `#define FOG`, without WGSL needing a\n// preprocessor or the engine deriving a second module. A scene that never\n// enables fog pays for none of the work below.\noverride enable_fog : bool = false;\n\n// How much the height falloff scales the fog along this view ray. Twin of\n// `fogHeightFactor` in the GLSL mesh shaders \u2014 keep them in step.\n//\n// Density falls off exponentially with altitude, and an exponential integrates\n// analytically along a straight segment, so the ray costs one `exp` and no\n// marching. The result multiplies the distance, leaving both curves untouched.\n//\n// Takes the VIEW-space position, not a height. The only position this stage\n// has is pre-view \u2014 `model * position` \u2014 and that is the mesh's parent space\n// rather than the world, because `Container.draw` folds every ancestor into\n// the view matrix. Reading a height straight off it put the fog floor at the\n// wrong altitude for anything under a scaled container. Dotting the view-space\n// position against the world-up axis expressed in view space gives the height\n// above the camera whatever those ancestors did, since they are inside the\n// very matrix that produced this position. `fogHeight.xyz` carries the falloff\n// too, so the exponent is one dot product.\n//\n// Render space is Y-DOWN: density rises as height INCREASES, the opposite sign\n// to every published form of this.\n//\n// A falloff of 0 gives exactly 1, so uniform fog is this with the dial at zero\n// rather than a special case.\nfn fog_height_factor(viewPos : vec3f) -> f32 {\n	let kdy = dot(uMesh.fogHeight.xyz, viewPos);\n	// (exp(x) - 1) / x is 0/0 at x = 0, which is a horizontal view ray \u2014 take\n	// the limit rather than guarding, or the fog steps as the ray flattens\n	var t = 1.0;\n	if (abs(kdy) >= 1e-4) {\n		t = (exp(kdy) - 1.0) / kdy;\n	}\n	return uMesh.fogHeight.w * t;\n}\n\n\n// Fold distance fog into a PREMULTIPLIED colour. Twin of `apply_fog` in\n// mesh.wgsl and `applyFog` in the GLSL mesh shaders \u2014 keep them in step. WGSL\n// has no preprocessor and the build loads shaders as raw text, so the block is\n// duplicated rather than shared.\n//\n// `rgb` is already multiplied by `a`, so the fog colour must be scaled by the\n// fragment's own coverage \u2014 a plain mix would paint fog onto near-transparent\n// fragments and halo every alpha-cutout leaf. Mode 0 returns the input\n// untouched, so a scene with no fog is bit-identical.\nfn apply_fog(rgb : vec3f, a : f32, fogDepth : f32) -> vec3f {\n	if (!enable_fog) {\n		return rgb;\n	}\n	let mode = uMesh.fogParams.x;\n	if (mode < 0.5) {\n		return rgb;\n	}\n	var f : f32;\n	if (mode < 1.5) {\n		f = 1.0 - clamp((fogDepth - uMesh.fogParams.y) * uMesh.fogParams.z, 0.0, 1.0);\n	} else {\n		let dd = fogDepth * uMesh.fogParams.w;\n		f = exp(-dd * dd);\n	}\n	return mix(uMesh.fogColor.rgb * a, rgb, f);\n}\n\n@vertex\nfn vertex_main(\n	@location(0) aVertex : vec3f,\n	@location(1) aRegion : vec2f,\n	@location(2) aColor : vec4f,\n	@location(3) aNormal : vec3f,\n) -> VSOut {\n	var out : VSOut;\n	let worldPos = uMesh.model * vec4f(aVertex, 1.0);\n	let clip = uFrame.projection * uMesh.view * worldPos;\n	// GL-convention clip z in [-w, w] remapped to WebGPU's [0, w]\n	out.position = vec4f(clip.xy, (clip.z + clip.w) * 0.5, clip.w);\n	let tinted = aColor * uMesh.tint;\n	out.vColor = vec4f(tinted.rgb * tinted.a, tinted.a);\n	out.vRegion = aRegion;\n	out.vWorldPos = worldPos.xyz;\n	if (enable_fog) {\n		let viewPos = (uMesh.view * worldPos).xyz;\n		out.vFogDepth = length(viewPos) * fog_height_factor(viewPos);\n	} else {\n		out.vFogDepth = 0.0;\n	}\n	// Rotate the normal into world space with the model matrix's upper\n	// 3\xD73. Lighting is evaluated in world space, so the view transform is\n	// deliberately excluded. Uniform scale cancels when the fragment\n	// renormalizes; non-uniform scale is approximated \u2014 an exact result\n	// would need the inverse-transpose.\n	let m = uMesh.model;\n	out.vNormal = mat3x3f(m[0].xyz, m[1].xyz, m[2].xyz) * aNormal;\n	return out;\n}\n\n@fragment\nfn fragment_main(in : VSOut) -> @location(0) vec4f {\n	// sampled unconditionally, before the discard (uniform control flow)\n	var base = textureSample(uTexture, uSampler, in.vRegion);\n	// Per-texel opacity (MTL map_d), applied BEFORE the cutout so one\n	// material can cut out to the shape of a leaf rather than at a single\n	// threshold across the whole surface. Sampled unconditionally and\n	// WEIGHTED: with no map bound the second pair is filler, and this keeps\n	// the sample in uniform control flow (and identical to the GLSL twin).\n	base.a = base.a * mix(1.0, textureSample(uAlphaMap, uAlphaSampler, in.vRegion).r, uMesh.params.y);\n	// hard alpha cutout (glTF alphaMode MASK) \u2014 discard before any shading\n	// so cut-away texels cost nothing and never write depth\n	// Thresholded on the MATERIAL's own alpha, deliberately BEFORE the tint\n	// multiply \u2014 see mesh.frag: the cutout is the surface's shape, and a\n	// fading object must keep it rather than pop out at its own threshold.\n	if (base.a < uMesh.params.x) {\n		discard;\n	}\n	base = base * in.vColor;\n\n	// see mesh-lit.frag: a `lit` mesh with no usable normals must degrade to\n	// unlit rather than normalize a zero vector to NaN and render black\n	let nLength = length(in.vNormal);\n	if (nLength < 1e-6) {\n		return vec4f(\n			apply_fog(base.rgb + uMesh.emissive.rgb, base.a, in.vFogDepth),\n			base.a\n		);\n	}\n	let n = in.vNormal / nLength;\n	var lit = uLights.ambient.rgb;\n	// Blinn-Phong specular, accumulated alongside the diffuse term. Gated on\n	// the exponent rather than the colour: `Ns` of 0 is the MTL format's \"no\n	// highlight\", and exporters happily write a non-black `Ks` next to it.\n	var specular = vec3f(0.0);\n	let shininess = uMesh.specular.w;\n	let hasSpecular = shininess > 0.0;\n	var viewDir = vec3f(0.0);\n	if (hasSpecular) {\n		viewDir = normalize(uMesh.eye.xyz - in.vWorldPos);\n	}\n	// clamped to the array size, not just taken on trust: if the block\n	// ever read as something other than what the writer put there, an\n	// unbounded trip count would also index out of range\n	let count = min(i32(uLights.countPad.x), 32);\n	for (var i = 0; i < count; i = i + 1) {\n		let pr = uLights.lights[i].posRange;\n		let dc = uLights.lights[i].dirCone;\n		var lightDir : vec3f;\n		var atten = 1.0;\n		if (pr.w < 0.0) {\n			// directional: dirCone.xyz is already the surface\u2192light vector\n			lightDir = dc.xyz;\n		} else {\n			// positional: quadratic falloff over range (the Light2d model \u2014\n			// stylized, not physical inverse-square, which is unusable in\n			// pixel-unit worlds with unit intensities)\n			let toLight = pr.xyz - in.vWorldPos;\n			let dist = max(length(toLight), 1e-4);\n			lightDir = toLight / dist;\n			let linearAtt = max(0.0, 1.0 - dist / pr.w);\n			atten = linearAtt * linearAtt;\n			if (dc.w > -1.0) {\n				// spot cone: -lightDir is the light\u2192surface direction; fade\n				// from the inner cone cosine to the outer\n				let cd = dot(-lightDir, dc.xyz);\n				atten = atten * smoothstep(dc.w, uLights.lights[i].colorInner.w, cd);\n			}\n		}\n		// Half-Lambert (\"wrap\") diffuse: dot * 0.5 + 0.5, squared. Softens\n		// the terminator and lifts the shadowed side \u2014 gentler than hard\n		// Lambert, which reads as harsh noon.\n		let ndl = dot(n, lightDir) * 0.5 + 0.5;\n		lit = lit + uLights.lights[i].colorInner.rgb * (ndl * ndl * atten);\n		if (hasSpecular) {\n			// masked by the UNWRAPPED Lambert term: half-Lambert lifts the\n			// shadowed side, and a highlight on a surface facing away from\n			// the light reads as a rendering error\n			let facing = max(dot(n, lightDir), 0.0);\n			let h = normalize(lightDir + viewDir);\n			let spec = pow(max(dot(n, h), 0.0), shininess);\n			specular = specular\n				+ uLights.lights[i].colorInner.rgb * (spec * facing * atten);\n		}\n	}\n\n	// emissive self-illuminates: added AFTER lighting so it glows at full\n	// strength regardless of the scene lights (neon, lava, glowing eyes)\n	return vec4f(\n		apply_fog(\n			base.rgb * lit + specular * uMesh.specular.rgb + uMesh.emissive.rgb,\n			base.a,\n			in.vFogDepth\n		),\n		base.a\n	);\n}\n";
+var mesh_lit_default3 = "// melonJS WebGPU lit mesh shader \u2014 the WGSL port of mesh-lit.vert /\n// mesh-lit.frag: half-Lambert diffuse from directional Light3d lights plus\n// an ambient floor, over the mesh tier's uniform-driven placement.\n//\n// Vertex layout (48-byte stride, shared with the WebGL backend): the\n// 36-byte unlit layout plus\n//   @location(3) aNormal float32x3 offset 36\n// aNormal is MODEL-space on the retained path (rotated below by the model\n// matrix's upper 3\xD73) and world-space on the accumulated path \u2014 which\n// supplies an identity model matrix, so one shader serves both.\n//\n// The std140 Light3dBlock binds at group 2 with a dynamic offset \u2014 one\n// snapshot per light change per frame, per the queue-write ordering law.\n// Its layout is written by src/video/webgl/lighting/std140.ts and the two\n// must agree byte for byte \u2014 a mismatch does not fail validation, it\n// silently shifts every light.\n\nstruct FrameUniforms {\n	projection : mat4x4<f32>,\n	// unused by this shader; part of the shared frame-globals block\n	lineWidth : f32,\n};\n\nstruct MeshUniforms {\n	model : mat4x4<f32>,\n	view : mat4x4<f32>,\n	tint : vec4f,\n	// x = alpha cutout threshold (0 = disabled), y = 1 when an opacity map\n	// is bound (0 = the second sampler is filler); z, w reserved\n	params : vec4f,\n	// self-illumination added AFTER lighting (r, g, b; w reserved)\n	emissive : vec4f,\n	// specular color (rgb) and exponent (w); w = 0 means no highlight\n	specular : vec4f,\n	// the camera's world position (xyz; w reserved), for the specular\n	// half-vector \u2014 nothing else in this shader needs it\n	eye : vec4f,\n	// straight (unpremultiplied) fog colour (rgb; w reserved)\n	fogColor : vec4f,\n	// x = mode (0 off / 1 linear / 2 exp2), y = near, z = 1/(far - near),\n	// w = density\n	fogParams : vec4f,\n	// xyz = height falloff x the world-up axis, in VIEW space;\n	// w = exp(k * (cameraY - fogHeight)), pre-baked on the CPU\n	fogHeight : vec4f,\n};\n\n// One light, type inferred from sentinels (see std140.ts):\n// posRange.w < 0 \u2192 directional (dirCone.xyz = surface\u2192light, normalized);\n// otherwise positional at posRange.xyz with quadratic falloff over\n// posRange.w, plus a spot cone when dirCone.w > -1 (dirCone.xyz = the\n// cone axis / travel direction, w = cos(outer), colorInner.w =\n// cos(inner)). colorInner.rgb is premultiplied by intensity.\nstruct Light3dData {\n	posRange : vec4f,\n	dirCone : vec4f,\n	colorInner : vec4f,\n};\n\n// header = count + pad (vec4), ambient rgb + pad (vec4), then 32 lights\n// of 3 vec4 each \u2014 1568 bytes total (BLOCK3D_BYTES)\nstruct Light3dBlock {\n	countPad : vec4f,\n	ambient : vec4f,\n	lights : array<Light3dData, 32>,\n};\n\n@group(0) @binding(0) var<uniform> uFrame : FrameUniforms;\n@group(1) @binding(0) var uTexture : texture_2d<f32>;\n@group(1) @binding(1) var uSampler : sampler;\n// per-texel opacity (MTL map_d). When no map is bound this pair is filler \u2014\n// the diffuse texture again \u2014 and `params.y` is 0, so its sample is weighted\n// away rather than branched around.\n@group(1) @binding(2) var uAlphaMap : texture_2d<f32>;\n@group(1) @binding(3) var uAlphaSampler : sampler;\n@group(2) @binding(0) var<uniform> uLights : Light3dBlock;\n@group(3) @binding(0) var<uniform> uMesh : MeshUniforms;\n\nstruct VSOut {\n	@builtin(position) position : vec4f,\n	@location(0) vRegion : vec2f,\n	@location(1) vColor : vec4f,\n	@location(2) vNormal : vec3f,\n	// world-space fragment position \u2014 positional lights (point / spot)\n	// fall off with distance, so the fragment stage needs where the\n	// surface IS\n	@location(3) vWorldPos : vec3f,\n	// radial view-space distance for distance fog\n	@location(4) vFogDepth : f32,\n};\n\n// Distance fog is behind a PIPELINE-OVERRIDABLE CONSTANT rather than a plain\n// runtime test. `enable_fog` is fixed when the pipeline is created, so the\n// implementation can fold the branch and drop the dead side \u2014 the same result\n// the WebGL backend gets from `#define FOG`, without WGSL needing a\n// preprocessor or the engine deriving a second module. A scene that never\n// enables fog pays for none of the work below.\noverride enable_fog : bool = false;\n\n// How much the height falloff scales the fog along this view ray. Twin of\n// `fogHeightFactor` in the GLSL mesh shaders \u2014 keep them in step.\n//\n// Density falls off exponentially with altitude, and an exponential integrates\n// analytically along a straight segment, so the ray costs one `exp` and no\n// marching. The result multiplies the distance, leaving both curves untouched.\n//\n// Takes the VIEW-space position, not a height. The only position this stage\n// has is pre-view \u2014 `model * position` \u2014 and that is the mesh's parent space\n// rather than the world, because `Container.draw` folds every ancestor into\n// the view matrix. Reading a height straight off it put the fog floor at the\n// wrong altitude for anything under a scaled container. Dotting the view-space\n// position against the world-up axis expressed in view space gives the height\n// above the camera whatever those ancestors did, since they are inside the\n// very matrix that produced this position. `fogHeight.xyz` carries the falloff\n// too, so the exponent is one dot product.\n//\n// Render space is Y-DOWN: density rises as height INCREASES, the opposite sign\n// to every published form of this.\n//\n// A falloff of 0 gives exactly 1, so uniform fog is this with the dial at zero\n// rather than a special case.\nfn fog_height_factor(viewPos : vec3f) -> f32 {\n	let kdy = dot(uMesh.fogHeight.xyz, viewPos);\n	// (exp(x) - 1) / x is 0/0 at x = 0, which is a horizontal view ray \u2014 take\n	// the limit rather than guarding, or the fog steps as the ray flattens\n	var t = 1.0;\n	if (abs(kdy) >= 1e-4) {\n		t = (exp(kdy) - 1.0) / kdy;\n	}\n	return uMesh.fogHeight.w * t;\n}\n\n\n// Fold distance fog into a PREMULTIPLIED colour. Twin of `apply_fog` in\n// mesh.wgsl and `applyFog` in the GLSL mesh shaders \u2014 keep them in step. WGSL\n// has no preprocessor and the build loads shaders as raw text, so the block is\n// duplicated rather than shared.\n//\n// `rgb` is already multiplied by `a`, so the fog colour must be scaled by the\n// fragment's own coverage \u2014 a plain mix would paint fog onto near-transparent\n// fragments and halo every alpha-cutout leaf. Mode 0 returns the input\n// untouched, so a scene with no fog is bit-identical.\nfn apply_fog(rgb : vec3f, a : f32, fogDepth : f32) -> vec3f {\n	if (!enable_fog) {\n		return rgb;\n	}\n	let mode = uMesh.fogParams.x;\n	if (mode < 0.5) {\n		return rgb;\n	}\n	var f : f32;\n	if (mode < 1.5) {\n		f = 1.0 - clamp((fogDepth - uMesh.fogParams.y) * uMesh.fogParams.z, 0.0, 1.0);\n	} else {\n		let dd = fogDepth * uMesh.fogParams.w;\n		f = exp(-dd * dd);\n	}\n	return mix(uMesh.fogColor.rgb * a, rgb, f);\n}\n\n// The mesh-hosted ShaderEffect hook (#1658). Identity by default \u2014 every\n// compiler inlines it away, so an un-effected mesh pays nothing. When an\n// effect is hosted, `spliceEffect` replaces this definition with one that\n// calls the effect's `apply()`, and pastes the effect body above it.\n//\n// Deliberately a FUNCTION and not a marker comment: the shader pipeline\n// strips comments, so a comment cannot be relied on to reach the splicer.\n//\n// Declared ABOVE `@vertex` on purpose: `buildInstancedMeshWGSL` assembles the\n// instanced variant as `source.slice(0, vertexAt)` + a generated vertex stage\n// + `source.slice(fragmentAt)`, so anything BETWEEN the two stages is dropped.\n// Defined there, the instanced module kept the call and lost the definition,\n// and every frame drawing an instanced lit mesh failed to compile.\nfn ME_effect(c : vec4f, uv : vec2f) -> vec4f { return c; }\n\n@vertex\nfn vertex_main(\n	@location(0) aVertex : vec3f,\n	@location(1) aRegion : vec2f,\n	@location(2) aColor : vec4f,\n	@location(3) aNormal : vec3f,\n) -> VSOut {\n	var out : VSOut;\n	let worldPos = uMesh.model * vec4f(aVertex, 1.0);\n	let clip = uFrame.projection * uMesh.view * worldPos;\n	// GL-convention clip z in [-w, w] remapped to WebGPU's [0, w]\n	out.position = vec4f(clip.xy, (clip.z + clip.w) * 0.5, clip.w);\n	let tinted = aColor * uMesh.tint;\n	out.vColor = vec4f(tinted.rgb * tinted.a, tinted.a);\n	out.vRegion = aRegion;\n	out.vWorldPos = worldPos.xyz;\n	if (enable_fog) {\n		let viewPos = (uMesh.view * worldPos).xyz;\n		out.vFogDepth = length(viewPos) * fog_height_factor(viewPos);\n	} else {\n		out.vFogDepth = 0.0;\n	}\n	// Rotate the normal into world space with the model matrix's upper\n	// 3\xD73. Lighting is evaluated in world space, so the view transform is\n	// deliberately excluded. Uniform scale cancels when the fragment\n	// renormalizes; non-uniform scale is approximated \u2014 an exact result\n	// would need the inverse-transpose.\n	let m = uMesh.model;\n	out.vNormal = mat3x3f(m[0].xyz, m[1].xyz, m[2].xyz) * aNormal;\n	return out;\n}\n\n\n@fragment\nfn fragment_main(in : VSOut) -> @location(0) vec4f {\n	// sampled unconditionally, before the discard (uniform control flow)\n	var base = textureSample(uTexture, uSampler, in.vRegion);\n	// Per-texel opacity (MTL map_d), applied BEFORE the cutout so one\n	// material can cut out to the shape of a leaf rather than at a single\n	// threshold across the whole surface. Sampled unconditionally and\n	// WEIGHTED: with no map bound the second pair is filler, and this keeps\n	// the sample in uniform control flow (and identical to the GLSL twin).\n	base.a = base.a * mix(1.0, textureSample(uAlphaMap, uAlphaSampler, in.vRegion).r, uMesh.params.y);\n	// hard alpha cutout (glTF alphaMode MASK) \u2014 discard before any shading\n	// so cut-away texels cost nothing and never write depth\n	// Thresholded on the MATERIAL's own alpha, deliberately BEFORE the tint\n	// multiply \u2014 see mesh.frag: the cutout is the surface's shape, and a\n	// fading object must keep it rather than pop out at its own threshold.\n	if (base.a < uMesh.params.x) {\n		discard;\n	}\n	base = base * in.vColor;\n	base = ME_effect(base, in.vRegion);\n\n	// see mesh-lit.frag: a `lit` mesh with no usable normals must degrade to\n	// unlit rather than normalize a zero vector to NaN and render black\n	let nLength = length(in.vNormal);\n	if (nLength < 1e-6) {\n		return vec4f(\n			apply_fog(base.rgb + uMesh.emissive.rgb, base.a, in.vFogDepth),\n			base.a\n		);\n	}\n	let n = in.vNormal / nLength;\n	var lit = uLights.ambient.rgb;\n	// Blinn-Phong specular, accumulated alongside the diffuse term. Gated on\n	// the exponent rather than the colour: `Ns` of 0 is the MTL format's \"no\n	// highlight\", and exporters happily write a non-black `Ks` next to it.\n	var specular = vec3f(0.0);\n	let shininess = uMesh.specular.w;\n	let hasSpecular = shininess > 0.0;\n	var viewDir = vec3f(0.0);\n	if (hasSpecular) {\n		viewDir = normalize(uMesh.eye.xyz - in.vWorldPos);\n	}\n	// clamped to the array size, not just taken on trust: if the block\n	// ever read as something other than what the writer put there, an\n	// unbounded trip count would also index out of range\n	let count = min(i32(uLights.countPad.x), 32);\n	for (var i = 0; i < count; i = i + 1) {\n		let pr = uLights.lights[i].posRange;\n		let dc = uLights.lights[i].dirCone;\n		var lightDir : vec3f;\n		var atten = 1.0;\n		if (pr.w < 0.0) {\n			// directional: dirCone.xyz is already the surface\u2192light vector\n			lightDir = dc.xyz;\n		} else {\n			// positional: quadratic falloff over range (the Light2d model \u2014\n			// stylized, not physical inverse-square, which is unusable in\n			// pixel-unit worlds with unit intensities)\n			let toLight = pr.xyz - in.vWorldPos;\n			let dist = max(length(toLight), 1e-4);\n			lightDir = toLight / dist;\n			let linearAtt = max(0.0, 1.0 - dist / pr.w);\n			atten = linearAtt * linearAtt;\n			if (dc.w > -1.0) {\n				// spot cone: -lightDir is the light\u2192surface direction; fade\n				// from the inner cone cosine to the outer\n				let cd = dot(-lightDir, dc.xyz);\n				atten = atten * smoothstep(dc.w, uLights.lights[i].colorInner.w, cd);\n			}\n		}\n		// Half-Lambert (\"wrap\") diffuse: dot * 0.5 + 0.5, squared. Softens\n		// the terminator and lifts the shadowed side \u2014 gentler than hard\n		// Lambert, which reads as harsh noon.\n		let ndl = dot(n, lightDir) * 0.5 + 0.5;\n		lit = lit + uLights.lights[i].colorInner.rgb * (ndl * ndl * atten);\n		if (hasSpecular) {\n			// masked by the UNWRAPPED Lambert term: half-Lambert lifts the\n			// shadowed side, and a highlight on a surface facing away from\n			// the light reads as a rendering error\n			let facing = max(dot(n, lightDir), 0.0);\n			let h = normalize(lightDir + viewDir);\n			let spec = pow(max(dot(n, h), 0.0), shininess);\n			specular = specular\n				+ uLights.lights[i].colorInner.rgb * (spec * facing * atten);\n		}\n	}\n\n	// emissive self-illuminates: added AFTER lighting so it glows at full\n	// strength regardless of the scene lights (neon, lava, glowing eyes)\n	return vec4f(\n		apply_fog(\n			base.rgb * lit + specular * uMesh.specular.rgb + uMesh.emissive.rgb,\n			base.a,\n			in.vFogDepth\n		),\n		base.a\n	);\n}\n";
 
 // src/video/webgpu/buffer/instance_buffer.js
 var WebGPUInstanceBuffer = class {
@@ -52416,7 +53322,7 @@ var WebGPURetainedGeometry = class {
 };
 
 // src/video/webgpu/shaders/mesh.wgsl
-var mesh_default3 = "// melonJS WebGPU mesh shader \u2014 the WGSL port of mesh.vert / mesh.frag.\n//\n// Vertex layout (36-byte stride, shared with the WebGL backend):\n//   @location(0) aVertex float32x3 offset 0\n//   @location(1) aRegion float32x2 offset 12\n//   @location(2) aColor  float32x4 offset 20\n//\n// aColor is four straight floats (R, G, B, A in [0, 1]) \u2014 NOT the quad\n// tier's packed unorm8x4 \u2014 so no BGRA swizzle applies. The float layout is\n// shared with the GL backend, where it exists to dodge NaN-pattern\n// canonicalization on Metal-backed drivers.\n//\n// Placement is uniform-driven so retained geometry uploads once and reuses:\n//   clip = projection \xD7 view \xD7 model \xD7 vertex\n// One MeshUniforms snapshot binds per draw (group 3, dynamic offset \u2014 the\n// queue-write ordering law: a shared region would be retroactively\n// clobbered for draws already recorded). The accumulated path (2D camera,\n// CPU-projected vertices) supplies an identity model matrix.\n\nstruct FrameUniforms {\n	projection : mat4x4<f32>,\n	// unused by this shader; part of the shared frame-globals block\n	lineWidth : f32,\n};\n\nstruct MeshUniforms {\n	// the mesh's own placement (axis bridge + mesh scale included)\n	model : mat4x4<f32>,\n	// the camera view plus any ancestor container transform\n	view : mat4x4<f32>,\n	// per-draw tint \xD7 global alpha (r, g, b, a) \u2014 kept out of the vertex\n	// data so re-tinting never invalidates retained geometry\n	tint : vec4f,\n	// x = alpha cutout threshold (0 = disabled), y = 1 when an opacity map\n	// is bound (0 = the second sampler is filler); z, w reserved\n	params : vec4f,\n	// self-illumination added on top (r, g, b; w reserved)\n	emissive : vec4f,\n	// specular color (rgb) and exponent (w); w = 0 means no highlight.\n	// Unused by the unlit tier, present so both tiers share one block size.\n	specular : vec4f,\n	// the camera's world position (xyz; w reserved)\n	eye : vec4f,\n	// straight (unpremultiplied) fog colour (rgb; w reserved)\n	fogColor : vec4f,\n	// x = mode (0 off / 1 linear / 2 exp2), y = near, z = 1/(far - near),\n	// w = density\n	fogParams : vec4f,\n	// xyz = height falloff x the world-up axis, in VIEW space;\n	// w = exp(k * (cameraY - fogHeight)), pre-baked on the CPU\n	fogHeight : vec4f,\n};\n\n@group(0) @binding(0) var<uniform> uFrame : FrameUniforms;\n@group(1) @binding(0) var uTexture : texture_2d<f32>;\n@group(1) @binding(1) var uSampler : sampler;\n// per-texel opacity (MTL map_d). When no map is bound this pair is filler \u2014\n// the diffuse texture again \u2014 and `params.y` is 0, so its sample is weighted\n// away rather than branched around.\n@group(1) @binding(2) var uAlphaMap : texture_2d<f32>;\n@group(1) @binding(3) var uAlphaSampler : sampler;\n@group(3) @binding(0) var<uniform> uMesh : MeshUniforms;\n\nstruct VSOut {\n	@builtin(position) position : vec4f,\n	@location(0) vRegion : vec2f,\n	@location(1) vColor : vec4f,\n	@location(2) vFogDepth : f32,\n};\n\n// Distance fog is behind a PIPELINE-OVERRIDABLE CONSTANT rather than a plain\n// runtime test. `enable_fog` is fixed when the pipeline is created, so the\n// implementation can fold the branch and drop the dead side \u2014 the same result\n// the WebGL backend gets from `#define FOG`, without WGSL needing a\n// preprocessor or the engine deriving a second module. A scene that never\n// enables fog pays for none of the work below.\noverride enable_fog : bool = false;\n\n// How much the height falloff scales the fog along this view ray. Twin of\n// `fogHeightFactor` in the GLSL mesh shaders \u2014 keep them in step.\n//\n// Density falls off exponentially with altitude, and an exponential integrates\n// analytically along a straight segment, so the ray costs one `exp` and no\n// marching. The result multiplies the distance, leaving both curves untouched.\n//\n// Takes the VIEW-space position, not a height. The only position this stage\n// has is pre-view \u2014 `model * position` \u2014 and that is the mesh's parent space\n// rather than the world, because `Container.draw` folds every ancestor into\n// the view matrix. Reading a height straight off it put the fog floor at the\n// wrong altitude for anything under a scaled container. Dotting the view-space\n// position against the world-up axis expressed in view space gives the height\n// above the camera whatever those ancestors did, since they are inside the\n// very matrix that produced this position. `fogHeight.xyz` carries the falloff\n// too, so the exponent is one dot product.\n//\n// Render space is Y-DOWN: density rises as height INCREASES, the opposite sign\n// to every published form of this.\n//\n// A falloff of 0 gives exactly 1, so uniform fog is this with the dial at zero\n// rather than a special case.\nfn fog_height_factor(viewPos : vec3f) -> f32 {\n	let kdy = dot(uMesh.fogHeight.xyz, viewPos);\n	// (exp(x) - 1) / x is 0/0 at x = 0, which is a horizontal view ray \u2014 take\n	// the limit rather than guarding, or the fog steps as the ray flattens\n	var t = 1.0;\n	if (abs(kdy) >= 1e-4) {\n		t = (exp(kdy) - 1.0) / kdy;\n	}\n	return uMesh.fogHeight.w * t;\n}\n\n\n// Fold distance fog into a PREMULTIPLIED colour. Twin of `applyFog` in the\n// GLSL mesh shaders \u2014 keep the two in step. They are duplicated rather than\n// shared because WGSL has no preprocessor and the production build loads each\n// shader as raw text.\n//\n// `rgb` is already multiplied by `a`, so the fog colour must be scaled by the\n// fragment's own coverage: a plain mix toward the fog colour would paint\n// full-strength fog onto near-transparent fragments \u2014 grey halos around every\n// alpha-cutout leaf.\n//\n// Mode 0 returns the input untouched, so a scene with no fog is bit-identical\n// to one built before fog existed.\nfn apply_fog(rgb : vec3f, a : f32, fogDepth : f32) -> vec3f {\n	if (!enable_fog) {\n		return rgb;\n	}\n	let mode = uMesh.fogParams.x;\n	if (mode < 0.5) {\n		return rgb;\n	}\n	var f : f32;\n	if (mode < 1.5) {\n		// linear: 1 at `near`, reaching 0 at `far`\n		f = 1.0 - clamp((fogDepth - uMesh.fogParams.y) * uMesh.fogParams.z, 0.0, 1.0);\n	} else {\n		// exponential squared: survival = exp(-(density * d)^2)\n		let dd = fogDepth * uMesh.fogParams.w;\n		f = exp(-dd * dd);\n	}\n	return mix(uMesh.fogColor.rgb * a, rgb, f);\n}\n\n@vertex\nfn vertex_main(\n	@location(0) aVertex : vec3f,\n	@location(1) aRegion : vec2f,\n	@location(2) aColor : vec4f,\n) -> VSOut {\n	var out : VSOut;\n	let clip =\n		uFrame.projection * uMesh.view * uMesh.model * vec4f(aVertex, 1.0);\n	// GL-convention clip z in [-w, w] remapped to WebGPU's [0, w]\n	out.position = vec4f(clip.xy, (clip.z + clip.w) * 0.5, clip.w);\n	// tint first, then premultiply \u2014 matches the fragment's expectation\n	let tinted = aColor * uMesh.tint;\n	out.vColor = vec4f(tinted.rgb * tinted.a, tinted.a);\n	// Radial view-space distance for distance fog. Radial rather than view-space\n	// z, so fog holds steady as the camera turns. The clip position above keeps\n	// its own product: re-associating it could shift vertices by an ulp, and\n	// fog-off output must stay bit-identical.\n	// the slot is always declared \u2014 an override cannot remove an inter-stage\n	// variable \u2014 but the work behind it folds away with the constant\n	if (enable_fog) {\n		let viewPos = uMesh.view * uMesh.model * vec4f(aVertex, 1.0);\n		out.vFogDepth = length(viewPos.xyz)\n			* fog_height_factor(viewPos.xyz);\n	} else {\n		out.vFogDepth = 0.0;\n	}\n	out.vRegion = aRegion;\n	return out;\n}\n\n@fragment\nfn fragment_main(in : VSOut) -> @location(0) vec4f {\n	// sampled unconditionally, before the discard (uniform control flow)\n	var color = textureSample(uTexture, uSampler, in.vRegion);\n	// Per-texel opacity (MTL map_d), applied BEFORE the cutout so one\n	// material can cut out to the shape of a leaf rather than at a single\n	// threshold across the whole surface. Sampled unconditionally and\n	// WEIGHTED: with no map bound the second pair is filler, and this keeps\n	// the sample in uniform control flow (and identical to the GLSL twin).\n	color.a = color.a * mix(1.0, textureSample(uAlphaMap, uAlphaSampler, in.vRegion).r, uMesh.params.y);\n	// hard alpha cutout (glTF alphaMode MASK): drop cut texels so foliage /\n	// fences / decals read crisp without blending or sorting\n	// Thresholded on the MATERIAL's own alpha, deliberately BEFORE the tint\n	// multiply \u2014 see mesh.frag: the cutout is the surface's shape, and a\n	// fading object must keep it rather than pop out at its own threshold.\n	if (color.a < uMesh.params.x) {\n		discard;\n	}\n	color = color * in.vColor;\n	// emissive adds a self-lit color on top (neon, lava, screens); the\n	// unlit path has no lighting, so it is simply added to the base color\n	return vec4f(\n		apply_fog(color.rgb + uMesh.emissive.rgb, color.a, in.vFogDepth),\n		color.a\n	);\n}\n";
+var mesh_default3 = "// melonJS WebGPU mesh shader \u2014 the WGSL port of mesh.vert / mesh.frag.\n//\n// Vertex layout (36-byte stride, shared with the WebGL backend):\n//   @location(0) aVertex float32x3 offset 0\n//   @location(1) aRegion float32x2 offset 12\n//   @location(2) aColor  float32x4 offset 20\n//\n// aColor is four straight floats (R, G, B, A in [0, 1]) \u2014 NOT the quad\n// tier's packed unorm8x4 \u2014 so no BGRA swizzle applies. The float layout is\n// shared with the GL backend, where it exists to dodge NaN-pattern\n// canonicalization on Metal-backed drivers.\n//\n// Placement is uniform-driven so retained geometry uploads once and reuses:\n//   clip = projection \xD7 view \xD7 model \xD7 vertex\n// One MeshUniforms snapshot binds per draw (group 3, dynamic offset \u2014 the\n// queue-write ordering law: a shared region would be retroactively\n// clobbered for draws already recorded). The accumulated path (2D camera,\n// CPU-projected vertices) supplies an identity model matrix.\n\nstruct FrameUniforms {\n	projection : mat4x4<f32>,\n	// unused by this shader; part of the shared frame-globals block\n	lineWidth : f32,\n};\n\nstruct MeshUniforms {\n	// the mesh's own placement (axis bridge + mesh scale included)\n	model : mat4x4<f32>,\n	// the camera view plus any ancestor container transform\n	view : mat4x4<f32>,\n	// per-draw tint \xD7 global alpha (r, g, b, a) \u2014 kept out of the vertex\n	// data so re-tinting never invalidates retained geometry\n	tint : vec4f,\n	// x = alpha cutout threshold (0 = disabled), y = 1 when an opacity map\n	// is bound (0 = the second sampler is filler); z, w reserved\n	params : vec4f,\n	// self-illumination added on top (r, g, b; w reserved)\n	emissive : vec4f,\n	// specular color (rgb) and exponent (w); w = 0 means no highlight.\n	// Unused by the unlit tier, present so both tiers share one block size.\n	specular : vec4f,\n	// the camera's world position (xyz; w reserved)\n	eye : vec4f,\n	// straight (unpremultiplied) fog colour (rgb; w reserved)\n	fogColor : vec4f,\n	// x = mode (0 off / 1 linear / 2 exp2), y = near, z = 1/(far - near),\n	// w = density\n	fogParams : vec4f,\n	// xyz = height falloff x the world-up axis, in VIEW space;\n	// w = exp(k * (cameraY - fogHeight)), pre-baked on the CPU\n	fogHeight : vec4f,\n};\n\n@group(0) @binding(0) var<uniform> uFrame : FrameUniforms;\n@group(1) @binding(0) var uTexture : texture_2d<f32>;\n@group(1) @binding(1) var uSampler : sampler;\n// per-texel opacity (MTL map_d). When no map is bound this pair is filler \u2014\n// the diffuse texture again \u2014 and `params.y` is 0, so its sample is weighted\n// away rather than branched around.\n@group(1) @binding(2) var uAlphaMap : texture_2d<f32>;\n@group(1) @binding(3) var uAlphaSampler : sampler;\n@group(3) @binding(0) var<uniform> uMesh : MeshUniforms;\n\nstruct VSOut {\n	@builtin(position) position : vec4f,\n	@location(0) vRegion : vec2f,\n	@location(1) vColor : vec4f,\n	@location(2) vFogDepth : f32,\n};\n\n// Distance fog is behind a PIPELINE-OVERRIDABLE CONSTANT rather than a plain\n// runtime test. `enable_fog` is fixed when the pipeline is created, so the\n// implementation can fold the branch and drop the dead side \u2014 the same result\n// the WebGL backend gets from `#define FOG`, without WGSL needing a\n// preprocessor or the engine deriving a second module. A scene that never\n// enables fog pays for none of the work below.\noverride enable_fog : bool = false;\n\n// How much the height falloff scales the fog along this view ray. Twin of\n// `fogHeightFactor` in the GLSL mesh shaders \u2014 keep them in step.\n//\n// Density falls off exponentially with altitude, and an exponential integrates\n// analytically along a straight segment, so the ray costs one `exp` and no\n// marching. The result multiplies the distance, leaving both curves untouched.\n//\n// Takes the VIEW-space position, not a height. The only position this stage\n// has is pre-view \u2014 `model * position` \u2014 and that is the mesh's parent space\n// rather than the world, because `Container.draw` folds every ancestor into\n// the view matrix. Reading a height straight off it put the fog floor at the\n// wrong altitude for anything under a scaled container. Dotting the view-space\n// position against the world-up axis expressed in view space gives the height\n// above the camera whatever those ancestors did, since they are inside the\n// very matrix that produced this position. `fogHeight.xyz` carries the falloff\n// too, so the exponent is one dot product.\n//\n// Render space is Y-DOWN: density rises as height INCREASES, the opposite sign\n// to every published form of this.\n//\n// A falloff of 0 gives exactly 1, so uniform fog is this with the dial at zero\n// rather than a special case.\nfn fog_height_factor(viewPos : vec3f) -> f32 {\n	let kdy = dot(uMesh.fogHeight.xyz, viewPos);\n	// (exp(x) - 1) / x is 0/0 at x = 0, which is a horizontal view ray \u2014 take\n	// the limit rather than guarding, or the fog steps as the ray flattens\n	var t = 1.0;\n	if (abs(kdy) >= 1e-4) {\n		t = (exp(kdy) - 1.0) / kdy;\n	}\n	return uMesh.fogHeight.w * t;\n}\n\n\n// Fold distance fog into a PREMULTIPLIED colour. Twin of `applyFog` in the\n// GLSL mesh shaders \u2014 keep the two in step. They are duplicated rather than\n// shared because WGSL has no preprocessor and the production build loads each\n// shader as raw text.\n//\n// `rgb` is already multiplied by `a`, so the fog colour must be scaled by the\n// fragment's own coverage: a plain mix toward the fog colour would paint\n// full-strength fog onto near-transparent fragments \u2014 grey halos around every\n// alpha-cutout leaf.\n//\n// Mode 0 returns the input untouched, so a scene with no fog is bit-identical\n// to one built before fog existed.\nfn apply_fog(rgb : vec3f, a : f32, fogDepth : f32) -> vec3f {\n	if (!enable_fog) {\n		return rgb;\n	}\n	let mode = uMesh.fogParams.x;\n	if (mode < 0.5) {\n		return rgb;\n	}\n	var f : f32;\n	if (mode < 1.5) {\n		// linear: 1 at `near`, reaching 0 at `far`\n		f = 1.0 - clamp((fogDepth - uMesh.fogParams.y) * uMesh.fogParams.z, 0.0, 1.0);\n	} else {\n		// exponential squared: survival = exp(-(density * d)^2)\n		let dd = fogDepth * uMesh.fogParams.w;\n		f = exp(-dd * dd);\n	}\n	return mix(uMesh.fogColor.rgb * a, rgb, f);\n}\n\n// The mesh-hosted ShaderEffect hook (#1658). Identity by default \u2014 every\n// compiler inlines it away, so an un-effected mesh pays nothing. When an\n// effect is hosted, `spliceEffect` replaces this definition with one that\n// calls the effect's `apply()`, and pastes the effect body above it.\n//\n// Deliberately a FUNCTION and not a marker comment: the shader pipeline\n// strips comments, so a comment cannot be relied on to reach the splicer.\n//\n// Declared ABOVE `@vertex` on purpose: `buildInstancedMeshWGSL` assembles the\n// instanced variant as `source.slice(0, vertexAt)` + a generated vertex stage\n// + `source.slice(fragmentAt)`, so anything BETWEEN the two stages is dropped.\n// Defined there, the instanced module kept the call and lost the definition,\n// and every frame drawing an instanced lit mesh failed to compile.\nfn ME_effect(c : vec4f, uv : vec2f) -> vec4f { return c; }\n\n@vertex\nfn vertex_main(\n	@location(0) aVertex : vec3f,\n	@location(1) aRegion : vec2f,\n	@location(2) aColor : vec4f,\n) -> VSOut {\n	var out : VSOut;\n	let clip =\n		uFrame.projection * uMesh.view * uMesh.model * vec4f(aVertex, 1.0);\n	// GL-convention clip z in [-w, w] remapped to WebGPU's [0, w]\n	out.position = vec4f(clip.xy, (clip.z + clip.w) * 0.5, clip.w);\n	// tint first, then premultiply \u2014 matches the fragment's expectation\n	let tinted = aColor * uMesh.tint;\n	out.vColor = vec4f(tinted.rgb * tinted.a, tinted.a);\n	// Radial view-space distance for distance fog. Radial rather than view-space\n	// z, so fog holds steady as the camera turns. The clip position above keeps\n	// its own product: re-associating it could shift vertices by an ulp, and\n	// fog-off output must stay bit-identical.\n	// the slot is always declared \u2014 an override cannot remove an inter-stage\n	// variable \u2014 but the work behind it folds away with the constant\n	if (enable_fog) {\n		let viewPos = uMesh.view * uMesh.model * vec4f(aVertex, 1.0);\n		out.vFogDepth = length(viewPos.xyz)\n			* fog_height_factor(viewPos.xyz);\n	} else {\n		out.vFogDepth = 0.0;\n	}\n	out.vRegion = aRegion;\n	return out;\n}\n\n\n@fragment\nfn fragment_main(in : VSOut) -> @location(0) vec4f {\n	// sampled unconditionally, before the discard (uniform control flow)\n	var color = textureSample(uTexture, uSampler, in.vRegion);\n	// Per-texel opacity (MTL map_d), applied BEFORE the cutout so one\n	// material can cut out to the shape of a leaf rather than at a single\n	// threshold across the whole surface. Sampled unconditionally and\n	// WEIGHTED: with no map bound the second pair is filler, and this keeps\n	// the sample in uniform control flow (and identical to the GLSL twin).\n	color.a = color.a * mix(1.0, textureSample(uAlphaMap, uAlphaSampler, in.vRegion).r, uMesh.params.y);\n	// hard alpha cutout (glTF alphaMode MASK): drop cut texels so foliage /\n	// fences / decals read crisp without blending or sorting\n	// Thresholded on the MATERIAL's own alpha, deliberately BEFORE the tint\n	// multiply \u2014 see mesh.frag: the cutout is the surface's shape, and a\n	// fading object must keep it rather than pop out at its own threshold.\n	if (color.a < uMesh.params.x) {\n		discard;\n	}\n	color = color * in.vColor;\n	color = ME_effect(color, in.vRegion);\n	// emissive adds a self-lit color on top (neon, lava, screens); the\n	// unlit path has no lighting, so it is simply added to the base color\n	return vec4f(\n		apply_fog(color.rgb + uMesh.emissive.rgb, color.a, in.vFogDepth),\n		color.a\n	);\n}\n";
 
 // src/video/webgpu/shaders/mesh-shadow-instanced.wgsl
 var mesh_shadow_instanced_default2 = "// Instanced ground-shadow module (#1515) \u2014 the WGSL twin of\n// `webgl/shaders/mesh-shadow-instanced.vert`.\n//\n// One flat blob per instance, drawn from the SAME instance buffer the mesh\n// itself uses, so a forest of a hundred thousand trees costs one extra draw\n// rather than a hundred thousand.\n//\n// Hand-written and STANDALONE, rather than derived from the mesh module by\n// `buildInstancedMeshWGSL`. Deriving it would inherit three things it must\n// not have: the `hasColor`/`hasData` variant matrix (this reads neither slot,\n// so one module serves every record layout), the per-instance tint multiply\n// and emissive substitution (which would give a forest coloured, glowing\n// shadows), and the VSOut member-written guard, which on the lit tier\n// requires a body that writes `vWorldPos` and `vNormal` \u2014 neither of which a\n// flat unlit blob has any use for.\n//\n// The instance's rotation and vertical scale are DISCARDED: a blob lies flat\n// however its tree is turned, and only the horizontal footprint sets its\n// width. Translation and horizontal scale come straight out of the record's\n// three rows with no matrix built. Flattening onto the ground is\n// `uMesh.model`'s job \u2014 the caller passes the group matrix with its Y basis\n// column zeroed and its translation Y set to the ground height.\n\nstruct FrameUniforms {\n	projection : mat4x4<f32>,\n	// unused by this shader; part of the shared frame-globals block. Its size\n	// has to match the block the layout declares EXACTLY \u2014 a struct that reads\n	// past `minBindingSize` is a pipeline-creation error, not a silent\n	// over-read, and takes the whole frame's command buffer down with it.\n	lineWidth : f32,\n};\n\nstruct MeshUniforms {\n	model : mat4x4<f32>,\n	view : mat4x4<f32>,\n	tint : vec4f,\n	params : vec4f,\n	emissive : vec4f,\n	specular : vec4f,\n	eye : vec4f,\n	// straight (unpremultiplied) fog colour (rgb; w reserved)\n	fogColor : vec4f,\n	// x = mode (0 off / 1 linear / 2 exp2), y = near, z = 1/(far - near),\n	// w = density\n	fogParams : vec4f,\n	// xyz = height falloff x the world-up axis, in VIEW space;\n	// w = exp(k * (cameraY - fogHeight)), pre-baked on the CPU\n	fogHeight : vec4f,\n};\n\n@group(0) @binding(0) var<uniform> uFrame : FrameUniforms;\n@group(1) @binding(0) var uTexture : texture_2d<f32>;\n@group(1) @binding(1) var uSampler : sampler;\n@group(1) @binding(2) var uAlphaMap : texture_2d<f32>;\n@group(1) @binding(3) var uAlphaSampler : sampler;\n@group(3) @binding(0) var<uniform> uMesh : MeshUniforms;\n\n// Distance fog is behind a PIPELINE-OVERRIDABLE CONSTANT rather than a plain\n// runtime test. `enable_fog` is fixed when the pipeline is created, so the\n// implementation can fold the branch and drop the dead side \u2014 the same result\n// the WebGL backend gets from `#define FOG`, without WGSL needing a\n// preprocessor or the engine deriving a second module. A scene that never\n// enables fog pays for none of the work below.\noverride enable_fog : bool = false;\n\n// How much the height falloff scales the fog along this view ray. Twin of\n// `fogHeightFactor` in the GLSL mesh shaders \u2014 keep them in step.\n//\n// Density falls off exponentially with altitude, and an exponential integrates\n// analytically along a straight segment, so the ray costs one `exp` and no\n// marching. The result multiplies the distance, leaving both curves untouched.\n//\n// Takes the VIEW-space position, not a height. The only position this stage\n// has is pre-view \u2014 `model * position` \u2014 and that is the mesh's parent space\n// rather than the world, because `Container.draw` folds every ancestor into\n// the view matrix. Reading a height straight off it put the fog floor at the\n// wrong altitude for anything under a scaled container. Dotting the view-space\n// position against the world-up axis expressed in view space gives the height\n// above the camera whatever those ancestors did, since they are inside the\n// very matrix that produced this position. `fogHeight.xyz` carries the falloff\n// too, so the exponent is one dot product.\n//\n// Render space is Y-DOWN: density rises as height INCREASES, the opposite sign\n// to every published form of this.\n//\n// A falloff of 0 gives exactly 1, so uniform fog is this with the dial at zero\n// rather than a special case.\nfn fog_height_factor(viewPos : vec3f) -> f32 {\n	let kdy = dot(uMesh.fogHeight.xyz, viewPos);\n	// (exp(x) - 1) / x is 0/0 at x = 0, which is a horizontal view ray \u2014 take\n	// the limit rather than guarding, or the fog steps as the ray flattens\n	var t = 1.0;\n	if (abs(kdy) >= 1e-4) {\n		t = (exp(kdy) - 1.0) / kdy;\n	}\n	return uMesh.fogHeight.w * t;\n}\n\n\nstruct VSOut {\n	@builtin(position) position : vec4f,\n	@location(0) vRegion : vec2f,\n	@location(1) vColor : vec4f,\n	// radial view-space distance for distance fog\n	@location(2) vFogDepth : f32,\n};\n\n@vertex\nfn vertex_main(\n	@location(0) aVertex : vec3f,\n	@location(1) aRegion : vec2f,\n	@location(2) aColor : vec4f,\n	@location(3) aInstanceRow0 : vec4f,\n	@location(4) aInstanceRow1 : vec4f,\n	@location(5) aInstanceRow2 : vec4f,\n) -> VSOut {\n	var out : VSOut;\n\n	let instancePos = vec3f(aInstanceRow0.w, aInstanceRow1.w, aInstanceRow2.w);\n	// column 0 of the instance basis is the X axis times its scale; a scatter\n	// is rotated about the vertical axis, so its length is the horizontal\n	// footprint whatever the rotation\n	let footprint = length(\n		vec3f(aInstanceRow0.x, aInstanceRow1.x, aInstanceRow2.x));\n\n	// the quad is a unit square in the ground plane (XZ); its own Y is\n	// irrelevant, because uMesh.model flattens it onto the floor\n	let local = instancePos + vec3f(aVertex.x, 0.0, aVertex.z) * footprint;\n\n	let clip = uFrame.projection * uMesh.view * uMesh.model * vec4f(local, 1.0);\n	// WebGPU clip space is [0, w] in Z where GL is [-w, w]\n	out.position = vec4f(clip.xy, (clip.z + clip.w) * 0.5, clip.w);\n\n	let tinted = aColor * uMesh.tint;\n	out.vColor = vec4f(tinted.rgb * tinted.a, tinted.a);\n	// a blob fades with distance like the ground it lies on\n	if (enable_fog) {\n		let viewPos = uMesh.view * uMesh.model * vec4f(local, 1.0);\n		out.vFogDepth = length(viewPos.xyz)\n			* fog_height_factor(viewPos.xyz);\n	} else {\n		out.vFogDepth = 0.0;\n	}\n	out.vRegion = aRegion;\n	return out;\n}\n\n// Fold distance fog into a PREMULTIPLIED colour. Twin of `apply_fog` in\n// mesh.wgsl \u2014 kept in step by hand (WGSL has no preprocessor, and the build\n// loads shaders as raw text). Present here because on WebGL this vertex\n// shader pairs with mesh.frag, which fogs; without this the two backends would\n// disagree on whether distant shadows fade.\nfn apply_fog(rgb : vec3f, a : f32, fogDepth : f32) -> vec3f {\n	if (!enable_fog) {\n		return rgb;\n	}\n	let mode = uMesh.fogParams.x;\n	if (mode < 0.5) {\n		return rgb;\n	}\n	var f : f32;\n	if (mode < 1.5) {\n		f = 1.0 - clamp((fogDepth - uMesh.fogParams.y) * uMesh.fogParams.z, 0.0, 1.0);\n	} else {\n		let dd = fogDepth * uMesh.fogParams.w;\n		f = exp(-dd * dd);\n	}\n	return mix(uMesh.fogColor.rgb * a, rgb, f);\n}\n\n@fragment\nfn fragment_main(in : VSOut) -> @location(0) vec4f {\n	let texel = textureSample(uTexture, uSampler, in.vRegion);\n	let color = texel * in.vColor;\n	return vec4f(apply_fog(color.rgb, color.a, in.vFogDepth), color.a);\n}\n";
@@ -52596,11 +53502,13 @@ var WebGPUMeshBatcher = class extends WebGPUBatcher {
     }
     this.vertexLayoutKey = vertexLayoutKey;
     this.customShader = null;
+    this.hostedEffect = null;
     this.indexData = new Uint32Array(this.vertexData.maxVertex * 6);
     this.indexCount = 0;
     this.currentMaterial = null;
     this.uniformBinding = null;
     this.uniformBindGroups = /* @__PURE__ */ new Map();
+    this.effectBindGroups = /* @__PURE__ */ new Map();
     this.meshState = { cullMode: "back", frontFace: "ccw" };
     if (this.retained !== void 0) {
       this.releaseAllRetained();
@@ -52745,9 +53653,11 @@ var WebGPUMeshBatcher = class extends WebGPUBatcher {
     const frame = renderer.currentFrameBinding;
     pass.setBindGroup(0, frame.bindGroup, [frame.dynamicOffset]);
     this.bindLights(pass);
-    pass.setBindGroup(3, this.uniformBinding.bindGroup, [
-      this.uniformBinding.dynamicOffset
-    ]);
+    pass.setBindGroup(
+      3,
+      this.uniformBinding.bindGroup,
+      this.uniformBinding.offsets
+    );
     pass.setVertexBuffer(0, geometry.vertexBuffer);
     pass.setVertexBuffer(1, instances.buffer);
     pass.setIndexBuffer(geometry.indexBuffer, geometry.indexFormat);
@@ -52856,9 +53766,11 @@ var WebGPUMeshBatcher = class extends WebGPUBatcher {
     pass.setBindGroup(0, frame.bindGroup, [frame.dynamicOffset]);
     pass.setBindGroup(1, this.currentMaterial);
     this.bindLights(pass);
-    pass.setBindGroup(3, this.uniformBinding.bindGroup, [
-      this.uniformBinding.dynamicOffset
-    ]);
+    pass.setBindGroup(
+      3,
+      this.uniformBinding.bindGroup,
+      this.uniformBinding.offsets
+    );
     pass.setVertexBuffer(0, quadGeometry.vertexBuffer);
     pass.setVertexBuffer(1, instances.buffer);
     pass.setIndexBuffer(quadGeometry.indexBuffer, quadGeometry.indexFormat);
@@ -52946,6 +53858,108 @@ var WebGPUMeshBatcher = class extends WebGPUBatcher {
   uniformSignature() {
     return `mesh:u${MESH_UNIFORM_SIZE}`;
   }
+  /**
+   * The group-3 layout when a `ShaderEffect` is hosted on the mesh (#1658).
+   *
+   * `uMesh` keeps binding 0 — the spliced module is the engine's own mesh
+   * shader and still declares it there — and the effect's own uniform block
+   * takes binding 1, its texture/sampler pairs following at their declared
+   * bindings shifted by the same one. That shift is why the body is rewritten
+   * rather than pasted: a quad effect declares its block at
+   * `@group(3) @binding(0)`, which is exactly where `uMesh` lives.
+   * @param {object} effect - the hosted effect
+   * @returns {GPUBindGroupLayout} the combined layout
+   * @ignore
+   * @internal
+   */
+  hostedEffectLayout(effect) {
+    const realization = effect.wgslRealization;
+    const entries = [
+      {
+        binding: 0,
+        visibility: GPUShaderStage.VERTEX | GPUShaderStage.FRAGMENT,
+        buffer: {
+          type: "uniform",
+          hasDynamicOffset: true,
+          minBindingSize: MESH_UNIFORM_SIZE
+        }
+      }
+    ];
+    let signature = `${this.uniformSignature()}|fx${realization.structSize}`;
+    if (realization.structSize > 0) {
+      entries.push({
+        binding: 1,
+        visibility: GPUShaderStage.FRAGMENT,
+        buffer: {
+          type: "uniform",
+          hasDynamicOffset: true,
+          minBindingSize: realization.structSize
+        }
+      });
+    }
+    return this.renderer.pipelineCache.getEffectLayout(signature, entries);
+  }
+  /**
+   * Build the group-3 binding for a draw that hosts an effect: `uMesh`
+   * plus a fresh snapshot of the effect's uniform mirror, plus its
+   * textures.
+   * @param {GPUDevice} device - the device
+   * @param {object} renderer - the owning renderer
+   * @param {object} effect - the hosted effect
+   * @param {object} meshRegion - the arena region already holding `uMesh`
+   * @returns {{bindGroup: GPUBindGroup, offsets: number[]}} the binding
+   * @ignore
+   * @internal
+   */
+  bindHostedEffect(device, renderer, effect, meshRegion) {
+    const realization = effect.wgslRealization;
+    const entries = [
+      {
+        binding: 0,
+        resource: { buffer: meshRegion.buffer, size: MESH_UNIFORM_SIZE }
+      }
+    ];
+    const offsets = [meshRegion.offset];
+    if (realization.structSize > 0) {
+      const region = renderer.effectUniformArena.alloc(
+        realization.structSize,
+        device.limits.minUniformBufferOffsetAlignment
+      );
+      device.queue.writeBuffer(
+        region.buffer,
+        region.offset,
+        realization.cpu,
+        0,
+        realization.structSize
+      );
+      entries.push({
+        binding: 1,
+        resource: { buffer: region.buffer, size: realization.structSize }
+      });
+      offsets.push(region.offset);
+    }
+    const effectBuffer = offsets.length > 1 ? entries[1].resource.buffer : null;
+    let byEffectPage = this.effectBindGroups.get(meshRegion.buffer);
+    if (byEffectPage === void 0) {
+      byEffectPage = /* @__PURE__ */ new Map();
+      this.effectBindGroups.set(meshRegion.buffer, byEffectPage);
+    }
+    let byEffect = byEffectPage.get(effectBuffer);
+    if (byEffect === void 0) {
+      byEffect = /* @__PURE__ */ new Map();
+      byEffectPage.set(effectBuffer, byEffect);
+    }
+    let bindGroup = byEffect.get(effect._effectId);
+    if (bindGroup === void 0) {
+      bindGroup = device.createBindGroup({
+        label: "melonJS mesh uniforms + hosted effect",
+        layout: this.hostedEffectLayout(effect),
+        entries
+      });
+      byEffect.set(effect._effectId, bindGroup);
+    }
+    return { bindGroup, offsets };
+  }
   /**
    * The shader family for the next recorded draw: the built-in family,
    * or the hosted custom module when `renderer.drawMesh` routed a
@@ -52960,6 +53974,27 @@ var WebGPUMeshBatcher = class extends WebGPUBatcher {
    * @internal
    */
   activeShaderKey() {
+    const effect = this.hostedEffect;
+    if (effect != null) {
+      const cache4 = this.renderer.pipelineCache;
+      if (this._effectKeys?.epoch !== cache4.epoch) {
+        this._effectKeys = { epoch: cache4.epoch, keys: /* @__PURE__ */ new Map() };
+      }
+      const host = `${this.vertexLayoutKey}|fx${effect._effectId}`;
+      let key2 = this._effectKeys.keys.get(host);
+      if (typeof key2 === "undefined") {
+        key2 = cache4.registerShader(
+          effect.wgslRealization.meshModule(this.shaderSource()),
+          {
+            bindGroupLayouts: this.bindGroupLayoutList(cache4),
+            vertexLayoutKey: this.vertexLayoutKey,
+            label: `melonJS ${this.vertexLayoutKey} + hosted effect`
+          }
+        );
+        this._effectKeys.keys.set(host, key2);
+      }
+      return key2;
+    }
     const custom = this.customShader;
     if (custom === null) {
       return this.shaderKey;
@@ -52984,9 +54019,27 @@ var WebGPUMeshBatcher = class extends WebGPUBatcher {
       cache3.frameLayout,
       cache3.meshMaterialLayout,
       cache3.emptyLayout,
-      this.meshLayout
+      this.perDrawLayout()
     ];
   }
+  /**
+   * The group-3 layout for the draw being recorded: `uMesh` alone, or
+   * `uMesh` plus a hosted effect's own block.
+   *
+   * A single accessor on purpose. Every subclass builds its own positional
+   * layout list — the lit tier swaps group 2 for its light block — and when
+   * this choice was inlined into the base list only, the lit subclass kept
+   * handing over the plain layout while the module declared the effect's
+   * binding. The pipeline then failed to validate with "Binding doesn't
+   * exist", every frame drawing that mesh was dropped, and the scene
+   * flickered. Subclasses override the list; they must not re-decide this.
+   * @returns {GPUBindGroupLayout} the group-3 layout
+   * @ignore
+   * @internal
+   */
+  perDrawLayout() {
+    return this.hostedEffect != null ? this.hostedEffectLayout(this.hostedEffect) : this.meshLayout;
+  }
   /**
    * Resolve the group-1 material for a mesh: its texture through the
    * texture store, honouring the mesh's own `textureRepeat` wrap override
@@ -53103,6 +54156,16 @@ var WebGPUMeshBatcher = class extends WebGPUBatcher {
       0,
       MESH_UNIFORM_SIZE
     );
+    const effect = this.hostedEffect;
+    if (effect !== null && effect !== void 0) {
+      this.uniformBinding = this.bindHostedEffect(
+        device,
+        renderer,
+        effect,
+        region
+      );
+      return;
+    }
     let bindGroup = this.uniformBindGroups.get(region.buffer);
     if (typeof bindGroup === "undefined") {
       bindGroup = device.createBindGroup({
@@ -53117,7 +54180,7 @@ var WebGPUMeshBatcher = class extends WebGPUBatcher {
       });
       this.uniformBindGroups.set(region.buffer, bindGroup);
     }
-    this.uniformBinding = { bindGroup, dynamicOffset: region.offset };
+    this.uniformBinding = { bindGroup, offsets: [region.offset] };
   }
   /**
    * Write one vertex into the staging buffer. The base (unlit) layout is
@@ -53273,9 +54336,11 @@ var WebGPUMeshBatcher = class extends WebGPUBatcher {
     pass.setBindGroup(0, frame.bindGroup, [frame.dynamicOffset]);
     pass.setBindGroup(1, this.currentMaterial);
     this.bindLights(pass);
-    pass.setBindGroup(3, this.uniformBinding.bindGroup, [
-      this.uniformBinding.dynamicOffset
-    ]);
+    pass.setBindGroup(
+      3,
+      this.uniformBinding.bindGroup,
+      this.uniformBinding.offsets
+    );
     pass.setVertexBuffer(
       0,
       vertexRegion.buffer,
@@ -53386,9 +54451,11 @@ var WebGPUMeshBatcher = class extends WebGPUBatcher {
     const frame = renderer.currentFrameBinding;
     pass.setBindGroup(0, frame.bindGroup, [frame.dynamicOffset]);
     this.bindLights(pass);
-    pass.setBindGroup(3, this.uniformBinding.bindGroup, [
-      this.uniformBinding.dynamicOffset
-    ]);
+    pass.setBindGroup(
+      3,
+      this.uniformBinding.bindGroup,
+      this.uniformBinding.offsets
+    );
     pass.setVertexBuffer(0, geometry.vertexBuffer);
     pass.setIndexBuffer(geometry.indexBuffer, geometry.indexFormat);
     const slices = mesh.textureGroups;
@@ -53438,8 +54505,10 @@ var WebGPUMeshBatcher = class extends WebGPUBatcher {
     this.indexCount = 0;
     this.currentMaterial = null;
     this.customShader = null;
+    this.hostedEffect = null;
     this.uniformBinding = null;
     this.uniformBindGroups.clear();
+    this.effectBindGroups.clear();
     this.releaseAllRetained();
   }
   /**
@@ -53547,7 +54616,9 @@ var WebGPULitMeshBatcher = class extends WebGPUMeshBatcher {
       cache3.frameLayout,
       cache3.meshMaterialLayout,
       this.ensureLightsLayout(),
-      this.meshLayout
+      // NOT `this.meshLayout`: a hosted effect extends group 3, and the
+      // base decides that for every tier (see `perDrawLayout`)
+      this.perDrawLayout()
     ];
   }
   /**
@@ -54334,46 +55405,75 @@ var WebGPUPipelineCache = class _WebGPUPipelineCache {
         primitive.cullMode = meshState.cullMode;
         primitive.frontFace = meshState.frontFace;
       }
-      pipeline = this.device.createRenderPipeline({
-        label: `melonJS ${key}`,
-        layout: this.pipelineLayouts[shaderKey],
-        vertex: {
-          module: this.modules[shaderKey],
-          entryPoint: "vertex_main",
-          buffers: vertexLayout ?? [],
-          ...meshState ? { constants: { enable_fog: fogFlag } } : {}
-        },
-        fragment: {
-          module: this.modules[shaderKey],
-          entryPoint: "fragment_main",
-          ...meshState ? { constants: { enable_fog: fogFlag } } : {},
-          targets: [
-            {
-              format: this.format,
-              blend: shaderKey === "clear" ? void 0 : gpuBlendState(blend, pma),
-              writeMask: stencil.colorWriteMask
-            }
-          ]
-        },
-        primitive,
-        depthStencil: {
-          format: DEPTH_STENCIL_FORMAT,
-          // `!== false`, not `!!`: mesh draws that never set the field (and
-          // every bare `{cullMode, frontFace}` literal) must keep writing
-          // depth exactly as they did before the axis existed
-          depthWriteEnabled: meshState ? meshState.depthWrite !== false : false,
-          depthCompare: meshState ? "less-equal" : "always",
-          stencilFront: stencil.stencil,
-          stencilBack: stencil.stencil,
-          stencilReadMask: stencil.readMask,
-          stencilWriteMask: stencil.writeMask
-        },
-        multisample: { count: this.sampleCount }
-      });
+      pipeline = this.device.createRenderPipeline(
+        this._descriptor(key, shaderKey, blend, pma, stencil, primitive, {
+          vertexLayout,
+          meshState,
+          fogFlag
+        })
+      );
       this.pipelines.set(key, pipeline);
     }
     return pipeline;
   }
+  /**
+   * Assemble a pipeline descriptor.
+   *
+   * Split out of `get()` so the descriptor can be read on its own — it is
+   * long, and every field in it is load-bearing for cache correctness: a
+   * pipeline built from a descriptor that differs from the one a draw would
+   * have produced is worse than no cache entry at all, because the draw
+   * silently builds a second one under a key nothing will hit again.
+   * @param {string} key - the cache key, used as the label
+   * @param {string} shaderKey - the module family
+   * @param {string} blend - normalized blend mode
+   * @param {boolean} pma - premultiplied alpha
+   * @param {object} stencil - the resolved stencil state
+   * @param {object} primitive - the resolved primitive state
+   * @param {object} opts - `{vertexLayout, meshState, fogFlag}`
+   * @returns {GPURenderPipelineDescriptor} the descriptor
+   * @ignore
+   * @internal
+   */
+  _descriptor(key, shaderKey, blend, pma, stencil, primitive, opts) {
+    const { vertexLayout, meshState, fogFlag } = opts;
+    return {
+      label: `melonJS ${key}`,
+      layout: this.pipelineLayouts[shaderKey],
+      vertex: {
+        module: this.modules[shaderKey],
+        entryPoint: "vertex_main",
+        buffers: vertexLayout ?? [],
+        ...meshState ? { constants: { enable_fog: fogFlag } } : {}
+      },
+      fragment: {
+        module: this.modules[shaderKey],
+        entryPoint: "fragment_main",
+        ...meshState ? { constants: { enable_fog: fogFlag } } : {},
+        targets: [
+          {
+            format: this.format,
+            blend: shaderKey === "clear" ? void 0 : gpuBlendState(blend, pma),
+            writeMask: stencil.colorWriteMask
+          }
+        ]
+      },
+      primitive,
+      depthStencil: {
+        format: DEPTH_STENCIL_FORMAT,
+        // `!== false`, not `!!`: mesh draws that never set the field (and
+        // every bare `{cullMode, frontFace}` literal) must keep writing
+        // depth exactly as they did before the axis existed
+        depthWriteEnabled: meshState ? meshState.depthWrite !== false : false,
+        depthCompare: meshState ? "less-equal" : "always",
+        stencilFront: stencil.stencil,
+        stencilBack: stencil.stencil,
+        stencilReadMask: stencil.readMask,
+        stencilWriteMask: stencil.writeMask
+      },
+      multisample: { count: this.sampleCount }
+    };
+  }
   /**
    * drop every cached pipeline (device loss — the whole cache object is
    * rebuilt by the renderer's restore path, this exists for symmetry)
@@ -57568,6 +58668,45 @@ var WebGPURenderer = class _WebGPURenderer extends Renderer {
     }
     return this.renderPass;
   }
+  /**
+   * Compile the WGSL module of every shader asset the loader has, ahead of
+   * the frame that first draws it.
+   *
+   * WebGPU splits what WebGL fuses into one program. The **modules** for
+   * the engine's own families — quad, blit, primitive, clear, and the mesh
+   * tiers — are already created when the pipeline cache and the batchers
+   * are constructed, so there is nothing lazy there to warm. A **pipeline**
+   * is lazy, but it is keyed by draw state (blend, cull, depth-write) as
+   * well as by shader, so the set a scene will ask for cannot be known from
+   * here — and creating one costs almost nothing anyway, because WebGPU
+   * records the intent and leaves the work to first use.
+   *
+   * What IS both lazy and knowable is a `ShaderEffect`'s module:
+   * `prepareEffectBinding` builds it, and it is only ever called from
+   * inside the draw path. Every effect the loader compiled from a
+   * `{type: "shader"}` asset is already in `shaderList`, so those are
+   * exactly the ones that can be brought forward — which is what makes
+   * declaring a level's effects alongside that level's assets worth doing.
+   *
+   * Effects constructed inline when a stage builds are not here yet and
+   * cannot be warmed; that is a property of when they come into existence,
+   * not a limitation of this method.
+   * @returns {Promise<void>} settles once those modules are built
+   * @see {@link Renderer#prewarm}
+   */
+  prewarm() {
+    return Promise.resolve().then(() => {
+      for (const effect of Object.values(shaderList)) {
+        const realization = effect?.wgslRealization;
+        if (realization === void 0 || realization.valid !== true) {
+          continue;
+        }
+        if (realization.gpu === null || realization.gpu.epoch !== this.pipelineCache.epoch) {
+          buildEffectGPU(this, effect, realization);
+        }
+      }
+    });
+  }
   /**
    * end the open pass and submit the frame's command buffer
    * @override
@@ -57841,23 +58980,46 @@ var WebGPURenderer = class _WebGPURenderer extends Renderer {
       this.pendingDepthClear = true;
     }
     const customShader = this.customShader != null && this.customShader.isWebGPU === true ? this.customShader : null;
-    if (this.customShader != null && customShader === null && this.meshEffectWarned !== true) {
+    const hostedEffect = customShader === null && this.customShader != null && typeof this.customShader.wgslRealization !== "undefined" && meshHostingBlocker(
+      this.customShader.wgslRealization.builtins,
+      this.customShader.wgslRealization.textures,
+      "wgsl"
+    ) === null && this.customShader.wgslRealization.meshModule(
+      this.batchers.get(
+        mesh.lit === true && this.batchers.has("litMesh") ? "litMesh" : "mesh"
+      )?.shaderSource?.() ?? ""
+    ) !== null ? this.customShader : null;
+    if (this.customShader != null && customShader === null && hostedEffect === null && this.meshEffectWarned !== true) {
       this.meshEffectWarned = true;
+      const realization = this.customShader.wgslRealization;
+      const blocker = typeof realization !== "undefined" ? meshHostingBlocker(
+        realization.builtins,
+        realization.textures,
+        "wgsl"
+      ) : null;
       console.warn(
-        "melonJS: this custom shader cannot be hosted on a Mesh by the WebGPU renderer (it carries no `wgsl` module) \u2014 the mesh draws with the built-in shading"
+        blocker !== null ? `melonJS: this ShaderEffect cannot be hosted on a Mesh \u2014 ${blocker}. The mesh draws with the built-in shading.` : "melonJS: this custom shader cannot be hosted on a Mesh by the WebGPU renderer (it carries no `wgsl` module) \u2014 the mesh draws with the built-in shading"
       );
     }
     const batcher = this.setBatcher(
       mesh.lit === true && this.batchers.has("litMesh") ? "litMesh" : "mesh"
     );
     batcher.customShader = customShader;
+    const instanced = mesh.instanceLayout !== void 0 && retained && this.supportsInstancing === true;
+    if (instanced && hostedEffect !== null && this.instancedEffectWarned !== true) {
+      this.instancedEffectWarned = true;
+      console.warn(
+        "melonJS: a ShaderEffect cannot be hosted on an InstancedMesh \u2014 the instanced shading is a separate shader family. The mesh draws with the built-in shading."
+      );
+    }
+    batcher.hostedEffect = instanced ? null : hostedEffect;
     const culling = mesh.cullBackFaces === true;
     const state4 = batcher.meshState;
     state4.cullMode = culling ? "back" : "none";
     state4.frontFace = culling && retained && mesh.rightHanded !== true ? "cw" : "ccw";
     try {
       const tint = this.currentTint.toUint32(this.getGlobalAlpha());
-      if (mesh.instanceLayout !== void 0 && retained && this.supportsInstancing === true) {
+      if (instanced) {
         batcher.drawInstancedMesh(mesh, modelMatrix, tint);
       } else if (retained) {
         batcher.drawRetainedMesh(mesh, modelMatrix, tint);
@@ -57867,6 +59029,7 @@ var WebGPURenderer = class _WebGPURenderer extends Renderer {
       }
     } finally {
       batcher.customShader = null;
+      batcher.hostedEffect = null;
     }
   }
   /**
@@ -59349,6 +60512,7 @@ var defaultApplicationSettings = {
   powerPreference: "default",
   transparent: false,
   antiAlias: false,
+  prewarm: true,
   textureFilter: "auto",
   maxTextures: "auto",
   castGroundShadow: true,
@@ -60914,7 +62078,7 @@ var Sprite3d = class extends Mesh {
    * @param {number} x - world x position
    * @param {number} y - world y position
    * @param {object} settings - configuration
-   * @param {HTMLImageElement|Texture2d|string} [settings.image] - the sprite texture (image name, image, or a {@link Texture2d} asset such as a {@link TextureAtlas}). Alias: `settings.texture`.
+   * @param {HTMLImageElement|HTMLCanvasElement|Texture2d|string} [settings.image] - the sprite texture (image name, image, or a {@link Texture2d} asset such as a {@link TextureAtlas}). Alias: `settings.texture`.
    * @param {number} [settings.width=settings.framewidth] - quad width in world units (pixels)
    * @param {number} [settings.height=settings.width] - quad height in world units
    * @param {number} [settings.framewidth] - width of a single frame within a spritesheet (enables frame animation)
@@ -60928,6 +62092,11 @@ var Sprite3d = class extends Mesh {
    * @param {boolean} [settings.flipY=false] - mirror the sprite vertically (see {@link Sprite3d#flipY})
    * @param {boolean} [settings.lit=false] - shade through the lit mesh batcher (see {@link Mesh})
    * @param {number[]|Float32Array} [settings.emissive] - emissive color (see {@link Mesh})
+   * @param {number} [settings.shadowGroundY] - world Y of the floor the blob shadow lands on. Omit and it falls back to the sprite's own base — which for a billboard moves with the camera, so a scene that knows where its floor is should say so.
+   * @param {number} [settings.shadowOpacity=0.45] - opacity of the shadow directly beneath the sprite, before any height fade
+   * @param {boolean} [settings.castGroundShadow] - give this sprite a blob ground shadow, overriding the application's `castGroundShadow` setting in both directions. Omit to inherit. Needs a GPU backend and a {@link Camera3d}.
+   * @param {boolean} [settings.fog] - set `false` to exempt this sprite from the camera's distance fog ({@link Camera3d#setFog}); omit to fog whenever the camera does. A sun or a moon wants this — everything else at that distance dissolves into the haze, and so would it.
+   * @param {boolean} [settings.transparent] - draw in the transparent pass (blended, back-to-front, no depth write) instead of the opaque one. Omit and the sprite goes transparent whenever its draw alpha is fractional; `true` for a soft-alpha sprite such as an additive glow; `false` to stay opaque however faded.
    * @param {number} [settings.alphaCutoff=0.5] - alpha cutout threshold (see {@link Mesh}). The mesh pass is opaque (no alpha blending), so this defaults to `0.5` to discard a sprite's transparent background (clean cutout silhouette, correct depth, no sorting). Set `0` for a fully-opaque quad, or tune the threshold.
    */
   constructor(x, y, settings) {
@@ -61010,6 +62179,7 @@ var Sprite3d = class extends Mesh {
       // flatten it to an explicit false, silently opting every sprite out
       // of a scene-wide default
       castGroundShadow: settings.castGroundShadow,
+      fog: settings.fog,
       // raw for the same reason as above: `undefined` means "decide from
       // the draw's alpha", and coercing it would pin every sprite opaque
       transparent: settings.transparent,
@@ -64247,25 +65417,8 @@ var lerp3 = (a, b, t) => {
 };
 var NoiseTexture2d = class extends Texture2d {
   /**
-   * @param {object} [settings] - configuration; any {@link Noise} setting
-   * (`type`, `seed`, `frequency`/`scale`, `octaves`, `gain`/`persistence`,
-   * `lacunarity`, `fractalType`, domain-warp settings) is forwarded when no
-   * `noise` instance is given.
-   * @param {number} [settings.width=256] - baked texture width in pixels
-   * @param {number} [settings.height=256] - baked texture height in pixels
-   * @param {Noise} [settings.noise] - an existing {@link Noise} to bake; when
-   * omitted one is built from the forwarded settings
-   * @param {boolean} [settings.seamless=false] - tile cleanly in both axes
-   * @param {number} [settings.seamlessBlendSkirt=0.1] - edge blend band width
-   * as a fraction (0..1) of the smaller dimension, when `seamless`
-   * @param {boolean} [settings.invert=false] - invert the noise value (`1 - v`)
-   * @param {boolean} [settings.asNormalMap=false] - encode as a normal map
-   * @param {number} [settings.bumpStrength=1] - normal steepness when `asNormalMap`
-   * @param {Gradient} [settings.colorRamp] - map the noise value to a color
-   * @param {boolean} [settings.animated=false] - sample in 3D (`getNoise3d`)
-   * using an internal `time` as the third axis, advanced by {@link NoiseTexture2d#update}
-   * @param {number} [settings.speed=1] - animation speed in noise z-units per
-   * second (only used while `animated`)
+   * @param {NoiseTexture2dSettings} [settings] - bake settings, plus any
+   * {@link NoiseSettings} for the field itself
    */
   constructor(settings = {}) {
     super();