Address Copilot review: push deopt, cache encapsulation, scissor tracking

- push(): use vertexSize > 5 instead of arguments.length (avoids V8 deopt),
  always write default textureId 0 when vertexSize is 6
- TextureCache.resetUnitAssignments(): encapsulate unit reset logic
- clipRect: use _scissorActive instead of gl.isEnabled() query
- Update vertex buffer tests for new push behavior

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: obiot

packages/melonjs/src/application/settings.ts

@@ -67,16 +67,42 @@ export type ApplicationSettings = {
 	 * @default true
 	 */
 	consoleHeader: boolean;
+
+	/**
+	 * the default blend mode to use ("normal", "multiply", "lighter", "additive", "screen")
+	 * @default "normal"
+	 */
 	blendMode: BlendMode;
 
 	/**
 	 * the physic system to use (default: "builtin", or "none" to disable builtin physic)
 	 * @default "builtin"
 	 */
 	physic: PhysicsType;
+	/**
+	 * if true, the renderer will fail if the browser reports a major performance caveat
+	 * (e.g. software WebGL). Set to false to allow WebGL on machines with
+	 * blocklisted GPU drivers or software renderers.
+	 * @default false
+	 */
 	failIfMajorPerformanceCaveat: boolean;
+
+	/**
+	 * whether to enable sub-pixel rendering (avoid sprite flickering when using transforms)
+	 * @default false
+	 */
 	subPixel: boolean;
+
+	/**
+	 * whether to enable verbose mode (additional console output for debugging)
+	 * @default false
+	 */
 	verbose: boolean;
+
+	/**
+	 * whether to enable legacy mode (compatibility with older melonJS APIs)
+	 * @default false
+	 */
 	legacy: boolean;
 
 	/**
@@ -99,13 +125,18 @@ export type ApplicationSettings = {
 	batcher?: (new (renderer: any) => Batcher) | undefined;
 } & (
 	| {
-			// the DOM parent element (or its string ID) to hold the canvas in the HTML file
+			/**
+			 * the DOM parent element (or its string ID) to hold the canvas in the HTML file
+			 */
 			parent: string | HTMLElement;
 			canvas?: never;
 	  }
 	| {
 			parent?: never;
-			// an existing canvas element to use as the renderer target (by default melonJS will create its own canvas based on given parameters)
+			/**
+			 * an existing canvas element to use as the renderer target
+			 * (by default melonJS will create its own canvas based on given parameters)
+			 */
 			canvas: HTMLCanvasElement;
 	  }
 );

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

@@ -275,10 +275,8 @@ class CanvasRenderTarget {
 	 */
 	invalidate(renderer) {
 		if (typeof renderer.gl !== "undefined") {
-			// flush pending draws that reference the current texture data
-			// before invalidating (required for multi-texture batching)
+			// flush pending draws referencing the current texture data
 			renderer.flush();
-			// make sure the right batcher is active
 			renderer.setBatcher("quad");
 			// invalidate the previous corresponding texture so that it can reuploaded once changed
 			this.glTextureUnit = renderer.cache.getUnit(

packages/melonjs/src/video/texture/cache.js

@@ -61,6 +61,16 @@ class TextureCache {
 		return 0;
 	}
 
+	/**
+	 * Reset all texture unit assignments without clearing the texture cache.
+	 * Used by multi-texture batching when the shader's sampler range is exceeded.
+	 * @ignore
+	 */
+	resetUnitAssignments() {
+		this.units.clear();
+		this.usedUnits.clear();
+	}
+
 	/**
 	 * @ignore
 	 */

packages/melonjs/src/video/webgl/batchers/quad_batcher.js

@@ -200,8 +200,7 @@ export default class QuadBatcher extends MaterialBatcher {
 			// reset if the cache assigned a unit beyond the shader's range
 			if (unit >= this.maxBatchTextures) {
 				this.flush();
-				this.renderer.cache.units.clear();
-				this.renderer.cache.usedUnits.clear();
+				this.renderer.cache.resetUnitAssignments();
 				unit = this.uploadTexture(texture, w, h, reupload, false);
 			}
 		} else {

packages/melonjs/src/video/webgl/buffer/vertex.js

@@ -56,8 +56,8 @@ export default class VertexArrayBuffer {
 		this.bufferF32[offset + 2] = u;
 		this.bufferF32[offset + 3] = v;
 		this.bufferU32[offset + 4] = tint;
-		if (arguments.length > 5) {
-			this.bufferF32[offset + 5] = textureId;
+		if (this.vertexSize > 5) {
+			this.bufferF32[offset + 5] = textureId || 0;
 		}
 
 		this.vertexCount++;

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

@@ -1701,7 +1701,7 @@ export default class WebGLRenderer extends Renderer {
 			height !== canvas.height
 		) {
 			const currentScissor = this.currentScissor;
-			if (gl.isEnabled(gl.SCISSOR_TEST)) {
+			if (this._scissorActive) {
 				// if same as the current scissor box do nothing
 				if (
 					currentScissor[0] === x &&

packages/melonjs/tests/vertexBuffer.spec.js

@@ -33,13 +33,24 @@ describe("VertexArrayBuffer", () => {
 			expect(buf.bufferF32[5]).toBe(3); // textureId
 		});
 
-		it("should not write textureId when not provided", () => {
+		it("should write default textureId 0 when not provided (vertexSize 6)", () => {
 			const buf = new VertexArrayBuffer(6, 4);
 
 			buf.push(10, 20, 0.0, 1.0, 0xffffffff);
 
 			expect(buf.vertexCount).toBe(1);
-			expect(buf.bufferF32[5]).toBe(0); // untouched (default zero)
+			expect(buf.bufferF32[5]).toBe(0); // default 0
+		});
+
+		it("should not write textureId when vertexSize is 5", () => {
+			const buf = new VertexArrayBuffer(5, 4);
+
+			// write a sentinel at offset 5
+			buf.bufferF32[5] = 99;
+			buf.push(10, 20, 0.0, 1.0, 0xffffffff);
+
+			expect(buf.vertexCount).toBe(1);
+			expect(buf.bufferF32[5]).toBe(99); // untouched
 		});
 
 		it("should write multiple vertices sequentially", () => {