@zx-vibes/ula 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,38 @@
+# @zx-vibes/ula
+
+48K ZX Spectrum ULA model for the zx-vibes toolchain.
+
+Current package version in this repository: `0.1.0`.
+
+A dependency-free JavaScript (ESM) model of the 48K ULA: frame/interrupt
+timing constants, memory contention, screen address/attribute arithmetic,
+`.scr` format helpers, floating-bus behavior, and Kempston joystick port
+decoding. It is regenerated from the project DNA (`dna/domain/`) and decided
+by the timing conformance fixtures.
+
+## Usage
+
+```js
+import {
+  FRAME_T_STATES,
+  interruptActive,
+  isContendedAddress,
+  contentionDelay,
+} from "@zx-vibes/ula";
+```
+
+`@zx-vibes/ula/timing` exposes the timing module directly. Type declarations
+are generated from the source JSDoc (`.d.mts` alongside each module).
+
+Most consumers want `@zx-vibes/machine`, which joins this model with the
+`@zx-vibes/cpu` core.
+
+## 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,52 @@
+{
+  "name": "@zx-vibes/ula",
+  "version": "0.1.0",
+  "description": "Regenerated 48K ZX Spectrum ULA timing model for zx-vibes, derived from the DNA and decided by the timing conformance fixtures.",
+  "license": "MIT",
+  "author": "Alvaro Mateos",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Alvaromah/zx-vibes.git",
+    "directory": "packages/ula"
+  },
+  "homepage": "https://github.com/Alvaromah/zx-vibes#readme",
+  "bugs": {
+    "url": "https://github.com/Alvaromah/zx-vibes/issues"
+  },
+  "keywords": [
+    "zx-spectrum",
+    "ula",
+    "emulator",
+    "emulation",
+    "timing"
+  ],
+  "type": "module",
+  "engines": {
+    "node": ">=20"
+  },
+  "main": "src/index.mjs",
+  "types": "src/index.d.mts",
+  "exports": {
+    ".": {
+      "types": "./src/index.d.mts",
+      "default": "./src/index.mjs"
+    },
+    "./timing": {
+      "types": "./src/ula-timing.d.mts",
+      "default": "./src/ula-timing.mjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "src",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "test": "node ../../dna/conformance/timing/run-timing-fixtures.mjs",
+    "lint": "eslint src",
+    "types:gen": "tsc src/index.mjs --allowJs --declaration --emitDeclarationOnly --outDir src"
+  }
+}

package/src/floating-bus.d.mts

@@ -0,0 +1,7 @@
+export function portFloats(port: any): boolean;
+export function activeDisplayFetch(t: any): boolean;
+export function floatingBusByte(t: any): {
+    value: number;
+    modeled: boolean;
+};
+export const FLOATING_BUS_IDLE: 255;

package/src/floating-bus.mjs

@@ -0,0 +1,58 @@
+// Regenerated 48K ZX Spectrum floating-bus read model, authored from the project
+// DNA (dna/domain/ula-timing.md "Floating bus", ULA-FLOATBUS-*) and decided by the
+// floating-bus conformance fixtures (dna/conformance/timing/floating-bus.json).
+//
+// Scope (decision:ADR-0026, refining ADR-0021's E2 assumption): the port-decode
+// precondition and the idle-bus value are pinned hardware facts; the timing-exact
+// IN-window byte depends on the deferred active-area pixel timing (A5, ADR-0021)
+// and is reported as UNMODELLED — never fabricated. The active-fetch window is the
+// contended display window of ula-timing.mjs (anchor 14335), NOT the legacy 14384.
+import {
+  FRAME_T_STATES,
+  T_STATES_PER_LINE,
+  CONTENTION_START_T,
+  DISPLAY_LINES,
+  CONTENDED_T_PER_LINE,
+} from "./ula-timing.mjs";
+
+// The value an undriven (floating) bus reads outside the display fetch: the data
+// lines float high (ULA-FLOATBUS-IDLE-001).
+export const FLOATING_BUS_IDLE = 0xff;
+
+// ULA-FLOATBUS-PORT-001: the ULA decodes I/O on A0. It drives every EVEN port
+// (A0 = 0) — that is the keyboard / EAR read surface (host-io-port-fe.md). An IN
+// from an ODD port (A0 = 1) that no other device decodes is undriven and reads the
+// floating bus. At the 48K base nothing decodes odd ports, so every odd port floats
+// (the canonical floating-bus port is the odd 0xFF). A later peripheral that decodes
+// an odd port (e.g. Kempston at 0x1F) carves out its own port and stops it floating.
+export function portFloats(port) {
+  return (port & 0x0001) === 1;
+}
+
+// True iff frame T-state `t` is inside the active display-fetch window — exactly the
+// contended window of ULA-TIME-CONTENTION-WINDOW-001 (192 lines, 224 T apart, each
+// starting at frame T 14335 for the first 128 T). This is the ULA display-fetch
+// activity that both contends memory and drives the floating bus.
+export function activeDisplayFetch(t) {
+  const f = ((t % FRAME_T_STATES) + FRAME_T_STATES) % FRAME_T_STATES;
+  const offset = f - CONTENTION_START_T;
+  if (offset < 0) return false; // before the first display line
+  const line = Math.floor(offset / T_STATES_PER_LINE);
+  if (line >= DISPLAY_LINES) return false; // after the last display line
+  const column = offset % T_STATES_PER_LINE;
+  return column < CONTENDED_T_PER_LINE; // border + retrace are not fetches
+}
+
+// The value an IN from a floating (odd, undriven) port reads at frame T-state `t`:
+//   outside the display-fetch window -> { value: 0xFF, modeled: true }
+//       the idle bus floats high (ULA-FLOATBUS-IDLE-001).
+//   inside  the display-fetch window -> { value: null,  modeled: false }
+//       the byte is the ULA-fetched display/attribute byte (ULA-FLOATBUS-FETCH-001),
+//       but the exact T->byte phase mapping is the deferred A5 timing
+//       (ULA-FLOATBUS-DEFER-001) and is NOT pinned — reported unmodelled, not faked.
+export function floatingBusByte(t) {
+  if (activeDisplayFetch(t)) {
+    return { value: null, modeled: false };
+  }
+  return { value: FLOATING_BUS_IDLE, modeled: true };
+}

package/src/index.d.mts

@@ -0,0 +1,6 @@
+export * from "./ula-timing.mjs";
+export * from "./screen-address.mjs";
+export * from "./screen-attribute.mjs";
+export * from "./scr-format.mjs";
+export * from "./floating-bus.mjs";
+export * from "./kempston.mjs";

package/src/index.mjs

@@ -0,0 +1,8 @@
+// @zx-vibes/ula — regenerated 48K ZX Spectrum ULA timing model + screen addressing
+// + attribute/colour decode.
+export * from "./ula-timing.mjs";
+export * from "./screen-address.mjs";
+export * from "./screen-attribute.mjs";
+export * from "./scr-format.mjs";
+export * from "./floating-bus.mjs";
+export * from "./kempston.mjs";

package/src/kempston.d.mts

@@ -0,0 +1,8 @@
+export function kempstonDecodes(port: any): boolean;
+export function kempstonByte(state?: {}): number;
+export const KEMPSTON_PORT: 31;
+export const KEMPSTON_RIGHT: 1;
+export const KEMPSTON_LEFT: 2;
+export const KEMPSTON_DOWN: 4;
+export const KEMPSTON_UP: 8;
+export const KEMPSTON_FIRE: 16;

package/src/kempston.mjs

@@ -0,0 +1,48 @@
+// @zx-vibes/ula — regenerated 48K ZX Spectrum Kempston joystick interface read model,
+// authored from the project DNA (dna/domain/peripherals.md "Kempston joystick",
+// JOY-KEMPSTON-*) and decided by the peripherals conformance fixtures
+// (dna/conformance/peripherals/kempston.json).
+//
+// The Kempston interface is an EXTERNAL peripheral, not part of the ULA; it is modeled
+// in @zx-vibes/ula beside the floating-bus model because both resolve an `IN` from the
+// I/O bus, and the Kempston port decode is precisely what carves port 0x1F out of the
+// floating odd-port set (ula-timing.mjs portFloats / ula-timing.md ULA-FLOATBUS-PORT-001).
+//
+// Scope (decision:ADR-0021, which ratified F1 as "port 0x1F active-high 000FUDLR"):
+// the bit layout + active-high read at the canonical port are pinned hardware. The
+// interface decodes the LOW address byte (the high byte — register B of `IN A,(C)` —
+// is don't-care); finer incomplete decoding (clones that alias 0x1F across any A5=0
+// port) is interface-specific and out of scope.
+
+// The canonical Kempston joystick port (low byte). Reads return the button state.
+export const KEMPSTON_PORT = 0x1f;
+
+// Active-high button bit masks in the read byte `000FUDLR` (bits 7-5 are always 0).
+export const KEMPSTON_RIGHT = 0x01; // bit 0
+export const KEMPSTON_LEFT = 0x02; // bit 1
+export const KEMPSTON_DOWN = 0x04; // bit 2
+export const KEMPSTON_UP = 0x08; // bit 3
+export const KEMPSTON_FIRE = 0x10; // bit 4
+
+// JOY-KEMPSTON-PORT-001: true iff `port` addresses the Kempston interface. The
+// canonical decode is low byte 0x1F; the high address byte is don't-care, so any port
+// whose low 8 bits are 0x1F reads the joystick. Finer A5-only aliasing is out of scope.
+export function kempstonDecodes(port) {
+  return (port & 0x00ff) === KEMPSTON_PORT;
+}
+
+// JOY-KEMPSTON-READ-001: map a joystick button state to the active-high read byte
+// `000FUDLR`. Each pressed control sets its bit; the unused top three bits are always
+// 0; idle (nothing pressed) reads 0x00. An absent/false field is "not pressed". The
+// five controls are independent — the hardware imposes no interlock, so the model does
+// not mask the physically-impossible Left+Right / Up+Down; it returns the OR of the
+// pressed bits exactly.
+export function kempstonByte(state = {}) {
+  let byte = 0;
+  if (state.right) byte |= KEMPSTON_RIGHT;
+  if (state.left) byte |= KEMPSTON_LEFT;
+  if (state.down) byte |= KEMPSTON_DOWN;
+  if (state.up) byte |= KEMPSTON_UP;
+  if (state.fire) byte |= KEMPSTON_FIRE;
+  return byte;
+}

package/src/scr-format.d.mts

@@ -0,0 +1,4 @@
+export function saveScr(memory: any): Uint8Array<ArrayBuffer>;
+export function loadScr(memory: any, scr: any): void;
+export const SCR_SIZE: number;
+export const SCR_BASE: 16384;

package/src/scr-format.mjs

@@ -0,0 +1,44 @@
+// Regenerated `.scr` screen-dump load/save, authored from the project DNA
+// (dna/domain/file-formats.md "`.scr` — raw screen dump") and decided by the format
+// conformance fixtures (dna/conformance/formats/scr-format.json). A `.scr` file is a
+// raw, headerless copy of the screen memory region 0x4000-0x5AFF (the 6144-byte
+// display file followed by the 768-byte attribute file) — exactly the 6912-byte image
+// the gallery framebuffer consumes (screen-render.md SCREEN-FRAMEBUFFER-001). Pure
+// data copy: no header, no reordering, no compression.
+import {
+  DISPLAY_FILE_BASE,
+  DISPLAY_FILE_SIZE,
+  ATTR_FILE_SIZE,
+} from "./screen-address.mjs";
+
+// FMT-SCR-SIZE-001: 6144 (display) + 768 (attribute).
+export const SCR_SIZE = DISPLAY_FILE_SIZE + ATTR_FILE_SIZE; // 6912
+// FMT-SCR-LAYOUT-001: file offset o is memory address 0x4000 + o.
+export const SCR_BASE = DISPLAY_FILE_BASE; // 0x4000
+
+// FMT-SCR-SAVE-001: read exactly 0x4000-0x5AFF into a 6912-byte file, in address
+// order (file[o] = memory[0x4000 + o]). No header, no dropped attribute byte.
+export function saveScr(memory) {
+  if (!memory || memory.length < SCR_BASE + SCR_SIZE) {
+    throw new Error(`saveScr: memory must hold at least 0x${(SCR_BASE + SCR_SIZE).toString(16)} bytes`);
+  }
+  const scr = new Uint8Array(SCR_SIZE);
+  for (let offset = 0; offset < SCR_SIZE; offset += 1) {
+    scr[offset] = memory[SCR_BASE + offset] & 0xff;
+  }
+  return scr;
+}
+
+// FMT-SCR-LOAD-001: write the 6912 bytes into memory at 0x4000 + offset and touch no
+// address outside 0x4000-0x5AFF. FMT-SCR-SIZE-001: reject any other length.
+export function loadScr(memory, scr) {
+  if (!scr || scr.length !== SCR_SIZE) {
+    throw new Error(`loadScr: a .scr file must be exactly ${SCR_SIZE} bytes, got ${scr ? scr.length : "none"}`);
+  }
+  if (!memory || memory.length < SCR_BASE + SCR_SIZE) {
+    throw new Error(`loadScr: memory must hold at least 0x${(SCR_BASE + SCR_SIZE).toString(16)} bytes`);
+  }
+  for (let offset = 0; offset < SCR_SIZE; offset += 1) {
+    memory[SCR_BASE + offset] = scr[offset] & 0xff;
+  }
+}

package/src/screen-address.d.mts

@@ -0,0 +1,14 @@
+export function displayByteAddress(x: any, y: any): number;
+export function displayLineAddress(y: any): number;
+export function attributeAddress(x: any, y: any): number;
+export const DISPLAY_FILE_BASE: 16384;
+export const DISPLAY_FILE_END: 22527;
+export const DISPLAY_FILE_SIZE: 6144;
+export const ATTR_FILE_BASE: 22528;
+export const ATTR_FILE_END: 23295;
+export const ATTR_FILE_SIZE: 768;
+export const SCREEN_WIDTH: 256;
+export const SCREEN_HEIGHT: 192;
+export const CHAR_COLS: 32;
+export const CHAR_ROWS: 24;
+export const THIRD_SIZE: 2048;

package/src/screen-address.mjs

@@ -0,0 +1,51 @@
+// Regenerated 48K ZX Spectrum memory map & screen-address decode, authored from the
+// project DNA (dna/domain/memory-map.md) and decided by the screen conformance
+// fixtures (dna/conformance/screen/screen-address.json). Pure functions of a pixel
+// coordinate: no machine state, no CPU coupling. This models the documented address
+// arithmetic only — the bitmap/attribute byte *interpretation* (bit->pixel,
+// INK/PAPER/BRIGHT/FLASH -> palette index) is a later slice and is not here.
+
+// --- Region constants (MM-LAYOUT-001 / MM-SCREEN-DISPLAY-FILE-001 / MM-ATTR-FILE-001) ---
+export const DISPLAY_FILE_BASE = 0x4000;
+export const DISPLAY_FILE_END = 0x57ff;
+export const DISPLAY_FILE_SIZE = 6144;
+
+export const ATTR_FILE_BASE = 0x5800;
+export const ATTR_FILE_END = 0x5aff;
+export const ATTR_FILE_SIZE = 768;
+
+// --- Geometry constants ---
+export const SCREEN_WIDTH = 256;
+export const SCREEN_HEIGHT = 192;
+export const CHAR_COLS = 32;
+export const CHAR_ROWS = 24;
+export const THIRD_SIZE = 0x800;
+
+// --- Display-file decode (MM-SCREEN-ADDR-001) -------------------------------------
+// The display file is NOT linear. The 16-bit address of the byte holding pixel
+// (x, y) (line y = y7 y6 y5 y4 y3 y2 y1 y0) has the bit layout:
+//   bit: 15 14 13 12 11 10  9  8   7  6  5  4  3  2  1  0
+//         0  1  0  y7 y6 y2 y1 y0  y5 y4 y3 x4 x3 x2 x1 x0
+// i.e. 0x4000 + third*0x800 + pixelRow*0x100 + charRow*0x20 + col, where
+// third = y>>6, pixelRow = y&7, charRow = (y>>3)&7, col = x>>3.
+export function displayByteAddress(x, y) {
+  return (
+    0x4000 +
+    ((y & 0xc0) << 5) + // y7 y6   -> bits 12-11 (third)
+    ((y & 0x07) << 8) + // y2 y1 y0 -> bits 10-8 (pixel row within cell)
+    ((y & 0x38) << 2) + // y5 y4 y3 -> bits 7-5 (char row within third)
+    (x >> 3) //           x4..x0   -> bits 4-0 (byte column)
+  );
+}
+
+// First byte (column 0) of pixel line y; the 32 bytes of a line are contiguous.
+// (MM-SCREEN-LINE-ADDR-001)
+export function displayLineAddress(y) {
+  return displayByteAddress(0, y);
+}
+
+// --- Attribute decode (MM-ATTR-ADDR-001) ------------------------------------------
+// Linear, row-major (no thirds interleave): 0x5800 + charRow*32 + charCol.
+export function attributeAddress(x, y) {
+  return 0x5800 + (y >> 3) * 32 + (x >> 3);
+}

package/src/screen-attribute.d.mts

@@ -0,0 +1,9 @@
+export function attributeInk(byte: any): number;
+export function attributePaper(byte: any): number;
+export function attributeBright(byte: any): number;
+export function attributeFlash(byte: any): number;
+export function inkColorIndex(byte: any): number;
+export function paperColorIndex(byte: any): number;
+export function flashPhase(frame: any): number;
+export function pixelColorIndex(byte: any, pixelOn: any, phase: any): number;
+export const FLASH_FRAMES: 16;

package/src/screen-attribute.mjs

@@ -0,0 +1,52 @@
+// Regenerated 48K ZX Spectrum attribute / colour decode, authored from the project
+// DNA (dna/domain/memory-map.md "Attribute & colour decode") and decided by the
+// screen conformance fixtures (dna/conformance/screen/attr-decode.json). Pure
+// functions of an attribute byte (and, for the per-pixel form, a bitmap bit and the
+// FLASH phase): no machine state. This produces a palette INDEX 0..15 (hardware
+// truth); the index -> RGB triple is gallery render policy (dna/product/palette.yaml).
+
+// Attribute bit fields (MM-ATTR-BITS-001):
+//   bit 7 FLASH | bit 6 BRIGHT | bits 5..3 PAPER (0..7) | bits 2..0 INK (0..7)
+export function attributeInk(byte) {
+  return byte & 0x07;
+}
+export function attributePaper(byte) {
+  return (byte >> 3) & 0x07;
+}
+export function attributeBright(byte) {
+  return (byte >> 6) & 1;
+}
+export function attributeFlash(byte) {
+  return (byte >> 7) & 1;
+}
+
+// Palette index 0..15 = base colour 0..7 + 8*BRIGHT (MM-ATTR-COLOUR-INDEX-001).
+// BRIGHT raises the whole cell; it is not a separate hue.
+export function inkColorIndex(byte) {
+  return attributeInk(byte) + attributeBright(byte) * 8;
+}
+export function paperColorIndex(byte) {
+  return attributePaper(byte) + attributeBright(byte) * 8;
+}
+
+// FLASH phase (MM-ATTR-FLASH-001): the ULA inverts every 16 frames. Phase 0 is the
+// normal state, phase 1 the swapped (INK<->PAPER) state.
+export const FLASH_FRAMES = 16;
+export function flashPhase(frame) {
+  return Math.floor(frame / FLASH_FRAMES) & 1;
+}
+
+// Final palette index of a pixel (MM-PIXEL-COLOUR-001): pixelOn=1 shows INK, 0 shows
+// PAPER. When the FLASH bit is set and the phase is odd, INK and PAPER swap first;
+// BRIGHT applies after the swap (it raises whichever colour is shown).
+export function pixelColorIndex(byte, pixelOn, phase) {
+  let ink = attributeInk(byte);
+  let paper = attributePaper(byte);
+  if (attributeFlash(byte) && (phase & 1)) {
+    const swap = ink;
+    ink = paper;
+    paper = swap;
+  }
+  const base = pixelOn ? ink : paper;
+  return base + attributeBright(byte) * 8;
+}

package/src/ula-timing.d.mts

@@ -0,0 +1,13 @@
+export function interruptActive(t: any): boolean;
+export function isContendedAddress(address: any): boolean;
+export function contentionDelay(t: any): number;
+export const SCAN_LINES: 312;
+export const T_STATES_PER_LINE: 224;
+export const FRAME_T_STATES: number;
+export const INTERRUPT_T_STATES: 32;
+export const CONTENDED_LOW: 16384;
+export const CONTENDED_HIGH: 32767;
+export const CONTENTION_PATTERN: number[];
+export const CONTENTION_START_T: 14335;
+export const DISPLAY_LINES: 192;
+export const CONTENDED_T_PER_LINE: 128;

package/src/ula-timing.mjs

@@ -0,0 +1,52 @@
+// Regenerated 48K ZX Spectrum ULA timing model, authored from the project DNA
+// (dna/domain/ula-timing.md) and decided by the timing conformance fixtures
+// (dna/conformance/timing/*.json). Pure functions of a frame T-state and a
+// memory address: no machine state, no CPU coupling. Integrating these into the
+// executed instruction stream (contention applied to each memory access) and
+// interrupt acceptance is a later slice; this models the documented timing only.
+
+// --- Frame and interrupt (ULA-TIME-FRAME-001 / ULA-TIME-INT-001) -------------
+export const SCAN_LINES = 312;
+export const T_STATES_PER_LINE = 224;
+export const FRAME_T_STATES = SCAN_LINES * T_STATES_PER_LINE; // 69888
+export const INTERRUPT_T_STATES = 32; // INT held LOW for the first 32 T of a frame
+
+// True iff the ULA is asserting INT at frame-relative T-state `t`. Works for any
+// integer t (negative or beyond one frame) by reducing modulo the frame length.
+export function interruptActive(t) {
+  const f = ((t % FRAME_T_STATES) + FRAME_T_STATES) % FRAME_T_STATES;
+  return f < INTERRUPT_T_STATES;
+}
+
+// --- Memory contention (ULA-TIME-CONTENDED-ADDR-001 / -PATTERN / -WINDOW) -----
+export const CONTENDED_LOW = 0x4000;
+export const CONTENDED_HIGH = 0x7fff;
+
+// Only the lower 16K RAM is contended on a 48K machine.
+export function isContendedAddress(address) {
+  const a = address & 0xffff;
+  return a >= CONTENDED_LOW && a <= CONTENDED_HIGH;
+}
+
+// The repeating period-8 delay pattern applied during the display fetch window.
+export const CONTENTION_PATTERN = [6, 5, 4, 3, 2, 1, 0, 0];
+
+// Canonical 48K early-timing geometry (pinned per ADR-0010).
+export const CONTENTION_START_T = 14335; // first contended frame T-state
+export const DISPLAY_LINES = 192; // contended display lines
+export const CONTENDED_T_PER_LINE = 128; // contended T-states at the start of each line
+
+// Extra T-states the ULA adds to a CONTENDED-RAM access that begins at frame
+// T-state `t`. Returns 0 outside the display fetch window (border, retrace, and
+// any access to uncontended memory must use isContendedAddress() first). The
+// caller is responsible for only applying this to contended addresses.
+export function contentionDelay(t) {
+  const f = ((t % FRAME_T_STATES) + FRAME_T_STATES) % FRAME_T_STATES;
+  const offset = f - CONTENTION_START_T;
+  if (offset < 0) return 0; // before the first display line
+  const line = Math.floor(offset / T_STATES_PER_LINE);
+  if (line >= DISPLAY_LINES) return 0; // after the last display line
+  const column = offset % T_STATES_PER_LINE;
+  if (column >= CONTENDED_T_PER_LINE) return 0; // border + horizontal retrace
+  return CONTENTION_PATTERN[column % CONTENTION_PATTERN.length];
+}