feat: modernize platform/device detection + Application fullscreen API (#1467)

[obiot]

Closes #1467.

Scope grew during review from the original "iPadOS 13+ detection + dead-platform deprecation" into a broader platform/device cleanup. Updated to reflect what actually ships.

What this fixes / changes

1. Modern iPads (iPadOS 13+, since Sept 2019) report as desktop

Safari on iPad ships the desktop Mac UA — no iPad token. The /iPhone|iPad|iPod/i regex missed every iPad sold in the last ~7 years; they all fell through isMobile as desktop. Every internal consumer (keyboard.ts, application.ts, header.ts) was getting the wrong answer for ~30% of mobile traffic.

Fix: layer a feature check on top of the UA regex:

const isIPadOnMacUA =
    navigator?.platform === "MacIntel" && (navigator?.maxTouchPoints ?? 0) > 1;
export const iOS = /iPhone|iPad|iPod/i.test(ua) || isIPadOnMacUA(_nav);

navigator.platform === "MacIntel" is NOT a CPU check — Apple deliberately freezes the legacy string for backwards compat (same trick Windows uses with Win32 on 64-bit). Apple Silicon Macs / iPads (M1, M2, M3, M4) all report MacIntel. The maxTouchPoints > 1 clause is what actually separates iPads from real Macs.

isIPadOnMacUA(nav) is extracted as a @internal-tagged exported function so the spec asserts the SAME predicate the module evaluates at load time (drift-proof). Marked @internal because it's a test-seam, not stable API.

2. Dead-platform regex noise

@deprecated since 19.7.0 on wp / BlackBerry / Kindle / android2. Exports stay functional through 19.x for backwards compat; IDE warnings light up at call sites. Removal scheduled for 20.x.

Also dropped these from isMobile's OR chain — remaining /Mobi/.test(ua) || iOS || android covers ~99.9% of 2026 mobile traffic per MDN.

3. system/device.js → system/device.ts (945 lines)

Mechanical conversion — JSDoc was already exhaustive, so most types just become native TS annotations. Non-standard / legacy browser surfaces (Document.mozFullScreenEnabled, Navigator.standalone, iOS-only DeviceOrientationEvent.requestPermission, etc.) typed via narrow local intersection types. Two small correctness improvements that fell out:

• onDeviceMotion now guards against accelerationIncludingGravity === null
• getElement JSDoc corrected (function never returns null, always falls back to document.body)

4. Application#requestFullscreen / exitFullscreen / isFullscreen — fullscreen finally has app-instance context

device.requestFullscreen() had to fall back to the deprecated getParent() → game.getParentElement() global-game lookup because the static helper had no Application reference. The new methods on Application use this.parentElement directly — canvas + sibling HUD go fullscreen together, no deprecated chain.

device.requestFullscreen / device.exitFullscreen deprecated (since 19.7.0) pointing at the Application methods. device.isFullscreen stays non-deprecated because it's a stateless document-state probe (there's exactly one fullscreen state per document regardless of how many Applications run); Application#isFullscreen is a thin convenience.

Also cleaned up the underlying probe in the deprecated wrappers — replaced prefixed("fullscreenElement", document as unknown as Record<string, unknown>) etc. with an explicit four-variant OR chain (the pattern lib.dom.d.ts itself uses).

5. keyboard.ts — drop the if (!isMobile) gate

Initially marked as a follow-up but pulled into this PR after the iPad fix made the gate observably wrong. The gate assumed "mobile = no physical keyboard" — invalid for iPads (now correctly identified) with Magic Keyboard, Samsung DeX, ChromeOS tablet mode, Bluetooth-keyboard-on-phone. Two empty listener slots cost nothing on touch-only devices; the unbound-key path is a single map lookup that returns undefined.

Also changed the surrounding if (globalThis.addEventListener) to typeof globalThis.addEventListener === "function" per Copilot's defensive-style suggestion.

6. Example migrations

• platformer/createGame.ts, platformer/HUD.ts, platformer-matter/createGame.ts, platformer-matter/HUD.ts migrated from device.{is,request,exit}Fullscreen() to app.* / game.* (canonical post-19.7 API).
• afterBurner/ExampleAfterBurner.tsx — added F→fullscreen shortcut + canvas retuned 1024×768 → 1024×576 (16:9, suits widescreen fullscreen better).
• afterBurner/HUD.ts — refactored to read live app.viewport.width / .height so HUD positions follow the configured Application size (was previously hardcoded to the old 1024×768). Added "Powered by melonJS" credit and tightened the bottom credit strip.

Won't-add: isTouch

Original issue suggested a new isTouch flag. We already have device.touch at system/device.ts — feature-detected via navigator.maxTouchPoints / pointer events. CHANGELOG migration note points there.

Tests

Six new cases in tests/platform.spec.ts covering the documented iPad-detection contract:

• ✅ Apple Silicon iPad reporting as Mac (platform=MacIntel, maxTouchPoints=5) → flagged
• ✅ Actual Mac (platform=MacIntel, maxTouchPoints=0) → not flagged
• ✅ Mac with maxTouchPoints undefined (older Safari) → not flagged
• ✅ Windows touchscreen (platform=Win32, maxTouchPoints=10) → not flagged
• ✅ Missing navigator (Node/SSR) → not flagged
• ✅ maxTouchPoints === 1 (single-point touch edge case) → not flagged (> 1 excludes it)

Existing 20 shape / desktop-defaults assertions kept.

Test plan

• pnpm test:types clean
• pnpm vitest run — 3975 / 13 skipped / 0 failed (was 3969, +6 new)
• pnpm build — lint + types clean
• AfterBurner F→fullscreen verified in dev server (1024×576 canvas, post-build dynamic HUD)

Follow-ups (separate tickets)

Filed out of scope:

• device.autoFocus is documented as user-settable but has no setter (ESM binding is read-only) #1486 — device.autoFocus is let-declared and documented as user-settable, but ESM namespace-import bindings are read-only externally. Needs a proper setter.
• Migrate to navigator.userAgentData where available. Chromium-only today; Safari/Firefox lag. 20.x candidate.

🤖 Generated with Claude Code

[Copilot]

Pull request overview

Updates melonJS platform detection to correctly classify modern iPads (iPadOS 13+) as iOS/mobile, while deprecating and removing dead-platform UA regexes from the isMobile aggregate to reduce noise and overhead.

Changes:

• Detect iPadOS 13+ devices that present a desktop “Mac” UA via navigator.platform === "MacIntel" + maxTouchPoints > 1, and fold this into iOS / isMobile.
• Deprecate legacy platform flags (wp, BlackBerry, Kindle, android2) and remove the dead-platform flags from the isMobile OR chain.
• Add/adjust unit tests for the new isMobile wiring and the iPadOS 13+ detection contract; document the behavior in the changelog.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 7 comments.

File	Description
packages/melonjs/src/system/platform.ts	Adds iPadOS 13+ detection logic, deprecates dead-platform flags, and simplifies isMobile aggregation.
packages/melonjs/tests/platform.spec.ts	Updates isMobile expectation and adds contract tests for the iPadOS 13+ detection heuristic.
packages/melonjs/CHANGELOG.md	Documents the iPadOS 13+ fix and deprecation/removal of dead-platform flags from isMobile.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 5 out of 5 changed files in this pull request and generated 3 comments.

Comments suppressed due to low confidence (4)

packages/melonjs/src/system/device.ts:44

• domRect is now constructed via new DOMRect(...) at module load time. In Node/SSR (or any non-DOM environment), DOMRect may be undefined, causing an immediate ReferenceError just by importing device.ts. Please guard this creation and fall back to a lightweight object when DOMRect isn't available.
  packages/melonjs/src/system/device.ts:290
• autoFocus was changed from an exported let to an exported const. This prevents consumers from disabling the autofocus behavior (me.device.autoFocus = false), which appears to be part of the public API per the JSDoc (@default true) and is used as a runtime flag (e.g. in pointerevent.ts).
  packages/melonjs/src/system/device.ts:246
• The device.isMobile JSDoc list is now out of date: platform.isMobile no longer ORs BlackBerry / Windows Phone / Kindle, so the comment is misleading.
  packages/melonjs/src/system/device.ts:604
• getElement never returns null (it falls back to document.body), but the JSDoc still says it can return null. This mismatch can confuse consumers and generated docs.

[Copilot]

Pull request overview

Copilot reviewed 5 out of 5 changed files in this pull request and generated 2 comments.

Comments suppressed due to low confidence (3)

packages/melonjs/src/system/device.ts:136

• touch and maxTouchPoints dereference globalThis.navigator.maxTouchPoints without guarding that navigator exists. In SSR/non-browser contexts (or environments with partial DOM polyfills), this can throw at module-load time and prevent importing device at all. Guard navigator consistently (similar to platform.ts) so both constants are safe to evaluate.
  packages/melonjs/src/system/device.ts:746
• watchAccelerometer() requests permission via DeviceOrientationEvent.requestPermission, but the permission gate for devicemotion on iOS is DeviceMotionEvent.requestPermission(). Using the orientation constructor here can cause accelerometer setup to fail even though hasAccelerometer is true.
  packages/melonjs/src/system/device.ts:472
• exitFullscreen assumes document.exitFullscreen() always exists and always returns a Promise (because .catch(...) is chained). In older fullscreen implementations you may only have vendor-prefixed exit APIs (or a void return), so this can throw even when hasFullscreenSupport is true.

[Copilot]

Pull request overview

Copilot reviewed 10 out of 10 changed files in this pull request and generated 1 comment.

[Copilot]

Pull request overview

Copilot reviewed 10 out of 10 changed files in this pull request and generated 2 comments.

Comments suppressed due to low confidence (1)

packages/melonjs/src/system/device.ts:308

• The eslint-disable prefer-const comment is misleading: it justifies let by claiming the variable is "reassignable via internal setters even though no setter exists today." There is no internal reassignment site (the only mutation today would be an external device.autoFocus = …, which ESM disallows on a module export binding regardless). If autoFocus is intended to be a public knob, it should be exposed via a setter / configuration object; otherwise this should be export const autoFocus = true; and the eslint-disable removed. As written, the comment encodes a contract (mutability) that the code does not actually provide.

[Copilot]

Pull request overview

Copilot reviewed 11 out of 11 changed files in this pull request and generated 3 comments.

Comments suppressed due to low confidence (1)

packages/melonjs/src/system/device.ts:308

• The eslint-disable rationale "reassignable via internal setters even though no setter exists today" is contradictory — if there is no setter, prefer-const is correct, and the binding can't be reassigned from outside the module anyway (ESM exports are read-only on the consumer side). Either drop the let + eslint-disable and use const, or add the missing setter function. As written, me.device.autoFocus = false from user code throws in strict-mode ESM, so the apparent mutability is misleading API surface.

[Copilot]

Pull request overview

Copilot reviewed 12 out of 12 changed files in this pull request and generated no new comments.