@gjsify/gamepad 0.52.0 → 0.54.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 on the first `getGamepads()` call.
+The W3C Gamepad API for GJS. Provides `navigator.getGamepads()` polling, `Gamepad`, `GamepadButton`, `gamepadconnected`/`gamepaddisconnected` events, and rumble via `GamepadHapticActuator`. The backend is SDL3 on macOS and Windows, through [`@gjsify/gamepad-native`](../gamepad-native/README.md), and libmanette 0.2 on Linux until SDL has been compared against it there; it starts lazily 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,11 +39,49 @@ for (const pad of gamepads) {
 }
 ```
 
-## Platform support — hosts without libmanette
+`vibrationActuator` follows the spec on both backends: parameters default to 0, an
+out-of-range one rejects with `TypeError`, an effect the pad lacks with
+`NotSupportedError`. `playEffect()` resolves `'complete'` once the effect has played
+(`startDelay + duration`, at most 5 s), or `'preempted'` when a later `playEffect()` or
+`reset()` interrupts it.
 
-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.
+## Platform support
 
-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`.
+| host | backend | status |
+|---|---|---|
+| Linux | libmanette 0.2 (`gi://Manette`) by default; the SDL3 shim with `GJSIFY_GAMEPAD_BACKEND=sdl`, or both with `=compare` | supported (libmanette); the shim reads a virtual uinput pad in CI |
+| macOS | SDL3 behind a GObject shim (`gi://GjsifyGamepad`, `@gjsify/gamepad-native`) | partial: builds, loads and enumerates; input from a real controller not yet verified |
+| Windows | the same shim, from Node through `@gjsify/node-gi` | partial: builds, loads, and reads a virtual XInput pad in CI; a real controller not yet verified |
+
+The decision is [ADR 0075](../../../docs/adr/0075-darwin-gamepad-backend-is-sdl3-behind-a-gobject-shim.md) and its Amendment 1: SDL3, statically linked and trimmed to the input subsystems, becomes the one backend on every OS, and replaces libmanette on Linux once it has been compared against it there with real controllers. libmanette itself cannot move: it links `libevdev` unconditionally, and libevdev is packaged for Linux and FreeBSD only.
+
+On macOS and Windows the typelib and library come from the per-target optional dependency `@gjsify/gamepad-native-<os>-<arch>`, and a process finds them through `gjsify run`, which puts every installed prebuild on `GI_TYPELIB_PATH` (and, on Windows, on `PATH`). Neither probes for libmanette.
+
+### Comparing the two Linux backends
+
+Amendment 1 removes libmanette only after the SDL3 shim has been compared against it on real controllers. `GJSIFY_GAMEPAD_BACKEND` selects the backend per process on Linux (macOS and Windows ignore it):
+
+| value | the page sees | what else happens |
+|---|---|---|
+| unset / `manette` | libmanette | — |
+| `sdl` | the SDL3 shim | — |
+| `compare` | libmanette | the shim runs beside it on the same controllers; connects, disconnects and every control on which the two disagree for more than one poll go to stderr, prefixed `[@gjsify/gamepad compare]` |
+
+Controllers are paired by USB vendor:product (read from each backend's GUID), then by connection order. A difference of up to 0.02 is scaling, not disagreement: libmanette normalises the evdev range, SDL rescales to int16 first. One difference is expected and is not a control: the two name the same pad differently (`Gamepad.id`), because SDL takes the name from its mapping database and libmanette from the kernel.
+
+Found so far (ADR 0075, Amendment 1's measurements): on an 8BitDo N30 Pro 2 SDL is the correct one of the two. libmanette 0.2 reports no Home button and no right-stick Y for it, and fires the left trigger when the right stick is pushed down: its evdev backend matches a mapping's `aN` against the kernel axis CODE rather than the N-th axis the device has, which only coincides on pads whose axis codes have no gaps.
+
+### Node
+
+`gjsify.runtimes.node` is `partial`, and the same source runs under Node: a `--app node` bundle reaches `gi://` through [`@gjsify/node-gi`](../../node-gi/node-gi), so with the macOS prebuild installed the shim works there too. `@gjsify/node-gi` is NOT a dependency — a plain-Node program without it is a supported configuration and answers `hasGamepadBackend() === false` with a `console.warn` naming it.
+
+```bash
+npm install @gjsify/node-gi @gjsify/gamepad   # plus @gjsify/gamepad-native-darwin-<arch>
+```
+
+Measured on macOS 27 arm64 / Node 24.21.0: the probe classifies `sdl`, `hasGamepadBackend()` is `true`, and `SdlSource` initialises, enumerates zero controllers and tears down over repeated cycles (`gjsify workspace @gjsify/gamepad run test:gjs-on-node`, 4 tests / 28 assertions). Input from a real controller is unverified on this target, exactly as on GJS.
+
+A host with no backend — Linux without libmanette, macOS or Windows without the prebuild — is a platform gap, not a bug in this package, and it is reported, not hidden. There, `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:
 
@@ -58,10 +96,30 @@ if (!(await hasGamepadBackend())) {
 
 `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.
+* **no backend** (no Manette typelib; no `@gjsify/gamepad-native` prebuild on macOS or Windows; 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.
 
+## Driving the manager from your own device source
+
+`GamepadManager` reads devices through a `GamepadSource`: an object with `start(sink)`, `stop()` and an optional `poll()`, which reports `connected` / `disconnected` / `button` / `axis` in the W3C standard layout. Hand one to the constructor to test gamepad handling with no controller attached, or to feed input you already own:
+
+```typescript
+import { GamepadManager, type GamepadSource, type GamepadSourceSink } from '@gjsify/gamepad';
+
+const pad = { id: 'Scripted Pad', vibrationActuator: null };
+let sink: GamepadSourceSink | null = null;
+const source: GamepadSource = {
+    name: 'scripted',
+    start: (s) => { sink = s; s.connected(pad); },
+    stop: () => { sink = null; },
+};
+
+const manager = new GamepadManager({ source });
+manager.getGamepads();          // starts the source: [Gamepad { id: 'Scripted Pad', index: 0, … }]
+sink!.button(pad, 0, 1, true);  // standard button 0 (A / Cross) pressed
+```
+
 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

package/lib/esm/axis-mapping.js

@@ -1 +1 @@
-const e={LEFT_X:0,LEFT_Y:1,RIGHT_X:2,RIGHT_Y:3,LEFT_TRIGGER:4,RIGHT_TRIGGER:5},t={LEFT_STICK_X:0,LEFT_STICK_Y:1,RIGHT_STICK_X:2,RIGHT_STICK_Y:3},n=4,r=new Map([[e.LEFT_X,t.LEFT_STICK_X],[e.LEFT_Y,t.LEFT_STICK_Y],[e.RIGHT_X,t.RIGHT_STICK_X],[e.RIGHT_Y,t.RIGHT_STICK_Y]]),i=.5;export{r as MANETTE_TO_W3C_AXIS,e as ManetteAxis,i as TRIGGER_PRESS_THRESHOLD,t as W3CAxis,n as W3C_AXIS_COUNT};
+const e={LEFT_X:0,LEFT_Y:1,RIGHT_X:3,RIGHT_Y:4,LEFT_TRIGGER:2,RIGHT_TRIGGER:5},t={LEFT_STICK_X:0,LEFT_STICK_Y:1,RIGHT_STICK_X:2,RIGHT_STICK_Y:3},n=4,r=new Map([[e.LEFT_X,t.LEFT_STICK_X],[e.LEFT_Y,t.LEFT_STICK_Y],[e.RIGHT_X,t.RIGHT_STICK_X],[e.RIGHT_Y,t.RIGHT_STICK_Y]]),i=.5;export{r as MANETTE_TO_W3C_AXIS,e as ManetteAxis,i as TRIGGER_PRESS_THRESHOLD,t as W3CAxis,n as W3C_AXIS_COUNT};

package/lib/esm/backend.js

@@ -1 +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?version=0.2`)),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};
+import"./_virtual/_rolldown/runtime.js";import{hostEnv as e,hostOs as t}from"@gjsify/utils/core";const n=`GJSIFY_GAMEPAD_BACKEND`,r=[`manette`,`sdl`,`compare`];function typelibAbsentNeedle(e){return`Typelib file for namespace '${e}'`}const i=`@gjsify/node-gi`;function loadFaultText(e,t){return`[@gjsify/gamepad] The gi://${e} gamepad backend failed to load — a fault on this host, NOT ${t}. getGamepads() reports no controllers until it is fixed.`}const a={status:`manette`,namespace:`Manette`,noTypelibText:`[@gjsify/gamepad] No gamepad backend on this host — the Manette-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); Windows has no libmanette at all. Gate on hasGamepadBackend().`,noBridgeText:`[@gjsify/gamepad] No gamepad backend in this process — ${i} is not installed, and it is how a --app node bundle reaches gi://Manette. getGamepads() reports no controllers until it is added (npm install ${i}, plus libmanette + its typelib). Gate on hasGamepadBackend().`,loadFaultText:loadFaultText(`Manette`,`a platform without libmanette`)},o={status:`sdl`,namespace:`GjsifyGamepad`,noTypelibText:"[@gjsify/gamepad] No gamepad backend on this host — the GjsifyGamepad-1.0 typelib of @gjsify/gamepad-native is not on the typelib path, so getGamepads() reports no controllers no matter what is plugged in. It ships as the optional dependency @gjsify/gamepad-native-<os>-<arch>: check that it installed, and start the program through `gjsify run` (or put its prebuilds/<os>-<arch> directory on GI_TYPELIB_PATH and on the library search path: PATH on Windows). Gate on hasGamepadBackend().",noBridgeText:`[@gjsify/gamepad] No gamepad backend in this process — ${i} is not installed, and it is how a --app node bundle reaches gi://GjsifyGamepad. getGamepads() reports no controllers until it is added (npm install ${i}). Gate on hasGamepadBackend().`,loadFaultText:loadFaultText(`GjsifyGamepad`,`a host without @gjsify/gamepad-native`)},s={manette:a,sdl:o};let c=null,l=!1;function isEmptiedGiModule(e){return typeof e==`object`&&!!e&&Object.getPrototypeOf(e)===Object.prototype&&Object.getOwnPropertyNames(e).length===0}function isMissingNodeGiBridge(e,t){if(!t.includes(i))return!1;let n=e?.code;return n===`MODULE_NOT_FOUND`||n===`ERR_MODULE_NOT_FOUND`||t.includes(`Cannot find module`)}function _diagnoseGiLoadError(e,t=a){let n=e instanceof Error?e.message:String(e);return n.includes(typelibAbsentNeedle(t.namespace))?{status:`absent`,diagnostic:t.noTypelibText}:isMissingNodeGiBridge(e,n)?{status:`absent`,diagnostic:t.noBridgeText}:{status:`failed`,diagnostic:t.loadFaultText}}async function probeGi(e,t){let n;try{if(n=(await t()).default,typeof n?.Monitor!=`function`)return isEmptiedGiModule(n)?{status:`absent`,module:null,error:null,diagnostic:null,shadow:null}:{status:`failed`,module:null,error:Error(`gi://${e.namespace} resolved without a Monitor class — unexpected ${e.namespace} ABI`),diagnostic:e.loadFaultText,shadow:null}}catch(t){let{status:n,diagnostic:r}=_diagnoseGiLoadError(t,e);return{status:n,module:null,error:t,diagnostic:r,shadow:null}}return e.status===`sdl`?{status:`sdl`,module:n,error:null,diagnostic:null,shadow:null}:{status:`manette`,module:n,error:null,diagnostic:null,shadow:null}}function readBackendChoice(e){let t=e(n);if(t===void 0||t===``)return{choice:`manette`,note:null};let i=t.trim().toLowerCase();return r.includes(i)?{choice:i,note:null}:{choice:`manette`,note:`[@gjsify/gamepad] ${n}=${JSON.stringify(t)} is not one of ${r.join(`, `)}; using manette.`}}async function probeGamepadBackend(n){let probeSdl=()=>probeGi(o,n.sdlImporter??(()=>import(`gi://GjsifyGamepad?version=1.0`))),probeManette=()=>probeGi(a,n.importer??(()=>import(`gi://Manette?version=0.2`))),r=(n.hostOs??t)();if(r===`darwin`||r===`win32`)return probeSdl();let{choice:i,note:s}=readBackendChoice(n.env??e);if(i===`sdl`)return probeSdl();let c=await probeManette();return s===null?i===`compare`?{...c,shadow:await probeSdl()}:c:{...c,diagnostic:c.diagnostic??s}}function loadGamepadBackend(e={}){if(c!==null){if(e.importer||e.sdlImporter||e.hostOs||e.env)throw Error(`loadGamepadBackend({ importer, sdlImporter, hostOs, env }) called after the probe already ran — the probe is cached per process, so the override would be ignored. Call _resetGamepadBackendCache() first (tests only).`);return c}return c=probeGamepadBackend(e),c}function reportGamepadBackendOnce(e){if(l)return;let t=e.shadow,r=t!==null&&t.status!==`sdl`?`[@gjsify/gamepad] ${n}=compare, but the SDL3 shim is ${t.status}: nothing to compare against. ${t.diagnostic??``}`.trim():null;if(e.status===`failed`){l=!0,console.error(e.diagnostic,e.error),r!==null&&warnWithCause(r,t?.error);return}e.diagnostic===null&&r===null||(l=!0,e.diagnostic!==null&&console.warn(e.diagnostic),r!==null&&warnWithCause(r,t?.error))}function warnWithCause(e,t){t==null?console.warn(e):console.warn(e,t)}function reportGamepadMonitorFault(e,t=null){let n=t?.name??`gamepad`,r=t?.startRequirements?`${t.startRequirements} `:``;console.error(`[@gjsify/gamepad] The ${n} backend loaded but the gamepad monitor could not be started — a fault AFTER the backend was available, not a missing backend. `+r+`getGamepads() reports no controllers until it is fixed.`,e)}async function hasGamepadBackend(){let{status:e}=await loadGamepadBackend();return e===`manette`||e===`sdl`}async function describeGamepadBackend(){let e=await loadGamepadBackend(),t={manette:`libmanette (gi://Manette)`,sdl:`SDL3 (gi://GjsifyGamepad)`};if(e.status===`absent`||e.status===`failed`)return`none (${e.status})`;let n=t[e.status];return e.shadow?.status===`sdl`?`${n}, compared against ${t.sdl}`:n}function _resetGamepadBackendCache(){c=null,l=!1}export{n as GAMEPAD_BACKEND_ENV,s as _GI_BACKENDS,_diagnoseGiLoadError,_resetGamepadBackendCache,describeGamepadBackend,hasGamepadBackend,loadGamepadBackend,reportGamepadBackendOnce,reportGamepadMonitorFault};

package/lib/esm/compare-source.js

@@ -0,0 +1,2 @@
+import"./_virtual/_rolldown/runtime.js";import"./axis-mapping.js";import"./button-mapping.js";const e=.02;var MirrorSink=class{_label;_report;_forward;devices=new Map;constructor(e,t,n){this._label=e,this._report=t,this._forward=n}connected(e){this.devices.has(e)||(this.devices.set(e,{device:e,buttons:Array.from({length:17}).fill(0),pressed:Array.from({length:17}).fill(!1),axes:Array.from({length:4}).fill(0)}),this._report(`${this._label}: connected "${e.id}"`)),this._forward?.connected(e)}disconnected(e){this.devices.delete(e)&&this._report(`${this._label}: disconnected "${e.id}"`),this._forward?.disconnected(e)}button(e,t,n,r){let i=this.devices.get(e);i&&t>=0&&t<17&&(i.buttons[t]=n,i.pressed[t]=r),this._forward?.button(e,t,n,r)}axis(e,t,n){let r=this.devices.get(e);r&&t>=0&&t<4&&(r.axes[t]=n),this._forward?.axis(e,t,n)}};function differences(t,n){let r=[];for(let i=0;i<17;i++){let a=t.buttons[i],o=n.buttons[i];(Math.abs(a-o)>e||t.pressed[i]!==n.pressed[i])&&r.push(`button ${i}: ${a.toFixed(2)}${t.pressed[i]?`*`:``} vs ${o.toFixed(2)}${n.pressed[i]?`*`:``}`)}for(let i=0;i<4;i++){let a=t.axes[i],o=n.axes[i];Math.abs(a-o)>e&&r.push(`axis ${i}: ${a.toFixed(2)} vs ${o.toFixed(2)}`)}return r}function pairUp(e,t){let n=[],r=[...t],i=[];for(let t of e){let e=t.device.model===void 0?-1:r.findIndex(e=>e.device.model===t.device.model);e>=0?n.push([t,r.splice(e,1)[0]]):i.push(t)}for(let e=0;e<Math.min(i.length,r.length);e++)n.push([i[e],r[e]]);return n}var ComparingSource=class{_primary;_shadow;_report;name;startRequirements;_primarySink=null;_shadowSink=null;_shadowStarted=!1;_pending=``;_reported=``;constructor(e,t,n=e=>console.warn(`[@gjsify/gamepad compare] ${e}`)){this._primary=e,this._shadow=t,this._report=n,this.name=`${e.name} (compared against ${t.name})`,this.startRequirements=e.startRequirements}start(e){this._primarySink=new MirrorSink(this._primary.name,this._report,e),this._shadowSink=new MirrorSink(this._shadow.name,this._report,null),this._primary.start(this._primarySink);try{this._shadow.start(this._shadowSink),this._shadowStarted=!0,this._report(`comparing ${this._primary.name} against ${this._shadow.name}`)}catch(e){this._report(`${this._shadow.name} did not start, nothing to compare against: ${String(e)}`),this._shadow.stop()}}poll(){this._primary.poll?.(),this._shadowStarted&&(this._shadow.poll?.(),this._compare())}stop(){this._primary.stop(),this._shadowStarted&&this._shadow.stop(),this._shadowStarted=!1,this._primarySink=null,this._shadowSink=null,this._pending=``,this._reported=``}_compare(){let e=[...this._primarySink?.devices.values()??[]],t=[...this._shadowSink?.devices.values()??[]],n=[];e.length!==t.length&&n.push(`${this._primary.name} sees ${e.length} controller(s), ${this._shadow.name} sees ${t.length}`);for(let[r,i]of pairUp(e,t)){let e=differences(r,i);e.length>0&&n.push(`"${r.device.id}" vs "${i.device.id}": ${e.join(`, `)}`)}let r=n.join(`
+`),i=r===this._pending;if(this._pending=r,!(!i||r===this._reported))if(this._reported=r,r===``)this._report(`the two backends agree again`);else for(let e of n)this._report(e)}};export{ComparingSource};

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{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};
+import"./_virtual/_rolldown/runtime.js";import"./axis-mapping.js";import{loadGamepadBackend as e,reportGamepadBackendOnce as t,reportGamepadMonitorFault as n}from"./backend.js";import"./button-mapping.js";import{ComparingSource as r}from"./compare-source.js";import{GamepadButton as i}from"./gamepad-button.js";import{GamepadEvent as a}from"./gamepad-event.js";import{Gamepad as o}from"./gamepad.js";import{ManetteSource as s}from"./manette-source.js";import{SdlSource as c}from"./sdl-source.js";var GamepadManager=class{_slots=[];_injectedSource;_source=null;_started=!1;_initPromise=null;_initialized=!1;_sink={connected:e=>this._onDeviceConnected(e),disconnected:e=>this._onDeviceDisconnected(e),button:(e,t,n,r)=>this._onButton(e,t,n,r),axis:(e,t,n)=>this._onAxis(e,t,n)};constructor(e={}){this._injectedSource=e.source??null}_ensureInit(){this._initialized||(this._initPromise||=this._init().catch(e=>{n(e,this._source),this._initialized=!0}))}async _init(){let n=this._injectedSource;if(n===null){let i=await e();if(t(i),i.status===`sdl`)n=new c(i.module);else if(i.status===`manette`)n=new s(i.module),i.shadow?.status===`sdl`&&(n=new r(n,new c(i.shadow.module)));else{this._initialized=!0;return}}this._source=n,n.start(this._sink),this._started=!0,this._initialized=!0}_onDeviceConnected(e){if(this._findState(e))return;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)};this._slots[t]=n,globalThis.dispatchEvent?.(new a(`gamepadconnected`,{gamepad:this._createSnapshot(n)}))}_onDeviceDisconnected(e){let t=this._findState(e);if(!t)return;t.connected=!1;let n=this._createSnapshot(t);this._slots[t.index]=null,globalThis.dispatchEvent?.(new a(`gamepaddisconnected`,{gamepad:n}))}_onButton(e,t,n,r){let i=this._findState(e);!i||!Number.isInteger(t)||t<0||t>=17||(i.buttons[t]=n,i.buttonsPressed[t]=r,i.timestamp=performance.now())}_onAxis(e,t,n){let r=this._findState(e);!r||!Number.isInteger(t)||t<0||t>=4||(r.axes[t]=n,r.timestamp=performance.now())}_findState(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 i(e.buttonsPressed[n],e.buttonsPressed[n]||e.buttons[n]>0,e.buttons[n]));return new o({id:e.device.id,index:e.index,connected:e.connected,timestamp:e.timestamp,mapping:`standard`,axes:Array.from(e.axes),buttons:t,vibrationActuator:e.device.vibrationActuator})}getGamepads(){return this._ensureInit(),this._started&&this._source?.poll?.(),this._slots.map(e=>e?this._createSnapshot(e):null)}dispose(){this._source?.stop(),this._source=null,this._started=!1,this._slots.length=0,this._initialized=!1,this._initPromise=null}};export{GamepadManager};

package/lib/esm/haptic-actuator.js

@@ -1 +1 @@
-import"./_virtual/_rolldown/runtime.js";var ManetteHapticActuator=class{effects;_device;constructor(e){this._device=e,this.effects=e.has_rumble()?[`dual-rumble`]:[]}playEffect(e,t){if(e!==`dual-rumble`||!this._device.has_rumble())return Promise.resolve(`complete`);let n=t?.duration??200,r=Math.round((t?.strongMagnitude??1)*65535),i=Math.round((t?.weakMagnitude??1)*65535);return this._device.rumble(r,i,Math.min(n,32767)),Promise.resolve(`complete`)}reset(){return this._device.has_rumble()&&this._device.rumble(0,0,0),Promise.resolve(`complete`)}};export{ManetteHapticActuator};
+import"./_virtual/_rolldown/runtime.js";import{DOMException as e}from"@gjsify/dom-events";const t=5e3;function toMotor(e){return Math.round(e*65535)}function isUnitMagnitude(e){return Number.isFinite(e)&&e>=0&&e<=1}function isMilliseconds(e){return Number.isFinite(e)&&e>=0}var RumbleHapticActuator=class{_playing=null;playEffect(n,r={}){let i=r.duration??0,a=r.startDelay??0,o={strong:r.strongMagnitude??0,weak:r.weakMagnitude??0,leftTrigger:r.leftTrigger??0,rightTrigger:r.rightTrigger??0};if(n!==`dual-rumble`&&n!==`trigger-rumble`)return Promise.reject(TypeError(`Unknown haptic effect type '${String(n)}'.`));if(!isMilliseconds(i)||!isMilliseconds(a)||i+a>5e3)return Promise.reject(TypeError(`A haptic effect lasts 0..${t} ms including its startDelay.`));if(!(n===`dual-rumble`?[o.strong,o.weak]:Object.values(o)).every(isUnitMagnitude))return Promise.reject(TypeError(`Haptic effect magnitudes are 0..1.`));if(this._preempt(),!this.effects.includes(n))return Promise.reject(new e(`This gamepad cannot play a '${n}' effect.`,`NotSupportedError`));let s={strong:toMotor(o.strong),weak:toMotor(o.weak),leftTrigger:toMotor(o.leftTrigger),rightTrigger:toMotor(o.rightTrigger)};return new Promise(e=>{let t={resolve:e,timer:null};this._playing=t;let finish=()=>{this._playing===t&&(this._playing=null,e(`complete`))},start=()=>{if(this._playing===t){if(i===0){finish();return}this._start(n,s,Math.round(i)),t.timer=setTimeout(finish,i)}};a>0?t.timer=setTimeout(start,a):start()})}reset(){return this._preempt(),Promise.resolve(`complete`)}_preempt(){let e=this._playing;e&&(this._playing=null,e.timer!==null&&clearTimeout(e.timer),this._stop(),e.resolve(`preempted`))}},ManetteHapticActuator=class extends RumbleHapticActuator{_device;effects;constructor(e){super(),this._device=e,this.effects=e.has_rumble()?[`dual-rumble`]:[]}_start(e,t,n){this._device.rumble(t.strong,t.weak,n)}_stop(){this._device.rumble(0,0,0)}},SdlHapticActuator=class extends RumbleHapticActuator{_device;effects;constructor(e){super(),this._device=e;let t=[];e.has_rumble()&&t.push(`dual-rumble`),e.has_trigger_rumble()&&t.push(`trigger-rumble`),this.effects=t}_start(e,t,n){e===`trigger-rumble`&&(this._device.rumble_triggers(t.leftTrigger,t.rightTrigger,n),!this.effects.includes(`dual-rumble`))||this._device.rumble(t.strong,t.weak,n)}_stop(){this.effects.includes(`dual-rumble`)&&this._device.rumble(0,0,0),this.effects.includes(`trigger-rumble`)&&this._device.rumble_triggers(0,0,0)}};export{t as MAX_HAPTIC_EFFECT_DURATION_MS,ManetteHapticActuator,SdlHapticActuator};

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

package/lib/esm/manette-source.js

@@ -0,0 +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{ManetteHapticActuator as a}from"./haptic-actuator.js";import{modelFromGuid as o}from"./source.js";var ManetteSource=class{_Manette;name=`gi://Manette`;startRequirements=`Manette.Monitor needs udev and /dev/input access, which a sandbox can withhold (flatpak: --device=input).`;_monitor=null;_monitorSignalIds=[];_devices=new Map;constructor(e){this._Manette=e}start(e){let t=new this._Manette.Monitor;this._monitor=t;let n=t.iterate(),r=n.next();for(;r[0];){let t=r[1];t&&this._add(t,e),r=n.next()}this._monitorSignalIds.push(t.connect(`device-connected`,(t,n)=>{this._add(n,e)}),t.connect(`device-disconnected`,(t,n)=>{this._remove(n,e)}))}stop(){for(let[e,t]of this._devices)for(let n of t.signalIds)e.disconnect(n);if(this._devices.clear(),this._monitor){for(let e of this._monitorSignalIds)this._monitor.disconnect(e);this._monitor=null}this._monitorSignalIds=[]}_add(e,t){if(this._devices.has(e))return;let n={id:e.get_name()??`Gamepad (${e.get_guid()})`,vibrationActuator:new a(e),model:o(e.get_guid())},r={handle:n,signalIds:[]};this._devices.set(e,r),r.signalIds.push(e.connect(`button-press-event`,(e,r)=>{this._onButton(n,r,!0,t)}),e.connect(`button-release-event`,(e,r)=>{this._onButton(n,r,!1,t)}),e.connect(`absolute-axis-event`,(e,r)=>{this._onAxis(n,r,t)}),e.connect(`hat-axis-event`,(e,r)=>{this._onHat(n,r,t)}),e.connect(`disconnected`,()=>{this._remove(e,t)})),t.connected(n)}_remove(e,t){let n=this._devices.get(e);if(n){for(let t of n.signalIds)e.disconnect(t);this._devices.delete(e),t.disconnected(n.handle)}}_onButton(e,t,n,i){let[a,o]=t.get_button();if(!a)return;let s=r.get(o);s!==void 0&&i.button(e,s,+!!n,n)}_onAxis(r,a,o){let[s,c,l]=a.get_absolute();if(!s)return;let u=e.get(c);if(u!==void 0){o.axis(r,u,l);return}let d=c===t.LEFT_TRIGGER?i.LEFT_TRIGGER:c===t.RIGHT_TRIGGER?i.RIGHT_TRIGGER:void 0;if(d===void 0)return;let f=(l+1)/2;o.button(r,d,f,f>n)}_onHat(e,t,n){let[r,a,o]=t.get_hat();if(!r)return;let[s,c]=a===0?[i.DPAD_LEFT,i.DPAD_RIGHT]:a===1?[i.DPAD_UP,i.DPAD_DOWN]:[void 0,void 0];s===void 0||c===void 0||(n.button(e,s,+(o<0),o<0),n.button(e,c,+(o>0),o>0))}};export{ManetteSource};

package/lib/esm/register.js

@@ -1 +1 @@
-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);
+import{GamepadEvent as e}from"./gamepad-event.js";import{GamepadManager as t}from"./gamepad-manager.js";import"@gjsify/node-globals/register/navigator";const n=globalThis;if(typeof n.navigator.getGamepads!=`function`){let e=new t;n.navigator.getGamepads=()=>e.getGamepads()}n.GamepadEvent===void 0&&(n.GamepadEvent=e);

package/lib/esm/sdl-source.js

@@ -0,0 +1 @@
+import"./_virtual/_rolldown/runtime.js";import{TRIGGER_PRESS_THRESHOLD as e}from"./axis-mapping.js";import{W3CButton as t}from"./button-mapping.js";import{SdlHapticActuator as n}from"./haptic-actuator.js";import{modelFromGuid as r}from"./source.js";function isPressed(n,r){return n===t.LEFT_TRIGGER||n===t.RIGHT_TRIGGER?r>e:r>0}var SdlSource=class{_GjsifyGamepad;name=`gi://GjsifyGamepad`;startRequirements=`SDL's gamepad subsystem has to start in this process; the error carries SDL's own reason.`;_monitor=null;_sink=null;_signalIds=[];_devices=new Map;constructor(e){this._GjsifyGamepad=e}start(e){let t=this._GjsifyGamepad.Monitor.new();this._monitor=t,this._sink=e,this._signalIds.push(t.connect(`device-added`,(t,n)=>this._add(n,e)),t.connect(`device-removed`,(t,n)=>this._remove(n,e))),t.update()}poll(){let e=this._monitor,t=this._sink;if(!(!e||!t)){e.update();for(let[e,n]of this._devices)this._report(e,n,t)}}stop(){let e=this._monitor;if(this._monitor=null,this._sink=null,e){for(let t of this._signalIds)e.disconnect(t);e.close()}this._signalIds=[],this._devices.clear()}_add(e,t){if(this._devices.has(e))return;let i={id:e.get_name(),vibrationActuator:new n(e),model:r(e.get_guid())},a={handle:i,buttons:Array.from({length:17}).fill(0),axes:Array.from({length:4}).fill(0)};this._devices.set(e,a),t.connected(i),this._report(e,a,t)}_remove(e,t){let n=this._devices.get(e);n&&(this._devices.delete(e),t.disconnected(n.handle))}_report(e,t,n){let r=e.get_buttons();for(let e=0;e<17;e++){let i=r[e]??0;i!==t.buttons[e]&&(t.buttons[e]=i,n.button(t.handle,e,i,isPressed(e,i)))}let i=e.get_axes();for(let e=0;e<4;e++){let r=i[e]??0;r!==t.axes[e]&&(t.axes[e]=r,n.axis(t.handle,e,r))}}};export{SdlSource};

package/lib/esm/source.js

@@ -0,0 +1 @@
+import"./_virtual/_rolldown/runtime.js";function modelFromGuid(e){if(!e||e.length<20)return;let le16=t=>e.slice(t+2,t+4)+e.slice(t,t+2),t=le16(8);return t===`0000`?void 0:`${t}:${le16(16)}`.toLowerCase()}export{modelFromGuid};

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

@@ -1,13 +1,20 @@
 /**
- * SDL logical axis indices as reported by Manette.Event.get_absolute().
- * These are the SDL gamepad mapping indices, NOT Linux ABS_* hardware codes.
+ * The axis codes `Manette.Event.get_absolute()` reports: Linux `ABS_*` codes. A mapped
+ * device is translated by libmanette's own table (`manette-mapping.c`: `leftx`→ABS_X,
+ * `lefty`→ABS_Y, `rightx`→ABS_RX, `righty`→ABS_RY; the triggers become the BUTTONS
+ * BTN_TL2/BTN_TR2), an unmapped one passes its kernel codes through. Measured with a
+ * uinput pad under gi://Manette: the right stick arrives as 3 and 4.
+ *
+ * NOT SDL mapping indices. This table once said RIGHT_X 2 / RIGHT_Y 3 / LEFT_TRIGGER 4,
+ * which put the right stick's X on W3C axis 3 and its Y on the left trigger for every
+ * controller libmanette maps; an 8BitDo N30 Pro 2 compared against the SDL3 shim showed it.
  */
 export declare const ManetteAxis: {
     readonly LEFT_X: 0;
     readonly LEFT_Y: 1;
-    readonly RIGHT_X: 2;
-    readonly RIGHT_Y: 3;
-    readonly LEFT_TRIGGER: 4;
+    readonly RIGHT_X: 3;
+    readonly RIGHT_Y: 4;
+    readonly LEFT_TRIGGER: 2;
     readonly RIGHT_TRIGGER: 5;
 };
 /**
@@ -23,8 +30,8 @@ export declare const W3CAxis: {
 /** Total number of axes in the W3C standard mapping. */
 export declare const W3C_AXIS_COUNT = 4;
 /**
- * Maps SDL logical axis → W3C axis index.
- * Stick axes (0–3) map 1:1. Trigger axes (4–5) are NOT in this map —
+ * Maps the libmanette axis code → W3C axis index.
+ * Only the four stick axes are in this map; the trigger codes are NOT —
  * they are handled separately in gamepad-manager as buttons[6]/buttons[7].
  */
 export declare const MANETTE_TO_W3C_AXIS: ReadonlyMap<number, number>;

package/lib/types/backend.d.ts

@@ -1,29 +1,61 @@
 import type Manette from '@girs/manette-0.2';
+import { type TargetOs } from '@gjsify/utils/core';
+import type { GjsifyGamepadNamespace } from './sdl-namespace.js';
+import type { GamepadSource } from './source.js';
 /**
  * What this host has.
  *
  * - `manette` — the Manette-0.2 typelib loaded and exposes `Monitor`.
- * - `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.
+ * - `sdl`     — the GjsifyGamepad-1.0 typelib (`@gjsify/gamepad-native`) loaded and
+ *   exposes `Monitor`.
+ * - `absent`  — no backend reachable from here: no libmanette, no gamepad-native
+ *   prebuild, 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';
-/** The resolved backend probe. `module` is non-null iff `status === 'manette'`. */
-export interface GamepadBackend {
-    status: GamepadBackendStatus;
-    module: typeof Manette | null;
+export type GamepadBackendStatus = 'manette' | 'sdl' | 'absent' | 'failed';
+/**
+ * Which backend a Linux process uses — `GJSIFY_GAMEPAD_BACKEND`, read once per process.
+ * darwin and win32 have only the SDL3 shim and ignore it.
+ *
+ * - `manette` (the default) — libmanette, as before Amendment 1.
+ * - `sdl`     — the SDL3 shim alone.
+ * - `compare` — libmanette drives the page and the SDL3 shim runs beside it on the
+ *   same controllers; every disagreement is written to stderr (`compare-source.ts`).
+ *   This is the measurement Amendment 1 requires before libmanette is removed.
+ */
+export type GamepadBackendChoice = 'manette' | 'sdl' | 'compare';
+/** The environment variable behind {@link GamepadBackendChoice}. */
+export declare const GAMEPAD_BACKEND_ENV = "GJSIFY_GAMEPAD_BACKEND";
+/** What every probe result carries besides the module. */
+interface GamepadBackendReport {
     /** The original load error for `absent`/`failed`; `null` otherwise. */
     error: unknown;
     /**
      * 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.
-     *
-     * `'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.
+     * Carried rather than printed so the capability query stays silent. `'absent'`
+     * with a `null` diagnostic is the by-design `gi://` stub (see
+     * {@link isEmptiedGiModule}).
      */
     diagnostic: string | null;
+    /**
+     * `compare` mode only: the SDL3 shim's own probe, run beside the primary. The
+     * manager compares against it when it is `sdl` and reports its diagnostic when it
+     * is not. `null` in every other mode.
+     */
+    shadow: GamepadBackend | null;
 }
+/** The resolved backend probe: a module exactly for the two usable states. */
+export type GamepadBackend = GamepadBackendReport & ({
+    status: 'manette';
+    module: typeof Manette;
+} | {
+    status: 'sdl';
+    module: GjsifyGamepadNamespace;
+} | {
+    status: 'absent' | 'failed';
+    module: null;
+});
 export interface LoadGamepadBackendOptions {
     /**
      * Override the `gi://Manette` import. Tests only — the single seam that exercises the
@@ -33,19 +65,49 @@ export interface LoadGamepadBackendOptions {
     importer?: () => Promise<{
         default: typeof Manette;
     }>;
+    /** Override the darwin branch's `gi://GjsifyGamepad` import. Tests only. */
+    sdlImporter?: () => Promise<{
+        default: GjsifyGamepadNamespace;
+    }>;
+    /**
+     * Override the host OS the probe branches on. Tests only — it is how the darwin
+     * branch is exercised on a Linux runner and the Manette branch on a Mac.
+     */
+    hostOs?: () => TargetOs | undefined;
+    /** Override the environment read for {@link GAMEPAD_BACKEND_ENV}. Tests only. */
+    env?: (name: string) => string | undefined;
+}
+/**
+ * One `gi://` backend: its namespace, which every wording is scoped to, and its three
+ * texts. Exported (underscored) for `backend.spec.ts`.
+ */
+export interface _GiBackend {
+    status: 'manette' | 'sdl';
+    namespace: string;
+    /** No typelib for {@link namespace} on this host: what to install. */
+    noTypelibText: string;
+    /** No `@gjsify/node-gi` in a `--app node` process: what to install. */
+    noBridgeText: string;
+    /** The load is a fault: said at `error` level, next to the original error. */
+    loadFaultText: string;
 }
 /** Absent-vs-fault plus the text the use site should print (`null` = silence). */
 interface GiLoadDiagnosis {
     status: 'absent' | 'failed';
     diagnostic: string | null;
 }
+/** Both backends, for `backend.spec.ts`; the probe itself picks one by host OS. */
+export declare const _GI_BACKENDS: {
+    readonly manette: _GiBackend;
+    readonly sdl: _GiBackend;
+};
 /**
  * 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
+ * backend 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;
+export declare function _diagnoseGiLoadError(error: unknown, backend?: _GiBackend): GiLoadDiagnosis;
 /**
  * Resolve (once) which gamepad backend this host has. Emits NOTHING.
  *
@@ -68,13 +130,16 @@ export declare function loadGamepadBackend(options?: LoadGamepadBackendOptions):
  */
 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: 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.
+ * The backend loaded and then its device source 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.
+ *
+ * The advice comes from the SOURCE (`startRequirements`), because it is per backend:
+ * udev is the right hint for Manette and the wrong one for anything else.
  */
-export declare function reportGamepadMonitorFault(error: unknown): void;
+export declare function reportGamepadMonitorFault(error: unknown, source?: GamepadSource | null): void;
 /**
  * Whether this host has a gamepad backend at all.
  *
@@ -82,12 +147,17 @@ export declare function reportGamepadMonitorFault(error: unknown): void;
  * 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.
  *
- * `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}).
+ * `false` on Linux without libmanette (or, with `GJSIFY_GAMEPAD_BACKEND=sdl`, without the
+ * shim), and on macOS and Windows without the `@gjsify/gamepad-native` prebuild. 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>;
+/**
+ * Which backend this process drives, in words — for a debug panel or a bug report, not
+ * for branching (use {@link hasGamepadBackend} for that). Quiet like the capability query.
+ */
+export declare function describeGamepadBackend(): Promise<string>;
 /** Reset the cached probe and its one-time diagnostic — tests only. */
 export declare function _resetGamepadBackendCache(): void;
 export {};

package/lib/types/compare-source.d.ts

@@ -0,0 +1,31 @@
+import type { GamepadSource, GamepadSourceSink } from './source.js';
+/** Where a comparison is written. `console.warn` unless a test captures it. */
+export type CompareReport = (line: string) => void;
+/**
+ * The primary drives the page; the shadow is compared against it.
+ *
+ * Devices are paired by model, then by connection order ({@link pairUp}). A count
+ * mismatch is itself reported.
+ *
+ * A difference is reported when it has held for two consecutive polls, and again
+ * only when the set of differences changes. Manette pushes from the main loop while
+ * SDL is pulled at the poll, so for one frame after a change the two legitimately
+ * disagree; a comparison that reported that would bury the real findings.
+ */
+export declare class ComparingSource implements GamepadSource {
+    private readonly _primary;
+    private readonly _shadow;
+    private readonly _report;
+    readonly name: string;
+    readonly startRequirements?: string;
+    private _primarySink;
+    private _shadowSink;
+    private _shadowStarted;
+    private _pending;
+    private _reported;
+    constructor(_primary: GamepadSource, _shadow: GamepadSource, _report?: CompareReport);
+    start(sink: GamepadSourceSink): void;
+    poll(): void;
+    stop(): void;
+    private _compare;
+}

package/lib/types/compare-source.spec.d.ts

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

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

@@ -1,31 +1,41 @@
 import { Gamepad } from './gamepad.js';
+import type { GamepadSource } from './source.js';
+export interface GamepadManagerOptions {
+    /**
+     * Drive this source instead of probing the host's backend. For tests — it is how the
+     * manager is exercised with no controller and no typelib — and for an embedder that
+     * already owns an input stack.
+     */
+    source?: GamepadSource;
+}
 /**
- * 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.
+ * The W3C polling model over a {@link GamepadSource}: the source reports changes as they
+ * happen, this caches the latest state, and `getGamepads()` returns a snapshot.
  */
 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;
+    private readonly _injectedSource;
+    private _source;
+    /** Whether `_source.start()` RETURNED — a source whose start threw is never polled. */
+    private _started;
     private _initPromise;
     private _initialized;
-    /** Lazily initialize the `Manette.Monitor`, on the first `getGamepads()`. */
+    /** The one sink every source reports through. */
+    private readonly _sink;
+    constructor(options?: GamepadManagerOptions);
+    /** Lazily start the device source, on the first `getGamepads()`. */
     private _ensureInit;
     private _init;
     private _onDeviceConnected;
     private _onDeviceDisconnected;
-    private _onButtonPress;
-    private _onButtonRelease;
-    private _onAxisChange;
-    private _onHatChange;
-    private _findStateByDevice;
+    private _onButton;
+    private _onAxis;
+    private _findState;
     private _createSnapshot;
     /**
      * Returns a snapshot list matching the W3C `navigator.getGamepads()`
@@ -72,6 +82,6 @@ export declare class GamepadManager {
      * plus the one-time diagnostic this manager emits on its first init.
      */
     getGamepads(): (Gamepad | null)[];
-    /** Cleanup — disconnect all signal handlers. */
+    /** Stop the source and drop every index. */
     dispose(): void;
 }

package/lib/types/gamepad.d.ts

@@ -42,4 +42,8 @@ export interface GamepadEffectParameters {
     startDelay?: number;
     strongMagnitude?: number;
     weakMagnitude?: number;
+    /** `trigger-rumble` only: the left trigger's motor, 0..1. */
+    leftTrigger?: number;
+    /** `trigger-rumble` only: the right trigger's motor, 0..1. */
+    rightTrigger?: number;
 }

package/lib/types/haptic-actuator.d.ts

@@ -1,16 +1,67 @@
 import type Manette from '@girs/manette-0.2';
-import type { GamepadHapticActuator, GamepadHapticEffectType, GamepadEffectParameters, GamepadHapticsResult } from './gamepad.js';
+import type { GamepadEffectParameters, GamepadHapticActuator, GamepadHapticEffectType, GamepadHapticsResult } from './gamepad.js';
+import type { GjsifyGamepadDevice } from './sdl-namespace.js';
 /**
- * Wraps libmanette's rumble support as a W3C GamepadHapticActuator.
+ * The longest effect (`startDelay + duration`) accepted, in ms — the spec's recommended
+ * maximum, and what Chromium enforces. It is also below both backends' own cap (SDL:
+ * 0xFFFF ms; libmanette: a signed 16-bit ms count), so a valid effect is never cut short.
+ */
+export declare const MAX_HAPTIC_EFFECT_DURATION_MS = 5000;
+/** The motor intensities one effect asks for, each a uint16 both backends take. */
+interface HapticMotors {
+    strong: number;
+    weak: number;
+    leftTrigger: number;
+    rightTrigger: number;
+}
+/**
+ * The W3C `playEffect()` / `reset()` algorithm, shared by every device source so a page
+ * behaves the same whichever backend its host has. A subclass only says which effects its
+ * device has and how to start and stop the motors.
  *
- * libmanette supports dual-rumble with strong/weak magnitude control
- * via `Device.rumble(strong_magnitude, weak_magnitude, milliseconds)`.
- * Magnitudes are in the range 0–65535 (uint16).
+ * What the spec asks for, and why each step is here rather than left to the device:
+ * - parameters default to 0 (the IDL's defaults) and are validated first: a magnitude
+ *   outside 0..1 or an effect longer than {@link MAX_HAPTIC_EFFECT_DURATION_MS} rejects
+ *   with a `TypeError` instead of being clamped into something the page did not ask for;
+ * - an effect the device cannot play rejects with `NotSupportedError` — resolving it
+ *   `'complete'` would tell the page it rumbled when nothing moved;
+ * - the promise resolves when the effect has PLAYED (`startDelay + duration`), or
+ *   `'preempted'` when a later `playEffect()` / `reset()` interrupts it — which is how a
+ *   page sequences effects, and why resolving at once would break it.
  */
-export declare class ManetteHapticActuator implements GamepadHapticActuator {
-    readonly effects: readonly GamepadHapticEffectType[];
-    private _device;
-    constructor(device: Manette.Device);
+declare abstract class RumbleHapticActuator implements GamepadHapticActuator {
+    abstract readonly effects: readonly GamepadHapticEffectType[];
+    private _playing;
+    /** Start the motors for `durationMs`; the device stops them on its own afterwards. */
+    protected abstract _start(type: GamepadHapticEffectType, motors: HapticMotors, durationMs: number): void;
+    /** Stop every motor now. */
+    protected abstract _stop(): void;
     playEffect(type: GamepadHapticEffectType, params?: GamepadEffectParameters): Promise<GamepadHapticsResult>;
     reset(): Promise<GamepadHapticsResult>;
+    /** Stop the effect in flight, if any, and resolve its promise `'preempted'`. */
+    private _preempt;
+}
+/**
+ * libmanette's rumble as a W3C GamepadHapticActuator: `dual-rumble` only, via
+ * `Device.rumble(strong_magnitude, weak_magnitude, milliseconds)`.
+ */
+export declare class ManetteHapticActuator extends RumbleHapticActuator {
+    private readonly _device;
+    readonly effects: readonly GamepadHapticEffectType[];
+    constructor(_device: Manette.Device);
+    protected _start(_type: GamepadHapticEffectType, motors: HapticMotors, durationMs: number): void;
+    protected _stop(): void;
+}
+/**
+ * The SDL3 shim's rumble as a W3C GamepadHapticActuator: `dual-rumble` drives the two
+ * body motors; `trigger-rumble` drives the impulse triggers (Xbox One/Series controllers)
+ * AND the body motors, since its parameters carry both.
+ */
+export declare class SdlHapticActuator extends RumbleHapticActuator {
+    private readonly _device;
+    readonly effects: readonly GamepadHapticEffectType[];
+    constructor(_device: GjsifyGamepadDevice);
+    protected _start(type: GamepadHapticEffectType, motors: HapticMotors, durationMs: number): void;
+    protected _stop(): void;
 }
+export {};

package/lib/types/hardware-check.d.mts

@@ -0,0 +1 @@
+export {};

package/lib/types/index.d.ts

@@ -4,8 +4,10 @@ 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 type { GamepadManagerOptions } from './gamepad-manager.js';
+export type { GamepadSource, GamepadSourceDevice, GamepadSourceSink } from './source.js';
+export { describeGamepadBackend, hasGamepadBackend } from './backend.js';
+export type { GamepadBackendChoice, 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/manette-source.d.ts

@@ -0,0 +1,19 @@
+import type Manette from '@girs/manette-0.2';
+import { type GamepadSource, type GamepadSourceSink } from './source.js';
+/** `Manette.Monitor` as a {@link GamepadSource}. Push model: no `poll()`. */
+export declare class ManetteSource implements GamepadSource {
+    private readonly _Manette;
+    readonly name = "gi://Manette";
+    readonly startRequirements = "Manette.Monitor needs udev and /dev/input access, which a sandbox can withhold (flatpak: --device=input).";
+    private _monitor;
+    private _monitorSignalIds;
+    private readonly _devices;
+    constructor(_Manette: typeof Manette);
+    start(sink: GamepadSourceSink): void;
+    stop(): void;
+    private _add;
+    private _remove;
+    private _onButton;
+    private _onAxis;
+    private _onHat;
+}

package/lib/types/register.d.ts

@@ -1 +1 @@
-export {};
+import '@gjsify/node-globals/register/navigator';

package/lib/types/sdl-namespace.d.ts

@@ -0,0 +1,28 @@
+/** One controller: `GjsifyGamepad.Device`. */
+export interface GjsifyGamepadDevice {
+    get_name(): string;
+    /** SDL's 32-hex-digit GUID; carries the USB vendor and product. */
+    get_guid(): string;
+    /** W3C standard buttons 0–16, 0..1 (the triggers 6/7 analog, the rest 0 or 1). */
+    get_buttons(): number[];
+    /** W3C standard axes 0–3, -1..1. */
+    get_axes(): number[];
+    has_rumble(): boolean;
+    has_trigger_rumble(): boolean;
+    rumble(lowFrequency: number, highFrequency: number, durationMs: number): boolean;
+    rumble_triggers(left: number, right: number, durationMs: number): boolean;
+}
+/** `GjsifyGamepad.Monitor` — the subset the source uses. */
+export interface GjsifyGamepadMonitor {
+    update(): void;
+    close(): void;
+    connect(signal: 'device-added' | 'device-removed', callback: (monitor: GjsifyGamepadMonitor, device: GjsifyGamepadDevice) => void): number;
+    disconnect(id: number): void;
+}
+/** The `gi://GjsifyGamepad` namespace — the subset the source uses. */
+export interface GjsifyGamepadNamespace {
+    /** A GI class: the probe checks `typeof Monitor === 'function'`. */
+    Monitor: {
+        new: () => GjsifyGamepadMonitor;
+    };
+}

package/lib/types/sdl-node-gi.spec.d.ts

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

package/lib/types/sdl-source.d.ts

@@ -0,0 +1,29 @@
+import type { GjsifyGamepadNamespace } from './sdl-namespace.js';
+import { type GamepadSource, type GamepadSourceSink } from './source.js';
+/**
+ * `GjsifyGamepad.Monitor` as a {@link GamepadSource}. Pull model: `poll()` pumps SDL and
+ * forwards the changed values, at exactly the W3C polling moment. Hotplug is also pushed
+ * between polls, by the monitor's own GLib timeout, so `gamepadconnected` reaches a page
+ * that has not polled yet.
+ */
+export declare class SdlSource implements GamepadSource {
+    private readonly _GjsifyGamepad;
+    readonly name = "gi://GjsifyGamepad";
+    readonly startRequirements = "SDL's gamepad subsystem has to start in this process; the error carries SDL's own reason.";
+    private _monitor;
+    private _sink;
+    private _signalIds;
+    private readonly _devices;
+    constructor(_GjsifyGamepad: GjsifyGamepadNamespace);
+    start(sink: GamepadSourceSink): void;
+    poll(): void;
+    stop(): void;
+    private _add;
+    private _remove;
+    /**
+     * Forward the values that changed since the sink last heard. Unchanged values are
+     * not re-sent because every sink call stamps `Gamepad.timestamp`, which the W3C
+     * spec advances only when the device reported new data.
+     */
+    private _report;
+}

package/lib/types/sdl-source.spec.d.ts

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

package/lib/types/source.d.ts

@@ -0,0 +1,71 @@
+import type { GamepadHapticActuator } from './gamepad.js';
+/**
+ * `vvvv:pppp` from an SDL-style joystick GUID (libmanette and SDL both use that layout:
+ * little-endian 16-bit bus, CRC, vendor, 0, product, …), or `undefined` when the GUID
+ * carries no vendor (SDL then stores a name hash there instead).
+ */
+export declare function modelFromGuid(guid: string | null | undefined): string | undefined;
+/**
+ * One physical device, as a source reports it. The OBJECT is the identity: the manager
+ * keys its slot on it, so a source must hand the same object to every call about the
+ * same device.
+ */
+export interface GamepadSourceDevice {
+    /** Becomes `Gamepad.id`. */
+    readonly id: string;
+    /** Becomes `Gamepad.vibrationActuator`; `null` when the source cannot drive one. */
+    readonly vibrationActuator: GamepadHapticActuator | null;
+    /**
+     * The controller MODEL as `vvvv:pppp` (USB vendor and product, hex), read from the
+     * SDL-style GUID both libmanette and SDL report. Optional: only `ComparingSource`
+     * reads it, to pair one controller across two backends that name it differently.
+     */
+    readonly model?: string;
+}
+/**
+ * Where a source reports to, in the W3C STANDARD mapping's vocabulary
+ * (https://w3c.github.io/gamepad/#remapping): `index` is a standard button or axis
+ * index, not a platform code. Calls about a device that is not connected, or with an
+ * index outside the standard layout, are ignored — a source may forward what it does not
+ * recognise without a guard of its own.
+ */
+export interface GamepadSourceSink {
+    /** A device became available — selects an index for it and fires `gamepadconnected`. */
+    connected(device: GamepadSourceDevice): void;
+    /** The device went away — frees its index and fires `gamepaddisconnected`. */
+    disconnected(device: GamepadSourceDevice): void;
+    /**
+     * A button's state. `value` is 0..1; `pressed` is passed explicitly because only the
+     * source knows whether the control is digital (pressed ⇔ value 1) or analog, where
+     * the threshold is its call.
+     */
+    button(device: GamepadSourceDevice, index: number, value: number, pressed: boolean): void;
+    /** A stick axis, -1..1. Analog triggers are BUTTONS 6/7 in the standard layout. */
+    axis(device: GamepadSourceDevice, index: number, value: number): void;
+}
+/** A platform's gamepad subsystem, behind the one contract the manager drives. */
+export interface GamepadSource {
+    /** Names the backend in diagnostics, e.g. `gi://Manette`. */
+    readonly name: string;
+    /**
+     * One sentence on what this backend needs to start, appended to the report when
+     * {@link start} throws. That report must not guess: udev advice for a darwin backend
+     * would be wrong advice.
+     */
+    readonly startRequirements?: string;
+    /**
+     * Begin reporting to `sink`. Devices that are already present are reported as
+     * `connected` too. May throw — the manager reports that as a monitor fault, distinct
+     * from a backend that failed to load. Called again after {@link stop} when a disposed
+     * manager is used again.
+     */
+    start(sink: GamepadSourceSink): void;
+    /**
+     * Refresh device state. A PULL backend (SDL is polled) implements it; the manager
+     * calls it at the top of every `getGamepads()`, which is exactly the W3C polling
+     * moment. A PUSH backend (Manette emits signals) omits it.
+     */
+    poll?(): void;
+    /** Stop reporting and release every native handle. Must be safe after a failed start. */
+    stop(): void;
+}

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

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

package/lib/types/test.browser.d.mts

@@ -0,0 +1 @@
+export {};

package/lib/types/test.node-gi.d.mts

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "@gjsify/gamepad",
-    "version": "0.52.0",
-    "description": "Gamepad Web API for GJS using libmanette as backend",
+    "version": "0.54.0",
+    "description": "Gamepad Web API for GJS: SDL3 (via @gjsify/gamepad-native) on macOS and Windows, libmanette on Linux until SDL is proven there",
     "type": "module",
     "module": "lib/esm/index.js",
     "types": "lib/types/index.d.ts",
@@ -25,35 +25,44 @@
         "./globals.mjs"
     ],
     "scripts": {
-        "clear": "gjsify clear lib tsconfig.tsbuildinfo tsconfig.types.tsbuildinfo test.gjs.mjs",
+        "clear": "gjsify clear lib tsconfig.tsbuildinfo tsconfig.types.tsbuildinfo test.gjs.mjs test.hardware-check.gjs.mjs",
         "check": "gjsify tsc --noEmit",
         "build": "gjsify run build:gjsify && gjsify run build:types",
-        "build:gjsify": "gjsify build --library 'src/**/*.{ts,js}' --exclude 'src/**/*.spec.{mts,ts}' 'src/test.{mts,ts}'",
+        "build:gjsify": "gjsify build --library 'src/**/*.{ts,js}' --exclude 'src/**/*.spec.{mts,ts}' 'src/test*.{mts,ts}'",
         "build:types": "gjsify tsc",
         "build:test": "gjsify run build:test:gjs",
         "build:test:gjs": "gjsify build src/test.mts --app gjs --outfile test.gjs.mjs",
         "build:test:browser": "gjsify build src/test.browser.mts --app browser --outfile dist/test.browser.mjs",
         "test": "gjsify run build:gjsify && gjsify run build:test && gjsify run test:gjs",
-        "test:gjs": "gjsify run test.gjs.mjs"
+        "test:gjs": "gjsify run test.gjs.mjs",
+        "hardware-check": "gjsify build src/hardware-check.mts --app gjs --outfile test.hardware-check.gjs.mjs && gjsify run test.hardware-check.gjs.mjs",
+        "test:gjs-on-node": "gjsify build src/test.node-gi.mts --app node --outfile dist/test.node-gi.mjs && node dist/test.node-gi.mjs"
     },
     "keywords": [
         "gjs",
         "gamepad",
         "libmanette",
+        "sdl3",
         "controller"
     ],
     "dependencies": {
-        "@gjsify/dom-events": "^0.52.0"
+        "@gjsify/dom-events": "^0.54.0",
+        "@gjsify/node-globals": "^0.54.0",
+        "@gjsify/utils": "^0.54.0"
     },
     "devDependencies": {
         "@girs/gjs": "5.4.0",
         "@girs/glib-2.0": "5.4.0",
         "@girs/manette-0.2": "5.4.0",
-        "@gjsify/cli": "^0.52.0",
-        "@gjsify/unit": "^0.52.0",
+        "@gjsify/cli": "^0.54.0",
+        "@gjsify/node-gi": "file:../../../packages/node-gi/node-gi",
+        "@gjsify/unit": "^0.54.0",
         "@types/node": "^25.9.2",
         "typescript": "^6.0.3"
     },
+    "optionalDependencies": {
+        "@gjsify/gamepad-native": "^0.54.0"
+    },
     "gjsify": {
         "runtimes": {
             "gjs": "polyfill",
@@ -61,6 +70,15 @@
             "browser": "native",
             "nativescript": "native"
         },
+        "os": {
+            "linux": "supported",
+            "darwin": "partial",
+            "win32": "partial"
+        },
+        "osNotes": {
+            "darwin": "The backend is SDL3 behind a GObject shim (@gjsify/gamepad-native, ADR 0075). It builds, loads and enumerates on macOS, but input from a real controller has not been verified yet, and its darwin prebuilds are not published yet. Without the prebuild, getGamepads() answers the conformant empty list and hasGamepadBackend() reports false.",
+            "win32": "The backend is the SDL3 shim (@gjsify/gamepad-native-win32-x64, ADR 0075 Amendment 1), reached from Node through @gjsify/node-gi since Windows has no GJS. It builds, loads and enumerates in CI, and a virtual XInput pad is read there, but input from a real controller has not been verified yet and the win32 prebuild is not published yet. Without it, getGamepads() answers the conformant empty list and hasGamepadBackend() reports false."
+        },
         "tier": 1
     },
     "license": "MIT",