jsbeeb 1.17.0 → 1.18.0

package/README.md

@@ -13,6 +13,7 @@ different peripherals.
 - [Keyboard Mappings](#keyboard-mappings)
 - [Remapping Keys](#remapping-keys)
 - [Emulator Shortcuts](#emulator-shortcuts)
+- [Printer Output](#printer-output)
 - [Save State and Rewind](#save-state-and-rewind)
 - [Getting Set Up to Run Locally](#getting-set-up-to-run-locally)
 - [Running as a Desktop Application](#running-as-a-desktop-application)
@@ -103,8 +104,15 @@ The definitive lists are `keyCodes` (host) and `BBC` (BBC micro) in [`src/utils.
 | `Ctrl+Home`    | Stop and enter debugger         |
 | `Ctrl+Insert`  | Toggle turbo (fast-as-possible) |
 | `Ctrl+End`     | Pause emulation                 |
+| `Ctrl+B`       | Open printer output window      |
 | `Alt+PageDown` | Open rewind scrubber            |
 
+### Printer Output
+
+Anything the machine prints is captured whether or not the printer window is open, so programs that print (with `VDU 2`, `*FX5,1` and the like) run rather than waiting for a printer that is not there.
+
+Press `Ctrl+B` to open a window showing what has been printed so far; it then keeps up with the output as it arrives. Only the most recent output is kept, roughly a dozen pages' worth, so a program printing forever cannot fill memory.
+
 ### Save State and Rewind
 
 Save and load full emulator state snapshots from the **State** menu (or `Ctrl+S` / `Ctrl+O` in the Electron app).

package/package.json

@@ -7,7 +7,7 @@
   "name": "jsbeeb",
   "description": "Emulate a BBC Micro",
   "repository": "git@github.com:mattgodbolt/jsbeeb.git",
-  "version": "1.17.0",
+  "version": "1.18.0",
   "//engines": "If you change the version of Node, it must also be updated at the top of the Dockerfile.",
   "engines": {
     "node": ">=24.15.0"
@@ -30,6 +30,7 @@
     "argparse": "^3.0.0",
     "bootstrap": "^5.3.8",
     "bootswatch": "^5.3.8",
+    "pako": "^3.0.1",
     "sharp": "^0.35.3",
     "smoothie": "^1.36.1"
   },
@@ -105,10 +106,11 @@
     "mirror-sth:upload": "npm-run-all mirror-sth:upload:*",
     "mirror-sth:upload:blobs": "aws s3 sync .sth-mirror s3://bbc.xania.org/archive/sth/ --no-progress --exclude '*manifest.json' --exclude 'meta/*' --cache-control 'public, max-age=31536000, immutable'",
     "mirror-sth:upload:index": "aws s3 sync .sth-mirror s3://bbc.xania.org/archive/sth/ --no-progress --exclude '*' --include '*manifest.json' --include 'meta/*' --cache-control 'public, max-age=300'",
-    "mirror-bbcdiscs": "node tools/mirror-bbcdiscs.js --csv .bbcdiscs-sheet.csv --out .bbcdiscs-mirror",
+    "mirror-bbcdiscs": "node tools/mirror-bbcdiscs.js --csv .bbcdiscs-sheet.csv --fsd .bbcdiscs-mirror/cache-fsd --out .bbcdiscs-mirror",
     "mirror-bbcdiscs:check": "node tools/mirror-bbcdiscs.js --csv .bbcdiscs-sheet.csv --check-only",
     "mirror-bbcdiscs:seed": "aws s3 sync s3://bbc.xania.org/archive/bbcdiscs/hfe/ .bbcdiscs-mirror/hfe/ --no-progress",
-    "mirror-bbcdiscs:upload": "npm-run-all mirror-bbcdiscs:upload:*",
+    "mirror-bbcdiscs:preflight": "node tools/mirror-bbcdiscs.js --preflight --out .bbcdiscs-mirror",
+    "mirror-bbcdiscs:upload": "npm-run-all mirror-bbcdiscs:preflight mirror-bbcdiscs:upload:*",
     "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 .",

package/src/6502.js

@@ -709,6 +709,7 @@ export class Cpu6502 extends Base6502 {
         this.acia = new Acia(this, this.soundChip.toneGenerator, this.scheduler, this.relayNoise);
         this.serial = new Serial(this.acia);
         this.adconverter = new Adc(this.sysvia, this.scheduler);
+        this.touchScreen = new TouchScreen(this.scheduler, this.model.cyclesPerSecond);
         this.soundChip.setScheduler(this.scheduler);
         this.fdc = new this.model.Fdc(this, this.ddNoise, this.scheduler, this.debugFlags);
     }
@@ -1240,7 +1241,9 @@ export class Cpu6502 extends Base6502 {
             soundChip: this.soundChip.snapshotState(),
             acia: this.acia.snapshotState(),
             adc: this.adconverter.snapshotState(),
+            touchScreen: this.touchScreen.snapshotState(),
             fdc: this.fdc.snapshotState(),
+            teletextAdaptor: this.teletextAdaptor ? this.teletextAdaptor.snapshotState() : undefined,
             tube: this.hasTube ? this.tube.snapshotState({ includeRoms }) : undefined,
         };
     }
@@ -1297,6 +1300,11 @@ export class Cpu6502 extends Base6502 {
         this.soundChip.restoreState(state.soundChip);
         this.acia.restoreState(state.acia);
         this.adconverter.restoreState(state.adc);
+        if (this.teletextAdaptor && state.teletextAdaptor) this.teletextAdaptor.restoreState(state.teletextAdaptor);
+
+        // Touchscreen state, added without a version bump. Absent from an older snapshot, whose
+        // touchscreen keeps its current state, unpolled.
+        if (state.touchScreen) this.touchScreen.restoreState(state.touchScreen);
 
         // FDC state (v2+). If absent (v1 snapshot), FDC keeps its current state.
         if (state.fdc) {
@@ -1359,7 +1367,8 @@ export class Cpu6502 extends Base6502 {
     // Override in subclasses for different peripheral sets.
     // Only called on hard reset.
     resetPeripherals() {
-        if (this.config.printerPort) this.uservia.ca2changecallback = this.config.printerPort.outputStrobe;
+        if (this.config.printerPort)
+            this.uservia.ca2changecallback = (level, output) => this.config.printerPort.outputStrobe(level, output);
 
         this.sysvia.reset();
         this.uservia.reset();
@@ -1369,7 +1378,7 @@ export class Cpu6502 extends Base6502 {
         this.fdc.powerOnReset();
         this.adconverter.reset();
 
-        this.touchScreen = new TouchScreen(this.scheduler, this.model.cyclesPerSecond);
+        this.touchScreen.reset();
         if (this.econet) this.filestore = new Filestore(this, this.econet);
     }
 

package/src/bbcdiscs.js

@@ -2,6 +2,14 @@
 
 const mirrorBase = "https://bbc.xania.org/archive/bbcdiscs";
 
+/** How a disc came to be an image, which is the difference between the archives it came from. */
+export const Provenance = {
+    /** Read off the disc itself, by flux capture. */
+    Captured: "captured",
+    /** Rebuilt from a sector dump, so the surface around the data is inferred. */
+    Reconstructed: "reconstructed",
+};
+
 // Numeric so a "Disc 2" would sort before a "Disc 10" rather than after it,
 // and case-insensitive so a lower-cased title stays with its neighbours.
 const collator = new Intl.Collator(undefined, { numeric: true, sensitivity: "base" });
@@ -34,6 +42,25 @@ export function describe(file) {
     };
 }
 
+/** The provenances a catalogue actually holds, so a source added later needs no code here. */
+export const provenancesIn = (catalogue) => [...new Set(catalogue.map((file) => file.provenance))].sort();
+
+/**
+ * Whether a disc belongs in the picker as it is currently filtered.
+ *
+ * @param {object} file manifest entry
+ * @param {string} filter lower cased text to look for
+ * @param {?Set<string>} shown provenances to include, or null for all of them
+ */
+export function matches(file, filter, shown) {
+    if (shown && !shown.has(file.provenance)) return false;
+    if (!filter) return true;
+    // What the row says the disc is, rather than everything the row renders:
+    // the provenance is a word the tickboxes control, not one to search for.
+    const { title, publisher, detail } = describe(file);
+    return `${title} ${publisher} ${detail}`.toLowerCase().includes(filter);
+}
+
 export class BbcDiscArchive {
     /** @param {string} [baseUrl] where the mirror lives, to point at a test prefix */
     constructor(onStart, onCat, onError, baseUrl = mirrorBase) {
@@ -55,7 +82,10 @@ export class BbcDiscArchive {
                 if (!response.ok) throw new Error(`Network response was not ok (${response.status})`);
                 const data = await response.json();
                 if (!Array.isArray(data?.files)) throw new Error("Invalid manifest: missing files array");
-                this._catalogue = [...data.files].sort(byTitle);
+                this._catalogue = data.files
+                    // The captured discs were published before provenance was recorded.
+                    .map((file) => ({ ...file, provenance: file.provenance ?? Provenance.Captured }))
+                    .sort(byTitle);
                 this._loaded = true;
             } catch (error) {
                 console.error("Failed to fetch HFE archive catalogue:", error);

package/src/bem-snapshot.js

@@ -1,5 +1,5 @@
 "use strict";
-import { decompress } from "./utils.js";
+import { inflate } from "./utils.js";
 
 // B-em snapshot format parser (versions 1 and 3).
 // v1 (BEMSNAP1): Fixed-size 327,885 byte packed struct. Reference: beebjit state.c
@@ -334,7 +334,7 @@ async function parseBemTube(sections, tubeName) {
 
     // Those names come from a config file, so size is the real check. It cannot be exact: the
     // trailing ROM's size comes from that same config, and b-em records it as zero if unset.
-    const parasite = await decompress(sections["P"].data, "deflate");
+    const parasite = inflate(sections["P"].data);
     const romBytes = parasite.length - BemTubeRegisterBytes - BemTubeRamSize;
     if (romBytes < 0 || romBytes > BemTubeRamSize) {
         throw new Error(
@@ -449,9 +449,8 @@ async function parseBemV3(buffer) {
     let roms = null;
     const memSection = sections["M"];
     if (memSection) {
-        // Memory is zlib-compressed; decompression is async.
         // Decompressed layout: 2 bytes (fe30, fe34) + 64KB RAM + 256KB ROM
-        const memData = await decompress(memSection.data, "deflate");
+        const memData = inflate(memSection.data);
         cpuState.fe30 = memData[0];
         cpuState.fe34 = memData[1];
         const ramStart = 2;

package/src/canvas.js

@@ -38,6 +38,11 @@ export class Canvas {
     /** Nothing to release: the 2D context owns no objects of ours. */
     dispose() {}
 
+    setFilter(filterClass) {
+        if (filterClass !== PassthroughFilter)
+            throw new Error(`${filterClass.getDisplayConfig().name} needs WebGL, which is not in use here`);
+    }
+
     paint(minx, miny, maxx, maxy, _frame) {
         const width = maxx - minx;
         const height = maxy - miny;
@@ -78,23 +83,14 @@ export class GlCanvas {
 
         checkedGl.depthMask(false);
 
-        this.filter = new filterClass(checkedGl);
-        const program = this.filter.program;
-        checkedGl.useProgram(program);
-
-        // Filters that pick their own samples want the texels they asked for,
-        // not a hardware blend of the ones either side.
-        const sampling = filterClass.getDisplayConfig().nearestSampling ? checkedGl.NEAREST : checkedGl.LINEAR;
-
         this.fb8 = new Uint8Array(width * height * 4);
         this.fb32 = new Uint32Array(this.fb8.buffer);
         this.texture = checkedGl.createTexture();
+        checkedGl.activeTexture(checkedGl.TEXTURE0);
         checkedGl.bindTexture(checkedGl.TEXTURE_2D, this.texture);
         checkedGl.pixelStorei(checkedGl.UNPACK_ALIGNMENT, 4);
         checkedGl.texParameteri(checkedGl.TEXTURE_2D, checkedGl.TEXTURE_WRAP_S, checkedGl.CLAMP_TO_EDGE);
         checkedGl.texParameteri(checkedGl.TEXTURE_2D, checkedGl.TEXTURE_WRAP_T, checkedGl.CLAMP_TO_EDGE);
-        checkedGl.texParameteri(checkedGl.TEXTURE_2D, checkedGl.TEXTURE_MAG_FILTER, sampling);
-        checkedGl.texParameteri(checkedGl.TEXTURE_2D, checkedGl.TEXTURE_MIN_FILTER, sampling);
         checkedGl.texImage2D(
             checkedGl.TEXTURE_2D,
             0,
@@ -106,44 +102,72 @@ export class GlCanvas {
             checkedGl.UNSIGNED_BYTE,
             this.fb8,
         );
-        checkedGl.bindTexture(checkedGl.TEXTURE_2D, null);
 
-        const vertexPositionAttrLoc = checkedGl.getAttribLocation(program, "pos");
-        checkedGl.enableVertexAttribArray(vertexPositionAttrLoc);
         this.vertexPositionBuffer = checkedGl.createBuffer();
         checkedGl.bindBuffer(checkedGl.ARRAY_BUFFER, this.vertexPositionBuffer);
         checkedGl.bufferData(checkedGl.ARRAY_BUFFER, new Float32Array([0, 0, 0, 1, 1, 0, 1, 1]), checkedGl.STATIC_DRAW);
-        checkedGl.vertexAttribPointer(vertexPositionAttrLoc, 2, checkedGl.FLOAT, false, 0, 0);
-
-        const uvAttrLoc = checkedGl.getAttribLocation(program, "uvIn");
-        checkedGl.enableVertexAttribArray(uvAttrLoc);
         this.uvBuffer = checkedGl.createBuffer();
-        checkedGl.bindBuffer(checkedGl.ARRAY_BUFFER, this.uvBuffer);
-        checkedGl.vertexAttribPointer(uvAttrLoc, 2, checkedGl.FLOAT, false, 0, 0);
-
-        checkedGl.activeTexture(gl.TEXTURE0);
-        checkedGl.bindTexture(gl.TEXTURE_2D, this.texture);
 
         this.checkedGl = checkedGl;
+        this.filter = null;
+        this.attribLocations = [];
         this.viewportWidth = this.viewportHeight = 0;
         this.uvFloatArray = new Float32Array(8);
         this.lastExtent = {};
 
+        try {
+            this.setFilter(filterClass);
+        } catch (e) {
+            this.dispose();
+            throw e;
+        }
+
         console.log("GL Canvas set up");
     }
 
     /**
-     * Release the GL objects this canvas owns.
+     * Draw with `filterClass` from here on, keeping the framebuffer texture and
+     * the vertex buffers: only the program, the texture sampling mode and the
+     * attribute locations differ between filters.
      *
-     * Switching display mode builds a new canvas over the same element, and a
-     * canvas only ever hands out one WebGL context — so the new one inherits
-     * the old one's context and the old one's objects stay resident unless
-     * they are deleted here. That is a megabytes-per-switch leak: the
-     * framebuffer texture alone is 1024x1024 RGBA.
+     * The new filter is built before the old one is disposed, so a filter that
+     * will not build leaves the canvas drawing as it was.
+     */
+    setFilter(filterClass) {
+        const gl = this.checkedGl;
+        const filter = new filterClass(gl);
+        this.filter?.dispose();
+        this.filter = filter;
+        gl.useProgram(filter.program);
+
+        // Filters that pick their own samples want the texels they asked for,
+        // not a hardware blend of the ones either side.
+        const sampling = filterClass.getDisplayConfig().nearestSampling ? gl.NEAREST : gl.LINEAR;
+        gl.activeTexture(gl.TEXTURE0);
+        gl.bindTexture(gl.TEXTURE_2D, this.texture);
+        gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MAG_FILTER, sampling);
+        gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MIN_FILTER, sampling);
+
+        const bindAttribute = (name, buffer) => {
+            const location = gl.getAttribLocation(filter.program, name);
+            gl.enableVertexAttribArray(location);
+            gl.bindBuffer(gl.ARRAY_BUFFER, buffer);
+            gl.vertexAttribPointer(location, 2, gl.FLOAT, false, 0, 0);
+            return location;
+        };
+        for (const location of this.attribLocations) gl.disableVertexAttribArray(location);
+        this.attribLocations = [bindAttribute("pos", this.vertexPositionBuffer), bindAttribute("uvIn", this.uvBuffer)];
+    }
+
+    /**
+     * Release the GL objects this canvas owns. Nothing else will: a canvas
+     * element hands out one WebGL context for its lifetime, so anything created
+     * through that context stays resident however many wrappers come and go.
      */
     dispose() {
         const gl = this.checkedGl;
-        this.filter.dispose();
+        this.filter?.dispose();
+        this.filter = null;
         gl.deleteTexture(this.texture);
         gl.deleteBuffer(this.vertexPositionBuffer);
         gl.deleteBuffer(this.uvBuffer);
@@ -218,6 +242,24 @@ function fellBackBecause(canvas, reason) {
     return canvas;
 }
 
+/**
+ * Draw with `filterClass`, or with the unfiltered display if it will not build,
+ * in which case `fallbackReason` says why.
+ */
+export function useBestFilter(canvas, filterClass) {
+    let reason;
+    try {
+        canvas.setFilter(filterClass);
+        return fellBackBecause(canvas, undefined);
+    } catch (e) {
+        console.log(`Unable to use ${filterClass.getDisplayConfig().name}: ${e}`);
+        if (filterClass === PassthroughFilter) throw e;
+        reason = e?.message ?? e;
+    }
+    canvas.setFilter(PassthroughFilter);
+    return fellBackBecause(canvas, reason);
+}
+
 export function bestCanvas(canvas, filterClass) {
     let reason;
     try {

package/src/cmos.js

@@ -33,6 +33,44 @@ function fromBcd(value) {
 
 export { defaultCmos };
 
+/**
+ * CMOS persistence backed by a browser storage object, which can be unavailable, full or holding
+ * something other than what was last saved.
+ *
+ * @param {function(): Storage} getStorage typically `() => window.localStorage`. Reading that
+ *   property is itself what throws when a page is refused storage, so it happens per call, inside
+ *   the try.
+ * @param {function(*)} onSaveFailure called with the error the first time a save fails
+ */
+export function localStoragePersistence(getStorage, onSaveFailure) {
+    let saveFailureReported = false;
+    return {
+        load() {
+            try {
+                const stored = getStorage().cmosRam;
+                if (!stored) return null;
+                const parsed = JSON.parse(stored);
+                if (!Array.isArray(parsed) || parsed.length !== defaultCmos.length)
+                    throw new Error(`the stored settings are not ${defaultCmos.length} bytes`);
+                return parsed;
+            } catch (error) {
+                console.log(`Unable to read the stored CMOS settings: ${error?.message ?? error}`);
+                return null;
+            }
+        },
+        save(data) {
+            try {
+                getStorage().cmosRam = JSON.stringify(data);
+            } catch (error) {
+                console.log(`Unable to store the CMOS settings: ${error?.message ?? error}`);
+                if (saveFailureReported) return;
+                saveFailureReported = true;
+                onSaveFailure(error);
+            }
+        },
+    };
+}
+
 export class Cmos {
     constructor(persistence, cmosOverride, econet) {
         this.store = persistence ? persistence.load() : null;

package/src/disc-hfe.js

@@ -213,7 +213,7 @@ export function loadHfe(disc, data, onChange) {
             const hfeData = toHfe(disc);
             // Call the onChange handler with the updated HFE data
             onChange(hfeData);
-        });
+        }, true);
     }
 
     return disc;

package/src/disc.js

@@ -720,6 +720,7 @@ export function loadSsd(disc, data, isDsd, onChange) {
                     if (!sectorShortfall(sector)) dataCopy.set(sector.sectorData, ssdOffsetOf(sector, side, numSides));
                 onChange(dataCopy);
             },
+            true,
         );
     }
     return disc;
@@ -905,6 +906,7 @@ export class Disc {
         this.is40Track = false;
 
         this._trackWriteListeners = new Set();
+        this._savingListeners = new Set();
         this.isWriteable = isWriteable;
 
         // Track which tracks have been written since the last snapshot.
@@ -931,14 +933,32 @@ export class Disc {
         this.initSurface(0);
     }
 
-    /** @param {function(boolean, Number, Track): void} listener called once per flushed track */
-    addTrackWriteListener(listener) {
+    /**
+     * @param {function(boolean, Number, Track): void} listener called once per flushed track
+     * @param {boolean} [savesChanges] whether the listener puts the image somewhere it is read back from
+     */
+    addTrackWriteListener(listener, savesChanges = false) {
         this._trackWriteListeners.add(listener);
+        if (savesChanges) this._savingListeners.add(listener);
+    }
+
+    get savesChanges() {
+        return this._savingListeners.size > 0;
     }
 
     /** @param {function(boolean, Number, Track): void} listener */
     removeTrackWriteListener(listener) {
         this._trackWriteListeners.delete(listener);
+        this._savingListeners.delete(listener);
+    }
+
+    /** @param {function(): void} listener called once, when a track is first written to this disc */
+    notifyOnFirstTrackWrite(listener) {
+        const onFirstWrite = () => {
+            this.removeTrackWriteListener(onFirstWrite);
+            listener();
+        };
+        this.addTrackWriteListener(onFirstWrite);
     }
 
     /**

package/src/fdc.js

@@ -289,7 +289,16 @@ export function discFor(fdc, name, stringData, onChange, layout = DiscLayout.aut
     return disc;
 }
 
-export function localDisc(fdc, name, layout = DiscLayout.auto) {
+/**
+ * Create or open a disc held in the browser's local storage.
+ * @param {Object} fdc - The FDC controller object
+ * @param {string} name - The file name with extension
+ * @param {string} [layout] - one of DiscLayout; by default the image is asked what it is
+ * @param {function(*): void} [onSaveError] - called with whatever was thrown, the first time a write
+ *   cannot be stored
+ * @returns {Disc} The loaded disc object
+ */
+export function localDisc(fdc, name, layout = DiscLayout.auto, onSaveError = () => {}) {
     const discName = "disc_" + name;
     let data;
     const dataString = window.localStorage[discName];
@@ -307,12 +316,16 @@ export function localDisc(fdc, name, layout = DiscLayout.auto) {
         console.log("Loading browser-local disc " + name);
         data = utils.stringToUint8Array(dataString);
     }
+    let reportedSaveError = false;
     const onChange = (data) => {
         try {
             const str = utils.uint8ArrayToString(data);
             window.localStorage.setItem(discName, str);
         } catch (e) {
-            window.alert("Writing to localStorage failed: " + e);
+            console.log(`Unable to save browser-local disc ${name}: ${e}`);
+            if (reportedSaveError) return;
+            reportedSaveError = true;
+            onSaveError(e);
         }
     };
     return discFor(fdc, name, data, onChange, layout);

package/src/google-drive.js

@@ -49,10 +49,11 @@ export class GoogleDriveLoader {
 
     _loadScript(src) {
         // https://github.com/google/google-api-javascript-client/issues/319
-        return new Promise((resolve) => {
+        return new Promise((resolve, reject) => {
             const script = document.createElement("script");
             script.src = src;
             script.onload = resolve;
+            script.onerror = () => reject(new Error(`Failed to fetch ${src}; a browser extension may be blocking it`));
             document.body.appendChild(script);
         });
     }

package/src/jsbeeb.css

@@ -1,5 +1,6 @@
 body {
   overflow: hidden;
+  visibility: visible !important; /* see index.html */
 }
 #outer {
   display: block;
@@ -171,7 +172,7 @@ th {
 
 #hfe-list li a {
   display: grid;
-  grid-template-columns: minmax(0, 3fr) minmax(0, 2fr) minmax(0, 2fr);
+  grid-template-columns: minmax(0, 3fr) minmax(0, 2fr) minmax(0, 2fr) 7em;
   gap: 0 1rem;
   align-items: baseline;
   padding: 3px 6px;
@@ -198,6 +199,22 @@ th {
   font-family: monospace;
 }
 
+#hfe-list .provenance {
+  font-size: 0.8em;
+  opacity: 0.6;
+  font-style: italic;
+  text-align: right;
+}
+
+.hfe-provenance label {
+  margin-left: 1.5rem;
+  opacity: 0.8;
+}
+
+.hfe-provenance input {
+  margin-right: 0.3em;
+}
+
 .hfe-credit {
   font-size: 0.9em;
   opacity: 0.75;
@@ -208,6 +225,11 @@ th {
     grid-template-columns: minmax(0, 1fr);
     padding-bottom: 6px;
   }
+
+  /* Stacked into one column, so there is no column end to sit against. */
+  #hfe-list .provenance {
+    text-align: left;
+  }
 }
 
 div.filter {

package/src/machine-session.js

@@ -25,6 +25,9 @@ import sharp from "sharp";
 const FB_WIDTH = 1024;
 const FB_HEIGHT = 625;
 
+// Five times a frame, so only a machine that has stopped painting hits it.
+const BackstopSecondsPerFrame = 0.1;
+
 export class MachineSession {
     /**
      * @param {string} modelName - e.g. "B-DFS1.2", "Master"
@@ -46,6 +49,8 @@ export class MachineSession {
         this._completeFb8 = new Uint8Array(FB_WIDTH * FB_HEIGHT * 4);
         this._lastPaint = { minx: 0, miny: 0, maxx: FB_WIDTH, maxy: FB_HEIGHT };
         this._frameDirty = false;
+        this._frameCount = 0;
+        this._stopAtFrame = Infinity;
 
         // Create a real Video instance so we get pixel output
         const modelObj = findModel(modelName);
@@ -59,6 +64,8 @@ export class MachineSession {
                 // Snapshot the complete frame now, before clearPaintBuffer() wipes _fb32.
                 // This mirrors what the browser does: paint_ext fires → canvas updated → fb32 cleared.
                 this._completeFb8.set(this._fb8);
+                this._frameCount++;
+                if (this._frameCount >= this._stopAtFrame) this._machine.processor.stop();
             },
             { isAtom: modelObj.isAtom },
         );
@@ -308,6 +315,56 @@ export class MachineSession {
         await this._machine.runFor(cycles);
     }
 
+    /** Emulated cycles since power-on, undoing the per-second rebasing execute() applies */
+    get elapsedCycles() {
+        const cpu = this._machine.processor;
+        return cpu.cycleSeconds * cpu.model.cyclesPerSecond + cpu.currentCycles;
+    }
+
+    /**
+     * Run until `count` more frames have been painted, stopping on the paint
+     * itself.  A frame is 40000 cycles interlaced, 39936 not, and whatever a
+     * program driving the CRTC makes it, so stepping by cycles instead walks
+     * the sample point through the guest's frame.
+     *
+     * `completed` is false if a breakpoint fired, or the backstop ran out
+     * first.
+     *
+     * @param {number} [count=1] frames to advance
+     * @param {Object} [opts]
+     * @param {number} [opts.maxCycles] how long to wait on a machine that is not painting
+     * @returns {Promise<{framesRun: number, cyclesRun: number, completed: boolean}>}
+     */
+    async runFrames(count = 1, { maxCycles } = {}) {
+        const cpu = this._machine.processor;
+        const backstop = maxCycles ?? count * BackstopSecondsPerFrame * cpu.model.cyclesPerSecond;
+        const startFrame = this._frameCount;
+        const startCycles = this.elapsedCycles;
+        // execute() adds each request to a running targetCycles, so budget left
+        // unspent by an early stop would silently lengthen the caller's next run.
+        const unspentBefore = cpu.targetCycles - cpu.currentCycles;
+
+        this._stopAtFrame = startFrame + count;
+        try {
+            await this._machine.runFor(backstop);
+        } finally {
+            this._stopAtFrame = Infinity;
+            cpu.targetCycles = cpu.currentCycles + unspentBefore;
+        }
+
+        const framesRun = this._frameCount - startFrame;
+        return {
+            framesRun,
+            cyclesRun: this.elapsedCycles - startCycles,
+            completed: framesRun >= count,
+        };
+    }
+
+    /** Frames painted since the session was created; a hard reset does not zero it */
+    get frameCount() {
+        return this._frameCount;
+    }
+
     /**
      * Run until PC reaches targetAddr (like a breakpoint), or timeout.
      */