@zx-vibes/machine 0.1.0

package/src/snapshot-z80.d.mts

@@ -0,0 +1,39 @@
+export function compressZ80(bytes: any): Uint8Array<ArrayBuffer>;
+export function decompressZ80(bytes: any, expectedLength: any): Uint8Array<ArrayBuffer>;
+export function writeZ80({ registers, memory, border }?: {
+    registers?: {};
+    border?: number;
+}): Uint8Array<ArrayBuffer>;
+export function readZ80(bytes: any): {
+    registers: {
+        a: number;
+        f: number;
+        c: number;
+        b: number;
+        l: number;
+        h: number;
+        sp: number;
+        i: number;
+        r: number;
+        e: number;
+        d: number;
+        c_: number;
+        b_: number;
+        e_: number;
+        d_: number;
+        l_: number;
+        h_: number;
+        a_: number;
+        f_: number;
+        iyl: number;
+        iyh: number;
+        ixl: number;
+        ixh: number;
+        iff1: number;
+        iff2: number;
+        im: number;
+    };
+    memory: Uint8Array<ArrayBuffer>;
+    border: number;
+    version: number;
+};

package/src/snapshot-z80.mjs

@@ -0,0 +1,164 @@
+// .z80 snapshot format (read/write) for the regenerated 48K machine, authored
+// from the project DNA (dna/domain/snapshot-z80.md) and decided by the format
+// conformance fixtures (dna/conformance/formats/z80-v3-roundtrip.json).
+//
+// The .z80 file format is the de-facto community ZX Spectrum snapshot format
+// (Gerton Lunter). This module implements the 48K variant: it WRITES version 3
+// (PC=0 marker, 54-byte extra header, hardware mode 0 = 48K, three RLE-compressed
+// 16K memory pages 8/4/5) and READS versions 1, 2 and 3. The state is the machine
+// register file + the 64 KB memory image + the border colour; round-tripping it
+// preserves RAM and registers (FMT-Z80-V3-001).
+
+const PAGE_TO_BASE = { 8: 0x4000, 4: 0x8000, 5: 0xc000 }; // 48K page numbers -> address
+const BASE_TO_PAGE = [[0x4000, 8], [0x8000, 4], [0xc000, 5]];
+
+// --- RLE (the .z80 "ED ED count value" run encoding) -------------------------
+// A run of >= 5 equal bytes (or >= 2 equal 0xED bytes, since a literal "ED ED"
+// would be misread as the marker) is encoded as ED ED count value, count <= 255.
+export function compressZ80(bytes) {
+  const out = [];
+  let i = 0;
+  while (i < bytes.length) {
+    const v = bytes[i];
+    let run = 1;
+    while (i + run < bytes.length && bytes[i + run] === v && run < 255) run += 1;
+    const worthRun = v === 0xed ? run >= 2 : run >= 5;
+    if (worthRun) {
+      out.push(0xed, 0xed, run, v);
+      i += run;
+    } else if (v === 0xed) {
+      // A lone ED (run of 1) must not start a literal "ED xx" that could be ED ED:
+      // emit the ED and the following byte verbatim as a pair so it is never a marker.
+      out.push(0xed);
+      i += 1;
+      if (i < bytes.length) { out.push(bytes[i]); i += 1; }
+    } else {
+      out.push(v);
+      i += 1;
+    }
+  }
+  return Uint8Array.from(out);
+}
+
+export function decompressZ80(bytes, expectedLength) {
+  const out = [];
+  let i = 0;
+  while (i < bytes.length && (expectedLength === undefined || out.length < expectedLength)) {
+    if (bytes[i] === 0xed && bytes[i + 1] === 0xed) {
+      const count = bytes[i + 2];
+      const value = bytes[i + 3];
+      for (let k = 0; k < count; k += 1) out.push(value);
+      i += 4;
+    } else {
+      out.push(bytes[i]);
+      i += 1;
+    }
+  }
+  return Uint8Array.from(out);
+}
+
+const REG = (r, name) => (r[name] ?? 0) & 0xff;
+const word = (lo, hi) => (lo & 0xff) | ((hi & 0xff) << 8);
+
+export function writeZ80({ registers = {}, memory, border = 0 } = {}) {
+  const r = registers;
+  const mem = memory instanceof Uint8Array ? memory : Uint8Array.from(memory ?? []);
+  const h = new Uint8Array(30 + 2 + 54);
+  // v1 header (PC at 6-7 = 0 => version 2/3)
+  h[0] = REG(r, "a"); h[1] = REG(r, "f");
+  h[2] = REG(r, "c"); h[3] = REG(r, "b");
+  h[4] = REG(r, "l"); h[5] = REG(r, "h");
+  h[6] = 0; h[7] = 0; // PC = 0 -> v2/v3
+  h[8] = REG(r, "sp") ; h[9] = (r.sp ?? 0) >> 8 & 0xff;
+  h[10] = REG(r, "i");
+  h[11] = REG(r, "r") & 0x7f;
+  h[12] = (((r.r ?? 0) >> 7) & 1) | ((border & 0x07) << 1);
+  h[13] = REG(r, "e"); h[14] = REG(r, "d");
+  h[15] = REG(r, "c_"); h[16] = REG(r, "b_");
+  h[17] = REG(r, "e_"); h[18] = REG(r, "d_");
+  h[19] = REG(r, "l_"); h[20] = REG(r, "h_");
+  h[21] = REG(r, "a_"); h[22] = REG(r, "f_");
+  h[23] = REG(r, "iyl"); h[24] = REG(r, "iyh");
+  h[25] = REG(r, "ixl"); h[26] = REG(r, "ixh");
+  h[27] = (r.iff1 ?? 0) ? 1 : 0;
+  h[28] = (r.iff2 ?? 0) ? 1 : 0;
+  h[29] = (r.im ?? 0) & 0x03;
+  // v3 extra header: length 54, PC, hardware mode 0 (48K).
+  h[30] = 54; h[31] = 0;
+  h[32] = REG(r, "pc"); h[33] = ((r.pc ?? 0) >> 8) & 0xff;
+  h[34] = 0; // hardware mode 0 = 48K
+  // bytes 35..83 left 0 (no extra hardware state)
+
+  const blocks = [];
+  for (const [base, page] of BASE_TO_PAGE) {
+    const raw = mem.subarray(base, base + 0x4000);
+    const comp = compressZ80(raw);
+    const len = comp.length;
+    const block = new Uint8Array(3 + len);
+    block[0] = len & 0xff; block[1] = (len >> 8) & 0xff; block[2] = page;
+    block.set(comp, 3);
+    blocks.push(block);
+  }
+  const total = h.length + blocks.reduce((s, b) => s + b.length, 0);
+  const out = new Uint8Array(total);
+  out.set(h, 0);
+  let off = h.length;
+  for (const b of blocks) { out.set(b, off); off += b.length; }
+  return out;
+}
+
+export function readZ80(bytes) {
+  const b = bytes instanceof Uint8Array ? bytes : Uint8Array.from(bytes);
+  const registers = {
+    a: b[0], f: b[1], c: b[2], b: b[3], l: b[4], h: b[5],
+    sp: word(b[8], b[9]), i: b[10],
+    r: (b[11] & 0x7f) | ((b[12] & 1) << 7),
+    e: b[13], d: b[14],
+    c_: b[15], b_: b[16], e_: b[17], d_: b[18], l_: b[19], h_: b[20],
+    a_: b[21], f_: b[22],
+    iyl: b[23], iyh: b[24], ixl: b[25], ixh: b[26],
+    iff1: b[27] ? 1 : 0, iff2: b[28] ? 1 : 0, im: b[29] & 0x03,
+  };
+  const border = (b[12] >> 1) & 0x07;
+  const memory = new Uint8Array(0x10000);
+
+  const v1pc = word(b[6], b[7]);
+  if (v1pc !== 0) {
+    // Version 1: single 48K image from 0x4000, optionally RLE-compressed (byte12 bit5).
+    registers.pc = v1pc;
+    const compressed = ((b[12] === 255 ? 1 : b[12]) & 0x20) !== 0;
+    const body = b.subarray(30);
+    const ram = compressed ? decompressZ80(stripV1End(body), 0xc000) : body.subarray(0, 0xc000);
+    memory.set(ram.subarray(0, 0xc000), 0x4000);
+    return { registers, memory, border, version: 1 };
+  }
+
+  // Version 2/3: extra header then page blocks.
+  const extraLen = word(b[30], b[31]);
+  registers.pc = word(b[32], b[33]);
+  const version = extraLen === 23 ? 2 : 3;
+  let off = 30 + 2 + extraLen;
+  while (off + 3 <= b.length) {
+    const len = word(b[off], b[off + 1]);
+    const page = b[off + 2];
+    off += 3;
+    const base = PAGE_TO_BASE[page];
+    const uncompressed = len === 0xffff;
+    const blockLen = uncompressed ? 0x4000 : len;
+    const slice = b.subarray(off, off + blockLen);
+    off += blockLen;
+    if (base === undefined) continue; // ignore non-48K pages
+    const ram = uncompressed ? slice : decompressZ80(slice, 0x4000);
+    memory.set(ram.subarray(0, 0x4000), base);
+  }
+  return { registers, memory, border, version };
+}
+
+// A compressed v1 body ends with the marker 00 ED ED 00; strip it before decoding.
+function stripV1End(body) {
+  const n = body.length;
+  if (n >= 4 && body[n - 4] === 0x00 && body[n - 3] === 0xed && body[n - 2] === 0xed && body[n - 1] === 0x00) {
+    return body.subarray(0, n - 4);
+  }
+  return body;
+}

package/src/tap-format.d.mts

@@ -0,0 +1,7 @@
+export function tapChecksum(flag: any, data: any): number;
+export function parseTap(bytes: any): {
+    flag: number;
+    data: Uint8Array<ArrayBuffer>;
+    checksum: number;
+}[];
+export function serializeTap(blocks: any): Uint8Array<ArrayBuffer>;

package/src/tap-format.mjs

@@ -0,0 +1,74 @@
+// Regenerated `.tap` tape-image codec, authored from the project DNA
+// (dna/domain/file-formats.md "`.tap` — tape image (block stream)") and decided by
+// the format conformance fixtures (dna/conformance/formats/tap-format.json). A `.tap`
+// file is a flat concatenation of blocks with no header/footer/global length; each
+// block is [len:2 LE][flag][data…][checksum], where len counts flag+data+checksum and
+// checksum = XOR of the flag and every data byte (the 48K ROM tape parity byte). Tape,
+// like a snapshot, is a file the machine loads, so this lives beside the .z80 codec.
+
+// FMT-TAP-CHECKSUM-001: the XOR of the flag byte and every data byte.
+export function tapChecksum(flag, data) {
+  let checksum = flag & 0xff;
+  for (let i = 0; i < data.length; i += 1) {
+    checksum ^= data[i] & 0xff;
+  }
+  return checksum & 0xff;
+}
+
+// FMT-TAP-BLOCK-001 / FMT-TAP-LENGTH-001 / FMT-TAP-CHECKSUM-001: walk the file front to
+// back. Each block = a 2-byte little-endian length L (flag + data + checksum), then L
+// body bytes: flag, L-2 data bytes, checksum. The recomputed XOR over flag+data must
+// equal the stored checksum, else the block is corrupt. Throws on a truncated block.
+export function parseTap(bytes) {
+  const file = bytes instanceof Uint8Array ? bytes : Uint8Array.from(bytes);
+  const blocks = [];
+  let offset = 0;
+  while (offset < file.length) {
+    if (offset + 2 > file.length) {
+      throw new Error(`parseTap: truncated length prefix at offset ${offset}`);
+    }
+    const length = file[offset] | (file[offset + 1] << 8); // little-endian
+    const bodyStart = offset + 2;
+    const bodyEnd = bodyStart + length;
+    if (length < 2) {
+      throw new Error(`parseTap: block at offset ${offset} has length ${length} < 2 (no room for flag + checksum)`);
+    }
+    if (bodyEnd > file.length) {
+      throw new Error(`parseTap: block at offset ${offset} runs past end of file (need ${bodyEnd}, have ${file.length})`);
+    }
+    const flag = file[bodyStart];
+    const data = file.slice(bodyStart + 1, bodyEnd - 1); // L-2 data bytes
+    const checksum = file[bodyEnd - 1];
+    const computed = tapChecksum(flag, data);
+    if (computed !== checksum) {
+      throw new Error(`parseTap: block at offset ${offset} checksum mismatch (stored 0x${checksum.toString(16)}, computed 0x${computed.toString(16)})`);
+    }
+    blocks.push({ flag, data, checksum });
+    offset = bodyEnd;
+  }
+  return blocks;
+}
+
+// FMT-TAP-ROUNDTRIP-001: the exact inverse of parseTap. For each { flag, data }, emit
+// [len LE][flag][data][checksum] with len = data.length + 2 and the checksum recomputed
+// from flag+data; concatenate the blocks in order.
+export function serializeTap(blocks) {
+  let total = 0;
+  for (const block of blocks) {
+    total += 2 + 2 + block.data.length; // length prefix + flag + checksum + data
+  }
+  const out = new Uint8Array(total);
+  let offset = 0;
+  for (const { flag, data } of blocks) {
+    const length = data.length + 2; // flag + data + checksum
+    out[offset] = length & 0xff; // little-endian low byte
+    out[offset + 1] = (length >> 8) & 0xff; // high byte
+    out[offset + 2] = flag & 0xff;
+    for (let i = 0; i < data.length; i += 1) {
+      out[offset + 3 + i] = data[i] & 0xff;
+    }
+    out[offset + 3 + data.length] = tapChecksum(flag, data);
+    offset += 2 + length;
+  }
+  return out;
+}

package/src/tape-edge-load.d.mts

@@ -0,0 +1,43 @@
+export function createTapeDeck(pulses: any, { clock, startLevel, keyboard }?: {
+    startLevel?: number;
+    keyboard?: number;
+}): {
+    levelAt: (t: any) => number;
+    total: number;
+    read(port: any): number;
+    write(port: any, value: any): void;
+};
+export function edgeLoadWithDeck(machine: any, deck: any, { ix, de, flag, load, tStateBudget, sentinel }?: {
+    load?: boolean;
+    tStateBudget?: number;
+    sentinel?: number;
+}): {
+    ok: boolean;
+    reason: string;
+    bytesLoaded: number;
+    tStates: number;
+};
+export function edgeLoad(machine: any, pulses: any, { ix, de, flag, load, tStateBudget, sentinel, startLevel, keyboard, trailingPulse }?: {
+    load?: boolean;
+    tStateBudget?: number;
+    sentinel?: number;
+    startLevel?: number;
+    keyboard?: number;
+    trailingPulse?: number;
+}): {
+    ok: boolean;
+    reason: string;
+    bytesLoaded: number;
+    tStates: number;
+};
+export function instantLoad(machine: any, body: any, { ix, de, flag, load }?: {
+    load?: boolean;
+}): {
+    ok: boolean;
+    reason: string;
+    bytesLoaded: number;
+    tStates: number;
+};
+export const LD_BYTES_ENTRY: 1366;
+export { FRAME_T_STATES };
+import { FRAME_T_STATES } from "@zx-vibes/ula";

package/src/tape-edge-load.mjs

@@ -0,0 +1,221 @@
+// Regenerated ROM tape edge-loading model, authored from the project DNA
+// (dna/domain/tape-loading.md "Edge loading" + dna/domain/host-io-port-fe.md
+// HOST-IO-PORTFE-READ-BITS-001) and decided by the tape edge-load conformance
+// fixtures (dna/conformance/tape/edge-load.json). The opaque 48K ROM LD-BYTES
+// routine (0x0556, memory-map.md MM-ROM-ARTIFACT-001 / ADR-0024) consumes the W10.9
+// EAR pulse stream (tape-pulses.mjs blockToPulses) on port 0xFE bit 6 and loads a
+// tape block byte-for-byte into RAM. This lives beside the .tap/.tzx codecs and the
+// pulse encoder, since the same machine loads the tape.
+import { FRAME_T_STATES } from "@zx-vibes/ula";
+
+// The ROM tape-load entry point. The DNA references ONLY this address of the opaque
+// ROM (ADR-0024); no other ROM routine is documented.
+export const LD_BYTES_ENTRY = 0x0556;
+
+// Z80 F-register carry bit (TAPE-EDGE-LDBYTES-001: CARRY set on entry = LOAD).
+const CARRY = 0x01;
+
+// A generous default ceiling so a wrong register setup or a broken deck can never
+// hang: a full data block is ~7M T-states of leader; 50M T covers a large block with
+// headroom. Exceeding the budget is a load failure, never a spin (risk guard).
+const DEFAULT_T_STATE_BUDGET = 50_000_000;
+
+// Stack the loader runs on (high RAM, clear of a 0x4000+ destination). LD-BYTES pushes
+// its own SA/LD-RET return plus a couple of saves; this leaves ample room below.
+const STACK_TOP = 0xff58;
+
+// A return address the ROM never sets PC to during a load; pushed as the sentinel so
+// the loader's final RET lands here and the run loop stops (TAPE-EDGE-LDBYTES-001).
+const DEFAULT_SENTINEL = 0x7fff;
+
+// TAPE-EDGE-TRAILING-001: a block's data pulses end on the second pulse of the
+// checksum's last bit; the loader reads each bit as one full period (two edges), so the
+// FINAL bit needs a closing edge AFTER the last pulse. On a real tape that edge is the
+// leading transition of the inter-block pause (TZX 0x20). `edgeLoad` therefore appends one
+// trailing pulse — a ~1 ms pause segment (3500 T at 3.5 MHz) — so the line transitions
+// once after the block and the loader detects the end of the final bit. Its exact length
+// is not load-bearing (any closing edge works); only that the transition occurs.
+const TRAILING_EDGE_PULSE_T = 3500;
+
+// TAPE-EDGE-DECK-001 / HOST-IO-PORTFE-READ-BITS-001: a "tape deck" implementing the
+// machine `io` contract { read(port), write(port, value) }. On a port-0xFE read (ULA:
+// address bit A0 = 0) it returns the keyboard/idle byte with bit 6 driven from the tape
+// level at the current tape clock. The deck holds the pulse list and a MONOTONIC tape
+// T-state cursor (supplied by `clock`); the level toggles at every pulse boundary from a
+// fixed start convention. Once the cursor runs past the last pulse the tape is silent and
+// bit 6 falls back to the issue-3 idle rule: it tracks the last bit-4 (speaker/EAR-out)
+// written to port 0xFE.
+export function createTapeDeck(pulses, { clock, startLevel = 0, keyboard = 0x1f } = {}) {
+  if (typeof clock !== "function") {
+    throw new Error("createTapeDeck: a clock() returning the tape T-state cursor is required");
+  }
+  const durations = pulses instanceof Uint16Array || pulses instanceof Array ? pulses : Array.from(pulses ?? []);
+  // ends[i] = cumulative T-state at which pulse i finishes; pulse i spans [ends[i-1], ends[i]).
+  const ends = new Array(durations.length);
+  let acc = 0;
+  for (let i = 0; i < durations.length; i += 1) {
+    acc += durations[i];
+    ends[i] = acc;
+  }
+  const total = acc;
+  const start = startLevel & 1;
+  // Issue-3 idle level (the EAR-in level when the tape is not driving the line): the last
+  // value written to bit 4 of port 0xFE. Initialized to the tape's start level.
+  let idleLevel = start;
+
+  // The tape-in level at tape clock `t`. Within the stream the level is the start level
+  // XOR the parity of the pulse index; past the end it is the issue-3 idle level.
+  function levelAt(t) {
+    if (durations.length === 0 || t >= total) return idleLevel;
+    // Smallest i with ends[i] > t — the index of the pulse covering t.
+    let lo = 0;
+    let hi = ends.length - 1;
+    while (lo < hi) {
+      const mid = (lo + hi) >> 1;
+      if (ends[mid] > t) hi = mid;
+      else lo = mid + 1;
+    }
+    return (start ^ (lo & 1)) & 1;
+  }
+
+  return {
+    levelAt,
+    total,
+    read(port) {
+      // Only the ULA (even port, A0 = 0) answers; other ports float high.
+      if ((port & 0x01) !== 0) return 0xff;
+      const level = levelAt(clock());
+      // HOST-IO-PORTFE-READ-BITS-001: b0–b4 keyboard (1 = released), b5/b7 = 1 (unused),
+      // b6 = EAR/tape-in level.
+      return ((keyboard & 0x1f) | 0xa0 | (level ? 0x40 : 0x00)) & 0xff;
+    },
+    write(port, value) {
+      // Issue-3 idle rule: bit 6 idles at the last bit-4 (EAR-out) written to port 0xFE.
+      if ((port & 0x01) === 0) idleLevel = (value >> 4) & 1;
+    },
+  };
+}
+
+// TAPE-EDGE-LDBYTES-001: set up the LD-BYTES register contract on `machine`, push the
+// sentinel return, and run the machine instruction-by-instruction until PC returns to the
+// sentinel (success/failure) or the T-state budget is hit. `deck` (already the machine's
+// io) supplies the tape edge stream. Returns { ok, reason, bytesLoaded, tStates }; ok is
+// the CARRY flag the ROM reports (set = the block loaded and its checksum verified).
+export function edgeLoadWithDeck(machine, deck, { ix, de, flag, load = true, tStateBudget = DEFAULT_T_STATE_BUDGET, sentinel = DEFAULT_SENTINEL } = {}) {
+  if (typeof ix !== "number" || typeof de !== "number" || typeof flag !== "number") {
+    throw new Error("edgeLoadWithDeck: ix, de and flag are required numbers");
+  }
+  machine.io = deck;
+  const reg = machine.registers;
+  // Entry contract: A = expected flag byte, CARRY set = LOAD (reset = VERIFY). LD-BYTES
+  // moves the entry AF into AF' (EX AF,AF'); set both so the flag/carry reach AF'
+  // regardless of the exchange.
+  const entryF = load ? CARRY : 0;
+  reg.a = flag & 0xff;
+  reg.f = entryF;
+  reg.a_ = flag & 0xff;
+  reg.f_ = entryF;
+  // IX = destination, DE = data byte count.
+  reg.ixh = (ix >> 8) & 0xff;
+  reg.ixl = ix & 0xff;
+  reg.d = (de >> 8) & 0xff;
+  reg.e = de & 0xff;
+  // The ROM disables interrupts itself (DI); keep them off so the direct call is clean.
+  reg.iff1 = 0;
+  reg.iff2 = 0;
+  // Push the sentinel return address, then enter LD-BYTES.
+  machine.memory[(STACK_TOP - 1) & 0xffff] = (sentinel >> 8) & 0xff;
+  machine.memory[(STACK_TOP - 2) & 0xffff] = sentinel & 0xff;
+  reg.sp = (STACK_TOP - 2) & 0xffff;
+  reg.pc = LD_BYTES_ENTRY;
+
+  const startRun = machine.tStatesTotal;
+  while ((machine.registers.pc & 0xffff) !== (sentinel & 0xffff)) {
+    if (machine.tStatesTotal - startRun > tStateBudget) {
+      return { ok: false, reason: "budget", bytesLoaded: 0, tStates: machine.tStatesTotal - startRun };
+    }
+    machine.stepInstruction();
+  }
+  const ok = Boolean(machine.registers.f & CARRY);
+  const deLeft = ((machine.registers.d & 0xff) << 8) | (machine.registers.e & 0xff);
+  return {
+    ok,
+    reason: ok ? "ok" : "load-error",
+    bytesLoaded: (de - deLeft) & 0xffff,
+    tStates: machine.tStatesTotal - startRun,
+  };
+}
+
+// TAPE-EDGE-LOAD-001: the convenience entry. Build the standard tape deck (a MONOTONIC
+// tape cursor that advances with the machine's executed T-states — not a frame-modulo
+// position, which would lose edges across a frame wrap) over `pulses`, wire it as the
+// machine's io, and drive LD-BYTES. `pulses` is the EAR pulse stream of a single block
+// body (blockToPulses); `de` is the data byte count (the body length minus the flag and
+// checksum), `flag` the block's flag byte, `ix` the RAM destination.
+export function edgeLoad(machine, pulses, { ix, de, flag, load = true, tStateBudget = DEFAULT_T_STATE_BUDGET, sentinel = DEFAULT_SENTINEL, startLevel = 0, keyboard = 0x1f, trailingPulse = TRAILING_EDGE_PULSE_T } = {}) {
+  const startT = machine.tStatesTotal;
+  // Append the closing edge (TAPE-EDGE-TRAILING-001) so the final bit terminates.
+  const base = pulses instanceof Array ? pulses : Array.from(pulses ?? []);
+  const playable = trailingPulse ? [...base, trailingPulse] : base;
+  const deck = createTapeDeck(playable, {
+    clock: () => machine.tStatesTotal - startT,
+    startLevel,
+    keyboard,
+  });
+  return edgeLoadWithDeck(machine, deck, { ix, de, flag, load, tStateBudget, sentinel });
+}
+
+// TAPE-INSTANT-LOAD-001: the instant (a.k.a. trap / flash) loader. A consumer convenience
+// that reproduces the OBSERVABLE result of `edgeLoad` (the real ROM `LD-BYTES`) for the same
+// tape block WITHOUT executing the ROM or simulating the pulse stream — it traps the load and
+// writes the block's data bytes straight to RAM. Its whole correctness criterion is
+// `instant == edge` for the same `.tap` block (TAPE-INSTANT-EQUIV-001): a mutual cross-check
+// against the real ROM, fabrication-free. `body` is the full block body
+// `[flag, ...data, checksum]` (the same input `blockToPulses` takes); `ix`/`de`/`flag` are
+// the LD-BYTES register contract (TAPE-EDGE-LDBYTES-001): IX = destination, DE = data byte
+// count, A = expected flag. Returns `{ ok, reason, bytesLoaded, tStates }` with `tStates = 0`
+// (instant — no machine time elapses). Only the OBSERVABLE triplet — `ok` (the CARRY result),
+// `bytesLoaded`, and the bytes written to RAM — is the contract and matches `edgeLoad`; the
+// `reason` string is the instant loader's own diagnosis and is NOT part of the contract (the
+// real ROM may instead time out or report a generic load error for the same failure).
+export function instantLoad(machine, body, { ix, de, flag, load = true } = {}) {
+  if (typeof ix !== "number" || typeof de !== "number" || typeof flag !== "number") {
+    throw new Error("instantLoad: ix, de and flag are required numbers");
+  }
+  const bytes = body instanceof Uint8Array || Array.isArray(body) ? body : Array.from(body ?? []);
+  const expectedFlag = flag & 0xff;
+  const dest = ix & 0xffff;
+  const want = de & 0xffff;
+  // The block body is [flag][data…][checksum]; a body shorter than 2 bytes has no checksum.
+  if (bytes.length < 2) {
+    return { ok: false, reason: "empty", bytesLoaded: 0, tStates: 0 };
+  }
+  const blockFlag = bytes[0] & 0xff;
+  // TAPE-INSTANT-FLAG-001: LD-BYTES compares the flag byte BEFORE storing any data; on a flag
+  // mismatch it returns failure with NOTHING written (verified against the real ROM: a
+  // mismatched edge-load leaves the destination RAM untouched and returns carry reset).
+  if (blockFlag !== expectedFlag) {
+    return { ok: false, reason: "flag-mismatch", bytesLoaded: 0, tStates: 0 };
+  }
+  // Data bytes present in the block body (everything between the flag and the final checksum).
+  const dataAvailable = bytes.length - 2;
+  const n = Math.min(want, Math.max(0, dataAvailable));
+  // TAPE-INSTANT-LOAD-001 / TAPE-INSTANT-CHECKSUM-001: store the DE data bytes (the flag and
+  // checksum are NOT stored, TAPE-EDGE-LDBYTES-001) while accumulating the running XOR parity
+  // over the flag + the data bytes + the checksum byte read after them
+  // (file-formats.md FMT-TAP-CHECKSUM-001). CARRY/ok is set iff the parity is zero.
+  let parity = blockFlag;
+  for (let i = 0; i < n; i += 1) {
+    const value = bytes[1 + i] & 0xff;
+    if (load) machine.memory[(dest + i) & 0xffff] = value;
+    parity ^= value;
+  }
+  // The byte LD-BYTES reads as the checksum after exactly DE data bytes.
+  parity ^= bytes[1 + want] & 0xff;
+  const ok = parity === 0;
+  return { ok, reason: ok ? "ok" : "checksum-error", bytesLoaded: n, tStates: 0 };
+}
+
+// Re-exported so a regeneration / self-test can build a frame-modulo (broken) tape clock
+// to prove the monotonic cursor is load-bearing (TAPE-EDGE-DECK-001).
+export { FRAME_T_STATES };

package/src/tape-pulses.d.mts

@@ -0,0 +1,9 @@
+export function bytePulses(byte: any): number[];
+export function blockToPulses(bytes: any): any[];
+export const PILOT_PULSE_T: 2168;
+export const PILOT_PULSES_HEADER: 8063;
+export const PILOT_PULSES_DATA: 3223;
+export const SYNC1_T: 667;
+export const SYNC2_T: 735;
+export const BIT0_PULSE_T: 855;
+export const BIT1_PULSE_T: 1710;

package/src/tape-pulses.mjs

@@ -0,0 +1,60 @@
+// Regenerated ROM tape-encoding model, authored from the project DNA
+// (dna/domain/tape-loading.md "The EAR pulse stream") and decided by the tape
+// conformance fixtures (dna/conformance/tape/tape-pulses.json). A tape block body
+// ([flag][data…][checksum]) is transmitted as a sequence of EAR pulses (durations in
+// Z80 T-states; the tape-in line, port 0xFE bit 6, toggles each pulse): a pilot tone,
+// a sync pair, then each byte MSB-first as two pulses per bit. Same machine loads the
+// tape, so this lives beside the .tap/.tzx codecs.
+
+// TAPE-PULSE-TIMINGS-001 / TAPE-PULSE-PILOT-001: fixed pulse durations (T-states at
+// 3.5 MHz), identical to the TZX v1.20 turbo-block defaults.
+export const PILOT_PULSE_T = 2168;
+export const PILOT_PULSES_HEADER = 8063; // flag < 0x80 (~5 s leader)
+export const PILOT_PULSES_DATA = 3223; // flag >= 0x80 (~2 s leader)
+export const SYNC1_T = 667;
+export const SYNC2_T = 735;
+export const BIT0_PULSE_T = 855;
+export const BIT1_PULSE_T = 1710;
+
+const HEADER_FLAG_MAX = 0x80; // flag < 0x80 => header pilot length
+
+// TAPE-PULSE-DATA-001: one byte -> 16 pulses, most-significant bit first; a 0 bit is
+// two 855 T pulses, a 1 bit is two 1710 T pulses.
+export function bytePulses(byte) {
+  const pulses = [];
+  for (let bit = 7; bit >= 0; bit -= 1) {
+    const length = (byte >> bit) & 1 ? BIT1_PULSE_T : BIT0_PULSE_T;
+    pulses.push(length, length);
+  }
+  return pulses;
+}
+
+// TAPE-PULSE-BLOCK-001: full pulse list for a block body. `bytes` is the on-tape body
+// [flag, ...data, checksum]. Pilot count is chosen by the flag (bytes[0]); then sync1,
+// sync2, then each byte's data pulses.
+export function blockToPulses(bytes) {
+  const body = bytes instanceof Uint8Array ? bytes : Uint8Array.from(bytes);
+  if (body.length === 0) {
+    throw new Error("blockToPulses: empty block body (need at least a flag byte)");
+  }
+  const flag = body[0] & 0xff;
+  const pilotCount = flag < HEADER_FLAG_MAX ? PILOT_PULSES_HEADER : PILOT_PULSES_DATA;
+
+  const pulses = new Array(pilotCount + 2 + body.length * 16);
+  let i = 0;
+  // TAPE-PULSE-PILOT-001: pilot tone.
+  for (let p = 0; p < pilotCount; p += 1) pulses[i++] = PILOT_PULSE_T;
+  // TAPE-PULSE-SYNC-001: the sync pair, in order.
+  pulses[i++] = SYNC1_T;
+  pulses[i++] = SYNC2_T;
+  // TAPE-PULSE-DATA-001: every body byte, MSB first.
+  for (let b = 0; b < body.length; b += 1) {
+    const byte = body[b] & 0xff;
+    for (let bit = 7; bit >= 0; bit -= 1) {
+      const length = (byte >> bit) & 1 ? BIT1_PULSE_T : BIT0_PULSE_T;
+      pulses[i++] = length;
+      pulses[i++] = length;
+    }
+  }
+  return pulses;
+}

package/src/tzx-format.d.mts

@@ -0,0 +1,13 @@
+export function parseTzx(bytes: any): {
+    version: {
+        major: number;
+        minor: number;
+    };
+    blocks: any[];
+};
+export function serializeTzx(tzx: any): Uint8Array<ArrayBuffer>;
+export const TZX_SIGNATURE: "ZXTape!";
+export namespace TZX_VERSION {
+    let major: number;
+    let minor: number;
+}