nescript/tests/emulator/harness.html

<!doctype html>
<html>
<head>
<meta charset="utf-8" />
<title>NEScript jsnes harness</title>
<style>
  body { margin: 0; background: #222; color: #eee; font-family: monospace; }
  canvas { image-rendering: pixelated; background: #000; display: block; }
  #info { padding: 8px; }
</style>
</head>
<body>
<canvas id="screen" width="256" height="240"></canvas>
<div id="info">waiting…</div>
<script src="./node_modules/jsnes/dist/jsnes.js"></script>
<script>
(function () {
  const { NES } = window.jsnes;
  const canvas = document.getElementById("screen");
  const ctx = canvas.getContext("2d");
  const image = ctx.createImageData(256, 240);
  // Pre-fill alpha channel so we don't have to do it every frame.
  const buf = new ArrayBuffer(image.data.length);
  const buf8 = new Uint8ClampedArray(buf);
  const buf32 = new Uint32Array(buf);
  for (let i = 0; i < buf32.length; i++) buf32[i] = 0xff000000;

  // Audio recording buffers. `onAudioSample(l, r)` pushes one
  // sample per channel; we collect both into growable int16 arrays
  // so the runner can hash them for fast diffing or dump them as a
  // WAV file when a diff fails. Samples are quantized to int16 at
  // capture time — minor fp drift in jsnes shouldn't change the
  // hash, and WAV output expects int16 anyway. The capacity grows
  // exponentially to amortize reallocation; 3 seconds at 44.1 kHz
  // is ~132k samples per channel which comfortably fits in the
  // initial 64k allocation after one doubling.
  const SAMPLE_RATE = 44100;
  let audioLeft = new Int16Array(65536);
  let audioRight = new Int16Array(65536);
  let audioLen = 0;

  function pushAudio(l, r) {
    if (audioLen >= audioLeft.length) {
      const next = new Int16Array(audioLeft.length * 2);
      next.set(audioLeft);
      audioLeft = next;
      const next2 = new Int16Array(audioRight.length * 2);
      next2.set(audioRight);
      audioRight = next2;
    }
    // Clamp to [-1, 1] then scale to int16 range. jsnes nominally
    // produces samples in [-1, 1] but we clamp defensively in case
    // of numerical edge cases at high volumes.
    let ll = l;
    if (ll < -1) ll = -1;
    else if (ll > 1) ll = 1;
    let rr = r;
    if (rr < -1) rr = -1;
    else if (rr > 1) rr = 1;
    audioLeft[audioLen] = (ll * 32767) | 0;
    audioRight[audioLen] = (rr * 32767) | 0;
    audioLen++;
  }

  function resetAudio() {
    audioLen = 0;
  }

  const nes = new NES({
    onFrame(frameBuffer) {
      for (let i = 0; i < 256 * 240; i++) {
        // jsnes pixel is 0x00BBGGRR in little-endian = 0xFFBBGGRR when alpha set
        buf32[i] = 0xff000000 | frameBuffer[i];
      }
      image.data.set(buf8);
      ctx.putImageData(image, 0, 0);
    },
    onAudioSample(l, r) {
      pushAudio(l, r);
    },
    sampleRate: SAMPLE_RATE,
  });

  // Expose an API for puppeteer to drive.
  window.nesHarness = {
    loadRomBase64(b64) {
      // atob produces a binary string, which is exactly what jsnes wants.
      const bin = atob(b64);
      // Wipe any stale audio samples left over from a previous
      // ROM in the same page lifecycle (the runner reuses the
      // puppeteer Page across ROMs in some configurations).
      resetAudio();
      nes.loadROM(bin);
    },
    frame() {
      nes.frame();
    },
    runFrames(n) {
      for (let i = 0; i < n; i++) nes.frame();
    },
    buttonDown(player, button) {
      nes.buttonDown(player, button);
    },
    buttonUp(player, button) {
      nes.buttonUp(player, button);
    },
    // Return an FNV-1a hash (32-bit, hex) over the full captured
    // stereo int16 audio buffer. This is the golden-compare key
    // — tiny enough to commit per-ROM alongside the PNG hash, and
    // stable across runs because samples are pre-quantized to
    // int16 at capture. A silent ROM hashes to a single well-
    // known value; any audio-producing ROM gets a distinct hash
    // that will immediately flag driver regressions.
    audioHash() {
      let h = 2166136261 >>> 0; // FNV-1a offset basis
      for (let i = 0; i < audioLen; i++) {
        const l = audioLeft[i] & 0xffff;
        const r = audioRight[i] & 0xffff;
        h ^= l & 0xff;
        h = Math.imul(h, 16777619);
        h ^= (l >> 8) & 0xff;
        h = Math.imul(h, 16777619);
        h ^= r & 0xff;
        h = Math.imul(h, 16777619);
        h ^= (r >> 8) & 0xff;
        h = Math.imul(h, 16777619);
      }
      return { hash: (h >>> 0).toString(16), samples: audioLen };
    },
    // Return a base64-encoded WAV file (16-bit stereo PCM at
    // SAMPLE_RATE Hz) containing everything the harness has
    // captured since the last ROM load. The runner only pulls
    // this when it needs to write an `actual/<name>.wav` for a
    // failed diff — we keep the full samples in memory so no
    // re-emulation is needed.
    audioWavBase64() {
      const n = audioLen;
      const dataBytes = n * 4; // 2 channels * 2 bytes per sample
      const headerBytes = 44;
      const total = headerBytes + dataBytes;
      const wav = new Uint8Array(total);
      const dv = new DataView(wav.buffer);
      // RIFF header
      wav[0] = 0x52; // 'R'
      wav[1] = 0x49; // 'I'
      wav[2] = 0x46; // 'F'
      wav[3] = 0x46; // 'F'
      dv.setUint32(4, total - 8, true);
      wav[8] = 0x57; // 'W'
      wav[9] = 0x41; // 'A'
      wav[10] = 0x56; // 'V'
      wav[11] = 0x45; // 'E'
      // fmt chunk
      wav[12] = 0x66; // 'f'
      wav[13] = 0x6d; // 'm'
      wav[14] = 0x74; // 't'
      wav[15] = 0x20; // ' '
      dv.setUint32(16, 16, true); // fmt chunk size
      dv.setUint16(20, 1, true); // PCM
      dv.setUint16(22, 2, true); // stereo
      dv.setUint32(24, SAMPLE_RATE, true); // sample rate
      dv.setUint32(28, SAMPLE_RATE * 4, true); // byte rate
      dv.setUint16(32, 4, true); // block align
      dv.setUint16(34, 16, true); // bits per sample
      // data chunk
      wav[36] = 0x64; // 'd'
      wav[37] = 0x61; // 'a'
      wav[38] = 0x74; // 't'
      wav[39] = 0x61; // 'a'
      dv.setUint32(40, dataBytes, true);
      let off = 44;
      for (let i = 0; i < n; i++) {
        dv.setInt16(off, audioLeft[i], true);
        dv.setInt16(off + 2, audioRight[i], true);
        off += 4;
      }
      // Base64-encode in chunks to avoid stringify limits.
      const chunks = [];
      for (let i = 0; i < wav.length; i += 4096) {
        chunks.push(String.fromCharCode.apply(null, wav.subarray(i, i + 4096)));
      }
      return btoa(chunks.join(""));
    },
    // Return a hash and non-zero-pixel count for the current canvas contents.
    frameStats() {
      const data = ctx.getImageData(0, 0, 256, 240).data;
      let nonBlack = 0;
      let hash = 2166136261 >>> 0; // FNV-1a
      for (let i = 0; i < data.length; i += 4) {
        const r = data[i], g = data[i + 1], b = data[i + 2];
        if (r !== 0 || g !== 0 || b !== 0) nonBlack++;
        hash ^= r; hash = Math.imul(hash, 16777619);
        hash ^= g; hash = Math.imul(hash, 16777619);
        hash ^= b; hash = Math.imul(hash, 16777619);
      }
      return { nonBlack, hash: (hash >>> 0).toString(16), totalPixels: 256 * 240 };
    },
    // Raw canvas pixels as a base64-encoded RGBA buffer
    // (256 * 240 * 4 bytes). Used by the golden-diff runner to
    // compare pixel-for-pixel against a decoded PNG golden file.
    // Base64 is cheap and avoids any puppeteer JSON-serialization
    // pitfalls with typed arrays.
    rawPixelsBase64() {
      const data = ctx.getImageData(0, 0, 256, 240).data;
      const chunks = [];
      // Chunk to stay under String.fromCharCode's argument limit.
      for (let i = 0; i < data.length; i += 4096) {
        chunks.push(String.fromCharCode.apply(null, data.subarray(i, i + 4096)));
      }
      return btoa(chunks.join(""));
    },
  };

  // Controller button enum constants (from jsnes Controller).
  window.nesButtons = {
    A: 0, B: 1, SELECT: 2, START: 3,
    UP: 4, DOWN: 5, LEFT: 6, RIGHT: 7,
  };

  document.getElementById("info").textContent = "ready";
})();
</script>
</body>
</html>