test: correct the harness docs, and stop one flake misreporting its cause

Three documentation claims in the test harness were wrong, and the wrong one
was load-bearing: it produced a diagnosis of the intermittent CI failure that
does not hold.

- `tests/helpers/webgl-context.js` said vitest runs every spec file in one
  page, so WebGL contexts accumulate across files until the browser's cap
  force-loses the oldest and a later `beforeAll` stalls. Measurably false: a
  probe shows a global set in one file is `undefined` in the next, and a
  context opened in one is already lost by the next. Vitest isolates each
  spec FILE. Contexts accumulate only WITHIN a file, across describe blocks.
- `vitest.config.ts` repeated the same claim.
- `src/system/device.ts` carried a JSDoc `@example` calling `me.video.init()`
  — an API that no longer exists — on an already-deprecated function. That
  one is user-facing, since it ships in the published docs.

All three now say what was measured, and the helper carries an explicit note
not to rebuild the starvation theory from it. The helper itself is still
worth using, for a different reason: acquisition through a software
rasterizer is genuinely slow, so creating fewer contexts saves real time.

`application_lifecycle` is the one spec that has failed intermittently here.
It built SIX WebGL applications in a loop — the most context churn in the
suite — and checked handler identity before checking a handler exists, so a
cycle that failed to obtain a renderer reported "reused a previous handler".
That message sent this investigation the wrong way. Three cycles prove the
property just as well, and the existence check now runs first, so a failure
says what actually happened.

The cause of the CI flake remains unknown. The `hookTimeout` note — that
acquisition can take tens of seconds under load — is the better lead.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01QVjYzf76AEU3wJk766JAQi

Author: obiot

packages/melonjs/src/system/device.ts

@@ -313,43 +313,9 @@ export function setAutoFocus(enable: boolean): void {
  * specify a function to execute when the Device is fully loaded and ready
  * @param fn - the function to be executed
  * @example
- * // small game skeleton
- * let game = {
- *    // called by the me.device.onReady function
- *    onload = function () {
- *       // init video
- *       if (!me.video.init('screen', 640, 480, true)) {
- *          alert("Sorry but your browser does not support html 5 canvas.");
- *          return;
- *       }
- *
- *       // initialize the "audio"
- *       me.audio.init("mp3,ogg");
- *
- *       // set callback for resources loaded event
- *       me.loader.onload = this.loaded.bind(this);
- *
- *       // set all resources to be loaded
- *       me.loader.preload(game.assets);
- *
- *       // load everything & display a loading screen
- *       me.state.change(me.state.LOADING);
- *    };
- *
- *    // callback when everything is loaded
- *    loaded = function () {
- *       // define stuff
- *       // ....
- *
- *       // change to the menu screen
- *       me.state.change(me.state.PLAY);
- *    }
- * }; // game
- *
- * // "bootstrap"
- * me.device.onReady(function () {
- *    game.onload();
- * });
+ * // the modern equivalent is simply to await the Application
+ * const app = new Application(640, 480, { parent: "screen" });
+ * await app.init();
  * @deprecated since 18.3.0 — no longer needed when using {@link Application} as entry point.
  * @category Application
  */

packages/melonjs/tests/application_lifecycle.spec.js

@@ -128,16 +128,27 @@ describe("Application lifecycle: renderer event handlers are unregisterable", ()
 		// Guards the drift case: were the handler shared on the prototype,
 		// cycle N would unregister cycle 0's closure and leave every later
 		// renderer on the bus.
+		// Three cycles prove the property (a prototype-shared handler collides
+		// on the second); six only tripled the WebGL contexts this one test
+		// builds and tore down, which is the most context churn in the suite.
+		const CYCLES = 3;
 		const seen = new Set();
-		for (let i = 0; i < 6; i++) {
+		for (let i = 0; i < CYCLES; i++) {
 			const app = await mk(video.WEBGL);
 			const handler = app.renderer.onGameReset;
+			// Check this FIRST. A cycle that failed to obtain a real WebGL
+			// renderer yields no handler, and two `undefined`s land in the set
+			// as a duplicate — reporting "reused a previous handler" for what is
+			// actually a context-acquisition failure. This test has failed
+			// intermittently in CI and that message sent the investigation the
+			// wrong way; it should say what really happened.
+			expect(typeof handler, `cycle ${i} produced no handler`).toBe("function");
 			expect(seen.has(handler), `cycle ${i} reused a previous handler`).toBe(
 				false,
 			);
 			seen.add(handler);
 			app.destroy();
 		}
-		expect(seen.size).toBe(6);
+		expect(seen.size).toBe(CYCLES);
 	});
 });

packages/melonjs/tests/helpers/webgl-context.js

@@ -6,20 +6,29 @@ import WebGLRenderer from "../../src/video/webgl/webgl_renderer.js";
  *
  * ## Why this exists
  *
- * Vitest browser mode runs every spec file in one page, and constructing an
- * `Application` and awaiting `init()` builds a fresh canvas and GL context
- * each time. With a spec
- * file per feature that adds up to dozens of live contexts in a single
- * session — and browsers cap how many they will keep, force-losing the oldest
- * once past the limit. Past that point, creating another context stalls.
- *
- * The failure that produces is badly misleading: some *unrelated* spec's
- * `beforeAll` times out, the suite blames whichever file happened to be late
- * in the run, and adding or reordering files moves the casualty around. It
- * looks like flakiness in the victim, but it is a resource limit set by
- * everything before it.
- *
- * So: create one context, keep it for the session, and let specs borrow it.
+ * Constructing an `Application` and awaiting `init()` builds a fresh canvas
+ * and GL context each time, and on a CI container with no GPU that runs
+ * through a software rasterizer — slow enough that `vitest.config.ts` raises
+ * `hookTimeout` to 90s for it. Creating FEWER contexts is therefore worth
+ * real time, which is what this helper is for.
+ *
+ * ## What this is NOT for
+ *
+ * This used to claim that vitest runs every spec file in one page, so contexts
+ * accumulated across files until the browser's cap force-lost the oldest and a
+ * later `beforeAll` stalled. That is measurably false: vitest isolates each
+ * spec FILE. A probe confirmed it — a global set in one file is `undefined` in
+ * the next, and a context opened in one is already lost by the next. Contexts
+ * accumulate only WITHIN a file, across its describe blocks.
+ *
+ * The belief was load-bearing for a while: an intermittent CI failure (an
+ * unrelated spec's `beforeAll` timing out in `getWebGLRenderer`) was blamed on
+ * cross-file starvation. It is not that. The cause is still unknown, and the
+ * `hookTimeout` note above — that acquisition is genuinely slow under load —
+ * is the better lead. Do not rebuild the starvation theory from this file.
+ *
+ * So: create one context per file, keep it for that file, and let its specs
+ * borrow it.
  *
  * ## Using it
  *

packages/melonjs/vitest.config.ts

@@ -25,18 +25,25 @@ export default defineConfig(() =>
 		// Anchor to this package. `pnpm test` invokes this config from the repo
 		// root, where an unanchored `include` globs every workspace package —
 		// so the adapters' and debug-plugin's specs were pulled into this run
-		// *as well as* being run by their own `pnpm -F ... test` jobs. Besides
-		// the duplicate work, each extra spec file that calls `video.init`
-		// creates another WebGL context in the one shared browser session, and
-		// past the browser's context cap a later `beforeAll` stalls.
+		// *as well as* being run by their own `pnpm -F ... test` jobs, doubling
+		// the work.
+		//
+		// This comment used to claim the specs also shared one browser session,
+		// so contexts accumulated across files until the browser's cap stalled a
+		// later `beforeAll`. That is NOT true here: vitest isolates each spec
+		// file, verified by a probe — a global set in one file is undefined in
+		// the next, and a context opened in one is dead by the next. Contexts do
+		// accumulate WITHIN a file across its describe blocks, which is worth
+		// releasing, but it is not a cross-file effect.
 		root: __dirname,
 		test: {
 			include: ["tests/**/*.{test,spec}.[jt]s?(x)"],
 			// Several specs create a WebGL context in `beforeAll`. On a CI
 			// container with no GPU that runs through a software rasterizer and
 			// can genuinely take tens of seconds under load, so the default hook
 			// timeout fails correct suites. Raised for headroom — this is a slow
-			// hook, not a hanging one.
+			// hook, not a hanging one. (`video.init` no longer exists; a context
+			// comes from `new Application(...)` + `await app.init()`.)
 			hookTimeout: 90000,
 			browser: {
 				enabled: true,