@gjsify/gamepad 0.27.1 → 0.29.0

package/README.md

@@ -1,6 +1,6 @@
 # @gjsify/gamepad
 
-The W3C Gamepad API for GJS, backed by libmanette 0.2. Provides `navigator.getGamepads()` polling, `Gamepad`, `GamepadButton`, `gamepadconnected`/`gamepaddisconnected` events, and dual-rumble haptics via `GamepadHapticActuator`. The Manette monitor is lazily initialised and degrades gracefully when libmanette is unavailable.
+The W3C Gamepad API for GJS, backed by libmanette 0.2. Provides `navigator.getGamepads()` polling, `Gamepad`, `GamepadButton`, `gamepadconnected`/`gamepaddisconnected` events, and dual-rumble haptics via `GamepadHapticActuator`. The Manette monitor is lazily initialised on the first `getGamepads()` call.
 
 Part of the [gjsify](https://github.com/gjsify/gjsify) project — Node.js and Web APIs for GJS (GNOME JavaScript).
 
@@ -39,6 +39,31 @@ for (const pad of gamepads) {
 }
 ```
 
+## Platform support — hosts without libmanette
+
+The backend is libmanette, and libmanette is Linux-only: it links `libevdev` unconditionally (`dependency('libevdev')` in its `meson.build`, with no `required:` argument and no `host_machine` branch anywhere in the tree), and libevdev is packaged for Linux and FreeBSD only — homebrew-core's formula carries `depends_on :linux`, MacPorts has no port, nixpkgs declares `platforms = linux ++ freebsd`. **So on macOS and Windows there is no gamepad backend at all, and there cannot be one until a native backend is written.** That is a platform gap, not a bug in this package.
+
+On such a host `navigator.getGamepads()` returns the **empty list** *because there is no backend* — indistinguishable, from the return value alone, from a Linux host with nothing plugged in. That is deliberate, and it is what the spec asks for: `Navigator.[[gamepads]]` "is initially the empty list" and grows only when an index is selected for a connected device, so `getGamepads()`'s steps only ever return a list (their one `throw` is a `SecurityError` for the `"gamepad"` permission policy), and a browser on a machine with no gamepad driver returns exactly the same empty answer — WebKit compiles an `EmptyGamepadProvider` for precisely that case. Making the call throw would break every page that polls `navigator.getGamepads().length`.
+
+Ask the capability export instead of guessing from an empty list:
+
+```typescript
+import { hasGamepadBackend } from '@gjsify/gamepad';
+
+if (!(await hasGamepadBackend())) {
+    // No gamepad subsystem on this host — hide the controller UI rather than
+    // showing "no controller connected" forever.
+}
+```
+
+`hasGamepadBackend()` needs no monitor and no connected device, and it is **quiet**: asking the question prints nothing, so the recommended usage above costs no stderr line on a macOS or Windows start. The one-time explanation comes from the *use* instead — the first `getGamepads()` that actually wanted a monitor:
+
+* **no backend** (no Manette typelib; or `@gjsify/node-gi` not installed on the node target) → one `console.warn` naming what to install.
+* **a fault** (a shared library that will not `dlopen`, a version or ABI skew) → one `console.error` carrying the original error. A broken setup is a fault, not a platform gap, and the two must not look alike.
+* **the monitor fails to start** after the backend loaded (no udev or `/dev/input` in a sandbox; flatpak: `--device=input`) → its own `console.error`, because that is a third, distinct failure.
+
+On the browser and NativeScript targets the runtime's own Gamepad API is the implementation (`gjsify.runtimes` declares both `native`): the package root routes to `globals.mjs`, whose `hasGamepadBackend()` reports that native surface, and `@gjsify/gamepad/register` leaves an existing `navigator.getGamepads` untouched rather than replacing it.
+
 ## License
 
 MIT

package/globals.mjs

@@ -5,12 +5,37 @@
  * the libmanette GJS backend stays GJS-only.
  *
  * The dynamic resolver in `@gjsify/resolve-npm/runtime-aliases.mjs` routes
- * `@gjsify/gamepad` here when `package.json#gjsify.runtimes.browser === "native"`.
+ * `@gjsify/gamepad` here when `package.json#gjsify.runtimes.browser === "native"`
+ * — and the same rule routes it here for `nativescript`. That makes this file the
+ * NON-GJS entry for the package root, so every root export a consumer may import
+ * has to be answerable from here or the routed bundle dies with `MISSING_EXPORT`.
  *
- * NOT used on Node — Node has no Gamepad global.
+ * NOT used on Node — Node has no Gamepad global (`gjsify.runtimes.node` is
+ * `"partial"`, which is not rewritten: the real GJS body runs through
+ * `@gjsify/node-gi`).
  */
 
 export const Gamepad = globalThis.Gamepad;
 export const GamepadButton = globalThis.GamepadButton;
 export const GamepadEvent = globalThis.GamepadEvent;
 export const GamepadHapticActuator = globalThis.GamepadHapticActuator;
+
+/**
+ * Whether this host has a gamepad backend at all — the same question the GJS
+ * entry answers about `gi://Manette`, answered here about the runtime's own
+ * Gamepad API, which on these targets IS the implementation.
+ *
+ * Kept REAL rather than stubbed or omitted: the answer is platform-independent in
+ * the sense AGENTS.md means (§ Slot routing — "Exports whose answer IS
+ * platform-independent stay REAL", as `hasOcspSupport()` → `false` does on
+ * `@gjsify/tls`'s browser entry). Omitting it broke the README's own recommended
+ * usage at BUILD time on `--app browser` and `--app nativescript`; a thrower
+ * would break it at run time. `true` in a browser; `false` on NativeScript, which
+ * ships no Gamepad API — both are the honest answer for that host.
+ *
+ * `async` to match the root entry's `Promise<boolean>` signature, where the
+ * answer needs a dynamic `import('gi://Manette')`; here it is already known.
+ */
+export async function hasGamepadBackend() {
+    return typeof globalThis.navigator?.getGamepads === 'function';
+}

package/lib/esm/backend.js

@@ -0,0 +1 @@
+import"./_virtual/_rolldown/runtime.js";const e=`Manette`;function typelibAbsentNeedle(e){return`Typelib file for namespace '${e}'`}const t=`@gjsify/node-gi`;function noTypelibText(e){return`[@gjsify/gamepad] No gamepad backend on this host — the ${e}-0.2 typelib is absent, so getGamepads() reports no controllers no matter what is plugged in. Install libmanette + its typelib (Fedora: libmanette; Debian/Ubuntu: gir1.2-manette-0.2); macOS and Windows have no libmanette at all. Gate on hasGamepadBackend().`}function noBridgeText(){return`[@gjsify/gamepad] No gamepad backend in this process — ${t} is not installed, and it is how a --app node bundle reaches gi://${e}. getGamepads() reports no controllers until it is added (npm install ${t}, plus libmanette + its typelib). Gate on hasGamepadBackend().`}const n=`[@gjsify/gamepad] The gi://${e} gamepad backend failed to load — a fault on this host, NOT a platform without libmanette. getGamepads() reports no controllers until it is fixed.`;let r=null,i=!1;function isEmptiedGiModule(e){return typeof e==`object`&&!!e&&Object.getPrototypeOf(e)===Object.prototype&&Object.getOwnPropertyNames(e).length===0}function isMissingNodeGiBridge(e,n){if(!n.includes(t))return!1;let r=e?.code;return r===`MODULE_NOT_FOUND`||r===`ERR_MODULE_NOT_FOUND`||n.includes(`Cannot find module`)}function _diagnoseGiLoadError(t,n=e){let r=t instanceof Error?t.message:String(t);return r.includes(typelibAbsentNeedle(n))?{status:`absent`,diagnostic:noTypelibText(n)}:isMissingNodeGiBridge(t,r)?{status:`absent`,diagnostic:noBridgeText()}:{status:`failed`,diagnostic:null}}async function probeGamepadBackend(t){let n=t.importer??(()=>import(`gi://Manette`)),r;try{if(r=(await n()).default,typeof r?.Monitor!=`function`)return isEmptiedGiModule(r)?{status:`absent`,module:null,error:null,diagnostic:null}:{status:`failed`,module:null,error:Error(`gi://${e} resolved without a Monitor class — unexpected ${e} ABI`),diagnostic:null}}catch(e){let{status:t,diagnostic:n}=_diagnoseGiLoadError(e);return{status:t,module:null,error:e,diagnostic:n}}return{status:`manette`,module:r,error:null,diagnostic:null}}function loadGamepadBackend(e={}){if(r!==null){if(e.importer)throw Error(`loadGamepadBackend({ importer }) called after the probe already ran — the probe is cached per process, so the importer would be ignored. Call _resetGamepadBackendCache() first (tests only).`);return r}return r=probeGamepadBackend(e),r}function reportGamepadBackendOnce(e){if(!i){if(e.status===`failed`){i=!0,console.error(n,e.error);return}e.diagnostic!==null&&(i=!0,console.warn(e.diagnostic))}}function reportGamepadMonitorFault(t){console.error(`[@gjsify/gamepad] The gi://${e} backend loaded but the gamepad monitor could not be started — a fault AFTER the backend was available, not a missing backend. Manette.Monitor needs udev and /dev/input access, which a sandbox can withhold (flatpak: --device=input). getGamepads() reports no controllers until it is fixed.`,t)}async function hasGamepadBackend(){return(await loadGamepadBackend()).status===`manette`}function _resetGamepadBackendCache(){r=null,i=!1}export{_diagnoseGiLoadError,_resetGamepadBackendCache,hasGamepadBackend,loadGamepadBackend,reportGamepadBackendOnce,reportGamepadMonitorFault};

package/lib/esm/gamepad-manager.js

@@ -1 +1 @@
-import"./_virtual/_rolldown/runtime.js";import{MANETTE_TO_W3C_AXIS as e,ManetteAxis as t,TRIGGER_PRESS_THRESHOLD as n}from"./axis-mapping.js";import{MANETTE_TO_W3C_BUTTON as r,W3CButton as i}from"./button-mapping.js";import{GamepadButton as a}from"./gamepad-button.js";import{GamepadEvent as o}from"./gamepad-event.js";import{Gamepad as s}from"./gamepad.js";import{ManetteHapticActuator as c}from"./haptic-actuator.js";var GamepadManager=class{_monitor=null;_slots=Array.from({length:4}).fill(null);_monitorSignalIds=[];_ManetteModule=null;_initPromise=null;_initialized=!1;_ensureInit(){this._initialized||(this._initPromise||=this._init())}async _init(){try{let e=await import(`gi://Manette`);this._ManetteModule=e.default}catch{this._initialized=!0;return}let e=new this._ManetteModule.Monitor;this._monitor=e;let t=e.iterate(),n=t.next();for(;n[0];){let e=n[1];e&&this._onDeviceConnected(e),n=t.next()}this._monitorSignalIds.push(e.connect(`device-connected`,(e,t)=>{this._onDeviceConnected(t)}),e.connect(`device-disconnected`,(e,t)=>{this._onDeviceDisconnected(t)})),this._initialized=!0}_onDeviceConnected(e){let t=-1;for(let e=0;e<4;e++)if(this._slots[e]===null){t=e;break}if(t===-1)return;let n={device:e,index:t,connected:!0,timestamp:performance.now(),buttons:new Float64Array(17),buttonsPressed:Array.from({length:17}).fill(!1),axes:new Float64Array(4),hapticActuator:new c(e),signalIds:[]};n.signalIds.push(e.connect(`button-press-event`,(e,t)=>{this._onButtonPress(n,t)}),e.connect(`button-release-event`,(e,t)=>{this._onButtonRelease(n,t)}),e.connect(`absolute-axis-event`,(e,t)=>{this._onAxisChange(n,t)}),e.connect(`hat-axis-event`,(e,t)=>{this._onHatChange(n,t)}),e.connect(`disconnected`,()=>{this._onDeviceDisconnected(e)})),this._slots[t]=n;let r=this._createSnapshot(n);r&&globalThis.dispatchEvent?.(new o(`gamepadconnected`,{gamepad:r}))}_onDeviceDisconnected(e){let t=this._findStateByDevice(e);if(!t)return;for(let n of t.signalIds)e.disconnect(n);t.connected=!1;let n=this._createSnapshot(t);this._slots[t.index]=null,n&&globalThis.dispatchEvent?.(new o(`gamepaddisconnected`,{gamepad:n}))}_onButtonPress(e,t){let[n,i]=t.get_button();if(!n)return;let a=r.get(i);a!==void 0&&(e.buttons[a]=1,e.buttonsPressed[a]=!0,e.timestamp=performance.now())}_onButtonRelease(e,t){let[n,i]=t.get_button();if(!n)return;let a=r.get(i);a!==void 0&&(e.buttons[a]=0,e.buttonsPressed[a]=!1,e.timestamp=performance.now())}_onAxisChange(r,a){let[o,s,c]=a.get_absolute();if(!o)return;let l=e.get(s);if(l!==void 0)r.axes[l]=c;else if(s===t.LEFT_TRIGGER){let e=(c+1)/2;r.buttons[i.LEFT_TRIGGER]=e,r.buttonsPressed[i.LEFT_TRIGGER]=e>n}else if(s===t.RIGHT_TRIGGER){let e=(c+1)/2;r.buttons[i.RIGHT_TRIGGER]=e,r.buttonsPressed[i.RIGHT_TRIGGER]=e>n}r.timestamp=performance.now()}_onHatChange(e,t){let[n,r,a]=t.get_hat();n&&(r===0?(e.buttonsPressed[i.DPAD_LEFT]=a<0,e.buttons[i.DPAD_LEFT]=+(a<0),e.buttonsPressed[i.DPAD_RIGHT]=a>0,e.buttons[i.DPAD_RIGHT]=+(a>0)):r===1&&(e.buttonsPressed[i.DPAD_UP]=a<0,e.buttons[i.DPAD_UP]=+(a<0),e.buttonsPressed[i.DPAD_DOWN]=a>0,e.buttons[i.DPAD_DOWN]=+(a>0)),e.timestamp=performance.now())}_findStateByDevice(e){for(let t of this._slots)if(t&&t.device===e)return t;return null}_createSnapshot(e){let t=[];for(let n=0;n<17;n++)t.push(new a(e.buttonsPressed[n],e.buttonsPressed[n]||e.buttons[n]>0,e.buttons[n]));return new s({id:e.device.get_name()??`Gamepad (${e.device.get_guid()})`,index:e.index,connected:e.connected,timestamp:e.timestamp,mapping:`standard`,axes:Array.from(e.axes),buttons:t,vibrationActuator:e.hapticActuator})}getGamepads(){this._ensureInit();let e=[];for(let t=0;t<4;t++){let n=this._slots[t];e.push(n?this._createSnapshot(n):null)}return e}dispose(){for(let e of this._slots)if(e)for(let t of e.signalIds)e.device.disconnect(t);if(this._slots.fill(null),this._monitor){for(let e of this._monitorSignalIds)this._monitor.disconnect(e);this._monitorSignalIds=[],this._monitor=null}this._initialized=!1,this._initPromise=null}};export{GamepadManager};
+import"./_virtual/_rolldown/runtime.js";import{MANETTE_TO_W3C_AXIS as e,ManetteAxis as t,TRIGGER_PRESS_THRESHOLD as n}from"./axis-mapping.js";import{loadGamepadBackend as r,reportGamepadBackendOnce as i,reportGamepadMonitorFault as a}from"./backend.js";import{MANETTE_TO_W3C_BUTTON as o,W3CButton as s}from"./button-mapping.js";import{GamepadButton as c}from"./gamepad-button.js";import{GamepadEvent as l}from"./gamepad-event.js";import{Gamepad as u}from"./gamepad.js";import{ManetteHapticActuator as d}from"./haptic-actuator.js";var GamepadManager=class{_monitor=null;_slots=[];_monitorSignalIds=[];_ManetteModule=null;_initPromise=null;_initialized=!1;_ensureInit(){this._initialized||(this._initPromise||=this._init().catch(e=>{a(e),this._initialized=!0}))}async _init(){let e=await r();if(i(e),e.module===null){this._initialized=!0;return}this._ManetteModule=e.module;let t=new this._ManetteModule.Monitor;this._monitor=t;let n=t.iterate(),a=n.next();for(;a[0];){let e=a[1];e&&this._onDeviceConnected(e),a=n.next()}this._monitorSignalIds.push(t.connect(`device-connected`,(e,t)=>{this._onDeviceConnected(t)}),t.connect(`device-disconnected`,(e,t)=>{this._onDeviceDisconnected(t)})),this._initialized=!0}_onDeviceConnected(e){let t=this._slots.indexOf(null);t===-1&&(t=this._slots.length,this._slots.push(null));let n={device:e,index:t,connected:!0,timestamp:performance.now(),buttons:new Float64Array(17),buttonsPressed:Array.from({length:17}).fill(!1),axes:new Float64Array(4),hapticActuator:new d(e),signalIds:[]};n.signalIds.push(e.connect(`button-press-event`,(e,t)=>{this._onButtonPress(n,t)}),e.connect(`button-release-event`,(e,t)=>{this._onButtonRelease(n,t)}),e.connect(`absolute-axis-event`,(e,t)=>{this._onAxisChange(n,t)}),e.connect(`hat-axis-event`,(e,t)=>{this._onHatChange(n,t)}),e.connect(`disconnected`,()=>{this._onDeviceDisconnected(e)})),this._slots[t]=n;let r=this._createSnapshot(n);r&&globalThis.dispatchEvent?.(new l(`gamepadconnected`,{gamepad:r}))}_onDeviceDisconnected(e){let t=this._findStateByDevice(e);if(!t)return;for(let n of t.signalIds)e.disconnect(n);t.connected=!1;let n=this._createSnapshot(t);this._slots[t.index]=null,n&&globalThis.dispatchEvent?.(new l(`gamepaddisconnected`,{gamepad:n}))}_onButtonPress(e,t){let[n,r]=t.get_button();if(!n)return;let i=o.get(r);i!==void 0&&(e.buttons[i]=1,e.buttonsPressed[i]=!0,e.timestamp=performance.now())}_onButtonRelease(e,t){let[n,r]=t.get_button();if(!n)return;let i=o.get(r);i!==void 0&&(e.buttons[i]=0,e.buttonsPressed[i]=!1,e.timestamp=performance.now())}_onAxisChange(r,i){let[a,o,c]=i.get_absolute();if(!a)return;let l=e.get(o);if(l!==void 0)r.axes[l]=c;else if(o===t.LEFT_TRIGGER){let e=(c+1)/2;r.buttons[s.LEFT_TRIGGER]=e,r.buttonsPressed[s.LEFT_TRIGGER]=e>n}else if(o===t.RIGHT_TRIGGER){let e=(c+1)/2;r.buttons[s.RIGHT_TRIGGER]=e,r.buttonsPressed[s.RIGHT_TRIGGER]=e>n}r.timestamp=performance.now()}_onHatChange(e,t){let[n,r,i]=t.get_hat();n&&(r===0?(e.buttonsPressed[s.DPAD_LEFT]=i<0,e.buttons[s.DPAD_LEFT]=+(i<0),e.buttonsPressed[s.DPAD_RIGHT]=i>0,e.buttons[s.DPAD_RIGHT]=+(i>0)):r===1&&(e.buttonsPressed[s.DPAD_UP]=i<0,e.buttons[s.DPAD_UP]=+(i<0),e.buttonsPressed[s.DPAD_DOWN]=i>0,e.buttons[s.DPAD_DOWN]=+(i>0)),e.timestamp=performance.now())}_findStateByDevice(e){for(let t of this._slots)if(t&&t.device===e)return t;return null}_createSnapshot(e){let t=[];for(let n=0;n<17;n++)t.push(new c(e.buttonsPressed[n],e.buttonsPressed[n]||e.buttons[n]>0,e.buttons[n]));return new u({id:e.device.get_name()??`Gamepad (${e.device.get_guid()})`,index:e.index,connected:e.connected,timestamp:e.timestamp,mapping:`standard`,axes:Array.from(e.axes),buttons:t,vibrationActuator:e.hapticActuator})}getGamepads(){return this._ensureInit(),this._slots.map(e=>e?this._createSnapshot(e):null)}dispose(){for(let e of this._slots)if(e)for(let t of e.signalIds)e.device.disconnect(t);if(this._slots.length=0,this._monitor){for(let e of this._monitorSignalIds)this._monitor.disconnect(e);this._monitorSignalIds=[],this._monitor=null}this._initialized=!1,this._initPromise=null}};export{GamepadManager};

package/lib/esm/index.js

@@ -1 +1 @@
-import{MANETTE_TO_W3C_AXIS as e,ManetteAxis as t,TRIGGER_PRESS_THRESHOLD as n,W3CAxis as r,W3C_AXIS_COUNT as i}from"./axis-mapping.js";import{LinuxButton as a,MANETTE_TO_W3C_BUTTON as o,W3CButton as s,W3C_BUTTON_COUNT as c}from"./button-mapping.js";import{GamepadButton as l}from"./gamepad-button.js";import{GamepadEvent as u}from"./gamepad-event.js";import{Gamepad as d}from"./gamepad.js";import{ManetteHapticActuator as f}from"./haptic-actuator.js";import{GamepadManager as p}from"./gamepad-manager.js";export{d as Gamepad,l as GamepadButton,u as GamepadEvent,p as GamepadManager,e as MANETTE_TO_W3C_AXIS,o as MANETTE_TO_W3C_BUTTON,t as ManetteAxis,a as ManetteButton,f as ManetteHapticActuator,n as TRIGGER_PRESS_THRESHOLD,r as W3CAxis,s as W3CButton,i as W3C_AXIS_COUNT,c as W3C_BUTTON_COUNT};
+import{MANETTE_TO_W3C_AXIS as e,ManetteAxis as t,TRIGGER_PRESS_THRESHOLD as n,W3CAxis as r,W3C_AXIS_COUNT as i}from"./axis-mapping.js";import{hasGamepadBackend as a}from"./backend.js";import{LinuxButton as o,MANETTE_TO_W3C_BUTTON as s,W3CButton as c,W3C_BUTTON_COUNT as l}from"./button-mapping.js";import{GamepadButton as u}from"./gamepad-button.js";import{GamepadEvent as d}from"./gamepad-event.js";import{Gamepad as f}from"./gamepad.js";import{ManetteHapticActuator as p}from"./haptic-actuator.js";import{GamepadManager as m}from"./gamepad-manager.js";export{f as Gamepad,u as GamepadButton,d as GamepadEvent,m as GamepadManager,e as MANETTE_TO_W3C_AXIS,s as MANETTE_TO_W3C_BUTTON,t as ManetteAxis,o as ManetteButton,p as ManetteHapticActuator,n as TRIGGER_PRESS_THRESHOLD,r as W3CAxis,c as W3CButton,i as W3C_AXIS_COUNT,l as W3C_BUTTON_COUNT,a as hasGamepadBackend};

package/lib/esm/register.js

@@ -1 +1 @@
-import"./_virtual/_rolldown/runtime.js";import{GamepadEvent as e}from"./gamepad-event.js";import{GamepadManager as t}from"./gamepad-manager.js";const n=new t,r=globalThis;r.navigator===void 0&&(r.navigator={}),r.navigator.getGamepads=()=>n.getGamepads(),r.GamepadEvent===void 0&&(r.GamepadEvent=e);
+import{GamepadEvent as e}from"./gamepad-event.js";import{GamepadManager as t}from"./gamepad-manager.js";const n=globalThis;if(n.navigator===void 0&&(n.navigator={}),typeof n.navigator.getGamepads!=`function`){let e=new t;n.navigator.getGamepads=()=>e.getGamepads()}n.GamepadEvent===void 0&&(n.GamepadEvent=e);

package/lib/types/backend.d.ts

@@ -0,0 +1,108 @@
+import type Manette from '@girs/manette-0.2';
+/**
+ * What this host has.
+ *
+ * - `manette` — the Manette-0.2 typelib loaded and exposes `Monitor`.
+ * - `absent`  — no backend reachable from here. Expected on a host without
+ *   libmanette, on a `--app node` process without `@gjsify/node-gi`, and on the
+ *   two targets where `gi://` is stubbed by design.
+ * - `failed`  — a backend should have been reachable and was not. A fault.
+ */
+export type GamepadBackendStatus = 'manette' | 'absent' | 'failed';
+/** The resolved backend probe. `module` is non-null iff `status === 'manette'`. */
+export interface GamepadBackend {
+    status: GamepadBackendStatus;
+    module: typeof Manette | null;
+    /** The original load error for `absent`/`failed`; `null` otherwise. */
+    error: unknown;
+    /**
+     * The one-time line the USE site emits for this outcome, or `null` when
+     * there is nothing to say. Carried rather than printed so the capability
+     * query stays silent — see the module header.
+     *
+     * `status: 'absent'` with a `null` diagnostic is the by-design `gi://` stub
+     * (see {@link isEmptiedGiModule}); `status: 'failed'` always prints, with
+     * the original error, and needs no text here.
+     */
+    diagnostic: string | null;
+}
+export interface LoadGamepadBackendOptions {
+    /**
+     * Override the `gi://Manette` import.
+     *
+     * Only for tests — it is the single seam that lets a suite exercise the
+     * absent and failed paths on a host where libmanette IS installed, which is
+     * every CI runner this package is tested on. Same role as
+     * `fillRandomBytes({ webcrypto })` in `@gjsify/webcrypto/random`.
+     */
+    importer?: () => Promise<{
+        default: typeof Manette;
+    }>;
+}
+/** Absent-vs-fault plus the text the use site should print (`null` = silence). */
+interface GiLoadDiagnosis {
+    status: 'absent' | 'failed';
+    diagnostic: string | null;
+}
+/**
+ * Classify a `gi://` load failure and pick the text for it.
+ *
+ * Exported (underscored) for `backend.spec.ts`, which pins the absent wording
+ * against the LIVE loader — that is why the namespace is a parameter and not
+ * hardcoded: the test asks for a namespace that cannot exist and classifies the
+ * error the running GJS/girepository actually produced for it.
+ */
+export declare function _diagnoseGiLoadError(error: unknown, namespace?: string): GiLoadDiagnosis;
+/**
+ * Resolve (once) which gamepad backend this host has. Emits NOTHING — see the
+ * module header on why the diagnostic belongs to the use site.
+ *
+ * The probe runs at most once per process. Passing `importer` after it has run
+ * is a test-setup bug and THROWS rather than being silently ignored: the old
+ * `cached ??= probe(options)` let a suite that forgot `_resetGamepadBackendCache()`
+ * assert against the PREVIOUS test's injected module and pass.
+ */
+export declare function loadGamepadBackend(options?: LoadGamepadBackendOptions): Promise<GamepadBackend>;
+/**
+ * Emit this backend's one-time diagnostic — called by the USE site
+ * (`GamepadManager._init()`), never by the capability query.
+ *
+ * `absent` warns (a platform gap, expected, but never silent) and `failed`
+ * errors with the original attached: two levels for two situations, which is
+ * what makes the split visible rather than merely present. Deliberately not a
+ * rethrow — `GamepadManager` starts its init without awaiting it, so a rethrow
+ * becomes an unhandled rejection: unattributable on GJS and, with Node's default
+ * `--unhandled-rejections=throw`, a process kill. A half-installed typelib must
+ * not be able to take down the host application.
+ */
+export declare function reportGamepadBackendOnce(backend: GamepadBackend): void;
+/**
+ * The backend loaded and then the monitor did not come up.
+ *
+ * A DIFFERENT failure from a failed load, and it says so: everything after the
+ * probe — `new Manette.Monitor()`, the device walk, `connect()` — needs udev and
+ * `/dev/input`, which a sandbox can withhold from a process whose typelib and
+ * shared library are both perfectly fine. Routing it through the load-failure
+ * text would re-create, one layer up, exactly the conflation this module removed.
+ */
+export declare function reportGamepadMonitorFault(error: unknown): void;
+/**
+ * Whether this host has a gamepad backend at all.
+ *
+ * `false` means `navigator.getGamepads()` can never report a controller here, no
+ * matter what is connected — which the W3C surface itself cannot express (it
+ * returns the same list either way, and that is correct: see
+ * `GamepadManager.getGamepads()`). Answerable without constructing a monitor or
+ * plugging anything in, and QUIET: the diagnostic fires from the use, not from
+ * this question.
+ *
+ * It is `false` on every host without libmanette, which today means macOS and
+ * Windows: libmanette links libevdev unconditionally, and libevdev is
+ * Linux/FreeBSD-only. Like `hasNativeSab()` and `hasOcspSupport()` this reports
+ * that the BRIDGE is usable, not that every later call will succeed — a monitor
+ * can still fail to start (see {@link reportGamepadMonitorFault}).
+ */
+export declare function hasGamepadBackend(): Promise<boolean>;
+/** Reset the cached probe and its one-time diagnostic — tests only. */
+export declare function _resetGamepadBackendCache(): void;
+export {};

package/lib/types/backend.spec.d.ts

@@ -0,0 +1,2 @@
+declare const _default: () => Promise<void>;
+export default _default;

package/lib/types/gamepad-manager.d.ts

@@ -8,6 +8,11 @@ import { Gamepad } from './gamepad.js';
  */
 export declare class GamepadManager {
     private _monitor;
+    /**
+     * The spec's `Navigator.[[gamepads]]` — an EMPTY list until something
+     * connects, then one entry per index ever handed out, `null` where the slot
+     * is free. Never pre-filled: see the note on {@link getGamepads}.
+     */
     private _slots;
     private _monitorSignalIds;
     private _ManetteModule;
@@ -28,8 +33,48 @@ export declare class GamepadManager {
     private _findStateByDevice;
     private _createSnapshot;
     /**
-     * Returns a snapshot array matching the W3C `navigator.getGamepads()` contract.
-     * Each non-null entry is a frozen Gamepad object with current state.
+     * Returns a snapshot list matching the W3C `navigator.getGamepads()`
+     * contract. Each non-null entry is a frozen Gamepad object with current
+     * state.
+     *
+     * ## The list is EMPTY until something connects — not four nulls
+     *
+     * `Navigator.[[gamepads]]` "is initially the empty list" and grows only when
+     * an index is selected for a connected gamepad (W3C Gamepad, § Extensions to
+     * the `Navigator` Interface + § Selecting an unused gamepad index); step 6 of
+     * `getGamepads()` starts from an empty list and step 7 copies `[[gamepads]]`
+     * into it. So on a host where nothing has ever connected the conformant answer
+     * is `[]`, and that is what this returns.
+     *
+     * The pre-filled four-slot array this used to return is CHROME's shape, not
+     * the spec's, and the difference is measured rather than assumed — same page
+     * (`about:blank`), same machine, no controller attached:
+     *
+     *     firefox  → {"length":0,"json":"[]"}
+     *     chromium → {"length":4,"json":"[null,null,null,null]"}
+     *
+     * WebKit agrees with Firefox by construction:
+     * `NavigatorGamepad::gamepads()` does `if (m_gamepads.isEmpty()) return
+     * m_gamepads;` (`Source/WebCore/Modules/gamepad/NavigatorGamepad.cpp`).
+     * Hard-coding four made `getGamepads().length` report four non-existent ports.
+     *
+     * ## On a host with NO gamepad backend it stays a list — do NOT make it throw
+     *
+     * The W3C Gamepad API has no state for "this platform has no gamepad
+     * subsystem". `getGamepads()`'s steps only ever *return a list*; the single
+     * `throw` in them is a `SecurityError` for the `"gamepad"` permission policy,
+     * and every other negative case — no `Document`, no user gesture, nothing
+     * connected — is spelled "return an empty list". A real browser on a machine
+     * with no gamepad driver does exactly that, structurally: WebKit compiles an
+     * `EmptyGamepadProvider` (`Source/WebCore/platform/gamepad/`) whose
+     * `platformGamepads()` returns a static empty vector on every port with no
+     * backend.
+     *
+     * So throwing here would be LESS conformant, not more: it would break every
+     * page that does `navigator.getGamepads().length`, which is the canonical
+     * poll. The reason behind an empty answer is exposed NEXT TO the conformant
+     * surface instead — `hasGamepadBackend()` (exported from the package root)
+     * plus the one-time diagnostic this manager emits on its first init.
      */
     getGamepads(): (Gamepad | null)[];
     /** Cleanup — disconnect all signal handlers. */

package/lib/types/index.d.ts

@@ -4,6 +4,8 @@ export type { GamepadMappingType, GamepadHapticActuator, GamepadHapticEffectType
 export { GamepadEvent } from './gamepad-event.js';
 export type { GamepadEventInit } from './gamepad-event.js';
 export { GamepadManager } from './gamepad-manager.js';
+export { hasGamepadBackend } from './backend.js';
+export type { GamepadBackendStatus } from './backend.js';
 export { ManetteHapticActuator } from './haptic-actuator.js';
 export { MANETTE_TO_W3C_BUTTON, ManetteButton, W3CButton, W3C_BUTTON_COUNT } from './button-mapping.js';
 export { MANETTE_TO_W3C_AXIS, ManetteAxis, W3CAxis, W3C_AXIS_COUNT, TRIGGER_PRESS_THRESHOLD } from './axis-mapping.js';

package/lib/types/register.spec.d.ts

@@ -0,0 +1,3 @@
+import '@gjsify/gamepad/register';
+declare const _default: () => Promise<void>;
+export default _default;

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@gjsify/gamepad",
-    "version": "0.27.1",
+    "version": "0.29.0",
     "description": "Gamepad Web API for GJS using libmanette as backend",
     "type": "module",
     "module": "lib/esm/index.js",
@@ -43,14 +43,14 @@
         "controller"
     ],
     "dependencies": {
-        "@gjsify/dom-events": "^0.27.1"
+        "@gjsify/dom-events": "^0.29.0"
     },
     "devDependencies": {
         "@girs/gjs": "^4.1.0",
         "@girs/glib-2.0": "^4.1.0",
         "@girs/manette-0.2": "^4.1.0",
-        "@gjsify/cli": "^0.27.1",
-        "@gjsify/unit": "^0.27.1",
+        "@gjsify/cli": "^0.29.0",
+        "@gjsify/unit": "^0.29.0",
         "@types/node": "^25.9.2",
         "typescript": "^6.0.3"
     },