jsbeeb 1.5.0 → 1.7.0

package/src/disc.js

@@ -3,30 +3,23 @@
 
 import * as utils from "./utils.js";
 
-/*
- * TODO: use in fingerprinting
-class Crc32Builder {
-    constructor() {
-        this._crc = 0xffffffff;
-    }
-
-    add(data) {
-        for (let i = 0; i < data.length; ++i) {
-            const byte = data[i];
-            this._crc ^= byte;
-            for (let j = 0; j < 8; ++j) {
-                const doEor = this._crc & 1;
-                this._crc = this._crc >>> 1;
-                if (doEor) this._crc ^= 0xedb88320;
-            }
+/**
+ * Compute CRC32 of a Uint8Array.
+ * @param {Uint8Array} data
+ * @returns {number} CRC32 as a signed 32-bit integer
+ */
+export function crc32(data) {
+    let crc = 0xffffffff;
+    for (let i = 0; i < data.length; ++i) {
+        crc ^= data[i];
+        for (let j = 0; j < 8; ++j) {
+            const doEor = crc & 1;
+            crc = crc >>> 1;
+            if (doEor) crc ^= 0xedb88320;
         }
     }
-
-    get crc() {
-        return ~this._crc;
-    }
+    return ~crc;
 }
-*/
 class TrackBuilder {
     /**
      * @param {Track} track
@@ -747,6 +740,27 @@ export class Disc {
         this.writeTrackCallback = undefined;
         this.isWriteable = isWriteable;
 
+        // Track which tracks have been written since the last snapshot.
+        // Keys are numeric: (track | (isSideUpper ? 0x100 : 0)).
+        this._snapshotDirtyTracks = new Set();
+        // Cumulative set of all tracks ever written since disc load (never cleared by snapshots).
+        // Same key encoding as _snapshotDirtyTracks.
+        this._everDirtyTracks = new Set();
+        // Cache of the previous snapshot's track data for structural sharing.
+        // Keys are "side:trackNum" strings, values are {pulses2Us, length} objects.
+        this._lastTrackSnapshots = Object.create(null);
+
+        // Original disc image data, stored for embedding in save-to-file snapshots
+        // and CRC32 verification on restore. _originalImageData is only set for
+        // local-file discs (not URL-sourced ones). _originalImageCrc32 is the CRC
+        // of the image bytes at load time — it is not updated if an onChange handler
+        // mutates the backing store. This is fine because the CRC is compared against
+        // the same source that would be reloaded (the original image or URL), not the
+        // mutated copy. If a mutable source URL were added in future, CRC verification
+        // should be skipped or the CRC updated accordingly.
+        this._originalImageData = null;
+        this._originalImageCrc32 = null;
+
         this.initSurface(0);
     }
 
@@ -754,6 +768,39 @@ export class Disc {
         this.writeTrackCallback = callback;
     }
 
+    /**
+     * Record the CRC32 of the original disc image for verification on restore.
+     * Called by discFor() after loading. Does not retain the image bytes.
+     * @param {Uint8Array} data - the raw disc image bytes (used only to compute CRC32)
+     */
+    setOriginalImageCrc32(data) {
+        this._originalImageCrc32 = crc32(data);
+    }
+
+    /**
+     * Store the original disc image bytes for embedding in snapshots.
+     * Only call this for local-file discs — URL-sourced discs should use
+     * setOriginalImageCrc32() instead to avoid retaining the full image.
+     * Computes CRC32 only if not already set (e.g. by discFor).
+     * @param {Uint8Array} data - the raw disc image bytes
+     */
+    setOriginalImage(data) {
+        this._originalImageData = data;
+        if (this._originalImageCrc32 == null) {
+            this._originalImageCrc32 = crc32(data);
+        }
+    }
+
+    /** @returns {Uint8Array|null} the original disc image bytes, or null if not set */
+    get originalImageData() {
+        return this._originalImageData;
+    }
+
+    /** @returns {number|null} CRC32 of the original disc image, or null if not set */
+    get originalImageCrc32() {
+        return this._originalImageCrc32;
+    }
+
     get writeProtected() {
         return !this.isWriteable;
     }
@@ -797,7 +844,9 @@ export class Disc {
     writePulses(isSideUpper, track, position, pulses) {
         const trackObj = this.getTrack(isSideUpper, track);
         if (position >= trackObj.length)
-            throw new Error(`Attempt to write off end of track ${position} > ${track.length}`);
+            throw new Error(
+                `Attempt to write off end of track ${track}: position ${position} >= length ${trackObj.length}`,
+            );
         if (this.isDirty) {
             if (isSideUpper !== this.dirtySide || track !== this.dirtyTrack)
                 throw new Error("Switched dirty track or side");
@@ -805,6 +854,11 @@ export class Disc {
         this.isDirty = true;
         this.dirtySide = isSideUpper;
         this.dirtyTrack = track;
+        // Numeric key avoids string allocation on every pulse write.
+        // Upper bit encodes side, lower 8 bits encode track number.
+        const dirtyKey = track | (isSideUpper ? 0x100 : 0);
+        this._snapshotDirtyTracks.add(dirtyKey);
+        this._everDirtyTracks.add(dirtyKey);
         trackObj.pulses2Us[position] = pulses;
         // TODO a debug log flag for this
         // console.log(`wrote to ${track}:${position * 32}`);
@@ -827,6 +881,106 @@ export class Disc {
         this.setTrackUsed(dirtySide, dirtyTrack);
     }
 
+    /**
+     * Create a snapshot of all track data with structural sharing.
+     * Clean tracks reuse references from the previous snapshot;
+     * dirty tracks get fresh copies.
+     */
+    snapshotState() {
+        const numSides = this.isDoubleSided ? 2 : 1;
+        // Use a plain object for JSON serialization compatibility.
+        // Keys are "side:trackNum" strings.
+        const tracks = Object.create(null);
+        for (let side = 0; side < numSides; ++side) {
+            for (let trackNum = 0; trackNum < this.tracksUsed; ++trackNum) {
+                const key = `${side === 1}:${trackNum}`;
+                const dirtyKey = trackNum | (side === 1 ? 0x100 : 0);
+                const trackObj = this.getTrack(side === 1, trackNum);
+                if (this._snapshotDirtyTracks.has(dirtyKey) || !this._lastTrackSnapshots[key]) {
+                    // Dirty or first snapshot: copy the track data
+                    tracks[key] = {
+                        pulses2Us: trackObj.pulses2Us.slice(),
+                        length: trackObj.length,
+                    };
+                } else {
+                    // Clean: reuse the previous snapshot's reference
+                    tracks[key] = this._lastTrackSnapshots[key];
+                }
+            }
+        }
+
+        this._snapshotDirtyTracks.clear();
+        this._lastTrackSnapshots = tracks;
+
+        return {
+            tracksUsed: this.tracksUsed,
+            isDoubleSided: this.isDoubleSided,
+            isWriteable: this.isWriteable,
+            name: this.name,
+            tracks,
+            // Expose for save-to-file snapshots to identify dirty tracks.
+            // This is a Set and won't survive JSON serialization — it's only
+            // used by createSnapshot() before the snapshot is serialized.
+            _everDirtyTracks: new Set(this._everDirtyTracks),
+            _originalImageData: this._originalImageData,
+            _originalImageCrc32: this._originalImageCrc32,
+        };
+    }
+
+    /**
+     * Restore disc track data from a snapshot.
+     * For save-to-file snapshots, `state.tracks` is empty and `state.dirtyTracks`
+     * contains only the tracks modified since disc load. The base disc data must
+     * already be loaded before calling this method.
+     */
+    restoreState(state) {
+        this.tracksUsed = state.tracksUsed;
+        this.isDoubleSided = state.isDoubleSided;
+        this.isWriteable = state.isWriteable;
+        this.name = state.name;
+
+        // Reset write-in-progress state
+        this.isDirty = false;
+        this.dirtySide = -1;
+        this.dirtyTrack = -1;
+        this._snapshotDirtyTracks.clear();
+        // Restore _everDirtyTracks from the snapshot if present (rewind path —
+        // the Set is carried in-memory but won't survive JSON serialization).
+        // For the save-to-file path, _everDirtyTracks is rebuilt from dirtyTracks below.
+        if (state._everDirtyTracks instanceof Set) {
+            this._everDirtyTracks = new Set(state._everDirtyTracks);
+        } else {
+            this._everDirtyTracks.clear();
+        }
+
+        // Restore full track data (rewind path — tracks contains all data)
+        this._lastTrackSnapshots = state.tracks;
+        for (const key of Object.keys(state.tracks)) {
+            const trackData = state.tracks[key];
+            const [sideStr, trackNumStr] = key.split(":");
+            const isSideUpper = sideStr === "true";
+            const trackNum = parseInt(trackNumStr, 10);
+            const trackObj = this.getTrack(isSideUpper, trackNum);
+            trackObj.pulses2Us.set(trackData.pulses2Us);
+            trackObj.length = trackData.length;
+        }
+
+        // Apply dirty track overlays (save-to-file path — base disc already loaded,
+        // overlay only the tracks that were written since disc load)
+        if (state.dirtyTracks) {
+            for (const key of Object.keys(state.dirtyTracks)) {
+                const trackData = state.dirtyTracks[key];
+                const [sideStr, trackNumStr] = key.split(":");
+                const isSideUpper = sideStr === "true";
+                const trackNum = parseInt(trackNumStr, 10);
+                const trackObj = this.getTrack(isSideUpper, trackNum);
+                trackObj.pulses2Us.set(trackData.pulses2Us);
+                trackObj.length = trackData.length;
+                this._everDirtyTracks.add(trackNum | (isSideUpper ? 0x100 : 0));
+            }
+        }
+    }
+
     logSummary() {
         const maxTrack = this.tracksUsed;
         const numSides = this.isDoubleSided ? 2 : 1;

package/src/fdc.js

@@ -212,7 +212,9 @@ export function guessDiscTypeFromName(name) {
  */
 export function discFor(fdc, name, stringData, onChange) {
     const data = typeof stringData !== "string" ? stringData : utils.stringToUint8Array(stringData);
-    return guessDiscTypeFromName(name).loader(new Disc(true, new DiscConfig(), name), data, onChange);
+    const disc = guessDiscTypeFromName(name).loader(new Disc(true, new DiscConfig(), name), data, onChange);
+    disc.setOriginalImageCrc32(data instanceof Uint8Array ? data : new Uint8Array(data));
+    return disc;
 }
 
 export function localDisc(fdc, name) {

package/src/intel-fdc.js

@@ -1670,6 +1670,71 @@ export class IntelFdc {
         this._doWriteRun(callContext, 0xff);
     }
 
+    snapshotState() {
+        const scheduler = this._timerTask.scheduler;
+        return {
+            regs: this._regs.slice(),
+            status: this._status,
+            isResultReady: this._isResultReady,
+            mmioData: this._mmioData,
+            mmioClocks: this._mmioClocks,
+            driveOut: this._driveOut,
+            shiftRegister: this._shiftRegister,
+            numShifts: this._numShifts,
+            state: this._state,
+            stateCount: this._stateCount,
+            stateIsIndexPulse: this._stateIsIndexPulse,
+            crc: this._crc,
+            onDiscCrc: this._onDiscCrc,
+            paramCallback: this._paramCallback,
+            indexPulseCallback: this._indexPulseCallback,
+            timerState: this._timerState,
+            callContext: this._callContext,
+            didSeekStep: this._didSeekStep,
+            timerTaskOffset: this._timerTask.scheduled() ? this._timerTask.expireEpoch - scheduler.epoch : null,
+            drives: this._drives.map((d) => d.snapshotState()),
+        };
+    }
+
+    restoreState(state) {
+        this._regs.set(state.regs);
+        this._status = state.status;
+        this._isResultReady = state.isResultReady;
+        this._mmioData = state.mmioData;
+        this._mmioClocks = state.mmioClocks;
+        this._driveOut = state.driveOut;
+        this._shiftRegister = state.shiftRegister;
+        this._numShifts = state.numShifts;
+        this._state = state.state;
+        this._stateCount = state.stateCount;
+        this._stateIsIndexPulse = state.stateIsIndexPulse;
+        this._crc = state.crc;
+        this._onDiscCrc = state.onDiscCrc;
+        this._paramCallback = state.paramCallback;
+        this._indexPulseCallback = state.indexPulseCallback;
+        this._timerState = state.timerState;
+        this._callContext = state.callContext;
+        this._didSeekStep = state.didSeekStep;
+
+        // Restore drives
+        for (let i = 0; i < this._drives.length; i++) {
+            this._drives[i].restoreState(state.drives[i]);
+        }
+
+        // Derive _currentDrive from _driveOut
+        this._currentDrive = null;
+        const selectBits = this._driveOut & DriveOut.selectFlags;
+        if (selectBits === DriveOut.select_0) this._currentDrive = this._drives[0];
+        else if (selectBits === DriveOut.select_1) this._currentDrive = this._drives[1];
+
+        // Restore timer
+        this._timerTask.cancel();
+        if (state.timerTaskOffset !== null) this._timerTask.schedule(state.timerTaskOffset);
+
+        // NMI level is saved/restored by the CPU snapshot directly,
+        // so we don't reassert it here.
+    }
+
     /// jsbeeb compatibility stuff
     /**
      *

package/src/jsbeeb.css

@@ -352,6 +352,72 @@ small {
   pointer-events: auto;
 }
 
+/* Rewind scrubber panel */
+#rewind-panel {
+  position: fixed;
+  bottom: 40px;
+  left: 0;
+  right: 0;
+  background: rgba(0, 0, 0, 0.85);
+  border-top: 1px solid #555;
+  z-index: 10;
+  padding: 8px 12px;
+}
+
+.rewind-header {
+  display: flex;
+  align-items: center;
+  gap: 12px;
+  margin-bottom: 6px;
+}
+
+.rewind-title {
+  color: #ccc;
+  font-size: 12px;
+  font-weight: bold;
+}
+
+.rewind-filmstrip {
+  display: flex;
+  gap: 6px;
+  overflow-x: auto;
+  padding: 4px 0;
+}
+
+.rewind-thumb {
+  flex: 0 0 auto;
+  cursor: pointer;
+  border: 2px solid transparent;
+  border-radius: 3px;
+  position: relative;
+  transition: border-color 0.15s;
+}
+
+.rewind-thumb:hover {
+  border-color: #aaa;
+}
+
+.rewind-thumb.selected {
+  border-color: #4af;
+}
+
+.rewind-thumb canvas {
+  display: block;
+  border-radius: 2px;
+}
+
+.rewind-thumb-label {
+  position: absolute;
+  bottom: 2px;
+  right: 4px;
+  font-size: 10px;
+  color: #fff;
+  text-shadow:
+    0 0 3px #000,
+    0 0 6px #000;
+  pointer-events: none;
+}
+
 div.smoothie-chart-tooltip {
   background: #444;
   padding: 1em;

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).
      *