fix(video): six GL-core audit findings, each reproduced before fixing

Beat 1 of the resumed subsystem audit (video/GL core, single-finder +
inline verification). Per protocol every bug was demonstrated red with
a reproduction test BEFORE being touched; one finding was refined
during reproduction (fillRect gradients never used the stencil path —
scoped the fix to the shape fills that do).

1. getSupportedCompressedTextureFormats: six WEBKIT fallbacks read the
   never-assigned `this._gl` → TypeError on any device missing one
   compression family (everything except ANGLE/Metal Macs — which is
   why it survived: the dev machines expose every family). → `gl.`
2. Nested multi-effect post-effects: RenderTargetPool's two scalars
   (_activeBase/_previousBase) became a proper base STACK — each
   nested sprite pass gets its own lazily-allocated capture/ping-pong
   pair (2/3, 4/5, …) and begin/end pairs unwind like save/restore;
   the saved effect projection is a per-pass stack too. Pre-fix, a
   2-effect child inside a 2-effect container cleared the parent's
   capture, popped its slot, and crashed endPostEffect every frame.
3. #gradientMask: write/clip/restore phases now use a high-bit stencil
   marker (collision-free with mask levels) gated on the VISIBLE value
   of the active mask (0 when inverted, maskLevel otherwise), and
   restore setMask's exact stencil test — the old code painted
   gradients inside inverted cutouts and left a NOTEQUAL parity test
   that inverted/leaked all subsequent masked draws. setMask/clearMask
   now track _maskInvert.
4. disableScissor() flushes pending quads before disabling the test
   (mirrors enableScissor/clipRect/restore) — batched sprites could
   escape the scissor entirely.
5. WebGL clearRect() erases to actual transparent black per its JSDoc
   ("#000000" parses with alpha 1 → it painted opaque black; Canvas
   parity).
6. Canvas clipRect() skip-optimizations now reason in DEVICE space
   (rotation/skew always clips + cache poisoned): the local-space
   early-outs dropped canvas-sized clips under a translate and skipped
   nested same-size clips via the stale cache.

Reproductions: tests/glcore-audit.spec.js (5) +
tests/canvas-cliprect-transform.spec.js (2) — all 7 red on the unfixed
code (nested-FBO red with the exact predicted undefined.unbind).
renderTargetPool.spec.js updated to the stack internals + 2 new
nesting tests. Full suite 4736 passed / 0 failed.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_019t8kP8vp58ZrvaD2FqJU6A

Author: obiot

packages/melonjs/CHANGELOG.md

@@ -26,6 +26,12 @@
 - **`moveTowards()` never reached its target — and returned the target instead of `this`** (all four vector classes) — the arrival test compared the remaining distance against `step * step` (wrong units: snapped way too early for steps above 1, dithered around the target forever for fractional steps), and on "arrival" it returned the **caller's target vector** without moving `this` at all — so the vector never landed, and chaining onto the result silently mutated the target. It now lands exactly on the target and always returns `this`, per its own documentation; negative-step flee semantics are unchanged.
 - **Every preloaded video was fetched with forced anonymous CORS** — the video parser unconditionally stamped the `crossorigin` attribute with the loader's `crossOrigin` setting, which defaults to `undefined` — and per the HTML spec an *invalid* value (the string `"undefined"`) maps to `anonymous`, unlike a *missing* attribute (no CORS). Cross-origin videos served without CORS headers failed to load outright when they would have played fine untainted. The attribute is now only set when `crossOrigin` is actually configured (the empty string remains a valid, honored value).
 - **Video preloading hung forever on autoplay-restricted browsers (e.g. iOS Safari) unless `autoplay: false` was spelled out** — the parser waited for `canplay`, which those browsers never fire for a video that isn't allowed to play, and only an *explicit* `autoplay: false` opted into the reliable `loadedmetadata` path — so the common manifest shape (no `autoplay` key) stalled the whole preloader and the game never started. Preloading now completes on `loadedmetadata` unless `autoplay: true` explicitly asks to wait for `canplay`.
+- **Compressed-texture loading crashed on any device missing one compression family** — six `WEBKIT_`-prefixed extension fallbacks in `getSupportedCompressedTextureFormats()` referenced `this._gl`, a field that is never assigned (the context lives in `this.gl`). The fallback only evaluates when the primary extension is absent, so the whole feature *worked on ANGLE/Metal Macs* (which expose every family) *and threw a TypeError everywhere else* — Windows (no ASTC), iOS (no S3TC), software renderers — killing every `.dds`/`.pvr`/`.pkm`/`.ktx`/`.ktx2` load.
+- **Nested multi-effect post-effects corrupted the render-target pool and crashed every frame** — a renderable with 2+ `postEffects` drawn inside a container with 2+ `postEffects` hit a half-guarded nesting path: the inner pass cleared the outer pass's capture target, its `end` popped the outer pass's pool slot, and the outer `endPostEffect` then dereferenced `undefined` (per-frame TypeError; with camera effects active it silently blitted the wrong texture instead). The pool now tracks a proper stack of passes — each nesting level gets its own lazily-allocated capture/ping-pong pair — and the saved effect projection is a per-pass stack too, so nested post-effect passes compose correctly.
+- **Gradient shape fills (`fillEllipse`/`fillPolygon`/`fillArc`/`fillRoundRect`) broke inverted and nested masks** — the internal stencil pass gated its write phase on the *hidden* region of an inverted `setMask` (painting the gradient inside the cutout instead of the visible area) and restored a `NOTEQUAL` parity test instead of the mask's actual test — inverting the mask for every subsequent draw, and leaking outside-all-masks pixels for nested masks. The pass now tags the shape's visible pixels with a high stencil bit (collision-free with mask levels), clips the gradient to the tag, and re-installs the exact stencil test `setMask` had established. (`fillRect` gradients were unaffected — they render through a textured quad.)
+- **`disableScissor()` didn't flush, so sprites batched inside the scissor escaped it** — GL scissor applies at draw time, not at batch time; every other scissor mutation (`enableScissor`, `clipRect`, `restore`) flushes pending vertices first, but `disableScissor` didn't — so the common `enableScissor → drawImage → disableScissor` pattern clipped nothing: the quads were still queued when the test was turned off.
+- **WebGL `clearRect()` painted opaque black instead of erasing** — its JSDoc (and the Canvas renderer) promise transparent black, but the internal `clearColor()` default (`"#000000"`) parses with alpha 1. Visible on `transparent: true` canvases and inside post-effect render targets, where the "erased" region composited as a solid black box.
+- **Canvas `clipRect()` skip-optimizations ignored the active transform** — the "full-viewport no-op" and "same-as-last-clip" early-outs compared the rect's raw *local* values, so a canvas-sized clipped container positioned off-origin got no clip at all, and a clipped container nested inside a same-sized clipped container skipped its own clip via the stale cache — both Canvas-only divergences from the transform-aware WebGL scissor path (the #1349 fix). The skip logic now reasons in device space (and always clips under rotation/skew, where an axis-aligned cache can't).
 - **`Path2D.arc()`/`arcTo()`/`ellipse()` appended to an open path started a new sub-path instead of connecting** — the native Path2D spec joins an arc to the current point with a straight line (`arcTo`'s own documentation even promises it), but all three called `moveTo()` unconditionally. Under this release's new multi-sub-path fill semantics that stray sub-path is treated as a **hole**, so an arc appended to a filled outline punched a hole in the shape. They now connect per the spec; the canonical circle-hole idiom (explicit `moveTo` before `arc()`) still registers a hole, and a virgin-path `arc()` still starts cleanly.
 - **`Rect.right`/`Rect.bottom` returned the width/height when the edge sat exactly at coordinate 0** — the getters computed `this.left + w || w`, so an edge landing precisely on 0 (falsy) fell back to the size. Bounds and collision math around the origin came out wrong for such rectangles.
 - **`Rect.toPolygon()` handed out the rectangle's live vertices** — `Polygon.setVertices` stores a `Vector2d[]` by reference, so the "new" polygon shared the rect's actual points array: transforming or mutating the polygon silently corrupted the rectangle. The vertices are now cloned.

packages/melonjs/src/video/canvas/canvas_renderer.js

@@ -1255,31 +1255,59 @@ export default class CanvasRenderer extends Renderer {
 	 * @param {number} height
 	 */
 	clipRect(x, y, width, height) {
+		const context = this.getContext();
+		const t = context.getTransform();
+
+		// The two skip-optimizations below (full-viewport no-op and
+		// same-as-last-clip) must reason in DEVICE space — the rect arrives
+		// in LOCAL coordinates (e.g. Container clipping translates first,
+		// then clips at (0, 0)), so comparing raw values against the canvas
+		// box or the cache is wrong under any transform. The WebGL renderer
+		// transforms the rect the same way (see the #1349 fix).
+		if (t.b !== 0 || t.c !== 0) {
+			// rotated/skewed: the axis-aligned skip logic can't reason about
+			// the clipped region — always clip, and poison the cache so a
+			// following axis-aligned call can't false-match
+			context.beginPath();
+			context.rect(x, y, width, height);
+			context.clip();
+			this.currentScissor[0] = Number.NaN;
+			return;
+		}
+
+		// axis-aligned device-space box (scale can be negative — normalize)
+		let dx = x * t.a + t.e;
+		let dy = y * t.d + t.f;
+		let dw = width * t.a;
+		let dh = height * t.d;
+		if (dw < 0) {
+			dx += dw;
+			dw = -dw;
+		}
+		if (dh < 0) {
+			dy += dh;
+			dh = -dh;
+		}
+
 		const canvas = this.getCanvas();
-		// if requested box is different from the current canvas size;
-		if (
-			x !== 0 ||
-			y !== 0 ||
-			width !== canvas.width ||
-			height !== canvas.height
-		) {
+		// if the requested box is different from the full canvas;
+		if (dx !== 0 || dy !== 0 || dw !== canvas.width || dh !== canvas.height) {
 			const currentScissor = this.currentScissor;
 			// if different from the current scissor box
 			if (
-				currentScissor[0] !== x ||
-				currentScissor[1] !== y ||
-				currentScissor[2] !== width ||
-				currentScissor[3] !== height
+				currentScissor[0] !== dx ||
+				currentScissor[1] !== dy ||
+				currentScissor[2] !== dw ||
+				currentScissor[3] !== dh
 			) {
-				const context = this.getContext();
 				context.beginPath();
 				context.rect(x, y, width, height);
 				context.clip();
-				// save the new currentScissor box
-				currentScissor[0] = x;
-				currentScissor[1] = y;
-				currentScissor[2] = width;
-				currentScissor[3] = height;
+				// save the new scissor box in device space
+				currentScissor[0] = dx;
+				currentScissor[1] = dy;
+				currentScissor[2] = dw;
+				currentScissor[3] = dh;
 			}
 		}
 	}

packages/melonjs/src/video/rendertarget/render_target_pool.js

@@ -7,8 +7,11 @@
  * Renderer-agnostic — the actual RenderTarget creation is delegated to a
  * factory function provided by the renderer (WebGL, WebGPU, etc.).
  *
- * Camera effects use pool indices 0 and 1 (capture + ping-pong),
- * sprite effects use indices 2 and 3.
+ * Camera effects use pool indices 0 and 1 (capture + ping-pong); sprite
+ * effects use indices 2 and 3, and each NESTED sprite pass (a multi-effect
+ * renderable drawn inside another multi-effect renderable) gets its own pair
+ * above that (4/5, 6/7, …), tracked by a stack of active bases so begin/end
+ * pairs compose like save/restore.
  * Render targets are lazily created and resized to match the required dimensions.
  * @ignore
  */
@@ -21,10 +24,23 @@ export default class RenderTargetPool {
 		this._factory = factory;
 		/** @type {RenderTarget[]} */
 		this._pool = [];
-		/** @type {number} */
-		this._activeBase = -1;
-		/** @type {number} */
-		this._previousBase = -1;
+		/**
+		 * active pass bases, innermost last — a STACK, so nested begin/end
+		 * pairs unwind correctly (two scalars silently corrupted the pool on
+		 * nested passes: the inner end() popped the outer pass's slot)
+		 * @type {number[]}
+		 */
+		this._baseStack = [];
+	}
+
+	/**
+	 * The base index of the innermost active pass, or -1 when none.
+	 * @returns {number}
+	 */
+	get activeBase() {
+		return this._baseStack.length > 0
+			? this._baseStack[this._baseStack.length - 1]
+			: -1;
 	}
 
 	/**
@@ -53,16 +69,24 @@ export default class RenderTargetPool {
 	 * @returns {RenderTarget} the capture target (ready to bind)
 	 */
 	begin(isCamera, effectCount, width, height) {
-		const newBase = isCamera ? 0 : 2;
-		// guard against nested sprite post-effect passes (not yet supported)
-		if (!isCamera && this._activeBase === newBase) {
-			return this.get(this._activeBase, width, height);
+		let newBase;
+		if (isCamera) {
+			newBase = 0;
+		} else {
+			// each nested sprite pass gets its own capture/ping-pong pair
+			// (2/3, then 4/5, 6/7, … — lazily allocated)
+			let depth = 0;
+			for (const base of this._baseStack) {
+				if (base >= 2) {
+					depth++;
+				}
+			}
+			newBase = 2 + depth * 2;
 		}
-		this._previousBase = this._activeBase;
-		this._activeBase = newBase;
-		const rt = this.get(this._activeBase, width, height);
+		this._baseStack.push(newBase);
+		const rt = this.get(newBase, width, height);
 		if (effectCount > 1) {
-			this.get(this._activeBase + 1, width, height);
+			this.get(newBase + 1, width, height);
 		}
 		return rt;
 	}
@@ -72,21 +96,23 @@ export default class RenderTargetPool {
 	 * @returns {RenderTarget|undefined} the capture target, or undefined if no active pass
 	 */
 	getCaptureTarget() {
-		if (this._activeBase < 0) {
+		const base = this.activeBase;
+		if (base < 0) {
 			return undefined;
 		}
-		return this._pool[this._activeBase];
+		return this._pool[base];
 	}
 
 	/**
 	 * Get the ping-pong render target for the current active pass.
 	 * @returns {RenderTarget|undefined} the ping-pong target, or undefined if no active pass
 	 */
 	getPingPongTarget() {
-		if (this._activeBase < 0) {
+		const base = this.activeBase;
+		if (base < 0) {
 			return undefined;
 		}
-		return this._pool[this._activeBase + 1];
+		return this._pool[base + 1];
 	}
 
 	/**
@@ -95,10 +121,10 @@ export default class RenderTargetPool {
 	 * @returns {RenderTarget|null} the parent target, or null if returning to screen
 	 */
 	end() {
-		this._activeBase = this._previousBase;
-		this._previousBase = -1;
-		if (this._activeBase >= 0 && this._pool[this._activeBase]) {
-			return this._pool[this._activeBase];
+		this._baseStack.pop();
+		const base = this.activeBase;
+		if (base >= 0 && this._pool[base]) {
+			return this._pool[base];
 		}
 		return null;
 	}
@@ -126,7 +152,6 @@ export default class RenderTargetPool {
 			}
 		}
 		this._pool.length = 0;
-		this._activeBase = -1;
-		this._previousBase = -1;
+		this._baseStack.length = 0;
 	}
 }

packages/melonjs/src/video/webgl/webgl_renderer.js

@@ -104,7 +104,9 @@ export default class WebGLRenderer extends Renderer {
 		 * @type {Matrix3d}
 		 * @ignore
 		 */
-		this._savedEffectProjection = new Matrix3d();
+		// projections saved by beginPostEffect, one per (possibly nested)
+		// active pass — a stack, matching RenderTargetPool's base stack
+		this._effectProjectionStack = [];
 
 		/**
 		 * sets or returns the thickness of lines for shape drawing
@@ -162,6 +164,10 @@ export default class WebGLRenderer extends Renderer {
 		// current gradient state (null when using solid color)
 		this._currentGradient = null;
 
+		// whether the innermost active mask (setMask) is inverted — needed by
+		// #gradientMask to gate/restore the exact stencil test setMask set
+		this._maskInvert = false;
+
 		/**
 		 * The current transformation matrix used for transformations on the overall scene
 		 * (alias to renderState.currentTransform for backward compatibility)
@@ -314,22 +320,22 @@ export default class WebGLRenderer extends Renderer {
 			supportedCompressedTextureFormats = {
 				astc:
 					gl.getExtension("WEBGL_compressed_texture_astc") ||
-					this._gl.getExtension("WEBKIT_WEBGL_compressed_texture_astc"),
+					gl.getExtension("WEBKIT_WEBGL_compressed_texture_astc"),
 				bptc:
 					gl.getExtension("EXT_texture_compression_bptc") ||
-					this._gl.getExtension("WEBKIT_EXT_texture_compression_bptc"),
+					gl.getExtension("WEBKIT_EXT_texture_compression_bptc"),
 				s3tc:
 					gl.getExtension("WEBGL_compressed_texture_s3tc") ||
-					this._gl.getExtension("WEBKIT_WEBGL_compressed_texture_s3tc"),
+					gl.getExtension("WEBKIT_WEBGL_compressed_texture_s3tc"),
 				s3tc_srgb:
 					gl.getExtension("WEBGL_compressed_texture_s3tc_srgb") ||
-					this._gl.getExtension("WEBKIT_WEBGL_compressed_texture_s3tc_srgb"),
+					gl.getExtension("WEBKIT_WEBGL_compressed_texture_s3tc_srgb"),
 				pvrtc:
 					gl.getExtension("WEBGL_compressed_texture_pvrtc") ||
-					this._gl.getExtension("WEBKIT_WEBGL_compressed_texture_pvrtc"),
+					gl.getExtension("WEBKIT_WEBGL_compressed_texture_pvrtc"),
 				etc1:
 					gl.getExtension("WEBGL_compressed_texture_etc1") ||
-					this._gl.getExtension("WEBKIT_WEBGL_compressed_texture_etc1"),
+					gl.getExtension("WEBKIT_WEBGL_compressed_texture_etc1"),
 				etc2:
 					gl.getExtension("WEBGL_compressed_texture_etc") ||
 					gl.getExtension("WEBKIT_WEBGL_compressed_texture_etc") ||
@@ -819,8 +825,9 @@ export default class WebGLRenderer extends Renderer {
 		// since FBO construction temporarily changes GL framebuffer bindings
 		this.flush();
 		this.save();
-		// save the current projection (not part of the render state stack)
-		this._savedEffectProjection.copy(this.projectionMatrix);
+		// save the current projection (not part of the render state stack) —
+		// pushed per pass so nested passes each restore their own
+		this._effectProjectionStack.push(this.projectionMatrix.clone());
 
 		const rt = this._renderTargetPool.begin(isCamera, effects.length, w, h);
 		// FBO creation/resize uses TEXTURE0 — invalidate the batcher's cache for that unit
@@ -931,7 +938,7 @@ export default class WebGLRenderer extends Renderer {
 
 		// restore renderer state and projection saved in beginPostEffect
 		this.restore();
-		this.projectionMatrix.copy(this._savedEffectProjection);
+		this.projectionMatrix.copy(this._effectProjectionStack.pop());
 		this.currentBatcher.setProjection(this.projectionMatrix);
 	}
 
@@ -1057,6 +1064,13 @@ export default class WebGLRenderer extends Renderer {
 	 * Disable the scissor test, allowing rendering to the full viewport.
 	 */
 	disableScissor() {
+		if (this._scissorActive === true) {
+			// drain quads batched under the scissor BEFORE turning the test
+			// off — GL scissor applies at draw time, not at batch time
+			// (mirrors enableScissor / clipRect / restore, which all flush
+			// for exactly this reason)
+			this.flush();
+		}
 		this.gl.disable(this.gl.SCISSOR_TEST);
 		this._scissorActive = false;
 	}
@@ -1126,7 +1140,10 @@ export default class WebGLRenderer extends Renderer {
 	clearRect(x, y, width, height) {
 		this.save();
 		this.clipRect(x, y, width, height);
-		this.clearColor();
+		// actual transparent black, per the JSDoc above and the Canvas
+		// renderer's native clearRect — the bare clearColor() default
+		// ("#000000") parses with alpha 1 and would paint OPAQUE black
+		this.clearColor("rgba(0,0,0,0)");
 		this.restore();
 	}
 
@@ -2260,18 +2277,28 @@ export default class WebGLRenderer extends Renderer {
 		const gl = this.gl;
 		const grad = this._currentGradient;
 		const hasMask = this.maskLevel > 0;
-		const stencilRef = hasMask ? this.maskLevel + 1 : 1;
 		this._currentGradient = null;
 
 		this.flush();
 
 		gl.enable(gl.STENCIL_TEST);
 		gl.colorMask(false, false, false, false);
 
+		// The stencil value of currently-VISIBLE pixels, as established by
+		// setMask: 0 for an inverted mask, maskLevel otherwise. The shape's
+		// visible pixels are tagged with a high-bit marker (mask levels only
+		// use the low 7 bits, so the marker can never collide with one),
+		// the gradient is clipped to the marker, then the marker is cleared
+		// and setMask's exact render test is re-installed.
+		const visibleRef = this._maskInvert === true ? 0 : this.maskLevel;
+		let markRef = 1;
+
 		if (hasMask) {
-			// nest within existing mask level
-			gl.stencilFunc(gl.EQUAL, this.maskLevel, 0xff);
-			gl.stencilOp(gl.KEEP, gl.KEEP, gl.INCR);
+			markRef = 0x80 | visibleRef;
+			// tag: only pixels that are visible under the active mask
+			// (low bits == visibleRef) get the marker written
+			gl.stencilFunc(gl.EQUAL, markRef, 0x7f);
+			gl.stencilOp(gl.KEEP, gl.KEEP, gl.REPLACE);
 		} else {
 			gl.clear(gl.STENCIL_BUFFER_BIT);
 			gl.stencilFunc(gl.ALWAYS, 1, 0xff);
@@ -2281,26 +2308,28 @@ export default class WebGLRenderer extends Renderer {
 		drawShape();
 		this.flush();
 
-		// use stencil to clip gradient
+		// use stencil to clip the gradient to the marked pixels
 		gl.colorMask(true, true, true, true);
-		gl.stencilFunc(gl.EQUAL, stencilRef, 0xff);
+		gl.stencilFunc(gl.EQUAL, markRef, 0xff);
 		gl.stencilOp(gl.KEEP, gl.KEEP, gl.KEEP);
 
 		this._currentGradient = grad;
 		this.fillRect(x, y, w, h);
 		this.flush();
 
 		if (hasMask) {
-			// restore the parent mask level by decrementing stencil
+			// clear the marker: write the visible value back on the shape's
+			// pixels (REPLACE writes the func ref — a no-op on unmarked
+			// visible pixels, and it strips the high bit from marked ones)
 			this._currentGradient = null;
 			gl.colorMask(false, false, false, false);
-			gl.stencilFunc(gl.EQUAL, stencilRef, 0xff);
-			gl.stencilOp(gl.KEEP, gl.KEEP, gl.DECR);
+			gl.stencilFunc(gl.EQUAL, visibleRef, 0x7f);
+			gl.stencilOp(gl.KEEP, gl.KEEP, gl.REPLACE);
 			drawShape();
 			this.flush();
 			gl.colorMask(true, true, true, true);
-			// restore parent mask stencil test
-			gl.stencilFunc(gl.NOTEQUAL, this.maskLevel + 1, 1);
+			// re-install the exact render test setMask had established
+			gl.stencilFunc(gl.EQUAL, visibleRef, 0xff);
 			gl.stencilOp(gl.KEEP, gl.KEEP, gl.KEEP);
 			this._currentGradient = grad;
 		} else {
@@ -2524,6 +2553,7 @@ export default class WebGLRenderer extends Renderer {
 			gl.stencilFunc(gl.EQUAL, this.maskLevel, 0xff);
 		}
 		gl.stencilOp(gl.KEEP, gl.KEEP, gl.KEEP);
+		this._maskInvert = invert === true;
 	}
 
 	/**
@@ -2535,6 +2565,7 @@ export default class WebGLRenderer extends Renderer {
 			// flush the batcher
 			this.flush();
 			this.maskLevel = 0;
+			this._maskInvert = false;
 			this.gl.disable(this.gl.STENCIL_TEST);
 		}
 	}