jsbeeb 1.21.0 → 1.22.1

package/package.json

@@ -7,7 +7,7 @@
   "name": "jsbeeb",
   "description": "Emulate a BBC Micro",
   "repository": "git@github.com:mattgodbolt/jsbeeb.git",
-  "version": "1.21.0",
+  "version": "1.22.1",
   "//engines": "If you change the version of Node, it must also be updated at the top of the Dockerfile.",
   "engines": {
     "node": ">=24.15.0"
@@ -114,7 +114,8 @@
     "mirror-bbcdiscs:upload:blobs": "aws s3 sync .bbcdiscs-mirror/hfe s3://bbc.xania.org/archive/bbcdiscs/hfe/ --no-progress --exclude 'manifest.json' --delete --content-encoding br --cache-control 'public, max-age=31536000, immutable'",
     "mirror-bbcdiscs:upload:index": "aws s3 cp .bbcdiscs-mirror/hfe/manifest.json s3://bbc.xania.org/archive/bbcdiscs/hfe/manifest.json --cache-control 'public, max-age=300' && aws s3 cp .bbcdiscs-mirror/manifest.json s3://bbc.xania.org/archive/bbcdiscs/manifest.json --cache-control 'public, max-age=300'",
     "electron": "npm run build && ELECTRON_DISABLE_SANDBOX=1 electron .",
-    "electron:build": "electron-builder"
+    "electron:build": "electron-builder",
+    "test:smoke": "npm run build && node tests/browser/smoke.js"
   },
   "lint-staged": {
     "*.js": [

package/src/basic-loader.js

@@ -0,0 +1,20 @@
+"use strict";
+
+/**
+ * Pokes a tokenised BASIC program into memory at PAGE, and sets TOP and
+ * VARTOP after it, exactly as if it had just been typed.
+ */
+export function installBasic(tokenised, { readByte, writeByte }) {
+    const page = readByte(0x18) << 8;
+    for (let i = 0; i < tokenised.length; ++i) {
+        writeByte(page + i, tokenised.charCodeAt(i));
+    }
+    // Set VARTOP (0x12/3) and TOP(0x02/3)
+    const end = page + tokenised.length;
+    const endLow = end & 0xff;
+    const endHigh = (end >>> 8) & 0xff;
+    writeByte(0x02, endLow);
+    writeByte(0x03, endHigh);
+    writeByte(0x12, endLow);
+    writeByte(0x13, endHigh);
+}

package/src/dom-utils.js

@@ -1,5 +1,7 @@
 "use strict";
 
+import { replaceOrAddExtension } from "./utils.js";
+
 // Minimal DOM helpers to replace jQuery usage.
 
 export function show(el) {
@@ -46,3 +48,9 @@ export function downloadBlob(blob, fileName) {
     a.remove();
     setTimeout(() => URL.revokeObjectURL(url), BlobUrlLifetimeMs);
 }
+
+/** Save raw image bytes under the disc's name with the extension of the format they are in. */
+export function downloadDriveData(data, name, extension) {
+    const blob = new Blob([data], { type: "application/octet-stream" });
+    downloadBlob(blob, replaceOrAddExtension(name, extension));
+}

package/src/machine-session.js

@@ -41,9 +41,9 @@ export class MachineSession {
         this.modelName = modelName;
         this._opts = opts;
 
-        // Raw RGBA framebuffer — the Video chip renders into _fb32 (cleared each frame).
+        // Raw RGBA framebuffer. The Video chip renders into _fb32 (cleared each frame).
         // _completeFb8 is a snapshot taken at paint time (the equivalent of the browser canvas)
-        // and is what screenshot() reads from — always a complete frame, never mid-render.
+        // and is what screenshot() reads from, always a complete frame, never mid-render.
         this._fb8 = new Uint8Array(FB_WIDTH * FB_HEIGHT * 4);
         this._fb32 = new Uint32Array(this._fb8.buffer);
         this._completeFb8 = new Uint8Array(FB_WIDTH * FB_HEIGHT * 4);
@@ -84,16 +84,16 @@ export class MachineSession {
             hasTeletextAdaptor: opts.hasTeletextAdaptor,
         });
 
-        // Accumulated VDU text output — drained by callers
+        // Accumulated VDU text output, drained by callers
         this._pendingOutput = [];
         this._flushCapture = () => {};
 
-        // Breakpoint management — persistent hooks that survive across run calls
+        // Breakpoint management, with persistent hooks that survive across run calls
         this._breakpoints = new Map(); // id → { hook, type, address, hit }
         this._nextBreakpointId = 1;
     }
 
-    /** Load ROMs and hardware — call once before anything else */
+    /** Load ROMs and hardware; call once before anything else */
     async initialise() {
         setNodeBasePath(_jsbeebRoot);
         await this._machine.initialise();
@@ -117,12 +117,12 @@ export class MachineSession {
      *
      * 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.
+     * 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
@@ -130,7 +130,7 @@ export class MachineSession {
      */
     _installCaptureHook() {
         const cpu = this._machine.processor;
-        const ram = cpu.ramRomOs; // direct Uint8Array — no dispatch overhead
+        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
@@ -156,6 +156,26 @@ export class MachineSession {
         // 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) {
@@ -244,7 +264,7 @@ export class MachineSession {
         }
 
         cpu.debugInstruction.add((addr) => {
-            // Two direct array reads — no function-call dispatch overhead.
+            // 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.
@@ -280,6 +300,35 @@ export class MachineSession {
         this._pendingOutput = [];
     }
 
+    /**
+     * Capture machine state and captured text as an opaque object for restore().
+     * Leaves the running session undisturbed.
+     *
+     * @param {Object} [opts]
+     * @param {boolean} [opts.includeRoms=true] - carry the ROM contents too.
+     *   Only safe to omit when restoring into a session built from the same
+     *   model, which is then left with whatever ROMs it already had.
+     */
+    snapshot({ includeRoms = true } = {}) {
+        return {
+            machine: this._machine.snapshot({ includeRoms }),
+            pendingOutput: this._pendingOutput.map((element) => ({ ...element })),
+            capture: this._snapshotCapture(),
+        };
+    }
+
+    /**
+     * Put back a state from snapshot().  `elapsedCycles` rewinds with the
+     * machine; breakpoints belong to the session, not the machine, so they and
+     * their hit flags are left alone, and `frameCount` keeps counting the way it
+     * does across a hard reset.
+     */
+    restore(state) {
+        this._machine.restore(state.machine);
+        this._pendingOutput = state.pendingOutput.map((element) => ({ ...element }));
+        this._restoreCapture(state.capture);
+    }
+
     /** Tokenise BBC BASIC source and write it into PAGE */
     async loadBasic(source) {
         await this._machine.loadBasic(source);
@@ -476,7 +525,7 @@ export class MachineSession {
      *
      * @param {Object} [opts]
      * @param {boolean} [opts.clear=true] - If true (default), clear the buffer
-     *   after returning it.  Pass false to peek without consuming — the same
+     *   after returning it.  Pass false to peek without consuming; the same
      *   elements will be returned again on the next call.
      *
      * Each element: { x, y, text, foreground, background, mode }
@@ -527,14 +576,14 @@ export class MachineSession {
     /**
      * Capture the current screen as a PNG.
      * Returns a Buffer containing a 1024×625 PNG (the full emulated display,
-     * including borders — matches what the browser renders).
+     * including borders, matching what the browser renders).
      *
      * The active display area is roughly:
      *   x: leftBorder .. 1024-rightBorder
      *   y: topBorder  .. 625-bottomBorder
      */
     async screenshot() {
-        // Read from _completeFb8 — the last fully-painted frame snapshotted in paint_ext.
+        // 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).
         return sharp(Buffer.from(this._completeFb8.buffer), {
             raw: { width: FB_WIDTH, height: FB_HEIGHT, channels: 4 },