@wasm-gaming/rsdkv4-wasm 0.2.0 → 0.3.0

package/src/rsdkv4.options.ts

@@ -185,6 +185,11 @@ export interface Rsdkv4InputDefaults {
 /**
  * The engine's own default bindings. See {@link Rsdkv4InputDefaults}.
  *
+ * Directions are the arrow keys. This build's `ProcessInput()` also reads `KeyW`,
+ * `KeyA`, `KeyS` and `KeyD` as a second set of them, and takes those three scancodes
+ * off `x`, `y` and `z` to do it — so the table below is what a *claiming* host should
+ * bind, and the engine under SDL polling answers to both.
+ *
  * This replaces the old `RSDKV4_KEYMAP`, which nothing read and which was wrong in
  * three ways for want of ever being checked against the engine: it listed 9 of the
  * 14 buttons, and bound `select` to `ShiftLeft` where the engine's default is `Tab`.
@@ -344,12 +349,15 @@ export interface Rsdkv4Assets {
 export interface Rsdkv4Storage {
   /**
    * Per-game folder for the pack, the settings and the save file, so two games do not
-   * overwrite each other. Examples: `"sonic1"`, `"rsdkv4/Sonic2"`.
+   * overwrite each other. Examples: `"sonic-1"`, `"sonic-2/profile-a"`.
    *
-   * It is a path under the engine's working root *and* the OPFS directory the SDK
-   * mirrors save data into, which is what lets a host read `<namespace>/SData.bin`
-   * itself. Anything that is not a usable relative path normalises to `"default"` —
-   * including the object you get from interpolating a game record by mistake.
+   * Relative to the engine's own folder: the SDK always prefixes `rsdkv4/`, so the
+   * files land in `rsdkv4/<namespace>/` — in WASMFS (`/data/rsdkv4/<namespace>`) and in
+   * OPFS alike — and no namespace can reach another engine's files. A host reads the
+   * resolved path from `play.storagePath`. Segments are cleaned (`.`/`..` dropped,
+   * odd characters → `_`); anything unusable normalises to `"default"`, including the
+   * object you get from interpolating a game record by mistake. A leading `rsdkv4/`
+   * (the old convention) is stripped with a warning.
    *
    * @defaultValue `"default"`
    */
@@ -491,7 +499,7 @@ export const RSDKV4_SPEC: EngineSpec<Rsdkv4Payloads> = {
     namespace: {
       default: 'default',
       live: false,
-      description: "Folder for this game's pack, settings and save file.",
+      description: "Folder for this game's pack, settings and save file, inside the engine's own rsdkv4/ folder (OPFS rsdkv4/<namespace>/).",
     },
     persist: {
       enum: ['opfs', null],

package/src/rsdkv4.sdk.ts

@@ -7,7 +7,7 @@
  * const play = await new Rsdkv4SDK()
  *   .mount(document.querySelector('#stage'))
  *   .assets({ data: () => library.readBytes('Sonic2') })
- *   .storage({ namespace: 'rsdkv4/Sonic2' })
+ *   .storage({ namespace: 'sonic-2' })        // → OPFS rsdkv4/sonic-2/
  *   .config({ startMenu: 'host' })
  *   .on('saves', ({ detail }) => paintSlots(detail))
  *   .start({ slot: 0 });
@@ -85,6 +85,16 @@ export type Rsdkv4Events_ = EventsOf<Rsdkv4Payloads>;
 const WORK_ROOT = '/data';
 const DEFAULT_STORAGE_NAMESPACE = 'default';
 
+/**
+ * This engine's folder in WASMFS / OPFS. Every rsdkv4 file lives under it, whatever
+ * namespace a host picks, so two engines can never share a working dir — the host
+ * chooses the sub-folder, never the root. Same value as {@link Rsdkv4SDK.id}.
+ */
+const ENGINE_ID = 'rsdkv4';
+
+/** The files this engine keeps in its namespace — and the only ones it ever migrates. */
+const ENGINE_FILES = ['Data.rsdk', 'settings.ini', 'SData.bin'] as const;
+
 /** RSDKv4's save file, written next to the game data in the working dir. */
 const SAVE_FILE = 'SData.bin';
 
@@ -116,6 +126,7 @@ const ENGINE_BRIDGES = [
   'web_start_game',
   'web_audio_stop',
   'web_devmenu_get_stage_list',
+  'web_devmenu_open',
   'web_input_set_source',
 ] as const;
 
@@ -129,6 +140,34 @@ const INPUT_PULL_HOOK = '__rsdkv4_input_pull';
 /** How often a pull that keeps throwing is allowed to say so. See {@link Rsdkv4Play}. */
 const INPUT_ERROR_INTERVAL_MS = 1000;
 
+/**
+ * Keys whose browser default action is swallowed while the canvas has focus — the
+ * arrows and Space scroll the page under the game, Tab takes the focus off the canvas
+ * and with it every key the engine was reading.
+ *
+ * Both `KeyboardEvent.code` and `.key` spellings are in here because the set is
+ * matched against each: `code` is the physical key (layout-independent, which is what
+ * the engine binds), `key` is what it produced, and a browser or a remapping tool that
+ * reports only one of the two still lands.
+ *
+ * WASD is included because this build's `ProcessInput()` reads those scancodes as a
+ * second set of directions. They have no default action to prevent today, so this
+ * costs nothing and stops mattering the day the page grows a shortcut on one of them.
+ */
+const ENGINE_KEYS = new Set([
+  'ArrowUp',
+  'ArrowDown',
+  'ArrowLeft',
+  'ArrowRight',
+  'KeyW',
+  'KeyA',
+  'KeyS',
+  'KeyD',
+  'Space',
+  ' ',
+  'Tab',
+]);
+
 /** The Emscripten module. Untyped on purpose: it is generated glue, not our surface. */
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 type EmscriptenModule = any;
@@ -150,21 +189,37 @@ async function resolveAsset(asset: Rsdkv4Asset | undefined): Promise<Uint8Array
   return toUint8(typeof asset === 'function' ? await asset() : asset);
 }
 
-/** Normalize a host-provided storage namespace into a safe relative path. */
-function normalizeStorageNamespace(namespace: unknown): string {
-  if (typeof namespace !== 'string' || !namespace.trim()) return DEFAULT_STORAGE_NAMESPACE;
-
-  const cleaned = namespace
-    .split('/')
-    .map((segment) => segment.trim())
-    .filter(Boolean)
-    .map((segment) => segment.replace(/[^A-Za-z0-9._-]/g, '_'))
-    .filter(Boolean)
-    .join('/');
-
-  return cleaned || DEFAULT_STORAGE_NAMESPACE;
+/**
+ * Where an engine keeps one namespace: `<engineId>/<namespace>`, relative to the OPFS
+ * root (which is WASMFS `/data`). Written with nothing rsdkv4-specific in it, so it can
+ * move verbatim into engine-specs.
+ *
+ * The host's namespace is cleaned segment by segment: blanks dropped, `.` and `..`
+ * dropped (they used to survive, and `'../x'` walked out of the work root), anything
+ * outside `[A-Za-z0-9._-]` turned into `_`. Nothing usable left means `'default'`.
+ * A namespace that already starts with the engine id has it stripped once, so a host
+ * written against the old convention (`'rsdkv4/Sonic1'`) lands where it always did.
+ */
+export function storagePath(
+  engineId: string,
+  namespace: unknown,
+): { namespace: string; path: string; prefixed: boolean } {
+  const segments =
+    typeof namespace === 'string'
+      ? namespace
+          .split('/')
+          .map((segment) => segment.trim())
+          .filter((segment) => segment && segment !== '.' && segment !== '..')
+          .map((segment) => segment.replace(/[^A-Za-z0-9._-]/g, '_'))
+      : [];
+  const prefixed = segments.length > 1 && segments[0] === engineId;
+  if (prefixed) segments.shift();
+  const cleaned = segments.join('/') || DEFAULT_STORAGE_NAMESPACE;
+  return { namespace: cleaned, path: `${engineId}/${cleaned}`, prefixed };
 }
 
+let warnedPrefixed = false;
+
 /** The plain values behind a descriptor table — what the engine actually needs. */
 function valuesOf<T>(described: PropertiesDefinition<T>): T {
   const out: Record<string, unknown> = {};
@@ -289,18 +344,18 @@ function mountWorkingDir(
 }
 
 /**
- * OPFS handle for `<namespace>/`, reached with the plain (async) OPFS API from JS —
+ * OPFS handle for `<engineId>/<namespace>/` (a {@link storagePath}), reached with the plain (async) OPFS API from JS —
  * which, unlike the WASM side's sync access handles, works on the main thread of any
  * page. Returns null when OPFS isn't available at all.
  */
 async function opfsNamespaceDir(
-  namespace: string,
+  path: string,
   create: boolean,
 ): Promise<FileSystemDirectoryHandle | null> {
   if (typeof navigator === 'undefined' || !navigator.storage?.getDirectory) return null;
   try {
     let dir = await navigator.storage.getDirectory();
-    for (const segment of namespace.split('/').filter(Boolean)) {
+    for (const segment of path.split('/').filter(Boolean)) {
       dir = await dir.getDirectoryHandle(segment, { create });
     }
     return dir;
@@ -309,6 +364,42 @@ async function opfsNamespaceDir(
   }
 }
 
+/**
+ * Before the namespace lived under `rsdkv4/`, the default one was a top-level
+ * `default/` — a folder snes9x, mGBA and geolith also fall back to. Copy rsdkv4's own
+ * files out of it into `rsdkv4/default/` when the new folder lacks them. Copy, never
+ * move or delete: whatever else is in `default/` is not ours to touch.
+ */
+async function migrateLegacyDefault(): Promise<void> {
+  const legacy = await opfsNamespaceDir(DEFAULT_STORAGE_NAMESPACE, false);
+  if (!legacy) return;
+  let target: FileSystemDirectoryHandle | null = null;
+  for (const name of ENGINE_FILES) {
+    let source: File;
+    try {
+      source = await (await legacy.getFileHandle(name)).getFile();
+    } catch {
+      continue;
+    }
+    target ??= await opfsNamespaceDir(`${ENGINE_ID}/${DEFAULT_STORAGE_NAMESPACE}`, true);
+    if (!target) return;
+    try {
+      await target.getFileHandle(name);
+      continue; // already there: the new layout wins
+    } catch {
+      /* missing — copy it */
+    }
+    try {
+      const writable = await (await target.getFileHandle(name, { create: true })).createWritable();
+      await writable.write(await source.arrayBuffer());
+      await writable.close();
+      console.info(`[rsdkv4] copied ${DEFAULT_STORAGE_NAMESPACE}/${name} → ${ENGINE_ID}/${DEFAULT_STORAGE_NAMESPACE}/${name}`);
+    } catch (e) {
+      console.warn(`[rsdkv4] could not migrate ${DEFAULT_STORAGE_NAMESPACE}/${name}`, e);
+    }
+  }
+}
+
 /**
  * Wait for `Engine::Init`, which runs on the engine's first frame (main.cpp's
  * main_loop), not inside `callMain`. Gives up after ~4s rather than hanging the host:
@@ -331,11 +422,49 @@ function engineBridgeComplete(Module: EmscriptenModule): boolean {
 
 // ---------------------------------------------------------------- this engine's own surface
 
+/**
+ * A screen of RSDKv4's own in-canvas Dev Menu (Debug.cpp), as {@link
+ * RsdkDevMenuBridge.open} names them.
+ *
+ * `'categories'` is the engine's `SELECT A STAGE LIST` — PRESENTATION / REGULAR /
+ * SPECIAL / BONUS — and `'stages'` the scene list under one of them. Those two are the
+ * only native way to reach the BONUS list: the packs' own menu scenes (Sonic 1 and 2's
+ * `LEVEL SELECT` and `STAGE MENU`) can load a regular stage and nothing else.
+ */
+export type RsdkDevMenuScreen = 'main' | 'player' | 'categories' | 'stages';
+
+/**
+ * The order `web_devmenu_open`'s first argument counts in — the index into this array
+ * is what crosses to C++, so it has to stay in step with WebDevMenu.cpp (written by
+ * scripts/build.sh). Names on this side, a number on the wire.
+ */
+const DEV_MENU_SCREENS: readonly RsdkDevMenuScreen[] = ['main', 'player', 'categories', 'stages'];
+
 /** RSDKv4-specific bridge for a host's debug/stage-select UI. */
 export interface RsdkDevMenuBridge {
   getStageList(): Array<{ name: string; stages: Array<{ name: string }> }>;
   loadStage(categoryIdx: number, stageIdx: number): void;
   setPaused(paused: boolean): void;
+  /**
+   * Whether the loaded wasm carries {@link open}. False means an engine built before
+   * the bridge existed — a host should hide the button rather than offer a dead one.
+   */
+  readonly canOpen: boolean;
+  /**
+   * Open the engine's own Dev Menu at `screen`, with `category` selecting the stage
+   * list for `'categories'` (preselected) and `'stages'` (listed). Categories are the
+   * engine's own indices, the ones {@link getStageList} is ordered by — 2 is BONUS.
+   *
+   * This is what Escape does natively: the request is handed to the engine thread
+   * (`ENGINE_INITDEVMENU`) and the menu comes up on its next frame, so **the running
+   * stage is torn down** — `initDevMenu()` clears graphics and animation data. Save
+   * files are untouched; the current run is not.
+   *
+   * The menu is driven by the engine's own input and does not run while the SDK holds
+   * a pause, so resume before calling. Returns false when the engine cannot be reached
+   * or the wasm predates the bridge ({@link canOpen}).
+   */
+  open(screen?: RsdkDevMenuScreen, category?: number): boolean;
 }
 
 /**
@@ -403,6 +532,34 @@ export interface RsdkInputBridge {
   release(): PromisePlay<Rsdkv4Payloads>;
   /** Whether a claim is held. The `options()` descriptor deliberately will not say. */
   readonly claimed: boolean;
+  /**
+   * What the engine has held **right now**, as the bitmask a claim writes: bit 0 is
+   * `up`, bit 13 is `select`, in {@link RSDKV4_BUTTONS} order.
+   *
+   * This is the read-back to the claim's write, and it answers the one question no
+   * amount of listening on the page can: *did the button reach the engine?* A key
+   * that fires `keydown` in the browser and never lights a bit here died between SDL
+   * and `ProcessInput()`; one that lights the bit and changes nothing on screen was
+   * received and the game chose not to act on it. Those two are otherwise the same
+   * silence, and telling them apart is the difference between a real input bug and
+   * Sonic simply refusing to roll while a direction is held.
+   *
+   * Works whether or not a claim is held — under SDL polling it is the keyboard and
+   * the pad as the engine read them. `0` when the engine is not up.
+   *
+   * Two things it is not. It is `hold`, not `press`: a button reads the same on the
+   * frame it goes down and on the hundredth frame it stays down. And it is the
+   * engine's view *after* the B→A fold, so in-stage the jump key `x` lights `a` and
+   * `b` never lights at all — which is the fold working, not a lost button.
+   */
+  readonly mask: number;
+  /**
+   * {@link mask}, spelled as the fourteen named booleans — the same shape a claim
+   * hands over, so a host can diff what it sent against what arrived.
+   *
+   * A fresh object on every read; it is a snapshot, not a live view.
+   */
+  readonly held: Rsdkv4Buttons;
 }
 
 /**
@@ -446,7 +603,8 @@ export class Rsdkv4Play extends EnginePlayBase<Rsdkv4Payloads> {
 
   #persistent = false;
   #namespace = DEFAULT_STORAGE_NAMESPACE;
-  #workDir = `${WORK_ROOT}/${DEFAULT_STORAGE_NAMESPACE}`;
+  #storagePath = `${ENGINE_ID}/${DEFAULT_STORAGE_NAMESPACE}`;
+  #workDir = `${WORK_ROOT}/${ENGINE_ID}/${DEFAULT_STORAGE_NAMESPACE}`;
   #mirrorSaves = true;
   #saveTimer: ReturnType<typeof setInterval> | null = null;
   /** Last bytes mirrored out, so the `saves` event means "changed" and not "checked". */
@@ -602,6 +760,7 @@ export class Rsdkv4Play extends EnginePlayBase<Rsdkv4Payloads> {
 
     canvas.addEventListener('contextmenu', this.#swallowContextMenu);
     canvas.addEventListener('pointerdown', this.#onPointerDown);
+    canvas.addEventListener('keydown', this.#onKeyDown);
     window.addEventListener('resize', this.#onResize);
     // Fullscreen transitions need a refit too.
     document.addEventListener('fullscreenchange', this.#onFullscreenChange);
@@ -754,6 +913,15 @@ export class Rsdkv4Play extends EnginePlayBase<Rsdkv4Payloads> {
     return this.#namespace;
   }
 
+  /**
+   * Where this session's files live, relative to the OPFS root: `rsdkv4/<namespace>`.
+   * The path a host walks with `navigator.storage.getDirectory()` to stage a
+   * `Data.rsdk` before booting, or to read `SData.bin` after.
+   */
+  get storagePath(): string {
+    return this.#storagePath;
+  }
+
   /**
    * Input ownership, named. `play.input.claim(buttons)` and `play.input.release()`
    * are exactly `options({ buttons })` and `options({ buttons: null })` — same state,
@@ -769,9 +937,34 @@ export class Rsdkv4Play extends EnginePlayBase<Rsdkv4Payloads> {
       get claimed(): boolean {
         return play.#buttons !== null;
       },
+      get mask(): number {
+        return play.#engineMask();
+      },
+      get held(): Rsdkv4Buttons {
+        const mask = play.#engineMask();
+        const held = {} as Rsdkv4Buttons;
+        for (let bit = 0; bit < RSDKV4_BUTTONS.length; bit++) {
+          held[RSDKV4_BUTTONS[bit]] = (mask & (1 << bit)) !== 0;
+        }
+        return held;
+      },
     };
   }
 
+  /**
+   * The engine's own `web_input_get_mask()`, or 0 when there is no engine to ask.
+   *
+   * Deliberately quiet about a module that does not have the bridge: unlike a claim,
+   * which silently does nothing and deserves the console error `#applyButtons` gives
+   * it, this is a read — a host polling it once a frame for an overlay would turn one
+   * old artifact into sixty messages a second.
+   */
+  #engineMask(): number {
+    const Module = this.#module;
+    if (!Module || typeof Module.web_input_get_mask !== 'function') return 0;
+    return Module.web_input_get_mask() | 0;
+  }
+
   // ---- Host-driven input ----
 
   /**
@@ -928,6 +1121,24 @@ export class Rsdkv4Play extends EnginePlayBase<Rsdkv4Payloads> {
         if (paused) this.pause('host');
         else this.resume(this.#pauseOwner ?? 'host');
       },
+      canOpen: typeof Module.web_devmenu_open === 'function',
+      open: (screen = 'main', category = 0) => {
+        if (typeof Module.web_devmenu_open !== 'function') {
+          console.warn(
+            '[rsdkv4] this rsdkv4.wasm has no web_devmenu_open — rebuild it (`make build-wasm`), or read devMenu.canOpen before offering the button',
+          );
+          return false;
+        }
+        const index = DEV_MENU_SCREENS.indexOf(screen);
+        if (index < 0) {
+          console.warn(
+            `[rsdkv4] "${screen}" is not a dev menu screen — one of ${DEV_MENU_SCREENS.join(', ')}`,
+          );
+          return false;
+        }
+        Module.web_devmenu_open(index, category | 0);
+        return true;
+      },
     };
   }
 
@@ -973,8 +1184,17 @@ export class Rsdkv4Play extends EnginePlayBase<Rsdkv4Payloads> {
     // Mount the working dir first, so we can see what is already persisted (OPFS)
     // before deciding whether to pull assets.
     this.#persistent = mountWorkingDir(Module, storage.persist).persistent;
-    this.#namespace = normalizeStorageNamespace(storage.namespace);
-    this.#workDir = `${WORK_ROOT}/${this.#namespace}`;
+    const resolved = storagePath(ENGINE_ID, storage.namespace);
+    if (resolved.prefixed && !warnedPrefixed) {
+      warnedPrefixed = true;
+      console.warn(
+        `[rsdkv4] storage.namespace no longer needs the "${ENGINE_ID}/" prefix — the engine adds it. Pass "${resolved.namespace}".`,
+      );
+    }
+    this.#namespace = resolved.namespace;
+    this.#storagePath = resolved.path;
+    this.#workDir = `${WORK_ROOT}/${resolved.path}`;
+    if (resolved.namespace === DEFAULT_STORAGE_NAMESPACE) await migrateLegacyDefault();
     this.#mirrorSaves = storage.persist !== null;
     ensureDir(Module, this.#workDir);
 
@@ -999,8 +1219,24 @@ export class Rsdkv4Play extends EnginePlayBase<Rsdkv4Payloads> {
 
     // The engine writes SData.bin at its own pace (new game, checkpoint, options
     // change), so copy it out on a slow timer as well as on the way down.
+    //
+    // The timer alone loses saves, and by a wide margin: `destroy()` is the only
+    // other flush, and a browser tab that is closed or reloaded never calls it. A
+    // player who finished an act and hit reload inside the next ten seconds had the
+    // save written by the engine, held in the wasm heap, and dropped on the floor —
+    // which reads as "my progress did not stick" and looks exactly like a save
+    // system that does not work.
+    //
+    // `visibilitychange` → hidden is the flush that actually fires: it covers the
+    // tab being switched away from, the window being minimised, the phone going to
+    // the home screen, and — unlike `beforeunload`, which browsers increasingly
+    // ignore — navigating away and closing. `pagehide` backs it up for the bfcache
+    // path. Cheap to over-fire: the mirror compares bytes and returns without
+    // touching OPFS when nothing moved.
     if (this.#mirrorSaves) {
       this.#saveTimer = setInterval(() => void this.#mirrorSaveData(), 10_000);
+      document.addEventListener('visibilitychange', this.#onVisibilityChange);
+      window.addEventListener('pagehide', this.#onPageHide);
     }
 
     return Module;
@@ -1071,7 +1307,7 @@ export class Rsdkv4Play extends EnginePlayBase<Rsdkv4Payloads> {
       if (explicit) Module.FS.writeFile(dataPath, explicit);
       else {
         console.log(
-          `[rsdkv4] Data.rsdk already in persistent storage (${this.#namespace}) — skipping fetch`,
+          `[rsdkv4] Data.rsdk already in persistent storage (${this.#storagePath}) — skipping fetch`,
         );
       }
     } else {
@@ -1103,7 +1339,7 @@ export class Rsdkv4Play extends EnginePlayBase<Rsdkv4Payloads> {
    * it changes.
    */
   async #restoreSaveData(Module: EmscriptenModule): Promise<void> {
-    const dir = await opfsNamespaceDir(this.#namespace, false);
+    const dir = await opfsNamespaceDir(this.#storagePath, false);
     if (!dir) return;
     try {
       const file = await (await dir.getFileHandle(SAVE_FILE)).getFile();
@@ -1118,7 +1354,7 @@ export class Rsdkv4Play extends EnginePlayBase<Rsdkv4Payloads> {
   }
 
   /**
-   * Copy SData.bin out of the wasm into `<namespace>/`, and announce it if it moved.
+   * Copy SData.bin out of the wasm into `rsdkv4/<namespace>/`, and announce it if it moved.
    *
    * The division of labour the session settled on: the SDK owns getting the bytes out
    * of the wasm and into the namespace both sides already agree on; a host owns
@@ -1140,7 +1376,7 @@ export class Rsdkv4Play extends EnginePlayBase<Rsdkv4Payloads> {
     }
     if (sameBytes(bytes, this.#lastSave)) return;
 
-    const dir = await opfsNamespaceDir(this.#namespace, true);
+    const dir = await opfsNamespaceDir(this.#storagePath, true);
     if (dir) {
       try {
         const handle = await dir.getFileHandle(SAVE_FILE, { create: true });
@@ -1159,8 +1395,26 @@ export class Rsdkv4Play extends EnginePlayBase<Rsdkv4Payloads> {
 
   // ---- The render target ----
 
+  /**
+   * Flush the save when the page is being put away. See where these are registered
+   * for why the ten-second timer is not enough on its own.
+   */
+  #onVisibilityChange = (): void => {
+    if (document.visibilityState === 'hidden' && this.#mirrorSaves) void this.#mirrorSaveData();
+  };
+  #onPageHide = (): void => {
+    if (this.#mirrorSaves) void this.#mirrorSaveData();
+  };
+
   #swallowContextMenu = (event: Event): void => event.preventDefault();
   #onPointerDown = (): void => this.#focusCanvas();
+  #onKeyDown = (event: KeyboardEvent): void => {
+    // Only the browser's own default action is suppressed — the arrows and Space
+    // scroll the page, Tab walks the focus out of the canvas. The event is left to
+    // propagate: SDL's own handler sits on `window` in the bubble phase, so calling
+    // stopPropagation() here would be the engine's whole keyboard.
+    if (ENGINE_KEYS.has(event.code) || ENGINE_KEYS.has(event.key)) event.preventDefault();
+  };
   #onResize = (): void => this.#fitPicture();
   #onFullscreenChange = (): void => {
     this.#fitPicture();
@@ -1214,9 +1468,12 @@ export class Rsdkv4Play extends EnginePlayBase<Rsdkv4Payloads> {
     if (canvas) {
       canvas.removeEventListener('contextmenu', this.#swallowContextMenu);
       canvas.removeEventListener('pointerdown', this.#onPointerDown);
+      canvas.removeEventListener('keydown', this.#onKeyDown);
       if (this.#ownsCanvas) canvas.remove();
     }
     document.removeEventListener('fullscreenchange', this.#onFullscreenChange);
+    document.removeEventListener('visibilitychange', this.#onVisibilityChange);
+    window.removeEventListener('pagehide', this.#onPageHide);
     window.removeEventListener('resize', this.#onResize);
     this.#boxObserver?.disconnect();
     this.#boxObserver = null;
@@ -1256,9 +1513,9 @@ export class Rsdkv4Play extends EnginePlayBase<Rsdkv4Payloads> {
  * Everything on it is the contract's — see the module doc for the shape of a call.
  */
 export class Rsdkv4SDK extends EngineSDKBase<Rsdkv4Payloads> {
-  static readonly id = 'rsdkv4';
+  static readonly id = ENGINE_ID;
   /** Kept in step with package.json by `node scripts/sync-version.mjs`. */
-  static readonly version = '0.2.0';
+  static readonly version = '0.3.0';
   static readonly name = 'Retro Software Development Kit v4';
   static readonly description =
     'RSDKv4 compiled to WebAssembly via Emscripten. One game-agnostic WASM binary runs both Sonic 1 and Sonic 2 — the difference is only which Data.rsdk the host supplies at runtime. Ships none of the game: the player provides their own Data.rsdk, and it never leaves their browser.';