@forgeax/engine-input 0.1.2

package/dist/input-snapshot.d.ts

@@ -0,0 +1,420 @@
+import type { ActionConfig, ActionState, GetVectorOptions } from './action-state';
+import type { GestureEvent, GestureState } from './gesture-recognizer';
+export type PointerType = 'mouse' | 'pen' | 'touch';
+/** Standard-layout gamepad button index (0-16 per W3C Gamepad spec). */
+export type GamepadButtonIndex = 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13 | 14 | 15 | 16;
+/** Standard-layout gamepad axis index (0-3 per W3C Gamepad spec). */
+export type GamepadAxisIndex = 0 | 1 | 2 | 3;
+/** W3C MouseEvent.button index (0=primary, 1=auxiliary, 2=secondary). */
+export type MouseButtonIndex = 0 | 1 | 2;
+/** Per-slot gamepad frame data produced by `sample()`. */
+export interface GamepadSlotSample {
+    readonly index: number;
+    /**
+     * True when the browser reports a standard mapping OR the SDL controller
+     * DB has normalized a non-standard layout at the acquisition layer (M3
+     * D-1 redefinition). The Feat1 meaning ("browser-reported standard
+     * mapping only") is widened here: a non-standard pad whose GUID matches
+     * gamecontrollerdb.txt is re-projected onto the standard layout and
+     * reported as standardMapping=true, so bindings and direct reads see a
+     * uniform standard button/axis space. A non-standard pad with no DB match
+     * (or before the DB has loaded) keeps standardMapping=false + empty
+     * readpoints (graceful degradation).
+     */
+    readonly standardMapping: boolean;
+    readonly pressed: ReadonlySet<number>;
+    readonly justPressed: ReadonlySet<number>;
+    readonly justReleased: ReadonlySet<number>;
+    readonly buttonValues: ReadonlyMap<number, number>;
+    readonly axes: readonly [number, number, number, number];
+}
+/** Per-pointer live state (active contacts tracked by pointerId).
+ *
+ * D-5 / E-10: `pointerType` is a 3-literal union. `'mouse'` is the default
+ * placeholder for inactive pointers — when `active=false`, `pointerType` is
+ * always `'mouse'`. The semantic "no pointer" is carried by the `active`
+ * field, never by a sentinel string value.
+ */
+export interface PointerSample {
+    readonly pointerId: number;
+    readonly x: number;
+    readonly y: number;
+    readonly pressure: number;
+    readonly pointerType: PointerType;
+    readonly active: boolean;
+    readonly delta: {
+        readonly x: number;
+        readonly y: number;
+    };
+}
+/** Per-frame phase event (down/move/up/cancel queue, one-frame lifecycle). */
+export interface PointerPhaseEvent {
+    readonly pointerId: number;
+    readonly phase: 'down' | 'move' | 'up' | 'cancel';
+    readonly x: number;
+    readonly y: number;
+    readonly pressure: number;
+    readonly pointerType: PointerType;
+}
+/** Per-frame virtual axis output (named joystick derived from pointer input). */
+export interface VirtualAxisSample {
+    readonly name: string;
+    readonly x: number;
+    readonly y: number;
+}
+/**
+ * Configuration for an on-screen virtual joystick (M3). Consumed by
+ * attachBrowserInputBackend and passed through to deriveVirtualAxes.
+ *
+ * Fixed mode: origin is config.anchor (or region center if anchor omitted).
+ * Floating mode: origin is the first pointerdown position within the region.
+ */
+export interface VirtualJoystickConfig {
+    readonly name: string;
+    readonly mode: 'fixed' | 'floating';
+    /** Canvas-pixel region where touches are eligible to bind this joystick. */
+    readonly region: {
+        readonly x: number;
+        readonly y: number;
+        readonly width: number;
+        readonly height: number;
+    };
+    /** Fixed-mode origin anchor. Defaults to region center when omitted. */
+    readonly anchor?: {
+        readonly x: number;
+        readonly y: number;
+    } | undefined;
+    /** Max drag radius in canvas pixels. Vector is clamped then normalized to radius. */
+    readonly radius: number;
+    /** Normalized deadzone (0..1). |vec| < deadzone → zero vector output. */
+    readonly deadzone: number;
+}
+/** Capability snapshot (frozen at backend attach time). */
+export interface Capabilities {
+    readonly gamepad: boolean;
+    readonly pointer: boolean;
+}
+/**
+ * Frozen value-shape view exposed to user systems via the `InputSnapshot`
+ * Resource. The methods are pure reads; calling them does not mutate any
+ * accumulator (charter P3 -- no observable side effects from the accessor
+ * surface). A fresh `InputSnapshot` instance is constructed by the
+ * frame-start scan system once per `world.update()` and replaces the
+ * previous Resource value.
+ */
+export interface InputSnapshot {
+    /** Keyboard view (held state plus frame edges). */
+    readonly keyboard: {
+        /**
+         * `true` while `key` is currently held. `key` matches the value the
+         * backend records (KeyboardEvent.key for the browser backend). When
+         * the key is not in the held set, returns `false` -- never throws
+         * (charter P3: empty signal is the signal).
+         */
+        down(key: string): boolean;
+        /** `true` for the first frame in which `key` becomes held. */
+        justPressed(key: string): boolean;
+        /**
+         * `true` for one frame after the key was released (the up-edge). The
+         * edge collapses on the following `world.update()`. `key` not in the
+         * up-edge set returns `false`.
+         */
+        up(key: string): boolean;
+        /** Code-key equivalent of `down`, using KeyboardEvent.code identity. */
+        downCode(code: string): boolean;
+        /** Code-key equivalent of `justPressed`. */
+        justPressedCode(code: string): boolean;
+        /** Code-key equivalent of `up`. */
+        upCode(code: string): boolean;
+    };
+    /** Mouse view (charter F2 minimal surface: position + movementDelta + button + wheelDelta). */
+    readonly mouse: {
+        /**
+         * Latest canvas-pixel cursor position. This is available during hover;
+         * it does not require a button press or pointer capture. The position is
+         * frozen with the rest of the frame-start snapshot.
+         */
+        readonly position: {
+            readonly x: number;
+            readonly y: number;
+        } | undefined;
+        /**
+         * PointerLock-style accumulated movement since the previous frame.
+         * Value is frozen at frame-start; reading it does not clear the
+         * accumulator. The next `world.update()` produces a fresh delta
+         * (zero if no movement events arrived).
+         */
+        readonly movementDelta: {
+            readonly x: number;
+            readonly y: number;
+        };
+        /**
+         * Merged pointer-lock state: true when either W3C pointer-lock
+         * (pointerLockElement === this backend's canvas) OR the lockProvider
+         * path has engaged. Consumers read this to decide whether to consume
+         * movementDelta for look/camera rotation. Required field, alongside
+         * movementDelta -- both facts sit at the same attribute path for
+         * single-point indexing (charter F1).
+         */
+        readonly pointerLocked: boolean;
+        /**
+         * `true` while the W3C MouseEvent.button slot `i` is held. `i` is
+         * narrowed to the literal `0 | 1 | 2` so out-of-range indices are
+         * rejected at compile time (charter P3 explicit failure: TS literal
+         * narrowing replaces a runtime bounds-clamp).
+         *
+         * - 0 -- primary button (left)
+         * - 1 -- auxiliary button (middle)
+         * - 2 -- secondary button (right)
+         */
+        button(i: MouseButtonIndex): boolean;
+        /** `true` for the first frame in which button `i` becomes held. */
+        justPressed(i: MouseButtonIndex): boolean;
+        /** `true` for the frame in which button `i` is released. */
+        justReleased(i: MouseButtonIndex): boolean;
+        /**
+         * Discrete wheel notches accumulated since the previous frame.
+         * Plan-strategy D-5 sign-discrete: each `WheelEvent` contributes
+         * `Math.sign(event.deltaY)` to the per-frame accumulator regardless
+         * of `deltaMode` (PIXEL / LINE / PAGE all collapse). Sign convention
+         * follows W3C `WheelEvent.deltaY`: positive = scroll down / away
+         * from user, negative = scroll up / toward user.
+         *
+         * Value is frozen at frame-start; reading it does not clear the
+         * accumulator. The next `world.update()` produces a fresh delta
+         * (zero when no wheel events arrived).
+         *
+         * Trade-off (plan-strategy R-7): trackpad high-resolution wheel
+         * events collapse to one notch per event, losing sub-notch fidelity.
+         * AI users who need analog magnitude must opt in via a future
+         * unitful surface (OOS-7 ScrollSnapshot is the deferred shape).
+         */
+        readonly wheelDelta: number;
+    };
+    /**
+     * Per-slot gamepad reader. Returns a reader object for the gamepad at
+     * slot `i` regardless of connection state: disconnected or out-of-range
+     * slots report `connected=false`, all button/axis readpoints return
+     * `false`/`0` (charter P3 empty signal). The slot index is intentionally
+     * not narrowed — platform slot counts vary, and bounds handling is a
+     * runtime concern.
+     */
+    gamepad(i: number): {
+        readonly connected: boolean;
+        readonly standardMapping: boolean;
+        button(b: GamepadButtonIndex): boolean;
+        buttonValue(b: GamepadButtonIndex): number;
+        justPressed(b: GamepadButtonIndex): boolean;
+        justReleased(b: GamepadButtonIndex): boolean;
+        axis(a: GamepadAxisIndex): number;
+    };
+    /**
+     * Frozen capabilities snapshot, determined once at backend attach time.
+     * Consumers use this to decide whether gamepad/pointer readpoints will
+     * ever carry live data, without probing per-frame.
+     */
+    readonly capabilities: Capabilities;
+    /**
+     * Per-pointerId reader. Returns `{ active: true/false, x, y, pressure,
+     * pointerType, delta }` for the given pointerId. Unknown pointerIds
+     * return `{ active: false, ... }` without throwing.
+     */
+    pointer(id: number): PointerSample & {
+        readonly delta: {
+            readonly x: number;
+            readonly y: number;
+        };
+    };
+    /**
+     * Named virtual axis reader (joystick-derived). Returns `{ x, y }` for
+     * the given joystick config name. Unknown names return the zero-vector
+     * `{ x: 0, y: 0 }` without throwing.
+     */
+    virtualAxis(name: string): {
+        readonly x: number;
+        readonly y: number;
+    };
+    /**
+     * Per-frame phase event queue (down/move/up/cancel). One-frame
+     * lifecycle; drained by `sample()` at frame end. Empty array when no
+     * pointer events occurred this frame.
+     */
+    readonly pointerEvents: readonly PointerPhaseEvent[];
+    /**
+     * Continuous gesture values (pinch scale + rotation angle) for the
+     * active dual-finger gesture. Returns the identity empty signal
+     * (`pinchScale=1`, `rotationAngle=0`) when no gesture is active (AC-12);
+     * an active gesture retains its value on idle frames (fingers held still
+     * are not a gesture end). AC-11: reading the same frame's snapshot twice
+     * returns the identical object.
+     */
+    readonly gesture: GestureState;
+    /**
+     * Per-frame gesture lifecycle + instantaneous event queue (begin / end /
+     * cancel / swipe / long-press / double-tap). One-frame lifecycle, same
+     * pattern as `pointerEvents` (charter P4). Empty array when no gesture
+     * activity occurred this frame. Closed discriminant union (AC-13): a
+     * consumer exhaustively switches on `kind` without a default branch.
+     */
+    readonly gestureEvents: readonly GestureEvent[];
+    /**
+     * Action mapping readpoint. Returns a frozen reader for the named action.
+     * When `name` is registered in the InputMap, `isPressed()` / `justPressed()`
+     * / `justReleased()` / `strength` reflect the derived state. Unregistered
+     * action names return empty signal (false / 0 / false / false / 0) without
+     * throwing (charter P3: empty signal is the signal). AC-11: calling
+     * action() multiple times in the same frame returns identical values.
+     */
+    action(name: string): {
+        readonly isPressed: () => boolean;
+        readonly justPressed: () => boolean;
+        readonly justReleased: () => boolean;
+        readonly strength: number;
+    };
+    /**
+     * Compose a 1D axis value from two opposing actions.
+     *
+     * Returns `strength(pos) - strength(neg)`, range [-1, 1].
+     * Both registered: combines normally. One unregistered: contributes 0
+     * (E-3). Same action for both ends: always 0 (E-12).
+     *
+     * @param neg - Action name for the negative direction (e.g. 'moveLeft').
+     * @param pos - Action name for the positive direction (e.g. 'moveRight').
+     */
+    getAxis(neg: string, pos: string): number;
+    /**
+     * Compose a 2D vector from four directional actions with a single radial
+     * deadzone (Godot input.cpp three-branch formula). Uses `raw` (not
+     * `strength`) to avoid per-axis deadzone stacking into a square deadzone
+     * (AC-06).
+     *
+     * @param negX - Action name for negative X (e.g. 'moveLeft').
+     * @param posX - Action name for positive X (e.g. 'moveRight').
+     * @param negY - Action name for negative Y (e.g. 'moveUp').
+     * @param posY - Action name for positive Y (e.g. 'moveDown').
+     * @param opts - Optional override (deadzone).
+     */
+    getVector(negX: string, posX: string, negY: string, posY: string, opts?: GetVectorOptions): {
+        readonly x: number;
+        readonly y: number;
+    };
+}
+/**
+ * Backend protocol consumed by the frame-start scan system. The browser
+ * implementation (`browser-backend.ts`) is the production producer;
+ * tests inject fakes that emit synthetic samples.
+ */
+export interface InputBackend {
+    /**
+     * Produce one frame's worth of input data and reset the per-frame
+     * accumulators (movement delta + up-edge set). Held-key state and
+     * held-button state survive across calls.
+     *
+     * Contract notes:
+     * - `downKeys` is the held-key set as of the call (held across frames)
+     * - `upKeys` is the up-edge set since the previous sample (cleared
+     *   after the call so the edge appears in exactly one frame)
+     * - `buttons` is the held-button slot tuple `[b0, b1, b2]`
+     * - `movementX` / `movementY` are the accumulated PointerLock delta
+     *   since the previous sample (cleared after the call)
+     * - `focused` mirrors `document.hasFocus()` so the scan system can
+     *   suppress spurious up-edges across alt-tab transitions
+     */
+    sample(): InputBackendSample;
+    /**
+     * Command-set game gate for pointer-lock. When set to `false`, the
+     * backend will not request pointer-lock on click AND will immediately
+     * release any currently active lock (W3C path: `exitPointerLock`;
+     * provider path: `exitLock()`). When `true` (default), pointer-lock
+     * can be requested through the normal gate logic.
+     *
+     * Optional -- backends without pointer-lock support omit this method.
+     */
+    setPointerLockAllowed?(allowed: boolean): void;
+    /**
+     * Atomically discard acquired state without detaching listeners. A host calls
+     * this when it revokes a control lease so held keys/buttons, contacts, frame
+     * edges, deltas and pointer lock cannot bleed into a later consumer. Optional
+     * keeps synthetic backends source-compatible.
+     */
+    clear?(): void;
+    /** Detach DOM listeners; called when the engine shuts down. */
+    detach(): void;
+}
+/** Snapshot value returned by `InputBackend.sample()` (POD). */
+export interface InputBackendSample {
+    readonly downKeys: ReadonlySet<string>;
+    readonly upKeys: ReadonlySet<string>;
+    /** Physical code identity (KeyboardEvent.code), when the producer has it. */
+    readonly downCodes?: ReadonlySet<string>;
+    /** One-frame physical code release edges, when the producer has them. */
+    readonly upCodes?: ReadonlySet<string>;
+    readonly buttons: readonly [boolean, boolean, boolean];
+    readonly movementX: number;
+    readonly movementY: number;
+    /** Latest canvas-pixel mouse position; absent for non-pointer backends. */
+    readonly mouseX?: number;
+    readonly mouseY?: number;
+    /**
+     * Sign-discrete wheel notch accumulator since the previous sample
+     * (plan-strategy D-5). Browser backend writes `Math.sign(deltaY)` per
+     * `WheelEvent`; sample() drains the value and resets the producer
+     * accumulator (mirrors movementX/Y semantics).
+     */
+    readonly wheelDelta: number;
+    /** True for the first sample after blur/hidden state reset. */
+    readonly focusReset?: boolean;
+    readonly focused: boolean;
+    /** M1+ gamepad per-slot frame data (optional — absent when backend lacks gamepad support). */
+    readonly gamepads?: readonly GamepadSlotSample[];
+    /** M1+ frozen capability snapshot (optional — absent for pre-M1 backends). */
+    readonly capabilities?: Capabilities;
+    /** M2+ active pointer contacts (optional — absent for keyboard-only backends). */
+    readonly pointers?: readonly PointerSample[];
+    /** M2+ per-frame phase event queue (optional — absent when no pointer events occurred). */
+    readonly pointerEvents?: readonly PointerPhaseEvent[];
+    /** M3+ virtual joystick axis outputs (optional — absent when no virtual joysticks configured). */
+    readonly virtualAxes?: readonly VirtualAxisSample[];
+    /** M5+ continuous gesture values (optional — absent when no gesture is active). */
+    readonly gestures?: GestureState;
+    /** M5+ per-frame gesture event queue (optional — absent when no gesture activity occurred). */
+    readonly gestureEvents?: readonly GestureEvent[];
+    /**
+     * Merged pointer-lock state: true when either W3C pointer-lock is active
+     * (pointerLockElement === this backend's canvas) OR the lockProvider path
+     * has engaged (requestLock() was called and not yet released). Required
+     * field -- always present, defaults to false when no lock is active.
+     */
+    readonly pointerLocked: boolean;
+}
+/** Build the neutral backend sample used before or outside an active consumer. */
+export declare function createEmptyInputBackendSample(): InputBackendSample;
+/**
+ * Build an `InputSnapshot` from a backend sample.
+ *
+ * @param sample - One frame's raw input backend sample (POD).
+ * @param actionStates - Optional per-frame derived action states from
+ *   deriveActionStates(). When provided, snap.action(name) returns mapped
+ *   values; when absent or empty, all action readpoints return empty signal
+ *   (charter P3: false/0, never throws). AC-11: actionStates is frozen into
+ *   the snapshot so same-frame re-reads return identical values.
+ */
+export declare function snapshotFromSample(sample: InputBackendSample, actionStates?: readonly ActionState[], inputMap?: readonly ActionConfig[], previousSnapshot?: InputSnapshot): InputSnapshot;
+/**
+ * @internal Read previously derived action states from a snapshot for edge diff.
+ * Used by the frame-start scan system (D-6: prev snapshot = edge baseline).
+ */
+export declare function readActionStatesForEdgeDiff(snap: InputSnapshot): readonly ActionState[] | undefined;
+/**
+ * Construct an empty snapshot for the pre-start window
+ * (`engine.run()` has not yet attached a backend). Returns the full
+ * multi-device shape as `snapshotFromSample`, with every accessor
+ * returning `false` / `0` / zero-vector. AI users can put this into the
+ * Resource store to satisfy `world.getResource('InputSnapshot')` calls
+ * in fixtures or unit tests (charter P3: empty signal is the signal).
+ * The underlying 7-field POD sample contract is unchanged (D-9).
+ */
+export declare function createInputSnapshot(): InputSnapshot;
+/** Stable Resource key for `world.insertResource` / `world.getResource`. */
+export declare const INPUT_SNAPSHOT_RESOURCE_KEY = "InputSnapshot";
+//# sourceMappingURL=input-snapshot.d.ts.map

package/dist/input-snapshot.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"input-snapshot.d.ts","sourceRoot":"","sources":["../src/input-snapshot.ts"],"names":[],"mappings":"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"}

package/dist/plugin-service.d.ts

@@ -0,0 +1,11 @@
+import type { Plugin } from '@forgeax/engine-plugin';
+import type { InputBackend } from './input-snapshot';
+declare module '@forgeax/engine-plugin' {
+    interface EngineContextServices {
+        input?: InputBackend;
+    }
+}
+export declare function inputBackendPlugin(backend: InputBackend): Plugin;
+/** Provide an App-acquired input backend and release its Host listeners with the Fiber. */
+export declare function ownedInputBackendPlugin(backend: InputBackend, dispose: () => void): Plugin;
+//# sourceMappingURL=plugin-service.d.ts.map

package/dist/plugin-service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin-service.d.ts","sourceRoot":"","sources":["../src/plugin-service.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,wBAAwB,CAAC;AAErD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAErD,OAAO,QAAQ,wBAAwB,CAAC;IACtC,UAAU,qBAAqB;QAC7B,KAAK,CAAC,EAAE,YAAY,CAAC;KACtB;CACF;AAED,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,YAAY,GAAG,MAAM,CAQhE;AAED,2FAA2F;AAC3F,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,YAAY,EAAE,OAAO,EAAE,MAAM,IAAI,GAAG,MAAM,CAS1F"}

package/dist/ui-ownership.d.ts

@@ -0,0 +1,17 @@
+/** Event-path ownership and lifecycle reset primitives for browser hosts. */
+export interface UiOwnershipResult {
+    readonly owned: boolean;
+    readonly source: 'composed-path' | 'target-fallback' | 'unknown';
+}
+export interface UiInputResetBoundaryOptions {
+    readonly clear: () => void;
+    readonly signal?: AbortSignal;
+}
+export interface UiInputResetBoundary {
+    readonly reset: () => void;
+    readonly dispose: () => void;
+}
+export declare function resolveUiOwnership(event: Event, host: Node): UiOwnershipResult;
+export declare function isUiOwnedEvent(event: Event, host: Node): boolean;
+export declare function createUiInputResetBoundary(options: UiInputResetBoundaryOptions): UiInputResetBoundary;
+//# sourceMappingURL=ui-ownership.d.ts.map

package/dist/ui-ownership.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ui-ownership.d.ts","sourceRoot":"","sources":["../src/ui-ownership.ts"],"names":[],"mappings":"AAAA,6EAA6E;AAE7E,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB,QAAQ,CAAC,MAAM,EAAE,eAAe,GAAG,iBAAiB,GAAG,SAAS,CAAC;CAClE;AAED,MAAM,WAAW,2BAA2B;IAC1C,QAAQ,CAAC,KAAK,EAAE,MAAM,IAAI,CAAC;IAC3B,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAC;CAC/B;AAED,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,KAAK,EAAE,MAAM,IAAI,CAAC;IAC3B,QAAQ,CAAC,OAAO,EAAE,MAAM,IAAI,CAAC;CAC9B;AAOD,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,IAAI,GAAG,iBAAiB,CAe9E;AAED,wBAAgB,cAAc,CAAC,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,IAAI,GAAG,OAAO,CAEhE;AAED,wBAAgB,0BAA0B,CACxC,OAAO,EAAE,2BAA2B,GACnC,oBAAoB,CAetB"}

package/dist/virtual-joystick.d.ts

@@ -0,0 +1,39 @@
+import type { VirtualAxisSample, VirtualJoystickConfig } from './input-snapshot';
+/**
+ * Per-joystick binding state. The backend closure owns a
+ * Map<string, BindState> keyed by joystick config name.
+ */
+export interface BindState {
+    /** bound pointerId, or undefined if unbound */
+    pointerId?: number | undefined;
+    /** origin in canvas pixels (anchor for fixed, first-touch for floating) */
+    originX: number;
+    originY: number;
+}
+/**
+ * Derive one frame of virtual axis outputs from live pointer state and
+ * per-joystick binding state.
+ *
+ * Pure function: no DOM access. The backend closure is the SSOT for
+ * per-joystick state; binding + origin selection happens in
+ * browser-backend.ts onPointerDown. This function only reads bindState
+ * and computes per-frame vectors.
+ *
+ * Unbound joysticks always produce the zero vector.
+ *
+ * @param configs - configured virtual joysticks
+ * @param pointerMap - live pointer positions keyed by pointerId
+ * @param bindState - per-joystick binding state (read-only)
+ * @returns one VirtualAxisSample per configured joystick
+ */
+export declare function deriveVirtualAxes(configs: readonly VirtualJoystickConfig[], pointerMap: Map<number, {
+    readonly x: number;
+    readonly y: number;
+}>, bindState: Map<string, BindState>): VirtualAxisSample[];
+/**
+ * Unbind a joystick when its bound pointer goes up or is cancelled.
+ * Sets pointerId to undefined; the next deriveVirtualAxes call will
+ * produce a zero vector for the unbound joystick.
+ */
+export declare function handleVirtualJoystickUnbind(bindState: Map<string, BindState>, pointerId: number): void;
+//# sourceMappingURL=virtual-joystick.d.ts.map

package/dist/virtual-joystick.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"virtual-joystick.d.ts","sourceRoot":"","sources":["../src/virtual-joystick.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,iBAAiB,EAAE,qBAAqB,EAAE,MAAM,kBAAkB,CAAC;AAEjF;;;GAGG;AACH,MAAM,WAAW,SAAS;IACxB,+CAA+C;IAC/C,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC/B,2EAA2E;IAC3E,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;CACjB;AAqBD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,SAAS,qBAAqB,EAAE,EACzC,UAAU,EAAE,GAAG,CAAC,MAAM,EAAE;IAAE,QAAQ,CAAC,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,EACnE,SAAS,EAAE,GAAG,CAAC,MAAM,EAAE,SAAS,CAAC,GAChC,iBAAiB,EAAE,CAyBrB;AAED;;;;GAIG;AACH,wBAAgB,2BAA2B,CACzC,SAAS,EAAE,GAAG,CAAC,MAAM,EAAE,SAAS,CAAC,EACjC,SAAS,EAAE,MAAM,GAChB,IAAI,CAMN"}

package/package.json

@@ -0,0 +1,72 @@
+{
+  "name": "@forgeax/engine-input",
+  "version": "0.1.2",
+  "private": false,
+  "type": "module",
+  "license": "Apache-2.0",
+  "sideEffects": false,
+  "description": "Frame-start scanned, frozen InputSnapshot Resource (logical keyboard key and physical code held/press/release edges + mouse.position/movementDelta + mouse.button(0|1|2)) + browser PointerLock backend for forgeax-engine.",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs"
+    },
+    "./controller-db": {
+      "types": "./dist/controller-db.d.ts",
+      "import": "./dist/controller-db.mjs"
+    },
+    "./controller-db-data": {
+      "types": "./dist/controller-db-data.d.ts",
+      "import": "./dist/controller-db-data.mjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "main": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "src",
+    "vendor",
+    "README.md",
+    "LICENSE"
+  ],
+  "dependencies": {
+    "@forgeax/engine-ecs": "0.1.2",
+    "@forgeax/engine-plugin": "0.1.2"
+  },
+  "forgeax": {
+    "metrics": {
+      "bundle-size": {
+        "enabled": true,
+        "path": "dist/index.mjs",
+        "compression": "gzip",
+        "baseline": {
+          "source": "b2ea70919",
+          "threshold": 13280
+        },
+        "reason": "dist/index.mjs = 12069 B gzip after the normalized input snapshot and action/gesture readpoints. Threshold 13280 B = approximately 10% headroom over measured gzip. Prior baseline 10899 B gzip @ b2ea70919 (threshold 11990). Includes: action-state.ts (deriveActionStates + getAxis/getVector), gesture-recognizer.ts (5 state machines), gamepad-frame.ts (DB remap), browser-backend.ts (recognizer wiring + lazy-load), composite-backend.ts (per-key-yield merge decorator), input-snapshot.ts (keyboard/mouse/action/gesture readpoints + PointerType narrowing), index.ts (barrel). The SDL controller DB sub-export (dist/controller-db.mjs, ~1.5 KB gzip) and data sub-export (dist/controller-db-data.mjs, ~45 KB gzip / 545 KB raw) are opt-in lazy dynamic-imports and are NOT in the main-entry path (path=dist/index.mjs)."
+      },
+      "fps": {
+        "enabled": false,
+        "reason": "library package, no runtime canvas; fps is reported by hello-* / learn-render apps that consume engine.input.snapshot()"
+      },
+      "bench": {
+        "enabled": false,
+        "reason": "frame-start scan path is O(events-since-last-tick); not a perf-critical surface for the MVP"
+      },
+      "gate": {
+        "enabled": false,
+        "reason": "no package-level binary gate; AC-07 surface coverage runs as part of pnpm test:unit + tsc -b"
+      },
+      "spike-report": {
+        "enabled": false,
+        "reason": "not a spike package; this is a production MVP per plan-strategy D-5 (input internalisation minimal surface)"
+      }
+    }
+  },
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run",
+    "typecheck": "tsc -b"
+  }
+}