game-koi 0.1.2 → 0.3.0

package/README.md

@@ -26,10 +26,78 @@ button.addEventListener("click", async () => {
 ```
 
 That's the whole integration: no separate files to serve for the audio worklet, no
-manual wasm memory or canvas bookkeeping, and the built-in keyboard layout (arrow
-keys, Z/X, Enter, right Shift) is wired up automatically. Pass `keymap: null` to
-`create()` to opt out of that and drive `press`/`release` yourself — from a gamepad,
-touch controls, or your own key bindings.
+manual wasm memory or canvas bookkeeping, and both input devices are wired up
+automatically — the keyboard layout (arrow keys, Z/X, Enter, right Shift) and any
+connected gamepad. Pass `keymap: null` or `gamepadMap: null` to `create()` to opt out
+of either and drive `press`/`release` yourself — from touch controls or your own
+bindings.
+
+### Gamepads
+
+A standard-layout pad maps d-pad to d-pad, the East and South face buttons to A and B
+(the DMG's diagonal), Start to Start and Back/Select to Select. The left analog stick
+doubles as the d-pad, thresholded at half deflection. Every connected pad drives the
+one player, since the Game Boy has only one.
+
+Two things follow from how the browser exposes pads, and neither needs anything from
+the page:
+
+- There is no event for a button being pressed — only connect/disconnect — so pads are
+  polled once per animation frame. That is also why a pad shows up on its own in
+  Chrome, which hides pads until one has been interacted with.
+- Pads the browser cannot identify (`mapping !== "standard"`) are ignored, because the
+  button indices of an unrecognised layout are whatever the driver enumerated and
+  binding them would be confidently wrong rather than merely absent. Use
+  `gamepadMap: null` and your own polling for such a pad.
+
+### Button events
+
+`koi.on("press" | "release", listener)` reports button edges from every input path —
+the built-in keyboard and gamepad handling as well as your own `press`/`release` calls —
+so an on-screen joypad can mirror whatever is driving the emulator:
+
+```ts
+const stop = koi.on("press", ({ button, source, pressed }) => {
+  // button: the one that changed. source: "keyboard" | "gamepad" | "api".
+  // pressed: everything held after this edge, as a Set — render straight from it.
+  render(pressed);
+});
+koi.on("release", ({ pressed }) => render(pressed));
+
+stop(); // or koi.off("press", listener)
+```
+
+Only *changes* are reported. A key held down with autorepeat, a stick resting past the
+threshold, and `press("a")` called twice each produce one `press` event and nothing more
+until the button comes up — so a listener never has to de-duplicate. `koi.pressed` gives
+the same set on demand, for a display built after the fact.
+
+Two cases release without anyone letting go: `loadRom()` releases everything (as
+`"api"`), since the new machine's joypad starts empty, and `pause()` releases whatever
+the gamepad was holding (as `"gamepad"`), since polling stops and nothing else would.
+Keys keep their own `keyup` while paused. `dispose()` drops every listener.
+
+### Debug overlay
+
+Press <kbd>`</kbd> (backtick) to toggle a stats panel over the canvas, or call
+`koi.toggleOverlay()`. It is the browser counterpart of the desktop build's panel, on
+the same key, and it counts browser-shaped things:
+
+- **FPS / Speed** — emulated frames per second, and that as a percentage of a real
+  DMG's 59.73 Hz. Frames, not animation-frame wakes: on a 120 Hz display the loop wakes
+  twice per frame.
+- **emulate / draw / Work** — milliseconds per emulated frame, and their total as a
+  share of the 16.74 ms a frame is worth.
+- **Frames/wake, Refresh, Capped** — how the two clocks relate, and how often
+  `maxFramesPerWake` clamped a catch-up.
+- **Buffer / Underruns / Dropped / Output** — how much audio is queued ahead, and the
+  two ways that goes wrong. Underruns are silence that was actually heard, and are the
+  closest thing here to the desktop's "late frames"; a `suspended` output is the usual
+  reason for no sound at all.
+
+The panel is read-only and `pointer-events: none`, so it never intercepts a click, and
+it is built the first time it is opened — a page that never opens it gets no extra
+element. Pass `overlayKey: null` to bind no key.
 
 ## API
 
@@ -38,12 +106,22 @@ touch controls, or your own key bindings.
   - `rom: Uint8Array` — the `.gb` file's bytes.
   - `keymap?: Record<string, Button> | null` — maps `KeyboardEvent.code` to a
     button; `null` disables built-in keyboard handling.
+  - `gamepadMap?: Record<number, Button> | null` — maps a standard-layout gamepad's
+    button indices to a button; `null` disables gamepad polling. The left stick acts
+    as a d-pad regardless of this map.
+  - `overlayKey?: string | null` — `KeyboardEvent.code` toggling the stats panel.
+    Default `"Backquote"`; `null` binds no key.
   - `targetBuffer?: number` — audio samples to keep queued ahead. Default `1600`.
   - `maxFramesPerWake?: number` — cap on frames emulated per wake-up, so a
     backgrounded tab can't return to a freeze. Default `4`.
 - `koi.loadRom(rom)` — swaps in a new ROM, keeping the same canvas and audio setup.
 - `koi.press(button)` / `koi.release(button)` — `Button` is one of `"up"`, `"down"`,
   `"left"`, `"right"`, `"a"`, `"b"`, `"start"`, `"select"`.
+- `koi.on(type, listener)` / `koi.off(type, listener)` — `"press"` and `"release"`
+  button edges, from any input path. `on` returns a function that unsubscribes. The
+  payload is `{ button, source: "keyboard" | "gamepad" | "api", pressed: Set<Button> }`.
+- `koi.pressed` — everything held right now, as a `Set<Button>` snapshot.
+- `koi.toggleOverlay()` / `koi.overlayVisible` — the debug stats panel.
 - `koi.pause()` / `koi.resume()`.
 - `koi.dispose()` — stops the loop and tears down the audio graph. Call this before
   dropping a `GameKoi` instance, or the AudioContext and its worklet leak.

package/dist/events.d.ts

@@ -0,0 +1,63 @@
+/**
+ * The package's event plumbing: a tiny typed emitter, plus the button-edge types it
+ * carries.
+ *
+ * `on`/`off` rather than `EventTarget`, because a `CustomEvent`'s payload lands in
+ * `detail` typed as whatever the listener's declaration says — subclassing `EventTarget`
+ * in TypeScript means writing `addEventListener` overloads by hand and consumers still
+ * end up casting. A five-line map of sets types exactly, costs nothing, and keeps the
+ * package free of DOM globals in a module that Node's test runner has to import.
+ *
+ * The emitter deals in *edges*, not state: `GameKoi` holds the set of what is down and
+ * only emits when a button actually changes, so a key held with autorepeat, a stick
+ * resting past the threshold, and a page calling `press` twice all produce one event.
+ */
+import type { Button } from "./index.js";
+/** Where a button edge came from. */
+export type ButtonSource = "keyboard" | "gamepad" | "api";
+/** A button going down or coming up. */
+export interface ButtonEvent {
+    button: Button;
+    /**
+     * Which input path produced this edge. `"api"` covers `press`/`release` called by the
+     * page, and the releases `loadRom()` emits for a machine that is going away;
+     * `pause()`'s releases are attributed to the device that was holding them.
+     */
+    source: ButtonSource;
+    /**
+     * Everything held *after* this edge — a snapshot, safe to keep.
+     *
+     * Handy for the common case of mirroring the joypad on screen: render from this and
+     * there is no second copy of the state to keep in step.
+     */
+    pressed: ReadonlySet<Button>;
+}
+/** Event names to their payloads. See {@link GameKoi.on}. */
+export interface GameKoiEvents {
+    press: ButtonEvent;
+    release: ButtonEvent;
+}
+export type Listener<E> = (event: E) => void;
+/** Unsubscribes the listener it was returned for. Calling it twice is harmless. */
+export type Unsubscribe = () => void;
+/** A minimal typed event emitter. */
+export declare class Emitter<Events> {
+    private readonly listeners;
+    /** Registers a listener, and returns a function that removes it again. */
+    on<K extends keyof Events>(type: K, listener: Listener<Events[K]>): Unsubscribe;
+    off<K extends keyof Events>(type: K, listener: Listener<Events[K]>): void;
+    /**
+     * Calls every listener for `type`.
+     *
+     * Each is isolated: these fire from inside a `keydown` handler and from the render
+     * loop, so a listener that throws would otherwise skip the rest of a gamepad poll or
+     * kill the loop outright. A page's display bug should not stop the emulator, so the
+     * error is reported and the remaining listeners still run.
+     *
+     * Iterates a copy, so a listener that unsubscribes itself (or another) mid-dispatch
+     * cannot disturb the walk.
+     */
+    emit<K extends keyof Events>(type: K, event: Events[K]): void;
+    /** Drops every listener. Called from `dispose()`. */
+    clear(): void;
+}

package/dist/events.js

@@ -0,0 +1,59 @@
+/**
+ * The package's event plumbing: a tiny typed emitter, plus the button-edge types it
+ * carries.
+ *
+ * `on`/`off` rather than `EventTarget`, because a `CustomEvent`'s payload lands in
+ * `detail` typed as whatever the listener's declaration says — subclassing `EventTarget`
+ * in TypeScript means writing `addEventListener` overloads by hand and consumers still
+ * end up casting. A five-line map of sets types exactly, costs nothing, and keeps the
+ * package free of DOM globals in a module that Node's test runner has to import.
+ *
+ * The emitter deals in *edges*, not state: `GameKoi` holds the set of what is down and
+ * only emits when a button actually changes, so a key held with autorepeat, a stick
+ * resting past the threshold, and a page calling `press` twice all produce one event.
+ */
+/** A minimal typed event emitter. */
+export class Emitter {
+    listeners = new Map();
+    /** Registers a listener, and returns a function that removes it again. */
+    on(type, listener) {
+        let set = this.listeners.get(type);
+        if (!set) {
+            set = new Set();
+            this.listeners.set(type, set);
+        }
+        set.add(listener);
+        return () => this.off(type, listener);
+    }
+    off(type, listener) {
+        this.listeners.get(type)?.delete(listener);
+    }
+    /**
+     * Calls every listener for `type`.
+     *
+     * Each is isolated: these fire from inside a `keydown` handler and from the render
+     * loop, so a listener that throws would otherwise skip the rest of a gamepad poll or
+     * kill the loop outright. A page's display bug should not stop the emulator, so the
+     * error is reported and the remaining listeners still run.
+     *
+     * Iterates a copy, so a listener that unsubscribes itself (or another) mid-dispatch
+     * cannot disturb the walk.
+     */
+    emit(type, event) {
+        const set = this.listeners.get(type);
+        if (!set)
+            return;
+        for (const listener of [...set]) {
+            try {
+                listener(event);
+            }
+            catch (error) {
+                console.error(`game-koi: "${String(type)}" listener threw`, error);
+            }
+        }
+    }
+    /** Drops every listener. Called from `dispose()`. */
+    clear() {
+        this.listeners.clear();
+    }
+}

package/dist/gamepad.d.ts

@@ -0,0 +1,85 @@
+/**
+ * Gamepad input, via the browser's Gamepad API.
+ *
+ * Unlike the keyboard, a gamepad is not a source of events here: the Gamepad API has
+ * `gamepadconnected`/`gamepaddisconnected` and nothing else — a button press fires no
+ * event at all. `navigator.getGamepads()` hands back a *snapshot* of every pad's
+ * current state, so this is polled once per wake of the render loop and diffed against
+ * the previous snapshot to recover the press/release edges the joypad wants. One frame
+ * (~16.7 ms) of latency is the granularity the emulator already runs at, so polling
+ * more often would buy nothing.
+ *
+ * Polling is also what makes a pad appear at all: Chrome exposes no pads until one has
+ * been interacted with, and reveals them through a later `getGamepads()` call rather
+ * than retroactively. Nothing extra is needed to pick that up.
+ *
+ * # Analog sticks are not a d-pad
+ *
+ * The DMG's d-pad is four switches: a direction is held or it isn't. A stick reports a
+ * continuous position, so it is thresholded into at most one direction per axis. The
+ * diff against the previous snapshot is what keeps a resting-at-0.7 stick from
+ * re-pressing Right on every frame.
+ */
+import type { Button } from "./index.js";
+/**
+ * The part of the browser's `Gamepad` this module reads.
+ *
+ * Narrowed to the two fields that matter (a real `Gamepad` is structurally compatible)
+ * so the mapping can be unit-tested with plain objects and no browser attached.
+ */
+export interface PadState {
+    /** `"standard"` iff the browser recognised the layout; see `heldButtons`. */
+    mapping: string;
+    buttons: readonly {
+        readonly pressed: boolean;
+    }[];
+    axes: readonly number[];
+}
+/** A press or release edge, to be applied to the emulator's joypad. */
+export interface Action {
+    type: "press" | "release";
+    button: Button;
+}
+/**
+ * Standard-layout button indices mapped to Game Boy buttons.
+ *
+ * A and B sit on a diagonal on the DMG — B lower-left, A upper-right — so the East and
+ * South face buttons reproduce that under the thumb. The Gamepad API reports face
+ * buttons by *position*, not by printed label: index 0 is always the bottom button and
+ * index 1 the right-hand one, whatever a given pad prints on them.
+ */
+export declare const DEFAULT_GAMEPAD_MAP: Readonly<Record<number, Button>>;
+/**
+ * Everything held across every connected pad, as a set of Game Boy buttons.
+ *
+ * Every pad is accepted rather than picking a "player 1": the Game Boy has one player,
+ * so asking which controller owns it would be ceremony for nothing.
+ *
+ * Pads whose `mapping` is not `"standard"` are skipped entirely. The indices in a
+ * non-standard layout are whatever the driver happened to enumerate, so guessing at
+ * them produces confidently wrong bindings rather than none; a page with such a pad can
+ * pass `gamepadMap: null` and drive `press`/`release` itself.
+ */
+export declare function heldButtons(pads: Iterable<PadState | null>, map: Readonly<Record<number, Button>>): Set<Button>;
+/**
+ * The edges between two snapshots.
+ *
+ * Releases come first so that flicking a stick from Left straight through centre to
+ * Right cannot leave Left stuck down for the instant the presses are applied.
+ */
+export declare function diff(previous: ReadonlySet<Button>, next: ReadonlySet<Button>): Action[];
+/** Remembers the last snapshot so each poll can report only what changed. */
+export declare class GamepadInput {
+    private readonly map;
+    private held;
+    constructor(map?: Readonly<Record<number, Button>>);
+    /** Diffs the pads against the previous poll and returns the edges to apply. */
+    poll(pads: Iterable<PadState | null>): Action[];
+    /**
+     * Releases everything currently held, forgetting the snapshot.
+     *
+     * Used when the loop stops: a button held at the moment of a pause would otherwise
+     * still be held from the emulator's point of view, with no poll coming to release it.
+     */
+    releaseAll(): Action[];
+}

package/dist/gamepad.js

@@ -0,0 +1,158 @@
+/**
+ * Gamepad input, via the browser's Gamepad API.
+ *
+ * Unlike the keyboard, a gamepad is not a source of events here: the Gamepad API has
+ * `gamepadconnected`/`gamepaddisconnected` and nothing else — a button press fires no
+ * event at all. `navigator.getGamepads()` hands back a *snapshot* of every pad's
+ * current state, so this is polled once per wake of the render loop and diffed against
+ * the previous snapshot to recover the press/release edges the joypad wants. One frame
+ * (~16.7 ms) of latency is the granularity the emulator already runs at, so polling
+ * more often would buy nothing.
+ *
+ * Polling is also what makes a pad appear at all: Chrome exposes no pads until one has
+ * been interacted with, and reveals them through a later `getGamepads()` call rather
+ * than retroactively. Nothing extra is needed to pick that up.
+ *
+ * # Analog sticks are not a d-pad
+ *
+ * The DMG's d-pad is four switches: a direction is held or it isn't. A stick reports a
+ * continuous position, so it is thresholded into at most one direction per axis. The
+ * diff against the previous snapshot is what keeps a resting-at-0.7 stick from
+ * re-pressing Right on every frame.
+ */
+/**
+ * Standard-layout button indices mapped to Game Boy buttons.
+ *
+ * A and B sit on a diagonal on the DMG — B lower-left, A upper-right — so the East and
+ * South face buttons reproduce that under the thumb. The Gamepad API reports face
+ * buttons by *position*, not by printed label: index 0 is always the bottom button and
+ * index 1 the right-hand one, whatever a given pad prints on them.
+ */
+export const DEFAULT_GAMEPAD_MAP = {
+    0: "b", // South
+    1: "a", // East
+    8: "select", // Back/Select
+    9: "start",
+    12: "up",
+    13: "down",
+    14: "left",
+    15: "right",
+};
+/**
+ * How far a stick must be pushed before it counts as a direction press.
+ *
+ * Half deflection, the same figure the desktop build uses: high enough that a drifting
+ * or off-centre stick does not hold a direction on its own, low enough that a diagonal
+ * registers on both axes.
+ */
+const STICK_THRESHOLD = 0.5;
+/** Standard-layout axis indices. The right stick (2, 3) is deliberately ignored. */
+const LEFT_STICK_X = 0;
+const LEFT_STICK_Y = 1;
+/**
+ * Everything held across every connected pad, as a set of Game Boy buttons.
+ *
+ * Every pad is accepted rather than picking a "player 1": the Game Boy has one player,
+ * so asking which controller owns it would be ceremony for nothing.
+ *
+ * Pads whose `mapping` is not `"standard"` are skipped entirely. The indices in a
+ * non-standard layout are whatever the driver happened to enumerate, so guessing at
+ * them produces confidently wrong bindings rather than none; a page with such a pad can
+ * pass `gamepadMap: null` and drive `press`/`release` itself.
+ */
+export function heldButtons(pads, map) {
+    const held = new Set();
+    for (const pad of pads) {
+        if (!pad || pad.mapping !== "standard")
+            continue;
+        pad.buttons.forEach((button, index) => {
+            // `pressed` rather than a threshold on `value`: the browser already applies the
+            // right one per button, and the Game Boy has no analog inputs to preserve.
+            if (!button.pressed)
+                return;
+            const mapped = map[index];
+            if (mapped)
+                held.add(mapped);
+        });
+        // The stick is a direction, not an index, so it is not part of `map`. Note the Y
+        // sign: the Gamepad API reports +1 as *down*, the opposite of the convention the
+        // desktop build's gilrs uses.
+        addAxis(held, pad.axes[LEFT_STICK_X], "left", "right");
+        addAxis(held, pad.axes[LEFT_STICK_Y], "up", "down");
+    }
+    cancelOpposites(held);
+    return held;
+}
+/** Adds whichever direction an axis position is holding, if any. */
+function addAxis(held, value, negative, positive) {
+    if (value === undefined)
+        return;
+    if (value <= -STICK_THRESHOLD)
+        held.add(negative);
+    else if (value >= STICK_THRESHOLD)
+        held.add(positive);
+}
+/**
+ * Drops both halves of an opposing pair held at once.
+ *
+ * A physical d-pad cannot produce Left+Right — it is one rocker — and some games handle
+ * the impossible state badly. Two sources can still ask for it here: a stick pushed one
+ * way while the d-pad is held the other, or two pads disagreeing. Neutral is the
+ * closest reachable state.
+ */
+function cancelOpposites(held) {
+    const pairs = [
+        ["left", "right"],
+        ["up", "down"],
+    ];
+    for (const [a, b] of pairs) {
+        if (held.has(a) && held.has(b)) {
+            held.delete(a);
+            held.delete(b);
+        }
+    }
+}
+/**
+ * The edges between two snapshots.
+ *
+ * Releases come first so that flicking a stick from Left straight through centre to
+ * Right cannot leave Left stuck down for the instant the presses are applied.
+ */
+export function diff(previous, next) {
+    const actions = [];
+    for (const button of previous) {
+        if (!next.has(button))
+            actions.push({ type: "release", button });
+    }
+    for (const button of next) {
+        if (!previous.has(button))
+            actions.push({ type: "press", button });
+    }
+    return actions;
+}
+/** Remembers the last snapshot so each poll can report only what changed. */
+export class GamepadInput {
+    map;
+    held = new Set();
+    constructor(map = DEFAULT_GAMEPAD_MAP) {
+        this.map = map;
+    }
+    /** Diffs the pads against the previous poll and returns the edges to apply. */
+    poll(pads) {
+        const next = heldButtons(pads, this.map);
+        const actions = diff(this.held, next);
+        this.held = next;
+        return actions;
+    }
+    /**
+     * Releases everything currently held, forgetting the snapshot.
+     *
+     * Used when the loop stops: a button held at the moment of a pause would otherwise
+     * still be held from the emulator's point of view, with no poll coming to release it.
+     */
+    releaseAll() {
+        const actions = diff(this.held, new Set());
+        this.held = new Set();
+        return actions;
+    }
+}

package/dist/index.d.ts

@@ -7,6 +7,8 @@
  * ships as a normal ES module asset next to this file, and the audio worklet is
  * inlined as a Blob URL.
  */
+import { type GameKoiEvents } from "./events.js";
+export type { ButtonEvent, ButtonSource, GameKoiEvents, Listener, Unsubscribe, } from "./events.js";
 export type Button = "up" | "down" | "left" | "right" | "a" | "b" | "start" | "select";
 export interface GameKoiOptions {
     /** Canvas the emulator draws into. Resized to the Game Boy's 160x144. */
@@ -19,6 +21,19 @@ export interface GameKoiOptions {
      * build's layout: arrow keys, Z/X, Enter, right Shift.
      */
     keymap?: Record<string, Button> | null;
+    /**
+     * Maps a standard-layout gamepad's button indices to a button. Pass `null` to
+     * disable gamepad polling entirely. Defaults to the desktop build's layout: d-pad,
+     * East/South face buttons for A/B, Start and Back/Select. The left analog stick acts
+     * as a d-pad regardless of this map, since it is a direction rather than an index.
+     */
+    gamepadMap?: Record<number, Button> | null;
+    /**
+     * `KeyboardEvent.code` that toggles the debug stats panel. Default `"Backquote"`
+     * (the ` / ~ key). Pass `null` to bind no key and drive {@link GameKoi.toggleOverlay}
+     * yourself. Like `keymap`, this is a physical key position, not a character.
+     */
+    overlayKey?: string | null;
     /** Samples to keep queued ahead of playback. Default 1600 (~2 frames at 48kHz). */
     targetBuffer?: number;
     /**
@@ -36,14 +51,25 @@ export declare class GameKoi {
     private readonly wasmMemory;
     private readonly imageData;
     private readonly keymap;
+    private readonly gamepad;
     private readonly targetBuffer;
     private readonly maxFramesPerWake;
+    private readonly stats;
+    private readonly emitter;
+    /** What the joypad currently has down, whichever device put it there. */
+    private readonly held;
     private emulator;
     private buffered;
+    /** Cumulative worklet counters, as last reported. See `worklet.ts`. */
+    private underruns;
+    private dropped;
+    /** Built on first toggle, so a page that never opens it gets no element. */
+    private overlay;
     private running;
     private rafHandle;
     private keydownListener?;
     private keyupListener?;
+    private overlayListener?;
     private constructor();
     /**
      * Builds and starts a running emulator.
@@ -56,12 +82,75 @@ export declare class GameKoi {
     loadRom(rom: Uint8Array): void;
     press(button: Button): void;
     release(button: Button): void;
+    /** Everything the joypad has down right now — a snapshot, safe to keep. */
+    get pressed(): ReadonlySet<Button>;
+    /**
+     * Listens for button edges, from any input path — the built-in keyboard and gamepad
+     * handling as well as `press`/`release` calls.
+     *
+     * Returns a function that removes the listener again:
+     *
+     * ```ts
+     * const stop = koi.on("press", ({ button, pressed }) => render(pressed));
+     * koi.on("release", ({ button, pressed }) => render(pressed));
+     * ```
+     *
+     * Only *changes* are reported: a key held down with autorepeat, a stick resting past
+     * the threshold, or `press("a")` twice in a row each produce one `press` event and no
+     * `release` until the button actually comes up.
+     */
+    on<K extends keyof GameKoiEvents>(type: K, listener: (event: GameKoiEvents[K]) => void): () => void;
+    /** Removes a listener registered with {@link on}. */
+    off<K extends keyof GameKoiEvents>(type: K, listener: (event: GameKoiEvents[K]) => void): void;
+    /**
+     * The one path to the emulated joypad, so every device's edges are counted once.
+     *
+     * A repeat is dropped here rather than forwarded: `Joypad::press` is idempotent, so
+     * skipping it changes nothing for the machine, and it is what makes the events edges
+     * instead of a restatement of whatever the browser felt like repeating.
+     */
+    private setButton;
+    /** Lets go of everything held, emitting the releases. */
+    private releaseAll;
+    /**
+     * Shows or hides the debug stats panel — the same thing the ` key does.
+     *
+     * The panel is built the first time this is called, so a page that never opens it
+     * never gets an extra element in its DOM.
+     */
+    toggleOverlay(): void;
+    /** Whether the stats panel is currently showing. */
+    get overlayVisible(): boolean;
     pause(): void;
     resume(): void;
     /** Stops the loop, releases wasm memory, and tears down the audio graph. */
     dispose(): void;
     private loop;
+    /**
+     * Feeds the counters and refreshes the panel.
+     *
+     * Always run, not just while the panel is open: the averages are computed over half a
+     * second, so a panel that only started counting when it opened would show nothing for
+     * its first window. The cost is four `performance.now()` reads per wake.
+     */
+    private recordWake;
     private drawFrame;
+    /**
+     * Reads every connected pad and applies whatever changed since the last wake.
+     *
+     * Done here rather than from a listener because the Gamepad API fires no event for a
+     * button: `getGamepads()` is a snapshot and polling it is the only way to see one.
+     */
+    private pollGamepads;
+    private applyGamepadActions;
     private attachKeyboard;
     private detachKeyboard;
+    /**
+     * Binds the panel's toggle key.
+     *
+     * Its own listener rather than a case inside the keymap one, because the two are
+     * independent: a page that drives the joypad itself (`keymap: null`) can still want
+     * the panel, and the panel key is not a Game Boy button.
+     */
+    private attachOverlayKey;
 }