game-koi 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Khôi Tran
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,60 @@
+# game-koi
+
+A Game Boy (DMG) emulator, compiled to WebAssembly, wrapped in a small TypeScript API
+that owns the canvas rendering, audio, and pacing loop for you.
+
+```
+npm install game-koi
+```
+
+## Usage
+
+```ts
+import { GameKoi } from "game-koi";
+
+const canvas = document.querySelector("canvas")!;
+const romBytes = new Uint8Array(await (await fetch("/game.gb")).arrayBuffer());
+
+// Call from inside a user gesture (e.g. a click handler) — browsers suspend a
+// freshly created AudioContext otherwise.
+button.addEventListener("click", async () => {
+  const koi = await GameKoi.create({ canvas, rom: romBytes });
+
+  // koi.pause(); koi.resume(); koi.dispose();
+  // koi.press("a"); koi.release("a");
+});
+```
+
+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.
+
+## API
+
+- `GameKoi.create(options)` — builds and starts a running emulator.
+  - `canvas: HTMLCanvasElement` — resized to 160x144 and drawn into every frame.
+  - `rom: Uint8Array` — the `.gb` file's bytes.
+  - `keymap?: Record<string, Button> | null` — maps `KeyboardEvent.code` to a
+    button; `null` disables built-in keyboard handling.
+  - `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.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.
+
+## Notes
+
+- Ships as an ES module with bundled `.d.ts` types; works with any bundler that
+  understands wasm as a fetchable asset (Vite, webpack 5, esbuild, Next.js) as well
+  as directly in a browser via `<script type="module">`, served over `http(s)://`
+  (not `file://` — ES modules and `AudioWorklet` both require an origin).
+- This package is the browser build of
+  [game-koi](https://github.com/KeeTraxx/game-koi), a from-scratch Game Boy emulator
+  written in Rust. The core emulation has no audio/video device of its own; this
+  package is what connects it to a web page.

package/dist/index.d.ts

@@ -0,0 +1,67 @@
+/**
+ * game-koi — a Game Boy (DMG) emulator, compiled to WebAssembly.
+ *
+ * `GameKoi` is the whole integration surface: point it at a canvas and hand it a
+ * ROM's bytes, and it owns wasm setup, the AudioWorklet, and the render/audio pacing
+ * loop. Nothing else needs to be served or configured by the page — the wasm binary
+ * ships as a normal ES module asset next to this file, and the audio worklet is
+ * inlined as a Blob URL.
+ */
+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. */
+    canvas: HTMLCanvasElement;
+    /** The ROM image — a `.gb` file's bytes. */
+    rom: Uint8Array;
+    /**
+     * Maps `KeyboardEvent.code` to a button. Pass `null` to disable built-in keyboard
+     * handling entirely and drive `press`/`release` yourself. Defaults to the desktop
+     * build's layout: arrow keys, Z/X, Enter, right Shift.
+     */
+    keymap?: Record<string, Button> | null;
+    /** Samples to keep queued ahead of playback. Default 1600 (~2 frames at 48kHz). */
+    targetBuffer?: number;
+    /**
+     * Safety cap on frames emulated per wake-up. Without this, a backgrounded tab
+     * (where `requestAnimationFrame` stops firing) would return to a large deficit and
+     * freeze the page catching up. Default 4.
+     */
+    maxFramesPerWake?: number;
+}
+/** A running Game Boy, attached to a canvas and driving an AudioWorklet. */
+export declare class GameKoi {
+    private readonly ctx;
+    private readonly audioContext;
+    private readonly worklet;
+    private readonly wasmMemory;
+    private readonly imageData;
+    private readonly keymap;
+    private readonly targetBuffer;
+    private readonly maxFramesPerWake;
+    private emulator;
+    private buffered;
+    private running;
+    private rafHandle;
+    private keydownListener?;
+    private keyupListener?;
+    private constructor();
+    /**
+     * Builds and starts a running emulator.
+     *
+     * Must be called from inside a user gesture (a click or keypress handler) —
+     * browsers suspend a freshly created `AudioContext` otherwise.
+     */
+    static create(options: GameKoiOptions): Promise<GameKoi>;
+    /** Swaps in a new ROM, keeping the same canvas and audio graph. */
+    loadRom(rom: Uint8Array): void;
+    press(button: Button): void;
+    release(button: Button): void;
+    pause(): void;
+    resume(): void;
+    /** Stops the loop, releases wasm memory, and tears down the audio graph. */
+    dispose(): void;
+    private loop;
+    private drawFrame;
+    private attachKeyboard;
+    private detachKeyboard;
+}

package/dist/index.js

@@ -0,0 +1,188 @@
+/**
+ * game-koi — a Game Boy (DMG) emulator, compiled to WebAssembly.
+ *
+ * `GameKoi` is the whole integration surface: point it at a canvas and hand it a
+ * ROM's bytes, and it owns wasm setup, the AudioWorklet, and the render/audio pacing
+ * loop. Nothing else needs to be served or configured by the page — the wasm binary
+ * ships as a normal ES module asset next to this file, and the audio worklet is
+ * inlined as a Blob URL.
+ */
+import init, { Emulator } from "../wasm/game_koi_web.js";
+import { WORKLET_SOURCE } from "./worklet.js";
+const DEFAULT_KEYMAP = {
+    ArrowRight: "right",
+    ArrowLeft: "left",
+    ArrowUp: "up",
+    ArrowDown: "down",
+    KeyZ: "a",
+    KeyX: "b",
+    Enter: "start",
+    ShiftRight: "select",
+};
+// The wasm module only needs instantiating once per page, no matter how many
+// `GameKoi` instances are created.
+let wasmReady = null;
+function ensureWasm() {
+    if (!wasmReady)
+        wasmReady = init();
+    return wasmReady;
+}
+/** A running Game Boy, attached to a canvas and driving an AudioWorklet. */
+export class GameKoi {
+    ctx;
+    audioContext;
+    worklet;
+    wasmMemory;
+    imageData;
+    keymap;
+    targetBuffer;
+    maxFramesPerWake;
+    emulator;
+    buffered = 0;
+    running = false;
+    rafHandle = 0;
+    keydownListener;
+    keyupListener;
+    constructor(emulator, wasmMemory, ctx, audioContext, worklet, keymap, targetBuffer, maxFramesPerWake) {
+        this.emulator = emulator;
+        this.wasmMemory = wasmMemory;
+        this.ctx = ctx;
+        this.audioContext = audioContext;
+        this.worklet = worklet;
+        this.keymap = keymap;
+        this.targetBuffer = targetBuffer;
+        this.maxFramesPerWake = maxFramesPerWake;
+        this.imageData = ctx.createImageData(Emulator.width(), Emulator.height());
+        this.worklet.port.onmessage = (event) => {
+            this.buffered = event.data.buffered;
+        };
+        if (keymap)
+            this.attachKeyboard();
+    }
+    /**
+     * Builds and starts a running emulator.
+     *
+     * Must be called from inside a user gesture (a click or keypress handler) —
+     * browsers suspend a freshly created `AudioContext` otherwise.
+     */
+    static async create(options) {
+        const wasm = await ensureWasm();
+        const canvas = options.canvas;
+        canvas.width = Emulator.width();
+        canvas.height = Emulator.height();
+        const ctx = canvas.getContext("2d");
+        if (!ctx)
+            throw new Error("canvas 2D context unavailable");
+        const audioContext = new AudioContext();
+        const blobUrl = URL.createObjectURL(new Blob([WORKLET_SOURCE], { type: "application/javascript" }));
+        try {
+            await audioContext.audioWorklet.addModule(blobUrl);
+        }
+        finally {
+            URL.revokeObjectURL(blobUrl);
+        }
+        const worklet = new AudioWorkletNode(audioContext, "koi-processor", {
+            outputChannelCount: [2],
+        });
+        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);
+        koi.running = true;
+        koi.loop();
+        return koi;
+    }
+    /** Swaps in a new ROM, keeping the same canvas and audio graph. */
+    loadRom(rom) {
+        this.emulator.free();
+        this.emulator = new Emulator(rom, this.audioContext.sampleRate);
+    }
+    press(button) {
+        this.emulator.press(button);
+    }
+    release(button) {
+        this.emulator.release(button);
+    }
+    pause() {
+        this.running = false;
+        cancelAnimationFrame(this.rafHandle);
+        void this.audioContext.suspend();
+    }
+    resume() {
+        if (this.running)
+            return;
+        this.running = true;
+        void this.audioContext.resume();
+        this.loop();
+    }
+    /** Stops the loop, releases wasm memory, and tears down the audio graph. */
+    dispose() {
+        this.running = false;
+        cancelAnimationFrame(this.rafHandle);
+        this.detachKeyboard();
+        this.emulator.free();
+        this.worklet.disconnect();
+        void this.audioContext.close();
+    }
+    loop = () => {
+        if (!this.running)
+            return;
+        // 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.
+        let frames = 0;
+        while (this.buffered < this.targetBuffer && frames < this.maxFramesPerWake) {
+            this.emulator.run_frame();
+            const samples = this.emulator.take_samples();
+            if (samples.length > 0) {
+                const count = samples.length / 2;
+                const left = new Float32Array(count);
+                const right = new Float32Array(count);
+                for (let i = 0; i < count; i++) {
+                    left[i] = samples[i * 2];
+                    right[i] = samples[i * 2 + 1];
+                }
+                // Transfer rather than copy: these are throwaway buffers.
+                this.worklet.port.postMessage({ left, right }, [left.buffer, right.buffer]);
+                this.buffered += count;
+            }
+            frames++;
+        }
+        if (frames > 0)
+            this.drawFrame();
+        this.rafHandle = requestAnimationFrame(this.loop);
+    };
+    drawFrame() {
+        // Read `wasmMemory.buffer` fresh rather than caching it: any wasm allocation can
+        // grow linear memory, which allocates a new ArrayBuffer and silently detaches
+        // views over the old one. Re-reading it here means a grown buffer is picked up
+        // automatically instead of producing a zero-length view.
+        const bytes = new Uint8ClampedArray(this.wasmMemory.buffer, this.emulator.frame_ptr(), this.emulator.frame_len());
+        this.imageData.data.set(bytes);
+        this.ctx.putImageData(this.imageData, 0, 0);
+    }
+    attachKeyboard() {
+        this.keydownListener = (event) => {
+            const button = this.keymap?.[event.code];
+            if (button) {
+                this.press(button);
+                event.preventDefault();
+            }
+        };
+        this.keyupListener = (event) => {
+            const button = this.keymap?.[event.code];
+            if (button) {
+                this.release(button);
+                event.preventDefault();
+            }
+        };
+        addEventListener("keydown", this.keydownListener);
+        addEventListener("keyup", this.keyupListener);
+    }
+    detachKeyboard() {
+        if (this.keydownListener)
+            removeEventListener("keydown", this.keydownListener);
+        if (this.keyupListener)
+            removeEventListener("keyup", this.keyupListener);
+    }
+}

package/dist/worklet.d.ts

@@ -0,0 +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";

package/dist/worklet.js

@@ -0,0 +1,69 @@
+// The audio side of the pacing clock. This runs on the browser's audio thread, woken
+// on a schedule the sound hardware drives rather than the display. It owns a ring
+// buffer that the main thread fills; all it does is drain it and report how full it
+// is.
+//
+// Why a ring and not a message per frame: postMessage allocates and is queued behind
+// whatever else the audio thread has to do, and this callback has a hard deadline. A
+// pre-allocated ring written by one thread and read by another needs no allocation and
+// no lock for a single-producer/single-consumer pair like this one.
+//
+// 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.
+export const WORKLET_SOURCE = `
+  const CAPACITY = 48000; // ~0.5s at 48kHz stereo: rides out a slow main thread.
+
+  class KoiProcessor extends AudioWorkletProcessor {
+    constructor() {
+      super();
+      this.left = new Float32Array(CAPACITY);
+      this.right = new Float32Array(CAPACITY);
+      this.readIndex = 0;
+      this.writeIndex = 0;
+
+      this.port.onmessage = (event) => {
+        const { left, right } = event.data;
+        for (let i = 0; i < left.length; i++) {
+          const next = (this.writeIndex + 1) % CAPACITY;
+          // Full: drop the oldest rather than the newest, so audio does not fall
+          // permanently further behind the picture.
+          if (next === this.readIndex) {
+            this.readIndex = (this.readIndex + 1) % CAPACITY;
+          }
+          this.left[this.writeIndex] = left[i];
+          this.right[this.writeIndex] = right[i];
+          this.writeIndex = next;
+        }
+      };
+    }
+
+    available() {
+      return (this.writeIndex - this.readIndex + CAPACITY) % CAPACITY;
+    }
+
+    process(_inputs, outputs) {
+      const output = outputs[0];
+      const outL = output[0];
+      const outR = output.length > 1 ? output[1] : output[0];
+
+      for (let i = 0; i < outL.length; i++) {
+        if (this.readIndex === this.writeIndex) {
+          // Silence on underrun. Holding the last sample turns a click into a buzz,
+          // which is worse.
+          outL[i] = 0;
+          outR[i] = 0;
+        } else {
+          outL[i] = this.left[this.readIndex];
+          outR[i] = this.right[this.readIndex];
+          this.readIndex = (this.readIndex + 1) % CAPACITY;
+        }
+      }
+
+      // The main thread paces itself off this number, so it goes back every block.
+      this.port.postMessage({ buffered: this.available() });
+      return true;
+    }
+  }
+
+  registerProcessor("koi-processor", KoiProcessor);
+`;

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "game-koi",
+  "version": "0.1.0",
+  "description": "A Game Boy (DMG) emulator, compiled to WebAssembly, with a drop-in canvas + audio wrapper",
+  "type": "module",
+  "main": "dist/index.js",
+  "module": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "wasm",
+    "LICENSE"
+  ],
+  "sideEffects": false,
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "gameboy",
+    "game boy",
+    "dmg",
+    "emulator",
+    "wasm",
+    "webassembly"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/KeeTraxx/game-koi.git",
+    "directory": "crates/game-koi-web/js"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "devDependencies": {
+    "typescript": "^5.6.0"
+  }
+}

package/wasm/game_koi_web.d.ts

@@ -0,0 +1,92 @@
+/* tslint:disable */
+/* eslint-disable */
+
+/**
+ * A running Game Boy, owned by JavaScript.
+ */
+export class Emulator {
+    free(): void;
+    [Symbol.dispose](): void;
+    frame_len(): number;
+    /**
+     * Pointer to the RGBA framebuffer inside wasm memory.
+     *
+     * Paired with [`Emulator::frame_len`], this lets the page build a view over wasm
+     * memory once and reuse it. Any call that grows wasm memory can detach that view,
+     * so re-read both after loading a new ROM.
+     */
+    frame_ptr(): number;
+    static height(): number;
+    /**
+     * Builds a machine from a ROM image.
+     *
+     * Fails if the header will not parse or the cartridge uses a mapper the core does
+     * not implement — the same typed failure the desktop build gets, flattened to a
+     * string because that is what crosses into JavaScript.
+     */
+    constructor(rom: Uint8Array, sample_rate: number);
+    /**
+     * Presses a button, named as the page sees it ("a", "start", "dpad-up", ...).
+     *
+     * Unknown names are ignored rather than an error: a key the page does not map is
+     * not a failure worth unwinding across the boundary for.
+     */
+    press(button: string): void;
+    release(button: string): void;
+    /**
+     * Runs until the PPU finishes a frame.
+     *
+     * The cycle budget is the same safety valve the desktop frontend uses: a ROM that
+     * somehow never completes a frame would otherwise wedge the browser tab.
+     */
+    run_frame(): void;
+    /**
+     * Takes the audio produced since the last call, interleaved as L,R,L,R.
+     */
+    take_samples(): Float32Array;
+    static width(): number;
+}
+
+export type InitInput = RequestInfo | URL | Response | BufferSource | WebAssembly.Module;
+
+export interface InitOutput {
+    readonly memory: WebAssembly.Memory;
+    readonly __wbg_emulator_free: (a: number, b: number) => void;
+    readonly emulator_frame_len: (a: number) => number;
+    readonly emulator_frame_ptr: (a: number) => number;
+    readonly emulator_height: () => number;
+    readonly emulator_new: (a: number, b: number, c: number) => [number, number, number];
+    readonly emulator_press: (a: number, b: number, c: number) => void;
+    readonly emulator_release: (a: number, b: number, c: number) => void;
+    readonly emulator_run_frame: (a: number) => void;
+    readonly emulator_take_samples: (a: number) => [number, number];
+    readonly emulator_width: () => number;
+    readonly __wbindgen_externrefs: WebAssembly.Table;
+    readonly __wbindgen_malloc: (a: number, b: number) => number;
+    readonly __externref_table_dealloc: (a: number) => void;
+    readonly __wbindgen_realloc: (a: number, b: number, c: number, d: number) => number;
+    readonly __wbindgen_free: (a: number, b: number, c: number) => void;
+    readonly __wbindgen_start: () => void;
+}
+
+export type SyncInitInput = BufferSource | WebAssembly.Module;
+
+/**
+ * Instantiates the given `module`, which can either be bytes or
+ * a precompiled `WebAssembly.Module`.
+ *
+ * @param {{ module: SyncInitInput }} module - Passing `SyncInitInput` directly is deprecated.
+ *
+ * @returns {InitOutput}
+ */
+export function initSync(module: { module: SyncInitInput } | SyncInitInput): InitOutput;
+
+/**
+ * If `module_or_path` is {RequestInfo} or {URL}, makes a request and
+ * for everything else, calls `WebAssembly.instantiate` directly.
+ *
+ * @param {{ module_or_path: InitInput | Promise<InitInput> }} module_or_path - Passing `InitInput` directly is deprecated.
+ *
+ * @returns {Promise<InitOutput>}
+ */
+export default function __wbg_init (module_or_path?: { module_or_path: InitInput | Promise<InitInput> } | InitInput | Promise<InitInput>): Promise<InitOutput>;

package/wasm/game_koi_web.js

@@ -0,0 +1,341 @@
+/* @ts-self-types="./game_koi_web.d.ts" */
+
+/**
+ * A running Game Boy, owned by JavaScript.
+ */
+export class Emulator {
+    __destroy_into_raw() {
+        const ptr = this.__wbg_ptr;
+        this.__wbg_ptr = 0;
+        EmulatorFinalization.unregister(this);
+        return ptr;
+    }
+    free() {
+        const ptr = this.__destroy_into_raw();
+        wasm.__wbg_emulator_free(ptr, 0);
+    }
+    /**
+     * @returns {number}
+     */
+    frame_len() {
+        const ret = wasm.emulator_frame_len(this.__wbg_ptr);
+        return ret >>> 0;
+    }
+    /**
+     * Pointer to the RGBA framebuffer inside wasm memory.
+     *
+     * Paired with [`Emulator::frame_len`], this lets the page build a view over wasm
+     * memory once and reuse it. Any call that grows wasm memory can detach that view,
+     * so re-read both after loading a new ROM.
+     * @returns {number}
+     */
+    frame_ptr() {
+        const ret = wasm.emulator_frame_ptr(this.__wbg_ptr);
+        return ret >>> 0;
+    }
+    /**
+     * @returns {number}
+     */
+    static height() {
+        const ret = wasm.emulator_height();
+        return ret >>> 0;
+    }
+    /**
+     * Builds a machine from a ROM image.
+     *
+     * Fails if the header will not parse or the cartridge uses a mapper the core does
+     * not implement — the same typed failure the desktop build gets, flattened to a
+     * string because that is what crosses into JavaScript.
+     * @param {Uint8Array} rom
+     * @param {number} sample_rate
+     */
+    constructor(rom, sample_rate) {
+        const ptr0 = passArray8ToWasm0(rom, wasm.__wbindgen_malloc);
+        const len0 = WASM_VECTOR_LEN;
+        const ret = wasm.emulator_new(ptr0, len0, sample_rate);
+        if (ret[2]) {
+            throw takeFromExternrefTable0(ret[1]);
+        }
+        this.__wbg_ptr = ret[0];
+        EmulatorFinalization.register(this, this.__wbg_ptr, this);
+        return this;
+    }
+    /**
+     * Presses a button, named as the page sees it ("a", "start", "dpad-up", ...).
+     *
+     * Unknown names are ignored rather than an error: a key the page does not map is
+     * not a failure worth unwinding across the boundary for.
+     * @param {string} button
+     */
+    press(button) {
+        const ptr0 = passStringToWasm0(button, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+        const len0 = WASM_VECTOR_LEN;
+        wasm.emulator_press(this.__wbg_ptr, ptr0, len0);
+    }
+    /**
+     * @param {string} button
+     */
+    release(button) {
+        const ptr0 = passStringToWasm0(button, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+        const len0 = WASM_VECTOR_LEN;
+        wasm.emulator_release(this.__wbg_ptr, ptr0, len0);
+    }
+    /**
+     * Runs until the PPU finishes a frame.
+     *
+     * The cycle budget is the same safety valve the desktop frontend uses: a ROM that
+     * somehow never completes a frame would otherwise wedge the browser tab.
+     */
+    run_frame() {
+        wasm.emulator_run_frame(this.__wbg_ptr);
+    }
+    /**
+     * Takes the audio produced since the last call, interleaved as L,R,L,R.
+     * @returns {Float32Array}
+     */
+    take_samples() {
+        const ret = wasm.emulator_take_samples(this.__wbg_ptr);
+        var v1 = getArrayF32FromWasm0(ret[0], ret[1]).slice();
+        wasm.__wbindgen_free(ret[0], ret[1] * 4, 4);
+        return v1;
+    }
+    /**
+     * @returns {number}
+     */
+    static width() {
+        const ret = wasm.emulator_width();
+        return ret >>> 0;
+    }
+}
+if (Symbol.dispose) Emulator.prototype[Symbol.dispose] = Emulator.prototype.free;
+function __wbg_get_imports() {
+    const import0 = {
+        __proto__: null,
+        __wbg_Error_67e7344beaa85059: function(arg0, arg1) {
+            const ret = Error(getStringFromWasm0(arg0, arg1));
+            return ret;
+        },
+        __wbg___wbindgen_throw_5d9e815e6fdf150f: function(arg0, arg1) {
+            throw new Error(getStringFromWasm0(arg0, arg1));
+        },
+        __wbindgen_init_externref_table: function() {
+            const table = wasm.__wbindgen_externrefs;
+            const offset = table.grow(4);
+            table.set(0, undefined);
+            table.set(offset + 0, undefined);
+            table.set(offset + 1, null);
+            table.set(offset + 2, true);
+            table.set(offset + 3, false);
+        },
+    };
+    return {
+        __proto__: null,
+        "./game_koi_web_bg.js": import0,
+    };
+}
+
+const EmulatorFinalization = (typeof FinalizationRegistry === 'undefined')
+    ? { register: () => {}, unregister: () => {} }
+    : new FinalizationRegistry(ptr => wasm.__wbg_emulator_free(ptr, 1));
+
+function getArrayF32FromWasm0(ptr, len) {
+    ptr = ptr >>> 0;
+    return getFloat32ArrayMemory0().subarray(ptr / 4, ptr / 4 + len);
+}
+
+let cachedFloat32ArrayMemory0 = null;
+function getFloat32ArrayMemory0() {
+    if (cachedFloat32ArrayMemory0 === null || cachedFloat32ArrayMemory0.byteLength === 0) {
+        cachedFloat32ArrayMemory0 = new Float32Array(wasm.memory.buffer);
+    }
+    return cachedFloat32ArrayMemory0;
+}
+
+function getStringFromWasm0(ptr, len) {
+    return decodeText(ptr >>> 0, len);
+}
+
+let cachedUint8ArrayMemory0 = null;
+function getUint8ArrayMemory0() {
+    if (cachedUint8ArrayMemory0 === null || cachedUint8ArrayMemory0.byteLength === 0) {
+        cachedUint8ArrayMemory0 = new Uint8Array(wasm.memory.buffer);
+    }
+    return cachedUint8ArrayMemory0;
+}
+
+function passArray8ToWasm0(arg, malloc) {
+    const ptr = malloc(arg.length * 1, 1) >>> 0;
+    getUint8ArrayMemory0().set(arg, ptr / 1);
+    WASM_VECTOR_LEN = arg.length;
+    return ptr;
+}
+
+function passStringToWasm0(arg, malloc, realloc) {
+    if (realloc === undefined) {
+        const buf = cachedTextEncoder.encode(arg);
+        const ptr = malloc(buf.length, 1) >>> 0;
+        getUint8ArrayMemory0().subarray(ptr, ptr + buf.length).set(buf);
+        WASM_VECTOR_LEN = buf.length;
+        return ptr;
+    }
+
+    let len = arg.length;
+    let ptr = malloc(len, 1) >>> 0;
+
+    const mem = getUint8ArrayMemory0();
+
+    let offset = 0;
+
+    for (; offset < len; offset++) {
+        const code = arg.charCodeAt(offset);
+        if (code > 0x7F) break;
+        mem[ptr + offset] = code;
+    }
+    if (offset !== len) {
+        if (offset !== 0) {
+            arg = arg.slice(offset);
+        }
+        ptr = realloc(ptr, len, len = offset + arg.length * 3, 1) >>> 0;
+        const view = getUint8ArrayMemory0().subarray(ptr + offset, ptr + len);
+        const ret = cachedTextEncoder.encodeInto(arg, view);
+
+        offset += ret.written;
+        ptr = realloc(ptr, len, offset, 1) >>> 0;
+    }
+
+    WASM_VECTOR_LEN = offset;
+    return ptr;
+}
+
+function takeFromExternrefTable0(idx) {
+    const value = wasm.__wbindgen_externrefs.get(idx);
+    wasm.__externref_table_dealloc(idx);
+    return value;
+}
+
+let cachedTextDecoder = new TextDecoder('utf-8', { ignoreBOM: true, fatal: true });
+cachedTextDecoder.decode();
+const MAX_SAFARI_DECODE_BYTES = 2146435072;
+let numBytesDecoded = 0;
+function decodeText(ptr, len) {
+    numBytesDecoded += len;
+    if (numBytesDecoded >= MAX_SAFARI_DECODE_BYTES) {
+        cachedTextDecoder = new TextDecoder('utf-8', { ignoreBOM: true, fatal: true });
+        cachedTextDecoder.decode();
+        numBytesDecoded = len;
+    }
+    return cachedTextDecoder.decode(getUint8ArrayMemory0().subarray(ptr, ptr + len));
+}
+
+const cachedTextEncoder = new TextEncoder();
+
+if (!('encodeInto' in cachedTextEncoder)) {
+    cachedTextEncoder.encodeInto = function (arg, view) {
+        const buf = cachedTextEncoder.encode(arg);
+        view.set(buf);
+        return {
+            read: arg.length,
+            written: buf.length
+        };
+    };
+}
+
+let WASM_VECTOR_LEN = 0;
+
+let wasmModule, wasmInstance, wasm;
+function __wbg_finalize_init(instance, module) {
+    wasmInstance = instance;
+    wasm = instance.exports;
+    wasmModule = module;
+    cachedFloat32ArrayMemory0 = null;
+    cachedUint8ArrayMemory0 = null;
+    wasm.__wbindgen_start();
+    return wasm;
+}
+
+async function __wbg_load(module, imports) {
+    if (typeof Response === 'function' && module instanceof Response) {
+        if (!module.ok) {
+            throw new Error(`failed to fetch Wasm: ${module.status} ${module.statusText} fetching '${module.url}'`);
+        }
+
+        if (typeof WebAssembly.instantiateStreaming === 'function') {
+            try {
+                return await WebAssembly.instantiateStreaming(module, imports);
+            } catch (e) {
+                const validResponse = expectedResponseType(module.type);
+
+                if (validResponse && module.headers.get('Content-Type') !== 'application/wasm') {
+                    console.warn("`WebAssembly.instantiateStreaming` failed because your server does not serve Wasm with `application/wasm` MIME type. Falling back to `WebAssembly.instantiate` which is slower. Original error:\n", e);
+
+                } else { throw e; }
+            }
+        }
+
+        const bytes = await module.arrayBuffer();
+        return await WebAssembly.instantiate(bytes, imports);
+    } else {
+        const instance = await WebAssembly.instantiate(module, imports);
+
+        if (instance instanceof WebAssembly.Instance) {
+            return { instance, module };
+        } else {
+            return instance;
+        }
+    }
+
+    function expectedResponseType(type) {
+        switch (type) {
+            case 'basic': case 'cors': case 'default': return true;
+        }
+        return false;
+    }
+}
+
+function initSync(module) {
+    if (wasm !== undefined) return wasm;
+
+
+    if (module !== undefined) {
+        if (Object.getPrototypeOf(module) === Object.prototype) {
+            ({module} = module)
+        } else {
+            console.warn('using deprecated parameters for `initSync()`; pass a single object instead')
+        }
+    }
+
+    const imports = __wbg_get_imports();
+    if (!(module instanceof WebAssembly.Module)) {
+        module = new WebAssembly.Module(module);
+    }
+    const instance = new WebAssembly.Instance(module, imports);
+    return __wbg_finalize_init(instance, module);
+}
+
+async function __wbg_init(module_or_path) {
+    if (wasm !== undefined) return wasm;
+
+
+    if (module_or_path !== undefined) {
+        if (Object.getPrototypeOf(module_or_path) === Object.prototype) {
+            ({module_or_path} = module_or_path)
+        } else {
+            console.warn('using deprecated parameters for the initialization function; pass a single object instead')
+        }
+    }
+
+    if (module_or_path === undefined) {
+        module_or_path = new URL('game_koi_web_bg.wasm', import.meta.url);
+    }
+    const imports = __wbg_get_imports();
+
+    if (typeof module_or_path === 'string' || (typeof Request === 'function' && module_or_path instanceof Request) || (typeof URL === 'function' && module_or_path instanceof URL)) {
+        module_or_path = fetch(module_or_path);
+    }
+
+    const { instance, module } = await __wbg_load(await module_or_path, imports);
+
+    return __wbg_finalize_init(instance, module);
+}
+
+export { initSync, __wbg_init as default };

package/wasm/game_koi_web_bg.wasm.d.ts

@@ -0,0 +1,19 @@
+/* tslint:disable */
+/* eslint-disable */
+export const memory: WebAssembly.Memory;
+export const __wbg_emulator_free: (a: number, b: number) => void;
+export const emulator_frame_len: (a: number) => number;
+export const emulator_frame_ptr: (a: number) => number;
+export const emulator_height: () => number;
+export const emulator_new: (a: number, b: number, c: number) => [number, number, number];
+export const emulator_press: (a: number, b: number, c: number) => void;
+export const emulator_release: (a: number, b: number, c: number) => void;
+export const emulator_run_frame: (a: number) => void;
+export const emulator_take_samples: (a: number) => [number, number];
+export const emulator_width: () => number;
+export const __wbindgen_externrefs: WebAssembly.Table;
+export const __wbindgen_malloc: (a: number, b: number) => number;
+export const __externref_table_dealloc: (a: number) => void;
+export const __wbindgen_realloc: (a: number, b: number, c: number, d: number) => number;
+export const __wbindgen_free: (a: number, b: number, c: number) => void;
+export const __wbindgen_start: () => void;