@fugloy/emu 0.2.0 → 0.3.0

package/src/machine/memory.js

@@ -1,26 +1,70 @@
 /**
- * TRS-80 Model III Memory Management System
+ * TRS-80 memory map, by model (src/machine/models.js holds the sources for the Model I facts):
  *
- * Real Model III address map (non-disk machine):
- *   0x0000-0x37FF  14K ROM (write-protected)
- *   0x3800-0x3BFF  keyboard matrix (memory-mapped, read-only;
- *                  low 8 address bits select rows, A8/A9 undecoded)
- *   0x3C00-0x3FFF  1K video RAM (64 cols x 16 rows)
- *   0x4000-0xFFFF  48K RAM
+ *   Model III (non-disk machine):
+ *     0x0000-0x37FF  14K ROM (write-protected)
+ *     0x3800-0x3BFF  keyboard matrix (memory-mapped, read-only;
+ *                    low 8 address bits select rows, A8/A9 undecoded)
+ *     0x3C00-0x3FFF  1K video RAM (64 cols x 16 rows)
+ *     0x4000-0xFFFF  48K RAM
+ *
+ *   Model I:
+ *     0x0000-0x2FFF  12K Level II ROM (write-protected)
+ *     0x3000-0x37DF  nothing: reads float to 0xFF, writes are lost
+ *     0x37E0-0x37EF  the Expansion Interface (IOSystem.readExpansion and
+ *                    writeExpansion: the interrupt latch at 0x37E0, the drive
+ *                    select at 0x37E1, the printer at 0x37E8, the WD1771 at
+ *                    0x37EC-0x37EF); without it, nothing, as 0x3000-0x37DF
+ *     0x3800-0x3BFF  keyboard matrix, as on the Model III
+ *     0x3C00-0x3FFF  1K video RAM, seven bits wide (below)
+ *     0x4000-...     4, 16, 32, or 48K RAM; above it reads float to 0xFF
+ *                    and writes are lost
+ *
+ *   The stock Model I's video RAM has no bit 6: "There are seven RAMs. Six
+ *   are used for ASCII storage, and the seventh is used as a graphic/
+ *   alphanumeric definition bit. ... Notice the line labeled Bit 6. It is
+ *   sourced by NOR gate Z30 at pin 13. If Bit 5 ... and Bit 7 ... are low,
+ *   then Bit 6 will be high" (TRS-80 Micro Computer Technical Reference
+ *   Handbook, 2nd ed., 1982, p. 34, "Video RAMs"). A byte written there is
+ *   kept as it reads back and displays: bit 6 = NOT (bit 5 OR bit 7). The
+ *   lowercase modification (`lowercase: true`) fits the missing RAM, so all
+ *   eight bits are kept.
  */
 
-const ROM_LIMIT = 0x3800;
+import { MODEL_III } from "./models.js";
+
+const KEYBOARD_BASE = 0x3800;
 const KEYBOARD_LIMIT = 0x3c00;
 const RAM_BASE = 0x4000;
+const EXPANSION_BASE = 0x37e0;
+const EXPANSION_LIMIT = 0x37f0;
 
 export class MemorySystem {
-  constructor() {
+  /**
+   * @param {{ model?: import('./models.js').Model, ram?: number, lowercase?: boolean }} [opts] the
+   *   model (the Model III by default), its RAM in K (checked by the Machine against the model's
+   *   sizes), and on the Model I whether the lowercase modification is fitted (not by default)
+   */
+  constructor({ model = MODEL_III, ram = model.defaultRam, lowercase = false } = {}) {
+    this.model = model;
+
+    // The stock Model I's seven-bit video RAM (above); the Model III's and a
+    // lowercase-modified Model I's keep all eight bits.
+    this.videoBit6Gate = model.id === 1 && !lowercase;
+
+    // The Model I's Expansion Interface at 0x37E0-0x37EF: the IOSystem, set by
+    // TRS80System when the interface is fitted; null, those addresses read 0xFF.
+    /** @type {{ readExpansion(a: number): number, peekExpansion(a: number): number, writeExpansion(a: number, v: number): void } | null} */
+    this.expansion = null;
+
     // ROM storage is 16K so padded 16K images can be loaded verbatim,
-    // but only 0x0000-0x37FF is ever mapped as ROM.
+    // but only 0x0000 up to the model's ROM top is ever mapped as ROM.
     this.rom = new Uint8Array(0x4000);
+    this.romLimit = model.romTop;
 
-    // 48K RAM (0x4000 - 0xFFFF)
-    this.ram = new Uint8Array(0xc000);
+    // RAM from 0x4000: 48K reaches 0xFFFF
+    this.ram = new Uint8Array(ram * 1024);
+    this.ramLimit = RAM_BASE + this.ram.length;
 
     // 1K video RAM (0x3C00 - 0x3FFF)
     this.videoRam = new Uint8Array(0x400);
@@ -51,18 +95,19 @@ export class MemorySystem {
   }
 
   /**
-   * Load a ROM image: the real 14K (0x3800) Model III ROM, or a 16K
-   * (0x4000) padded image of it. Anything else is a wrong file — reject
-   * it rather than guessing.
+   * Load a ROM image of a size the model takes: the Model III's real 14K
+   * (0x3800) ROM or a 16K (0x4000) padded image of it; the Model I's 12K
+   * (0x3000) Level II ROM. Anything else is a wrong file — reject it
+   * rather than guessing.
    */
   loadROM(romData) {
     if (!romData || romData.length === 0) {
       throw new Error("ROM data is required");
     }
 
-    if (romData.length !== 0x3800 && romData.length !== 0x4000) {
+    if (!this.model.romSizes.includes(romData.length)) {
       throw new Error(
-        `Invalid ROM size: ${romData.length} bytes. Expected 14KB (0x3800) or a 16KB (0x4000) padded image`
+        `Invalid ROM size: ${romData.length} bytes. ${this.model.romSizeText}`
       );
     }
 
@@ -80,9 +125,16 @@ export class MemorySystem {
   readByte(address) {
     address = address & 0xffff;
 
-    if (address < ROM_LIMIT) {
+    if (address < this.romLimit) {
       return this.rom[address];
     }
+    if (address < KEYBOARD_BASE) {
+      // The Model I's 0x3000-0x37FF (models.js): the Expansion Interface, or nothing
+      if (address >= EXPANSION_BASE && address < EXPANSION_LIMIT && this.expansion !== null) {
+        return this.expansion.readExpansion(address);
+      }
+      return 0xff;
+    }
     if (address < KEYBOARD_LIMIT) {
       // Keyboard matrix: reading with no keys down yields 0x00
       return this.keyboard ? this.keyboard.read(address & 0xff) : 0x00;
@@ -90,26 +142,51 @@ export class MemorySystem {
     if (address < RAM_BASE) {
       return this.videoRam[address - KEYBOARD_LIMIT];
     }
-    return this.ram[address - RAM_BASE];
+    if (address < this.ramLimit) {
+      return this.ram[address - RAM_BASE];
+    }
+    return 0xff; // above the fitted RAM (models.js)
+  }
+
+  /**
+   * Read a byte as `readByte` does, without a device's read side effect: the
+   * Model I's Expansion Interface addresses are peeked (reading the interrupt
+   * latch at 0x37E0 does not clear it). For the debugger and `m.mem.read`.
+   */
+  peekByte(address) {
+    address = address & 0xffff;
+    if (address >= EXPANSION_BASE && address < EXPANSION_LIMIT && this.expansion !== null) {
+      return this.expansion.peekExpansion(address);
+    }
+    return this.readByte(address);
   }
 
   /**
    * Write a byte to memory
-   * ROM and the keyboard region ignore writes; video RAM and RAM accept them.
+   * ROM, the Model I's unmapped 0x3000-0x37FF, the keyboard region, and
+   * addresses above the fitted RAM ignore writes; video RAM and RAM accept them,
+   * and the Model I's Expansion Interface takes its own.
    */
   writeByte(address, value) {
     address = address & 0xffff;
     value = value & 0xff;
 
     if (address < KEYBOARD_LIMIT) {
-      return; // ROM / keyboard matrix: not writable
+      // ROM / keyboard matrix: not writable; the Model I's Expansion Interface
+      if (this.expansion !== null && address >= EXPANSION_BASE && address < EXPANSION_LIMIT) {
+        this.expansion.writeExpansion(address, value);
+      }
+      return;
     }
     if (address < RAM_BASE) {
+      if (this.videoBit6Gate) value = (value & 0xbf) | (value & 0xa0 ? 0 : 0x40);
       this.videoRam[address - KEYBOARD_LIMIT] = value;
       this.videoDirty = true;
       return;
     }
-    this.ram[address - RAM_BASE] = value;
+    if (address < this.ramLimit) {
+      this.ram[address - RAM_BASE] = value;
+    }
   }
 
   /**
@@ -198,10 +275,16 @@ export class MemorySystem {
    */
   getMemoryView() {
     const view = new Uint8Array(0x10000);
-    view.set(this.rom.subarray(0, ROM_LIMIT), 0);
-    // Keyboard region reads as idle (0x00) in the debug view
+    // Unmapped addresses read 0xFF; the keyboard region reads as idle (0x00) in the debug view
+    view.fill(0xff, this.romLimit, KEYBOARD_BASE);
+    view.fill(0xff, this.ramLimit);
+    view.set(this.rom.subarray(0, this.romLimit), 0);
     view.set(this.videoRam, KEYBOARD_LIMIT);
     view.set(this.ram, RAM_BASE);
+    // The Model I's Expansion Interface, peeked, as m.mem.read shows it
+    if (this.expansion !== null) {
+      for (let a = EXPANSION_BASE; a < EXPANSION_LIMIT; a++) view[a] = this.expansion.peekExpansion(a);
+    }
     return view;
   }
 }

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

@@ -1,14 +1,21 @@
 /**
- * Known Model III ROM images by SHA-256 (lowercase hex), so the Machine can report which ROM it
- * was given (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.
+ * 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 both: github.com/kiwisincebirth/TRS-80-ROMS, folder test-roms/, hashed locally
- * 2026-10-17. `Model3-RevC-2EF8.bin` is the stock Model III Rev C ROM (14,336 bytes) and the
- * image the repository's fugloy.mcp.json names as roms.model3; `Model3-RevC-FreHD.bin` is the
- * same ROM patched to boot a FreHD hard-disk emulator.
+ * 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/trs80-system.js

@@ -1,10 +1,14 @@
 /**
- * TRS-80 Model III System
+ * TRS-80 System, Model III or Model I
  *
  * Owns and wires the machine: Z80 CPU, memory map, I/O ports, and the
- * keyboard matrix. Runs the CPU in T-state-budgeted slices at the real
- * 2.02752 MHz clock and raises the 30 Hz RTC heartbeat interrupt the
- * ROM's clock/cursor services depend on.
+ * 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
@@ -13,17 +17,37 @@
 
 import { Z80CPU } from "../cpu/z80cpu.js";
 import { MemorySystem } from "./memory.js";
-import { IOSystem, MODE_32COL_BIT } from "./io.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";
 
-export const CPU_CLOCK_HZ = 2027520;
-export const RTC_HZ = 30;
+/** 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 {
-  constructor({ romData, log }) {
-    this.memory = new MemorySystem();
-    this.io = new IOSystem();
+  /**
+   * @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) {
@@ -47,9 +71,22 @@ export class TRS80System {
     // 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 = RTC_INTERVAL_TSTATES;
+    this.nextRtcAt = this.rtcInterval;
     this.reset();
   }
 
@@ -63,7 +100,7 @@ export class TRS80System {
     this.io.reset();
     this.keyboard.reset();
     this.memory.clearVideoRAM();
-    this.nextRtcAt = this.cpu.cycles + RTC_INTERVAL_TSTATES;
+    this.nextRtcAt = this.cpu.cycles + this.rtcInterval;
     this._nmiWasPending = false;
   }
 
@@ -98,44 +135,64 @@ export class TRS80System {
   stepInstruction(beforeExecute) {
     const start = this.cpu.cycles;
     if (this.cpu.cycles >= this.nextRtcAt) {
-      this.io.raiseRTC();
-      this.nextRtcAt += RTC_INTERVAL_TSTATES;
+      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
+    // 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) {
-      this.cpu.nmi();
+      if (this.cpu.nmi()) this._nmiWasPending = true;
+    } else {
+      this._nmiWasPending = nmiNow;
     }
-    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 and the disk controller does not tick: like the normal path,
-    // it never ticks for an interrupt response's T-states. The return value is those T-states.
-    const before = this.cpu.cycles;
-    if (beforeExecute !== undefined) {
-      const r = beforeExecute();
-      if (r === 'stop') {
-        return before - start;
+    // 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();
       }
-      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.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 (mode register bit 2,
-   * 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.
+   * 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 & MODE_32COL_BIT) !== 0;
+    return (this.io.modeRegister & this._mode32Bit) !== 0;
   }
 
   /** Mount a .dsk image (DiskImage) in drive 0-3. */
@@ -176,7 +233,7 @@ export class TRS80System {
 
   /** Convenience for tests: run N emulated seconds. */
   runSeconds(seconds) {
-    return this.runTStates(Math.round(seconds * CPU_CLOCK_HZ));
+    return this.runTStates(Math.round(seconds * this.clockHz));
   }
 
   /**