@gjsify/gamepad 0.35.0 → 0.37.0

package/globals.mjs

@@ -1,18 +1,12 @@
 /**
- * Re-exports native Gamepad API globals for browser builds.
+ * Re-exports the native Gamepad API globals for browser + NativeScript builds; the
+ * libmanette GJS backend stays GJS-only.
  *
- * Universal in modern browsers (Chrome 35+, Firefox 29+, Safari 10.1+);
- * 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"`
- * — 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 (`gjsify.runtimes.node` is
- * `"partial"`, which is not rewritten: the real GJS body runs through
- * `@gjsify/node-gi`).
+ * `@gjsify/resolve-npm/runtime-aliases.mjs` routes `@gjsify/gamepad` here whenever
+ * `gjsify.runtimes.<target> === "native"`, which makes this the NON-GJS entry for the
+ * package root: every root export a consumer may import must be answerable from here or
+ * the routed bundle dies with `MISSING_EXPORT`. NOT used on Node, whose slot is
+ * `"partial"` and is not rewritten — the real GJS body runs through `@gjsify/node-gi`.
  */
 
 export const Gamepad = globalThis.Gamepad;
@@ -21,20 +15,17 @@ 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.
+ * Whether this host has a gamepad backend at all — the GJS entry's question 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.
+ * REAL rather than stubbed or omitted (AGENTS.md § Slot routing: "Exports whose answer IS
+ * platform-independent stay REAL"): omitting it broke the README's recommended usage at
+ * BUILD time on `--app browser`/`--app nativescript`, and a thrower would break it at run
+ * time. `true` in a browser, `false` on NativeScript, which ships no Gamepad API.
  *
- * `async` to match the root entry's `Promise<boolean>` signature, where the
- * answer needs a dynamic `import('gi://Manette')`; here it is already known.
+ * `async` to match the root entry's `Promise<boolean>`, where the answer needs a dynamic
+ * `import('gi://Manette')`.
  */
 export async function hasGamepadBackend() {
     return typeof globalThis.navigator?.getGamepads === 'function';

package/lib/types/backend.d.ts

@@ -3,9 +3,8 @@ 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.
+ * - `absent`  — no backend reachable from here: no libmanette, a `--app node` process
+ *   without `@gjsify/node-gi`, or a target where `gi://` is stubbed by design.
  * - `failed`  — a backend should have been reachable and was not. A fault.
  */
 export type GamepadBackendStatus = 'manette' | 'absent' | 'failed';
@@ -16,24 +15,20 @@ export interface GamepadBackend {
     /** 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.
+     * The one-time line the USE site emits, or `null` when there is nothing to say.
+     * Carried rather than printed so the capability query stays silent.
      *
-     * `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.
+     * `'absent'` with a `null` diagnostic is the by-design `gi://` stub (see
+     * {@link isEmptiedGiModule}); `'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`.
+     * Override the `gi://Manette` import. Tests only — the single seam that exercises the
+     * absent and failed paths on a host where libmanette IS installed, which is every CI
+     * runner this package is tested on.
      */
     importer?: () => Promise<{
         default: typeof Manette;
@@ -45,62 +40,52 @@ interface GiLoadDiagnosis {
     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.
+ * 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 — hence the
+ * namespace parameter: the test asks for a namespace that cannot exist and classifies the
+ * error the running GJS/girepository 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.
+ * Resolve (once) which gamepad backend this host has. Emits NOTHING.
  *
- * 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.
+ * Passing `importer` after the probe has run is a test-setup bug and THROWS rather than
+ * being silently ignored: a `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.
+ * `absent` warns (a platform gap: expected, but never silent) and `failed` errors with
+ * the original attached — two levels for two situations. Deliberately NOT a rethrow:
+ * `GamepadManager` starts its init without awaiting it, so a rethrow becomes an unhandled
+ * rejection, unattributable on GJS and a process kill under Node's default
+ * `--unhandled-rejections=throw`. A half-installed typelib must not 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.
+ * The backend loaded and then the monitor did not come up — a DIFFERENT failure from a
+ * failed load: 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 fine. Routing it through the load-failure text
+ * would re-create the same conflation one layer up.
  */
 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.
+ * `false` means `navigator.getGamepads()` can never report a controller here, no matter
+ * what is connected — something the W3C surface itself cannot express, since it returns
+ * the same list either way. Answerable without constructing a monitor, and QUIET.
  *
- * 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}).
+ * `false` on every host without libmanette, which today means macOS and Windows:
+ * libmanette links libevdev unconditionally and libevdev is Linux/FreeBSD-only. Reports
+ * that the BRIDGE is usable, not that every later call succeeds — 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. */

package/lib/types/button-mapping.d.ts

@@ -1,7 +1,4 @@
-/**
- * Linux BTN_* input event codes as reported by Manette.Event.get_button().
- * These are the actual values libmanette 0.2 passes in button-press/release signals.
- */
+/** Linux BTN_* input event codes as reported by `Manette.Event.get_button()`. */
 export declare const LinuxButton: {
     readonly BTN_SOUTH: 304;
     readonly BTN_EAST: 305;
@@ -23,10 +20,7 @@ export declare const LinuxButton: {
     readonly BTN_DPAD_LEFT: 546;
     readonly BTN_DPAD_RIGHT: 547;
 };
-/**
- * W3C standard gamepad button indices.
- * https://w3c.github.io/gamepad/#remapping
- */
+/** W3C standard gamepad button indices — https://w3c.github.io/gamepad/#remapping */
 export declare const W3CButton: {
     readonly FACE_1: 0;
     readonly FACE_2: 1;
@@ -48,8 +42,6 @@ export declare const W3CButton: {
 };
 /** Total number of buttons in the W3C standard mapping. */
 export declare const W3C_BUTTON_COUNT = 17;
-/**
- * Maps Linux BTN_* code → W3C standard button index.
- */
+/** Linux BTN_* code → W3C standard button index. */
 export declare const MANETTE_TO_W3C_BUTTON: ReadonlyMap<number, number>;
 export { LinuxButton as ManetteButton };

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

@@ -1,10 +1,8 @@
 import { Gamepad } from './gamepad.js';
 /**
- * Singleton manager that wraps Manette.Monitor and maintains gamepad state.
- *
- * libmanette fires GObject signals on button/axis changes. This manager
- * caches the latest state so that `getGamepads()` can return a snapshot
- * matching the W3C Gamepad API's polling model.
+ * Singleton manager wrapping `Manette.Monitor`. libmanette fires GObject signals on
+ * button/axis changes, so this caches the latest state and `getGamepads()` returns a
+ * snapshot, matching the W3C polling model.
  */
 export declare class GamepadManager {
     private _monitor;
@@ -18,10 +16,7 @@ export declare class GamepadManager {
     private _ManetteModule;
     private _initPromise;
     private _initialized;
-    /**
-     * Lazily initialize the Manette.Monitor.
-     * Called on first `getGamepads()` invocation.
-     */
+    /** Lazily initialize the `Manette.Monitor`, on the first `getGamepads()`. */
     private _ensureInit;
     private _init;
     private _onDeviceConnected;

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@gjsify/gamepad",
-    "version": "0.35.0",
+    "version": "0.37.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.35.0"
+        "@gjsify/dom-events": "^0.37.0"
     },
     "devDependencies": {
         "@girs/gjs": "^4.1.0",
         "@girs/glib-2.0": "^4.1.0",
         "@girs/manette-0.2": "^4.1.0",
-        "@gjsify/cli": "^0.35.0",
-        "@gjsify/unit": "^0.35.0",
+        "@gjsify/cli": "^0.37.0",
+        "@gjsify/unit": "^0.37.0",
         "@types/node": "^25.9.2",
         "typescript": "^6.0.3"
     },