@forgeax/engine-input 0.1.2

package/dist/browser-backend.d.ts

@@ -0,0 +1,121 @@
+import type { InputBackend, PointerType, VirtualJoystickConfig } from './input-snapshot';
+export declare function coercePointerType(raw: string): PointerType;
+/**
+ * Options accepted by `attachBrowserInputBackend`.
+ */
+export interface BrowserInputBackendOptions {
+    /** Optional host-owned UI root. Events in this root never reach gameplay. */
+    readonly uiRoot?: Node;
+    /**
+     * Optional document handle (testing override). Defaults to `document`.
+     * Plan-strategy section 9 row 7 (`document.hasFocus()` semantics)
+     * relies on this to decide whether the up-edge set should be cleared
+     * when focus is lost.
+     */
+    readonly document?: Document;
+    /**
+     * Optional window handle (testing override). Defaults to `window`.
+     * Used to attach key listeners (capturing focus loss) without
+     * requiring the canvas itself to receive keyboard events.
+     */
+    readonly window?: Window;
+    /**
+     * Neutral gate for the auto PointerLock-on-click. When provided and it
+     * returns false, the click handler skips `requestPointerLock()` — the host
+     * decides whether a click should capture the cursor right now. Defaults to
+     * always-locking (returns true), so the standalone game runtime keeps its
+     * MVP behaviour unchanged. This predicate is deliberately host-opaque: the
+     * backend never learns WHY locking is (dis)allowed — it only asks. A host
+     * that mounts this canvas in a non-game context (e.g. an editor viewport
+     * that owns the cursor for orbit/pick) supplies a predicate that returns
+     * false there. The input package carries zero knowledge of those contexts.
+     */
+    readonly pointerLockAllowed?: () => boolean;
+    /**
+     * Optional navigator handle (testing override). Defaults to
+     * `globalThis.navigator`. Used to poll `navigator.getGamepads()` each
+     * frame. Mirrors the `document`/`window` override pattern.
+     */
+    readonly navigator?: {
+        getGamepads?(): (Gamepad | null)[];
+    };
+    /**
+     * Optional virtual joystick configurations (M3). When provided, the
+     * backend auto-binds the first pointerdown within each config's region
+     * and derives per-frame VirtualAxisSample outputs via deriveVirtualAxes.
+     */
+    readonly virtualJoysticks?: readonly VirtualJoystickConfig[];
+    /**
+     * Optional SDL controller DB text loader (M3 D-13 test injection). When
+     * omitted, the backend dynamic-imports the vendored 554KB DB from
+     * `@forgeax/engine-input/controller-db-data` on first sight of a
+     * non-standard gamepad (D-2 lazy-load: the 554KB never sits in the
+     * default path). Tests inject a synthetic DB string to avoid loading the
+     * real vendored file. Returns the raw gamecontrollerdb.txt contents.
+     */
+    readonly loadControllerDb?: () => Promise<string>;
+    /**
+     * Optional monotonic clock (M5 D-3 test injection). Defaults to
+     * `() => performance.now()`. The gesture recognizer advances all timers
+     * (long-press duration, double-tap / swipe windows) off this clock, NOT
+     * off pointer-event arrival, so recognition stays decoupled from event
+     * frequency (AC-16). Tests inject a fake clock for deterministic timing,
+     * mirroring the `document` / `window` / `navigator` override pattern.
+     */
+    readonly now?: () => number;
+    /**
+     * Optional lock provider (D-2). When provided, pointer-lock requests
+     * route through requestLock() / exitLock() instead of the W3C
+     * requestPointerLock / exitPointerLock API. The backend remains
+     * host-opaque -- it never learns whether the provider wraps Tauri
+     * native-grab, postMessage, or any other mechanism.
+     */
+    readonly lockProvider?: PointerLockProvider;
+    /**
+     * Optional callback for lock request failures (D-4). When W3C
+     * requestPointerLock rejects or lockProvider.requestLock/exitLock
+     * throws/rejects, the backend calls this with a detail object.
+     * Without this callback, failures are silently caught (backward
+     * compatible but contrary to charter P3).
+     */
+    readonly onLockError?: (detail: {
+        path: 'w3c' | 'provider';
+        cause: unknown;
+    }) => void;
+}
+/**
+ * Lock provider interface (D-2). A host injects this to replace the
+ * W3C Pointer Lock API path. requestLock() may return void (fire-and-forget,
+ * D-7 optimistic placement) or Promise<void> (awaitable). exitLock() is
+ * called when the backend needs to release the lock (ESC / blur / detach /
+ * setPointerLockAllowed(false)).
+ */
+export interface PointerLockProvider {
+    /**
+     * Request pointer lock. The backend optimistically sets providerLocked=true
+     * when this is called (D-7). On throw/reject, the backend calls onLockError
+     * and rolls back providerLocked.
+     */
+    requestLock(): void | Promise<void>;
+    /** Release pointer lock. */
+    exitLock(): void;
+}
+/**
+ * Attach DOM listeners (keydown / keyup / mousedown / mouseup /
+ * pointerlockchange / mousemove inside lock / blur) to `canvas` and the
+ * surrounding window. Returns a `detach` callable that:
+ *
+ *   - removes all listeners
+ *   - exits PointerLock if currently locked
+ *   - drops every internal accumulator
+ *
+ * The returned object also implements the `InputBackend` protocol -- the
+ * runtime inserts it under `INPUT_BACKEND_KEY` and adds the
+ * `InputFrameStartScan` system, which reads it back each tick.
+ * Calling `detach()` and the protocol's `detach()` are equivalent
+ * (idempotent; double-detach is safe -- charter P3).
+ */
+export declare function attachBrowserInputBackend(canvas: HTMLCanvasElement, options?: BrowserInputBackendOptions): (() => void) & {
+    backend: InputBackend;
+};
+//# sourceMappingURL=browser-backend.d.ts.map

package/dist/browser-backend.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser-backend.d.ts","sourceRoot":"","sources":["../src/browser-backend.ts"],"names":[],"mappings":"AA+BA,OAAO,KAAK,EAGV,YAAY,EAIZ,WAAW,EAEX,qBAAqB,EACtB,MAAM,kBAAkB,CAAC;AAQ1B,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,WAAW,CAI1D;AAED;;GAEG;AACH,MAAM,WAAW,0BAA0B;IACzC,6EAA6E;IAC7E,QAAQ,CAAC,MAAM,CAAC,EAAE,IAAI,CAAC;IACvB;;;;;OAKG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,QAAQ,CAAC;IAC7B;;;;OAIG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB;;;;;;;;;;OAUG;IACH,QAAQ,CAAC,kBAAkB,CAAC,EAAE,MAAM,OAAO,CAAC;IAC5C;;;;OAIG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE;QAAE,WAAW,CAAC,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC,EAAE,CAAA;KAAE,CAAC;IAC5D;;;;OAIG;IACH,QAAQ,CAAC,gBAAgB,CAAC,EAAE,SAAS,qBAAqB,EAAE,CAAC;IAC7D;;;;;;;OAOG;IACH,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,OAAO,CAAC,MAAM,CAAC,CAAC;IAClD;;;;;;;OAOG;IACH,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;IAC5B;;;;;;OAMG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,mBAAmB,CAAC;IAC5C;;;;;;OAMG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,CAAC,MAAM,EAAE;QAAE,IAAI,EAAE,KAAK,GAAG,UAAU,CAAC;QAAC,KAAK,EAAE,OAAO,CAAA;KAAE,KAAK,IAAI,CAAC;CACvF;AAED;;;;;;GAMG;AACH,MAAM,WAAW,mBAAmB;IAClC;;;;OAIG;IACH,WAAW,IAAI,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACpC,4BAA4B;IAC5B,QAAQ,IAAI,IAAI,CAAC;CAClB;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,yBAAyB,CACvC,MAAM,EAAE,iBAAiB,EACzB,OAAO,GAAE,0BAA+B,GACvC,CAAC,MAAM,IAAI,CAAC,GAAG;IAAE,OAAO,EAAE,YAAY,CAAA;CAAE,CAysB1C"}

package/dist/canvas-input-boundary.d.ts

@@ -0,0 +1,13 @@
+import { type InputBackend } from './input-snapshot';
+export interface CanvasInputBoundary {
+    readonly editor: InputBackend;
+    readonly game: InputBackend;
+    owner(): 'editor' | 'game';
+    grantGame(): void;
+    revokeGame(): void;
+    /** Clear the active consumer when an event originated in the host UI. */
+    handleUiEvent(event: Event, host: Node): boolean;
+    detach(): void;
+}
+export declare function createCanvasInputBoundary(source: InputBackend): CanvasInputBoundary;
+//# sourceMappingURL=canvas-input-boundary.d.ts.map

package/dist/canvas-input-boundary.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"canvas-input-boundary.d.ts","sourceRoot":"","sources":["../src/canvas-input-boundary.ts"],"names":[],"mappings":"AAOA,OAAO,EAEL,KAAK,YAAY,EAElB,MAAM,kBAAkB,CAAC;AAG1B,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,MAAM,EAAE,YAAY,CAAC;IAC9B,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAC;IAC5B,KAAK,IAAI,QAAQ,GAAG,MAAM,CAAC;IAC3B,SAAS,IAAI,IAAI,CAAC;IAClB,UAAU,IAAI,IAAI,CAAC;IACnB,yEAAyE;IACzE,aAAa,CAAC,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,IAAI,GAAG,OAAO,CAAC;IACjD,MAAM,IAAI,IAAI,CAAC;CAChB;AAID,wBAAgB,yBAAyB,CAAC,MAAM,EAAE,YAAY,GAAG,mBAAmB,CAqDnF"}

package/dist/composite-backend.d.ts

@@ -0,0 +1,34 @@
+import type { InputBackend } from './input-snapshot';
+/** Options controlling the composite merge policy. */
+export interface CompositeBackendOptions {
+    /**
+     * When `true` (default), a key held on the inner (human) backend suppresses
+     * injected state only for that same key in that frame. Set `false` for
+     * record/replay or AI-solo scenarios where both sources should coexist even
+     * on key overlap.
+     */
+    readonly yieldToHuman?: boolean;
+}
+/**
+ * A composite backend: an `InputBackend` (drop-in for `INPUT_BACKEND_KEY`) plus
+ * a programmatic injection surface. All injection is additive over the wrapped
+ * human backend.
+ */
+export interface CompositeInputBackend extends InputBackend {
+    /** Hold `key` down (mirrors a keydown). Idempotent. */
+    press(key: string): void;
+    /** Release `key` (mirrors a keyup); emits a one-frame up-edge on next sample. */
+    release(key: string): void;
+    /** Set an injected mouse-button slot (0/1/2) held-state. */
+    setButton(slot: 0 | 1 | 2, down: boolean): void;
+    /** Accumulate injected pointer-lock movement delta (drained on next sample). */
+    addMovement(dx: number, dy: number): void;
+    /** Accumulate injected wheel notches (drained on next sample). */
+    addWheel(notches: number): void;
+    /** Drop all injected state; currently-held keys emit a clean up-edge once. */
+    clearInjected(): void;
+    /** Toggle the yield-to-human gate at runtime. */
+    setYieldToHuman(yield_: boolean): void;
+}
+export declare function makeCompositeBackend(inner: InputBackend, options?: CompositeBackendOptions): CompositeInputBackend;
+//# sourceMappingURL=composite-backend.d.ts.map

package/dist/composite-backend.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"composite-backend.d.ts","sourceRoot":"","sources":["../src/composite-backend.ts"],"names":[],"mappings":"AAgCA,OAAO,KAAK,EAAE,YAAY,EAAsB,MAAM,kBAAkB,CAAC;AAEzE,sDAAsD;AACtD,MAAM,WAAW,uBAAuB;IACtC;;;;;OAKG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,OAAO,CAAC;CACjC;AAED;;;;GAIG;AACH,MAAM,WAAW,qBAAsB,SAAQ,YAAY;IACzD,uDAAuD;IACvD,KAAK,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,iFAAiF;IACjF,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,4DAA4D;IAC5D,SAAS,CAAC,IAAI,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,IAAI,EAAE,OAAO,GAAG,IAAI,CAAC;IAChD,gFAAgF;IAChF,WAAW,CAAC,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1C,kEAAkE;IAClE,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,8EAA8E;IAC9E,aAAa,IAAI,IAAI,CAAC;IACtB,iDAAiD;IACjD,eAAe,CAAC,MAAM,EAAE,OAAO,GAAG,IAAI,CAAC;CACxC;AAED,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,YAAY,EACnB,OAAO,CAAC,EAAE,uBAAuB,GAChC,qBAAqB,CAsHvB"}

package/dist/controller-db-data.d.ts

@@ -0,0 +1,5 @@
+/** The vendored gamecontrollerdb.txt contents, inlined at build time. */
+export declare const BUNDLED_CONTROLLER_DB: string;
+/** Default loader used by the backend when no override is supplied (D-13). */
+export declare function loadBundledControllerDb(): Promise<string>;
+//# sourceMappingURL=controller-db-data.d.ts.map

package/dist/controller-db-data.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"controller-db-data.d.ts","sourceRoot":"","sources":["../src/controller-db-data.ts"],"names":[],"mappings":"AAkBA,yEAAyE;AACzE,eAAO,MAAM,qBAAqB,EAAE,MAAsC,CAAC;AAE3E,8EAA8E;AAC9E,wBAAgB,uBAAuB,IAAI,OAAO,CAAC,MAAM,CAAC,CAEzD"}