docs(webgl): correct WebGL-availability docs for the WebGL 2 requirement

- `device.isWebGLSupported()` documented as probing WebGL 2, and as the
  same probe renderer construction uses, with the AUTO-falls-back /
  WEBGL-throws consequence spelled out (the old text claimed the renderer
  "will switch to CANVAS mode", true only on the AUTO path)
- `failIfMajorPerformanceCaveat` notes that melonJS defaults it to `true`
  where the WebGL default is `false`, and what that means combined with
  the WebGL 2 requirement
- changelog: record the resulting narrowing of which devices get the
  WebGL renderer

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

Author: obiot

packages/melonjs/CHANGELOG.md

@@ -9,6 +9,7 @@
 - `renderer.type` is always `"WebGL2"` for the WebGL renderer; `renderer.WebGLVersion` is deprecated (always `2`)
 - behavior corrections on ex-WebGL-1 configs: `repeat` wrap now genuinely tiles non-power-of-two textures (was clamp + warning), `"darken"` / `"lighten"` blend modes use true MIN/MAX equations (were silently downgraded to `"normal"`), and `createPattern()` accepts non-power-of-two sources (threw before)
 - TMX GPU tilemap eligibility is now advertised through `renderer.supportsShaderTileLayers` (a backend capability flag) instead of a WebGL-version check
+- the WebGL renderer is now selected only on devices providing a WebGL 2 context **and** passing the `failIfMajorPerformanceCaveat` check (which melonJS leaves enabled by default, unlike the WebGL default of `false`) — a software rasterizer or blocklisted driver therefore gets the Canvas renderer under `video.AUTO`, and throws under `video.WEBGL`. Set `failIfMajorPerformanceCaveat: false` to accept such a context
 - **each `Batcher` now owns an immutable Vertex Array Object** built at init ([#1509](https://github.com/melonjs/melonJS/issues/1509)): vertex attribute layout is frozen once built, batcher switches cost a single `bindVertexArray` (steady-state frames issue zero attribute-specification calls, measured), and `Batcher.unbind()` no longer disables attribute arrays. Custom batchers inheriting `Batcher.init()`/`bind()` need no changes. Custom shaders hosted by a built-in batcher must declare that batcher's attributes first, in layout order (ShaderEffect-generated vertex shaders already comply) — a console warning fires on mismatch. `GLShader.setVertexAttributes` is no longer called by the engine (still public)
 
 ### Performance

packages/melonjs/src/application/settings.ts

@@ -181,9 +181,15 @@ export type ApplicationSettings = {
 	 */
 	gpuTilemap: boolean;
 	/**
-	 * 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.
+	 * If true, treat WebGL as unavailable when the browser warns that a
+	 * context would perform dramatically worse than a native application
+	 * (a software rasterizer, a blocklisted driver). Note this is stricter
+	 * than the WebGL default, which is `false`.
+	 *
+	 * Combined with the WebGL 2 requirement, the effect is: under
+	 * {@link AUTO} such a machine gets the Canvas renderer, and under
+	 * {@link WEBGL} construction throws. Set to `false` to accept a
+	 * software or blocklisted WebGL context instead.
 	 * @default true
 	 */
 	failIfMajorPerformanceCaveat: boolean;

packages/melonjs/src/system/device.ts

@@ -637,10 +637,15 @@ export function getParentBounds(element: string | HTMLElement) {
 }
 
 /**
- * returns true if the device supports WebGL
+ * Returns true if the device supports WebGL 2 — the version the WebGL
+ * renderer requires since 20.0. This probes the same context type that
+ * renderer construction requests, so the two can never disagree.
+ *
+ * When it returns false, `renderer: video.AUTO` falls back to the Canvas
+ * renderer and `renderer: video.WEBGL` throws at construction time.
  * @param [options] - context creation options
- * @param [options.failIfMajorPerformanceCaveat=true] - If true, the renderer will switch to CANVAS mode if the performances of a WebGL context would be dramatically lower than that of a native application making equivalent OpenGL calls.
- * @returns true if WebGL is supported
+ * @param [options.failIfMajorPerformanceCaveat=true] - if true, report WebGL as unsupported when the browser warns that a context would perform dramatically worse than a native application (e.g. a software rasterizer). Set false to accept WebGL on blocklisted drivers or software renderers.
+ * @returns true if WebGL 2 is supported
  * @category Application
  */
 export function isWebGLSupported(options?: {