game-koi 0.1.0 → 0.2.0

package/README.md

@@ -26,10 +26,51 @@ 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.
+
+### 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 +79,18 @@ 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.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/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

@@ -19,6 +19,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 +49,22 @@ 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 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 +77,45 @@ export declare class GameKoi {
     loadRom(rom: Uint8Array): void;
     press(button: Button): void;
     release(button: Button): void;
+    /**
+     * 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;
 }

package/dist/index.js

@@ -9,6 +9,9 @@
  */
 import init, { Emulator } from "../wasm/game_koi_web.js";
 import { WORKLET_SOURCE } from "./worklet.js";
+import { DEFAULT_GAMEPAD_MAP, GamepadInput } from "./gamepad.js";
+import { FrameStats } from "./stats.js";
+import { StatsOverlay } from "./overlay.js";
 const DEFAULT_KEYMAP = {
     ArrowRight: "right",
     ArrowLeft: "left",
@@ -35,29 +38,43 @@ export class GameKoi {
     wasmMemory;
     imageData;
     keymap;
+    gamepad;
     targetBuffer;
     maxFramesPerWake;
+    stats;
     emulator;
     buffered = 0;
+    /** Cumulative worklet counters, as last reported. See `worklet.ts`. */
+    underruns = 0;
+    dropped = 0;
+    /** Built on first toggle, so a page that never opens it gets no element. */
+    overlay = null;
     running = false;
     rafHandle = 0;
     keydownListener;
     keyupListener;
-    constructor(emulator, wasmMemory, ctx, audioContext, worklet, keymap, targetBuffer, maxFramesPerWake) {
+    overlayListener;
+    constructor(emulator, wasmMemory, ctx, audioContext, worklet, keymap, gamepadMap, overlayKey, targetBuffer, maxFramesPerWake) {
         this.emulator = emulator;
         this.wasmMemory = wasmMemory;
         this.ctx = ctx;
         this.audioContext = audioContext;
         this.worklet = worklet;
         this.keymap = keymap;
+        this.gamepad = gamepadMap ? new GamepadInput(gamepadMap) : null;
         this.targetBuffer = targetBuffer;
         this.maxFramesPerWake = maxFramesPerWake;
         this.imageData = ctx.createImageData(Emulator.width(), Emulator.height());
+        this.stats = new FrameStats(performance.now());
         this.worklet.port.onmessage = (event) => {
             this.buffered = event.data.buffered;
+            this.underruns = event.data.underruns;
+            this.dropped = event.data.dropped;
         };
         if (keymap)
             this.attachKeyboard();
+        if (overlayKey !== null)
+            this.attachOverlayKey(overlayKey);
     }
     /**
      * Builds and starts a running emulator.
@@ -87,13 +104,18 @@ export class GameKoi {
         worklet.connect(audioContext.destination);
         const emulator = new Emulator(options.rom, audioContext.sampleRate);
         const keymap = options.keymap === null ? null : options.keymap ?? DEFAULT_KEYMAP;
-        const koi = new GameKoi(emulator, wasm.memory, ctx, audioContext, worklet, keymap, options.targetBuffer ?? 1600, options.maxFramesPerWake ?? 4);
+        const gamepadMap = options.gamepadMap === null ? null : options.gamepadMap ?? DEFAULT_GAMEPAD_MAP;
+        const koi = new GameKoi(emulator, wasm.memory, ctx, audioContext, worklet, keymap, gamepadMap, options.overlayKey === null ? null : options.overlayKey ?? "Backquote", options.targetBuffer ?? 1600, options.maxFramesPerWake ?? 4);
         koi.running = true;
         koi.loop();
         return koi;
     }
     /** Swaps in a new ROM, keeping the same canvas and audio graph. */
     loadRom(rom) {
+        // The new machine's joypad starts with nothing held, so the snapshot of what is
+        // held has to start over too or the first poll will emit no press for a direction
+        // that was already down.
+        this.gamepad?.releaseAll();
         this.emulator.free();
         this.emulator = new Emulator(rom, this.audioContext.sampleRate);
     }
@@ -103,9 +125,26 @@ export class GameKoi {
     release(button) {
         this.emulator.release(button);
     }
+    /**
+     * 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() {
+        this.overlay ??= new StatsOverlay(this.ctx.canvas);
+        this.overlay.toggle();
+    }
+    /** Whether the stats panel is currently showing. */
+    get overlayVisible() {
+        return this.overlay?.visible ?? false;
+    }
     pause() {
         this.running = false;
         cancelAnimationFrame(this.rafHandle);
+        // A direction held at the moment of the pause has no poll coming to release it,
+        // so it would still be down when the machine resumes.
+        this.applyGamepadActions(this.gamepad?.releaseAll());
         void this.audioContext.suspend();
     }
     resume() {
@@ -120,6 +159,9 @@ export class GameKoi {
         this.running = false;
         cancelAnimationFrame(this.rafHandle);
         this.detachKeyboard();
+        if (this.overlayListener)
+            removeEventListener("keydown", this.overlayListener);
+        this.overlay?.dispose();
         this.emulator.free();
         this.worklet.disconnect();
         void this.audioContext.close();
@@ -127,6 +169,11 @@ export class GameKoi {
     loop = () => {
         if (!this.running)
             return;
+        const wokeAt = performance.now();
+        this.pollGamepads();
+        // Measured from after the input poll: reading a gamepad snapshot is neither
+        // emulation nor drawing, and it costs a fraction of a microsecond.
+        const emulateStart = performance.now();
         // Emulate however many frames the audio buffer is short by, capped. Audio wins
         // when the display's refresh rate and the Game Boy's 59.73Hz disagree, since a
         // dry buffer is audible and a repeated frame is not.
@@ -148,10 +195,39 @@ export class GameKoi {
             }
             frames++;
         }
+        const drawStart = performance.now();
         if (frames > 0)
             this.drawFrame();
+        const drawEnd = performance.now();
+        this.recordWake(wokeAt, emulateStart, drawStart, drawEnd, frames);
         this.rafHandle = requestAnimationFrame(this.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.
+     */
+    recordWake(wokeAt, emulateStart, drawStart, drawEnd, frames) {
+        this.stats.wake({
+            emulate: drawStart - emulateStart,
+            draw: frames > 0 ? drawEnd - drawStart : 0,
+            frames,
+            // The catch-up was clamped and the buffer is still short, so a deficit is
+            // being carried into the next wake.
+            capped: frames >= this.maxFramesPerWake && this.buffered < this.targetBuffer,
+        }, wokeAt);
+        this.stats.setAudio({
+            buffered: this.buffered,
+            target: this.targetBuffer,
+            underruns: this.underruns,
+            dropped: this.dropped,
+            sampleRate: this.audioContext.sampleRate,
+            state: this.audioContext.state,
+        });
+        this.overlay?.update(this.stats.snapshot(), wokeAt);
+    }
     drawFrame() {
         // Read `wasmMemory.buffer` fresh rather than caching it: any wasm allocation can
         // grow linear memory, which allocates a new ArrayBuffer and silently detaches
@@ -161,6 +237,30 @@ export class GameKoi {
         this.imageData.data.set(bytes);
         this.ctx.putImageData(this.imageData, 0, 0);
     }
+    /**
+     * 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.
+     */
+    pollGamepads() {
+        if (!this.gamepad)
+            return;
+        // Guarded because the API is absent outside a secure context, and in a few
+        // embedded webviews that still have no gamepad support at all.
+        const pads = navigator.getGamepads?.();
+        if (!pads)
+            return;
+        this.applyGamepadActions(this.gamepad.poll(pads));
+    }
+    applyGamepadActions(actions) {
+        for (const action of actions ?? []) {
+            if (action.type === "press")
+                this.press(action.button);
+            else
+                this.release(action.button);
+        }
+    }
     attachKeyboard() {
         this.keydownListener = (event) => {
             const button = this.keymap?.[event.code];
@@ -185,4 +285,20 @@ export class GameKoi {
         if (this.keyupListener)
             removeEventListener("keyup", this.keyupListener);
     }
+    /**
+     * 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.
+     */
+    attachOverlayKey(code) {
+        this.overlayListener = (event) => {
+            if (event.code !== code || event.repeat)
+                return;
+            this.toggleOverlay();
+            event.preventDefault();
+        };
+        addEventListener("keydown", this.overlayListener);
+    }
 }

package/dist/overlay.d.ts

@@ -0,0 +1,87 @@
+/**
+ * The debug stats panel.
+ *
+ * This is the browser counterpart of `game-koi-desktop`'s `overlay.rs`, and the split is
+ * the same on both sides: `stats.ts` counts, this draws. What differs is the medium.
+ * The desktop panel is egui, rendered into the same wgpu pass as the game; egui here
+ * would mean bringing wgpu or WebGL into a package whose whole rendering path is one
+ * `putImageData` call, and roughly 2 MB of wasm paid by every consumer whether or not
+ * they ever press the key. So this is a plain DOM panel with the same content.
+ *
+ * Three consequences of that choice, all deliberate:
+ *
+ * - **It is a sibling of the canvas, not a wrapper around it.** The element is appended
+ *   to `document.body` and positioned over the canvas from its bounding rect. Wrapping
+ *   the consumer's canvas in a new element would be the tidier CSS, but it would move
+ *   their node in the document and break any selector or layout rule that depended on
+ *   where it was.
+ * - **`pointer-events: none`.** The panel is read-only, so it must never swallow a click
+ *   meant for the page underneath. The desktop panel does have widgets, but the two it
+ *   has — vsync and the CRT mode — are host-render settings that do not exist here.
+ * - **Styles are inline.** Nothing to serve, nothing for a bundler to find, and no
+ *   chance of a page's stylesheet reaching in; the same reasoning that keeps the audio
+ *   worklet a Blob rather than a file.
+ */
+import type { StatsSnapshot } from "./stats.js";
+/** A read-only panel of counters, floating over the emulator's canvas. */
+export declare class StatsOverlay {
+    private readonly canvas;
+    private readonly element;
+    private readonly grid;
+    private readonly values;
+    private shown;
+    private lastRefresh;
+    constructor(canvas: HTMLCanvasElement);
+    get visible(): boolean;
+    toggle(): void;
+    /**
+     * Rewrites the panel, at most every {@link REFRESH_MS}.
+     *
+     * Cheap to call every frame — while hidden it does nothing at all, which is what keeps
+     * a switched-off feature costing a branch rather than a layout.
+     */
+    update(snapshot: StatsSnapshot, now: number): void;
+    dispose(): void;
+    /**
+     * Anchors the panel to the canvas's current position.
+     *
+     * Re-read rather than cached because a page can scroll, resize or reflow under us with
+     * no event this module sees. `getBoundingClientRect` forces layout, which is why it
+     * happens on the refresh tick and only while the panel is open.
+     */
+    private position;
+    private addRow;
+    /**
+     * A rule across both columns.
+     *
+     * `grid-column: 1 / -1` rather than one cell per column: two cells would be broken in
+     * the middle by the column gap, which reads as two dashes rather than the single line
+     * egui draws.
+     */
+    private addSeparator;
+    private set;
+}
+/**
+ * A duration in milliseconds at a fixed width, so the column does not jitter.
+ *
+ * The desktop formats these as `{:>6.2} ms` for exactly the same reason.
+ */
+export declare function formatMs(ms: number): string;
+export declare function formatPercent(percent: number): string;
+/** A plain count, right-aligned to the same width as the percentages above it. */
+export declare function count(value: number): string;
+/**
+ * Green through to red as a figure approaches and passes its budget.
+ *
+ * Only worth colouring near the limit: a number that matters at 100% is easy to miss if
+ * it spends most of its time at 12%.
+ */
+export declare function loadColour(fraction: number): string;
+/**
+ * How alarming the audio buffer's depth is.
+ *
+ * Zero is not a warning but a failure that was audible: the worklet emitted silence.
+ * Below half the target is the warning, because that is the buffer draining rather than
+ * sitting where the pacing loop means to hold it.
+ */
+export declare function bufferColour(bufferedMs: number, targetMs: number): string;

package/dist/overlay.js

@@ -0,0 +1,245 @@
+/**
+ * The debug stats panel.
+ *
+ * This is the browser counterpart of `game-koi-desktop`'s `overlay.rs`, and the split is
+ * the same on both sides: `stats.ts` counts, this draws. What differs is the medium.
+ * The desktop panel is egui, rendered into the same wgpu pass as the game; egui here
+ * would mean bringing wgpu or WebGL into a package whose whole rendering path is one
+ * `putImageData` call, and roughly 2 MB of wasm paid by every consumer whether or not
+ * they ever press the key. So this is a plain DOM panel with the same content.
+ *
+ * Three consequences of that choice, all deliberate:
+ *
+ * - **It is a sibling of the canvas, not a wrapper around it.** The element is appended
+ *   to `document.body` and positioned over the canvas from its bounding rect. Wrapping
+ *   the consumer's canvas in a new element would be the tidier CSS, but it would move
+ *   their node in the document and break any selector or layout rule that depended on
+ *   where it was.
+ * - **`pointer-events: none`.** The panel is read-only, so it must never swallow a click
+ *   meant for the page underneath. The desktop panel does have widgets, but the two it
+ *   has — vsync and the CRT mode — are host-render settings that do not exist here.
+ * - **Styles are inline.** Nothing to serve, nothing for a bundler to find, and no
+ *   chance of a page's stylesheet reaching in; the same reasoning that keeps the audio
+ *   worklet a Blob rather than a file.
+ */
+/**
+ * How often the text is rewritten.
+ *
+ * Deliberately slower than the frame rate: the underlying averages only change when a
+ * sampling window closes, and text that changes 60 times a second is unreadable anyway.
+ * The DOM writes are what this throttle is really for — the measurements carry on every
+ * wake regardless.
+ */
+const REFRESH_MS = 250;
+/** Distance from the canvas's top-left corner, matching the desktop panel's [8, 8]. */
+const INSET_PX = 8;
+const TEXT = "#c8d0d8";
+const DIM = "#8896a0";
+const WARN = "#e8c060";
+const BAD = "#e05050";
+const PANEL_STYLE = {
+    position: "fixed",
+    // Above anything a page is plausibly stacking, since a debug panel hidden behind the
+    // page's own chrome would be useless.
+    zIndex: "2147483647",
+    pointerEvents: "none",
+    font: "12px/1.45 ui-monospace, SFMono-Regular, Menlo, Consolas, monospace",
+    color: TEXT,
+    background: "rgba(8, 24, 32, 0.86)",
+    border: "1px solid rgba(136, 192, 112, 0.4)",
+    borderRadius: "4px",
+    padding: "6px 8px",
+    display: "none",
+};
+/** A read-only panel of counters, floating over the emulator's canvas. */
+export class StatsOverlay {
+    canvas;
+    element;
+    grid;
+    values = new Map();
+    shown = false;
+    lastRefresh = 0;
+    constructor(canvas) {
+        this.canvas = canvas;
+        this.element = document.createElement("div");
+        Object.assign(this.element.style, PANEL_STYLE);
+        const title = document.createElement("div");
+        title.textContent = "Stats";
+        title.style.marginBottom = "4px";
+        title.style.color = DIM;
+        this.element.appendChild(title);
+        this.grid = document.createElement("div");
+        this.grid.style.display = "grid";
+        this.grid.style.gridTemplateColumns = "auto auto";
+        this.grid.style.columnGap = "14px";
+        this.element.appendChild(this.grid);
+        // The same grouping as the desktop panel: how fast, what it cost, how the two
+        // clocks relate, and what the audio device is doing.
+        this.addRow("FPS");
+        this.addRow("Speed");
+        this.addSeparator();
+        this.addRow("  emulate");
+        this.addRow("  draw");
+        this.addRow("Work");
+        this.addSeparator();
+        this.addRow("Frames/wake");
+        this.addRow("Refresh");
+        this.addRow("Capped");
+        this.addSeparator();
+        this.addRow("Buffer");
+        this.addRow("Underruns");
+        this.addRow("Dropped");
+        this.addRow("Output");
+        document.body.appendChild(this.element);
+    }
+    get visible() {
+        return this.shown;
+    }
+    toggle() {
+        this.shown = !this.shown;
+        this.element.style.display = this.shown ? "block" : "none";
+        // Force the next update through: the panel should not open showing whatever was
+        // last written up to a refresh interval ago.
+        this.lastRefresh = 0;
+    }
+    /**
+     * Rewrites the panel, at most every {@link REFRESH_MS}.
+     *
+     * Cheap to call every frame — while hidden it does nothing at all, which is what keeps
+     * a switched-off feature costing a branch rather than a layout.
+     */
+    update(snapshot, now) {
+        if (!this.shown)
+            return;
+        if (now - this.lastRefresh < REFRESH_MS)
+            return;
+        this.lastRefresh = now;
+        this.position();
+        this.set("FPS", snapshot.fps.toFixed(1));
+        this.set("Speed", formatPercent(snapshot.speedPercent));
+        this.set("  emulate", formatMs(snapshot.emulate));
+        this.set("  draw", formatMs(snapshot.draw));
+        // The headline cost figure, coloured the same way the desktop colours its budget:
+        // worth noticing near the limit, noise the rest of the time.
+        this.set("Work", formatPercent(snapshot.workFraction * 100), loadColour(snapshot.workFraction));
+        this.set("Frames/wake", snapshot.framesPerWake.toFixed(2));
+        this.set("Refresh", `${snapshot.wakeRate.toFixed(1)} Hz`);
+        // A capped wake means the catch-up was clamped and a deficit was left behind —
+        // usually a backgrounded tab, occasionally a machine that cannot keep up.
+        this.set("Capped", count(snapshot.cappedWakes), snapshot.cappedWakes > 0 ? WARN : TEXT);
+        const audio = snapshot.audio;
+        if (!audio) {
+            // Only reachable in the first moments, before the worklet's first report.
+            this.set("Buffer", "—");
+            this.set("Underruns", "—");
+            this.set("Dropped", "—");
+            this.set("Output", "—");
+            return;
+        }
+        const targetMs = (audio.target / audio.sampleRate) * 1000;
+        this.set("Buffer", `${audio.bufferedMs.toFixed(1)} ms`, bufferColour(audio.bufferedMs, targetMs));
+        // Cumulative, and the closest thing here to the desktop's late-frame count: an
+        // underrun is a moment of silence that was actually heard.
+        this.set("Underruns", count(audio.underruns), audio.underruns > 0 ? WARN : TEXT);
+        // The opposite failure — the page ran ahead of the sound card and the ring threw
+        // samples away. Normal in small numbers after a tab comes back to the foreground.
+        this.set("Dropped", count(audio.dropped), audio.dropped > 0 ? WARN : TEXT);
+        this.set("Output", `${(audio.sampleRate / 1000).toFixed(1)}k ${audio.state}`, 
+        // A suspended context is the first thing to check when there is no sound, and
+        // nothing else on the panel would say so.
+        audio.state === "running" ? TEXT : WARN);
+    }
+    dispose() {
+        this.element.remove();
+    }
+    /**
+     * Anchors the panel to the canvas's current position.
+     *
+     * Re-read rather than cached because a page can scroll, resize or reflow under us with
+     * no event this module sees. `getBoundingClientRect` forces layout, which is why it
+     * happens on the refresh tick and only while the panel is open.
+     */
+    position() {
+        const rect = this.canvas.getBoundingClientRect();
+        this.element.style.left = `${rect.left + INSET_PX}px`;
+        this.element.style.top = `${rect.top + INSET_PX}px`;
+    }
+    addRow(label) {
+        const labelCell = document.createElement("span");
+        labelCell.textContent = label;
+        labelCell.style.color = DIM;
+        // Leading spaces mark the sub-rows of the work breakdown, as they do on the
+        // desktop; without this the browser collapses them.
+        labelCell.style.whiteSpace = "pre";
+        const valueCell = document.createElement("span");
+        valueCell.textContent = "—";
+        valueCell.style.textAlign = "right";
+        valueCell.style.whiteSpace = "pre";
+        this.grid.appendChild(labelCell);
+        this.grid.appendChild(valueCell);
+        this.values.set(label, valueCell);
+    }
+    /**
+     * A rule across both columns.
+     *
+     * `grid-column: 1 / -1` rather than one cell per column: two cells would be broken in
+     * the middle by the column gap, which reads as two dashes rather than the single line
+     * egui draws.
+     */
+    addSeparator() {
+        const rule = document.createElement("div");
+        rule.style.gridColumn = "1 / -1";
+        rule.style.borderTop = "1px solid rgba(200, 208, 216, 0.15)";
+        rule.style.margin = "3px 0";
+        this.grid.appendChild(rule);
+    }
+    set(label, text, colour = TEXT) {
+        const cell = this.values.get(label);
+        if (!cell)
+            return;
+        cell.textContent = text;
+        cell.style.color = colour;
+    }
+}
+/**
+ * A duration in milliseconds at a fixed width, so the column does not jitter.
+ *
+ * The desktop formats these as `{:>6.2} ms` for exactly the same reason.
+ */
+export function formatMs(ms) {
+    return `${ms.toFixed(2).padStart(6)} ms`;
+}
+export function formatPercent(percent) {
+    return `${percent.toFixed(0).padStart(4)}%`;
+}
+/** A plain count, right-aligned to the same width as the percentages above it. */
+export function count(value) {
+    return value.toString().padStart(5);
+}
+/**
+ * Green through to red as a figure approaches and passes its budget.
+ *
+ * Only worth colouring near the limit: a number that matters at 100% is easy to miss if
+ * it spends most of its time at 12%.
+ */
+export function loadColour(fraction) {
+    if (fraction > 1)
+        return BAD;
+    if (fraction > 0.8)
+        return WARN;
+    return TEXT;
+}
+/**
+ * How alarming the audio buffer's depth is.
+ *
+ * Zero is not a warning but a failure that was audible: the worklet emitted silence.
+ * Below half the target is the warning, because that is the buffer draining rather than
+ * sitting where the pacing loop means to hold it.
+ */
+export function bufferColour(bufferedMs, targetMs) {
+    if (bufferedMs <= 0)
+        return BAD;
+    if (bufferedMs < targetMs / 2)
+        return WARN;
+    return TEXT;
+}

package/dist/stats.d.ts

@@ -0,0 +1,116 @@
+/**
+ * Host-side performance counters for the browser build.
+ *
+ * Everything here describes the *emulator*, not the emulated machine: how fast the page
+ * is managing to run it, and whether it is keeping up. A Game Boy has no idea what a
+ * wall clock is — its own notion of a frame is 70224 T-cycles, and that number never
+ * varies however slowly they are executed.
+ *
+ * This is the browser counterpart of `game-koi-desktop`'s `stats.rs`, and it counts
+ * different things on purpose, because the two frontends are paced differently.
+ *
+ * # Frames are not wakes
+ *
+ * The desktop sleeps until each 16.74 ms deadline, so one loop iteration is one frame
+ * and a frame rate is just how often the loop ran. Here `requestAnimationFrame` wakes at
+ * the *display's* rate — 120 Hz on a fast panel, 0 Hz in a backgrounded tab — and each
+ * wake emulates however many frames the audio buffer is short by, which may be two, one
+ * or none. Counting wakes would report the refresh rate and say nothing about the
+ * emulator, so `fps` counts frames the emulator actually completed. `framesPerWake` is
+ * the ratio between the two clocks: 1.0 on a 60 Hz display, ~0.5 on a 120 Hz one.
+ *
+ * # There is no "blocked" figure here
+ *
+ * The desktop's most useful number is time neither spent working nor slept away, which
+ * is the compositor holding the swapchain. A page never sleeps and never presents, so
+ * that figure has no analogue. Its replacement is the audio buffer: since pacing runs
+ * off the sound card, "am I keeping up" *is* "is the buffer staying full", and a buffer
+ * that reaches zero is the audible failure the whole design exists to avoid. That is why
+ * `underruns` is the closest thing here to the desktop's late-frame count.
+ *
+ * # The clock is passed in, never read
+ *
+ * Nothing in this module calls `performance.now()`; the caller passes the timestamp it
+ * already has. That keeps the counters pure — testable with plain numbers, no timers and
+ * no fake clock.
+ */
+/** The DMG's frame rate. Not 60: 4194304 / 70224 cycles per frame. */
+export declare const TARGET_HZ = 59.7275;
+/** The wall-clock budget for one emulated frame, in milliseconds. */
+export declare const FRAME_MS: number;
+/** What one `requestAnimationFrame` wake did. */
+export interface WakeReport {
+    /** Milliseconds spent running the emulator and handing its samples to the worklet. */
+    emulate: number;
+    /** Milliseconds spent blitting to the canvas; zero when nothing was drawn. */
+    draw: number;
+    /** Frames emulated this wake — often 0 or 1, more while catching up. */
+    frames: number;
+    /** Whether `maxFramesPerWake` clamped the catch-up, leaving a deficit behind. */
+    capped: boolean;
+}
+/** The audio side's view of itself, as last reported by the worklet. */
+export interface AudioReport {
+    /** Sample frames sitting in the worklet's ring, waiting to be played. */
+    buffered: number;
+    /** How many the page tries to keep there. */
+    target: number;
+    /** Cumulative silent samples emitted because the ring was empty. */
+    underruns: number;
+    /** Cumulative samples overwritten because the ring was full. */
+    dropped: number;
+    /** The `AudioContext`'s rate — what the core resamples its output to. */
+    sampleRate: number;
+    /** `"running"`, `"suspended"` or `"closed"`. */
+    state: string;
+}
+/** Everything the panel draws, computed once per refresh. */
+export interface StatsSnapshot {
+    /** Emulated frames per second, averaged over the sampling window. */
+    fps: number;
+    /** `fps` as a percentage of real hardware, where 100% is a DMG. */
+    speedPercent: number;
+    /** Milliseconds of emulation per emulated frame. */
+    emulate: number;
+    /** Milliseconds of canvas blitting per emulated frame. */
+    draw: number;
+    /** `emulate + draw`, the work this page does per frame. */
+    work: number;
+    /** That work as a fraction of the 16.74 ms a frame is worth. */
+    workFraction: number;
+    /** Emulated frames per `rAF` wake: the ratio of the two clocks. */
+    framesPerWake: number;
+    /** How often `rAF` is firing — in practice, the display's refresh rate. */
+    wakeRate: number;
+    frames: number;
+    wakes: number;
+    /** Wakes whose catch-up hit `maxFramesPerWake`. */
+    cappedWakes: number;
+    /** `null` until the worklet has reported once. */
+    audio: (AudioReport & {
+        bufferedMs: number;
+    }) | null;
+}
+/** Rolling counters, recomputed roughly twice a second. */
+export declare class FrameStats {
+    private windowStart;
+    private framesInWindow;
+    private wakesInWindow;
+    private emulateInWindow;
+    private drawInWindow;
+    private fps;
+    private wakeRate;
+    private emulatePerFrame;
+    private drawPerFrame;
+    private framesPerWake;
+    private frames;
+    private wakes;
+    private cappedWakes;
+    private audio;
+    constructor(now: number);
+    /** Records a wake and, once the window is old enough, recomputes the averages. */
+    wake(report: WakeReport, now: number): void;
+    /** Takes the audio thread's latest report of itself. */
+    setAudio(report: AudioReport): void;
+    snapshot(): StatsSnapshot;
+}

package/dist/stats.js

@@ -0,0 +1,120 @@
+/**
+ * Host-side performance counters for the browser build.
+ *
+ * Everything here describes the *emulator*, not the emulated machine: how fast the page
+ * is managing to run it, and whether it is keeping up. A Game Boy has no idea what a
+ * wall clock is — its own notion of a frame is 70224 T-cycles, and that number never
+ * varies however slowly they are executed.
+ *
+ * This is the browser counterpart of `game-koi-desktop`'s `stats.rs`, and it counts
+ * different things on purpose, because the two frontends are paced differently.
+ *
+ * # Frames are not wakes
+ *
+ * The desktop sleeps until each 16.74 ms deadline, so one loop iteration is one frame
+ * and a frame rate is just how often the loop ran. Here `requestAnimationFrame` wakes at
+ * the *display's* rate — 120 Hz on a fast panel, 0 Hz in a backgrounded tab — and each
+ * wake emulates however many frames the audio buffer is short by, which may be two, one
+ * or none. Counting wakes would report the refresh rate and say nothing about the
+ * emulator, so `fps` counts frames the emulator actually completed. `framesPerWake` is
+ * the ratio between the two clocks: 1.0 on a 60 Hz display, ~0.5 on a 120 Hz one.
+ *
+ * # There is no "blocked" figure here
+ *
+ * The desktop's most useful number is time neither spent working nor slept away, which
+ * is the compositor holding the swapchain. A page never sleeps and never presents, so
+ * that figure has no analogue. Its replacement is the audio buffer: since pacing runs
+ * off the sound card, "am I keeping up" *is* "is the buffer staying full", and a buffer
+ * that reaches zero is the audible failure the whole design exists to avoid. That is why
+ * `underruns` is the closest thing here to the desktop's late-frame count.
+ *
+ * # The clock is passed in, never read
+ *
+ * Nothing in this module calls `performance.now()`; the caller passes the timestamp it
+ * already has. That keeps the counters pure — testable with plain numbers, no timers and
+ * no fake clock.
+ */
+/** The DMG's frame rate. Not 60: 4194304 / 70224 cycles per frame. */
+export const TARGET_HZ = 59.7275;
+/** The wall-clock budget for one emulated frame, in milliseconds. */
+export const FRAME_MS = 1000 / TARGET_HZ;
+/**
+ * How long to gather before recomputing the averages.
+ *
+ * A rate computed over a single wake is pure noise — one scheduler hiccup and it reads
+ * 12 fps. Averaging over about half a second gives numbers steady enough to read, which
+ * matters more here than on the desktop because these are rendered as text that a person
+ * is trying to follow rather than a graph.
+ */
+const SAMPLE_WINDOW_MS = 500;
+/** Rolling counters, recomputed roughly twice a second. */
+export class FrameStats {
+    windowStart;
+    framesInWindow = 0;
+    wakesInWindow = 0;
+    emulateInWindow = 0;
+    drawInWindow = 0;
+    fps = 0;
+    wakeRate = 0;
+    emulatePerFrame = 0;
+    drawPerFrame = 0;
+    framesPerWake = 0;
+    frames = 0;
+    wakes = 0;
+    cappedWakes = 0;
+    audio = null;
+    constructor(now) {
+        this.windowStart = now;
+    }
+    /** Records a wake and, once the window is old enough, recomputes the averages. */
+    wake(report, now) {
+        this.wakes++;
+        this.wakesInWindow++;
+        this.frames += report.frames;
+        this.framesInWindow += report.frames;
+        this.emulateInWindow += report.emulate;
+        this.drawInWindow += report.draw;
+        if (report.capped)
+            this.cappedWakes++;
+        const elapsed = now - this.windowStart;
+        if (elapsed < SAMPLE_WINDOW_MS)
+            return;
+        const seconds = elapsed / 1000;
+        this.fps = this.framesInWindow / seconds;
+        this.wakeRate = this.wakesInWindow / seconds;
+        // Per *frame*, not per wake: a wake that emulated nothing did no work, and
+        // averaging those in would report a machine faster than it is.
+        const frames = this.framesInWindow;
+        this.emulatePerFrame = frames > 0 ? this.emulateInWindow / frames : 0;
+        this.drawPerFrame = frames > 0 ? this.drawInWindow / frames : 0;
+        this.framesPerWake = this.wakesInWindow > 0 ? frames / this.wakesInWindow : 0;
+        this.windowStart = now;
+        this.framesInWindow = 0;
+        this.wakesInWindow = 0;
+        this.emulateInWindow = 0;
+        this.drawInWindow = 0;
+    }
+    /** Takes the audio thread's latest report of itself. */
+    setAudio(report) {
+        this.audio = report;
+    }
+    snapshot() {
+        const work = this.emulatePerFrame + this.drawPerFrame;
+        return {
+            fps: this.fps,
+            speedPercent: (this.fps / TARGET_HZ) * 100,
+            emulate: this.emulatePerFrame,
+            draw: this.drawPerFrame,
+            work,
+            workFraction: work / FRAME_MS,
+            framesPerWake: this.framesPerWake,
+            wakeRate: this.wakeRate,
+            frames: this.frames,
+            wakes: this.wakes,
+            cappedWakes: this.cappedWakes,
+            audio: this.audio
+                ? { ...this.audio, bufferedMs: (this.audio.buffered / this.audio.sampleRate) * 1000 }
+                : null,
+        };
+    }
+}

package/dist/worklet.d.ts

@@ -1 +1 @@
-export declare const WORKLET_SOURCE = "\n  const CAPACITY = 48000; // ~0.5s at 48kHz stereo: rides out a slow main thread.\n\n  class KoiProcessor extends AudioWorkletProcessor {\n    constructor() {\n      super();\n      this.left = new Float32Array(CAPACITY);\n      this.right = new Float32Array(CAPACITY);\n      this.readIndex = 0;\n      this.writeIndex = 0;\n\n      this.port.onmessage = (event) => {\n        const { left, right } = event.data;\n        for (let i = 0; i < left.length; i++) {\n          const next = (this.writeIndex + 1) % CAPACITY;\n          // Full: drop the oldest rather than the newest, so audio does not fall\n          // permanently further behind the picture.\n          if (next === this.readIndex) {\n            this.readIndex = (this.readIndex + 1) % CAPACITY;\n          }\n          this.left[this.writeIndex] = left[i];\n          this.right[this.writeIndex] = right[i];\n          this.writeIndex = next;\n        }\n      };\n    }\n\n    available() {\n      return (this.writeIndex - this.readIndex + CAPACITY) % CAPACITY;\n    }\n\n    process(_inputs, outputs) {\n      const output = outputs[0];\n      const outL = output[0];\n      const outR = output.length > 1 ? output[1] : output[0];\n\n      for (let i = 0; i < outL.length; i++) {\n        if (this.readIndex === this.writeIndex) {\n          // Silence on underrun. Holding the last sample turns a click into a buzz,\n          // which is worse.\n          outL[i] = 0;\n          outR[i] = 0;\n        } else {\n          outL[i] = this.left[this.readIndex];\n          outR[i] = this.right[this.readIndex];\n          this.readIndex = (this.readIndex + 1) % CAPACITY;\n        }\n      }\n\n      // The main thread paces itself off this number, so it goes back every block.\n      this.port.postMessage({ buffered: this.available() });\n      return true;\n    }\n  }\n\n  registerProcessor(\"koi-processor\", KoiProcessor);\n";
+export declare const WORKLET_SOURCE = "\n  const CAPACITY = 48000; // ~0.5s at 48kHz stereo: rides out a slow main thread.\n\n  class KoiProcessor extends AudioWorkletProcessor {\n    constructor() {\n      super();\n      this.left = new Float32Array(CAPACITY);\n      this.right = new Float32Array(CAPACITY);\n      this.readIndex = 0;\n      this.writeIndex = 0;\n      // The two ways this can go wrong, counted for the stats panel. Both are\n      // cumulative: what matters is whether they are climbing, not their value.\n      this.underruns = 0;\n      this.dropped = 0;\n\n      this.port.onmessage = (event) => {\n        const { left, right } = event.data;\n        for (let i = 0; i < left.length; i++) {\n          const next = (this.writeIndex + 1) % CAPACITY;\n          // Full: drop the oldest rather than the newest, so audio does not fall\n          // permanently further behind the picture.\n          if (next === this.readIndex) {\n            this.readIndex = (this.readIndex + 1) % CAPACITY;\n            this.dropped++;\n          }\n          this.left[this.writeIndex] = left[i];\n          this.right[this.writeIndex] = right[i];\n          this.writeIndex = next;\n        }\n      };\n    }\n\n    available() {\n      return (this.writeIndex - this.readIndex + CAPACITY) % CAPACITY;\n    }\n\n    process(_inputs, outputs) {\n      const output = outputs[0];\n      const outL = output[0];\n      const outR = output.length > 1 ? output[1] : output[0];\n\n      for (let i = 0; i < outL.length; i++) {\n        if (this.readIndex === this.writeIndex) {\n          // Silence on underrun. Holding the last sample turns a click into a buzz,\n          // which is worse.\n          outL[i] = 0;\n          outR[i] = 0;\n          this.underruns++;\n        } else {\n          outL[i] = this.left[this.readIndex];\n          outR[i] = this.right[this.readIndex];\n          this.readIndex = (this.readIndex + 1) % CAPACITY;\n        }\n      }\n\n      // The main thread paces itself off \"buffered\", so it goes back every block. The\n      // counters ride along in the same message rather than in one of their own \u2014\n      // there is no cheaper time to send them, and a second postMessage per block from\n      // the audio thread would cost more than the numbers are worth.\n      this.port.postMessage({\n        buffered: this.available(),\n        underruns: this.underruns,\n        dropped: this.dropped,\n      });\n      return true;\n    }\n  }\n\n  registerProcessor(\"koi-processor\", KoiProcessor);\n";

package/dist/worklet.js

@@ -10,6 +10,10 @@
 //
 // Kept as a source string, not a separate .js file, so `GameKoi` can register it via a
 // Blob URL — a consumer never needs to serve this file or point a bundler at it.
+//
+// Being a template literal, the body below cannot contain a backtick or a `${`, even in
+// a comment: either one ends the string. The failure is a parse error in *this* file
+// pointing at a line that looks fine.
 export const WORKLET_SOURCE = `
   const CAPACITY = 48000; // ~0.5s at 48kHz stereo: rides out a slow main thread.
 
@@ -20,6 +24,10 @@ export const WORKLET_SOURCE = `
       this.right = new Float32Array(CAPACITY);
       this.readIndex = 0;
       this.writeIndex = 0;
+      // The two ways this can go wrong, counted for the stats panel. Both are
+      // cumulative: what matters is whether they are climbing, not their value.
+      this.underruns = 0;
+      this.dropped = 0;
 
       this.port.onmessage = (event) => {
         const { left, right } = event.data;
@@ -29,6 +37,7 @@ export const WORKLET_SOURCE = `
           // permanently further behind the picture.
           if (next === this.readIndex) {
             this.readIndex = (this.readIndex + 1) % CAPACITY;
+            this.dropped++;
           }
           this.left[this.writeIndex] = left[i];
           this.right[this.writeIndex] = right[i];
@@ -52,6 +61,7 @@ export const WORKLET_SOURCE = `
           // which is worse.
           outL[i] = 0;
           outR[i] = 0;
+          this.underruns++;
         } else {
           outL[i] = this.left[this.readIndex];
           outR[i] = this.right[this.readIndex];
@@ -59,8 +69,15 @@ export const WORKLET_SOURCE = `
         }
       }
 
-      // The main thread paces itself off this number, so it goes back every block.
-      this.port.postMessage({ buffered: this.available() });
+      // The main thread paces itself off "buffered", so it goes back every block. The
+      // counters ride along in the same message rather than in one of their own —
+      // there is no cheaper time to send them, and a second postMessage per block from
+      // the audio thread would cost more than the numbers are worth.
+      this.port.postMessage({
+        buffered: this.available(),
+        underruns: this.underruns,
+        dropped: this.dropped,
+      });
       return true;
     }
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "game-koi",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "A Game Boy (DMG) emulator, compiled to WebAssembly, with a drop-in canvas + audio wrapper",
   "type": "module",
   "main": "dist/index.js",
@@ -20,6 +20,7 @@
   "sideEffects": false,
   "scripts": {
     "build": "tsc -p tsconfig.json",
+    "test": "npm run build && node --test \"test/*.test.js\"",
     "prepublishOnly": "npm run build"
   },
   "keywords": [