@fugloy/emu 0.0.0-stage → 0.3.0

package/src/devices/interrupt-latch.js

@@ -0,0 +1,76 @@
+/**
+ * The Model I Expansion Interface's interrupt latch at $37E0: one object, owned by the Model I's
+ * I/O decode (`IOSystem.latch`, null on the Model III and on a Model I built with
+ * `expansion: false`), that every interrupting device of the Expansion Interface raises its bit in.
+ *
+ * - Bit 7 is the real-time clock: the Expansion Interface's 40 Hz pulse (a "25-millisecond pulse
+ *   on the interrupt line", "this 40-times-per-second pulse": Kitsz, The Custom TRS-80 and Other
+ *   Mysteries, p. 136; MAME's trs80 driver, `IRQ_M1_RTC` 0x80 and its 40 Hz periodic interrupt).
+ *   TRS80System raises it on schedule (`raise(TIMER_BIT)`).
+ * - Bit 6 is the disk controller's INTRQ (MAME, `IRQ_M1_FDC` 0x40). The WD1771 (emu phase 6,
+ *   Task 3) drives it with `raise(DISK_BIT)` and `clear(DISK_BIT)` as its INTRQ rises and falls;
+ *   reading the controller's status at $37EC is what drops it.
+ *
+ * Any bit set holds the CPU's INT line low; the Z80 takes it in IM 1 (or IM 0 with $FF on the bus)
+ * at $0038 whenever its interrupts are enabled. There is no mask: every source interrupts.
+ *
+ * Reading $37E0 (and its mirrors $37E1-$37E3, as MAME maps them; the mirrors are unverified) returns
+ * the latch and clears the clock bit: "reading 37EC (disk controller status) followed by reading
+ * 37E0 (real-time clock) resets a flip-flop used to signal input from disk controller and real-time
+ * clock, respectively. This must be done each time or the interrupt will continue to be 'on'"
+ * (Kitsz, p. 137). The disk bit is left for the status read to clear. Bits 0-5 read 0
+ * (unverified; MAME and xtrs return only the sources).
+ *
+ * The Level II ROM never reads it: its interrupt vector at $4012 is `EI / RET`
+ * (MDL1LEV2.Z80, INITR at $06D2), and Level II BASIC runs with interrupts disabled (DI at $0000 and
+ * no EI outside that vector), so the clock bit simply stays set until a DOS or a program enables
+ * interrupts with a handler that reads $37E0.
+ */
+
+/** The real-time clock's bit. */
+export const TIMER_BIT = 0x80;
+/** The disk controller's INTRQ bit. */
+export const DISK_BIT = 0x40;
+
+export class InterruptLatch {
+  /** @type {number} The pending sources (TIMER_BIT, DISK_BIT). */
+  bits = 0;
+
+  /**
+   * Set source bits: the INT line goes (or stays) low.
+   * @param {number} mask
+   */
+  raise(mask) {
+    this.bits |= mask & 0xff;
+  }
+
+  /**
+   * Clear source bits.
+   * @param {number} mask
+   */
+  clear(mask) {
+    this.bits &= ~mask & 0xff;
+  }
+
+  /** True while any source holds the INT line. */
+  get pending() {
+    return this.bits !== 0;
+  }
+
+  /** A CPU read of $37E0: the latch, after which the clock bit is cleared. */
+  read() {
+    const value = this.bits;
+    this.bits &= ~TIMER_BIT;
+    return value;
+  }
+
+  /** The latch as a read would return it, clearing nothing (for the debugger and `m.mem.read`). */
+  peek() {
+    return this.bits;
+  }
+
+  /** Power-on: nothing pending. */
+  reset() {
+    this.bits = 0;
+  }
+}

package/src/devices/key-queue.js

@@ -0,0 +1,278 @@
+/**
+ * The spec §3 `m.keyboard`: a cycle-timed key queue over the KeyboardMatrix, and the feed buffer
+ * the ROM keyboard-scan hook (spec §6) reads.
+ *
+ * Matrix mode presses and releases matrix keys at T-state timestamps, as a typist would; any
+ * program sees them, the ROM and games that scan $3800 directly alike. Hook mode hands characters
+ * to the ROM's own scan entries ($002B, $0049) without touching the matrix, so it is fast and
+ * exact but reaches only code that calls the ROM. The Machine drains the queue at instruction
+ * boundaries and runs the hook there.
+ */
+import { CPU_CLOCK_HZ } from '../machine/trs80-system.js';
+
+/** Key names → the KeyboardMatrix's browser-key names. */
+const NAMES = {
+  ENTER: 'Enter',
+  CLEAR: 'Clear',
+  BREAK: 'Escape',
+  UP: 'ArrowUp',
+  DOWN: 'ArrowDown',
+  LEFT: 'ArrowLeft',
+  RIGHT: 'ArrowRight',
+  SHIFT: 'Shift',
+  SPACE: ' ',
+};
+
+/**
+ * The KeyboardMatrix key for a character or key name. The matrix maps browser keys, where an
+ * uppercase letter is physically shifted; on the Model III an unshifted letter key types the
+ * capital, so 'A' presses the bare A key and 'a' presses SHIFT+A.
+ * @param {string} key
+ * @returns {string}
+ */
+function matrixKey(key) {
+  if (Object.hasOwn(NAMES, key)) return NAMES[key];
+  if (key === '\n') return 'Enter';
+  if (/^[A-Z]$/.test(key)) return key.toLowerCase();
+  if (/^[a-z]$/.test(key)) return key.toUpperCase();
+  return key;
+}
+
+/**
+ * The byte the ROM's keyboard routine returns for a fed character: its ASCII code, with '\n'
+ * as ENTER ($0D).
+ * @param {string} ch
+ * @returns {number}
+ */
+function romCode(ch) {
+  if (ch === '\n') return 0x0d;
+  const code = ch.codePointAt(0) ?? 0;
+  if (ch.length !== 1 || code < 0x01 || code > 0x7f) throw new Error(`feed: ${JSON.stringify(ch)} is not a character the ROM keyboard routine returns (ASCII $01-$7F, or '\\n' for ENTER)`);
+  return code;
+}
+
+/** Sign, zero, the undocumented bits 5 and 3, and parity, as the Z80 sets them for a logical op on `v`. */
+function logicFlags(v) {
+  let parity = v;
+  parity ^= parity >> 4;
+  parity ^= parity >> 2;
+  parity ^= parity >> 1;
+  return (v & 0xa8) | (v === 0 ? 0x40 : 0) | ((parity & 1) === 0 ? 0x04 : 0);
+}
+
+/** F after `CP 01H` with A = `a` (the last flag-setting instruction of the $002B path, at $3100). */
+function cp01Flags(a) {
+  const r = (a - 1) & 0xff;
+  return (r & 0x80) | (r === 0 ? 0x40 : 0) | ((a & 0x0f) < 1 ? 0x10 : 0) | ((a ^ 1) & (a ^ r) & 0x80 ? 0x04 : 0) | 0x02 | (a < 1 ? 0x01 : 0);
+}
+
+/** The KDCB, the keyboard device control block at $4015: $002B loads DE with it and returns it there. */
+const KDCB = 0x4015;
+
+/**
+ * Return from the ROM keyboard routine at `pc` ($002B or $0049) as the Model III ROM does with
+ * `code` in A, verified against the ROM listing (spec §6, "Keyboard-scan hook"): DE = $4015 (the
+ * KDCB), BC, HL, IX, IY and the alternate set unchanged, F as the routine's last flag-setting
+ * instruction leaves it (`CP 01H` at $3100 for $002B, `OR A` at $004C for $0049), and the return
+ * address popped.
+ *
+ * The Model I Level II ROM keeps the same contract (MDL1LEV2.Z80, kiwisincebirth/TRS-80-ROMS at
+ * 736bcba): `_KBD` at $002B loads DE with the KDCB ($4015) and goes through `_GET` ($0013) and
+ * `CIO` ($03C2), which saves BC, HL, IX, and that DE and restores them at `CIORTN` ($03DD), to the
+ * keyboard driver `KBDDRV` ($03E3, the KDCB's driver address at $4016), whose path for a key ends
+ * with `CP $01` at $0453 (the BREAK test) and `RET NZ`, or for BREAK `RST 28H` (a RET under
+ * Level II, $400C) and `RET`; `_KEY` at $0049 is `CALL _KBD / OR A / RET NZ / JR _KEY`. So the
+ * stand-in is the same on both models (phase 6 plan, Ruling 6). It also does what the CPU does at
+ * the end of any instruction: clears `afterPrefix` and counts a pending EI down. It costs what a
+ * RET costs, 10 T-states and one refresh-counter step; the routine's RAM side effects (its
+ * key-rollover buffer at $4036, the repeat counters) are not made.
+ * @param {import('../cpu/z80cpu.js').Z80CPU} cpu
+ * @param {number} pc
+ * @param {number} code
+ */
+export function romKeyReturn(cpu, pc, code) {
+  const r = cpu.registers;
+  cpu.afterPrefix = false;
+  r.A = code;
+  r.F = pc === 0x0049 ? logicFlags(code) : cp01Flags(code);
+  r.D = KDCB >> 8;
+  r.E = KDCB & 0xff;
+  const sp = r.SP;
+  r.PC = cpu.readMemory(sp) | (cpu.readMemory((sp + 1) & 0xffff) << 8);
+  r.SP = (sp + 2) & 0xffff;
+  cpu.incrementR();
+  // The end of any instruction (Z80CPU.executeInstruction): a pending EI counts down and takes effect.
+  if (cpu.pendingEI > 0) {
+    cpu.pendingEI--;
+    if (cpu.pendingEI === 0) {
+      cpu.IFF1 = true;
+      cpu.IFF2 = true;
+    }
+  }
+  cpu.lastOpCycles = 10;
+  cpu.cycles += 10;
+}
+
+/**
+ * @typedef {{ at: number, down: boolean, key: string, code: string }} KeyEvent
+ */
+
+export class KeyQueue {
+  /** @type {import('./keyboard.js').KeyboardMatrix} */
+  #matrix;
+  /** @type {() => number} */
+  #now;
+  /** @type {number} */
+  #clockHz;
+  /** @type {KeyEvent[]} Matrix events in time order. */
+  #events = [];
+  /** @type {number} Index of the next undelivered matrix event. */
+  #next = 0;
+  /** @type {number[]} ROM codes waiting for the keyboard-scan hook. */
+  #feed = [];
+  #feedNext = 0;
+  /** @type {number} The T-state the queued typing ends at; new typing starts no earlier. */
+  #end = 0;
+  #seq = 0;
+  /** T-state of the next matrix event, Infinity when none: the Machine's cheap per-instruction check. */
+  nextAt = Infinity;
+
+  /**
+   * @param {import('./keyboard.js').KeyboardMatrix} matrix
+   * @param {() => number} now the current T-state
+   */
+  /**
+   * @param {import('./keyboard.js').KeyboardMatrix} matrix
+   * @param {() => number} now the CPU's T-state count
+   * @param {number} [clockHz] the CPU clock `type`'s cps counts in (the Model III's by default)
+   */
+  constructor(matrix, now, clockHz = CPU_CLOCK_HZ) {
+    this.#matrix = matrix;
+    this.#now = now;
+    this.#clockHz = clockHz;
+  }
+
+  /**
+   * Press a key now and hold it until `release`.
+   * @param {string} key a character ('A', '1', ' ') or a name: ENTER, CLEAR, BREAK, UP, DOWN, LEFT, RIGHT, SHIFT, SPACE
+   */
+  press(key) {
+    this.#matrix.keyDown(this.#mapped(key, 'press'), `press:${key}`);
+  }
+
+  /**
+   * Release a key `press` holds.
+   * @param {string} key
+   */
+  release(key) {
+    this.#matrix.keyUp(`press:${key}`);
+  }
+
+  /**
+   * Queue typing. In matrix mode each character is pressed for half of a 1/cps-second window and
+   * released for the other half, so a repeated letter registers twice; typing starts now, or when
+   * the typing already queued ends. In hook mode it is `feed`.
+   *
+   * Pick `cps` for the program. The default 10 cps holds each key 50 ms of emulated time, long
+   * enough for the ROM's keyboard driver, which debounces. A program that reads the keyboard
+   * slowly, or only once a frame or less often, can miss a short tap: Rear Guard needs ENTER held
+   * about half a second (`{ cps: 1 }`). A high `cps` shortens the hold and can drop keys, and
+   * typing at the ROM's line editor with no pause for the ENTER can lose characters. For
+   * `press` and `release`, use the same name for both: a mismatch leaves the key down.
+   *
+   * `str` is a string of characters, or an array whose every element is one key: a character or
+   * a key name (`['A', 'ENTER', 'UP']`), so named keys can be typed in sequence; in hook mode
+   * every element must be a character the ROM routine returns.
+   * @param {string | string[]} str '\n' is ENTER
+   * @param {{ cps?: number, mode?: 'matrix' | 'hook' }} [opts]
+   */
+  type(str, { cps = 10, mode = 'matrix' } = {}) {
+    if (mode === 'hook') return this.feed(str);
+    if (mode !== 'matrix') throw new Error(`type: mode must be 'matrix' or 'hook', not ${String(mode)}`);
+    if (!(cps > 0) || !Number.isFinite(cps)) throw new Error(`type: cps must be a positive number, not ${String(cps)}`);
+    const period = Math.round(this.#clockHz / cps);
+    const hold = Math.round(period / 2);
+    const keys = Array.from(str, (ch) => this.#mapped(ch, 'type'));
+    this.#compact();
+    let t = Math.max(this.#now(), this.#end);
+    for (const key of keys) {
+      const code = `queue:${this.#seq++}`;
+      this.#events.push({ at: t, down: true, key, code }, { at: t + hold, down: false, key, code });
+      t += period;
+    }
+    this.#end = t;
+    this.nextAt = this.#events[this.#next]?.at ?? Infinity;
+  }
+
+  /**
+   * Queue characters for the ROM keyboard-scan hook: each is returned once by the next call to
+   * $002B or $0049. The matrix is not touched.
+   * All characters are checked first, so a bad one throws and queues nothing.
+   * @param {string | string[]} str '\n' is ENTER; an array holds one character an element
+   */
+  feed(str) {
+    const codes = Array.from(str, romCode);
+    for (const code of codes) this.#feed.push(code);
+  }
+
+  /** Queued events not yet delivered: matrix presses and releases, and fed characters. */
+  get pending() {
+    return this.#events.length - this.#next + this.#feed.length - this.#feedNext;
+  }
+
+  /** True when a fed character is waiting for the hook. */
+  get hasFeed() {
+    return this.#feedNext < this.#feed.length;
+  }
+
+  /** The next fed character's ROM code, removed from the buffer. */
+  takeFeed() {
+    const code = this.#feed[this.#feedNext++];
+    if (this.#feedNext === this.#feed.length) {
+      this.#feed.length = 0;
+      this.#feedNext = 0;
+    }
+    return code;
+  }
+
+  /**
+   * Deliver every matrix event due at T-state `now`, in order.
+   * @param {number} now
+   */
+  drain(now) {
+    const events = this.#events;
+    while (this.#next < events.length && events[this.#next].at <= now) {
+      const e = events[this.#next++];
+      if (e.down) this.#matrix.keyDown(e.key, e.code);
+      else this.#matrix.keyUp(e.code);
+    }
+    this.nextAt = this.#next < events.length ? events[this.#next].at : Infinity;
+  }
+
+  /** Drop everything queued, releasing any queued key that is down; keys held with `press` stay down. */
+  clear() {
+    for (let i = this.#next; i < this.#events.length; i++) {
+      if (!this.#events[i].down) this.#matrix.keyUp(this.#events[i].code);
+    }
+    this.#events = [];
+    this.#next = 0;
+    this.#feed.length = 0;
+    this.#feedNext = 0;
+    this.#end = 0;
+    this.nextAt = Infinity;
+  }
+
+  #compact() {
+    if (this.#next > 0) {
+      this.#events = this.#events.slice(this.#next);
+      this.#next = 0;
+    }
+  }
+
+  /** @param {string} key @param {string} who */
+  #mapped(key, who) {
+    const k = matrixKey(key);
+    if (!this.#matrix.knows(k)) throw new Error(`${who}: no matrix key for ${JSON.stringify(key)}`);
+    return k;
+  }
+}

package/src/devices/keyboard.js

@@ -0,0 +1,176 @@
+/**
+ * TRS-80 Model III Keyboard Matrix
+ *
+ * The keyboard is an 8x8 switch matrix memory-mapped at 0x3800-0x3BFF.
+ * Address bits 0-7 select rows; reading returns the OR of every selected
+ * row's key bits (bit set = key down). The ROM scans by reading
+ * 0x3801, 0x3802, 0x3804 ... 0x3880.
+ *
+ * Row layout:
+ *   row 0: @ A B C D E F G          row 4: 0 1 2 3 4 5 6 7
+ *   row 1: H I J K L M N O          row 5: 8 9 : ; , - . /
+ *   row 2: P Q R S T U V W          row 6: ENT CLR BRK ↑ ↓ ← → SPC
+ *   row 3: X Y Z                    row 7: SHIFT (bit 0), right SHIFT (bit 1)
+ *
+ * Browser keys are mapped by the character they produce (e.key), with a
+ * synthetic SHIFT for characters that live on a shifted TRS-80 key (e.g.
+ * `"` is SHIFT+2). Each press is remembered by its physical key (e.code)
+ * so keyUp releases exactly the combo keyDown pressed.
+ */
+
+const SHIFT = { row: 7, bit: 0 };
+
+function key(row, bit) {
+  return [{ row, bit }];
+}
+
+function shifted(row, bit) {
+  return [{ row, bit }, SHIFT];
+}
+
+function buildKeyMap() {
+  const map = new Map();
+
+  // Letters: rows 0-3, @ at row 0 bit 0, then A-Z in order.
+  // Model III convention: unshifted letter keys type UPPERCASE, and
+  // SHIFT+letter types lowercase. Browser lowercase input maps to the
+  // bare key; browser uppercase (physically shifted) maps to SHIFT+key,
+  // matching the real machine exactly.
+  map.set("@", key(0, 0));
+  for (let i = 0; i < 26; i++) {
+    const letter = String.fromCharCode(0x41 + i); // 'A'...
+    const pos = i + 1; // A is row 0 bit 1
+    const row = Math.floor(pos / 8);
+    const bit = pos % 8;
+    map.set(letter.toLowerCase(), key(row, bit));
+    map.set(letter, shifted(row, bit));
+  }
+
+  // Digits: 0-7 on row 4, 8-9 on row 5 bits 0-1
+  for (let d = 0; d <= 7; d++) {
+    map.set(String(d), key(4, d));
+  }
+  map.set("8", key(5, 0));
+  map.set("9", key(5, 1));
+
+  // Unshifted punctuation on row 5
+  map.set(":", key(5, 2));
+  map.set(";", key(5, 3));
+  map.set(",", key(5, 4));
+  map.set("-", key(5, 5));
+  map.set(".", key(5, 6));
+  map.set("/", key(5, 7));
+
+  // Shifted symbols per the Level II keyboard legends
+  map.set("!", shifted(4, 1));
+  map.set('"', shifted(4, 2));
+  map.set("#", shifted(4, 3));
+  map.set("$", shifted(4, 4));
+  map.set("%", shifted(4, 5));
+  map.set("&", shifted(4, 6));
+  map.set("'", shifted(4, 7));
+  map.set("(", shifted(5, 0));
+  map.set(")", shifted(5, 1));
+  map.set("*", shifted(5, 2));
+  map.set("+", shifted(5, 3));
+  map.set("<", shifted(5, 4));
+  map.set("=", shifted(5, 5));
+  map.set(">", shifted(5, 6));
+  map.set("?", shifted(5, 7));
+
+  // Control and navigation keys (row 6) and shift (row 7)
+  map.set("Enter", key(6, 0));
+  map.set("Clear", key(6, 1)); // dedicated CLEAR if the browser reports one
+  map.set("Home", key(6, 1)); // common stand-in for CLEAR
+  map.set("Escape", key(6, 2)); // BREAK
+  map.set("Pause", key(6, 2)); // BREAK on keyboards that have it
+  map.set("ArrowUp", key(6, 3));
+  map.set("ArrowDown", key(6, 4));
+  map.set("ArrowLeft", key(6, 5));
+  map.set("Backspace", key(6, 5)); // ← doubles as delete in Level II
+  map.set("ArrowRight", key(6, 6));
+  map.set(" ", key(6, 7));
+  map.set("Shift", [SHIFT]);
+
+  return map;
+}
+
+const KEY_MAP = buildKeyMap();
+
+export class KeyboardMatrix {
+  constructor() {
+    this.rows = new Uint8Array(8);
+    // physical key id (e.code) -> combo currently held for it
+    this.pressed = new Map();
+    this._boundKeyDown = null;
+    this._boundKeyUp = null;
+    this._element = null;
+  }
+
+  /** Row-select read: OR of every row whose select bit is set. */
+  read(select) {
+    let value = 0;
+    let sel = select & 0xff;
+    for (let row = 0; row < 8; row++) {
+      if (sel & (1 << row)) {
+        value |= this.rows[row];
+      }
+    }
+    return value;
+  }
+
+  /**
+   * Press the combo for a browser key. Returns true if the key maps to
+   * the TRS-80 matrix (caller should preventDefault), false otherwise.
+   */
+  keyDown(browserKey, physicalCode) {
+    const combo = KEY_MAP.get(browserKey);
+    if (!combo) {
+      return false;
+    }
+    this.pressed.set(physicalCode || browserKey, combo);
+    this._rebuild();
+    return true;
+  }
+
+  /** True when `browserKey` maps to the TRS-80 matrix. */
+  knows(browserKey) {
+    return KEY_MAP.has(browserKey);
+  }
+
+  /** Release whatever combo the physical key pressed. */
+  keyUp(physicalCode) {
+    if (!this.pressed.delete(physicalCode)) {
+      return false;
+    }
+    this._rebuild();
+    return true;
+  }
+
+  /** Directly press a matrix position (used by tests and the system). */
+  pressKey(row, bit) {
+    this.pressed.set(`matrix:${row}:${bit}`, key(row, bit));
+    this._rebuild();
+  }
+
+  releaseKey(row, bit) {
+    this.pressed.delete(`matrix:${row}:${bit}`);
+    this._rebuild();
+  }
+
+  reset() {
+    this.pressed.clear();
+    this.rows.fill(0);
+  }
+
+  // The matrix is always derived from the full set of held combos, so
+  // overlapping synthetic shifts can't get out of sync on release.
+  _rebuild() {
+    this.rows.fill(0);
+    for (const combo of this.pressed.values()) {
+      for (const { row, bit } of combo) {
+        this.rows[row] |= 1 << bit;
+      }
+    }
+  }
+}

package/src/devices/printer.js

@@ -0,0 +1,44 @@
+/**
+ * TRS-80 Model III line printer (ports 0xF8-0xFB)
+ *
+ * The parallel printer interface answers status reads and takes data
+ * writes on port 0xF8; all four addresses 0xF8-0xFB decode to it.
+ * Status 0x30 is "selected, ready" — busy (bit 7) and out-of-paper
+ * (bit 6) clear, unit-select (bit 5) and the held-high line (bit 4)
+ * set — which is what the ROM's LPRINT driver polls for before every
+ * byte. This printer is never busy and never out of paper: bytes land
+ * on an in-memory printout the UI offers as a .txt download.
+ */
+
+const STATUS_READY = 0x30;
+
+export class Printer {
+  constructor() {
+    this.bytes = [];
+  }
+
+  status() {
+    return STATUS_READY;
+  }
+
+  write(byte) {
+    this.bytes.push(byte & 0xff);
+  }
+
+  get length() {
+    return this.bytes.length;
+  }
+
+  /** The printout as text — the TRS-80 ends lines with 0x0D. */
+  text() {
+    let out = "";
+    for (const b of this.bytes) {
+      out += b === 0x0d ? "\n" : String.fromCharCode(b);
+    }
+    return out;
+  }
+
+  clear() {
+    this.bytes = [];
+  }
+}

package/src/devices/sound.js

@@ -0,0 +1,53 @@
+/**
+ * The Model III's only sound source is the cassette output on port $FF. This device keeps every
+ * write to that port, raw and stamped with the CPU's T-state count, in a fixed ring of 65,536
+ * events (typed arrays, no allocation per write). The newest events are kept; `overflowed`
+ * counts the ones lost to wrap-around. It is not part of serializeState.
+ */
+
+const SIZE = 65536;
+
+export class Sound {
+  #cycles = new Float64Array(SIZE);
+  #values = new Uint8Array(SIZE);
+  #head = 0; // next slot to write
+  #count = 0; // events held, at most SIZE
+  /** @type {number} Events lost to wrap-around since the last clear. */
+  overflowed = 0;
+
+  /**
+   * Record one port $FF write. Called by the I/O system.
+   * @param {number} cycle T-states at the write.
+   * @param {number} value The raw byte written.
+   */
+  record(cycle, value) {
+    this.#cycles[this.#head] = cycle;
+    this.#values[this.#head] = value;
+    this.#head = (this.#head + 1) & (SIZE - 1);
+    if (this.#count < SIZE) this.#count++;
+    else this.overflowed++;
+  }
+
+  /**
+   * Every port $FF write after a cycle, oldest first.
+   * @param {number} [sinceCycle] Only events with `cycle > sinceCycle`; the default -1 returns everything, including a write at cycle 0.
+   * @returns {{ cycle: number, value: number }[]}
+   */
+  events(sinceCycle = -1) {
+    const out = [];
+    const start = (this.#head - this.#count + SIZE) & (SIZE - 1);
+    for (let k = 0; k < this.#count; k++) {
+      const i = (start + k) & (SIZE - 1);
+      const cycle = this.#cycles[i];
+      if (cycle > sinceCycle) out.push({ cycle, value: this.#values[i] });
+    }
+    return out;
+  }
+
+  /** Empty the ring and reset `overflowed`. */
+  clear() {
+    this.#head = 0;
+    this.#count = 0;
+    this.overflowed = 0;
+  }
+}

package/src/devices/video.js

@@ -0,0 +1,69 @@
+/**
+ * The video as a text readout: 16 lines over video RAM at $3C00-$3FFF, 64 columns, or 32 in
+ * 32-column mode (on the Model III, port $EC bit 2; on the Model I, port $FF bit 3, MODESEL), where
+ * the hardware shows the even-address bytes double-wide. It reads the live video RAM; it draws
+ * nothing. The Model I's video RAM sits at the same addresses (models.js); the stock machine has no
+ * bit 6 there, so a byte reads back, and shows, with bit 6 made from bits 5 and 7 (memory.js, which
+ * cites the Technical Reference Handbook), unless the lowercase modification is fitted.
+ */
+
+import { fromBase64 } from '../debug/state.js';
+
+export class Video {
+  #system;
+
+  /** @param {import('../machine/trs80-system.js').TRS80System} system */
+  constructor(system) {
+    this.#system = system;
+  }
+
+  /** @returns {Uint8Array} A live view of $3C00-$3FFF (1024 bytes). */
+  get raw() {
+    return this.#system.memory.videoRam;
+  }
+
+  /** @returns {64 | 32} */
+  get columns() {
+    return this.#system.columns32 ? 32 : 64;
+  }
+
+  /**
+   * The screen as 16 lines of text. Bytes below $20 show as +$40 (the Model III character
+   * generator folds them to $40-$5F), and graphics and special bytes ($80-$FF) show as '.'.
+   * @returns {string[]}
+   */
+  text() {
+    const ram = this.raw;
+    const step = this.#system.columns32 ? 2 : 1;
+    const cols = 64 / step;
+    const rows = [];
+    for (let row = 0; row < 16; row++) {
+      let line = '';
+      for (let col = 0; col < cols; col++) {
+        let byte = ram[row * 64 + col * step];
+        if (byte < 0x20) byte += 0x40;
+        line += byte >= 0x20 && byte < 0x80 ? String.fromCharCode(byte) : '.';
+      }
+      rows.push(line);
+    }
+    return rows;
+  }
+
+  /**
+   * The cells of video RAM that differ from a snapshot's (`m.debug.snapshot()`), row-major, as
+   * byte values over the 64-column RAM layout (32-column mode shows only even columns).
+   * @param {any} snap
+   * @returns {{ row: number, col: number, was: number, now: number }[]}
+   */
+  diff(snap) {
+    const text = snap?.memory?.videoRam;
+    if (typeof text !== 'string') throw new Error('video.diff needs a snapshot from m.debug.snapshot()');
+    const was = fromBase64(text);
+    const now = this.raw;
+    const out = [];
+    for (let i = 0; i < now.length; i++) {
+      if (was[i] !== now[i]) out.push({ row: i >> 6, col: i & 63, was: was[i], now: now[i] });
+    }
+    return out;
+  }
+}