device.autoFocus is documented as user-settable but has no setter (ESM binding is read-only)

[obiot]

Summary

device.autoFocus is a let-declared module-level flag (packages/melonjs/src/system/device.ts:290) documented as user-settable:

Specify whether to automatically bring the window to the front
@default true

But ESM read-only namespace bindings mean device.autoFocus = false via import * as device from "melonjs/system/device" (or me.device.autoFocus = false through the package re-export) throws TypeError: Cannot assign to read only property 'autoFocus'. There's no setAutoFocus() setter either. The only consumers (initVisibilityEvents focus-handler at device.ts:359/372, pointerevent.ts:176) read it; nothing writes it; users cannot turn it off.

So users who want focus-on-window-restore disabled — e.g. games rendered inside an iframe or alongside another input-capturing widget where stealing focus is unwanted — have no public way to do it.

Repro

import * as device from "melonjs/system/device";
device.autoFocus = false;
// TypeError: Cannot assign to read only property 'autoFocus' of object '[object Module]'

Or:

import * as me from "melonjs";
me.device.autoFocus = false;  // same TypeError

Proposed fix

Add a setter and document the JSDoc accordingly. Two options:

Option A — function setter (consistent with enableSwipe, requestFullscreen etc. in the same module):

export function setAutoFocus(enable: boolean) {
  autoFocus = enable;
}

Option B — wrap the flag in a small state object so external code can mutate the property:

export const focusOptions = { auto: true };

Then initVisibilityEvents reads focusOptions.auto. Object-property writes survive ESM namespace import.

Option A keeps the existing autoFocus read access working (if (device.autoFocus)) and only adds a new function — preferred for backwards compatibility. Option B is a clean rename but breaks the existing read sites.

Notes

• Surfaced during Modernize isMobile / platform detection — UA sniffing misses iPadOS 13+, includes dead platforms #1467 / feat: modernize platform/device detection + Application fullscreen API (#1467) #1485 (device.js → device.ts conversion). The original device.js form had the same defect — the let declaration was always vestigial because the module never reassigned it.
• Low priority — niche enough that the issue may have never been reported via the broken let form either. Tracking so it doesn't get lost.

[Huaian666]

melonJS has always been a solid choice for lightweight 2D HTML5 games. The fact that it's been maintained for years with consistent API improvements shows real dedication. The device.autoFocus handling discussed here is exactly the kind of developer-experience polish that makes a framework trustworthy for production games.

By the way, if anyone's into HTML - there's an iOS app called Like Code that lets you upload and run HTML directly on your phone. If you use AI to write some HTML and it runs well, you can optionally save it to your collection, even offline. If it's a game, you can even tweak the code to make yourself invincible haha

It's on the App Store, feel free to check it out!