@fugloy/emu 0.0.0-stage → 0.3.0

package/src/machine/models.js

@@ -0,0 +1,123 @@
+/**
+ * Model descriptions: what differs between the TRS-80 models the Machine builds, as data, so the
+ * memory map, the I/O ports, the clock, and the ROM checks read one description instead of
+ * hard-coding the Model III (spec §5).
+ *
+ * Model I facts and where they come from (the ROM sources are github.com/kiwisincebirth/TRS-80-ROMS;
+ * spec §5 lists what is still unverified against the Model I Technical Reference Manual):
+ * - ROM: 12 KB at $0000-$2FFF. The repository's Model I Level II images `test-roms/M1L2_1.2.bin`
+ *   and `M1L2_1.3.bin` are 12,288 bytes each, and its MODEL1.md describes `MDL1LEV2.Z80` as the
+ *   source of the "Model I Level 2 12KB ROMS".
+ * - Keyboard matrix at $3800, video RAM at $3C00 (400H bytes), RAM from $4000: CONSTANTS.Z80,
+ *   "Memory Mapped Hardware" and "RAM Communications Area".
+ * - $37E0-$37EF belong to the Expansion Interface (drive select $37E1, cassette select $37E4,
+ *   printer $37E8, the disk controller $37EC-$37EF: CONSTANTS.Z80, "Memory Mapped Hardware,
+ *   Model 1"). Without the Expansion Interface those addresses read $FF: MDL1LEV2.Z80 at $0069
+ *   ("$FF if no expansion interface present") and $0696-$069C, where the ROM takes $FF (or $00) at
+ *   $37EC as "no disk controller" and goes to Level II BASIC. The rest of $3000-$37FF decodes to
+ *   nothing and is taken to read $FF as well (unverified).
+ * - RAM sizes 4, 16, 32, and 48 KB from $4000 (spec §5, unverified against the manual; Ruling 2
+ *   of the phase 6 plan). Above the fitted RAM a read is taken to float to $FF and a write is
+ *   lost (unverified); the ROM's MEMORY SIZE? probe at $00C4-$00D4 needs only that a byte there
+ *   does not hold the complement written to it.
+ * - Clock 1,774,080 Hz: spec §5's 1.774 MHz, taken as the 10.6445 MHz crystal divided by 6 (as
+ *   xtrs runs it; unverified against the manual). The ROM's PAUSE loop at $0060 is commented
+ *   "BC times 14.65" µs at $06AF, and one pass of it is 26 T-states, which puts the clock at
+ *   1.775 MHz.
+ */
+
+/**
+ * @typedef {{ id: 1 | 3, name: string, clockHz: number, timerHz: number, romTop: number,
+ *   romSizes: readonly number[], romSizeText: string, ram: readonly number[], defaultRam: number,
+ *   ramNote: string, roms: readonly string[], romTitle: string, stateMachine: string }} Model
+ */
+
+/** @type {Model} */
+export const MODEL_I = Object.freeze({
+  id: 1,
+  name: 'Model I',
+  clockHz: 1774080,
+  // The Expansion Interface's 40 Hz clock, raised through its latch at $37E0
+  // (devices/interrupt-latch.js, which cites it); none without the Expansion Interface.
+  timerHz: 40,
+  romTop: 0x3000,
+  romSizes: Object.freeze([0x3000]),
+  romSizeText: "The Model I's Level II ROM is 12KB (0x3000)",
+  ram: Object.freeze([4, 16, 32, 48]),
+  defaultRam: 48,
+  ramNote: '',
+  roms: Object.freeze(['model1-level2-1.2', 'model1-level2-1.3']),
+  romTitle: 'the Model I Level II ROM',
+  stateMachine: 'trs80-model1',
+});
+
+/** @type {Model} */
+export const MODEL_III = Object.freeze({
+  id: 3,
+  name: 'Model III',
+  clockHz: 2027520,
+  timerHz: 30,
+  romTop: 0x3800,
+  // The real 14K image, or a 16K padded image of it (only $0000-$37FF is mapped).
+  romSizes: Object.freeze([0x3800, 0x4000]),
+  romSizeText: 'Expected 14KB (0x3800) or a 16KB (0x4000) padded image',
+  ram: Object.freeze([48]),
+  defaultRam: 48,
+  // Ruling 2 of the phase 6 plan: 16K and 32K are cheap but would run untested programs.
+  ramNote: '; 16K and 32K come in a later phase',
+  roms: Object.freeze(['model3-rev-c-2ef8', 'model3-rev-c-frehd']),
+  romTitle: 'the Model III ROM',
+  stateMachine: 'trs80-model3',
+});
+
+/** The models built, by number. */
+export const MODELS = Object.freeze({ 1: MODEL_I, 3: MODEL_III });
+
+/**
+ * The description of model `n`, or a sentence-long error for a model not built.
+ * @param {unknown} n
+ * @returns {Model}
+ */
+export function modelOf(n) {
+  if (n === 1) return MODEL_I;
+  if (n === 3) return MODEL_III;
+  if (n === 4) throw new Error('There is no Model 4 yet: it needs a Model 4 ROM and boot disk to prove it boots, and comes in its own plan when one is supplied; use model 1 or 3.');
+  throw new Error(`model must be 1 (the Model I) or 3 (the Model III), not ${String(n)}.`);
+}
+
+/**
+ * Why `ram` (in K) is not a size model `desc` is built with, as a sentence, or null when it is.
+ * @param {Model} desc
+ * @param {unknown} ram
+ * @returns {string | null}
+ */
+export function ramProblem(desc, ram) {
+  if (desc.ram.includes(/** @type {number} */ (ram))) return null;
+  const sizes = desc.ram.length === 1 ? String(desc.ram[0]) : `${desc.ram.slice(0, -1).join(', ')}, or ${desc.ram.at(-1)}`;
+  const got = typeof ram === 'string' ? JSON.stringify(ram) : String(ram);
+  return `The ${desc.name} takes ram: ${sizes} (K), not ${got}${desc.ramNote}.`;
+}
+
+/**
+ * The CPU clock of model `n`, in Hz.
+ * @param {1 | 3} n
+ */
+export function clockHz(n) {
+  return modelOf(n).clockHz;
+}
+
+/**
+ * Why a recognised ROM cannot run on model `n`, as a sentence, or null when it can (or is not
+ * recognised: an unknown image is checked by its size alone).
+ * @param {string | null} recognized the ROM_HASHES name
+ * @param {1 | 3} n
+ * @returns {string | null}
+ */
+export function romModelProblem(recognized, n) {
+  if (recognized === null) return null;
+  const wanted = modelOf(n);
+  if (wanted.roms.includes(recognized)) return null;
+  const owner = [MODEL_I, MODEL_III].find((d) => d.roms.includes(recognized));
+  if (owner === undefined) return null;
+  return `This ROM is ${owner.romTitle} (${recognized}); it runs on the ${owner.name}, not the ${wanted.name}: construct the Machine with model: ${owner.id}.`;
+}

package/src/machine/rom-hashes.js

@@ -0,0 +1,21 @@
+/**
+ * Known ROM images by SHA-256 (lowercase hex), so the Machine can report which ROM it was given
+ * and refuse one given for the other model (spec §5: the core validates by length and a
+ * known-hash table). Hashes are facts about the images; the images themselves are never committed
+ * or bundled. Each name starts with its model (`model1-`, `model3-`); src/machine/models.js lists
+ * which names each model runs.
+ *
+ * Source for all: github.com/kiwisincebirth/TRS-80-ROMS, folder test-roms/.
+ * - `M1L2_1.2.bin` and `M1L2_1.3.bin` (12,288 bytes each): the Model I Level II ROM, versions 1.2
+ *   and 1.3 (the repository's MODEL1.md: "Both 1.3 and 1.2 versions"), hashed 2026-10-18; 1.3 is
+ *   the image the repository's fugloy.mcp.json names as roms.model1.
+ * - `Model3-RevC-2EF8.bin` (14,336 bytes): the stock Model III Rev C ROM and the image named as
+ *   roms.model3; `Model3-RevC-FreHD.bin` is the same ROM patched to boot a FreHD hard-disk
+ *   emulator. Hashed 2026-10-17.
+ */
+export const ROM_HASHES = Object.freeze({
+  '3cd3824d2ac2743750d2179951ed812794302b885ccb4f98aa2579b352c4b00e': 'model1-level2-1.2',
+  '5515d95d7c19058400a2e91c6930bb557035db5ce093bd96fd017f795c346776': 'model1-level2-1.3',
+  beeb3741175a8b8706cc384d5b2534ebf32e383662864054e5a0ce4d861a43bb: 'model3-rev-c-2ef8',
+  ad6de30c6aece2d6a2243ee90a2959295d5c46b82650b27f46f1ecf8b34b2361: 'model3-rev-c-frehd',
+});

package/src/machine/sha256.js

@@ -0,0 +1,74 @@
+/**
+ * SHA-256 (FIPS 180-4) in plain JavaScript, because the core may use neither Node's crypto nor
+ * the browser's asynchronous Web Crypto. A copy of @fugloy/disasm's `src/hash.ts` (emu must not
+ * depend on disasm); identifies ROM images against ROM_HASHES.
+ */
+const K = new Uint32Array([
+  0x428a2f98, 0x71374491, 0xb5c0fbcf, 0xe9b5dba5, 0x3956c25b, 0x59f111f1, 0x923f82a4, 0xab1c5ed5,
+  0xd807aa98, 0x12835b01, 0x243185be, 0x550c7dc3, 0x72be5d74, 0x80deb1fe, 0x9bdc06a7, 0xc19bf174,
+  0xe49b69c1, 0xefbe4786, 0x0fc19dc6, 0x240ca1cc, 0x2de92c6f, 0x4a7484aa, 0x5cb0a9dc, 0x76f988da,
+  0x983e5152, 0xa831c66d, 0xb00327c8, 0xbf597fc7, 0xc6e00bf3, 0xd5a79147, 0x06ca6351, 0x14292967,
+  0x27b70a85, 0x2e1b2138, 0x4d2c6dfc, 0x53380d13, 0x650a7354, 0x766a0abb, 0x81c2c92e, 0x92722c85,
+  0xa2bfe8a1, 0xa81a664b, 0xc24b8b70, 0xc76c51a3, 0xd192e819, 0xd6990624, 0xf40e3585, 0x106aa070,
+  0x19a4c116, 0x1e376c08, 0x2748774c, 0x34b0bcb5, 0x391c0cb3, 0x4ed8aa4a, 0x5b9cca4f, 0x682e6ff3,
+  0x748f82ee, 0x78a5636f, 0x84c87814, 0x8cc70208, 0x90befffa, 0xa4506ceb, 0xbef9a3f7, 0xc67178f2,
+]);
+
+const H0 = [0x6a09e667, 0xbb67ae85, 0x3c6ef372, 0xa54ff53a, 0x510e527f, 0x9b05688c, 0x1f83d9ab, 0x5be0cd19];
+
+const rotr = (x, n) => (x >>> n) | (x << (32 - n));
+
+/**
+ * @param {Uint8Array} bytes
+ * @returns {Uint8Array} the 32-byte digest
+ */
+export function sha256(bytes) {
+  const len = bytes.length;
+  const padded = new Uint8Array(((len + 9 + 63) >> 6) << 6);
+  padded.set(bytes);
+  padded[len] = 0x80;
+  const view = new DataView(padded.buffer);
+  const bits = len * 8;
+  view.setUint32(padded.length - 8, Math.floor(bits / 0x100000000));
+  view.setUint32(padded.length - 4, bits >>> 0);
+
+  const h = Uint32Array.from(H0);
+  const w = new Uint32Array(64);
+  for (let off = 0; off < padded.length; off += 64) {
+    for (let i = 0; i < 16; i++) w[i] = view.getUint32(off + i * 4);
+    for (let i = 16; i < 64; i++) {
+      const w15 = w[i - 15];
+      const w2 = w[i - 2];
+      const s0 = rotr(w15, 7) ^ rotr(w15, 18) ^ (w15 >>> 3);
+      const s1 = rotr(w2, 17) ^ rotr(w2, 19) ^ (w2 >>> 10);
+      w[i] = (w[i - 16] + s0 + w[i - 7] + s1) >>> 0;
+    }
+    let a = h[0], b = h[1], c = h[2], d = h[3], e = h[4], f = h[5], g = h[6], hh = h[7];
+    for (let i = 0; i < 64; i++) {
+      const S1 = rotr(e, 6) ^ rotr(e, 11) ^ rotr(e, 25);
+      const ch = (e & f) ^ (~e & g);
+      const t1 = (hh + S1 + ch + K[i] + w[i]) >>> 0;
+      const S0 = rotr(a, 2) ^ rotr(a, 13) ^ rotr(a, 22);
+      const maj = (a & b) ^ (a & c) ^ (b & c);
+      const t2 = (S0 + maj) >>> 0;
+      hh = g; g = f; f = e;
+      e = (d + t1) >>> 0;
+      d = c; c = b; b = a;
+      a = (t1 + t2) >>> 0;
+    }
+    h[0] = (h[0] + a) >>> 0; h[1] = (h[1] + b) >>> 0; h[2] = (h[2] + c) >>> 0; h[3] = (h[3] + d) >>> 0;
+    h[4] = (h[4] + e) >>> 0; h[5] = (h[5] + f) >>> 0; h[6] = (h[6] + g) >>> 0; h[7] = (h[7] + hh) >>> 0;
+  }
+  const out = new Uint8Array(32);
+  const outView = new DataView(out.buffer);
+  for (let i = 0; i < 8; i++) outView.setUint32(i * 4, h[i]);
+  return out;
+}
+
+/**
+ * @param {Uint8Array} bytes
+ * @returns {string} the digest as 64 lowercase hex digits
+ */
+export function sha256Hex(bytes) {
+  return Array.from(sha256(bytes), (b) => b.toString(16).padStart(2, '0')).join('');
+}

package/src/machine/trs80-system.js

@@ -0,0 +1,289 @@
+/**
+ * TRS-80 System, Model III or Model I
+ *
+ * Owns and wires the machine: Z80 CPU, memory map, I/O ports, and the
+ * keyboard matrix, laid out by the model description (models.js). Runs the
+ * CPU in T-state-budgeted slices at the model's clock (the Model III's real
+ * 2.02752 MHz) and raises the Model III's 30 Hz RTC heartbeat interrupt the
+ * ROM's clock/cursor services depend on, or the Model I Expansion
+ * Interface's 40 Hz clock, through its latch at $37E0
+ * (devices/interrupt-latch.js); a Model I without the Expansion Interface
+ * has no clock and takes no interrupts.
+ *
+ * Rendering is the caller's concern: read `memory.videoRam` (or
+ * `screenText()`) and consult `memory.videoDirty`. Keyboard input goes
+ * through `system.keyboard` (press and release keys directly).
+ */
+
+import { Z80CPU } from "../cpu/z80cpu.js";
+import { MemorySystem } from "./memory.js";
+import { IOSystem, MODE_32COL_BIT, M1_MODESEL_BIT } from "./io.js";
+import { TIMER_BIT } from "../devices/interrupt-latch.js";
+import { KeyboardMatrix } from "../devices/keyboard.js";
+import { MODEL_III, modelOf } from "./models.js";
+
+/** The Model III's clock and RTC; a system's own are `clockHz` and `rtcInterval`. */
+export const CPU_CLOCK_HZ = MODEL_III.clockHz;
+export const RTC_HZ = MODEL_III.timerHz;
+export const RTC_INTERVAL_TSTATES = CPU_CLOCK_HZ / RTC_HZ; // 67,584
+
+export class TRS80System {
+  /**
+   * @param {{ romData: Uint8Array, log?: (level: string, text: string) => void,
+   *   model?: 1 | 3 | import('./models.js').Model, ram?: number, expansion?: boolean, lowercase?: boolean }} opts
+   *   the model (a number or a description; the Model III by default), its RAM in K (the model's
+   *   default), and the Model I's Expansion Interface (fitted by default) and lowercase modification
+   *   (not fitted by default); the Machine checks them
+   */
+  constructor({ romData, log, model = MODEL_III, ram, expansion = true, lowercase = false }) {
+    const desc = typeof model === "number" ? modelOf(model) : model;
+    this.model = desc;
+    this.clockHz = desc.clockHz;
+    this.rtcInterval = desc.clockHz / desc.timerHz;
+    this.expansion = expansion;
+    this.lowercase = lowercase;
+    this.memory = new MemorySystem({ model: desc, ram: ram ?? desc.defaultRam, lowercase });
+    this.io = new IOSystem({ model: desc, expansion });
+    // The Model I's Expansion Interface addresses go to the I/O decode
+    if (this.io.latch !== null) this.memory.expansion = this.io;
+    // The 32-column bit: port $EC bit 2 on the Model III, port $FF bit 3 (MODESEL) on the Model I
+    this._mode32Bit = desc.id === 1 ? M1_MODESEL_BIT : MODE_32COL_BIT;
+    this.keyboard = new KeyboardMatrix();
+    this.cpu = new Z80CPU();
+    if (log !== undefined) {
+      this.cpu.log = log;
+      this.io.cassette.log = log;
+    }
+
+    this.memory.keyboard = this.keyboard;
+
+    this.cpu.readMemory = (addr) => this.memory.readByte(addr);
+    this.cpu.writeMemory = (addr, value) => this.memory.writeByte(addr, value);
+    this.cpu.readPort = (port) => this.io.readPort(port);
+    this.cpu.writePort = (port, value) => this.io.writePort(port, value);
+
+    // A mode-register change (e.g. the ROM handling CHR$(23)) redraws
+    // the same video RAM in a different layout — force a repaint.
+    this.io.onModeWrite = () => {
+      this.memory.videoDirty = true;
+    };
+
+    // Cassette-out sound transitions are stamped in CPU T-states
+    this.io.getCycles = () => this.cpu.cycles;
+
+    // The Model III WAIT (port F4 bit 6): the controller runs ahead to its
+    // next DRQ or INTRQ; the CPU's clock catches up, and stepInstruction
+    // does not tick the controller for those T-states again. A port write
+    // from outside an instruction (a debugger poke) does not wait.
+    this._executing = false;
+    this._fdcAhead = 0;
+    this.io.onWait = (runToDrq) => {
+      if (!this._executing) return;
+      const held = runToDrq();
+      this.cpu.cycles += held;
+      this._fdcAhead += held;
+    };
+
+    this.memory.loadROM(romData);
+
+    this.nextRtcAt = this.rtcInterval;
+    this.reset();
+  }
+
+  /**
+   * Hardware reset (the orange button): CPU restarts at 0x0000, interrupt
+   * latches clear, screen blanks. RAM contents survive, as on the real
+   * machine.
+   */
+  reset() {
+    this.cpu.reset();
+    this.io.reset();
+    this.keyboard.reset();
+    this.memory.clearVideoRAM();
+    this.nextRtcAt = this.cpu.cycles + this.rtcInterval;
+    this._nmiWasPending = false;
+  }
+
+  /**
+   * Execute instructions until `budget` T-states have elapsed, raising
+   * the RTC heartbeat on schedule and delivering pending interrupts
+   * between instructions. Returns the T-states actually consumed (the
+   * final instruction may overshoot slightly).
+   */
+  runTStates(budget) {
+    const start = this.cpu.cycles;
+    const target = start + budget;
+
+    while (this.cpu.cycles < target) {
+      this.stepInstruction();
+    }
+
+    return this.cpu.cycles - start;
+  }
+
+  /**
+   * One instruction boundary, the only place the machine advances: raise
+   * the RTC heartbeat when its T-state is due, deliver a pending
+   * interrupt or NMI edge, then call `beforeExecute` (if given) and
+   * execute one instruction, ticking the disk controller by its cost.
+   * `runTStates` and the Machine facade both step through here, so the
+   * RTC keeps one schedule however the machine is driven. Returns the
+   * T-states consumed, an interrupt response included.
+   * @param {() => boolean | 'stop' | void} [beforeExecute] called after interrupt delivery, with PC at the instruction about to run; returning true means it stood in for that instruction, which then does not execute; returning 'stop' means no instruction executes at all (a debugger break)
+   * @returns {number}
+   */
+  stepInstruction(beforeExecute) {
+    const start = this.cpu.cycles;
+    if (this.cpu.cycles >= this.nextRtcAt) {
+      if (this.model.id === 3) this.io.raiseRTC();
+      else if (this.io.latch !== null) this.io.latch.raise(TIMER_BIT);
+      this.nextRtcAt += this.rtcInterval;
+    }
+    if (this.io.pendingInterrupt()) {
+      this.cpu.interrupt();
+    }
+    // FDC INTRQ -> NMI, edge-triggered so one assertion fires one NMI. The
+    // CPU holds an NMI off after a lone DD/FD prefix, as it does a maskable
+    // interrupt (Young §3.6); the edge then stays pending for the next
+    // boundary.
+    const nmiNow = this.io.nmiPending();
+    if (nmiNow && !this._nmiWasPending) {
+      if (this.cpu.nmi()) this._nmiWasPending = true;
+    } else {
+      this._nmiWasPending = nmiNow;
+    }
+
+    // The disk controller ticks by every T-state the boundary takes, an interrupt or NMI
+    // response included, so its clock (the disk's angle) keeps step with the CPU's: the response
+    // first, so an OUT that sets the WAIT finds the controller at the start of that OUT; then the
+    // instruction, less the T-states the WAIT already ran it ahead for (`_fdcAhead`).
+    const before = this.cpu.cycles;
+    if (before !== start) this.io.fdc.tick(before - start);
+
+    // beforeExecute returning true has executed the boundary's instruction itself (the
+    // Machine's ROM keyboard-scan hook stands in for a RET), so the CPU does not run one.
+    // Returning 'stop' runs nothing; the return value is then the response's T-states.
+    // try/finally: a callback or an instruction that throws must not leave `_executing` set, or
+    // a later debugger port poke would wait as if an instruction were running.
+    this._executing = true;
+    try {
+      if (beforeExecute !== undefined) {
+        const r = beforeExecute();
+        if (r === 'stop') return before - start;
+        if (r !== true) this.cpu.executeInstruction();
+      } else {
+        this.cpu.executeInstruction();
+      }
+    } catch (e) {
+      this._fdcAhead = 0;
+      throw e;
+    } finally {
+      this._executing = false;
+    }
+    this.io.fdc.tick(this.cpu.cycles - before - this._fdcAhead);
+    this._fdcAhead = 0;
+    return this.cpu.cycles - start;
+  }
+
+  /**
+   * True when the machine is in 32-character mode (on the Model III the
+   * mode register's bit 2, on the Model I port $FF's MODESEL, bit 3; set by
+   * the ROM for CHR$(23), cleared by CLS). The ROM lays 32-column text at
+   * even video addresses; hardware shows them double-wide.
+   */
+  get columns32() {
+    return (this.io.modeRegister & this._mode32Bit) !== 0;
+  }
+
+  /** Mount a .dsk image (DiskImage) in drive 0-3. */
+  mountDisk(driveNumber, image) {
+    this.io.fdc.attachDrive(driveNumber, image);
+  }
+
+  /**
+   * Eject every drive and reboot into cassette BASIC, answering the
+   * ROM's Cass? and Memory Size? prompts. Cassette-world loaders (the
+   * library, .cas tapes, paste-BASIC) need the machine at READY — under
+   * a booted DOS their typed RUN goes to the DOS prompt instead. Runs
+   * ~3.5 emulated seconds inline, a blink of wall clock.
+   * @returns {boolean} true when the READY prompt was reached
+   */
+  bootToCassetteBasic() {
+    for (let drive = 0; drive < 4; drive++) {
+      this.ejectDisk(drive);
+    }
+    this.reset();
+    const pressEnter = () => {
+      this.keyboard.keyDown("Enter", "bootdance");
+      this.runTStates(200000);
+      this.keyboard.keyUp("bootdance");
+      this.runTStates(100000);
+    };
+    this.runSeconds(1);
+    pressEnter();
+    this.runSeconds(0.5);
+    pressEnter();
+    this.runSeconds(2);
+    return this.screenText().join("\n").includes("READY");
+  }
+
+  ejectDisk(driveNumber) {
+    this.io.fdc.ejectDrive(driveNumber);
+  }
+
+  /** Convenience for tests: run N emulated seconds. */
+  runSeconds(seconds) {
+    return this.runTStates(Math.round(seconds * this.clockHz));
+  }
+
+  /**
+   * Type text through the keyboard matrix at emulated speed ("turbo
+   * paste"): each key is held long enough for the ROM's scan/debounce,
+   * but the wall-clock cost is only the emulation time (~3 ms/char).
+   * '\n' presses ENTER. Returns the number of characters that had no
+   * matrix mapping and were skipped.
+   *
+   * After ENTER the ROM tokenizes and stores the line (cost grows with
+   * program size) before it scans the keyboard again — give it room or
+   * the first character of the next line gets eaten. The default suits
+   * the small built-in classics; pass a larger `enterTStates` for
+   * multi-KB listings (a 5.7 KB program needs ~1M).
+   */
+  typeText(text, { enterTStates = 400000 } = {}) {
+    let skipped = 0;
+    let seq = 0;
+    for (const ch of text) {
+      const key = ch === "\n" ? "Enter" : ch;
+      const code = `typeText:${seq++}`;
+      if (!this.keyboard.keyDown(key, code)) {
+        skipped++;
+        continue;
+      }
+      this.runTStates(70000); // held across several scans + debounce
+      this.keyboard.keyUp(code);
+      this.runTStates(ch === "\n" ? enterTStates : 50000);
+    }
+    return skipped;
+  }
+
+  /**
+   * The 64x16 screen as strings, for tests and status displays.
+   * Control bytes 0x00-0x1F display as their 0x40-0x5F fold (Model III
+   * character generator); block-graphics bytes render as '.'.
+   */
+  screenText() {
+    const rows = [];
+    for (let row = 0; row < 16; row++) {
+      let line = "";
+      for (let col = 0; col < 64; col++) {
+        let byte = this.memory.videoRam[row * 64 + col];
+        if (byte < 0x20) {
+          byte += 0x40;
+        }
+        line += byte >= 0x20 && byte < 0x80 ? String.fromCharCode(byte) : ".";
+      }
+      rows.push(line);
+    }
+    return rows;
+  }
+}