jsbeeb 1.17.1 → 1.19.0

package/package.json

@@ -7,7 +7,7 @@
   "name": "jsbeeb",
   "description": "Emulate a BBC Micro",
   "repository": "git@github.com:mattgodbolt/jsbeeb.git",
-  "version": "1.17.1",
+  "version": "1.19.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"
@@ -106,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) {
@@ -1370,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/canvas.js

@@ -14,15 +14,27 @@ export function getFilterForMode(mode) {
     return DISPLAY_MODE_FILTERS[mode] || DISPLAY_MODE_FILTERS.rgb;
 }
 
+// The hint asks the browser to skip the renderer compositor queue and hand the buffer straight to
+// the display controller, saving a frame or so of output latency. It is only a hint, so read back
+// what we actually got.
+// https://developer.chrome.com/blog/desynchronized
+function reportDesynchronized(ctx, asked) {
+    // A lost context returns null here rather than an attributes object.
+    const honoured = ctx.getContextAttributes?.()?.desynchronized ?? false;
+    if (!asked) console.log("Low latency canvas turned off");
+    else console.log(`Low latency canvas ${honoured ? "in use" : "not available"}`);
+}
+
 export class Canvas {
     /** The 2D canvas draws the framebuffer as-is, which is what this filter is. */
     get filterClass() {
         return PassthroughFilter;
     }
 
-    constructor(canvas) {
-        this.ctx = canvas.getContext("2d", { alpha: false });
+    constructor(canvas, lowLatency = true) {
+        this.ctx = canvas.getContext("2d", { alpha: false, desynchronized: lowLatency });
         if (this.ctx === null) throw new Error("Unable to get a 2D context");
+        reportDesynchronized(this.ctx, lowLatency);
         this.ctx.fillStyle = "black";
         this.ctx.fillRect(0, 0, 1024, 625);
         this.backBuffer = window.document.createElement("canvas");
@@ -38,6 +50,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;
@@ -55,7 +72,7 @@ export class GlCanvas {
         return this.filter.constructor;
     }
 
-    constructor(canvas, filterClass) {
+    constructor(canvas, filterClass, lowLatency = true) {
         // failIfMajorPerformanceCaveat prevents the use of CPU based WebGL
         // rendering, which is much worse than simply using a 2D canvas for
         // rendering.
@@ -63,38 +80,33 @@ export class GlCanvas {
             alpha: false,
             antialias: false,
             depth: false,
-            preserveDrawingBuffer: false,
+            // A desynchronized context can be scanned out while it is cleared but not yet redrawn,
+            // which flickers unless the buffer is preserved between frames.
+            preserveDrawingBuffer: lowLatency,
             stencil: false,
             failIfMajorPerformanceCaveat: true,
+            desynchronized: lowLatency,
         };
         const gl = canvas.getContext("webgl", glAttrs) || canvas.getContext("experimental-webgl", glAttrs);
         this.gl = gl;
         if (!gl) {
             throw new Error("Unable to create a GL context");
         }
+        reportDesynchronized(gl, lowLatency);
         const checkedGl = webglDebug.makeDebugContext(gl, function (err, funcName) {
             throw new Error("Problem creating GL context: " + webglDebug.glEnumToString(err) + " in " + funcName);
         });
 
         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 +118,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,10 +258,28 @@ function fellBackBecause(canvas, reason) {
     return canvas;
 }
 
-export function bestCanvas(canvas, filterClass) {
+/**
+ * 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, lowLatency = true) {
     let reason;
     try {
-        return new GlCanvas(canvas, filterClass);
+        return new GlCanvas(canvas, filterClass, lowLatency);
     } catch (e) {
         // Either WebGL is unavailable or this particular filter declined it.
         reason = e?.message ?? e;
@@ -233,11 +291,11 @@ export function bestCanvas(canvas, filterClass) {
     // 2D fallback below would throw and take the emulator with it.
     if (filterClass !== PassthroughFilter) {
         try {
-            return fellBackBecause(new GlCanvas(canvas, PassthroughFilter), reason);
+            return fellBackBecause(new GlCanvas(canvas, PassthroughFilter, lowLatency), reason);
         } catch (e) {
             console.log("Unable to fall back to the passthrough filter: " + e);
         }
     }
 
-    return fellBackBecause(new Canvas(canvas), reason);
+    return fellBackBecause(new Canvas(canvas, lowLatency), reason);
 }

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