@fugloy/emu 0.0.0-stage → 0.3.0

package/src/machine/machine.js

@@ -0,0 +1,333 @@
+/**
+ * The spec §3 `Machine`: the public face of the emulator, over a TRS80System. It builds the
+ * Model III with 48K, or (emu phase 6) the Model I with 4, 16, 32, or 48K, as the model
+ * descriptions in models.js lay them out; execution, state access, ROM identification, the
+ * devices, the loaders, and the debugger live here.
+ */
+import { TRS80System } from './trs80-system.js';
+import { ROM_HASHES } from './rom-hashes.js';
+import { modelOf, ramProblem, romModelProblem } from './models.js';
+import { sha256Hex } from './sha256.js';
+import { Video } from '../devices/video.js';
+import { Sound } from '../devices/sound.js';
+import { loadBas } from '../loaders/bas.js';
+import { cassetteDeck, diskDrives, loadCas, loadCmd, loadDsk } from '../loaders/load.js';
+import { Debugger } from '../debug/debugger.js';
+import { KeyQueue, romKeyReturn } from '../devices/key-queue.js';
+
+/**
+ * @typedef {{ a: number, f: number, b: number, c: number, d: number, e: number, h: number, l: number,
+ *   a2: number, f2: number, b2: number, c2: number, d2: number, e2: number, h2: number, l2: number,
+ *   ix: number, iy: number, sp: number, pc: number, i: number, r: number,
+ *   iff1: boolean, iff2: boolean, im: number }} Regs
+ * @typedef {{ s: boolean, z: boolean, h: boolean, pv: boolean, n: boolean, c: boolean }} Flags
+ * @typedef {'halt' | ((m: Machine) => boolean)} Until
+ */
+
+export class Machine {
+  /** @type {TRS80System} The wrapped system: an escape hatch to the devices, outside the stable API. */
+  system;
+  /** @type {{ bytes: number, sha256: string, recognized: string | null }} */
+  rom;
+  /** @type {{ readonly regs: Regs, readonly flags: Flags }} */
+  cpu;
+  /** @type {{ read(addr: number, len: number): Uint8Array, write(addr: number, bytes: ArrayLike<number>): void, readonly ram: Uint8Array }} */
+  mem;
+  /** @type {{ in(port: number): number, out(port: number, value: number): void }} */
+  io;
+  /** @type {Video} The text readout of video RAM. */
+  video;
+  /** @type {Sound} Every port $FF write, raw and stamped in T-states. */
+  sound;
+  /** @type {KeyQueue} Key presses now, cycle-timed typing through the matrix, and the ROM keyboard-scan hook's feed. */
+  keyboard;
+  /**
+   * @type {{ bas(bytes: Uint8Array): ReturnType<typeof loadBas>, cmd(bytes: Uint8Array): ReturnType<typeof loadCmd>,
+   *   cas(bytes: Uint8Array, opts?: { baud?: 500 | 1500, via?: 'rom' | 'fast' }): ReturnType<typeof loadCas>,
+   *   dsk(bytes: Uint8Array, opts?: { drive?: number, boot?: boolean }): ReturnType<typeof loadDsk> }}
+   * Program loaders; each returns a manifest of where the bytes land and why.
+   */
+  load;
+  /** @type {ReturnType<typeof cassetteDeck>} The cassette deck: insert a .CAS at a baud, rewind, read the motor relay. */
+  cassette;
+  /** @type {ReturnType<typeof diskDrives>} The four floppy drives: mount a JV1, JV3, or DMK image, unmount, list what is in each, export one as DMK. */
+  fdc;
+  /** @type {Debugger} Breakpoints, watchpoints, hooks, coverage, the instruction trace, snapshots, labels, and the label file (spec §7, §8). */
+  debug;
+
+  /** True inside `run`, false inside `step`, which ignores breakpoints. */
+  #checkBreaks = false;
+  /** True until a run's first boundary has passed; that boundary is never checked, so a run resumes past a break. */
+  #firstBoundary = false;
+  /** @type {number | null} The PC where the last run stopped for a breakpoint: the next run's first boundary skips the check there only. */
+  #resumePc = null;
+  /** True while `step` or `run` executes, so a callback cannot re-enter either. */
+  #busy = false;
+  /** Set by the hook when a breakpoint held the boundary, read by `run`. */
+  #stopped = false;
+
+  /**
+   * @param {{ model?: 1 | 3, ram?: 4 | 16 | 32 | 48, roms: { level2: Uint8Array }, expansion?: boolean, lowercase?: boolean,
+   *   log?: (level: string, text: string) => void }} opts
+   *   `ram` defaults to 48 (the Model III takes only 48 for now); `expansion` (the Expansion Interface, default
+   *   true) and `lowercase` (the lowercase modification, default false) are Model I options
+   */
+  constructor({ model = 3, ram, roms, expansion, lowercase, log } = /** @type {any} */ ({})) {
+    const desc = modelOf(model);
+    const kb = ram ?? desc.defaultRam;
+    const badRam = ramProblem(desc, kb);
+    if (badRam !== null) throw new Error(badRam);
+    for (const [name, value] of /** @type {const} */ ([['expansion', expansion], ['lowercase', lowercase]])) {
+      if (value === undefined) continue;
+      if (desc.id !== 1) throw new Error(`${name} is a Model I option; the ${desc.name} has no ${name === 'expansion' ? 'Expansion Interface' : 'lowercase modification (its lowercase is built in)'}.`);
+      if (typeof value !== 'boolean') throw new Error(`${name} must be true or false, not ${String(value)}.`);
+    }
+    const level2 = roms?.level2;
+    if (!ArrayBuffer.isView(level2) || level2.BYTES_PER_ELEMENT !== 1) throw new Error('Machine needs roms.level2, the ROM image as a Uint8Array');
+
+    // A ROM recognised as the other model's is refused by name before its size is checked, so the
+    // sentence says which model it needs rather than only that its length is wrong.
+    const sha256 = sha256Hex(level2);
+    const recognized = ROM_HASHES[sha256] ?? null;
+    const problem = romModelProblem(recognized, desc.id);
+    if (problem !== null) throw new Error(problem);
+    this.system = new TRS80System({ romData: level2, log, model: desc, ram: kb, expansion: expansion ?? true, lowercase: lowercase ?? false });
+    this.rom = { bytes: level2.length, sha256, recognized };
+
+    const sys = this.system;
+    const cpu = sys.cpu;
+    this.cpu = {
+      get regs() {
+        const r = cpu.registers;
+        return {
+          a: r.A, f: r.F, b: r.B, c: r.C, d: r.D, e: r.E, h: r.H, l: r.L,
+          a2: r.A_, f2: r.F_, b2: r.B_, c2: r.C_, d2: r.D_, e2: r.E_, h2: r.H_, l2: r.L_,
+          ix: cpu.IX, iy: cpu.IY, sp: r.SP, pc: r.PC, i: r.I, r: r.R,
+          iff1: cpu.IFF1, iff2: cpu.IFF2, im: cpu.interruptMode,
+        };
+      },
+      get flags() {
+        const f = cpu.registers.F;
+        return { s: (f & 0x80) !== 0, z: (f & 0x40) !== 0, h: (f & 0x10) !== 0, pv: (f & 0x04) !== 0, n: (f & 0x02) !== 0, c: (f & 0x01) !== 0 };
+      },
+    };
+    this.mem = {
+      read(addr, len) {
+        const out = new Uint8Array(len);
+        // Peeked: reading the Model I's interrupt latch here does not clear it, as a CPU read would.
+        for (let k = 0; k < len; k++) out[k] = sys.memory.peekByte((addr + k) & 0xffff);
+        return out;
+      },
+      write(addr, bytes) {
+        for (let k = 0; k < bytes.length; k++) sys.memory.writeByte((addr + k) & 0xffff, bytes[k]);
+      },
+      get ram() {
+        return sys.memory.ram;
+      },
+    };
+    this.video = new Video(sys);
+    this.sound = new Sound();
+    sys.io.onSoundWrite = (cycle, value) => this.sound.record(cycle, value);
+    sys.io.onSoundReset = () => this.sound.clear();
+    this.keyboard = new KeyQueue(sys.keyboard, () => sys.cpu.cycles, sys.clockHz);
+    this.debug = new Debugger(this);
+    // Each load records its manifest and the bytes' hash for the label file (the last one wins).
+    const record = (/** @type {any} */ manifest, /** @type {Uint8Array} */ bytes) => {
+      this.debug.recordLoad(manifest, bytes);
+      return manifest;
+    };
+    this.load = {
+      bas: (bytes) => record(loadBas(this, bytes), bytes),
+      cmd: (bytes) => record(loadCmd(this, bytes), bytes),
+      cas: (bytes, opts) => record(loadCas(this, bytes, opts), bytes),
+      dsk: (bytes, opts) => record(loadDsk(this, bytes, opts), bytes),
+    };
+    this.cassette = cassetteDeck(this);
+    this.fdc = diskDrives(this);
+    this.io = {
+      in: (port) => sys.io.readPort(port),
+      out: (port, value) => sys.io.writePort(port, value),
+    };
+  }
+
+  /** @returns {1 | 3} The model built: 1 (the Model I) or 3 (the Model III). */
+  get model() {
+    return this.system.model.id;
+  }
+
+  /**
+   * The model's CPU clock in Hz: 2,027,520 on the Model III, 1,774,080 on the Model I (models.js).
+   * T-state counts (`cycles`, `run`'s budget, `m.sound` stamps) are in this clock's states.
+   * @returns {number}
+   */
+  get clockHz() {
+    return this.system.clockHz;
+  }
+
+  /** Total T-states since the last reset. */
+  get cycles() {
+    return this.system.cpu.cycles;
+  }
+
+  /** Hardware reset: CPU to $0000, cycle count to 0, RAM kept (TRS80System.reset). */
+  reset() {
+    this.system.reset();
+    this.#resumePc = null;
+    this.sound.clear();
+    this.keyboard.clear();
+  }
+
+  /**
+   * Internal: a restore starts a fresh timeline, so the PC where the last run stopped for a
+   * breakpoint is forgotten, and the key queue and sound ring (whose cycle stamps belong to the
+   * old timeline) are cleared.
+   */
+  newTimeline() {
+    this.#resumePc = null;
+    this.sound.clear();
+    this.keyboard.clear();
+  }
+
+  /**
+   * The internal per-instruction hook, run at every instruction boundary (after interrupt
+   * delivery, before the instruction executes) by both `step` and `run`: deliver the matrix key
+   * events now due, then, with a fed character waiting and the PC at the ROM's keyboard scan
+   * ($002B) or wait-for-key ($0049), return from that routine with the character as the ROM
+   * would (spec §6, "Keyboard-scan hook"). The Model I Level II ROM has the same two entries with
+   * the same contract (romKeyReturn), so the hook serves both models. That return stands in for
+   * the boundary's instruction, as one RET (10 T-states); a halted CPU idles instead, as it does
+   * for any instruction, so the next boundary is at the caller's return address.
+   * Between draining and the keyboard hook, a breakpoint hit (only while `debug.active`, and
+   * never in `step`) stops the boundary: nothing executes. Last, with memory accesses watched or
+   * hooked, the debugger is told an instruction starts at PC, so its fetches are not taken for
+   * reads and its accesses carry its PC; the keyboard hook's stand-in and a halted CPU's idle
+   * start none (the idle reads nothing; the stand-in's stack reads carry the CPU's PC).
+   * @returns {boolean | 'stop'} true when the hook stood in for the instruction, 'stop' when a breakpoint holds the boundary
+   */
+  #beforeInstruction() {
+    const cpu = this.system.cpu;
+    const kb = this.keyboard;
+    if (cpu.cycles >= kb.nextAt) kb.drain(cpu.cycles);
+    // A run's first boundary skips the check only at the PC its predecessor stopped at; a halted
+    // CPU idles at HALT+1 on every boundary, so it is never checked.
+    const pc = cpu.registers.PC;
+    const first = this.#firstBoundary && pc === this.#resumePc;
+    this.#firstBoundary = false;
+    this.#resumePc = null;
+    if (this.debug.active && this.#checkBreaks && !cpu.halted && this.debug.beforeInstruction(pc, first)) {
+      this.#stopped = true;
+      this.#resumePc = pc;
+      return 'stop';
+    }
+    if (cpu.halted) return false;
+    if (kb.hasFeed && (pc === 0x002b || pc === 0x0049)) {
+      const debug = this.debug;
+      if (debug.tracksAccess) {
+        debug.standIn(true);
+        try {
+          romKeyReturn(cpu, pc, kb.takeFeed());
+        } finally {
+          debug.standIn(false);
+        }
+      } else romKeyReturn(cpu, pc, kb.takeFeed());
+      return true;
+    }
+    if (this.debug.startsInstruction) this.debug.startInstruction(pc);
+    return false;
+  }
+
+  /** Bound once, so the hot loop passes the same function every instruction. */
+  #hook = () => this.#beforeInstruction();
+
+  /**
+   * Execute `n` whole instructions (an interrupt response counts with the instruction after it).
+   * @param {number} [n]
+   * @returns {{ cycles: number, halted: boolean }}
+   */
+  step(n = 1) {
+    const sys = this.system;
+    const start = sys.cpu.cycles;
+    const debug = this.debug;
+    if (this.#busy) throw new Error('step: the machine is already running; step and run cannot be called from a when or until callback');
+    this.#busy = true;
+    this.#checkBreaks = false;
+    try {
+      for (let k = 0; k < n; k++) {
+        sys.stepInstruction(this.#hook);
+        if (debug.active) debug.afterInstruction();
+      }
+    } catch (e) {
+      // A hook or callback that threw leaves no instruction open, no edge recorded for it, and no stop pending for the next call.
+      if (debug.active) {
+        debug.endInstruction();
+        debug.afterInstruction();
+      }
+      throw e;
+    } finally {
+      this.#busy = false;
+    }
+    return { cycles: sys.cpu.cycles - start, halted: sys.cpu.halted };
+  }
+
+  /**
+   * Run until a T-state budget is spent or a condition holds, both checked after each
+   * instruction; at least one instruction always runs. The condition wins a tie with the budget.
+   * A breakpoint stops the run before its instruction executes, and the next run starts past it
+   * (only at that PC, so hit counts do not depend on how a session is split into runs). A
+   * breakpoint at a run's first boundary that it did not just stop at stops with `cycles: 0`
+   * (an interrupt response at that boundary counts). Breakpoints are not checked while halted.
+   * A watch with `stop` returns after the instruction whose access hit it; after an instruction
+   * the order is watch stop, then `until`, then the budget. `step` logs watch hits but never stops.
+   * A stop watch hit by an interrupt response at a boundary a breakpoint then holds stays pending:
+   * the next run returns `'watch'` after the held instruction (a `step` in between drops it).
+   * @param {{ cycles?: number, until?: Until }} opts
+   * @returns {{ reason: 'cycles' | 'halt' | 'predicate', cycles: number } | { reason: 'break' | 'watch', id: number, cycles: number }}
+   */
+  run({ cycles, until } = {}) {
+    if (cycles === undefined && until === undefined) throw new Error('run needs cycles, until, or both; with neither it would never stop');
+    if (cycles !== undefined && !(Number.isFinite(cycles) && cycles >= 0)) throw new Error(`run: cycles must be a finite number of T-states, 0 or more, not ${String(cycles)}`);
+    if (until !== undefined && until !== 'halt' && typeof until !== 'function') throw new Error(`run: until must be 'halt' or a function, not ${String(until)}`);
+    const sys = this.system;
+    const cpu = sys.cpu;
+    const start = cpu.cycles;
+    const target = cycles === undefined ? Infinity : start + cycles;
+    const debug = this.debug;
+    if (this.#busy) throw new Error('run: the machine is already running; step and run cannot be called from a when or until callback');
+    this.#busy = true;
+    this.#checkBreaks = true;
+    this.#firstBoundary = true;
+    this.#stopped = false;
+    try {
+      for (;;) {
+        sys.stepInstruction(this.#hook);
+        if (this.#stopped) {
+          this.#stopped = false;
+          // A watch stop from this boundary's interrupt response stays pending: the next run returns it after the held instruction.
+          debug.endInstruction();
+          const id = /** @type {number} */ (debug.stopId);
+          debug.stopId = null;
+          return { reason: 'break', id, cycles: cpu.cycles - start };
+        }
+        if (debug.active) {
+          const w = debug.afterInstruction();
+          if (w !== null) return { reason: 'watch', id: w, cycles: cpu.cycles - start };
+        }
+        if (until === 'halt') {
+          if (cpu.halted) return { reason: 'halt', cycles: cpu.cycles - start };
+        } else if (until !== undefined && until(this)) {
+          return { reason: 'predicate', cycles: cpu.cycles - start };
+        }
+        if (cpu.cycles >= target) return { reason: 'cycles', cycles: cpu.cycles - start };
+      }
+    } catch (e) {
+      // A hook or callback that threw leaves no instruction open, no edge recorded for it, and no stop pending for the next call.
+      if (debug.active) {
+        debug.endInstruction();
+        debug.afterInstruction();
+      }
+      throw e;
+    } finally {
+      this.#busy = false;
+    }
+  }
+}

package/src/machine/memory.js

@@ -0,0 +1,290 @@
+/**
+ * TRS-80 memory map, by model (src/machine/models.js holds the sources for the Model I facts):
+ *
+ *   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.
+ */
+
+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 {
+  /**
+   * @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 up to the model's ROM top is ever mapped as ROM.
+    this.rom = new Uint8Array(0x4000);
+    this.romLimit = model.romTop;
+
+    // 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);
+
+    // Set on every video RAM write so the renderer can skip idle frames
+    this.videoDirty = false;
+
+    // Keyboard matrix peripheral: { read(addrLow8) -> row bits } or null
+    this.keyboard = null;
+
+    this.romLoaded = false;
+
+    // Kept for API compatibility with existing callers
+    this.VIDEO_RAM_START = 0x3c00;
+    this.VIDEO_RAM_END = 0x3fff;
+  }
+
+  /**
+   * Get memory statistics
+   */
+  getStats() {
+    return {
+      romSize: this.rom.length,
+      ramSize: this.ram.length,
+      totalSize: this.rom.length + this.ram.length,
+      romLoaded: this.romLoaded,
+    };
+  }
+
+  /**
+   * 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 (!this.model.romSizes.includes(romData.length)) {
+      throw new Error(
+        `Invalid ROM size: ${romData.length} bytes. ${this.model.romSizeText}`
+      );
+    }
+
+    this.rom.fill(0);
+    this.rom.set(romData, 0);
+
+    this.romLoaded = true;
+    return true;
+  }
+
+  /**
+   * Read a byte from memory
+   * Addresses are masked to 16 bits (0x0000 - 0xFFFF)
+   */
+  readByte(address) {
+    address = address & 0xffff;
+
+    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;
+    }
+    if (address < RAM_BASE) {
+      return this.videoRam[address - KEYBOARD_LIMIT];
+    }
+    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, 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) {
+      // 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;
+    }
+    if (address < this.ramLimit) {
+      this.ram[address - RAM_BASE] = value;
+    }
+  }
+
+  /**
+   * Read a 16-bit word (little-endian)
+   */
+  readWord(address) {
+    address = address & 0xffff;
+    const low = this.readByte(address);
+    const high = this.readByte((address + 1) & 0xffff);
+    return (high << 8) | low;
+  }
+
+  /**
+   * Write a 16-bit word (little-endian)
+   */
+  writeWord(address, value) {
+    address = address & 0xffff;
+    value = value & 0xffff;
+    const low = value & 0xff;
+    const high = (value >> 8) & 0xff;
+    this.writeByte(address, low);
+    this.writeByte((address + 1) & 0xffff, high);
+  }
+
+  /**
+   * Load a program into RAM
+   * @param {Uint8Array|Array} program - Program data
+   * @param {number} address - Load address (default: 0x4200)
+   * @returns {number} The address where the program was loaded
+   */
+  loadProgram(program, address = 0x4200) {
+    if (!program || program.length === 0) {
+      return address;
+    }
+
+    // Convert to Uint8Array if needed
+    let programData;
+    if (program instanceof Uint8Array) {
+      programData = program;
+    } else if (Array.isArray(program)) {
+      programData = new Uint8Array(program);
+    } else {
+      throw new Error("Program must be Uint8Array or Array");
+    }
+
+    address = address & 0xffff;
+
+    // Check if program fits in memory
+    if (address < RAM_BASE) {
+      throw new Error("Cannot load program into ROM area");
+    }
+
+    const endAddress = (address + programData.length - 1) & 0xffff;
+    if (endAddress < address) {
+      // Wrapped around - program too large
+      throw new Error("Program exceeds available memory");
+    }
+
+    // Load program into RAM
+    for (let i = 0; i < programData.length; i++) {
+      const addr = (address + i) & 0xffff;
+      this.writeByte(addr, programData[i]);
+    }
+
+    return address;
+  }
+
+  /**
+   * Clear all RAM (set to 0x00)
+   */
+  clearRAM() {
+    this.ram.fill(0);
+  }
+
+  /**
+   * Clear video RAM to spaces (what the ROM's CLS leaves behind)
+   */
+  clearVideoRAM() {
+    this.videoRam.fill(0x20);
+    this.videoDirty = true;
+  }
+
+  /**
+   * Get a view of the entire memory space (for debugging)
+   * Returns a Uint8Array representing the full 64K address space
+   */
+  getMemoryView() {
+    const view = new Uint8Array(0x10000);
+    // 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;
+  }
+}