Add types to the public API

Remove `@ts-nocheck` from the exported classes (NES, Controller, Browser,
GameGenie) and add real type annotations to the surface that consumers
see. The internal emulator modules (CPU, PPU, PAPU, mappers, browser
helpers) still have `@ts-nocheck` — references to them from the public
classes are typed as `any` so the implementation keeps working unchanged.

Public types exported from `src/index.ts`:
- `NESOptions`, `EmulatorData`, `ControllerId`, `RomData`
- `ButtonKey`, `ControllerState`
- `BrowserOptions`
- `GameGeniePatch`

The class fields, method parameters, and return types on the exported
classes themselves are also annotated so consumers get IntelliSense on
things like `nes.loadROM(...)`, `controller.buttonDown(...)`, etc.

All 577 tests still pass and the webpack build is unchanged.

Author: claude

src/browser/index.ts

@@ -1,19 +1,37 @@
-// @ts-nocheck
 import NES from "../nes.ts";
+import type { RomData } from "../nes.ts";
 import Screen from "./screen.ts";
 import Speakers from "./speakers.ts";
 import FrameTimer from "./frame-timer.ts";
 import KeyboardController from "./keyboard.ts";
 import GamepadController from "./gamepad.ts";
 
+export interface BrowserOptions {
+  /** The container element to render into. */
+  container: HTMLElement;
+  /** ROM data to load immediately. If omitted, call loadROM() then start(). */
+  romData?: RomData | null;
+  /** Called when the emulator encounters an error during frame execution. */
+  onError?: (error: unknown) => void;
+  /** Called when battery-backed SRAM is written. */
+  onBatteryRamWrite?: (address: number, value: number) => void;
+}
+
+// The browser helper classes (Screen, Speakers, FrameTimer, etc.) still
+// have @ts-nocheck for a loose conversion, so their public shapes are not
+// accurately typed. We use `any` for their field types here so consumers
+// of the Browser class still get precise types on the public API surface.
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+type Internal = any;
+
 // Debug logging, enabled via localStorage.jsnes_debug = 1
 let debugEnabled = false;
 try {
   debugEnabled = !!localStorage.getItem("jsnes_debug");
 } catch {
   // localStorage not available
 }
-function debug(...args) {
+function debug(...args: unknown[]): void {
   if (debugEnabled) console.log(...args);
 }
 
@@ -31,12 +49,23 @@ function debug(...args) {
  * If romData is omitted, call browser.loadROM(data) then browser.start().
  */
 export default class Browser {
-  constructor(options = {}) {
+  readonly nes: NES;
+  readonly keyboard: Internal;
+  readonly gamepad: Internal;
+
+  private _options: BrowserOptions;
+  private _screen: Internal;
+  private _speakers: Internal;
+  private _frameTimer: Internal;
+  private _gamepadPolling: Internal;
+  private _fpsInterval: ReturnType<typeof setInterval> | undefined;
+
+  constructor(options: BrowserOptions) {
     this._options = options;
 
     // Create screen (creates <canvas> inside container)
     this._screen = new Screen(options.container, {
-      onMouseDown: (x, y) => {
+      onMouseDown: (x: number, y: number) => {
         this.nes.zapperMove(x, y);
         this.nes.zapperFireDown();
       },
@@ -117,21 +146,24 @@ export default class Browser {
     }
   }
 
-  start() {
+  /** Start emulation. Called automatically if romData is provided to constructor. */
+  start(): void {
     this._frameTimer.start();
     this._speakers.start();
     this._fpsInterval = setInterval(() => {
       debug(`FPS: ${this.nes.getFPS()}`);
     }, 1000);
   }
 
-  stop() {
+  /** Pause emulation. */
+  stop(): void {
     this._frameTimer.stop();
     this._speakers.stop();
     clearInterval(this._fpsInterval);
   }
 
-  loadROM(data) {
+  /** Load a new ROM and start emulation. */
+  loadROM(data: RomData): void {
     this.stop();
     this.nes.loadROM(data);
     this.start();
@@ -140,18 +172,19 @@ export default class Browser {
   /**
    * Fill parent element with screen. Call if parent element changes size.
    */
-  fitInParent() {
+  fitInParent(): void {
     this._screen.fitInParent();
   }
 
-  screenshot() {
+  /** Get a screenshot as an HTMLImageElement. */
+  screenshot(): HTMLImageElement {
     return this._screen.screenshot();
   }
 
   /**
    * Clean up all resources: stop emulation, remove event listeners, remove canvas.
    */
-  destroy() {
+  destroy(): void {
     this.stop();
     document.removeEventListener("keydown", this.keyboard.handleKeyDown);
     document.removeEventListener("keyup", this.keyboard.handleKeyUp);
@@ -163,7 +196,10 @@ export default class Browser {
   /**
    * Load ROM data from a URL via XHR.
    */
-  static loadROMFromURL(url, callback) {
+  static loadROMFromURL(
+    url: string,
+    callback: (error: Error | null, data?: string) => void,
+  ): XMLHttpRequest {
     var req = new XMLHttpRequest();
     req.open("GET", url);
     req.overrideMimeType("text/plain; charset=x-user-defined");
@@ -175,7 +211,7 @@ export default class Browser {
       } else if (this.status === 0) {
         // Aborted, ignore
       } else {
-        req.onerror();
+        req.onerror!(new ProgressEvent("error"));
       }
     };
     req.send();

src/controller.ts

@@ -1,28 +1,45 @@
-// @ts-nocheck
 import { toJSON, fromJSON } from "./utils.ts";
 
+export type ButtonKey = 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9;
+
+export interface ControllerState {
+  state: number[];
+  baseA: number;
+  baseB: number;
+  turboA: boolean;
+  turboB: boolean;
+  turboToggle: boolean;
+}
+
 class Controller {
-  static BUTTON_A = 0;
-  static BUTTON_B = 1;
-  static BUTTON_SELECT = 2;
-  static BUTTON_START = 3;
-  static BUTTON_UP = 4;
-  static BUTTON_DOWN = 5;
-  static BUTTON_LEFT = 6;
-  static BUTTON_RIGHT = 7;
+  static readonly BUTTON_A = 0;
+  static readonly BUTTON_B = 1;
+  static readonly BUTTON_SELECT = 2;
+  static readonly BUTTON_START = 3;
+  static readonly BUTTON_UP = 4;
+  static readonly BUTTON_DOWN = 5;
+  static readonly BUTTON_LEFT = 6;
+  static readonly BUTTON_RIGHT = 7;
   // Turbo buttons rapidly toggle A/B each frame while held, simulating the
   // extra buttons on the NES Advantage and dogbone controllers.
-  static BUTTON_TURBO_A = 8;
-  static BUTTON_TURBO_B = 9;
+  static readonly BUTTON_TURBO_A = 8;
+  static readonly BUTTON_TURBO_B = 9;
 
-  static JSON_PROPERTIES = [
+  static readonly JSON_PROPERTIES = [
     "state",
     "baseA",
     "baseB",
     "turboA",
     "turboB",
     "turboToggle",
-  ];
+  ] as const;
+
+  state: number[];
+  baseA: number;
+  baseB: number;
+  turboA: boolean;
+  turboB: boolean;
+  turboToggle: boolean;
 
   constructor() {
     this.state = new Array(8);
@@ -38,7 +55,7 @@ class Controller {
     this.turboToggle = false;
   }
 
-  buttonDown(key) {
+  buttonDown(key: ButtonKey): void {
     if (key === Controller.BUTTON_TURBO_A) {
       this.turboA = true;
     } else if (key === Controller.BUTTON_TURBO_B) {
@@ -50,7 +67,7 @@ class Controller {
     }
   }
 
-  buttonUp(key) {
+  buttonUp(key: ButtonKey): void {
     if (key === Controller.BUTTON_TURBO_A) {
       this.turboA = false;
       this.state[Controller.BUTTON_A] = this.baseA;
@@ -67,7 +84,7 @@ class Controller {
   // Called once per frame to toggle turbo button states. Produces a ~30 Hz
   // press rate at 60 FPS, matching the fast end of the NES Advantage's
   // adjustable turbo range.
-  clock() {
+  clock(): void {
     if (!this.turboA && !this.turboB) return;
     this.turboToggle = !this.turboToggle;
     if (this.turboA) {
@@ -78,11 +95,11 @@ class Controller {
     }
   }
 
-  toJSON() {
-    return toJSON(this);
+  toJSON(): ControllerState {
+    return toJSON(this) as ControllerState;
   }
 
-  fromJSON(s) {
+  fromJSON(s: ControllerState): void {
     fromJSON(this, s);
   }
 }

src/gamegenie.ts

@@ -1,35 +1,45 @@
-// @ts-nocheck
 const LETTER_VALUES = "APZLGITYEOXUKSVN";
 
-function toDigit(letter) {
+function toDigit(letter: string): number {
   return LETTER_VALUES.indexOf(letter);
 }
 
-function toLetter(digit) {
+function toLetter(digit: number): string {
   return LETTER_VALUES[digit];
 }
 
-function toHex(n, width) {
+function toHex(n: number, width: number): string {
   const s = n.toString(16);
   return "0000".substring(0, width - s.length) + s;
 }
 
+export interface GameGeniePatch {
+  addr: number;
+  value: number;
+  wantskey?: boolean;
+  key?: number;
+}
+
 class GameGenie {
+  patches: GameGeniePatch[];
+  enabled: boolean;
+  // Callback invoked when patches or enabled state change, so the CPU
+  // can swap its loadFromCartridge function pointer. Set by NES after
+  // construction.
+  onChange: (() => void) | null;
+
   constructor() {
     this.patches = [];
     this.enabled = true;
-    // Callback invoked when patches or enabled state change, so the CPU
-    // can swap its loadFromCartridge function pointer. Set by NES after
-    // construction.
     this.onChange = null;
   }
 
-  setEnabled(enabled) {
+  setEnabled(enabled: boolean): void {
     this.enabled = enabled;
     if (this.onChange) this.onChange();
   }
 
-  addCode(code) {
+  addCode(code: string): void {
     const patch = this.decode(code);
     if (!patch) {
       throw new Error(`Invalid Game Genie code: ${code}`);
@@ -38,12 +48,12 @@ class GameGenie {
     if (this.onChange) this.onChange();
   }
 
-  addPatch(addr, value, key) {
+  addPatch(addr: number, value: number, key?: number): void {
     this.patches.push({ addr, value, key });
     if (this.onChange) this.onChange();
   }
 
-  removeAllCodes() {
+  removeAllCodes(): void {
     this.patches = [];
     if (this.onChange) this.onChange();
   }
@@ -52,7 +62,7 @@ class GameGenie {
   // Game Genie works by intercepting ROM reads and substituting values.
   // The address is masked to 15 bits because Game Genie ignores the
   // highest bit (ROM is mirrored in $8000-$FFFF).
-  applyCodes(addr, value) {
+  applyCodes(addr: number, value: number): number {
     if (!this.enabled) return value;
 
     for (let i = 0; i < this.patches.length; ++i) {
@@ -68,7 +78,7 @@ class GameGenie {
     return value;
   }
 
-  decode(code) {
+  decode(code: string): GameGeniePatch | null {
     if (code.includes(":")) return this.decodeHex(code);
 
     const digits = code.toUpperCase().split("").map(toDigit);
@@ -83,7 +93,7 @@ class GameGenie {
       ((digits[2] & 7) << 4) +
       (digits[3] & 8) +
       (digits[4] & 7);
-    let key;
+    let key: number | undefined;
 
     if (digits.length === 8) {
       value += digits[7] & 8;
@@ -101,7 +111,12 @@ class GameGenie {
     return { value, addr, wantskey, key };
   }
 
-  encodeHex(addr, value, key, wantskey) {
+  encodeHex(
+    addr: number,
+    value: number,
+    key?: number,
+    wantskey?: boolean,
+  ): string {
     let s = toHex(addr, 4) + ":" + toHex(value, 2);
 
     if (key !== undefined || wantskey) {
@@ -115,7 +130,7 @@ class GameGenie {
     return s;
   }
 
-  decodeHex(s) {
+  decodeHex(s: string): GameGeniePatch | null {
     const match = s.match(/([0-9a-fA-F]+):([0-9a-fA-F]+)(\?[0-9a-fA-F]*)?/);
     if (!match) return null;
 
@@ -130,8 +145,13 @@ class GameGenie {
     return { value, addr, wantskey, key };
   }
 
-  encode(addr, value, key, wantskey) {
-    const digits = Array(6);
+  encode(
+    addr: number,
+    value: number,
+    key?: number,
+    wantskey?: boolean,
+  ): string {
+    const digits: number[] = Array(6);
 
     digits[0] = (value & 7) + ((value >> 4) & 8);
     digits[1] = ((value >> 4) & 7) + ((addr >> 4) & 8);

src/index.ts

@@ -1,7 +1,11 @@
-// @ts-nocheck
 import Browser from "./browser/index.ts";
 import Controller from "./controller.ts";
 import GameGenie from "./gamegenie.ts";
 import NES from "./nes.ts";
 
 export { Browser, Controller, GameGenie, NES };
+
+export type { BrowserOptions } from "./browser/index.ts";
+export type { ButtonKey, ControllerState } from "./controller.ts";
+export type { GameGeniePatch } from "./gamegenie.ts";
+export type { ControllerId, EmulatorData, NESOptions, RomData } from "./nes.ts";