@zx-vibes/machine 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Alvaro Mateos
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,41 @@
+# @zx-vibes/machine
+
+48K ZX Spectrum machine layer for the zx-vibes toolchain.
+
+Current package version in this repository: `0.1.0`.
+
+Joins `@zx-vibes/cpu` and `@zx-vibes/ula` into a runnable 48K machine with
+interrupt acceptance, per-access memory contention, `.z80` snapshot
+read/write, `.tap`/`.tzx` parsing and serialization, and tape loading (edge
+and instant). It is regenerated from the project DNA and decided by the
+machine conformance fixtures. This is the core the `@zx-vibes/toolkit` CLI
+and MCP server run on.
+
+## Usage
+
+```js
+import { createMachine, readZ80, writeZ80, parseTap } from "@zx-vibes/machine";
+
+// memory is a caller-provided 64 KB address space with the 16 KB 48K ROM
+// mapped at 0x0000 (the ROM is not bundled with this package)
+const machine = createMachine({ memory });
+machine.runFrame();
+machine.stepInstruction();
+```
+
+`@zx-vibes/machine/interrupt` and `@zx-vibes/machine/machine` expose those
+modules directly. Type declarations are generated from the source JSDoc
+(`.d.mts` alongside each module).
+
+The package does not ship the ZX Spectrum ROM; supply your own copy (the
+toolkit ships one under its Amstrad redistribution notice).
+
+## Testing
+
+Tests are repo-only: the package is exercised by the `dna/conformance` fixture
+suites in the [zx-vibes monorepo](https://github.com/Alvaromah/zx-vibes)
+(`npm test` inside a published tarball is unsupported).
+
+## License
+
+MIT. See `LICENSE`.

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@zx-vibes/machine",
+  "version": "0.1.0",
+  "description": "Regenerated 48K ZX Spectrum machine layer for zx-vibes: joins @zx-vibes/cpu and @zx-vibes/ula with interrupt acceptance and per-access memory contention, derived from the DNA and decided by the machine conformance fixtures.",
+  "license": "MIT",
+  "author": "Alvaro Mateos",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Alvaromah/zx-vibes.git",
+    "directory": "packages/machine"
+  },
+  "homepage": "https://github.com/Alvaromah/zx-vibes#readme",
+  "bugs": {
+    "url": "https://github.com/Alvaromah/zx-vibes/issues"
+  },
+  "keywords": [
+    "zx-spectrum",
+    "z80",
+    "emulator",
+    "emulation",
+    "snapshot",
+    "tape"
+  ],
+  "type": "module",
+  "engines": {
+    "node": ">=20"
+  },
+  "main": "src/index.mjs",
+  "types": "src/index.d.mts",
+  "exports": {
+    ".": {
+      "types": "./src/index.d.mts",
+      "default": "./src/index.mjs"
+    },
+    "./interrupt": {
+      "types": "./src/interrupt.d.mts",
+      "default": "./src/interrupt.mjs"
+    },
+    "./machine": {
+      "types": "./src/machine.d.mts",
+      "default": "./src/machine.mjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "src",
+    "README.md"
+  ],
+  "dependencies": {
+    "@zx-vibes/cpu": "0.1.0",
+    "@zx-vibes/ula": "0.1.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "test": "node ../../dna/conformance/machine/run-machine-fixtures.mjs",
+    "lint": "eslint src",
+    "types:gen": "tsc src/index.mjs --allowJs --declaration --emitDeclarationOnly --outDir src"
+  }
+}

package/src/index.d.mts

@@ -0,0 +1,8 @@
+export { Machine, createMachine, RESET_REGISTERS } from "./machine.mjs";
+export { acceptInterrupt, acceptNmi, INT_DATA_BUS, IM01_T_STATES, IM2_T_STATES, NMI_VECTOR, NMI_T_STATES } from "./interrupt.mjs";
+export { readZ80, writeZ80, compressZ80, decompressZ80 } from "./snapshot-z80.mjs";
+export { tapChecksum, parseTap, serializeTap } from "./tap-format.mjs";
+export { parseTzx, serializeTzx, TZX_SIGNATURE, TZX_VERSION } from "./tzx-format.mjs";
+export { blockToPulses, bytePulses, PILOT_PULSE_T, PILOT_PULSES_HEADER, PILOT_PULSES_DATA, SYNC1_T, SYNC2_T, BIT0_PULSE_T, BIT1_PULSE_T } from "./tape-pulses.mjs";
+export { createTapeDeck, edgeLoad, edgeLoadWithDeck, instantLoad, LD_BYTES_ENTRY } from "./tape-edge-load.mjs";
+export { displayByteAddress, displayLineAddress, attributeAddress, DISPLAY_FILE_BASE, DISPLAY_FILE_END, DISPLAY_FILE_SIZE, ATTR_FILE_BASE, ATTR_FILE_END, ATTR_FILE_SIZE, portFloats, floatingBusByte, activeDisplayFetch, FLOATING_BUS_IDLE, kempstonByte, kempstonDecodes, KEMPSTON_PORT, KEMPSTON_RIGHT, KEMPSTON_LEFT, KEMPSTON_DOWN, KEMPSTON_UP, KEMPSTON_FIRE } from "@zx-vibes/ula";

package/src/index.mjs

@@ -0,0 +1,79 @@
+// @zx-vibes/machine — regenerated 48K ZX Spectrum machine layer.
+//
+// Joins the regenerated CPU (@zx-vibes/cpu) and ULA timing model (@zx-vibes/ula)
+// into a running machine: interrupt acceptance at instruction boundaries and
+// per-access memory contention threaded onto the executed stream. Authored from
+// the project DNA (dna/domain/machine-execution.md) and decided by the machine
+// conformance fixtures (dna/conformance/machine/*.json).
+export { Machine, createMachine, RESET_REGISTERS } from "./machine.mjs";
+export { acceptInterrupt, acceptNmi, INT_DATA_BUS, IM01_T_STATES, IM2_T_STATES, NMI_VECTOR, NMI_T_STATES } from "./interrupt.mjs";
+export { readZ80, writeZ80, compressZ80, decompressZ80 } from "./snapshot-z80.mjs";
+// `.tap` tape-image codec (dna/domain/file-formats.md FMT-TAP-*) — tape, like a
+// snapshot, is a file the machine loads, so it lives beside the .z80 codec.
+export { tapChecksum, parseTap, serializeTap } from "./tap-format.mjs";
+// `.tzx` tape-image codec (dna/domain/file-formats.md FMT-TZX-*) — the versioned,
+// pulse-level tape archive, beside the .tap codec.
+export { parseTzx, serializeTzx, TZX_SIGNATURE, TZX_VERSION } from "./tzx-format.mjs";
+// ROM tape encoding (dna/domain/tape-loading.md TAPE-PULSE-*) — a block body becomes
+// the EAR pulse stream (pilot/sync/bit pulses) the real ROM LD-BYTES reads.
+export {
+  blockToPulses,
+  bytePulses,
+  PILOT_PULSE_T,
+  PILOT_PULSES_HEADER,
+  PILOT_PULSES_DATA,
+  SYNC1_T,
+  SYNC2_T,
+  BIT0_PULSE_T,
+  BIT1_PULSE_T,
+} from "./tape-pulses.mjs";
+// ROM tape edge-loading (dna/domain/tape-loading.md "Edge loading" TAPE-EDGE-*) — the
+// opaque ROM LD-BYTES (0x0556) consumes the EAR pulse stream on port 0xFE b6 and loads a
+// block byte-for-byte into RAM. The tape deck implements the machine io contract.
+// `instantLoad` is the instant/trap counterpart: it reproduces the same observable result
+// without running the ROM (its correctness is `instant == edge` for the same block).
+export {
+  createTapeDeck,
+  edgeLoad,
+  edgeLoadWithDeck,
+  instantLoad,
+  LD_BYTES_ENTRY,
+} from "./tape-edge-load.mjs";
+// Screen-address decode lives in @zx-vibes/ula; re-export it from the integrated
+// machine entry so a machine consumer can map a screen pixel to its display/attribute
+// byte (dna/domain/memory-map.md, MM-SCREEN-ADDR-001 / MM-ATTR-ADDR-001).
+export {
+  displayByteAddress,
+  displayLineAddress,
+  attributeAddress,
+  DISPLAY_FILE_BASE,
+  DISPLAY_FILE_END,
+  DISPLAY_FILE_SIZE,
+  ATTR_FILE_BASE,
+  ATTR_FILE_END,
+  ATTR_FILE_SIZE,
+} from "@zx-vibes/ula";
+// Floating-bus read model also lives in @zx-vibes/ula; re-export it from the
+// integrated machine entry so a machine consumer can resolve an IN from an
+// undriven (odd) port (dna/domain/ula-timing.md "Floating bus", ULA-FLOATBUS-*;
+// scoped per ADR-0026 — the in-window byte is deferred with A5, never fabricated).
+export {
+  portFloats,
+  floatingBusByte,
+  activeDisplayFetch,
+  FLOATING_BUS_IDLE,
+} from "@zx-vibes/ula";
+// Kempston joystick read model also lives in @zx-vibes/ula (beside the floating-bus
+// model — the Kempston is what carves port 0x1F out of the floating odd-port set);
+// re-export it from the integrated machine entry so a machine consumer can resolve an
+// IN from the joystick port (dna/domain/peripherals.md, JOY-KEMPSTON-*; ADR-0021).
+export {
+  kempstonByte,
+  kempstonDecodes,
+  KEMPSTON_PORT,
+  KEMPSTON_RIGHT,
+  KEMPSTON_LEFT,
+  KEMPSTON_DOWN,
+  KEMPSTON_UP,
+  KEMPSTON_FIRE,
+} from "@zx-vibes/ula";

package/src/interrupt.d.mts

@@ -0,0 +1,26 @@
+export function acceptInterrupt({ registers, memory, halted, dataBus }: {
+    registers: any;
+    memory: any;
+    halted?: boolean;
+    dataBus?: number;
+}): {
+    registers: any;
+    tStates: number;
+    accepted: boolean;
+    halted: boolean;
+};
+export function acceptNmi({ registers, memory, halted }: {
+    registers: any;
+    memory: any;
+    halted?: boolean;
+}): {
+    registers: any;
+    tStates: number;
+    accepted: boolean;
+    halted: boolean;
+};
+export const INT_DATA_BUS: 255;
+export const IM01_T_STATES: 13;
+export const IM2_T_STATES: 19;
+export const NMI_VECTOR: 102;
+export const NMI_T_STATES: 11;

package/src/interrupt.mjs

@@ -0,0 +1,111 @@
+// Maskable interrupt acceptance for the 48K ZX Spectrum machine layer, authored
+// from the project DNA (dna/domain/machine-execution.md) and decided by the
+// machine conformance fixtures (dna/conformance/machine/interrupt-accept.json).
+//
+// This is the CPU's response to the ULA's once-per-frame INT, the part that lives
+// at an instruction boundary and so is not expressible by the single-step CPU
+// contract. The caller (the Machine frame loop) decides *whether* to accept
+// (IFF1 set, INT asserted, not in the post-EI delay); this function performs the
+// documented sequence once that decision is made.
+
+// 48K interrupt-acknowledge data-bus value (floats high). Pins IM 0 to RST 38h
+// and the IM 2 vector low byte to 0xFF. (MACHINE-INT-DATABUS-001, ADR-0011.)
+export const INT_DATA_BUS = 0xff;
+
+// Total instruction-acknowledge cost: IM 0 / IM 1 take 13 T, IM 2 takes 19 T.
+export const IM01_T_STATES = 13;
+export const IM2_T_STATES = 19;
+
+// Non-maskable interrupt: fixed restart vector 0x0066, 11 T-states (a 5 T
+// acknowledge M1 cycle plus the two 3 T stack writes). (MACHINE-NMI-ACCEPT-001.)
+export const NMI_VECTOR = 0x0066;
+export const NMI_T_STATES = 11;
+
+// Accept a maskable interrupt against the given CPU state.
+//
+//   acceptInterrupt({ registers, memory, halted?, dataBus? })
+//     -> { registers, tStates, accepted, halted }
+//
+// registers: the same plain register object the CPU step() uses (a,f,...,pc,sp,
+//   i,r,iff1,iff2,im,...). memory: Uint8Array(0x10000). halted: whether the CPU
+//   was in the HALT state at the boundary (so the return address skips the HALT).
+//   dataBus: the byte on the data bus during acknowledge (default 0xFF on 48K).
+//
+// Mutates and returns `registers` (clearing IFF1/IFF2, bumping R, moving SP/PC)
+// and writes the pushed return address into `memory`. If IFF1 is clear the
+// interrupt is masked: nothing changes, accepted=false, tStates=0.
+export function acceptInterrupt({ registers, memory, halted = false, dataBus = INT_DATA_BUS }) {
+  const reg = registers;
+  if (!reg.iff1) {
+    return { registers: reg, tStates: 0, accepted: false, halted };
+  }
+
+  // Leaving HALT: the frozen PC sits on the HALT opcode, so the return address is
+  // the instruction after it. (MACHINE-INT-ACCEPT-001 step 1.)
+  let pc = reg.pc & 0xffff;
+  if (halted) pc = (pc + 1) & 0xffff;
+
+  // Disable further interrupts; the acknowledge cycle bumps R (low 7 bits).
+  reg.iff1 = 0;
+  reg.iff2 = 0;
+  reg.r = (reg.r & 0x80) | ((reg.r + 1) & 0x7f);
+
+  // Push the return address, high byte first.
+  const sp = (reg.sp - 2) & 0xffff;
+  memory[sp] = pc & 0xff;
+  memory[(sp + 1) & 0xffff] = (pc >> 8) & 0xff;
+  reg.sp = sp;
+
+  let tStates;
+  if (reg.im === 2) {
+    const vector = ((reg.i & 0xff) << 8) | (dataBus & 0xff);
+    reg.pc = (memory[vector & 0xffff] | (memory[(vector + 1) & 0xffff] << 8)) & 0xffff;
+    tStates = IM2_T_STATES;
+  } else {
+    // IM 0 (data bus = 0xFF = RST 38h on 48K) and IM 1 both vector to 0x0038.
+    reg.pc = 0x0038;
+    tStates = IM01_T_STATES;
+  }
+
+  return { registers: reg, tStates, accepted: true, halted: false };
+}
+
+// Accept a non-maskable interrupt against the given CPU state.
+//
+//   acceptNmi({ registers, memory, halted? })
+//     -> { registers, tStates, accepted, halted }
+//
+// NMI is edge-triggered and NON-maskable: unlike acceptInterrupt it ignores
+// IFF1, so it always accepts (there is no masked no-accept case). It clears IFF1
+// but PRESERVES IFF2 (which holds the pre-NMI IFF1, so a later RETN restores the
+// maskable-interrupt enable state), bumps R, leaves HALT with the post-HALT
+// return address, pushes PC high-byte first, and vectors to 0x0066 in 11 T.
+// (dna/domain/machine-execution.md MACHINE-NMI-SAMPLE-001 / -ACCEPT-001 /
+// -RETN-001; decided by dna/conformance/machine/nmi-accept.json.)
+//
+// Mutates and returns `registers` (clearing IFF1, bumping R, moving SP/PC) and
+// writes the pushed return address into `memory`; IFF2 and IM are untouched.
+export function acceptNmi({ registers, memory, halted = false }) {
+  const reg = registers;
+
+  // Leaving HALT: the frozen PC sits on the HALT opcode, so the return address is
+  // the instruction after it. (MACHINE-NMI-ACCEPT-001 step 1.)
+  let pc = reg.pc & 0xffff;
+  if (halted) pc = (pc + 1) & 0xffff;
+
+  // Disable maskable interrupts but PRESERVE IFF2 (so RETN can restore IFF1);
+  // the acknowledge cycle bumps R (low 7 bits).
+  reg.iff1 = 0;
+  reg.r = (reg.r & 0x80) | ((reg.r + 1) & 0x7f);
+
+  // Push the return address, high byte first.
+  const sp = (reg.sp - 2) & 0xffff;
+  memory[sp] = pc & 0xff;
+  memory[(sp + 1) & 0xffff] = (pc >> 8) & 0xff;
+  reg.sp = sp;
+
+  // Fixed NMI restart vector.
+  reg.pc = NMI_VECTOR;
+
+  return { registers: reg, tStates: NMI_T_STATES, accepted: true, halted: false };
+}

package/src/machine.d.mts

@@ -0,0 +1,82 @@
+export function createMachine(options?: {}): Machine;
+export const RESET_REGISTERS: Readonly<{
+    a: 255;
+    f: 255;
+    b: 255;
+    c: 255;
+    d: 255;
+    e: 255;
+    h: 255;
+    l: 255;
+    a_: 255;
+    f_: 255;
+    b_: 255;
+    c_: 255;
+    d_: 255;
+    e_: 255;
+    h_: 255;
+    l_: 255;
+    pc: 0;
+    sp: 65535;
+    i: 0;
+    r: 0;
+    iff1: 0;
+    iff2: 0;
+    im: 0;
+    memptr: 0;
+    ixh: 255;
+    ixl: 255;
+    iyh: 255;
+    iyl: 255;
+}>;
+export class Machine {
+    constructor({ registers, memory, io, clock, exactContention }?: {
+        clock?: number;
+        exactContention?: boolean;
+    });
+    registers: {};
+    memory: Uint8Array<ArrayBuffer>;
+    io: any;
+    clock: number;
+    exactContention: boolean;
+    halted: boolean;
+    eiDelay: number;
+    tStatesTotal: number;
+    frames: number;
+    reset(): this;
+    _contentionClock(instructionStart: any): {
+        base: any;
+        extra: number;
+        access(address: any): void;
+    };
+    _exactClock(instructionStart: any): {
+        base: any;
+        runT: number;
+        extra: number;
+        perAccessExtra: number;
+        incomplete: boolean;
+        access(address: any): void;
+        mcycle(address: any, tStates: any): void;
+        internal(address: any, n: any): void;
+        inexact(): void;
+        total(): number;
+    };
+    stepInstruction(): {
+        tStates: any;
+        contention: any;
+        halted: boolean;
+    };
+    _acceptInterrupt(dataBus?: number): {
+        registers: any;
+        tStates: number;
+        accepted: boolean;
+        halted: boolean;
+    };
+    _interruptArmed(): boolean;
+    runFrame({ dataBus }?: {
+        dataBus?: number;
+    }): {
+        tStates: number;
+        accepted: number;
+    };
+}

package/src/machine.mjs

@@ -0,0 +1,242 @@
+// 48K ZX Spectrum machine layer, authored from the project DNA
+// (dna/domain/machine-execution.md) and decided by the machine conformance
+// fixtures (dna/conformance/machine/*.json). It joins the regenerated CPU
+// (@zx-vibes/cpu step()) and ULA timing model (@zx-vibes/ula) into a running
+// machine: a register file + 64 KB memory + I/O ports + a frame T-state clock,
+// with per-access memory contention threaded onto the executed instruction
+// stream and the once-per-frame maskable interrupt accepted at instruction
+// boundaries.
+import { step } from "@zx-vibes/cpu";
+import { FRAME_T_STATES, contentionDelay, interruptActive, isContendedAddress } from "@zx-vibes/ula";
+import { INT_DATA_BUS, acceptInterrupt } from "./interrupt.mjs";
+
+// The register fields the CPU step() contract recognizes, all defaulting to 0.
+const REGISTER_NAMES = [
+  "a", "f", "b", "c", "d", "e", "h", "l",
+  "a_", "f_", "b_", "c_", "d_", "e_", "h_", "l_",
+  "pc", "sp", "i", "r", "iff1", "iff2", "im", "memptr",
+  "ixh", "ixl", "iyh", "iyl",
+];
+
+const HALT_OPCODE = 0x76;
+const EI_OPCODE = 0xfb;
+
+// Power-on / reset register state (dna/domain/machine-execution.md
+// MACHINE-RESET-CONTROL-001 + MACHINE-RESET-REGISTERS-001). The Z80 RESET defines
+// only PC/I/R = 0, IM 0, IFF1 = IFF2 = 0 (z80-spec); SP/AF and the GP/alternate/index
+// registers are undefined and modeled as all-bits-set (0xFF halves -> 0xFFFF pairs)
+// per decision:ADR-0021. Stored in the same 8-bit-half representation as the register
+// file. MEMPTR is not part of the reset contract.
+export const RESET_REGISTERS = Object.freeze({
+  a: 0xff, f: 0xff, b: 0xff, c: 0xff, d: 0xff, e: 0xff, h: 0xff, l: 0xff,
+  a_: 0xff, f_: 0xff, b_: 0xff, c_: 0xff, d_: 0xff, e_: 0xff, h_: 0xff, l_: 0xff,
+  pc: 0x0000, sp: 0xffff, i: 0x00, r: 0x00, iff1: 0, iff2: 0, im: 0, memptr: 0,
+  ixh: 0xff, ixl: 0xff, iyh: 0xff, iyl: 0xff,
+});
+
+function buildRegisters(initial = {}) {
+  const reg = {};
+  for (const name of REGISTER_NAMES) reg[name] = 0;
+  for (const [name, value] of Object.entries(initial)) {
+    if (REGISTER_NAMES.includes(name)) reg[name] = value | 0;
+  }
+  return reg;
+}
+
+function buildMemory(initial) {
+  if (initial instanceof Uint8Array) return initial;
+  const memory = new Uint8Array(0x10000);
+  if (initial && typeof initial === "object") {
+    for (const [address, bytes] of Object.entries(initial)) {
+      let pointer = Number(address) & 0xffff;
+      const data = bytes instanceof Uint8Array ? bytes : Uint8Array.from(bytes);
+      for (const byte of data) { memory[pointer & 0xffff] = byte & 0xff; pointer += 1; }
+    }
+  }
+  return memory;
+}
+
+// A default I/O interface: reads float high (0xFF), writes are dropped. The
+// caller can supply its own { read(port), write(port, value) }.
+function defaultIo() {
+  return { read: () => 0xff, write: () => {} };
+}
+
+export function createMachine(options = {}) {
+  return new Machine(options);
+}
+
+export class Machine {
+  constructor({ registers, memory, io, clock = 0, exactContention = false } = {}) {
+    this.registers = buildRegisters(registers);
+    this.memory = buildMemory(memory);
+    this.io = io ?? defaultIo();
+    this.clock = ((clock % FRAME_T_STATES) + FRAME_T_STATES) % FRAME_T_STATES;
+    // Contention model: the conformed per-access model (default,
+    // MACHINE-CONTENTION-CLOCK-001) or the M-cycle-exact model
+    // (MACHINE-CONTENTION-MCYCLE-001), which also charges internal no-MREQ cycles
+    // and samples each access at its true in-instruction T-offset.
+    this.exactContention = Boolean(exactContention);
+    this.halted = false;
+    // Boundaries to skip interrupt sampling for (the post-EI one-instruction
+    // delay, MACHINE-INT-EI-DELAY-001).
+    this.eiDelay = 0;
+    // Running totals (across frames), useful for drivers and assertions.
+    this.tStatesTotal = 0;
+    this.frames = 0;
+  }
+
+  // Power-on / reset: restore the documented reset state (MACHINE-RESET-001) —
+  // the Z80 control registers cleared, the rest of the register file all-bits-set,
+  // RAM all-zero, the frame clock at 0, and not halted. Run totals are cleared too.
+  reset() {
+    this.registers = { ...RESET_REGISTERS };
+    this.memory = new Uint8Array(0x10000);
+    this.clock = 0;
+    this.halted = false;
+    this.eiDelay = 0;
+    this.tStatesTotal = 0;
+    this.frames = 0;
+    return this;
+  }
+
+  // The contention observer handed to step(): it accumulates the ULA delay for
+  // each contended memory access, sampling at (instructionStart + accumulated)
+  // per MACHINE-CONTENTION-CLOCK-001.
+  _contentionClock(instructionStart) {
+    const clock = {
+      base: instructionStart,
+      extra: 0,
+      access(address) {
+        if (isContendedAddress(address)) {
+          const t = (this.base + this.extra) % FRAME_T_STATES;
+          this.extra += contentionDelay(t);
+        }
+      },
+    };
+    return clock;
+  }
+
+  // The M-cycle-exact contention observer (MACHINE-CONTENTION-MCYCLE-001). It
+  // threads a running uncontended T-offset through the instruction's bus cycles
+  // (memory M-cycles via mcycle(), internal no-MREQ cycles via internal()),
+  // sampling contentionDelay at (instructionStart + runT + accumulated) for each
+  // contended cycle. It also keeps the per-access tally and an `incomplete` flag:
+  // when the CPU signals inexact() (an instruction whose internal cycles this
+  // slice does not yet model exactly), the machine falls back to the conformed
+  // per-access value, so no instruction is ever silently mis-timed (C5).
+  _exactClock(instructionStart) {
+    return {
+      base: instructionStart,
+      runT: 0,
+      extra: 0,
+      perAccessExtra: 0,
+      incomplete: false,
+      access(address) {
+        if (isContendedAddress(address)) {
+          const t = (this.base + this.perAccessExtra) % FRAME_T_STATES;
+          this.perAccessExtra += contentionDelay(t);
+        }
+      },
+      mcycle(address, tStates) {
+        if (isContendedAddress(address)) {
+          const t = (this.base + this.runT + this.extra) % FRAME_T_STATES;
+          this.extra += contentionDelay(t);
+        }
+        this.runT += tStates;
+      },
+      internal(address, n) {
+        for (let i = 0; i < n; i += 1) {
+          if (isContendedAddress(address)) {
+            const t = (this.base + this.runT + this.extra) % FRAME_T_STATES;
+            this.extra += contentionDelay(t);
+          }
+          this.runT += 1;
+        }
+      },
+      inexact() { this.incomplete = true; },
+      total() { return this.incomplete ? this.perAccessExtra : this.extra; },
+    };
+  }
+
+  // Execute exactly one instruction with contention threaded. Advances the clock
+  // by the real (uncontended + contention) duration and tracks the HALT state.
+  // Does NOT sample interrupts — that is the frame loop's job
+  // (MACHINE-INT-SAMPLE-001 fixes interrupt sampling to boundaries it controls).
+  stepInstruction() {
+    const reg = this.registers;
+    const pcBefore = reg.pc & 0xffff;
+    const opcode = this.memory[pcBefore];
+    const clock = this.exactContention
+      ? this._exactClock(this.clock)
+      : this._contentionClock(this.clock);
+
+    const result = step({ registers: reg, memory: this.memory, io: this.io, clock });
+    this.registers = result.registers;
+
+    const contention = this.exactContention ? clock.total() : clock.extra;
+    const tStates = result.tStates + contention;
+    this.clock = (this.clock + tStates) % FRAME_T_STATES;
+    this.tStatesTotal += tStates;
+
+    // HALT is the only instruction that does not advance PC; the CPU leaves PC on
+    // the HALT opcode and reports 4 T per refetch.
+    this.halted = opcode === HALT_OPCODE && (this.registers.pc & 0xffff) === pcBefore;
+
+    return { tStates, contention, halted: this.halted };
+  }
+
+  // Accept the pending maskable interrupt (caller has verified the conditions).
+  _acceptInterrupt(dataBus = INT_DATA_BUS) {
+    const result = acceptInterrupt({
+      registers: this.registers,
+      memory: this.memory,
+      halted: this.halted,
+      dataBus,
+    });
+    this.registers = result.registers;
+    this.halted = false;
+    this.eiDelay = 0;
+    this.clock = (this.clock + result.tStates) % FRAME_T_STATES;
+    this.tStatesTotal += result.tStates;
+    return result;
+  }
+
+  // True iff the machine may accept a maskable interrupt at the current boundary:
+  // interrupts enabled and not inside the post-EI one-instruction delay.
+  _interruptArmed() {
+    return Boolean(this.registers.iff1) && this.eiDelay === 0;
+  }
+
+  // Run one whole frame: execute instructions until the clock crosses the frame
+  // length, sampling INT at each boundary and accepting at most once
+  // (MACHINE-FRAME-LOOP-001). Returns { tStates, accepted } for the frame.
+  runFrame({ dataBus = INT_DATA_BUS } = {}) {
+    const start = this.tStatesTotal;
+    let accepted = 0;
+    let intTaken = false;
+
+    // The frame ends when the running clock would wrap. Because the clock is kept
+    // modulo the frame length, we track elapsed T-states for this frame directly.
+    let elapsed = 0;
+    while (elapsed < FRAME_T_STATES) {
+      if (!intTaken && this._interruptArmed() && interruptActive(this.clock)) {
+        const before = this.tStatesTotal;
+        this._acceptInterrupt(dataBus);
+        elapsed += this.tStatesTotal - before;
+        accepted += 1;
+        intTaken = true;
+        continue;
+      }
+      const wasEi = this.memory[this.registers.pc & 0xffff] === EI_OPCODE;
+      if (this.eiDelay > 0) this.eiDelay -= 1;
+      const before = this.tStatesTotal;
+      this.stepInstruction();
+      elapsed += this.tStatesTotal - before;
+      if (wasEi) this.eiDelay = 1;
+    }
+
+    this.frames += 1;
+    return { tStates: this.tStatesTotal - start, accepted };
+  }
+}