NX.js compatibility: run melonJS without a DOM (experimental) - #1854

Description

melonJS can now run where there is no document: on nx.js (JavaScript homebrew for the Nintendo Switch) and, for rendering and loading, in a Web Worker. The game hands the Application the canvas to draw to:

const app = new Application(1280, 720, {
    canvas: screen, // nx.js's display; an OffscreenCanvas in a worker
    renderer: video.AUTO,
    scale: 1,
});
await app.init();

Browsers are unchanged. Every new path is gated on document being missing (an internal hasDOM() in src/system/dom.ts), or on an API being missing. The few lines a page still runs give the same result as before, such as the OffscreenCanvas check, now done with a 1×1 canvas instead of 0×0.

Engine changes (packages/melonjs/src)

• Application: with no DOM, there is no parent element to mount the canvas in, measure or observe. app.parentElement is undefined there and keeps its HTMLElement type, so existing TypeScript games don't break. scale: "auto" draws at the given size.
• Canvas style: a canvas with no style (nx.js's screen) is accepted wherever the engine sets CSS on it: display, CSS size and touch-action.
• WebGL check: with no DOM, it reports whether WebGL 2 exists rather than probing a <canvas> it cannot create. Creating the renderer decides, and video.AUTO still falls back to Canvas.
• Spare canvases: the canvas factory returns an OffscreenCanvas with no DOM, and gives a clear error when there is neither a DOM nor an OffscreenCanvas. The OffscreenCanvas check now uses a 1×1 canvas, because nx.js rejects 0×0.
• Touch: with no DOM, a global TouchEvent counts as touch support, and touches use client coordinates. nx.js touches have no pageX/Y.
• Audio: unlocks at once with no DOM. When Audio has no canPlayType (nx.js), every format is assumed playable and decoding reports the ones that fail.
• Screen orientation: screen.orientation is read inside a try/catch; nx.js's getter throws, which broke import "melonjs".
• Tiled: an XML map where there is no DOMParser fails with an error saying to export it as JSON (.tmj/.tsj). The loader keeps the parser's error as the cause of its "Failed loading resource" error, in both preload() and reload().

Tests

• tests/nxjs-compatibility.spec.js: runs a game in a Web Worker made to look like nx.js, using nx.js's own source as the reference: a style-less screen whose orientation throws, OffscreenCanvas that is 2D-only and rejects 0×0, touches without pageX, a Web Audio stand-in, an Audio without canPlayType, and no XHR, DOMParser or WebGPU. With the Canvas, WebGL and AUTO renderers it checks:
  • startup;
  • loading images and a JSON map, and the drawn pixels: tiles, a tile cut from a larger image, and text;
  • touch;
  • sound;
  • the XML-map error;
  • the DOM helpers with no DOM;
  • the error when there is no OffscreenCanvas.
• tests/nxjs-browser-parity.spec.js: in a real page, checks each capability touched against the formula it was computed with before (touchEvent, pointerEvent, touch, maxTouchPoints, screenOrientation, offscreenCanvas, WebGL support, audio formats). It also checks the DOM helpers, and that an Application still mounts in the page with the same canvas styling, coordinate mapping and XML map parsing.
• Mutation checks: reverting each fix, or removing a browser-side guard, makes its test fail.

Docs

• Skills: a new "Runtimes with no DOM: nx.js, Web Workers" section in melonjs-deployment, with setup, what differs and symptom rows. Notes in melonjs-tilemaps (use JSON maps), melonjs-audio (no gesture needed; nodes nx.js lacks) and melonjs-input, plus the router entry.
• README: a short "Running without a DOM (experimental)" section.
• Changelog: entries under 20.14.0.

Limits

• Experimental: tested against a simulation of nx.js, not yet on Switch hardware. Text over WebGL with no DOM now goes through OffscreenCanvas, which melonJS avoids in browsers (textImage2D does not accept OffscreenCanvas anymore as a pixel source for texture #1180); it renders correctly in the Chromium worker but should be checked on a Switch.
• Things that need nx.js changes:
  • spatial audio, tone()/noise() and the audio effects, whose nodes nx.js doesn't implement;
  • fontface assets, because nx.js's FontFace takes bytes, not a URL. The skill shows how to load the bytes and add the face by hand.
• Web Worker: gets no input events or AudioContext of its own, so those have to come from the page.
• Node.js: import "melonjs" works there, but it can't run a game.

Type of change

• Bug fix
• New feature
• Documentation update
• Performance improvement
• Refactoring (no functional changes)

Checklist

• I have read the Contributing Guide
• My code follows the existing code style (pnpm lint passes): run for the melonjs package (ESLint over src and tests, Biome, tsc), with no new warnings on changed lines; no other package changed
• I have tested my changes locally (pnpm test passes): the full engine suite (452 files, 10,810 tests) passed before the parity spec was added; the parity and nx.js specs (31 tests) pass together
• I have added tests that cover my changes (if applicable)
• The build succeeds (pnpm build): the melonjs package build

Related issues

None.

Generated by Claude Code