@thunderclap-engine/engine 0.0.0-stage → 1.1.0

package/dist/input/input.d.ts

@@ -0,0 +1,543 @@
+import type { Gestures } from './gestures.js';
+import { type Glyph, type PadLayout } from './glyphs.js';
+import type { Look } from './look.js';
+import { type PointerDispatcher, type PointerRecord } from './pointer-dispatch.js';
+import type { PointerRouter } from './pointer-router.js';
+import type { InputPlayback, InputRecorder } from './record.js';
+import type { ActionState, Binding, Bindings, GamepadLike, InputDevice, PointerState, PointerTransform } from './types.js';
+export interface InputOptions {
+    /** Gamepad source. Default: `navigator.getGamepads()` (guarded). */
+    getGamepads?: () => readonly (GamepadLike | null)[];
+    /**
+     * While this returns true (e.g. a modal UI panel is open) every action reads inactive and no
+     * keys are `preventDefault`ed. Raw state keeps tracking so nothing sticks on unblock.
+     */
+    blocked?: () => boolean;
+    /**
+     * Key codes that still register while a button, link or other non-text control has focus
+     * (e.g. HUD shortcuts after clicking a HUD button). They never register in text entry and
+     * are not preventDefaulted on interactive targets. See `setGlobalKeys`.
+     */
+    globalKeys?: Iterable<string>;
+    /**
+     * Key codes that still register while a plain button or link has focus (`isButtonTarget`),
+     * but not on form controls that use them (sliders, checkboxes, selects, text). For keys
+     * like Escape and the arrows: a clicked button shouldn't swallow "back" or navigation.
+     * Like global keys they are not preventDefaulted there. See `setButtonKeys`.
+     */
+    buttonKeys?: Iterable<string>;
+    /**
+     * Queue repeat taps: when a key or mouse button goes down again before the tick that saw
+     * its first press, each extra tap fires `pressed` on a following tick instead of merging
+     * into one. Default true; pass false for the old one-press-per-tick behaviour.
+     */
+    queueTaps?: boolean;
+    /** Gestures to link (see `Input.setGestures`). */
+    gestures?: Gestures;
+    /** Pointer router to link (see `Input.setPointers`). */
+    pointers?: PointerRouter<any>;
+    /** Look controls to link (see `Input.setLook`). */
+    look?: Look;
+    /**
+     * Ms per `update()` tick, the clock `'hold'` and `'doubleTap'` triggers and `listen` timeouts
+     * count in (ws/input-3). Default 1000/60. Pass the game's fixed step so `holdMs` means ms.
+     */
+    tickMs?: number;
+    /** Pad button naming for `glyphFor`; default guessed from the first connected pad's `id`. */
+    padLayout?: PadLayout;
+}
+/** `Input` events (`Input.on`). */
+export interface InputEvents {
+    /** `lastDevice` changed. */
+    device: InputDevice;
+    /** `rumble` was issued (whether or not a pad could play it). */
+    rumble: RumbleOptions;
+    /** `attach` built its pointer dispatcher (touch zones and other consumers join here). */
+    attach: PointerDispatcher;
+    /** `detach` is about to destroy the dispatcher. */
+    detach: PointerDispatcher;
+    /** The top action context changed (`pushContext`, `popContext`): its name, `null` for none. */
+    context: string | null;
+    /**
+     * A playback replayed an overlay control's activation (`replayControl`, the recording's `ui`
+     * lane; ws/input-12): its stable id. `createGame` activates the overlay control with that id
+     * (`Overlay.activate`). A live `control(id)` does not emit it: the control's handler ran.
+     */
+    control: string;
+}
+/**
+ * What a pushed action context lets through for the actions it does not bind (ws/input-5):
+ * `'unbound'` falls through to the context below, `'none'` silences them, `'all'` falls through
+ * and also adds the context below's bindings to the ones it does bind.
+ */
+export type ContextPass = 'none' | 'unbound' | 'all';
+/** `Input.pushContext` options. */
+export interface ContextOptions<A extends string> {
+    /**
+     * The context's own bindings. Default none. An action the base map lacks is added
+     * (ws/api-core): it reads inactive below this context and after it pops, never throws.
+     */
+    bindings?: Partial<Bindings<A>>;
+    /** What happens to the actions it does not bind. Default `'unbound'`. */
+    pass?: ContextPass;
+}
+/** How `shapeStick` and `Input.stick` treat the deadzone (ws/input-5). */
+export type StickShape = 'radial' | 'axial' | 'scaledRadial';
+/** `shapeStick` / `Input.stick` options. */
+export interface StickOptions {
+    /** Below this length (each axis for `'axial'`) the stick reads 0. 0..1, default 0.15. */
+    deadzone?: number;
+    /**
+     * `'scaledRadial'` (default): a radial deadzone, the rest rescaled so its edge is 0 and full
+     * deflection 1 (continuous). `'radial'`: a radial deadzone, the rest passed through as is.
+     * `'axial'`: each axis has its own deadzone, passed through (cardinal snapping).
+     */
+    shape?: StickShape;
+    /** Exponent on the shaped length (each axis for `'axial'`): 2 is finer near the centre. Default 1. */
+    curve?: number;
+    /** Clamp the length to 1 (diagonal keys read 1, not √2). Default true. */
+    clamp?: boolean;
+}
+/** The phase of a pointer the feed saw (`InputFeedHook.pointer`, the recording's `ptr` lane). */
+export type InputPointerPhase = 'down' | 'move' | 'up' | 'cancel' | 'leave';
+/**
+ * Shape a stick (x, y) through a deadzone into `out` and return it (ws/input-5). Pure and
+ * allocation-free; `Input.stick` reads four actions through it and `Look` reads the pad sticks
+ * and the touch stick through it. See `StickOptions` for the shapes.
+ */
+export declare function shapeStick(x: number, y: number, out: [number, number], opts?: StickOptions): [number, number];
+/**
+ * Something that feeds action values from outside the bindings (ws/input-4): touch zones. The
+ * input calls `update()` every tick before evaluating actions, then `value(action)` per action
+ * (0..1, folded in like a `press` binding) and `fresh(action)` for a new press while already
+ * active (a repeated button tap).
+ */
+export interface ActionSource {
+    update?(): void;
+    value(action: string): number;
+    fresh?(action: string): boolean;
+}
+/** `Input.rumble` parameters: magnitudes 0..1, duration in ms. */
+export interface RumbleOptions {
+    /** Low-frequency motor, 0..1. Default 1. */
+    strong?: number;
+    /** High-frequency motor, 0..1. Default 1. */
+    weak?: number;
+    /** Duration in ms. Default 100. */
+    ms?: number;
+    /** Pad index; default the first connected pad that can rumble. */
+    pad?: number;
+}
+/** `Input.listen` options. */
+export interface ListenOptions {
+    /** Give up (resolve `null`) after this many ms of ticks. Default: never. */
+    timeoutMs?: number;
+}
+/** Default `holdMs` for `trigger: 'hold'`. */
+export declare const DEFAULT_HOLD_MS = 400;
+/** Default `doubleTapMs` for `trigger: 'doubleTap'`. */
+export declare const DEFAULT_DOUBLE_TAP_MS = 300;
+/**
+ * Sees every low-level feed call and the pads `update()` reads, in call order. `input/record.ts`
+ * builds the two implementations (`createInputRecorder`, `createInputPlayback`); `Input.onFeed`
+ * installs one. Nothing here changes how `Input` evaluates bindings.
+ */
+export interface InputFeedHook {
+    keyDown(code: string): void;
+    keyUp(code: string): void;
+    buttonDown(button: number): void;
+    buttonUp(button: number): void;
+    wheel(dx: number, dy: number): void;
+    pointerAt(clientX: number, clientY: number, type: PointerState['type']): void;
+    releaseAll(): void;
+    /** Called once per `update()` with the pads `getGamepads` returned; what it returns is used. */
+    gamepads(pads: readonly (GamepadLike | null)[]): readonly (GamepadLike | null)[];
+    /**
+     * Replace this tick's pads before anything reads them (ws/input-9): called once per `update()`,
+     * before gestures and a linked look advance, with the pads `getGamepads` returned. A playback
+     * returns its recorded snapshot here, so the linked look turns from the recorded sticks too.
+     * `gamepads` then sees what this returned.
+     */
+    padSource?(pads: readonly (GamepadLike | null)[]): readonly (GamepadLike | null)[];
+    /** Sees every `rumble` call (ws/input-3), after defaults are applied. */
+    rumble?(strong: number, weak: number, ms: number, pad: number | undefined): void;
+    /**
+     * Sees every pointer the attached dispatcher delivers, claimed or not, primary or not
+     * (ws/input-5): the recorder's `ptr` lane. The record is reused; copy what you keep.
+     */
+    pointer?(phase: InputPointerPhase, p: Readonly<PointerRecord>): void;
+    /** The dispatcher dropped every pointer (window blur, hidden tab). */
+    cancelPointers?(): void;
+    /** `pushContext` (`pushed` true) or a context's removal (false). */
+    context?(name: string, pushed: boolean): void;
+    /** `consume(action)` was called. */
+    consume?(action: string): void;
+    /** `control(id)` was called: an overlay control with that stable id fired (ws/input-12). */
+    control?(id: string): void;
+}
+export interface AttachOptions {
+    /** Element that receives pointer/wheel input (the canvas, or the element wrapping it). */
+    pointerTarget: HTMLElement;
+    /** Where keyboard events are read. Default: the pointer target's window. */
+    keyTarget?: Window | HTMLElement;
+    /** Set `touch-action: none` on the pointer target so touch drags don't scroll/zoom. Default true. */
+    disableTouchScroll?: boolean;
+    /**
+     * Let a pointer claimed through the dispatcher (an orbit drag, a touch-zone thumb) still hover
+     * the linked router (`hit`/`hitEnd`, no select). Default false: a claimed pointer is hidden
+     * from the router until it is released.
+     */
+    hoverWhileClaimed?: boolean;
+    /**
+     * The element whose box pointer positions are measured against (ws/core-8;
+     * `PointerDispatcherOptions.bounds`). Default the pointer target. `createGame`'s replay sink
+     * passes the canvas, so a recorded touch stick or touch zone replays at its recorded place.
+     */
+    bounds?: Element;
+}
+/** True for elements where keys type text (text inputs, textareas, selects, contenteditable). */
+export declare function isTextEntryTarget(target: EventTarget | null): boolean;
+/**
+ * True for plain activatable controls (buttons, links, `summary`, button-type inputs,
+ * `role=button|link|menuitem`) whose own keys are only Enter and Space.
+ */
+export declare function isButtonTarget(target: EventTarget | null): boolean;
+/** True for elements that own their keyboard input (text fields, buttons, links, …). */
+export declare function isInteractiveTarget(target: EventTarget | null): boolean;
+/**
+ * Action-mapped input. Feed it raw events (via `attach` or the low-level methods), call
+ * `update()` once per simulation tick, then query actions.
+ *
+ * ```ts
+ * const input = new Input({ confirm: [{ key: 'Enter' }, { key: 'Space' }, { padButton: 0 }],
+ *                           cancel:  [{ key: 'Escape' }, { padButton: 1 }] });
+ * input.attach({ pointerTarget: canvas });
+ * input.setPointerTransform(platform.clientToLogical);
+ * // each tick:
+ * input.update();
+ * if (input.pressed('confirm')) …
+ * ```
+ *
+ * `A` is the full action union. The base map may leave some out (ws/input-12): an action only a
+ * pushed context binds (`new Input<'jump' | 'back'>({ jump }, …)`, then
+ * `pushContext('menu', { bindings: { back } })`) is typed everywhere and reads inactive until a
+ * context binds it. `bindings()` lists the actions bound so far.
+ */
+export declare class Input<A extends string> {
+    readonly pointer: PointerState;
+    blocked: () => boolean;
+    /** Pad button naming for `glyphFor` (`InputOptions.padLayout`); `null` guesses from the pad's `id`. */
+    padLayout: PadLayout | null;
+    /** Ms per tick (`InputOptions.tickMs`). */
+    readonly tickMs: number;
+    /** The recorder capturing this input's feed (`createInputRecorder`), until `stop()`. */
+    recorder: InputRecorder | null;
+    /** The playback feeding this input (`createInputPlayback`), until `detach()`. */
+    playback: InputPlayback | null;
+    /** Feed hooks in install order (`onFeed`). Read-only for callers. */
+    private readonly feedHooks;
+    /** The base bindings (below every context). */
+    private map;
+    /** The bindings in force: `map` with the context stack resolved over it (`map` when empty). */
+    private active;
+    /** Pushed contexts, bottom first. */
+    private readonly stack;
+    /** Actions a context added that the base map lacks (`pushContext`); bound to nothing below it. */
+    private extraActions;
+    /** `stack`'s names, bottom first (the `contexts` getter). */
+    private contextNames;
+    /** The latest press per action (`buffered`, `consume`). */
+    private readonly presses;
+    /** True while `replayPointer` dispatches: the feed consumer then leaves the raw state alone. */
+    private injecting;
+    private readonly states;
+    private readonly triggers;
+    private readonly events;
+    private deviceValue;
+    /** Ticks since construction (the trigger clock). */
+    private tick;
+    private listenState;
+    /** Last client-space pointer position fed through `pointerAt` (the orbit drag's coordinates). */
+    private clientX;
+    private clientY;
+    private readonly claimFn;
+    private readonly getGamepads;
+    private transform;
+    private readonly keysDown;
+    private readonly keysTapped;
+    private readonly buttonsDown;
+    private readonly buttonsTapped;
+    /** Extra taps queued per key/button (see `InputOptions.queueTaps`). */
+    private readonly keyRepeats;
+    private readonly buttonRepeats;
+    private readonly queueTaps;
+    private globalKeys;
+    private buttonKeys;
+    private wheelAccX;
+    private wheelAccY;
+    private prevX;
+    private prevY;
+    private boundKeys;
+    private boundMouse;
+    private boundWheel;
+    private pads;
+    /** `this.pads`, bound once, for a linked look (`Look.padsFromInput`). */
+    private readonly readTickPads;
+    /** Keys and mouse buttons that were down or tapped on the last tick. */
+    private readonly prevKeys;
+    private readonly prevButtons;
+    private detachFn;
+    private linkedGestures;
+    private linkedPointers;
+    private linkedLook;
+    private attached;
+    private dispatcherValue;
+    private readonly updatedFns;
+    private readonly actionSources;
+    private readonly actionReader;
+    constructor(bindings: Partial<Bindings<A>>, opts?: InputOptions);
+    /**
+     * Device that produced the most recent input (updated on real events: keys, pointer events,
+     * pad activity, XR button presses). Useful for showing the right button prompts; `on('device')`
+     * fires when it changes.
+     */
+    get lastDevice(): InputDevice;
+    set lastDevice(device: InputDevice);
+    /** Subscribe to an `InputEvents` event; returns the unsubscriber. */
+    on<K extends keyof InputEvents>(type: K, fn: (payload: InputEvents[K]) => void): () => void;
+    /**
+     * Link gestures (or unlink with `null`). Linked gestures share this input's `blocked()` and
+     * pointer transform, attach to the same pointer target, and advance in `update()` before the
+     * actions are read, so `{ gesture }` bindings work. Don't call `gestures.update()` yourself.
+     */
+    setGestures(gestures: Gestures | null): void;
+    /** The linked gestures (`setGestures`), or `null`. */
+    get gestures(): Gestures | null;
+    /**
+     * Link a pointer router (or unlink with `null`). A linked router shares this input's
+     * `blocked()`, pointer transform (client → camera screen units) and gestures (the magnify aim),
+     * attaches to the same pointer target, and is polled in `update()` before the actions are
+     * read, so `{ pointer }` and `{ xr }` bindings work; after them its `select` and `secondary`
+     * events follow the actions named by `selectAction` / `secondaryAction` when bound. Don't call
+     * `router.update()` yourself.
+     */
+    setPointers<T>(router: PointerRouter<T> | null): void;
+    /** The linked pointer router (`setPointers`), or `null`. */
+    get pointers(): PointerRouter<unknown> | null;
+    /**
+     * Link look controls (or unlink with `null`). Linked, they share this input's `blocked()`, read
+     * their move keys from its raw key state, attach to the same pointer target and advance in
+     * `update()`, so `look.look` and `look.move` are this tick's. Don't call `look.update()` yourself.
+     */
+    setLook(look: Look | null): void;
+    /**
+     * The pointer dispatcher `attach` built (one DOM listener set shared by the feed, gestures,
+     * look, router and touch zones), or `null` while detached.
+     */
+    get dispatcher(): PointerDispatcher | null;
+    /**
+     * Run `fn` at the end of every `update()`, after gestures, look, router and triggers have
+     * advanced (same tick, registration order): the place to poll a world panel or read
+     * `pressed()` for the frame. Returns the remover.
+     */
+    onUpdated(fn: () => void): () => void;
+    /** Add an `ActionSource` (touch zones). Returns the remover. */
+    addActionSource(src: ActionSource): () => void;
+    /** `value(positive) - value(negative)`, -1..1: a move axis from two actions. */
+    axis(negative: A, positive: A): number;
+    /**
+     * Gives the linked gestures the look's pointer claim (an orbit drag is never a pan) when the
+     * gestures have no claim of their own; takes it back when the look unlinks.
+     */
+    private wireClaim;
+    /** The linked look controls (`setLook`), or `null`. */
+    get look(): Look | null;
+    /**
+     * Replace the base bindings (below every pushed context). Action states and the input buffer
+     * reset (use `rebind` to change one action and keep the rest). The map may leave out actions
+     * of `A` (ws/input-12): a pushed context binds those.
+     */
+    setBindings(bindings: Partial<Bindings<A>>): void;
+    /**
+     * Replace one action's bindings, keeping every other action's state (ws/input-3). Rebinding
+     * while an input is held is safe: the old action sees `released` next tick, and a new binding
+     * whose input is already down reads inactive until it lifts and goes down again.
+     *
+     * With contexts pushed (ws/input-5) it writes into the top context (the action becomes one that
+     * context binds); `context` names another pushed context instead, `null` the base map.
+     */
+    rebind(action: A, list: readonly Binding[], context?: string | null): void;
+    /**
+     * The bindings in force (what `serializeBindings` saves): the base map with the pushed
+     * contexts resolved over it. `context` reads one context's own bindings over the ones below
+     * it as if it were on top (`null`: the base map).
+     */
+    bindings(context?: string | null): Bindings<A>;
+    /**
+     * Push an action context (ws/input-5): a menu, gameplay, a vehicle, each with its own bindings.
+     * The top context's bindings win; `pass` says what happens to the actions it does not bind
+     * (default `'unbound'`: they fall through). Pushing a name already on the stack moves it to the
+     * top with the new options. Every action whose bindings in force change resets its hold
+     * progress, tap counts and buffered press, and a binding whose input is already down reads
+     * inactive until it lifts, so a held key never fires across the change. Returns the remover
+     * (it removes this push only).
+     */
+    pushContext(name: string, opts?: ContextOptions<A>): () => void;
+    /** Remove the topmost context named `name`. Returns false when none is pushed. */
+    popContext(name: string): boolean;
+    /** The top context's name, `null` with none pushed. */
+    get context(): string | null;
+    /** The pushed context names, bottom first. One array, rebuilt when the stack changes. */
+    get contexts(): readonly string[];
+    /** Shorthand for `on('context', fn)`: the top context changed. Returns the remover. */
+    onContextChange(fn: (name: string | null) => void): () => void;
+    private removeContextAt;
+    private contextIndex;
+    /** The context `rebind` writes to: `undefined` the top one (or none), `null` none, else by name. */
+    private contextEntry;
+    /** Give a context's actions the base map lacks a state (bound to nothing below the context). */
+    private addContextActions;
+    /** The bindings in force with contexts `0..top` on the stack (all of them by default). */
+    private resolveContexts;
+    private resolveAction;
+    /**
+     * Recompute the bindings in force; every action whose list changed (element by element), and
+     * `force` too, gets fresh trigger state, latched where its input is down, and loses its
+     * buffered press.
+     */
+    private applyActive;
+    /**
+     * True if `action` went `pressed` within the last `windowMs` (counted in ticks:
+     * `ceil(windowMs / tickMs)`, this tick included) and that press was not `consume`d
+     * (ws/input-5). A press a few frames early still lands: `if (input.buffered('jump', 100) &&
+     * grounded) { input.consume('jump'); jump(); }`. Deterministic under replay.
+     */
+    buffered(action: A, windowMs: number): boolean;
+    /**
+     * Mark `action`'s latest press used: `buffered` no longer returns it and `pressed` reads false
+     * for the rest of this tick. Returns whether there was an unused press. Feed hooks see it, so a
+     * recording carries it.
+     */
+    consume(action: A): boolean;
+    /**
+     * Read four actions as a stick into `out` (`[x, y]`, the caller's; returned) through
+     * `shapeStick` (ws/input-5): x is `value(posX) - value(negX)`, y `value(posY) - value(negY)`.
+     * Keys, pad axes (bind them with `threshold: 0` for an analog read) and touch-zone sticks all
+     * go through it; diagonal keys read length 1. Allocation-free.
+     */
+    stick(negX: A, posX: A, negY: A, posY: A, out: [number, number], opts?: StickOptions): [number, number];
+    /**
+     * The aim angle of a stick read (`Math.atan2(y, x)`, radians), `null` when it is at rest
+     * (inside the deadzone). Pass the array `stick` filled.
+     */
+    stickAngle(out: readonly [number, number]): number | null;
+    private rebuildBound;
+    private noteBound;
+    /**
+     * Resolve with the next input the player presses (ws/input-3): a key as `{ key }`, a mouse
+     * or pen button as `{ mouse }`, a pad button that was up when the listen began as
+     * `{ padButton }`, an XR button as `{ xr }`. Escape, a `timeoutMs` elapsing or a newer
+     * `listen` resolve `null`. The captured input is swallowed (no action sees it). Keys typed
+     * into text fields never reach `Input`, so they are not captured either. The caller rebinds:
+     * `const b = await input.listen('jump'); if (b) input.rebind('jump', [b]);`.
+     */
+    listen(action: A, opts?: ListenOptions): Promise<Binding | null>;
+    /** The action a `listen` is waiting for, or `null`. */
+    get listening(): A | null;
+    private settleListen;
+    /** Replace the global keys (see `InputOptions.globalKeys`). */
+    setGlobalKeys(codes: Iterable<string>): void;
+    /** Replace the button keys (see `InputOptions.buttonKeys`). */
+    setButtonKeys(codes: Iterable<string>): void;
+    /**
+     * The prompt glyph for `action` on `device` (default `lastDevice`): the first binding that
+     * device produces, else the action's first binding; `null` for an unbound action. Pad labels
+     * follow `padLayout`, guessed from the first connected pad's `id` when unset. Reads the
+     * bindings in force, so the top context's (ws/input-5).
+     */
+    glyphFor(action: A, device?: InputDevice): Glyph | null;
+    private firstPad;
+    /** True when `pad` (or any connected pad) has a vibration actuator `rumble` can drive. */
+    rumbleSupported(pad?: number): boolean;
+    private actuatorPad;
+    /**
+     * Play a dual-rumble effect on `pad` (default: the first connected pad that can). Returns
+     * true when an actuator took it; a no-op (false) otherwise, so games call it freely. Feed hooks
+     * see every call, so a recording carries the rumbles for playback to assert.
+     */
+    rumble(opts?: RumbleOptions): boolean;
+    /**
+     * Install a feed hook: it sees every `keyDown`, `keyUp`, `buttonDown`, `buttonUp`, `wheel`,
+     * `pointerAt` and `releaseAll` call (DOM or direct) and the pads read in `update()`, and may
+     * substitute those pads. Returns the uninstaller. Used by `createInputRecorder` and
+     * `createInputPlayback`; hooks never change how bindings are evaluated.
+     */
+    onFeed(hook: InputFeedHook): () => void;
+    /** Install the client → game-space mapping (platform owns letterboxing). `null` = identity relative to the target. */
+    setPointerTransform(fn: PointerTransform | null): void;
+    pressed(action: A): boolean;
+    held(action: A): boolean;
+    released(action: A): boolean;
+    value(action: A): number;
+    state(action: A): Readonly<ActionState>;
+    /** True if any bound action was pressed this tick. */
+    anyPressed(): boolean;
+    /** Raw key state by `KeyboardEvent.code`, ignoring bindings and blocking. */
+    keyHeld(code: string): boolean;
+    /** Advance one tick: poll gamepads, compute edges, clear per-tick accumulators. */
+    update(): void;
+    /** A pending `listen`: pad buttons newly down, XR presses, the timeout. Keys and mouse come via the feed. */
+    private pollListen;
+    private readonly evalOut;
+    /**
+     * Fold a list of bindings into one value: the largest raw value after each binding's trigger
+     * (`press` passes it through, `hold` gates it on `holdMs` of ticks down, `doubleTap` passes a
+     * second down edge within `doubleTapMs`). `fresh` marks a new press while already active,
+     * `hold` the furthest hold progress, `pad` that a pad produced the value.
+     */
+    private evaluate;
+    /** One binding's raw value before its trigger; sets `evalOut.fresh`/`pad` as a side effect. */
+    private rawValue;
+    private padValue;
+    keyDown(code: string): void;
+    keyUp(code: string): void;
+    buttonDown(button: number): void;
+    buttonUp(button: number): void;
+    wheel(dx: number, dy: number): void;
+    /** Set the pointer position from client coordinates (runs the transform). */
+    pointerAt(clientX: number, clientY: number, type?: PointerState['type']): void;
+    /** Release every key and button (focus loss, tab hidden). */
+    releaseAll(): void;
+    /**
+     * An overlay control fired (ws/input-12): a button the player clicked, tapped or activated
+     * with Enter or the pad, named by its stable id (`controlId` in ui). Feed hooks see it, so a
+     * recording carries it in its `ui` lane on the tick it happened; nothing else changes. The
+     * control's own handler has already run. `createGame` calls it for every overlay control.
+     */
+    control(id: string): void;
+    /**
+     * Replay an overlay control's activation (ws/input-12): emits `'control'` with `id`, whose
+     * listener (`createGame`: `Overlay.activate`) fires the control. `createInputPlayback` calls it
+     * for the recording's `ui` lane, before that tick's `update()`, so the handler runs on the
+     * tick it ran live. Feed hooks do not see it.
+     */
+    replayControl(id: string): void;
+    /**
+     * Listen to the DOM. Keyboard: only bound keys are `preventDefault`ed, and never when a
+     * modifier (Ctrl/Meta/Alt) is held, the target is a text field/button/link, input is
+     * blocked, or the document lacks focus. That keeps browser shortcuts working and avoids
+     * scrolling hijacks inside the itch.io iframe.
+     */
+    attach(opts: AttachOptions): void;
+    /**
+     * Dispatch a recorded pointer event on the attached pointer target (ws/input-5), so every
+     * dispatcher consumer (gestures, look, touch zones, the router) sees it as it saw the original;
+     * the feed's own key/button/pointer state is left to the playback's `b` and `p` lanes.
+     * `createInputPlayback` calls it for the recording's `ptr` lane. `age` (ws/input-7) is how
+     * many ms ago the event happened on the consumers' clocks (`PointerRecord.age`; negative is
+     * ahead); omitted, it happened now. Returns false (and does nothing) while detached or
+     * without `PointerEvent`.
+     */
+    replayPointer(phase: InputPointerPhase, id: number, device: 'mouse' | 'touch' | 'pen', clientX: number, clientY: number, button: number, primary: boolean, age?: number): boolean;
+    detach(): void;
+}