zx84: Instructions file for Codex

ZX84 — Codex Guidelines

You may learn how old hardware works from other open source emulators. You may not copy code from them.

Architecture

The codebase is layered "machines as hardware, components as chips" — see 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, MOS 6502, 6522 VIA, Intel 8271, SAA5050). 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; m6502/: the same for the 6502 — used by the BBC Micro). 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.