jsbeeb 1.22.4 → 1.24.0

package/src/loader.js

@@ -0,0 +1,63 @@
+import { stringToUint8Array } from "./binary.js";
+
+export const runningInNode = typeof window === "undefined";
+
+function loadDataHttp(url) {
+    return new Promise(function (resolve, reject) {
+        const request = new XMLHttpRequest();
+        request.open("GET", url, true);
+        request.overrideMimeType("text/plain; charset=x-user-defined");
+        request.onload = function () {
+            if (request.status !== 200) {
+                reject(new Error("Unable to load " + url + ", http code " + request.status));
+                return;
+            }
+            if (typeof request.response !== "string") {
+                resolve(request.response);
+            } else {
+                resolve(stringToUint8Array(request.response));
+            }
+        };
+        request.onerror = function () {
+            reject(new Error("A network error occurred loading " + url));
+        };
+        request.send(null);
+    });
+}
+
+let _nodeBasePath = null;
+
+export function setNodeBasePath(basePath) {
+    _nodeBasePath = basePath;
+}
+
+async function loadDataNode(url) {
+    if (url.startsWith("file:")) {
+        const fs = await import("fs");
+        const { fileURLToPath } = await import("url");
+        return fs.readFileSync(fileURLToPath(url));
+    }
+    if (/^https?:\/\//.test(url)) {
+        const response = await fetch(url);
+        if (!response.ok) throw new Error(`Unable to load ${url}, http code ${response.status}`);
+        return new Uint8Array(await response.arrayBuffer());
+    }
+    const fs = await import("fs");
+    const nodePath = await import("path");
+    if (_nodeBasePath) {
+        const publicPath = nodePath.join(_nodeBasePath, "public", url);
+        if (fs.existsSync(publicPath)) return fs.readFileSync(publicPath);
+        return fs.readFileSync(nodePath.join(_nodeBasePath, url));
+    }
+    if (url[0] === "/") url = "." + url;
+    if (fs.existsSync("public/" + url)) return fs.readFileSync("public/" + url);
+    return fs.readFileSync(url);
+}
+
+export function loadData(url) {
+    if (runningInNode) {
+        return loadDataNode(url);
+    } else {
+        return loadDataHttp(url);
+    }
+}

package/src/machine-session.js

@@ -8,7 +8,8 @@
 import { readFileSync } from "fs";
 import { fileURLToPath } from "url";
 import path from "path";
-import { TestMachine } from "../tests/test-machine.js";
+import { TestMachine } from "./test-machine.js";
+import { VduTextCapture } from "./vdu-capture.js";
 import { InstrumentedSoundChip, FakeSoundChip } from "./soundchip.js";
 
 // Resolve the jsbeeb package root from our own location (src/machine-session.js
@@ -16,10 +17,12 @@ import { InstrumentedSoundChip, FakeSoundChip } from "./soundchip.js";
 // files relative to this package regardless of the calling process's cwd.
 const _jsbeebRoot = path.dirname(path.dirname(fileURLToPath(import.meta.url)));
 import * as fdc from "./fdc.js";
+import { MediaResolver } from "./media-resolver.js";
+import { StairwayToHell } from "./sth.js";
+import { BbcDiscArchive } from "./bbcdiscs.js";
 import { Video } from "./video.js";
 import { findModel } from "./models.js";
-import { setNodeBasePath } from "./utils.js";
-import sharp from "sharp";
+import { setNodeBasePath } from "./loader.js";
 
 // BBC framebuffer is 1024×625 pixels
 const FB_WIDTH = 1024;
@@ -86,7 +89,7 @@ export class MachineSession {
 
         // Accumulated VDU text output, drained by callers
         this._pendingOutput = [];
-        this._flushCapture = () => {};
+        this._capture = new VduTextCapture((element) => this._pendingOutput.push(element), { isAtom: this._isAtom });
 
         // Breakpoint management, with persistent hooks that survive across run calls
         this._breakpoints = new Map(); // id → { hook, type, address, hit }
@@ -100,7 +103,7 @@ export class MachineSession {
         if (this._opts.discImage) {
             this.loadDisc(this._opts.discImage);
         }
-        this._installCaptureHook();
+        this._machine.onVduChar((c) => this._capture.onChar(c));
     }
 
     /**
@@ -112,170 +115,6 @@ export class MachineSession {
         return this.drainOutput();
     }
 
-    /**
-     * Install the VDU character-output capture hook.
-     *
-     * WRCHV discovery: RAM at the OS write-character vector (0x20E on BBC,
-     * 0x208 on Atom) initialises to 0x0000 before the OS runs.  We read
-     * directly from cpu.ramRomOs (two array lookups, no readmem() dispatch
-     * overhead) on every instruction, waiting for the value to change from
-     * its initial 0xFFFF.  Once the OS installs a real handler we use that
-     * address for the lifetime of the session.  Programs that later install
-     * a custom VDU driver are handled seamlessly because we always re-read
-     * from the live memory.
-     *
-     * Text elements: { x, y, text, foreground, background, mode }
-     * Screenshots (via the real Video chip) are the right tool for anything
-     * visual; this capture is a lightweight aid for text-mode output only.
-     */
-    _installCaptureHook() {
-        const cpu = this._machine.processor;
-        const ram = cpu.ramRomOs; // direct Uint8Array, no dispatch overhead
-        // WRCHV vector: BBC at $020E, Atom at $0208.
-        const wrchvAddr = this._isAtom ? 0x208 : 0x20e;
-        const initialWrchv = ram[wrchvAddr] | (ram[wrchvAddr + 1] << 8); // 0xFFFF pre-boot
-
-        const attributes = { x: 0, y: 0, text: "", foreground: 7, background: 0, mode: 7 };
-        let currentText = "";
-        let params = [];
-        let nextN = 0;
-        let vduProc = null;
-
-        const onElement = (elem) => this._pendingOutput.push({ ...elem });
-
-        function flush() {
-            if (currentText.length) {
-                attributes.text = currentText;
-                onElement({ ...attributes });
-                attributes.x += currentText.length;
-            }
-            currentText = "";
-        }
-
-        // Expose flush so drainOutput can capture trailing text
-        // that hasn't been terminated by a control character.
-        this._flushCapture = flush;
-
-        // Expose the decoder's cursor so snapshot()/restore() can rewind it too:
-        // text captured after a restore would otherwise carry the coordinates
-        // and colours the abandoned run had reached.
-        this._snapshotCapture = () => ({
-            attributes: { ...attributes },
-            currentText,
-            params: [...params],
-            nextN,
-        });
-        this._restoreCapture = (state) => {
-            Object.assign(attributes, state.attributes);
-            currentText = state.currentText;
-            params = [...state.params];
-            nextN = state.nextN;
-            // vduProc is a closure and does not survive, so a snapshot taken
-            // mid-sequence resumes with nextN still swallowing the parameters:
-            // the sequence is dropped rather than printed as text.
-            vduProc = null;
-        };
-
-        const isAtom = this._isAtom;
-
-        function onChar(c) {
-            if (nextN) {
-                params.push(c);
-                if (--nextN === 0) {
-                    if (vduProc) vduProc(params);
-                    params = [];
-                    vduProc = null;
-                }
-                return;
-            }
-            switch (c) {
-                case 10: // LF
-                    flush();
-                    attributes.y++;
-                    break;
-                case 12: // CLS
-                    flush();
-                    attributes.x = 0;
-                    attributes.y = 0;
-                    break;
-                case 13: // CR
-                    flush();
-                    attributes.x = 0;
-                    break;
-                default:
-                    // BBC VDU control codes (multi-byte sequences).
-                    // The Atom doesn't use these; skip them to avoid
-                    // swallowing printable characters.
-                    if (!isAtom) {
-                        switch (c) {
-                            case 1: // next char to printer only
-                                nextN = 1;
-                                return;
-                            case 17: // COLOUR n
-                                nextN = 1;
-                                vduProc = (p) => {
-                                    if (p[0] & 0x80) attributes.background = p[0] & 0xf;
-                                    else attributes.foreground = p[0] & 0xf;
-                                };
-                                return;
-                            case 18: // GCOL
-                                nextN = 2;
-                                return;
-                            case 19: // define logical colour
-                                nextN = 5;
-                                return;
-                            case 22: // MODE n
-                                nextN = 1;
-                                vduProc = (p) => {
-                                    flush();
-                                    attributes.mode = p[0];
-                                    attributes.x = 0;
-                                    attributes.y = 0;
-                                    attributes.foreground = 7;
-                                    attributes.background = 0;
-                                };
-                                return;
-                            case 25: // PLOT
-                                nextN = 5;
-                                return;
-                            case 28: // define text window
-                                nextN = 4;
-                                return;
-                            case 29: // define graphics origin
-                                nextN = 4;
-                                return;
-                            case 31: // TAB(x,y)
-                                nextN = 2;
-                                vduProc = (p) => {
-                                    flush();
-                                    attributes.x = p[0];
-                                    attributes.y = p[1];
-                                };
-                                return;
-                        }
-                    }
-                    if (c >= 32 && c < 0x7f) {
-                        currentText += String.fromCharCode(c);
-                    } else {
-                        flush();
-                    }
-                    break;
-            }
-        }
-
-        cpu.debugInstruction.add((addr) => {
-            // Two direct array reads, no function-call dispatch overhead.
-            // Once the OS sets WRCHV (it changes from 0xFFFF), we start
-            // capturing.  Programs that install a custom VDU driver mid-run
-            // are handled transparently because we re-read on every call.
-            const wrchv = ram[wrchvAddr] | (ram[wrchvAddr + 1] << 8);
-            if (wrchv !== initialWrchv && addr === wrchv) {
-                onChar(cpu.a);
-            }
-            return false;
-        });
-    }
-
     /**
      * Press a key (by browser keyCode).
      * Use utils.keyCodes for named keys, or ASCII charCode for letters/digits.
@@ -313,7 +152,7 @@ export class MachineSession {
         return {
             machine: this._machine.snapshot({ includeRoms }),
             pendingOutput: this._pendingOutput.map((element) => ({ ...element })),
-            capture: this._snapshotCapture(),
+            capture: this._capture.snapshot(),
         };
     }
 
@@ -326,7 +165,7 @@ export class MachineSession {
     restore(state) {
         this._machine.restore(state.machine);
         this._pendingOutput = state.pendingOutput.map((element) => ({ ...element }));
-        this._restoreCapture(state.capture);
+        this._capture.restore(state.capture);
     }
 
     /** Tokenise BBC BASIC source and write it into PAGE */
@@ -364,10 +203,9 @@ export class MachineSession {
         await this._machine.runFor(cycles);
     }
 
-    /** Emulated cycles since power-on, undoing the per-second rebasing execute() applies */
+    /** Emulated cycles since power-on */
     get elapsedCycles() {
-        const cpu = this._machine.processor;
-        return cpu.cycleSeconds * cpu.model.cyclesPerSecond + cpu.currentCycles;
+        return this._machine.elapsedCycles;
     }
 
     /**
@@ -516,8 +354,28 @@ export class MachineSession {
      */
     loadDisc(imagePath) {
         const data = new Uint8Array(readFileSync(imagePath));
-        const machineFdc = this._machine.processor.fdc;
-        machineFdc.loadDisc(0, fdc.discFor(machineFdc, imagePath, data));
+        this._machine.processor.fdc.loadDisc(0, fdc.discFor(imagePath, data));
+    }
+
+    /**
+     * Put a disc in a drive by any reference the web page's URL accepts: a bare
+     * name from the built-in discs, `sth:` or `hfe:` for the archives, or a URL.
+     * Returns the name of the image loaded and any others the archive held.
+     */
+    async loadDiscImage(ref, drive = 0) {
+        const { name, data, ignored } = await this.mediaResolver().resolve("disc", ref);
+        this._machine.processor.fdc.loadDisc(drive, fdc.discFor(name, data));
+        return { name, ignored };
+    }
+
+    mediaResolver() {
+        if (!this._mediaResolver) {
+            const quiet = () => {};
+            this._mediaResolver = new MediaResolver();
+            this._mediaResolver.addSource("sth", (file) => new StairwayToHell(quiet, quiet, quiet).fetch(file));
+            this._mediaResolver.addSource("hfe", (path) => new BbcDiscArchive(quiet, quiet, quiet).fetch(path));
+        }
+        return this._mediaResolver;
     }
 
     /**
@@ -532,7 +390,7 @@ export class MachineSession {
      * Also includes a flat `screenText` reconstruction.
      */
     drainOutput({ clear = true } = {}) {
-        this._flushCapture();
+        this._capture.flush();
         const elements = clear ? this._pendingOutput.splice(0) : [...this._pendingOutput];
         return {
             elements,
@@ -585,6 +443,7 @@ export class MachineSession {
     async screenshot() {
         // Read from _completeFb8, the last fully-painted frame snapshotted in paint_ext.
         // _fb8/_fb32 is the live render buffer (cleared and partially refilled each frame).
+        const { default: sharp } = await import("sharp");
         return sharp(Buffer.from(this._completeFb8.buffer), {
             raw: { width: FB_WIDTH, height: FB_HEIGHT, channels: 4 },
         })
@@ -609,6 +468,7 @@ export class MachineSession {
         const w = FB_WIDTH - left - right;
         const h = FB_HEIGHT - top - bottom;
 
+        const { default: sharp } = await import("sharp");
         return sharp(Buffer.from(this._completeFb8.buffer), {
             raw: { width: FB_WIDTH, height: FB_HEIGHT, channels: 4 },
         })

package/src/machine-spec.js

@@ -0,0 +1,59 @@
+import { Cmos } from "./cmos.js";
+import { FakeDdNoise } from "./ddnoise.js";
+import { FakeMusic5000 } from "./music5000.js";
+import { FakeRelayNoise } from "./relaynoise.js";
+import { FakeSoundChip } from "./soundchip.js";
+import { FakeVideo } from "./video.js";
+
+const NullUserPort = {
+    write() {},
+    read() {
+        return 0xff;
+    },
+};
+
+const SpecDefaults = {
+    keyLayout: "physical",
+    cpuMultiplier: 1,
+    tubeCpuMultiplier: 1,
+    videoCyclesBatch: 0,
+    tube: null,
+    hasMusic5000: false,
+    hasTeletextAdaptor: false,
+    extraRoms: [],
+    userPort: NullUserPort,
+    printerPort: null,
+    getGamepads: () => [],
+    debugFlags: { logFdcCommands: false, logFdcStateChanges: false },
+};
+
+/**
+ * What a machine is fitted with and how it is driven, complete and frozen:
+ * every field is present, an unknown one is an error, and an undefined
+ * override means the default. It is the `config` a CPU is built with.
+ */
+export function machineSpec(overrides = {}) {
+    const unknown = Object.keys(overrides).filter((field) => !Object.hasOwn(SpecDefaults, field));
+    if (unknown.length) throw new Error(`Unknown machine spec fields: ${unknown.join(", ")}`);
+    const given = Object.fromEntries(Object.entries(overrides).filter(([, value]) => value !== undefined));
+    return Object.freeze({
+        ...SpecDefaults,
+        ...given,
+        extraRoms: Object.freeze([...(given.extraRoms ?? SpecDefaults.extraRoms)]),
+        debugFlags: Object.freeze({ ...SpecDefaults.debugFlags, ...given.debugFlags }),
+    });
+}
+
+/** Peripherals that go nowhere, for a machine run headless. */
+export function nullIo({ video = new FakeVideo(), soundChip = new FakeSoundChip() } = {}) {
+    return {
+        dbgr: { setCpu() {} },
+        video,
+        soundChip,
+        ddNoise: new FakeDdNoise(),
+        relayNoise: new FakeRelayNoise(),
+        music5000: new FakeMusic5000(),
+        cmos: new Cmos(),
+        econet: null,
+    };
+}