game-koi 0.5.0 → 0.7.0

package/README.md

@@ -77,6 +77,32 @@ Two cases release without anyone letting go: `loadRom()` releases everything (as
 the gamepad was holding (as `"gamepad"`), since polling stops and nothing else would.
 Keys keep their own `keyup` while paused. `dispose()` drops every listener.
 
+### Saves
+
+Games that save — the ones whose cartridge has a battery — keep their saves in
+`localStorage` automatically, so a reload or a later visit picks up where the player
+left off. Nothing needs configuring. The save is written about every two seconds while
+the game has unsaved changes, and again on `pause()`, `loadRom()`, `dispose()`, and when
+the tab is hidden or closed. Each write, and each save restored when a ROM loads, is
+logged with `console.info`, so the browser console shows when a game saved and under
+which key.
+
+A few things worth knowing:
+
+- **Only battery-backed cartridges are saved**, as on hardware: RAM on a board without
+  a battery is gone when the power is. Check with `koi.exportSave() !== null`.
+- Saves are keyed by the ROM's header title plus a CRC32 of the whole ROM, so two
+  ROMs sharing a title (a hack and its original, say) do not share a save.
+- `localStorage` is per origin and holds roughly 5 MiB. The largest Game Boy save is
+  128 KiB (about 171 KiB stored), so that is plenty for a handful of games but not an
+  unlimited library. A write that hits the quota is logged and retried later, not lost.
+- `koi.exportSave()` / `koi.importSave(bytes)` read and replace the raw save RAM — the
+  same `.sav` format the desktop build and most other emulators use — for download or
+  upload buttons. A game only re-reads its save at its own pace, usually on the title
+  screen, so call `loadRom()` after an import if you want it picked up at once.
+- Pass `saves: false` to `create()` to leave `localStorage` alone and handle saves
+  entirely through `exportSave`/`importSave` — for IndexedDB, or a server.
+
 ### Debug overlay
 
 Press <kbd>`</kbd> (backtick) to toggle a stats panel over the canvas, or call
@@ -114,13 +140,21 @@ element. Pass `overlayKey: null` to bind 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`.
+  - `saves?: boolean` — keep battery-backed saves in `localStorage`. Default `true`.
 - `koi.loadRom(rom)` — swaps in a new ROM, keeping the same canvas and audio setup.
+- `koi.exportSave()` — the cartridge's save RAM as a `Uint8Array`, or `null` if it
+  has no battery-backed RAM.
+- `koi.importSave(bytes)` — replaces the save RAM (and stores it, if saving is on).
+  Returns `false` if the cartridge has none or `bytes` is shorter than it.
 - `koi.press(button)` / `koi.release(button)` — `Button` is one of `"up"`, `"down"`,
   `"left"`, `"right"`, `"a"`, `"b"`, `"start"`, `"select"`.
 - `koi.on(type, listener)` / `koi.off(type, listener)` — `"press"` and `"release"`
   button edges, from any input path. `on` returns a function that unsubscribes. The
   payload is `{ button, source: "keyboard" | "gamepad" | "api", pressed: Set<Button> }`.
 - `koi.pressed` — everything held right now, as a `Set<Button>` snapshot.
+- `koi.version` — the emulator's version, e.g. `"0.6.0"`. It is also logged once per
+  page (`console.info`) when the wasm module loads. It is read from the wasm binary
+  itself, so a stale cached `.wasm` shows up as a mismatch here.
 - `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

package/dist/index.d.ts

@@ -42,6 +42,13 @@ export interface GameKoiOptions {
      * freeze the page catching up. Default 4.
      */
     maxFramesPerWake?: number;
+    /**
+     * Keep battery-backed save RAM in `localStorage`, so a game's saves survive a
+     * reload. Default `true`. Cartridges without a battery are never saved, as on
+     * hardware. Pass `false` to manage saves yourself with {@link GameKoi.exportSave}
+     * and {@link GameKoi.importSave}.
+     */
+    saves?: boolean;
 }
 /** A running Game Boy, attached to a canvas and driving an AudioWorklet. */
 export declare class GameKoi {
@@ -70,6 +77,12 @@ export declare class GameKoi {
     private keydownListener?;
     private keyupListener?;
     private overlayListener?;
+    /** Where saves go, or `null` if saving is off or storage is unavailable. */
+    private readonly saves;
+    /** The current ROM's storage key. */
+    private saveKey;
+    private framesSinceAutosave;
+    private flushListener?;
     private constructor();
     /**
      * Builds and starts a running emulator.
@@ -80,8 +93,26 @@ export declare class GameKoi {
     static create(options: GameKoiOptions): Promise<GameKoi>;
     /** Swaps in a new ROM, keeping the same canvas and audio graph. */
     loadRom(rom: Uint8Array): void;
+    /**
+     * The cartridge's save RAM, or `null` if it has no battery-backed RAM.
+     *
+     * The same raw bytes the desktop build writes to its `.sav` file, so either can be
+     * handed to the other — and to most other emulators, which use the same format.
+     */
+    exportSave(): Uint8Array | null;
+    /**
+     * Replaces the cartridge's save RAM, and stores it if saving is on.
+     *
+     * Returns `false` if the cartridge has no battery-backed RAM or the data is shorter
+     * than its RAM (more likely another game's save than a truncated one of this game's).
+     * The running game will not notice until it next reads its save — for most games,
+     * that means going back to the title screen or calling {@link loadRom} again.
+     */
+    importSave(data: Uint8Array): boolean;
     press(button: Button): void;
     release(button: Button): void;
+    /** The version of the emulator core running — the same number logged at startup. */
+    get version(): string;
     /** Everything the joypad has down right now — a snapshot, safe to keep. */
     get pressed(): ReadonlySet<Button>;
     /**
@@ -143,6 +174,26 @@ export declare class GameKoi {
      */
     private pollGamepads;
     private applyGamepadActions;
+    /** Loads the stored save for `rom` into the machine just built for it. */
+    private restoreSave;
+    /**
+     * Writes the save if the game has touched its RAM since the last write.
+     *
+     * The dirty flag is cleared only after the write succeeds, so a full quota or
+     * blocked storage leaves the save pending for the next attempt rather than
+     * silently dropped.
+     */
+    private flushSave;
+    /**
+     * Flushes when the page goes away.
+     *
+     * `pagehide` and a hidden `visibilitychange` rather than `beforeunload`, which
+     * mobile browsers skip when they kill a backgrounded tab. Hidden is the last moment
+     * a page is reliably given, and `localStorage` being synchronous is what makes
+     * writing in it safe — an async store could be cut off mid-write.
+     */
+    private attachSaveFlush;
+    private detachSaveFlush;
     private attachKeyboard;
     private detachKeyboard;
     /**

package/dist/index.js

@@ -7,12 +7,19 @@
  * 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 init, { Emulator, version as wasmVersion } from "../wasm/game_koi_web.js";
 import { WORKLET_SOURCE } from "./worklet.js";
 import { DEFAULT_GAMEPAD_MAP, GamepadInput } from "./gamepad.js";
 import { Emitter } from "./events.js";
 import { FrameStats } from "./stats.js";
 import { StatsOverlay } from "./overlay.js";
+import { LocalStorageSaves, defaultStorage, saveKey } from "./saves.js";
+/**
+ * How often the loop checks for unsaved RAM, in emulated frames — about two seconds,
+ * the desktop's interval. Most checks find nothing: a game only writes save RAM when
+ * it saves.
+ */
+const AUTOSAVE_FRAMES = 120;
 const DEFAULT_KEYMAP = {
     ArrowRight: "right",
     ArrowLeft: "left",
@@ -24,11 +31,16 @@ const DEFAULT_KEYMAP = {
     ShiftRight: "select",
 };
 // The wasm module only needs instantiating once per page, no matter how many
-// `GameKoi` instances are created.
+// `GameKoi` instances are created. The version line is logged here for the same
+// reason: once per page, not once per instance or per `loadRom`.
 let wasmReady = null;
 function ensureWasm() {
-    if (!wasmReady)
-        wasmReady = init();
+    if (!wasmReady) {
+        wasmReady = init().then((wasm) => {
+            console.info(`game-koi ${wasmVersion()}`);
+            return wasm;
+        });
+    }
     return wasmReady;
 }
 /** A running Game Boy, attached to a canvas and driving an AudioWorklet. */
@@ -58,7 +70,13 @@ export class GameKoi {
     keydownListener;
     keyupListener;
     overlayListener;
-    constructor(emulator, wasmMemory, ctx, audioContext, worklet, keymap, gamepadMap, overlayKey, targetBuffer, maxFramesPerWake) {
+    /** Where saves go, or `null` if saving is off or storage is unavailable. */
+    saves;
+    /** The current ROM's storage key. */
+    saveKey = "";
+    framesSinceAutosave = 0;
+    flushListener;
+    constructor(emulator, wasmMemory, ctx, audioContext, worklet, keymap, gamepadMap, overlayKey, targetBuffer, maxFramesPerWake, saves) {
         this.emulator = emulator;
         this.wasmMemory = wasmMemory;
         this.ctx = ctx;
@@ -70,6 +88,7 @@ export class GameKoi {
         this.maxFramesPerWake = maxFramesPerWake;
         this.imageData = ctx.createImageData(Emulator.width(), Emulator.height());
         this.stats = new FrameStats(performance.now());
+        this.saves = saves;
         this.worklet.port.onmessage = (event) => {
             this.buffered = event.data.buffered;
             this.underruns = event.data.underruns;
@@ -79,6 +98,8 @@ export class GameKoi {
             this.attachKeyboard();
         if (overlayKey !== null)
             this.attachOverlayKey(overlayKey);
+        if (saves)
+            this.attachSaveFlush();
     }
     /**
      * Builds and starts a running emulator.
@@ -109,7 +130,9 @@ export class GameKoi {
         const emulator = new Emulator(options.rom, audioContext.sampleRate);
         const keymap = options.keymap === null ? null : options.keymap ?? DEFAULT_KEYMAP;
         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);
+        const storage = options.saves === false ? null : defaultStorage();
+        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, storage ? new LocalStorageSaves(storage) : null);
+        koi.restoreSave(options.rom);
         koi.running = true;
         koi.loop();
         return koi;
@@ -123,8 +146,40 @@ export class GameKoi {
         // machine, and a display would show it stuck down).
         this.gamepad?.releaseAll();
         this.releaseAll();
+        // Before the old machine is freed, or whatever it saved since the last autosave
+        // goes with it.
+        this.flushSave();
         this.emulator.free();
         this.emulator = new Emulator(rom, this.audioContext.sampleRate);
+        this.restoreSave(rom);
+    }
+    /**
+     * The cartridge's save RAM, or `null` if it has no battery-backed RAM.
+     *
+     * The same raw bytes the desktop build writes to its `.sav` file, so either can be
+     * handed to the other — and to most other emulators, which use the same format.
+     */
+    exportSave() {
+        return this.emulator.save_data() ?? null;
+    }
+    /**
+     * Replaces the cartridge's save RAM, and stores it if saving is on.
+     *
+     * Returns `false` if the cartridge has no battery-backed RAM or the data is shorter
+     * than its RAM (more likely another game's save than a truncated one of this game's).
+     * The running game will not notice until it next reads its save — for most games,
+     * that means going back to the title screen or calling {@link loadRom} again.
+     */
+    importSave(data) {
+        if (!this.emulator.load_save(data))
+            return false;
+        try {
+            this.saves?.store(this.saveKey, data);
+        }
+        catch (error) {
+            console.warn("game-koi: could not store imported save", error);
+        }
+        return true;
     }
     press(button) {
         this.setButton(button, true, "api");
@@ -132,6 +187,10 @@ export class GameKoi {
     release(button) {
         this.setButton(button, false, "api");
     }
+    /** The version of the emulator core running — the same number logged at startup. */
+    get version() {
+        return wasmVersion();
+    }
     /** Everything the joypad has down right now — a snapshot, safe to keep. */
     get pressed() {
         return new Set(this.held);
@@ -202,6 +261,7 @@ export class GameKoi {
         return this.overlay?.visible ?? false;
     }
     pause() {
+        this.flushSave();
         this.running = false;
         cancelAnimationFrame(this.rafHandle);
         // A direction held at the moment of the pause has no poll coming to release it,
@@ -220,6 +280,8 @@ export class GameKoi {
     dispose() {
         this.running = false;
         cancelAnimationFrame(this.rafHandle);
+        this.flushSave();
+        this.detachSaveFlush();
         this.detachKeyboard();
         if (this.overlayListener)
             removeEventListener("keydown", this.overlayListener);
@@ -258,6 +320,11 @@ export class GameKoi {
             }
             frames++;
         }
+        this.framesSinceAutosave += frames;
+        if (this.framesSinceAutosave >= AUTOSAVE_FRAMES) {
+            this.framesSinceAutosave = 0;
+            this.flushSave();
+        }
         const drawStart = performance.now();
         if (frames > 0)
             this.drawFrame();
@@ -321,6 +388,71 @@ export class GameKoi {
             this.setButton(action.button, action.type === "press", "gamepad");
         }
     }
+    /** Loads the stored save for `rom` into the machine just built for it. */
+    restoreSave(rom) {
+        this.framesSinceAutosave = 0;
+        if (!this.saves)
+            return;
+        this.saveKey = saveKey(rom);
+        if (!this.emulator.has_save())
+            return;
+        const data = this.saves.load(this.saveKey);
+        // No stored save is the normal first run, and not worth a line.
+        if (!data)
+            return;
+        const where = `localStorage["${this.saveKey}"]`;
+        if (this.emulator.load_save(data)) {
+            console.info(`game-koi: restored ${data.length} bytes from ${where}`);
+        }
+        else {
+            console.warn(`game-koi: ignoring ${where}, it is smaller than this cartridge's RAM`);
+        }
+    }
+    /**
+     * Writes the save if the game has touched its RAM since the last write.
+     *
+     * The dirty flag is cleared only after the write succeeds, so a full quota or
+     * blocked storage leaves the save pending for the next attempt rather than
+     * silently dropped.
+     */
+    flushSave() {
+        if (!this.saves || !this.emulator.save_dirty())
+            return;
+        const data = this.emulator.save_data();
+        if (!data)
+            return;
+        try {
+            this.saves.store(this.saveKey, data);
+            this.emulator.mark_saved();
+            // Only reached when the game wrote its save RAM, so this is one line per in-game
+            // save (give or take the ~2 s autosave batching), not one per autosave tick.
+            console.info(`game-koi: saved ${data.length} bytes to localStorage["${this.saveKey}"]`);
+        }
+        catch (error) {
+            console.warn("game-koi: could not store save", error);
+        }
+    }
+    /**
+     * Flushes when the page goes away.
+     *
+     * `pagehide` and a hidden `visibilitychange` rather than `beforeunload`, which
+     * mobile browsers skip when they kill a backgrounded tab. Hidden is the last moment
+     * a page is reliably given, and `localStorage` being synchronous is what makes
+     * writing in it safe — an async store could be cut off mid-write.
+     */
+    attachSaveFlush() {
+        // Unconditional, since a flush with nothing dirty is a no-op: becoming *visible*
+        // costs one check, and `pagehide` need not trust the visibility state to be set yet.
+        this.flushListener = () => this.flushSave();
+        addEventListener("pagehide", this.flushListener);
+        document.addEventListener("visibilitychange", this.flushListener);
+    }
+    detachSaveFlush() {
+        if (!this.flushListener)
+            return;
+        removeEventListener("pagehide", this.flushListener);
+        document.removeEventListener("visibilitychange", this.flushListener);
+    }
     attachKeyboard() {
         this.keydownListener = (event) => {
             const button = this.keymap?.[event.code];

package/dist/saves.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Battery-backed saves, kept in `localStorage`.
+ *
+ * The browser counterpart of the desktop's `save.rs`. The rule for *what* is saved
+ * lives on the Rust side (`Emulator::has_save`: a battery and RAM to keep powered);
+ * this module only decides where the bytes go and what they are called.
+ *
+ * # The key
+ *
+ * The desktop names a save after the ROM's filename, but a page hands over bytes, not
+ * a file. The header title is not enough on its own — plenty of cartridges share one,
+ * and a ROM hack keeps its original's — so the key is the title plus a CRC32 of the
+ * whole ROM, the same checksum No-Intro uses to identify dumps. The title is only
+ * there so a person reading their storage in devtools can tell what is what.
+ *
+ * # The encoding
+ *
+ * `localStorage` holds strings, so the RAM is stored as base64. The largest DMG save
+ * is 128 KiB (MBC5), about 171 KiB encoded, against a per-origin quota of roughly
+ * 5 MiB — ample for a handful of games, not for a library of the largest ones. A write
+ * that hits the quota throws; the caller leaves the save dirty and tries again later.
+ *
+ * Everything but {@link LocalStorageSaves} is pure, and that class takes its `Storage`
+ * as a parameter, so all of it is testable under Node without a DOM.
+ */
+/** CRC-32 (IEEE 802.3, as zlib and No-Intro use), over the whole input. */
+export declare function crc32(bytes: Uint8Array): number;
+/**
+ * The cartridge title from the header, 0x134–0x143.
+ *
+ * Read up to the first NUL, printable ASCII only. On later cartridges the last bytes of
+ * that range were repurposed (manufacturer code, CGB flag), which is why stray
+ * non-letters get dropped rather than trusted.
+ */
+export declare function romTitle(rom: Uint8Array): string;
+/** The storage key a ROM's save lives under. */
+export declare function saveKey(rom: Uint8Array): string;
+export declare function encodeSave(bytes: Uint8Array): string;
+/** Decodes a stored save, or `null` if the string is not valid base64. */
+export declare function decodeSave(text: string): Uint8Array | null;
+/** Reads and writes saves in a `Storage` — `localStorage` in a page. */
+export declare class LocalStorageSaves {
+    private readonly storage;
+    constructor(storage: Storage);
+    load(key: string): Uint8Array | null;
+    /** Throws if the write fails — most often `QuotaExceededError`. */
+    store(key: string, bytes: Uint8Array): void;
+}
+/**
+ * `localStorage`, or `null` where touching it throws.
+ *
+ * It is not just absent in odd places: with storage blocked by the user, or in a
+ * sandboxed iframe, merely *reading the property* throws a `SecurityError`. A page
+ * that cannot save should still play.
+ */
+export declare function defaultStorage(): Storage | null;

package/dist/saves.js

@@ -0,0 +1,121 @@
+/**
+ * Battery-backed saves, kept in `localStorage`.
+ *
+ * The browser counterpart of the desktop's `save.rs`. The rule for *what* is saved
+ * lives on the Rust side (`Emulator::has_save`: a battery and RAM to keep powered);
+ * this module only decides where the bytes go and what they are called.
+ *
+ * # The key
+ *
+ * The desktop names a save after the ROM's filename, but a page hands over bytes, not
+ * a file. The header title is not enough on its own — plenty of cartridges share one,
+ * and a ROM hack keeps its original's — so the key is the title plus a CRC32 of the
+ * whole ROM, the same checksum No-Intro uses to identify dumps. The title is only
+ * there so a person reading their storage in devtools can tell what is what.
+ *
+ * # The encoding
+ *
+ * `localStorage` holds strings, so the RAM is stored as base64. The largest DMG save
+ * is 128 KiB (MBC5), about 171 KiB encoded, against a per-origin quota of roughly
+ * 5 MiB — ample for a handful of games, not for a library of the largest ones. A write
+ * that hits the quota throws; the caller leaves the save dirty and tries again later.
+ *
+ * Everything but {@link LocalStorageSaves} is pure, and that class takes its `Storage`
+ * as a parameter, so all of it is testable under Node without a DOM.
+ */
+const KEY_PREFIX = "game-koi:save:";
+let crcTable = null;
+/** CRC-32 (IEEE 802.3, as zlib and No-Intro use), over the whole input. */
+export function crc32(bytes) {
+    if (!crcTable) {
+        crcTable = new Uint32Array(256);
+        for (let n = 0; n < 256; n++) {
+            let c = n;
+            for (let k = 0; k < 8; k++)
+                c = c & 1 ? 0xedb88320 ^ (c >>> 1) : c >>> 1;
+            crcTable[n] = c >>> 0;
+        }
+    }
+    let crc = 0xffffffff;
+    for (let i = 0; i < bytes.length; i++) {
+        crc = crcTable[(crc ^ bytes[i]) & 0xff] ^ (crc >>> 8);
+    }
+    return (crc ^ 0xffffffff) >>> 0;
+}
+/**
+ * The cartridge title from the header, 0x134–0x143.
+ *
+ * Read up to the first NUL, printable ASCII only. On later cartridges the last bytes of
+ * that range were repurposed (manufacturer code, CGB flag), which is why stray
+ * non-letters get dropped rather than trusted.
+ */
+export function romTitle(rom) {
+    let title = "";
+    for (let i = 0x134; i < 0x144 && i < rom.length; i++) {
+        const byte = rom[i];
+        if (byte === 0)
+            break;
+        if (byte >= 0x20 && byte < 0x7f)
+            title += String.fromCharCode(byte);
+    }
+    return title.trim();
+}
+/** The storage key a ROM's save lives under. */
+export function saveKey(rom) {
+    const crc = crc32(rom).toString(16).padStart(8, "0");
+    return `${KEY_PREFIX}${romTitle(rom) || "untitled"}:${crc}`;
+}
+export function encodeSave(bytes) {
+    // Chunked because `String.fromCharCode(...bytes)` on 128 KiB overflows the argument
+    // limit of some engines' call stacks.
+    let binary = "";
+    const chunk = 0x8000;
+    for (let i = 0; i < bytes.length; i += chunk) {
+        binary += String.fromCharCode(...bytes.subarray(i, i + chunk));
+    }
+    return btoa(binary);
+}
+/** Decodes a stored save, or `null` if the string is not valid base64. */
+export function decodeSave(text) {
+    let binary;
+    try {
+        binary = atob(text);
+    }
+    catch {
+        return null;
+    }
+    const bytes = new Uint8Array(binary.length);
+    for (let i = 0; i < binary.length; i++)
+        bytes[i] = binary.charCodeAt(i);
+    return bytes;
+}
+/** Reads and writes saves in a `Storage` — `localStorage` in a page. */
+export class LocalStorageSaves {
+    storage;
+    constructor(storage) {
+        this.storage = storage;
+    }
+    load(key) {
+        const text = this.storage.getItem(key);
+        return text === null ? null : decodeSave(text);
+    }
+    /** Throws if the write fails — most often `QuotaExceededError`. */
+    store(key, bytes) {
+        this.storage.setItem(key, encodeSave(bytes));
+    }
+}
+/**
+ * `localStorage`, or `null` where touching it throws.
+ *
+ * It is not just absent in odd places: with storage blocked by the user, or in a
+ * sandboxed iframe, merely *reading the property* throws a `SecurityError`. A page
+ * that cannot save should still play.
+ */
+export function defaultStorage() {
+    try {
+        return globalThis.localStorage ?? null;
+    }
+    catch {
+        return null;
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "game-koi",
-  "version": "0.5.0",
+  "version": "0.7.0",
   "description": "A Game Boy (DMG) emulator, compiled to WebAssembly, with a drop-in canvas + audio wrapper",
   "type": "module",
   "main": "dist/index.js",

package/wasm/game_koi_web.d.ts

@@ -16,7 +16,27 @@ export class Emulator {
      * so re-read both after loading a new ROM.
      */
     frame_ptr(): number;
+    /**
+     * Whether this cartridge has save RAM worth keeping.
+     *
+     * Same rule as the desktop's `save.rs`: a battery on the board *and* RAM to keep
+     * powered. RAM on a battery-less board is volatile on hardware too, so persisting
+     * it would invent a memory the cartridge never had. The mapper is asked rather
+     * than the header because MBC2's RAM is inside the mapper chip and its header
+     * declares none.
+     */
+    has_save(): boolean;
     static height(): number;
+    /**
+     * Restores save RAM from stored bytes. Returns whether it was applied.
+     *
+     * A save shorter than the chip is refused, as on the desktop: it is more likely a
+     * different game's than a truncated copy of this one's, and half-loading it would
+     * corrupt what the player has. A longer one is accepted, since some emulators
+     * append RTC state after the RAM.
+     */
+    load_save(data: Uint8Array): boolean;
+    mark_saved(): void;
     /**
      * Builds a machine from a ROM image.
      *
@@ -40,6 +60,21 @@ export class Emulator {
      * somehow never completes a frame would otherwise wedge the browser tab.
      */
     run_frame(): void;
+    /**
+     * A copy of the save RAM, or `undefined` if the cartridge has nothing to save.
+     *
+     * Deliberately does not clear the dirty flag: if the page's write fails (storage
+     * full, private browsing), the save must still count as unwritten. The page calls
+     * [`Emulator::mark_saved`] once the bytes are actually stored.
+     */
+    save_data(): Uint8Array | undefined;
+    /**
+     * Whether the game has written to save RAM since the last [`Emulator::mark_saved`].
+     *
+     * The page polls this rather than writing storage every frame: a game only
+     * touches save RAM when it saves, so almost every check is a cheap `false`.
+     */
+    save_dirty(): boolean;
     /**
      * Takes the audio produced since the last call, interleaved as L,R,L,R.
      */
@@ -47,6 +82,15 @@ export class Emulator {
     static width(): number;
 }
 
+/**
+ * The workspace version this module was built from.
+ *
+ * Read from Cargo at compile time rather than from `package.json`, so it names the
+ * binary actually loaded: a stale `.wasm` cached next to a newer JS wrapper reports
+ * its own, older, number instead of the wrapper's.
+ */
+export function version(): string;
+
 export type InitInput = RequestInfo | URL | Response | BufferSource | WebAssembly.Module;
 
 export interface InitOutput {
@@ -54,13 +98,19 @@ export interface InitOutput {
     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_has_save: (a: number) => number;
     readonly emulator_height: () => number;
+    readonly emulator_load_save: (a: number, b: number, c: number) => number;
+    readonly emulator_mark_saved: (a: number) => void;
     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_save_data: (a: number) => [number, number];
+    readonly emulator_save_dirty: (a: number) => number;
     readonly emulator_take_samples: (a: number) => [number, number];
     readonly emulator_width: () => number;
+    readonly version: () => [number, number];
     readonly __wbindgen_externrefs: WebAssembly.Table;
     readonly __wbindgen_malloc: (a: number, b: number) => number;
     readonly __externref_table_dealloc: (a: number) => void;

package/wasm/game_koi_web.js

@@ -33,6 +33,20 @@ export class Emulator {
         const ret = wasm.emulator_frame_ptr(this.__wbg_ptr);
         return ret >>> 0;
     }
+    /**
+     * Whether this cartridge has save RAM worth keeping.
+     *
+     * Same rule as the desktop's `save.rs`: a battery on the board *and* RAM to keep
+     * powered. RAM on a battery-less board is volatile on hardware too, so persisting
+     * it would invent a memory the cartridge never had. The mapper is asked rather
+     * than the header because MBC2's RAM is inside the mapper chip and its header
+     * declares none.
+     * @returns {boolean}
+     */
+    has_save() {
+        const ret = wasm.emulator_has_save(this.__wbg_ptr);
+        return ret !== 0;
+    }
     /**
      * @returns {number}
      */
@@ -40,6 +54,25 @@ export class Emulator {
         const ret = wasm.emulator_height();
         return ret >>> 0;
     }
+    /**
+     * Restores save RAM from stored bytes. Returns whether it was applied.
+     *
+     * A save shorter than the chip is refused, as on the desktop: it is more likely a
+     * different game's than a truncated copy of this one's, and half-loading it would
+     * corrupt what the player has. A longer one is accepted, since some emulators
+     * append RTC state after the RAM.
+     * @param {Uint8Array} data
+     * @returns {boolean}
+     */
+    load_save(data) {
+        const ptr0 = passArray8ToWasm0(data, wasm.__wbindgen_malloc);
+        const len0 = WASM_VECTOR_LEN;
+        const ret = wasm.emulator_load_save(this.__wbg_ptr, ptr0, len0);
+        return ret !== 0;
+    }
+    mark_saved() {
+        wasm.emulator_mark_saved(this.__wbg_ptr);
+    }
     /**
      * Builds a machine from a ROM image.
      *
@@ -89,6 +122,34 @@ export class Emulator {
     run_frame() {
         wasm.emulator_run_frame(this.__wbg_ptr);
     }
+    /**
+     * A copy of the save RAM, or `undefined` if the cartridge has nothing to save.
+     *
+     * Deliberately does not clear the dirty flag: if the page's write fails (storage
+     * full, private browsing), the save must still count as unwritten. The page calls
+     * [`Emulator::mark_saved`] once the bytes are actually stored.
+     * @returns {Uint8Array | undefined}
+     */
+    save_data() {
+        const ret = wasm.emulator_save_data(this.__wbg_ptr);
+        let v1;
+        if (ret[0] !== 0) {
+            v1 = getArrayU8FromWasm0(ret[0], ret[1]).slice();
+            wasm.__wbindgen_free(ret[0], ret[1] * 1, 1);
+        }
+        return v1;
+    }
+    /**
+     * Whether the game has written to save RAM since the last [`Emulator::mark_saved`].
+     *
+     * The page polls this rather than writing storage every frame: a game only
+     * touches save RAM when it saves, so almost every check is a cheap `false`.
+     * @returns {boolean}
+     */
+    save_dirty() {
+        const ret = wasm.emulator_save_dirty(this.__wbg_ptr);
+        return ret !== 0;
+    }
     /**
      * Takes the audio produced since the last call, interleaved as L,R,L,R.
      * @returns {Float32Array}
@@ -108,6 +169,27 @@ export class Emulator {
     }
 }
 if (Symbol.dispose) Emulator.prototype[Symbol.dispose] = Emulator.prototype.free;
+
+/**
+ * The workspace version this module was built from.
+ *
+ * Read from Cargo at compile time rather than from `package.json`, so it names the
+ * binary actually loaded: a stale `.wasm` cached next to a newer JS wrapper reports
+ * its own, older, number instead of the wrapper's.
+ * @returns {string}
+ */
+export function version() {
+    let deferred1_0;
+    let deferred1_1;
+    try {
+        const ret = wasm.version();
+        deferred1_0 = ret[0];
+        deferred1_1 = ret[1];
+        return getStringFromWasm0(ret[0], ret[1]);
+    } finally {
+        wasm.__wbindgen_free(deferred1_0, deferred1_1, 1);
+    }
+}
 function __wbg_get_imports() {
     const import0 = {
         __proto__: null,
@@ -143,6 +225,11 @@ function getArrayF32FromWasm0(ptr, len) {
     return getFloat32ArrayMemory0().subarray(ptr / 4, ptr / 4 + len);
 }
 
+function getArrayU8FromWasm0(ptr, len) {
+    ptr = ptr >>> 0;
+    return getUint8ArrayMemory0().subarray(ptr / 1, ptr / 1 + len);
+}
+
 let cachedFloat32ArrayMemory0 = null;
 function getFloat32ArrayMemory0() {
     if (cachedFloat32ArrayMemory0 === null || cachedFloat32ArrayMemory0.byteLength === 0) {

package/wasm/game_koi_web_bg.wasm.d.ts

@@ -4,13 +4,19 @@ 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_has_save: (a: number) => number;
 export const emulator_height: () => number;
+export const emulator_load_save: (a: number, b: number, c: number) => number;
+export const emulator_mark_saved: (a: number) => void;
 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_save_data: (a: number) => [number, number];
+export const emulator_save_dirty: (a: number) => number;
 export const emulator_take_samples: (a: number) => [number, number];
 export const emulator_width: () => number;
+export const version: () => [number, number];
 export const __wbindgen_externrefs: WebAssembly.Table;
 export const __wbindgen_malloc: (a: number, b: number) => number;
 export const __externref_table_dealloc: (a: number) => void;