jsbeeb 1.5.0 → 1.6.0

package/src/machine-session.js

@@ -62,6 +62,10 @@ export class MachineSession {
 
         // Accumulated VDU text output — drained by callers
         this._pendingOutput = [];
+
+        // Breakpoint management — 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 */
@@ -277,6 +281,93 @@ export class MachineSession {
         await this._machine.runUntilAddress(addr, timeoutSecs);
     }
 
+    /**
+     * Add a persistent breakpoint. Returns the breakpoint id.
+     * The hook stays active across run calls until removed.
+     * When the hook fires, cpu.stop() halts the current runFor.
+     * @param {"execute"|"read"|"write"} type
+     * @param {number} address
+     * @returns {number} breakpoint id
+     */
+    addBreakpoint(type, address) {
+        const id = this._nextBreakpointId++;
+        const cpu = this._machine.processor;
+        const bp = { type, address, hit: false, id, value: undefined };
+
+        if (type === "execute") {
+            bp.hook = cpu.debugInstruction.add((pc) => {
+                if (pc === address) {
+                    bp.hit = true;
+                    return true;
+                }
+            });
+        } else if (type === "read") {
+            bp.hook = cpu.debugRead.add((addr, val) => {
+                if (addr === address) {
+                    bp.hit = true;
+                    bp.value = val;
+                    return true;
+                }
+            });
+        } else if (type === "write") {
+            bp.hook = cpu.debugWrite.add((addr, val) => {
+                if (addr === address) {
+                    bp.hit = true;
+                    bp.value = val;
+                    return true;
+                }
+            });
+        } else {
+            throw new Error(`Unknown breakpoint type: ${type}`);
+        }
+
+        this._breakpoints.set(id, bp);
+        return id;
+    }
+
+    /**
+     * Remove a breakpoint by id.
+     */
+    removeBreakpoint(id) {
+        const bp = this._breakpoints.get(id);
+        if (!bp) throw new Error(`No breakpoint with id ${id}`);
+        bp.hook.remove();
+        this._breakpoints.delete(id);
+    }
+
+    /**
+     * Remove all breakpoints.
+     */
+    clearBreakpoints() {
+        for (const bp of this._breakpoints.values()) {
+            bp.hook.remove();
+        }
+        this._breakpoints.clear();
+    }
+
+    /**
+     * Return the first breakpoint that was hit since the last reset, or null.
+     */
+    hitBreakpoint() {
+        for (const bp of this._breakpoints.values()) {
+            if (bp.hit) {
+                const result = { id: bp.id, type: bp.type, address: bp.address };
+                if (bp.value !== undefined) result.value = bp.value;
+                return result;
+            }
+        }
+        return null;
+    }
+
+    /**
+     * Reset all hit flags (call before starting a new run).
+     */
+    resetBreakpointHits() {
+        for (const bp of this._breakpoints.values()) {
+            bp.hit = false;
+        }
+    }
+
     /**
      * Load a disc image (absolute or relative path to an .ssd or .dsd file).
      *

package/src/main.js

@@ -30,6 +30,9 @@ import { MicrophoneInput } from "./microphone-input.js";
 import { SpeechOutput } from "./speech-output.js";
 import { MouseJoystickSource } from "./mouse-joystick-source.js";
 import { getFilterForMode } from "./canvas.js";
+import { createSnapshot, restoreSnapshot, snapshotToJSON, snapshotFromJSON, modelsCompatible } from "./snapshot.js";
+import { isBemSnapshot, parseBemSnapshot } from "./bem-snapshot.js";
+import { RewindBuffer } from "./rewind.js";
 import {
     buildUrlFromParams,
     guessModelFromHostname,
@@ -327,6 +330,16 @@ const $screen = $("#screen");
 const $errorDialog = $("#error-dialog");
 const $errorDialogModal = new bootstrap.Modal($errorDialog[0]);
 
+async function compressBlob(blob) {
+    const stream = blob.stream().pipeThrough(new CompressionStream("gzip"));
+    return new Response(stream).blob();
+}
+
+async function decompressBlob(blob) {
+    const stream = blob.stream().pipeThrough(new DecompressionStream("gzip"));
+    return new Response(stream).blob();
+}
+
 function showError(context, error) {
     $errorDialog.find(".context").text(context);
     $errorDialog.find(".error").text(error);
@@ -474,7 +487,11 @@ $pastetext.on("dragover", function (event) {
 $pastetext.on("drop", async function (event) {
     utils.noteEvent("local", "drop");
     const file = event.originalEvent.dataTransfer.files[0];
-    await loadHTMLFile(file);
+    if (isSnapshotFile(file.name)) {
+        await loadStateFromFile(file);
+    } else {
+        await loadHTMLFile(file);
+    }
 });
 
 const $cub = $("#cub-monitor");
@@ -1354,6 +1371,101 @@ $("#soft-reset").click(function (event) {
     event.preventDefault();
 });
 
+// Expose rewind to the debugger/console for v1
+window.jsbeebRewind = {
+    step: function () {
+        const snapshot = rewindBuffer.pop();
+        if (!snapshot) {
+            console.log("Rewind buffer empty");
+            return;
+        }
+        const wasRunning = running;
+        if (wasRunning) stop(false);
+        processor.restoreState(snapshot);
+        // Force a repaint so the display updates even while paused
+        video.paint();
+        console.log(`Rewound 1 step (${rewindBuffer.length} remaining)`);
+        // Don't auto-resume - stay paused so user can inspect state
+    },
+    get length() {
+        return rewindBuffer.length;
+    },
+    clear: function () {
+        rewindBuffer.clear();
+        console.log("Rewind buffer cleared");
+    },
+};
+
+$("#save-state").click(async function (event) {
+    event.preventDefault();
+    const wasRunning = running;
+    if (running) stop(false);
+    try {
+        const snapshot = createSnapshot(processor, model);
+        const json = snapshotToJSON(snapshot);
+        const blob = await compressBlob(new Blob([json]));
+        const url = URL.createObjectURL(blob);
+        const timestamp = new Date().toISOString().replace(/[:.]/g, "-");
+        const a = document.createElement("a");
+        a.href = url;
+        a.download = `jsbeeb-${model.name}-${timestamp}.json.gz`;
+        a.click();
+        URL.revokeObjectURL(url);
+    } catch (e) {
+        showError("saving state", e);
+    }
+    if (wasRunning) go();
+});
+
+async function loadStateFromFile(file) {
+    const wasRunning = running;
+    if (running) stop(false);
+    try {
+        const arrayBuffer = await file.arrayBuffer();
+        let snapshot;
+        if (isBemSnapshot(arrayBuffer)) {
+            snapshot = await parseBemSnapshot(arrayBuffer);
+        } else {
+            // Detect gzip (magic bytes 0x1f 0x8b) or plain JSON
+            const bytes = new Uint8Array(arrayBuffer);
+            let text;
+            if (bytes[0] === 0x1f && bytes[1] === 0x8b) {
+                const decompressed = await decompressBlob(new Blob([arrayBuffer]));
+                text = await decompressed.text();
+            } else {
+                text = new TextDecoder().decode(arrayBuffer);
+            }
+            snapshot = snapshotFromJSON(text);
+        }
+        if (!modelsCompatible(snapshot.model, model.name)) {
+            // Model mismatch: stash state and reload with correct model
+            sessionStorage.setItem("jsbeeb-pending-state", snapshotToJSON(snapshot));
+            const newQuery = { ...parsedQuery, model: snapshot.model };
+            const baseUrl = window.location.origin + window.location.pathname;
+            window.location.href = buildUrlFromParams(baseUrl, newQuery, paramTypes);
+            return;
+        }
+        restoreSnapshot(processor, model, snapshot);
+        // Force a repaint so the display updates even while paused
+        video.paint();
+    } catch (e) {
+        showError("loading state", e);
+    }
+    if (wasRunning) go();
+}
+
+function isSnapshotFile(filename) {
+    const lower = filename.toLowerCase();
+    return lower.endsWith(".snp") || lower.endsWith(".json") || lower.endsWith(".json.gz") || lower.endsWith(".gz");
+}
+
+$("#load-state").on("change", async function (event) {
+    const file = event.target.files[0];
+    if (!file) return;
+    event.target.value = "";
+    await loadStateFromFile(file);
+});
+
 $("#tape-menu a").on("click", function (e) {
     const type = $(e.target).attr("data-id");
     if (type === undefined) return;
@@ -1509,6 +1621,19 @@ startPromise
             dbgr.setPatch(parsedQuery.patch);
         }
 
+        // Restore pending state from a cross-model load (sessionStorage)
+        const pendingState = sessionStorage.getItem("jsbeeb-pending-state");
+        if (pendingState) {
+            sessionStorage.removeItem("jsbeeb-pending-state");
+            try {
+                const snapshot = snapshotFromJSON(pendingState);
+                restoreSnapshot(processor, model, snapshot);
+                processor.execute(40000);
+            } catch (e) {
+                showError("restoring saved state", e);
+            }
+        }
+
         go();
     })
     .catch((error) => {
@@ -1603,6 +1728,10 @@ function VirtualSpeedUpdater() {
 
 const virtualSpeedUpdater = new VirtualSpeedUpdater();
 
+const rewindBuffer = new RewindBuffer(30);
+let rewindFrameCounter = 0;
+const RewindCaptureInterval = 50; // ~1 second at 50fps
+
 function draw(now) {
     if (!running) {
         last = 0;
@@ -1655,6 +1784,11 @@ function draw(now) {
             }
             const end = performance.now();
             virtualSpeedUpdater.update(cycles, end - now, speedy);
+            // Capture rewind snapshot periodically
+            if (++rewindFrameCounter >= RewindCaptureInterval) {
+                rewindFrameCounter = 0;
+                rewindBuffer.push(processor.snapshotState());
+            }
         } catch (e) {
             running = false;
             utils.noteEvent("exception", "thrown", e.stack);
@@ -1836,9 +1970,11 @@ electron({
             }
         },
     },
+    loadStateFile: loadStateFromFile,
     actions: {
         "soft-reset": () => processor.reset(false),
         "hard-reset": () => processor.reset(true),
+        "save-state": () => $("#save-state").trigger("click"),
     },
 });
 

package/src/rewind.js

@@ -0,0 +1,71 @@
+"use strict";
+
+/**
+ * Circular buffer of emulator state snapshots for rewind functionality.
+ * Snapshots are stored directly without deep-copying, since
+ * snapshotState() already clones all TypedArrays via .slice().
+ */
+export class RewindBuffer {
+    /**
+     * @param {number} maxSnapshots - maximum number of snapshots to retain
+     */
+    constructor(maxSnapshots = 30) {
+        this.maxSnapshots = maxSnapshots;
+        this.snapshots = new Array(maxSnapshots);
+        this.count = 0;
+        this.writeIndex = 0;
+    }
+
+    /**
+     * Push a snapshot into the buffer.
+     * The caller must ensure the snapshot's typed arrays are already
+     * independent copies (e.g. from snapshotState() which uses .slice()).
+     * Overwrites the oldest snapshot when full.
+     * @param {object} snapshot - emulator state snapshot (already cloned)
+     */
+    push(snapshot) {
+        this.snapshots[this.writeIndex] = snapshot;
+        this.writeIndex = (this.writeIndex + 1) % this.maxSnapshots;
+        if (this.count < this.maxSnapshots) this.count++;
+    }
+
+    /**
+     * Pop the most recent snapshot from the buffer.
+     * @returns {object|null} the most recent snapshot, or null if empty
+     */
+    pop() {
+        if (this.count === 0) return null;
+        this.writeIndex = (this.writeIndex - 1 + this.maxSnapshots) % this.maxSnapshots;
+        this.count--;
+        const snapshot = this.snapshots[this.writeIndex];
+        this.snapshots[this.writeIndex] = null;
+        return snapshot;
+    }
+
+    /**
+     * Peek at the most recent snapshot without removing it.
+     * @returns {object|null} the most recent snapshot, or null if empty
+     */
+    peek() {
+        if (this.count === 0) return null;
+        const index = (this.writeIndex - 1 + this.maxSnapshots) % this.maxSnapshots;
+        return this.snapshots[index];
+    }
+
+    /**
+     * Clear all snapshots from the buffer.
+     */
+    clear() {
+        this.snapshots.fill(null);
+        this.count = 0;
+        this.writeIndex = 0;
+    }
+
+    /**
+     * Number of snapshots currently stored.
+     * @returns {number}
+     */
+    get length() {
+        return this.count;
+    }
+}

package/src/scheduler.js

@@ -87,6 +87,34 @@ export class Scheduler {
         return this.scheduled.expireEpoch - this.epoch;
     }
 
+    /**
+     * Cancel all scheduled tasks.
+     * Used during state restore - components will re-register their own tasks.
+     */
+    cancelAll() {
+        while (this.scheduled) {
+            this.scheduled.cancel();
+        }
+    }
+
+    /**
+     * Capture the scheduler's state for snapshotting.
+     * @returns {{epoch: number}}
+     */
+    snapshotState() {
+        return { epoch: this.epoch };
+    }
+
+    /**
+     * Restore the scheduler's state from a snapshot.
+     * Cancels all existing tasks - components must re-register theirs after this call.
+     * @param {{epoch: number}} state
+     */
+    restoreState(state) {
+        this.cancelAll();
+        this.epoch = state.epoch;
+    }
+
     /**
      * Create a new task.
      * @param {function(): void} onExpire function to call when the task expires

package/src/snapshot.js

@@ -0,0 +1,110 @@
+"use strict";
+
+import { typedArrayToBase64, base64ToTypedArray } from "./state-utils.js";
+import { findModel } from "./models.js";
+
+const SnapshotFormat = "jsbeeb-snapshot";
+const SnapshotVersion = 1;
+
+/**
+ * Check if two model names are compatible for state restore.
+ * Resolves synonyms via findModel, then compares by stripping any
+ * trailing parenthesised suffix (e.g. treating "BBC Master 128 (DFS)"
+ * and "BBC Master 128 (ADFS)" as compatible). Does not treat
+ * differently-named models like "BBC B with DFS 0.9" vs "BBC B with DFS 1.2"
+ * as compatible — those are distinct models.
+ */
+export function modelsCompatible(snapshotModel, currentModel) {
+    if (snapshotModel === currentModel) return true;
+    const resolvedSnapshot = findModel(snapshotModel);
+    const resolvedCurrent = findModel(currentModel);
+    if (resolvedSnapshot && resolvedCurrent) {
+        // Same model object, or same base machine (strip filesystem suffix)
+        if (resolvedSnapshot === resolvedCurrent) return true;
+        const base = (name) => name.replace(/\s*\(.*\)$/, "");
+        return base(resolvedSnapshot.name) === base(resolvedCurrent.name);
+    }
+    return false;
+}
+
+// Map of TypedArray constructor names for deserialization
+const TypedArrayConstructors = {
+    Uint8Array,
+    Uint16Array,
+    Uint32Array,
+    Int32Array,
+    Float32Array,
+    Float64Array,
+};
+
+/**
+ * Create a snapshot of the emulator state.
+ * @param {import('./6502.js').Cpu6502} cpu
+ * @param {object} model - the model definition object
+ * @returns {object} snapshot object
+ */
+export function createSnapshot(cpu, model) {
+    return {
+        format: SnapshotFormat,
+        version: SnapshotVersion,
+        model: model.name,
+        timestamp: new Date().toISOString(),
+        state: cpu.snapshotState(),
+    };
+}
+
+/**
+ * Restore emulator state from a snapshot.
+ * @param {import('./6502.js').Cpu6502} cpu
+ * @param {object} model - the current model definition
+ * @param {object} snapshot
+ * @throws {Error} if the model doesn't match
+ */
+export function restoreSnapshot(cpu, model, snapshot) {
+    if (snapshot.format !== SnapshotFormat) {
+        throw new Error(`Unknown snapshot format: ${snapshot.format}`);
+    }
+    if (snapshot.version > SnapshotVersion) {
+        throw new Error(`Snapshot version ${snapshot.version} is newer than supported version ${SnapshotVersion}`);
+    }
+    if (!modelsCompatible(snapshot.model, model.name)) {
+        throw new Error(`Model mismatch: snapshot is for "${snapshot.model}" but current model is "${model.name}"`);
+    }
+    cpu.restoreState(snapshot.state);
+}
+
+/**
+ * Serialize a snapshot to a JSON string, converting TypedArrays to base64.
+ * @param {object} snapshot
+ * @returns {string} JSON string
+ */
+export function snapshotToJSON(snapshot) {
+    return JSON.stringify(snapshot, (key, value) => {
+        if (ArrayBuffer.isView(value) && !(value instanceof DataView)) {
+            return {
+                __typedArray: true,
+                type: value.constructor.name,
+                data: typedArrayToBase64(value),
+            };
+        }
+        return value;
+    });
+}
+
+/**
+ * Deserialize a snapshot from a JSON string, converting base64 back to TypedArrays.
+ * @param {string} json
+ * @returns {object} snapshot object
+ */
+export function snapshotFromJSON(json) {
+    return JSON.parse(json, (key, value) => {
+        if (value && value.__typedArray) {
+            const Constructor = TypedArrayConstructors[value.type];
+            if (!Constructor) {
+                throw new Error(`Unknown TypedArray type: ${value.type}`);
+            }
+            return base64ToTypedArray(value.data, Constructor);
+        }
+        return value;
+    });
+}

package/src/soundchip.js

@@ -263,6 +263,45 @@ export class SoundChip {
         }
     }
 
+    snapshotState() {
+        return {
+            registers: this.registers.slice(),
+            counter: this.counter.slice(),
+            outputBit: [...this.outputBit],
+            volume: this.volume.slice(),
+            lfsr: this.lfsr,
+            latchedRegister: this.latchedRegister,
+            residual: this.residual,
+            sineOn: this.sineOn,
+            sineStep: this.sineStep,
+            sineTime: this.sineTime,
+        };
+    }
+
+    restoreState(state) {
+        this.registers.set(state.registers);
+        this.counter.set(state.counter);
+        this.outputBit[0] = state.outputBit[0];
+        this.outputBit[1] = state.outputBit[1];
+        this.outputBit[2] = state.outputBit[2];
+        this.outputBit[3] = state.outputBit[3];
+        this.volume.set(state.volume);
+        this.lfsr = state.lfsr;
+        this.latchedRegister = state.latchedRegister;
+        // Sync to current scheduler epoch to avoid a catch-up burst
+        this.lastRunEpoch = this.scheduler.epoch;
+        this.residual = state.residual;
+        this.sineOn = state.sineOn;
+        this.sineStep = state.sineStep;
+        this.sineTime = state.sineTime;
+        // Rebind the LFSR function based on noise register
+        this.shiftLfsr =
+            this.registers[3] & 4 ? this.shiftLfsrWhiteNoise.bind(this) : this.shiftLfsrPeriodicNoise.bind(this);
+        // Reset output buffer
+        this.position = 0;
+        this.buffer.fill(0);
+    }
+
     reset(hard) {
         if (!hard) return;
         for (let i = 0; i < 4; ++i) {

package/src/state-utils.js

@@ -0,0 +1,66 @@
+"use strict";
+
+/**
+ * Convert a TypedArray to a base64 string for JSON serialization.
+ * @param {ArrayBufferView} typedArray
+ * @returns {string} base64-encoded string
+ */
+export function typedArrayToBase64(typedArray) {
+    const bytes = new Uint8Array(typedArray.buffer, typedArray.byteOffset, typedArray.byteLength);
+    // Build binary string in chunks to avoid excessive string concatenation
+    const chunkSize = 8192;
+    const parts = [];
+    for (let i = 0; i < bytes.length; i += chunkSize) {
+        const end = Math.min(i + chunkSize, bytes.length);
+        parts.push(String.fromCharCode(...bytes.subarray(i, end)));
+    }
+    return btoa(parts.join(""));
+}
+
+/**
+ * Convert a base64 string back to a TypedArray.
+ * @param {string} base64 base64-encoded string
+ * @param {function} TypedArrayConstructor constructor for the desired type (e.g., Uint8Array)
+ * @returns {ArrayBufferView} the decoded typed array
+ */
+export function base64ToTypedArray(base64, TypedArrayConstructor) {
+    const binary = atob(base64);
+    const bytes = new Uint8Array(binary.length);
+    for (let i = 0; i < binary.length; i++) {
+        bytes[i] = binary.charCodeAt(i);
+    }
+    // Create a properly aligned typed array from the raw bytes
+    const elementSize = TypedArrayConstructor.BYTES_PER_ELEMENT;
+    const length = bytes.length / elementSize;
+    if (!Number.isInteger(length)) {
+        throw new Error(
+            `Base64 data length (${bytes.length} bytes) is not a multiple of ${TypedArrayConstructor.name} element size (${elementSize})`,
+        );
+    }
+    const result = new TypedArrayConstructor(length);
+    new Uint8Array(result.buffer).set(bytes);
+    return result;
+}
+
+/**
+ * Deep copy a snapshot object, cloning any TypedArrays found within.
+ * This ensures rewind buffer snapshots are fully isolated from live state.
+ * @param {object} obj snapshot object to copy
+ * @returns {object} a deep copy with all TypedArrays cloned
+ */
+export function deepCopySnapshot(obj) {
+    if (obj === null || typeof obj !== "object") {
+        return obj;
+    }
+    if (ArrayBuffer.isView(obj)) {
+        return obj.slice();
+    }
+    if (Array.isArray(obj)) {
+        return obj.map((item) => deepCopySnapshot(item));
+    }
+    const copy = {};
+    for (const key of Object.keys(obj)) {
+        copy[key] = deepCopySnapshot(obj[key]);
+    }
+    return copy;
+}