@vgai/engine 0.2.0 → 0.3.0

package/dist/input/input-types.d.ts

@@ -0,0 +1,171 @@
+/**
+ * A single binding for an action.
+ *
+ * F2 (spec §12 "Complete Device Backends") un-rejects `mouse_move` and
+ * `gamepad_axis_pair` — both now have real `InputManager` readers (see that
+ * file's `collectPointerDeltaContributions`/`collectVector2Contributions`):
+ *  - `mouse_move` feeds a `'pointerDelta'`-valueType action with the raw
+ *    accumulated mouse delta (no deadzone — deltas are not deadzoned, same
+ *    rule as `test_pointer_delta`), and can ALSO feed a `'vector2'`-valueType
+ *    action (the same delta, radial-deadzoned + unit-circle-clamped via
+ *    `deadzone`) — e.g. an alternative look control. It does not feed a
+ *    `'scalar'` action (no natural single-axis-select field is defined; add
+ *    one if a real use case needs it).
+ *  - `gamepad_axis_pair` feeds a `'vector2'`-valueType action with the
+ *    coupled `(xAxis, yAxis)` reading, radial-deadzoned the same way a real
+ *    analog stick is (default deadzone 0.15, matching `gamepad_axis`).
+ *
+ * F2 also adds `touch_button`/`touch_stick` below — the touch/virtual-control
+ * backend. Both are driven by `InputManager.setTouchButton`/`setTouchStick`
+ * (the injectable entry points a touch-control UI's own touchstart/
+ * touchmove/touchend handlers call — that DOM wiring is a thin adapter at
+ * the edge, browser-verified separately; the MAPPING here is unit-tested
+ * headlessly with no DOM). `sourceId` names the virtual control (a zone/
+ * knob id chosen by the touch UI), reusing the same field `test_*` bindings
+ * use for their named source — not a real device index.
+ */
+export type InputBinding = {
+    type: 'key';
+    code: string;
+} | {
+    type: 'mouse_button';
+    button: number;
+} | {
+    type: 'mouse_move';
+    deadzone?: number;
+} | {
+    type: 'gamepad_button';
+    button: number;
+} | {
+    type: 'gamepad_axis';
+    axis: number;
+    direction: 'positive' | 'negative';
+    deadzone?: number;
+} | {
+    type: 'gamepad_axis_pair';
+    xAxis: number;
+    yAxis: number;
+    deadzone?: number;
+} | {
+    type: 'test_axis';
+    sourceId: string;
+    deadzone?: number;
+} | {
+    type: 'test_vector2';
+    sourceId: string;
+    deadzone?: number;
+} | {
+    type: 'test_pointer_delta';
+    sourceId: string;
+} | {
+    type: 'test_pointer_position';
+    sourceId: string;
+} | {
+    type: 'touch_button';
+    sourceId: string;
+} | {
+    type: 'touch_stick';
+    sourceId: string;
+    deadzone?: number;
+};
+/**
+ * The value shape an action carries (F1, spec §12 "Define Typed Action Values"):
+ *  - `'digital'` — boolean, with pressed/justPressed/justReleased edges (InputManager.isPressed
+ *    et al.). The default when an action omits `valueType` — every action authored before F1
+ *    is a digital action, so this stays backward compatible.
+ *  - `'scalar'` — a single float axis (InputManager.getScalar), e.g. a throttle or a single
+ *    thumbstick axis.
+ *  - `'vector2'` — a {x,y} axis pair (InputManager.getVector2), e.g. movement/look.
+ *  - `'pointerDelta'` — a {x,y} per-frame movement delta (InputManager.getPointerDelta),
+ *    summed across contributing sources, cleared every frame (mirrors the existing
+ *    mouseDeltaX/Y accumulator's per-frame-reset shape).
+ *  - `'pointerPosition'` — a {x,y} absolute position (InputManager.getPointerPosition),
+ *    last-write-wins across contributing sources (position isn't additive).
+ */
+export type ActionValueType = 'digital' | 'scalar' | 'vector2' | 'pointerDelta' | 'pointerPosition';
+/** A plain 2D vector — the shared shape for Vector2 axis pairs, pointer delta, and pointer
+ *  position action values (F1). */
+export interface Vector2 {
+    x: number;
+    y: number;
+}
+/**
+ * Maps an `ActionValueType` to its TS read type. This is the "no `any`" backbone behind
+ * `InputManager.readAction` (and, informally, behind each dedicated typed getter returning a
+ * concrete, non-`any` type): given a value type known at the call site (a literal, or a type
+ * parameter inferred from a caller's own action-value-type map), the return type is exact.
+ */
+export type ActionValueOf<T extends ActionValueType> = T extends 'digital' ? boolean : T extends 'scalar' ? number : T extends 'vector2' | 'pointerDelta' | 'pointerPosition' ? Vector2 : never;
+/**
+ * Device/source metadata (F1 AC): which binding — and, for gamepad bindings, which connected
+ * gamepad, or for injected test bindings, which named source — produced an action's current
+ * value. Returned by the `*Source` sibling of each typed getter (e.g. `getScalarSource`).
+ */
+export interface ActionValueSource {
+    /** The binding kind that produced the current value. */
+    bindingType: InputBinding['type'];
+    /** Present for `test_axis`/`test_vector2`/`test_pointer_delta`/`test_pointer_position`/
+     *  `touch_button`/`touch_stick` bindings — the caller-chosen source id passed to the
+     *  matching `inject*`/`setTouch*` call (F2 reuses this same field for named touch zones,
+     *  not a real device index). */
+    sourceId?: string;
+    /** Present for `gamepad_button`/`gamepad_axis`/`gamepad_axis_pair` (F2) bindings — the
+     *  index into `navigator.getGamepads()` of the gamepad that produced the value. */
+    gamepadIndex?: number;
+    /** F2 — present alongside `gamepadIndex` for `gamepad_button`/`gamepad_axis`/
+     *  `gamepad_axis_pair` bindings: the connected gamepad's `Gamepad.id` (device identity,
+     *  spec §12 F2 "expose device identity"), e.g. a vendor/product string. */
+    gamepadId?: string;
+}
+/** An action has a name and one or more bindings */
+export interface InputAction {
+    /** Declares this action's value shape (F1). Optional — defaults to `'digital'`, matching
+     *  every action authored before F1. See `ActionValueType` for the full set. */
+    valueType?: ActionValueType;
+    bindings: InputBinding[];
+}
+/** The .inputmap.json file format */
+export interface InputMapFile {
+    version: number;
+    actions: Record<string, InputAction>;
+}
+/**
+ * A structural conflict returned by `InputManager.findConflicts` (F3 AC
+ * "Conflicts are detected and returned structurally"): a proposed binding
+ * would collide with an EXISTING binding already registered on a different
+ * action. Never thrown — always a plain data array the caller (typically a
+ * rebinding UI) inspects and decides what to do with (block, warn, or let the
+ * user override).
+ */
+export interface BindingConflict {
+    /** The other action whose existing binding collides with the proposed one. */
+    actionName: string;
+    /** That action's bindings-array index the collision was found at (stable
+     *  enough to pass straight to `removeBinding`/`replaceBinding` if the UI
+     *  offers "steal this binding"). */
+    bindingIndex: number;
+    /** The colliding binding itself. */
+    binding: InputBinding;
+}
+/**
+ * The coarse input-device family a prompt is being requested for (F3 AC "a
+ * current-device prompt API"). Keyboard and mouse are kept distinct — a
+ * binding list frequently carries one of each (e.g. `key` for movement,
+ * `mouse_button` for fire) and a prompt UI usually wants to show whichever
+ * one is bound, not conflate the two.
+ */
+export type PromptDevice = 'keyboard' | 'mouse' | 'gamepad' | 'touch';
+/**
+ * The resolved display prompt for one action's binding on a given device
+ * family (F3 AC: "resolves labels/icons such as `Space`, `A`, or a touch
+ * control"). `icon` is a short glyph/name a UI can look up in its own icon
+ * set (for keyboard it's the same short label; for gamepad it's the
+ * canonical button/glyph name, e.g. `'A'`; the UI decides how to render it).
+ */
+export interface BindingPrompt {
+    device: PromptDevice;
+    bindingType: InputBinding['type'];
+    label: string;
+    icon: string;
+}
+//# sourceMappingURL=input-types.d.ts.map

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

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

package/dist/input/input-types.js

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

package/dist/input/prompt-labels.d.ts

@@ -0,0 +1,21 @@
+import type { InputBinding, PromptDevice } from './input-types';
+/** Display label for a `KeyboardEvent.code` (F3 AC example: `'Space'`). */
+export declare function keyLabel(code: string): string;
+/** Display label for a `MouseEvent.button` index. */
+export declare function mouseButtonLabel(button: number): string;
+/** W3C Standard Gamepad button-index -> conventional face-button glyph name
+ *  (F3 AC example: `'A'`). Only meaningful when `Gamepad.mapping === 'standard'`
+ *  — see `InputManager.getPrompt`, which falls back to a raw index label when
+ *  the connected pad doesn't report the standard mapping. */
+export declare const STANDARD_GAMEPAD_BUTTON_LABELS: Record<number, string>;
+/** Display label for a single standard-mapping gamepad axis (a `gamepad_axis`
+ *  binding — one half of a stick, or a trigger). */
+export declare function gamepadAxisLabel(axis: number): string;
+/** Display label for a coupled `gamepad_axis_pair` binding. */
+export declare function gamepadAxisPairLabel(xAxis: number, yAxis: number): string;
+/** Which `PromptDevice` family a binding kind belongs to, or `null` for a
+ *  binding kind with no real physical device (the synthetic `test_*` kinds —
+ *  they're an injected-test-input source, never something to prompt a player
+ *  about). */
+export declare function bindingDeviceFamily(type: InputBinding['type']): PromptDevice | null;
+//# sourceMappingURL=prompt-labels.d.ts.map

package/dist/input/prompt-labels.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"prompt-labels.d.ts","sourceRoot":"","sources":["../../src/input/prompt-labels.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AA2BhE,2EAA2E;AAC3E,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAQ7C;AAUD,qDAAqD;AACrD,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAEvD;AAED;;;6DAG6D;AAC7D,eAAO,MAAM,8BAA8B,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAkBjE,CAAC;AAEF;oDACoD;AACpD,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAIrD;AAED,+DAA+D;AAC/D,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAIzE;AAED;;;cAGc;AACd,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,YAAY,CAAC,MAAM,CAAC,GAAG,YAAY,GAAG,IAAI,CAiBnF"}

package/dist/input/prompt-labels.js

@@ -0,0 +1,121 @@
+// F3 (spec §12 "Add Rebinding and Prompts") — the device->label map behind
+// `InputManager.getPrompt`. Pure data + pure functions, no InputManager
+// dependency, so it's independently unit-testable and reusable by a
+// rebinding UI that wants to render a label without going through a live
+// InputManager instance (e.g. previewing a not-yet-applied binding).
+//
+// Labels intentionally favor short, conventional display strings over exact
+// spec names (`'Ctrl'` not `'ControlLeft'`, `'A'` not `'button-0'`) — this is
+// what a HUD prompt or rebinding list actually renders.
+/** `KeyboardEvent.code` values with a friendlier display label than the raw
+ *  code string. Anything not listed here falls through to `keyLabel`'s
+ *  `Key*`/`Digit*` stripping, or the raw code as a last resort. */
+const KEY_LABELS = {
+    Space: 'Space',
+    Escape: 'Esc',
+    Enter: 'Enter',
+    NumpadEnter: 'Enter',
+    Tab: 'Tab',
+    Backspace: 'Backspace',
+    CapsLock: 'Caps Lock',
+    ArrowUp: '↑',
+    ArrowDown: '↓',
+    ArrowLeft: '←',
+    ArrowRight: '→',
+    ShiftLeft: 'Shift',
+    ShiftRight: 'Shift',
+    ControlLeft: 'Ctrl',
+    ControlRight: 'Ctrl',
+    AltLeft: 'Alt',
+    AltRight: 'Alt',
+    MetaLeft: 'Meta',
+    MetaRight: 'Meta',
+};
+/** Display label for a `KeyboardEvent.code` (F3 AC example: `'Space'`). */
+export function keyLabel(code) {
+    const known = KEY_LABELS[code];
+    if (known)
+        return known;
+    if (code.startsWith('Key') && code.length === 4)
+        return code.slice(3); // KeyW -> W
+    if (code.startsWith('Digit') && code.length === 6)
+        return code.slice(5); // Digit1 -> 1
+    if (code.startsWith('Numpad'))
+        return `Num ${code.slice(6)}`;
+    if (code.startsWith('F') && /^F\d+$/.test(code))
+        return code; // F1..F12 already short
+    return code;
+}
+const MOUSE_BUTTON_LABELS = {
+    0: 'Left Click',
+    1: 'Middle Click',
+    2: 'Right Click',
+    3: 'Mouse 4',
+    4: 'Mouse 5',
+};
+/** Display label for a `MouseEvent.button` index. */
+export function mouseButtonLabel(button) {
+    return MOUSE_BUTTON_LABELS[button] ?? `Mouse ${button}`;
+}
+/** W3C Standard Gamepad button-index -> conventional face-button glyph name
+ *  (F3 AC example: `'A'`). Only meaningful when `Gamepad.mapping === 'standard'`
+ *  — see `InputManager.getPrompt`, which falls back to a raw index label when
+ *  the connected pad doesn't report the standard mapping. */
+export const STANDARD_GAMEPAD_BUTTON_LABELS = {
+    0: 'A',
+    1: 'B',
+    2: 'X',
+    3: 'Y',
+    4: 'LB',
+    5: 'RB',
+    6: 'LT',
+    7: 'RT',
+    8: 'Back',
+    9: 'Start',
+    10: 'L3',
+    11: 'R3',
+    12: 'D-Up',
+    13: 'D-Down',
+    14: 'D-Left',
+    15: 'D-Right',
+    16: 'Home',
+};
+/** Display label for a single standard-mapping gamepad axis (a `gamepad_axis`
+ *  binding — one half of a stick, or a trigger). */
+export function gamepadAxisLabel(axis) {
+    if (axis === 0 || axis === 1)
+        return 'Left Stick';
+    if (axis === 2 || axis === 3)
+        return 'Right Stick';
+    return `Axis ${axis}`;
+}
+/** Display label for a coupled `gamepad_axis_pair` binding. */
+export function gamepadAxisPairLabel(xAxis, yAxis) {
+    if (xAxis === 0 && yAxis === 1)
+        return 'Left Stick';
+    if (xAxis === 2 && yAxis === 3)
+        return 'Right Stick';
+    return `Axis ${xAxis}/${yAxis}`;
+}
+/** Which `PromptDevice` family a binding kind belongs to, or `null` for a
+ *  binding kind with no real physical device (the synthetic `test_*` kinds —
+ *  they're an injected-test-input source, never something to prompt a player
+ *  about). */
+export function bindingDeviceFamily(type) {
+    switch (type) {
+        case 'key':
+            return 'keyboard';
+        case 'mouse_button':
+        case 'mouse_move':
+            return 'mouse';
+        case 'gamepad_button':
+        case 'gamepad_axis':
+        case 'gamepad_axis_pair':
+            return 'gamepad';
+        case 'touch_button':
+        case 'touch_stick':
+            return 'touch';
+        default:
+            return null;
+    }
+}

package/dist/input/rebind-controller.d.ts

@@ -0,0 +1,59 @@
+import type { InputManager } from './input-manager';
+import type { BindingConflict, InputBinding } from './input-types';
+/** How a captured binding is applied once accepted. */
+export type RebindMode = 'replace' | 'add';
+export type RebindState = {
+    status: 'idle';
+} | {
+    status: 'listening';
+    actionName: string;
+    mode: RebindMode;
+    index: number;
+} | {
+    status: 'conflict';
+    actionName: string;
+    mode: RebindMode;
+    index: number;
+    proposed: InputBinding;
+    conflicts: BindingConflict[];
+} | {
+    status: 'applied';
+    actionName: string;
+    binding: InputBinding;
+};
+export declare class RebindController {
+    private readonly input;
+    private state;
+    constructor(input: InputManager);
+    getState(): RebindState;
+    /**
+     * Enter listening mode for `actionName`. `mode: 'replace'` (default)
+     * rebinds the slot at `index` (default 0 — the action's first/primary
+     * binding); `mode: 'add'` appends a new binding alongside the existing
+     * ones instead (`index` is ignored for `'add'`).
+     */
+    listen(actionName: string, mode?: RebindMode, index?: number): void;
+    /** Abandon listening/a pending conflict with no changes applied. */
+    cancel(): void;
+    /**
+     * Feed a captured raw `InputBinding` while in the `'listening'` state
+     * (a no-op returning the current state unchanged otherwise — e.g. a stray
+     * keypress arriving after the UI already cancelled). Checks
+     * `InputManager.findConflicts` first: a free binding is applied
+     * immediately (-> `'applied'`); a colliding one transitions to
+     * `'conflict'` instead of applying, so the UI can surface it before
+     * anything changes.
+     */
+    capture(binding: InputBinding): RebindState;
+    /**
+     * From a `'conflict'` state, apply the pending proposed binding anyway
+     * (the UI decided the collision is acceptable, e.g. "steal this binding").
+     * Does NOT remove the colliding binding from the other action — that is a
+     * separate, explicit `InputManager.removeBinding` call the UI can make
+     * first if it wants a true swap. A no-op (returns current state) unless a
+     * conflict is pending.
+     */
+    resolveOverride(): RebindState;
+    private apply;
+}
+//# sourceMappingURL=rebind-controller.d.ts.map

package/dist/input/rebind-controller.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rebind-controller.d.ts","sourceRoot":"","sources":["../../src/input/rebind-controller.ts"],"names":[],"mappings":"AAmBA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AACpD,OAAO,KAAK,EAAE,eAAe,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAEnE,uDAAuD;AACvD,MAAM,MAAM,UAAU,GAAG,SAAS,GAAG,KAAK,CAAC;AAE3C,MAAM,MAAM,WAAW,GACnB;IAAE,MAAM,EAAE,MAAM,CAAA;CAAE,GAClB;IAAE,MAAM,EAAE,WAAW,CAAC;IAAC,UAAU,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,UAAU,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GAC5E;IACE,MAAM,EAAE,UAAU,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,EAAE,UAAU,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,YAAY,CAAC;IACvB,SAAS,EAAE,eAAe,EAAE,CAAC;CAC9B,GACD;IAAE,MAAM,EAAE,SAAS,CAAC;IAAC,UAAU,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,YAAY,CAAA;CAAE,CAAC;AAErE,qBAAa,gBAAgB;IAGf,OAAO,CAAC,QAAQ,CAAC,KAAK;IAFlC,OAAO,CAAC,KAAK,CAAmC;gBAEnB,KAAK,EAAE,YAAY;IAEhD,QAAQ,IAAI,WAAW;IAIvB;;;;;OAKG;IACH,MAAM,CAAC,UAAU,EAAE,MAAM,EAAE,IAAI,GAAE,UAAsB,EAAE,KAAK,SAAI,GAAG,IAAI;IAIzE,oEAAoE;IACpE,MAAM,IAAI,IAAI;IAId;;;;;;;;OAQG;IACH,OAAO,CAAC,OAAO,EAAE,YAAY,GAAG,WAAW;IAa3C;;;;;;;OAOG;IACH,eAAe,IAAI,WAAW;IAQ9B,OAAO,CAAC,KAAK;CAId"}

package/dist/input/rebind-controller.js

@@ -0,0 +1,85 @@
+// F3 (spec §12 "Add Rebinding and Prompts") — a framework-free rebinding
+// STATE MACHINE over an `InputManager`. Deliberately has no dependency on
+// React (or any UI library): "listen for the next input, surface a conflict,
+// let the caller decide" is the same flow whether the caller is the
+// template's `RebindPanel.tsx` (ordinary React, see that file) or any other
+// UI/CLI. Keeping the logic here means it's unit-testable with no DOM/JSX at
+// all, and the React component becomes a thin, mechanically-verifiable
+// wrapper (see the template component's own doc comment).
+//
+// Flow: `listen(actionName)` -> caller captures the next raw input event
+// itself (a keydown, a gamepad poll, a touch tap — capture is inherently
+// device-specific and NOT this class's job) and turns it into an
+// `InputBinding`, then calls `capture(binding)`. If the proposed binding is
+// free, it's applied immediately and the state becomes `'applied'`. If it
+// collides with another action's existing binding (per
+// `InputManager.findConflicts`), the state becomes `'conflict'`, carrying the
+// structured conflict list for the UI to show — the caller then calls either
+// `resolveOverride()` (apply anyway) or `cancel()`.
+export class RebindController {
+    input;
+    state = { status: 'idle' };
+    constructor(input) {
+        this.input = input;
+    }
+    getState() {
+        return this.state;
+    }
+    /**
+     * Enter listening mode for `actionName`. `mode: 'replace'` (default)
+     * rebinds the slot at `index` (default 0 — the action's first/primary
+     * binding); `mode: 'add'` appends a new binding alongside the existing
+     * ones instead (`index` is ignored for `'add'`).
+     */
+    listen(actionName, mode = 'replace', index = 0) {
+        this.state = { status: 'listening', actionName, mode, index };
+    }
+    /** Abandon listening/a pending conflict with no changes applied. */
+    cancel() {
+        this.state = { status: 'idle' };
+    }
+    /**
+     * Feed a captured raw `InputBinding` while in the `'listening'` state
+     * (a no-op returning the current state unchanged otherwise — e.g. a stray
+     * keypress arriving after the UI already cancelled). Checks
+     * `InputManager.findConflicts` first: a free binding is applied
+     * immediately (-> `'applied'`); a colliding one transitions to
+     * `'conflict'` instead of applying, so the UI can surface it before
+     * anything changes.
+     */
+    capture(binding) {
+        if (this.state.status !== 'listening')
+            return this.state;
+        const { actionName, mode, index } = this.state;
+        const conflicts = this.input.findConflicts(binding, actionName);
+        if (conflicts.length > 0) {
+            this.state = { status: 'conflict', actionName, mode, index, proposed: binding, conflicts };
+            return this.state;
+        }
+        this.apply(actionName, mode, index, binding);
+        this.state = { status: 'applied', actionName, binding };
+        return this.state;
+    }
+    /**
+     * From a `'conflict'` state, apply the pending proposed binding anyway
+     * (the UI decided the collision is acceptable, e.g. "steal this binding").
+     * Does NOT remove the colliding binding from the other action — that is a
+     * separate, explicit `InputManager.removeBinding` call the UI can make
+     * first if it wants a true swap. A no-op (returns current state) unless a
+     * conflict is pending.
+     */
+    resolveOverride() {
+        if (this.state.status !== 'conflict')
+            return this.state;
+        const { actionName, mode, index, proposed } = this.state;
+        this.apply(actionName, mode, index, proposed);
+        this.state = { status: 'applied', actionName, binding: proposed };
+        return this.state;
+    }
+    apply(actionName, mode, index, binding) {
+        if (mode === 'add')
+            this.input.addBinding(actionName, binding);
+        else
+            this.input.replaceBinding(actionName, index, binding);
+    }
+}

package/dist/input/schema.d.ts

@@ -0,0 +1,16 @@
+import { z } from 'zod';
+import type { InputAction, InputBinding, InputMapFile } from './input-types';
+/** A single input binding. Every kind listed here is LIVE — F2 (spec §12) closed the last two
+ *  dead stubs (`mouse_move`/`gamepad_axis_pair`) by giving both real `InputManager` readers. */
+export declare const InputBindingSchema: z.ZodType<InputBinding>;
+/** An action has a name (the record key) and one or more bindings. */
+export declare const InputActionSchema: z.ZodType<InputAction>;
+/**
+ * The `.inputmap.json` file format (`InputManager.loadMap`).
+ *
+ * `version` is RESERVED (no range-check reader exists yet for this format —
+ * same convention `2d.version`/`Scene2DSchema` used before T2.3 gave the 3D
+ * scene version axis a real reader; see `schema-consumption-map.ts`).
+ */
+export declare const InputMapFileSchema: z.ZodType<InputMapFile>;
+//# sourceMappingURL=schema.d.ts.map

package/dist/input/schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../../src/input/schema.ts"],"names":[],"mappings":"AAoCA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,KAAK,EAAE,WAAW,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AA6L7E;gGACgG;AAChG,eAAO,MAAM,kBAAkB,EAAE,CAAC,CAAC,OAAO,CAAC,YAAY,CAa1B,CAAC;AAE9B,sEAAsE;AACtE,eAAO,MAAM,iBAAiB,EAAE,CAAC,CAAC,OAAO,CAAC,WAAW,CAwBnD,CAAC;AAEH;;;;;;GAMG;AACH,eAAO,MAAM,kBAAkB,EAAE,CAAC,CAAC,OAAO,CAAC,YAAY,CAK1B,CAAC"}