@driftengine/core 3.61.0

package/dist/input/actionMap.js

@@ -0,0 +1,314 @@
+function isAnalog(definition) {
+    return 'stick' in definition;
+}
+/** Scratch, at module scope because `vector` is a per-frame read. */
+const stickVector = { x: 0, y: 0 };
+const keyVector = { x: 0, y: 0 };
+export class ActionMap {
+    input;
+    definitions;
+    /** The current bindings per digital action, which rebinding and loading replace. */
+    bindings = new Map();
+    defaults = new Map();
+    warnedAboutRecord = false;
+    constructor(input, definitions) {
+        this.input = input;
+        this.definitions = definitions;
+        for (const [name, definition] of Object.entries(definitions)) {
+            if (isAnalog(definition))
+                continue;
+            const initial = bindingsOf(definition);
+            this.defaults.set(name, initial);
+            this.bindings.set(name, [...initial]);
+        }
+    }
+    /** Whether anything bound to this action is held. */
+    down(action) {
+        return this.any(action, (binding) => binding.device === 'keyboard'
+            ? this.input.isDown(binding.code)
+            : (this.input.pad(0)?.down(binding.button) ?? false));
+    }
+    /** Whether anything bound to it went down since the last poll. Readable by anything. */
+    pressed(action) {
+        return this.any(action, (binding) => binding.device === 'keyboard'
+            ? this.input.keyPressed(binding.code)
+            : (this.input.pad(0)?.pressed(binding.button) ?? false));
+    }
+    /**
+     * The same edge, claimed: true for exactly one caller.
+     *
+     * **Claims through the device rather than keeping its own set**, so a claim made here is also
+     * gone from `input.keyPressed` and from the pad's own `pressed`. Two claim registers over one
+     * physical press is how a press gets acted on twice.
+     */
+    consumePress(action) {
+        const bindings = this.bindings.get(action);
+        if (bindings === undefined)
+            return false;
+        for (const binding of bindings) {
+            if (binding.device === 'keyboard') {
+                if (this.input.consumeKeyPress(binding.code))
+                    return true;
+            }
+            else if (this.input.pad(0)?.consumePress(binding.button) === true) {
+                return true;
+            }
+        }
+        return false;
+    }
+    /**
+     * Fill `out` with an analog action's direction.
+     *
+     * **The larger of stick and keys, never the sum.** A player holding a key while pushing the
+     * stick the same way is asking to go that way, once; adding the contributions would send them at
+     * twice the speed, which is the bug a naive merge ships with. What it costs: the two cannot be
+     * combined to exceed the rim, which is the intent. What would make it wrong: an action where two
+     * devices genuinely should add, and nothing has asked for one.
+     *
+     * **This is the reader for a direction.** If the two axes are two separate controls — throttle
+     * and steering, pitch and roll — read them one at a time with `axis`, which does not normalise
+     * them against each other. See its note for what the joint normalisation cost one consumer.
+     */
+    vector(action, out) {
+        out.x = 0;
+        out.y = 0;
+        if (!this.sample(action))
+            return;
+        /* Normalised, so a diagonal on the keyboard is not faster than a straight line. This is the
+           one line `axis` does not run, and the whole difference between the two readers. */
+        const keyLength = Math.hypot(keyVector.x, keyVector.y);
+        if (keyLength > 1) {
+            keyVector.x /= keyLength;
+            keyVector.y /= keyLength;
+        }
+        const useStick = Math.hypot(stickVector.x, stickVector.y) >= Math.min(keyLength, 1);
+        out.x = useStick ? stickVector.x : keyVector.x;
+        out.y = useStick ? stickVector.y : keyVector.y;
+    }
+    /**
+     * One axis of an analog action, on its own, **not normalised against the other**.
+     *
+     * **`vector` is right for a direction and wrong for two controls**, and the difference is not
+     * cosmetic. On foot the two axes are one direction, so a keyboard diagonal must be shortened to
+     * the rim or the player walks faster askew than straight ahead — that is what `vector` is for and
+     * it should stay the default. At a wheel the same two axes are throttle and steering, which are
+     * two separate controls that happen to share an action: normalising them together means a driver
+     * holding forward and left gets 0.707 of each and **can never reach full lock while accelerating**.
+     *
+     * A consumer lost two weeks to this. The report was "the car does not turn and it is slow", the
+     * whole vehicle model was rewritten looking for it, and it was not in the vehicle model — it was
+     * `Math.hypot` three call frames away, doing exactly what it was written to do. They shipped four
+     * duplicate digital actions bound to the same keys to get around it.
+     *
+     * The pad is unchanged either way: a stick already gives its two axes independently, so a caller
+     * driving with one reads the same numbers from both methods. The keyboard is where they part.
+     */
+    axis(action, axis) {
+        if (!this.sample(action))
+            return 0;
+        const useStick = Math.hypot(stickVector.x, stickVector.y) >= Math.min(Math.hypot(keyVector.x, keyVector.y), 1);
+        const from = useStick ? stickVector : keyVector;
+        return axis === 'x' ? from.x : from.y;
+    }
+    /**
+     * Fill the two scratch vectors for an analog action, and say whether there was one.
+     *
+     * Shared so that `vector` and `axis` cannot disagree about which device is being read or how a
+     * key becomes a number — the device choice in particular is subtle enough that two copies of it
+     * would drift.
+     */
+    sample(action) {
+        const definition = this.definitions[action];
+        if (definition === undefined || !isAnalog(definition))
+            return false;
+        const pad = this.input.pad(0);
+        stickVector.x = pad === null ? 0 : pad.axis(definition.stick === 'left' ? 'leftX' : 'rightX');
+        stickVector.y = pad === null ? 0 : pad.axis(definition.stick === 'left' ? 'leftY' : 'rightY');
+        keyVector.x = 0;
+        keyVector.y = 0;
+        if (this.anyDown(definition.left))
+            keyVector.x -= 1;
+        if (this.anyDown(definition.right))
+            keyVector.x += 1;
+        if (this.anyDown(definition.up))
+            keyVector.y -= 1;
+        if (this.anyDown(definition.down))
+            keyVector.y += 1;
+        return true;
+    }
+    /**
+     * Whether the pad these actions read has motors this browser can drive.
+     *
+     * **Pad 0, which is the pad every other member of this class already reads.** An action map is
+     * one player's controls, so "the pad the actions come from" is the device a rumble belongs on;
+     * a consumer running local multiplayer reaches `InputSource.pad(n).rumble` directly.
+     *
+     * Grey the control out when this is false. It is re-read rather than cached, because a pad
+     * unplugged and plugged back in is a different device behind the same slot.
+     */
+    get canRumble() {
+        return this.input.pad(0)?.canRumble ?? false;
+    }
+    /**
+     * Rumble that pad for `durationMs`, at two magnitudes in [0, 1]. Answers whether it was taken.
+     *
+     * `false` where there is no pad, no actuator, or nothing to play. Never throws.
+     */
+    rumble(durationMs, strong, weak) {
+        return this.input.pad(0)?.rumble(durationMs, strong, weak) ?? false;
+    }
+    /** Stop whatever that pad is playing. Answers whether the platform took it. */
+    stopRumble() {
+        return this.input.pad(0)?.stopRumble() ?? false;
+    }
+    /**
+     * Whether any of a direction's codes is held.
+     *
+     * Allocation-free for both shapes: a single code is compared without wrapping it in an array,
+     * and an array is walked by index. `vector` runs once a tick.
+     */
+    anyDown(codes) {
+        if (codes === undefined)
+            return false;
+        if (typeof codes === 'string')
+            return this.input.isDown(codes);
+        for (let i = 0; i < codes.length; i++) {
+            const code = codes[i];
+            if (code !== undefined && this.input.isDown(code))
+                return true;
+        }
+        return false;
+    }
+    /** What currently satisfies an action. */
+    bindingsFor(action) {
+        return this.bindings.get(action) ?? [];
+    }
+    /**
+     * Give an action a binding, and say which actions lost it.
+     *
+     * **Reports rather than decides.** A binding already serving another action is the interesting
+     * case in every rebinding screen there has ever been, and what to do about it is a product
+     * decision: steal it silently, warn, or refuse. A consumer that wants uniqueness enforced reads
+     * the return and rebinds back.
+     */
+    rebind(action, binding) {
+        const displaced = [];
+        for (const [name, list] of this.bindings) {
+            if (name === action)
+                continue;
+            const at = list.findIndex((held) => sameBinding(held, binding));
+            if (at < 0)
+                continue;
+            list.splice(at, 1);
+            displaced.push(name);
+        }
+        const own = this.bindings.get(action);
+        if (own === undefined)
+            return displaced;
+        if (!own.some((held) => sameBinding(held, binding)))
+            own.push(binding);
+        return displaced;
+    }
+    /** Put one action, or every action, back to what the game shipped with. */
+    resetToDefaults(action) {
+        for (const [name, initial] of this.defaults) {
+            if (action !== undefined && name !== action)
+                continue;
+            this.bindings.set(name, [...initial]);
+        }
+    }
+    /**
+     * Write the bindings a player has actually changed, and nothing else.
+     *
+     * **A diff rather than a snapshot, and this is the load-bearing decision.** A snapshot freezes
+     * the map at the version that saved it: a game that later adds an action, or changes a default
+     * nobody had rebound, finds every returning player still on the old set with no way to tell a
+     * deliberate choice from a stale record. A diff means an untouched action always follows the
+     * current default and only real choices survive an update.
+     *
+     * Through `KeyValueStore` because the engine calls no platform API a consumer might want to
+     * supply differently — the rule that put saves behind this seam.
+     */
+    save(store, key) {
+        const changed = {};
+        for (const [name, list] of this.bindings) {
+            const initial = this.defaults.get(name) ?? [];
+            if (sameList(list, initial))
+                continue;
+            changed[name] = list;
+        }
+        store.write(key, JSON.stringify(changed));
+    }
+    /**
+     * Apply a stored record over the defaults.
+     *
+     * **An unreadable record is the defaults, reported once.** A player whose stored bindings cannot
+     * be parsed should get a working game rather than a broken one, and should not have that decided
+     * silently — the same shape as every other refusal in this engine.
+     */
+    load(store, key) {
+        const raw = store.read(key);
+        if (raw === null)
+            return;
+        let parsed = null;
+        try {
+            parsed = JSON.parse(raw);
+        }
+        catch {
+            parsed = null;
+        }
+        if (parsed === null || typeof parsed !== 'object') {
+            if (!this.warnedAboutRecord) {
+                this.warnedAboutRecord = true;
+                console.warn(`[driftengine] the stored input bindings at ${JSON.stringify(key)} could not be read; ` +
+                    'the defaults are in force. Save again to replace the record.');
+            }
+            return;
+        }
+        for (const [name, list] of Object.entries(parsed)) {
+            /* An action the record knows and this build does not is dropped rather than kept: it is a
+               binding for a verb that no longer exists, and holding it would resurrect it on a
+               downgrade. An action this build has and the record does not keeps its default, which is
+               the whole reason this is a diff. */
+            if (!this.bindings.has(name) || !Array.isArray(list))
+                continue;
+            this.bindings.set(name, list.filter(isBinding));
+        }
+    }
+    any(action, holds) {
+        const bindings = this.bindings.get(action);
+        if (bindings === undefined)
+            return false;
+        for (const binding of bindings)
+            if (holds(binding))
+                return true;
+        return false;
+    }
+}
+function bindingsOf(definition) {
+    const list = [];
+    for (const code of definition.keys ?? [])
+        list.push({ device: 'keyboard', code });
+    for (const button of definition.buttons ?? [])
+        list.push({ device: 'gamepad', button });
+    return list;
+}
+function sameBinding(a, b) {
+    if (a.device !== b.device)
+        return false;
+    return a.device === 'keyboard' && b.device === 'keyboard'
+        ? a.code === b.code
+        : a.device === 'gamepad' && b.device === 'gamepad' && a.button === b.button;
+}
+function sameList(a, b) {
+    return a.length === b.length && a.every((entry, at) => sameBinding(entry, b[at]));
+}
+/** A stored entry is data from disk, so it is checked rather than trusted. */
+function isBinding(value) {
+    if (typeof value !== 'object' || value === null)
+        return false;
+    const candidate = value;
+    if (candidate.device === 'keyboard')
+        return typeof candidate.code === 'string';
+    return candidate.device === 'gamepad' && typeof candidate.button === 'string';
+}

package/dist/input/activeDevice.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Which device the player is actually using, so a consumer can redraw its prompts.
+ *
+ * **The rule is use, never presence**, and that single word is most of the design. A controller
+ * plugged in for something else, or left on a desk, must not change every prompt on screen while
+ * the player is still on the keyboard — which is the bug this kind of feature usually ships with.
+ * The browser helps: it does not report a gamepad at all until a button has been pressed on it.
+ * This closes the rest.
+ */
+export type InputDevice = 'keyboard' | 'mouse' | 'touch' | 'gamepad';
+/**
+ * How far a cursor must travel, in pixels, before it counts as the player choosing the mouse.
+ *
+ * A tuning constant, so its value is not asserted anywhere — `AGENTS.md` forbids that, because a
+ * decision that will change every feel pass produces a test that fails on intent.
+ */
+export declare const MOUSE_MOVE_THRESHOLD_PX = 32;
+export declare class ActiveDevice {
+    /**
+     * The keyboard to begin with.
+     *
+     * Something has to be answered before anything has been touched, and a prompt is more often
+     * wanted on a desktop than not. It is corrected by the first real input either way, and no
+     * device is *reported* as connected by this — only as used.
+     */
+    private device;
+    /**
+     * Travel accumulated since a device other than the mouse was last used.
+     *
+     * **A threshold rather than a flip on the first event, and the mouse alone needs one.** A
+     * keydown and a touchstart are intentional; a mousemove is not necessarily anything at all — an
+     * unlocked cursor drifts, a desk gets bumped, and a window manager can deliver motion nobody
+     * caused. Accumulating rather than testing one delta means a slow deliberate movement counts
+     * while a single stray pixel does not.
+     *
+     * **What it costs:** a drift of a pixel at a time does eventually cross it, in about thirty
+     * moves. **What would make it wrong:** a pointing device whose ordinary use produces less travel
+     * than this — a trackpoint or an eye tracker — where the answer is a smaller threshold rather
+     * than none.
+     */
+    private travel;
+    private readonly listeners;
+    get last(): InputDevice;
+    /** Record that a device was used. Notifies only on a change. */
+    use(device: InputDevice): void;
+    /** Offer pointer movement. Becomes a use of the mouse once it adds up to a decision. */
+    moved(dx: number, dy: number): void;
+    /**
+     * Hear about changes. Returns the unsubscribe, which is the shape `InputSource.subscribe` uses.
+     *
+     * Fires only on a change, so a consumer that redraws its prompts here redraws them once rather
+     * than every frame a button is held.
+     */
+    subscribe(listener: (device: InputDevice) => void): () => void;
+}

package/dist/input/activeDevice.js

@@ -0,0 +1,83 @@
+/**
+ * Which device the player is actually using, so a consumer can redraw its prompts.
+ *
+ * **The rule is use, never presence**, and that single word is most of the design. A controller
+ * plugged in for something else, or left on a desk, must not change every prompt on screen while
+ * the player is still on the keyboard — which is the bug this kind of feature usually ships with.
+ * The browser helps: it does not report a gamepad at all until a button has been pressed on it.
+ * This closes the rest.
+ */
+/**
+ * How far a cursor must travel, in pixels, before it counts as the player choosing the mouse.
+ *
+ * A tuning constant, so its value is not asserted anywhere — `AGENTS.md` forbids that, because a
+ * decision that will change every feel pass produces a test that fails on intent.
+ */
+export const MOUSE_MOVE_THRESHOLD_PX = 32;
+export class ActiveDevice {
+    /**
+     * The keyboard to begin with.
+     *
+     * Something has to be answered before anything has been touched, and a prompt is more often
+     * wanted on a desktop than not. It is corrected by the first real input either way, and no
+     * device is *reported* as connected by this — only as used.
+     */
+    device = 'keyboard';
+    /**
+     * Travel accumulated since a device other than the mouse was last used.
+     *
+     * **A threshold rather than a flip on the first event, and the mouse alone needs one.** A
+     * keydown and a touchstart are intentional; a mousemove is not necessarily anything at all — an
+     * unlocked cursor drifts, a desk gets bumped, and a window manager can deliver motion nobody
+     * caused. Accumulating rather than testing one delta means a slow deliberate movement counts
+     * while a single stray pixel does not.
+     *
+     * **What it costs:** a drift of a pixel at a time does eventually cross it, in about thirty
+     * moves. **What would make it wrong:** a pointing device whose ordinary use produces less travel
+     * than this — a trackpoint or an eye tracker — where the answer is a smaller threshold rather
+     * than none.
+     */
+    travel = 0;
+    listeners = [];
+    get last() {
+        return this.device;
+    }
+    /** Record that a device was used. Notifies only on a change. */
+    use(device) {
+        if (device !== 'mouse')
+            this.travel = 0;
+        if (device === this.device)
+            return;
+        this.device = device;
+        /* Indexed rather than iterated: this can fire from a frame callback, and the house rule about
+           allocation in a per-frame path binds it. */
+        for (let i = 0; i < this.listeners.length; i += 1)
+            this.listeners[i]?.(device);
+    }
+    /** Offer pointer movement. Becomes a use of the mouse once it adds up to a decision. */
+    moved(dx, dy) {
+        if (this.device === 'mouse')
+            return;
+        this.travel += Math.hypot(dx, dy);
+        if (this.travel >= MOUSE_MOVE_THRESHOLD_PX)
+            this.use('mouse');
+    }
+    /**
+     * Hear about changes. Returns the unsubscribe, which is the shape `InputSource.subscribe` uses.
+     *
+     * Fires only on a change, so a consumer that redraws its prompts here redraws them once rather
+     * than every frame a button is held.
+     */
+    subscribe(listener) {
+        this.listeners.push(listener);
+        let subscribed = true;
+        return () => {
+            if (!subscribed)
+                return;
+            subscribed = false;
+            const index = this.listeners.indexOf(listener);
+            if (index >= 0)
+                this.listeners.splice(index, 1);
+        };
+    }
+}

package/dist/input/gamepadIdentity.d.ts

@@ -0,0 +1,43 @@
+import { type GamepadButton } from './gamepadMapping.ts';
+/**
+ * What the pad in the player's hands calls a position, so a consumer can draw the right prompt.
+ *
+ * **The engine ships no art and never will.** A glyph key is an identifier a consumer maps to its
+ * own icon set or font. It exists so that several consumers do not each write the same table, and
+ * so the mapping from *hardware* to *name* lives beside the hardware knowledge rather than inside
+ * somebody's heads-up display.
+ *
+ * **Four families, and no device database.** A table of individual controllers is a maintenance
+ * obligation that grows with the hardware market and rots silently — and a rotted entry shows a
+ * wrong glyph to a player while no test can see it. Four families cover the pads a browser will
+ * vouch for; everything else is `generic` and correct rather than guessed.
+ *
+ * **What would make this wrong:** a family whose members disagree about their own lettering, which
+ * would make the family the wrong unit to key on. None of these four do.
+ */
+export type GamepadFamily = 'xbox' | 'playstation' | 'nintendo' | 'generic';
+/**
+ * Read the family out of the `id` string, in either shape a browser writes it.
+ *
+ * Chromium writes `Wireless Controller (STANDARD GAMEPAD Vendor: 054c Product: 09cc)`; Firefox
+ * writes `054c-09cc-Wireless Controller`. Both are matched, because a parser that knew only one
+ * would answer `generic` for every pad in the other browser — which is a wrong prompt on screen
+ * with nothing anywhere reporting it, the failure this repository's rules about silent plausible
+ * answers exist for.
+ */
+export declare function identifyGamepad(id: string): GamepadFamily;
+/**
+ * What this pad calls that position.
+ *
+ * A generic pad answers its position — `Face Down` is a poor prompt and it is not a *wrong* one,
+ * which is the trade this design takes over inventing a lettering for hardware it cannot identify.
+ */
+export declare function labelFor(family: GamepadFamily, button: GamepadButton): string;
+/**
+ * A stable key for a consumer's own icon set: `xbox.a`, `playstation.cross`, `nintendo.b`.
+ *
+ * Stable is the load-bearing word. A consumer builds a lookup from these to its own art, so
+ * changing one silently breaks an icon in somebody else's repository — they are an interface, not
+ * a formatting choice.
+ */
+export declare function glyphFor(family: GamepadFamily, button: GamepadButton): string;

package/dist/input/gamepadIdentity.js

@@ -0,0 +1,108 @@
+import {} from './gamepadMapping.js';
+/** Vendor identifiers, which are the same four hex digits in every browser that reports them. */
+const VENDORS = {
+    '045e': 'xbox',
+    '054c': 'playstation',
+    '057e': 'nintendo',
+};
+/** For a pad that names itself but carries no vendor pair, which is most of what XInput reports. */
+const NAMED = [
+    ['xbox', 'xbox'],
+    ['xinput', 'xbox'],
+    ['dualsense', 'playstation'],
+    ['dualshock', 'playstation'],
+    ['playstation', 'playstation'],
+    ['nintendo', 'nintendo'],
+    ['switch pro', 'nintendo'],
+];
+/**
+ * Read the family out of the `id` string, in either shape a browser writes it.
+ *
+ * Chromium writes `Wireless Controller (STANDARD GAMEPAD Vendor: 054c Product: 09cc)`; Firefox
+ * writes `054c-09cc-Wireless Controller`. Both are matched, because a parser that knew only one
+ * would answer `generic` for every pad in the other browser — which is a wrong prompt on screen
+ * with nothing anywhere reporting it, the failure this repository's rules about silent plausible
+ * answers exist for.
+ */
+export function identifyGamepad(id) {
+    const lower = id.toLowerCase();
+    const vendor = /(?:^|vendor:\s*)([0-9a-f]{4})\b/.exec(lower);
+    const known = vendor === null ? undefined : VENDORS[vendor[1] ?? ''];
+    if (known !== undefined)
+        return known;
+    for (const [needle, family] of NAMED)
+        if (lower.includes(needle))
+            return family;
+    return 'generic';
+}
+/**
+ * The vendor's own token for a position, which is also the tail of its glyph key.
+ *
+ * Only the positions vendors actually name differently are listed. A shoulder is `L1` on every pad
+ * that has one printed, so it falls through to the positional label rather than being repeated
+ * three times.
+ */
+const TOKENS = {
+    xbox: {
+        faceDown: 'a',
+        faceRight: 'b',
+        faceLeft: 'x',
+        faceUp: 'y',
+        select: 'view',
+        start: 'menu',
+    },
+    playstation: {
+        faceDown: 'cross',
+        faceRight: 'circle',
+        faceLeft: 'square',
+        faceUp: 'triangle',
+        select: 'create',
+        start: 'options',
+        l1: 'l1',
+        r1: 'r1',
+        l2: 'l2',
+        r2: 'r2',
+    },
+    /* The swap: Nintendo's bottom button is B and its right button is A, the other way round from
+       every other pad here. This is the entire reason the engine names positions. */
+    nintendo: {
+        faceDown: 'b',
+        faceRight: 'a',
+        faceLeft: 'y',
+        faceUp: 'x',
+        select: 'minus',
+        start: 'plus',
+    },
+    generic: {},
+};
+/** `faceDown` to `Face Down`, `l1` to `L1` — true of any pad, and readable rather than cryptic. */
+function positionalLabel(button) {
+    if (/^[lr][123]$/.test(button))
+        return button.toUpperCase();
+    const spaced = button.replace(/([A-Z])/g, ' $1');
+    return spaced.charAt(0).toUpperCase() + spaced.slice(1);
+}
+/** A vendor token to the label a player reads on the plastic: `cross` to `Cross`, `a` to `A`. */
+function titled(token) {
+    return token.length <= 2 ? token.toUpperCase() : token.charAt(0).toUpperCase() + token.slice(1);
+}
+/**
+ * What this pad calls that position.
+ *
+ * A generic pad answers its position — `Face Down` is a poor prompt and it is not a *wrong* one,
+ * which is the trade this design takes over inventing a lettering for hardware it cannot identify.
+ */
+export function labelFor(family, button) {
+    const token = TOKENS[family][button];
+    return token === undefined ? positionalLabel(button) : titled(token);
+}
+/**
+ * A stable key for a consumer's own icon set: `xbox.a`, `playstation.cross`, `nintendo.b`.
+ *
+ * Stable is the load-bearing word. A consumer builds a lookup from these to its own art, so
+ * changing one silently breaks an icon in somebody else's repository — they are an interface, not
+ * a formatting choice.
+ */
+export function glyphFor(family, button) {
+    return `${family}.${TOKENS[family][button] ?? button}`;
+}

package/dist/input/gamepadMapping.d.ts

@@ -0,0 +1,56 @@
+/**
+ * The W3C Standard Gamepad, by position rather than by anybody's lettering.
+ *
+ * **The names are positional and that is a correctness decision, not a style one.** Index 0 is the
+ * bottom button of the right cluster. It is labelled A on an Xbox pad, Cross on a PlayStation pad
+ * and **B** on a Nintendo pad, because Nintendo's physical layout swaps the two. Any lettering
+ * this file picked would therefore be a false statement about somebody's hardware. It names the
+ * position, which is true everywhere; `gamepadIdentity.ts` answers what that position is *called*
+ * on the pad actually in the player's hands.
+ *
+ * A browser sets `mapping: 'standard'` only when it is confident the device matches this table.
+ * Anything else is served by raw index and says so once — see `InputSource`'s pad view.
+ */
+export type GamepadButton = 'faceDown' | 'faceRight' | 'faceLeft' | 'faceUp' | 'l1' | 'r1' | 'l2' | 'r2' | 'select' | 'start' | 'l3' | 'r3' | 'dpadUp' | 'dpadDown' | 'dpadLeft' | 'dpadRight' | 'guide';
+export type GamepadAxis = 'leftX' | 'leftY' | 'rightX' | 'rightY';
+export declare const BUTTON_INDEX: Readonly<Record<GamepadButton, number>>;
+/**
+ * **Vertical axes point up at −1**, which is the specification's choice and the opposite of most
+ * game code's expectation.
+ *
+ * It is not corrected here. An engine that silently flips a sign is one a consumer cannot reason
+ * about — the value it reads would disagree with every reference about the API it came from — so a
+ * caller that wants the other convention negates it at the one place that means something. What it
+ * costs: a caller has to know. What would make it wrong: nothing short of the specification
+ * changing, which it will not.
+ */
+export declare const AXIS_INDEX: Readonly<Record<GamepadAxis, number>>;
+/**
+ * How far a stick must travel before it is moving at all.
+ *
+ * A tuning constant, so it is an option rather than a rule — `AGENTS.md` forbids asserting the
+ * value of one, and `gamepadMapping.test.ts` checks only that it sits in a range a stick can
+ * leave. Sticks rest off-centre by different amounts on different pads and wear looser with age,
+ * which is the whole reason a deadzone exists.
+ */
+export declare const DEFAULT_DEADZONE = 0.15;
+/**
+ * Drop the dead region and rescale what is left, into a caller-owned target.
+ *
+ * **Radial rather than per-axis.** A per-axis deadzone leaves a *square* dead region, so a stick
+ * pushed diagonally clears it at a smaller displacement than one pushed straight, and the diagonal
+ * snaps out of nothing. What a player is controlling is the magnitude, so the magnitude is what
+ * the test applies to.
+ *
+ * **Rescaled from the edge**, because without it the value jumps from 0 to the deadzone the
+ * instant it is crossed — a stick that begins moving fast rather than from rest. What it costs:
+ * full deflection is reached fractionally before the hardware's own rim. What would make it wrong:
+ * a caller wanting the untouched number, which the pad view answers separately as `rawAxis`.
+ *
+ * Fills `out` rather than returning an object: this is a per-frame path and the house rule about
+ * allocation binds it.
+ */
+export declare function applyDeadzone(x: number, y: number, deadzone: number, out: {
+    x: number;
+    y: number;
+}): void;