jsbeeb 1.5.0 → 1.7.0

package/src/rewind.js

@@ -0,0 +1,84 @@
+"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;
+    }
+
+    /**
+     * Return all snapshots in order from oldest to newest.
+     * @returns {object[]} array of snapshots
+     */
+    getAll() {
+        const result = new Array(this.count);
+        const start = (this.writeIndex - this.count + this.maxSnapshots) % this.maxSnapshots;
+        for (let i = 0; i < this.count; i++) {
+            result[i] = this.snapshots[(start + i) % this.maxSnapshots];
+        }
+        return result;
+    }
+
+    /**
+     * 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,143 @@
+"use strict";
+
+import { typedArrayToBase64, base64ToTypedArray } from "./state-utils.js";
+import { findModel } from "./models.js";
+
+const SnapshotFormat = "jsbeeb-snapshot";
+const SnapshotVersion = 2;
+
+/**
+ * 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 for save-to-file.
+ * Disc track pulse data is stripped — on restore, the discs are reloaded
+ * from the source references in the `media` field. (The in-memory rewind
+ * path uses cpu.snapshotState() directly, which retains full disc data.)
+ * @param {import('./6502.js').Cpu6502} cpu
+ * @param {object} model - the model definition object
+ * @param {object} [media] - optional media source references (disc1, disc2)
+ * @returns {object} snapshot object
+ */
+export function createSnapshot(cpu, model, media) {
+    const state = cpu.snapshotState();
+    // Strip clean disc track data from the save-to-file snapshot.
+    // The FDC/drive mechanical state is kept; only clean tracks
+    // (which can be reloaded from the disc image) are removed.
+    // Dirty tracks (written since disc load) are kept as an overlay.
+    if (state.fdc && state.fdc.drives) {
+        for (const drive of state.fdc.drives) {
+            if (drive.disc) {
+                const dirtyTracks = {};
+                for (const key of Object.keys(drive.disc.tracks)) {
+                    const [sideStr, trackNumStr] = key.split(":");
+                    const isSideUpper = sideStr === "true";
+                    const trackNum = parseInt(trackNumStr, 10);
+                    const dirtyKey = trackNum | (isSideUpper ? 0x100 : 0);
+                    if (drive.disc._everDirtyTracks && drive.disc._everDirtyTracks.has(dirtyKey)) {
+                        dirtyTracks[key] = drive.disc.tracks[key];
+                    }
+                }
+                drive.disc.tracks = {};
+                drive.disc.dirtyTracks = dirtyTracks;
+                // Clean up internal-only fields not needed in serialized state
+                delete drive.disc._everDirtyTracks;
+                delete drive.disc._originalImageData;
+                delete drive.disc._originalImageCrc32;
+            }
+        }
+    }
+    const snapshot = {
+        format: SnapshotFormat,
+        version: SnapshotVersion,
+        model: model.name,
+        timestamp: new Date().toISOString(),
+        state,
+    };
+    if (media) snapshot.media = media;
+    return snapshot;
+}
+
+/**
+ * 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) {
@@ -338,11 +377,7 @@ export class InstrumentedSoundChip extends SoundChip {
     /** Read current SN76489 register state in a friendly format. */
     getState() {
         return {
-            tone: [
-                this.registers[0],
-                this.registers[1],
-                this.registers[2],
-            ],
+            tone: [this.registers[0], this.registers[1], this.registers[2]],
             noise: this.registers[3],
             volume: [
                 this._attenuationFromVolume(0),

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;
+}

package/src/teletext.js

@@ -150,6 +150,75 @@ export class Teletext {
         }
     }
 
+    snapshotState() {
+        // Encode glyph table references as strings for serialization
+        let nextGlyphsName, curGlyphsName, heldGlyphsName;
+        for (const [name, table] of [
+            ["normal", this.normalGlyphs],
+            ["graphics", this.graphicsGlyphs],
+            ["separated", this.separatedGlyphs],
+        ]) {
+            if (this.nextGlyphs === table) nextGlyphsName = name;
+            if (this.curGlyphs === table) curGlyphsName = name;
+            if (this.heldGlyphs === table) heldGlyphsName = name;
+        }
+        return {
+            prevCol: this.prevCol,
+            col: this.col,
+            bg: this.bg,
+            sep: this.sep,
+            dbl: this.dbl,
+            oldDbl: this.oldDbl,
+            secondHalfOfDouble: this.secondHalfOfDouble,
+            wasDbl: this.wasDbl,
+            gfx: this.gfx,
+            flash: this.flash,
+            flashOn: this.flashOn,
+            flashTime: this.flashTime,
+            heldChar: this.heldChar,
+            holdChar: this.holdChar,
+            dataQueue: [...this.dataQueue],
+            scanlineCounter: this.scanlineCounter,
+            levelDEW: this.levelDEW,
+            levelDISPTMG: this.levelDISPTMG,
+            levelRA0: this.levelRA0,
+            nextGlyphs: nextGlyphsName,
+            curGlyphs: curGlyphsName,
+            heldGlyphs: heldGlyphsName,
+        };
+    }
+
+    restoreState(state) {
+        this.prevCol = state.prevCol;
+        this.col = state.col;
+        this.bg = state.bg;
+        this.sep = state.sep;
+        this.dbl = state.dbl;
+        this.oldDbl = state.oldDbl;
+        this.secondHalfOfDouble = state.secondHalfOfDouble;
+        this.wasDbl = state.wasDbl;
+        this.gfx = state.gfx;
+        this.flash = state.flash;
+        this.flashOn = state.flashOn;
+        this.flashTime = state.flashTime;
+        this.heldChar = state.heldChar;
+        this.holdChar = state.holdChar;
+        this.dataQueue = [...state.dataQueue];
+        this.scanlineCounter = state.scanlineCounter;
+        this.levelDEW = state.levelDEW;
+        this.levelDISPTMG = state.levelDISPTMG;
+        this.levelRA0 = state.levelRA0;
+
+        const glyphMap = {
+            normal: this.normalGlyphs,
+            graphics: this.graphicsGlyphs,
+            separated: this.separatedGlyphs,
+        };
+        this.nextGlyphs = glyphMap[state.nextGlyphs] || this.normalGlyphs;
+        this.curGlyphs = glyphMap[state.curGlyphs] || this.normalGlyphs;
+        this.heldGlyphs = glyphMap[state.heldGlyphs] || this.normalGlyphs;
+    }
+
     setNextChars() {
         if (this.gfx) {
             if (this.sep) {

package/src/via.js

@@ -402,6 +402,73 @@ class Via {
         this.portBUpdated();
     }
 
+    snapshotState() {
+        return {
+            ora: this.ora,
+            orb: this.orb,
+            ira: this.ira,
+            irb: this.irb,
+            ddra: this.ddra,
+            ddrb: this.ddrb,
+            sr: this.sr,
+            t1l: this.t1l,
+            t2l: this.t2l,
+            t1c: this.t1c,
+            t2c: this.t2c,
+            acr: this.acr,
+            pcr: this.pcr,
+            ifr: this.ifr,
+            ier: this.ier,
+            t1hit: this.t1hit,
+            t2hit: this.t2hit,
+            portapins: this.portapins,
+            portbpins: this.portbpins,
+            ca1: this.ca1,
+            ca2: this.ca2,
+            cb1: this.cb1,
+            cb2: this.cb2,
+            justhit: this.justhit,
+            t1_pb7: this.t1_pb7,
+            lastPolltime: this.lastPolltime,
+            taskOffset: this.task.scheduled() ? this.task.expireEpoch - this.scheduler.epoch : null,
+        };
+    }
+
+    restoreState(state) {
+        this.ora = state.ora;
+        this.orb = state.orb;
+        this.ira = state.ira;
+        this.irb = state.irb;
+        this.ddra = state.ddra;
+        this.ddrb = state.ddrb;
+        this.sr = state.sr;
+        this.t1l = state.t1l;
+        this.t2l = state.t2l;
+        this.t1c = state.t1c;
+        this.t2c = state.t2c;
+        this.acr = state.acr;
+        this.pcr = state.pcr;
+        this.ifr = state.ifr;
+        this.ier = state.ier;
+        this.t1hit = state.t1hit;
+        this.t2hit = state.t2hit;
+        this.portapins = state.portapins;
+        this.portbpins = state.portbpins;
+        this.ca1 = state.ca1;
+        this.ca2 = state.ca2;
+        this.cb1 = state.cb1;
+        this.cb2 = state.cb2;
+        this.justhit = state.justhit;
+        this.t1_pb7 = state.t1_pb7;
+        this.lastPolltime = state.lastPolltime;
+        this.updateIFR();
+        if (state.taskOffset !== null) {
+            this.task.reschedule(state.taskOffset);
+        } else {
+            this.task.cancel();
+        }
+    }
+
     setca1(level) {
         if (level === this.ca1) return;
         const pcrSet = !!(this.pcr & 1);
@@ -484,6 +551,30 @@ export class SysVia extends Via {
         this.reset();
     }
 
+    snapshotState() {
+        return {
+            ...super.snapshotState(),
+            IC32: this.IC32,
+            capsLockLight: this.capsLockLight,
+            shiftLockLight: this.shiftLockLight,
+        };
+    }
+
+    restoreState(state) {
+        super.restoreState(state);
+        this.IC32 = state.IC32;
+        this.capsLockLight = state.capsLockLight;
+        this.shiftLockLight = state.shiftLockLight;
+        // Re-apply IC32 side effects (sound chip data bus, CMOS, port A)
+        // Must call portBUpdated directly (not recalculatePortBPins which
+        // overwrites IC32 based on portbpins) and then re-set IC32.
+        this.portBUpdated();
+        this.IC32 = state.IC32;
+        this.capsLockLight = state.capsLockLight;
+        this.shiftLockLight = state.shiftLockLight;
+        this.recalculatePortAPins();
+    }
+
     setKeyLayout(map) {
         this.keycodeToRowCol = utils.getKeyMap(map);
     }