manim-web 0.30.0 → 0.32.0

package/dist/interaction/GamepadInput.d.ts

@@ -0,0 +1,273 @@
+import { StateMachineInputSink, ValueSink, Unsubscribe, BindValueOptions } from './KeyboardInput';
+/**
+ * The subset of a `GamepadButton` the controller reads. A real `GamepadButton`
+ * satisfies this, and a test stub implements only these two fields.
+ */
+export interface GamepadButtonLike {
+    /** Whether the button is pressed. */
+    readonly pressed: boolean;
+    /** The analog value in `[0, 1]` (triggers), or `0` / `1` for a plain button. */
+    readonly value: number;
+}
+/**
+ * The subset of a `Gamepad` the controller reads. A real `Gamepad` satisfies
+ * this shape, so `navigator.getGamepads()` feeds the controller directly, and a
+ * test injects a plain object with the same fields.
+ */
+export interface GamepadLike {
+    /** The pad's index in the snapshot array. */
+    readonly index: number;
+    /** The device id, when the pad exposes one. */
+    readonly id?: string;
+    /** Whether the pad is connected. Absent is treated as connected. */
+    readonly connected?: boolean;
+    /** The W3C mapping name, typically `'standard'`. */
+    readonly mapping?: string;
+    /** The button states, indexed by the standard-mapping order. */
+    readonly buttons: ReadonlyArray<GamepadButtonLike>;
+    /** The axis values in `[-1, 1]`, indexed by the standard-mapping order. */
+    readonly axes: ReadonlyArray<number>;
+}
+/**
+ * The snapshot source. Returns one entry per pad slot; a slot is `null` when no
+ * pad is connected there. `navigator.getGamepads()` matches this signature.
+ */
+export type GamepadSource = () => ReadonlyArray<GamepadLike | null>;
+/** A gamepad button callback. `button` is the resolved button index. */
+export type GamepadButtonCallback = (button: number, gamepad: GamepadLike | null) => void;
+/**
+ * The W3C standard-gamepad button name → index map. Use a name
+ * (`'A'`, `'dpadUp'`, `'LT'`) in any query instead of a raw index.
+ * @see https://www.w3.org/TR/gamepad/#remapping
+ */
+export declare const STANDARD_BUTTONS: {
+    readonly A: 0;
+    readonly B: 1;
+    readonly X: 2;
+    readonly Y: 3;
+    readonly LB: 4;
+    readonly RB: 5;
+    readonly LT: 6;
+    readonly RT: 7;
+    readonly select: 8;
+    readonly start: 9;
+    readonly L3: 10;
+    readonly R3: 11;
+    readonly dpadUp: 12;
+    readonly dpadDown: 13;
+    readonly dpadLeft: 14;
+    readonly dpadRight: 15;
+    readonly guide: 16;
+};
+/** The standard-mapping axis indices for the two sticks. */
+export declare const STANDARD_AXES: {
+    readonly leftX: 0;
+    readonly leftY: 1;
+    readonly rightX: 2;
+    readonly rightY: 3;
+};
+/**
+ * Resolve a button name or index to a standard-mapping index.
+ * @param button - A button index, or a name in any common spelling.
+ * @returns The index, or `-1` when the name is unknown.
+ */
+export declare function resolveButton(button: number | string): number;
+/** Options for a {@link GamepadInput}. */
+export interface GamepadInputOptions {
+    /**
+     * Which pad slot to read. By default the first connected pad in the snapshot
+     * is used, so a single controller just works.
+     */
+    gamepadIndex?: number;
+    /**
+     * Stick deadzone in `[0, 1]`. An axis whose magnitude is below this reads as
+     * `0`, so a resting stick does not drift. Default `0.1`.
+     */
+    deadzone?: number;
+    /**
+     * Attach the connection listeners immediately on construction. Set `false` to
+     * attach later with {@link GamepadInput.enable}. Default `true`.
+     */
+    autoEnable?: boolean;
+}
+/** Whether the Web Gamepad API is available in this environment. */
+export declare function isGamepadSupported(): boolean;
+/**
+ * Reads live gamepad state for interactive apps and games. Mirrors
+ * {@link KeyboardInput}: construct, then
+ * {@link enable} / {@link disable} / {@link dispose}, and {@link poll} once a
+ * frame.
+ */
+export declare class GamepadInput {
+    private readonly _getGamepads;
+    private readonly _eventTarget;
+    private readonly _gamepadIndex?;
+    private readonly _deadzone;
+    private readonly _down;
+    private readonly _pressed;
+    private readonly _released;
+    private _axes;
+    private _buttonValues;
+    private readonly _downCallbacks;
+    private readonly _upCallbacks;
+    private _enabled;
+    private readonly _onConnect;
+    private readonly _onDisconnect;
+    /**
+     * Create a GamepadInput.
+     * @param options - Behavior options.
+     * @param getGamepads - Snapshot source. Defaults to `navigator.getGamepads`,
+     *   or `null` when no Gamepad API is present. Tests inject a fake here.
+     * @param eventTarget - Target for connection events. Defaults to `window`.
+     */
+    constructor(options?: GamepadInputOptions, getGamepads?: GamepadSource | null, eventTarget?: EventTarget | null);
+    /** Whether the controller is enabled (connection listeners attached). */
+    get isEnabled(): boolean;
+    /** Whether a Gamepad API snapshot source is available. */
+    get hasSource(): boolean;
+    /** Whether a DOM target for connection events is available. */
+    get hasTarget(): boolean;
+    /**
+     * Attach the `gamepadconnected` / `gamepaddisconnected` listeners. A no-op
+     * when already enabled. Polling works even without a DOM target.
+     */
+    enable(): void;
+    /**
+     * Detach the connection listeners and clear all held and edge state, so no
+     * button stays stuck. Reads return defaults until {@link enable} is called.
+     */
+    disable(): void;
+    /**
+     * Detach listeners and drop every registered callback. Use when the
+     * controller is no longer needed.
+     */
+    dispose(): void;
+    /** Clear held buttons, both edge sets, and the cached axes and values. */
+    clear(): void;
+    /**
+     * Read the live gamepad snapshot and compute the press / release edges. Call
+     * once per frame before reading state. The edges stay readable until the next
+     * {@link poll}, so {@link wasButtonPressed} is true for exactly one frame.
+     *
+     * When no pad is present, any held button is released and the state resets,
+     * so a disconnect never leaves a button stuck.
+     */
+    poll(): void;
+    /**
+     * Alias of {@link poll} for render-loop compatibility with
+     * {@link KeyboardInput}.
+     * @param _dt - Delta time (seconds), accepted but not used.
+     */
+    update(_dt?: number): void;
+    /**
+     * Whether the button is held right now (as of the last {@link poll}).
+     * @param button - A button index, or a name (`'A'`, `'dpadUp'`, `'LT'`).
+     */
+    isButtonDown(button: number | string): boolean;
+    /** Whether any button is held right now. */
+    anyButtonDown(): boolean;
+    /**
+     * Whether the button went down on the last {@link poll}. True for exactly one
+     * frame after a 0→1 transition.
+     * @param button - A button index or name.
+     */
+    wasButtonPressed(button: number | string): boolean;
+    /**
+     * Whether the button came up on the last {@link poll}. True for exactly one
+     * frame after a 1→0 transition.
+     * @param button - A button index or name.
+     */
+    wasButtonReleased(button: number | string): boolean;
+    /**
+     * The analog value `[0, 1]` of a button (triggers vary; plain buttons read
+     * `0` or `1`).
+     * @param button - A button index or name.
+     */
+    getButtonValue(button: number | string): number;
+    /**
+     * The raw value `[-1, 1]` of an axis, with the deadzone applied so a resting
+     * stick reads `0`. The API convention is used verbatim: for the vertical
+     * stick axes, up is negative.
+     * @param index - The axis index (see {@link STANDARD_AXES}).
+     * @param deadzone - Override the instance deadzone for this read.
+     */
+    getAxis(index: number, deadzone?: number): number;
+    /**
+     * The left stick as `[x, y]`, deadzone applied, with up as `+y` (the API's
+     * downward vertical axis is flipped to match {@link KeyboardInput}).
+     */
+    getLeftStick(): [number, number];
+    /** The right stick as `[x, y]`, deadzone applied, with up as `+y`. */
+    getRightStick(): [number, number];
+    /**
+     * A normalized movement direction `[x, y]`, up is `+y`. The d-pad wins when
+     * any d-pad button is held; otherwise the left stick is used. A neutral input
+     * stays `[0, 0]`.
+     */
+    getDirectionVector(): [number, number];
+    /** The connected pads in the current snapshot (empty when headless). */
+    getConnectedGamepads(): GamepadLike[];
+    /**
+     * Register a button-down callback, fired by {@link poll} on a 0→1 edge.
+     * @param button - A button index or name, or `'any'` for every button.
+     * @param callback - Called with the button index and the pad.
+     * @returns An unsubscribe function.
+     */
+    onButtonDown(button: number | string, callback: GamepadButtonCallback): Unsubscribe;
+    /**
+     * Register a button-up callback, fired by {@link poll} on a 1→0 edge.
+     * @param button - A button index or name, or `'any'` for every button.
+     * @param callback - Called with the button index and the pad.
+     * @returns An unsubscribe function.
+     */
+    onButtonUp(button: number | string, callback: GamepadButtonCallback): Unsubscribe;
+    /**
+     * Hold a `StateMachine` bool input to match a button: `true` while held,
+     * `false` on release.
+     * @param machine - The `StateMachine` (or any {@link StateMachineInputSink}).
+     * @param inputName - The bool input name.
+     * @param button - The button to track.
+     * @returns An unsubscribe function.
+     */
+    bindBool(machine: StateMachineInputSink, inputName: string, button: number | string): Unsubscribe;
+    /**
+     * Fire a `StateMachine` trigger input on each button-down.
+     * @param machine - The `StateMachine` (or any {@link StateMachineInputSink}).
+     * @param triggerName - The trigger input name.
+     * @param button - The button to track.
+     * @returns An unsubscribe function.
+     */
+    bindTrigger(machine: StateMachineInputSink, triggerName: string, button: number | string): Unsubscribe;
+    /**
+     * Drive a `ValueTracker` from a button: `heldValue` while held,
+     * `releasedValue` on release.
+     * @param tracker - The `ValueTracker` (or any {@link ValueSink}).
+     * @param button - The button to track.
+     * @param options - The held and released values.
+     * @returns An unsubscribe function.
+     */
+    bindValue(tracker: ValueSink, button: number | string, options: BindValueOptions): Unsubscribe;
+    /** Read the active pad from the snapshot, honoring the `gamepadIndex` option. */
+    private _readActivePad;
+    /** Release every held button, emitting up callbacks, on a disconnect. */
+    private _releaseAll;
+    /** Apply the deadzone: magnitudes below `deadzone` read as `0`. */
+    private _applyDeadzone;
+    private _addCallback;
+    /** Resolve a callback registration key, warning on an unknown button name. */
+    private _callbackKey;
+    private _emit;
+    /** Log a connected pad. The snapshot is still read fresh each {@link poll}. */
+    private _handleConnect;
+    /** Log a disconnected pad. {@link poll} releases its held buttons. */
+    private _handleDisconnect;
+}
+/**
+ * Factory for a {@link GamepadInput}.
+ * @param options - Behavior options.
+ * @param getGamepads - Snapshot source.
+ * @param eventTarget - Target for connection events.
+ * @returns A new GamepadInput.
+ */
+export declare function makeGamepadInput(options?: GamepadInputOptions, getGamepads?: GamepadSource | null, eventTarget?: EventTarget | null): GamepadInput;
+//# sourceMappingURL=GamepadInput.d.ts.map

package/dist/interaction/GamepadInput.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"GamepadInput.d.ts","sourceRoot":"","sources":["../../src/interaction/GamepadInput.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAGH,OAAO,KAAK,EACV,qBAAqB,EACrB,SAAS,EACT,WAAW,EACX,gBAAgB,EACjB,MAAM,iBAAiB,CAAC;AAMzB;;;GAGG;AACH,MAAM,WAAW,iBAAiB;IAChC,qCAAqC;IACrC,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,gFAAgF;IAChF,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAED;;;;GAIG;AACH,MAAM,WAAW,WAAW;IAC1B,6CAA6C;IAC7C,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,+CAA+C;IAC/C,QAAQ,CAAC,EAAE,CAAC,EAAE,MAAM,CAAC;IACrB,oEAAoE;IACpE,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,CAAC;IAC7B,oDAAoD;IACpD,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,gEAAgE;IAChE,QAAQ,CAAC,OAAO,EAAE,aAAa,CAAC,iBAAiB,CAAC,CAAC;IACnD,2EAA2E;IAC3E,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;CACtC;AAED;;;GAGG;AACH,MAAM,MAAM,aAAa,GAAG,MAAM,aAAa,CAAC,WAAW,GAAG,IAAI,CAAC,CAAC;AAEpE,wEAAwE;AACxE,MAAM,MAAM,qBAAqB,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,WAAW,GAAG,IAAI,KAAK,IAAI,CAAC;AAM1F;;;;GAIG;AACH,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;;;;;;CAkBnB,CAAC;AAEX,4DAA4D;AAC5D,eAAO,MAAM,aAAa;;;;;CAKhB,CAAC;AA2BX;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,CAM7D;AAMD,0CAA0C;AAC1C,MAAM,WAAW,mBAAmB;IAClC;;;OAGG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;OAGG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;CACtB;AA+BD,oEAAoE;AACpE,wBAAgB,kBAAkB,IAAI,OAAO,CAE5C;AAMD;;;;;GAKG;AACH,qBAAa,YAAY;IACvB,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAuB;IACpD,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAqB;IAClD,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAC,CAAS;IACxC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IAEnC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAqB;IAC3C,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAqB;IAC9C,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAqB;IAC/C,OAAO,CAAC,KAAK,CAAgB;IAC7B,OAAO,CAAC,aAAa,CAAgB;IAErC,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAyD;IACxF,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAyD;IAEtF,OAAO,CAAC,QAAQ,CAAS;IACzB,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAyB;IACpD,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAyB;IAEvD;;;;;;OAMG;gBAED,OAAO,GAAE,mBAAwB,EACjC,WAAW,CAAC,EAAE,aAAa,GAAG,IAAI,EAClC,WAAW,CAAC,EAAE,WAAW,GAAG,IAAI;IAmBlC,yEAAyE;IACzE,IAAI,SAAS,IAAI,OAAO,CAEvB;IAED,0DAA0D;IAC1D,IAAI,SAAS,IAAI,OAAO,CAEvB;IAED,+DAA+D;IAC/D,IAAI,SAAS,IAAI,OAAO,CAEvB;IAED;;;OAGG;IACH,MAAM,IAAI,IAAI;IASd;;;OAGG;IACH,OAAO,IAAI,IAAI;IASf;;;OAGG;IACH,OAAO,IAAI,IAAI;IAMf,0EAA0E;IAC1E,KAAK,IAAI,IAAI;IAYb;;;;;;;OAOG;IACH,IAAI,IAAI,IAAI;IAuCZ;;;;OAIG;IACH,MAAM,CAAC,GAAG,SAAI,GAAG,IAAI;IAQrB;;;OAGG;IACH,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO;IAK9C,4CAA4C;IAC5C,aAAa,IAAI,OAAO;IAIxB;;;;OAIG;IACH,gBAAgB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO;IAKlD;;;;OAIG;IACH,iBAAiB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO;IAKnD;;;;OAIG;IACH,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM;IAU/C;;;;;;OAMG;IACH,OAAO,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,GAAE,MAAuB,GAAG,MAAM;IAIjE;;;OAGG;IACH,YAAY,IAAI,CAAC,MAAM,EAAE,MAAM,CAAC;IAKhC,sEAAsE;IACtE,aAAa,IAAI,CAAC,MAAM,EAAE,MAAM,CAAC;IAIjC;;;;OAIG;IACH,kBAAkB,IAAI,CAAC,MAAM,EAAE,MAAM,CAAC;IActC,wEAAwE;IACxE,oBAAoB,IAAI,WAAW,EAAE;IAerC;;;;;OAKG;IACH,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,QAAQ,EAAE,qBAAqB,GAAG,WAAW;IAInF;;;;;OAKG;IACH,UAAU,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,QAAQ,EAAE,qBAAqB,GAAG,WAAW;IAQjF;;;;;;;OAOG;IACH,QAAQ,CACN,OAAO,EAAE,qBAAqB,EAC9B,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,MAAM,GAAG,MAAM,GACtB,WAAW;IASd;;;;;;OAMG;IACH,WAAW,CACT,OAAO,EAAE,qBAAqB,EAC9B,WAAW,EAAE,MAAM,EACnB,MAAM,EAAE,MAAM,GAAG,MAAM,GACtB,WAAW;IAId;;;;;;;OAOG;IACH,SAAS,CAAC,OAAO,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,OAAO,EAAE,gBAAgB,GAAG,WAAW;IAc9F,iFAAiF;IACjF,OAAO,CAAC,cAAc;IAetB,yEAAyE;IACzE,OAAO,CAAC,WAAW;IASnB,mEAAmE;IACnE,OAAO,CAAC,cAAc;IAItB,OAAO,CAAC,YAAY;IAepB,8EAA8E;IAC9E,OAAO,CAAC,YAAY;IASpB,OAAO,CAAC,KAAK;IASb,+EAA+E;IAC/E,OAAO,CAAC,cAAc;IAKtB,sEAAsE;IACtE,OAAO,CAAC,iBAAiB;CAI1B;AASD;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAC9B,OAAO,CAAC,EAAE,mBAAmB,EAC7B,WAAW,CAAC,EAAE,aAAa,GAAG,IAAI,EAClC,WAAW,CAAC,EAAE,WAAW,GAAG,IAAI,GAC/B,YAAY,CAEd"}

package/dist/interaction/KeyboardInput.d.ts

@@ -0,0 +1,210 @@
+/**
+ * KeyboardInput — a general-purpose keyboard controller for interactive apps
+ * and games.
+ *
+ * manim-web already has pointer interaction (`Clickable` / `Draggable` /
+ * `Hoverable`) and a `StateMachine`, but no general keyboard primitive. This
+ * controller tracks held keys, exposes per-frame edge queries (`wasPressed` /
+ * `wasReleased`), derives a movement vector from arrow keys and WASD, and binds
+ * a key to a `StateMachine` input or a `ValueTracker`. It makes the kind of
+ * interactive software and games that plain Manim cannot do first-class in the
+ * browser.
+ *
+ * All DOM access is feature-detected, so the controller is safe to construct
+ * in Node, jsdom, or a headless render. Without a window the reads return
+ * `false` or zero and never throw.
+ *
+ * @example
+ * ```typescript
+ * const keys = new KeyboardInput({ preventDefault: true });
+ * // In the render loop, each frame:
+ * function frame(dt: number): void {
+ *   const [dx, dy] = keys.getDirectionVector();
+ *   player.shift([dx * speed * dt, dy * speed * dt, 0]);
+ *   if (keys.wasPressed('Space')) player.jump();
+ *   keys.endFrame(); // clear the per-frame pressed/released edges
+ * }
+ * ```
+ */
+/** A per-key or wildcard callback. `key` is the normalized key name. */
+export type KeyCallback = (key: string, event: KeyboardEvent) => void;
+/** Unsubscribe from a callback registration. */
+export type Unsubscribe = () => void;
+/**
+ * Minimal view of a `StateMachine` for binding. Both `StateMachine.setInput`
+ * and `StateMachine.fire` match this, so no import of the class is needed.
+ */
+export interface StateMachineInputSink {
+    setInput(name: string, value: boolean | number): unknown;
+    fire(name: string): unknown;
+}
+/** Minimal view of a `ValueTracker` for binding. */
+export interface ValueSink {
+    setValue(value: number): unknown;
+}
+/** Options for a {@link KeyboardInput}. */
+export interface KeyboardInputOptions {
+    /**
+     * Call `preventDefault()` on handled key events. `true` applies to every
+     * key; an array restricts it to the listed (normalized) keys. Use it so game
+     * keys such as the arrows and Space do not scroll the page. Default `false`.
+     */
+    preventDefault?: boolean | string[];
+    /**
+     * Attach the listeners immediately on construction. Set `false` to attach
+     * later with {@link KeyboardInput.enable}. Default `true`.
+     */
+    autoEnable?: boolean;
+}
+/** Options for {@link KeyboardInput.bindValue}. */
+export interface BindValueOptions {
+    /** Value written to the tracker while the key is held. */
+    heldValue: number;
+    /** Value written when the key is released. Default `0`. */
+    releasedValue?: number;
+}
+/**
+ * Normalize a raw `KeyboardEvent.key` or a user query to a canonical,
+ * lowercase name. `'ArrowUp'`, `'W'`, and `' '` become `'arrowup'`, `'w'`, and
+ * `'space'`, so a held key reads back under any common spelling.
+ * @param key - A raw key name.
+ * @returns The canonical key name.
+ */
+export declare function normalizeKey(key: string): string;
+/**
+ * Tracks keyboard state for interactive apps and games. Mirrors the
+ * `Clickable` / `OrbitControls` lifecycle: construct, then
+ * {@link enable} / {@link disable} / {@link dispose}.
+ */
+export declare class KeyboardInput {
+    private readonly _target;
+    private readonly _preventDefault;
+    private readonly _down;
+    private readonly _pressed;
+    private readonly _released;
+    private readonly _downCallbacks;
+    private readonly _upCallbacks;
+    private _enabled;
+    private readonly _onKeyDown;
+    private readonly _onKeyUp;
+    /**
+     * Create a KeyboardInput.
+     * @param options - Behavior options.
+     * @param domTarget - Event target for key events. Defaults to `window` (or
+     *   `document`), or `null` when no DOM is present.
+     */
+    constructor(options?: KeyboardInputOptions, domTarget?: EventTarget | null);
+    /** Whether the listeners are attached. */
+    get isEnabled(): boolean;
+    /** Whether a DOM target is available. `false` in a headless environment. */
+    get hasTarget(): boolean;
+    /**
+     * Attach the key listeners. A no-op when already enabled or headless.
+     */
+    enable(): void;
+    /**
+     * Detach the key listeners and clear all held and edge state, so no key stays
+     * stuck. Reads return defaults until {@link enable} is called again.
+     */
+    disable(): void;
+    /**
+     * Detach listeners and drop every registered callback. Use when the
+     * controller is no longer needed.
+     */
+    dispose(): void;
+    /** Clear held keys and both per-frame edge sets. */
+    clear(): void;
+    /**
+     * Whether the key is held right now.
+     * @param key - A key name in any common spelling (`'ArrowUp'`, `'w'`, `' '`).
+     */
+    isKeyDown(key: string): boolean;
+    /** Whether any key is held right now. */
+    anyKeyDown(): boolean;
+    /**
+     * Whether the key went down during the current frame. Cleared by
+     * {@link update} / {@link endFrame}. Key auto-repeat does not re-fire it.
+     * @param key - A key name in any common spelling.
+     */
+    wasPressed(key: string): boolean;
+    /**
+     * Whether the key came up during the current frame. Cleared by
+     * {@link update} / {@link endFrame}.
+     * @param key - A key name in any common spelling.
+     */
+    wasReleased(key: string): boolean;
+    /**
+     * The raw movement axes from the arrow keys and WASD, each component in
+     * `{-1, 0, 1}`. Up is +y and right is +x; opposite keys cancel.
+     * @returns `[x, y]`.
+     */
+    getAxis(): [number, number];
+    /**
+     * The movement vector from {@link getAxis}, normalized to unit length so a
+     * diagonal is not faster than a straight line. A zero axis stays `[0, 0]`.
+     * @returns `[x, y]`.
+     */
+    getDirectionVector(): [number, number];
+    /**
+     * Register a key-down callback. Repeated auto-repeat events do not re-fire it.
+     * @param key - A key name, or `'any'` for every key.
+     * @param callback - Called with the normalized key and the event.
+     * @returns An unsubscribe function.
+     */
+    onKeyDown(key: string, callback: KeyCallback): Unsubscribe;
+    /**
+     * Register a key-up callback.
+     * @param key - A key name, or `'any'` for every key.
+     * @param callback - Called with the normalized key and the event.
+     * @returns An unsubscribe function.
+     */
+    onKeyUp(key: string, callback: KeyCallback): Unsubscribe;
+    /**
+     * Hold a `StateMachine` bool input to match a key: `true` while held, `false`
+     * on release.
+     * @param machine - The `StateMachine` (or any {@link StateMachineInputSink}).
+     * @param inputName - The bool input name.
+     * @param key - The key to track.
+     * @returns An unsubscribe function.
+     */
+    bindBool(machine: StateMachineInputSink, inputName: string, key: string): Unsubscribe;
+    /**
+     * Fire a `StateMachine` trigger input on each key-down.
+     * @param machine - The `StateMachine` (or any {@link StateMachineInputSink}).
+     * @param triggerName - The trigger input name.
+     * @param key - The key to track.
+     * @returns An unsubscribe function.
+     */
+    bindTrigger(machine: StateMachineInputSink, triggerName: string, key: string): Unsubscribe;
+    /**
+     * Drive a `ValueTracker` from a key: `heldValue` while held, `releasedValue`
+     * on release.
+     * @param tracker - The `ValueTracker` (or any {@link ValueSink}).
+     * @param key - The key to track.
+     * @param options - The held and released values.
+     * @returns An unsubscribe function.
+     */
+    bindValue(tracker: ValueSink, key: string, options: BindValueOptions): Unsubscribe;
+    /**
+     * Clear the per-frame pressed and released edge sets. Call once per frame
+     * after reading {@link wasPressed} / {@link wasReleased}.
+     * @param _dt - Delta time (seconds), accepted for render-loop compatibility.
+     */
+    update(_dt?: number): void;
+    /** Alias of {@link update} that clears the per-frame edge sets. */
+    endFrame(): void;
+    private _anyDown;
+    private _handleKeyDown;
+    private _handleKeyUp;
+    private _maybePreventDefault;
+    private _addCallback;
+    private _emit;
+}
+/**
+ * Factory for a {@link KeyboardInput}.
+ * @param options - Behavior options.
+ * @param domTarget - Event target for key events.
+ * @returns A new KeyboardInput.
+ */
+export declare function makeKeyboardInput(options?: KeyboardInputOptions, domTarget?: EventTarget | null): KeyboardInput;
+//# sourceMappingURL=KeyboardInput.d.ts.map

package/dist/interaction/KeyboardInput.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"KeyboardInput.d.ts","sourceRoot":"","sources":["../../src/interaction/KeyboardInput.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,wEAAwE;AACxE,MAAM,MAAM,WAAW,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,aAAa,KAAK,IAAI,CAAC;AAEtE,gDAAgD;AAChD,MAAM,MAAM,WAAW,GAAG,MAAM,IAAI,CAAC;AAErC;;;GAGG;AACH,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,OAAO,CAAC;IACzD,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC;CAC7B;AAED,oDAAoD;AACpD,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC;CAClC;AAED,2CAA2C;AAC3C,MAAM,WAAW,oBAAoB;IACnC;;;;OAIG;IACH,cAAc,CAAC,EAAE,OAAO,GAAG,MAAM,EAAE,CAAC;IACpC;;;OAGG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;CACtB;AAED,mDAAmD;AACnD,MAAM,WAAW,gBAAgB;IAC/B,0DAA0D;IAC1D,SAAS,EAAE,MAAM,CAAC;IAClB,2DAA2D;IAC3D,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAcD;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAGhD;AAyBD;;;;GAIG;AACH,qBAAa,aAAa;IACxB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAqB;IAC7C,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAwB;IAExD,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAqB;IAC3C,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAqB;IAC9C,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAqB;IAE/C,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAuC;IACtE,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAuC;IAEpE,OAAO,CAAC,QAAQ,CAAS;IACzB,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAiC;IAC5D,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAiC;IAE1D;;;;;OAKG;gBACS,OAAO,GAAE,oBAAyB,EAAE,SAAS,CAAC,EAAE,WAAW,GAAG,IAAI;IAc9E,0CAA0C;IAC1C,IAAI,SAAS,IAAI,OAAO,CAEvB;IAED,4EAA4E;IAC5E,IAAI,SAAS,IAAI,OAAO,CAEvB;IAED;;OAEG;IACH,MAAM,IAAI,IAAI;IAOd;;;OAGG;IACH,OAAO,IAAI,IAAI;IASf;;;OAGG;IACH,OAAO,IAAI,IAAI;IAMf,oDAAoD;IACpD,KAAK,IAAI,IAAI;IAMb;;;OAGG;IACH,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO;IAI/B,yCAAyC;IACzC,UAAU,IAAI,OAAO;IAIrB;;;;OAIG;IACH,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO;IAIhC;;;;OAIG;IACH,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO;IAIjC;;;;OAIG;IACH,OAAO,IAAI,CAAC,MAAM,EAAE,MAAM,CAAC;IAM3B;;;;OAIG;IACH,kBAAkB,IAAI,CAAC,MAAM,EAAE,MAAM,CAAC;IAOtC;;;;;OAKG;IACH,SAAS,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,WAAW,GAAG,WAAW;IAI1D;;;;;OAKG;IACH,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,WAAW,GAAG,WAAW;IAIxD;;;;;;;OAOG;IACH,QAAQ,CAAC,OAAO,EAAE,qBAAqB,EAAE,SAAS,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,WAAW;IASrF;;;;;;OAMG;IACH,WAAW,CAAC,OAAO,EAAE,qBAAqB,EAAE,WAAW,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,WAAW;IAI1F;;;;;;;OAOG;IACH,SAAS,CAAC,OAAO,EAAE,SAAS,EAAE,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,gBAAgB,GAAG,WAAW;IAUlF;;;;OAIG;IACH,MAAM,CAAC,GAAG,SAAI,GAAG,IAAI;IAIrB,mEAAmE;IACnE,QAAQ,IAAI,IAAI;IAKhB,OAAO,CAAC,QAAQ;IAIhB,OAAO,CAAC,cAAc;IAUtB,OAAO,CAAC,YAAY;IAQpB,OAAO,CAAC,oBAAoB;IAO5B,OAAO,CAAC,YAAY;IAepB,OAAO,CAAC,KAAK;CAId;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAC/B,OAAO,CAAC,EAAE,oBAAoB,EAC9B,SAAS,CAAC,EAAE,WAAW,GAAG,IAAI,GAC7B,aAAa,CAEf"}

package/dist/interaction/index.d.ts

@@ -12,6 +12,8 @@ export { Slider, makeSlider, type SliderOptions } from './Slider';
 export { MatrixTracker, makeMatrixTracker, applyMatrixLive, type Matrix2x2, type MatrixSource, type BasisVectorSource, type DependentPoint, type DynamicMatrixOptions, type LiveMatrixBinding, } from './DynamicMatrix';
 export { SelectionManager, type SelectionManagerOptions } from './SelectionManager';
 export { StateMachine, GuardBuilder, when, allOf, anyOf, type InputValue, type InputKind, type InputsSnapshot, type Guard, type StateContext, type StateAction, type StateConfig, type TransitionConfig, type StateMachineOptions, } from './StateMachine';
+export { KeyboardInput, makeKeyboardInput, normalizeKey, type KeyboardInputOptions, type KeyCallback, type Unsubscribe, type StateMachineInputSink, type ValueSink, type BindValueOptions, } from './KeyboardInput';
+export { GamepadInput, makeGamepadInput, resolveButton, isGamepadSupported, STANDARD_BUTTONS, STANDARD_AXES, type GamepadInputOptions, type GamepadButtonLike, type GamepadLike, type GamepadSource, type GamepadButtonCallback, } from './GamepadInput';
 export { OrbitControls, type OrbitControlsOptions } from './OrbitControls';
 export { PanZoomControls, makePanZoomControls, type PanZoomControlsOptions, type PanZoomCamera, type PanZoomBounds, } from './PanZoomControls';
 //# sourceMappingURL=index.d.ts.map

package/dist/interaction/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/interaction/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EACL,QAAQ,EACR,KAAK,eAAe,EACpB,KAAK,gBAAgB,EACrB,KAAK,aAAa,EAClB,KAAK,YAAY,EACjB,KAAK,YAAY,EACjB,KAAK,cAAc,EACnB,KAAK,iBAAiB,GACvB,MAAM,YAAY,CAAC;AAEpB,OAAO,EACL,gBAAgB,EAChB,KAAK,uBAAuB,EAC5B,KAAK,kBAAkB,GACxB,MAAM,oBAAoB,CAAC;AAG5B,OAAO,EAAE,SAAS,EAAE,aAAa,EAAE,KAAK,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAC9E,OAAO,EAAE,SAAS,EAAE,aAAa,EAAE,KAAK,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAC9E,OAAO,EAAE,SAAS,EAAE,aAAa,EAAE,KAAK,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAG9E,OAAO,EAAE,YAAY,EAAE,gBAAgB,EAAE,KAAK,mBAAmB,EAAE,MAAM,gBAAgB,CAAC;AAC1F,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,KAAK,aAAa,EAAE,MAAM,UAAU,CAAC;AAGlE,OAAO,EACL,aAAa,EACb,iBAAiB,EACjB,eAAe,EACf,KAAK,SAAS,EACd,KAAK,YAAY,EACjB,KAAK,iBAAiB,EACtB,KAAK,cAAc,EACnB,KAAK,oBAAoB,EACzB,KAAK,iBAAiB,GACvB,MAAM,iBAAiB,CAAC;AAGzB,OAAO,EAAE,gBAAgB,EAAE,KAAK,uBAAuB,EAAE,MAAM,oBAAoB,CAAC;AAGpF,OAAO,EACL,YAAY,EACZ,YAAY,EACZ,IAAI,EACJ,KAAK,EACL,KAAK,EACL,KAAK,UAAU,EACf,KAAK,SAAS,EACd,KAAK,cAAc,EACnB,KAAK,KAAK,EACV,KAAK,YAAY,EACjB,KAAK,WAAW,EAChB,KAAK,WAAW,EAChB,KAAK,gBAAgB,EACrB,KAAK,mBAAmB,GACzB,MAAM,gBAAgB,CAAC;AAGxB,OAAO,EAAE,aAAa,EAAE,KAAK,oBAAoB,EAAE,MAAM,iBAAiB,CAAC;AAC3E,OAAO,EACL,eAAe,EACf,mBAAmB,EACnB,KAAK,sBAAsB,EAC3B,KAAK,aAAa,EAClB,KAAK,aAAa,GACnB,MAAM,mBAAmB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/interaction/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EACL,QAAQ,EACR,KAAK,eAAe,EACpB,KAAK,gBAAgB,EACrB,KAAK,aAAa,EAClB,KAAK,YAAY,EACjB,KAAK,YAAY,EACjB,KAAK,cAAc,EACnB,KAAK,iBAAiB,GACvB,MAAM,YAAY,CAAC;AAEpB,OAAO,EACL,gBAAgB,EAChB,KAAK,uBAAuB,EAC5B,KAAK,kBAAkB,GACxB,MAAM,oBAAoB,CAAC;AAG5B,OAAO,EAAE,SAAS,EAAE,aAAa,EAAE,KAAK,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAC9E,OAAO,EAAE,SAAS,EAAE,aAAa,EAAE,KAAK,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAC9E,OAAO,EAAE,SAAS,EAAE,aAAa,EAAE,KAAK,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAG9E,OAAO,EAAE,YAAY,EAAE,gBAAgB,EAAE,KAAK,mBAAmB,EAAE,MAAM,gBAAgB,CAAC;AAC1F,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,KAAK,aAAa,EAAE,MAAM,UAAU,CAAC;AAGlE,OAAO,EACL,aAAa,EACb,iBAAiB,EACjB,eAAe,EACf,KAAK,SAAS,EACd,KAAK,YAAY,EACjB,KAAK,iBAAiB,EACtB,KAAK,cAAc,EACnB,KAAK,oBAAoB,EACzB,KAAK,iBAAiB,GACvB,MAAM,iBAAiB,CAAC;AAGzB,OAAO,EAAE,gBAAgB,EAAE,KAAK,uBAAuB,EAAE,MAAM,oBAAoB,CAAC;AAGpF,OAAO,EACL,YAAY,EACZ,YAAY,EACZ,IAAI,EACJ,KAAK,EACL,KAAK,EACL,KAAK,UAAU,EACf,KAAK,SAAS,EACd,KAAK,cAAc,EACnB,KAAK,KAAK,EACV,KAAK,YAAY,EACjB,KAAK,WAAW,EAChB,KAAK,WAAW,EAChB,KAAK,gBAAgB,EACrB,KAAK,mBAAmB,GACzB,MAAM,gBAAgB,CAAC;AAGxB,OAAO,EACL,aAAa,EACb,iBAAiB,EACjB,YAAY,EACZ,KAAK,oBAAoB,EACzB,KAAK,WAAW,EAChB,KAAK,WAAW,EAChB,KAAK,qBAAqB,EAC1B,KAAK,SAAS,EACd,KAAK,gBAAgB,GACtB,MAAM,iBAAiB,CAAC;AAGzB,OAAO,EACL,YAAY,EACZ,gBAAgB,EAChB,aAAa,EACb,kBAAkB,EAClB,gBAAgB,EAChB,aAAa,EACb,KAAK,mBAAmB,EACxB,KAAK,iBAAiB,EACtB,KAAK,WAAW,EAChB,KAAK,aAAa,EAClB,KAAK,qBAAqB,GAC3B,MAAM,gBAAgB,CAAC;AAGxB,OAAO,EAAE,aAAa,EAAE,KAAK,oBAAoB,EAAE,MAAM,iBAAiB,CAAC;AAC3E,OAAO,EACL,eAAe,EACf,mBAAmB,EACnB,KAAK,sBAAsB,EAC3B,KAAK,aAAa,EAClB,KAAK,aAAa,GACnB,MAAM,mBAAmB,CAAC"}