zx84 AGENTS.md

ZX84 — Codex Guidelines

Architecture

The codebase is layered "machines as hardware, components as chips" — see docs/re-architecture.md for the full rationale and docs/adding-a-machine.md for the new-machine checklist. Dependencies point strictly downward and the boundaries are enforced mechanically (npm run depcheck, zero exceptions).

Layer map

• src/cores/ — commodity silicon only: chips that shipped in more than one machine (Z80, AY-3-891x, TMS9918A, CRTC 6845, uPD765A, WD179x/1772/1793, Z80 CTC, i8255). Pure — imports only other cores, src/media/ types, src/utils/. Custom silicon that only ever existed in one machine (the Spectrum's Ferranti ULA, the CPC's Amstrad gate array, the microdrive) is not here — it lives in that machine's folder.
• src/machines/<name>/ — one folder per machine = a motherboard. Everything specific to that machine: the machine class (extends base-machine.ts), its custom silicon (spectrum/ula.ts, cpc/gate-array.ts), contention.ts, variants/, memory.ts, io.ts (port decode if-chain — hot, load-bearing), keyboard.ts, peripherals/, snapshots/, tape-loader.ts, per-family models.ts helpers, descriptor.ts (pure metadata + factory), services/ (the service surface), and ui/ (Solid contributions — the ONLY machine files allowed to import solid-js and the shell/state layers). A machine folder is an island: it never imports another machine folder, nor UI/state/store/shell.
• src/machines/machine.ts — the SPI: Machine, MachineServices, the service interfaces (media/roms/tape/disks/snapshots/debug/input/probe), MachineDescriptor + MachineUiCapabilities, MachineHost, MachineEntry.
• src/machines/base-machine.ts — shared driver loop (frame pacing, turbo pump, audio back-pressure, lifecycle, debug-field storage). Untouched by machines.
• src/machines/registry.ts — the parts catalog: the only file besides src/models.ts allowed to name every machine. Stays headless-safe.
• src/media/ — format codecs → neutral models: floppy/ (DskImage, DSK/HFE/SCP/MGT/TRD/SCL, disk-detect.ts, floppy-sound.ts), tape/ (TAP/TZX/CSW deck + .cas), zip.ts. Pure — imports only media + utils.
• src/shell/ — the host: context.ts (shared machine handle + managers), lifecycle.ts (create/switch/destroy, pause/turbo, stepping, refresh state), media.ts (zip/picker/dispatch/persistence + transport wrappers), settings.ts (SettingsView pump), rom.ts (fetch/cache/persist). Reaches machines only through machine.services and the SPI/registry — never a concrete machine folder.
• src/state/ — Solid reactive stores (machine, debug, disk, tape, activity, microdrive). Shared flat signal bags; the writers are generic (shell + probe).
• src/store/ — settings + IndexedDB persistence.
• src/ui/ — generic UI: panes/ hosts panes and components/ hosts reusable elements. Bind to machine.services and the descriptor's ui capabilities; never import a concrete machine or branch on machine kind. machine-ui.ts is the UI-side manifest mapping a kind → its lazily-imported ui/ contributions (the sole sanctioned exception).
• src/frame-bridge.ts — the generic per-frame consumer of each machine's FrameProbe; owns presentation policy (LED latch, formatting, diffing).
• src/managers/ — debug-manager + rom-manager: generic orchestration.
• src/models.ts — the MachineModel union manifest + leaf helpers (isCpcModel, …). Per-family helpers (is128kClass, isPlusDCapable, …) live in each machine's own models.ts.
• src/debug/ — machine-agnostic debug tools (BASIC parser) plus per-CPU-family debug substrate in src/debug/<family>/ (z80/: disasm.ts disassembler + service.ts Z80DebugService/z80Cpu(), step-over/out logic, register surface — shared by every Z80 machine). A machine may import its family module — that's substrate, not another machine. Imports only cores, utils, and machine SPI types. These tools take Uint8Array, not ByteReader.
• src/ocr/ — machine-specific screen OCR engines, each returning neutral text and styling data from display memory.
• src/display/ — Canvas and WebGL renderers with HQx/xBR upscaling shaders.
• src/emulator.ts — a thin compatibility shim (re-exports shell + state), retained only because frame-bridge.ts and its module-mock tests still import from it. New code imports from @/shell/* and @/state/* directly.
• mcp/ — MCP server (persistent Node process; mcp/server.ts entry, tools under mcp/tools/). Binds to state.spec.services; mcp/concrete.ts is the single sanctioned module that narrows to a concrete machine.