jsbeeb 1.18.0 → 1.19.1

package/README.md

@@ -51,15 +51,15 @@ KEY.<host key>=<BBC key>
 Add one for each key you want to change. For example, Superior Software's Space Invaders fires with `COPY`; this makes
 `Enter` fire instead:
 
-[`https://bbc.xania.org/?disc1=sth:Superior/SpaceInvaders-Superior.zip&autoboot&KEY.ENTER=COPY`](https://bbc.xania.org/?disc1=sth%3ASuperior%2FSpaceInvaders-Superior.zip&autoboot&KEY.ENTER=COPY)
+[`https://bbc.xania.org/?disc1=sth:Superior/SpaceInvaders-Superior.zip&autoboot&KEY.ENTER=COPY`](https://bbc.xania.org/?disc1=sth:Superior/SpaceInvaders-Superior.zip&autoboot&KEY.ENTER=COPY)
 
 Superior's Frogger uses `A`/`Z`/`DELETE`/`COPY` to move; this puts it on the arrow keys:
 
-[`https://bbc.xania.org/?disc1=sth:Superior/Frogger-Superior.zip&autoboot&KEY.UP=A&KEY.DOWN=Z&KEY.LEFT=DELETE&KEY.RIGHT=COPY`](https://bbc.xania.org/?disc1=sth%3ASuperior%2FFrogger-Superior.zip&autoboot&KEY.UP=A&KEY.DOWN=Z&KEY.LEFT=DELETE&KEY.RIGHT=COPY)
+[`https://bbc.xania.org/?disc1=sth:Superior/Frogger-Superior.zip&autoboot&KEY.UP=A&KEY.DOWN=Z&KEY.LEFT=DELETE&KEY.RIGHT=COPY`](https://bbc.xania.org/?disc1=sth:Superior/Frogger-Superior.zip&autoboot&KEY.UP=A&KEY.DOWN=Z&KEY.LEFT=DELETE&KEY.RIGHT=COPY)
 
 And Superior's Hunchback steers with `CAPS LOCK` and `CTRL`, which the arrow keys can stand in for:
 
-[`https://bbc.xania.org/?disc1=sth:Superior/Hunchback-Superior.zip&autoboot&KEY.LEFT=CAPSLOCK&KEY.RIGHT=CTRL`](https://bbc.xania.org/?disc1=sth%3ASuperior%2FHunchback-Superior.zip&autoboot&KEY.LEFT=CAPSLOCK&KEY.RIGHT=CTRL)
+[`https://bbc.xania.org/?disc1=sth:Superior/Hunchback-Superior.zip&autoboot&KEY.LEFT=CAPSLOCK&KEY.RIGHT=CTRL`](https://bbc.xania.org/?disc1=sth:Superior/Hunchback-Superior.zip&autoboot&KEY.LEFT=CAPSLOCK&KEY.RIGHT=CTRL)
 
 The **host key** names are jsbeeb's names for the keys on your own keyboard. Most are what you'd expect, but note:
 
@@ -141,7 +141,7 @@ GP.<gamepad control>=<BBC key>
 By default the D-pad presses the "Snapper" keys (`Z`, `X`, `:`, `/`), the `A` button presses `RETURN` and `Start`
 presses `SPACE`. To play Superior's Space Invaders on a pad, where `COPY` fires:
 
-[`https://bbc.xania.org/?disc1=sth:Superior/SpaceInvaders-Superior.zip&autoboot&GP.FIRE=COPY`](https://bbc.xania.org/?disc1=sth%3ASuperior%2FSpaceInvaders-Superior.zip&autoboot&GP.FIRE=COPY)
+[`https://bbc.xania.org/?disc1=sth:Superior/SpaceInvaders-Superior.zip&autoboot&GP.FIRE=COPY`](https://bbc.xania.org/?disc1=sth:Superior/SpaceInvaders-Superior.zip&autoboot&GP.FIRE=COPY)
 
 The gamepad control names are:
 

package/package.json

@@ -7,7 +7,7 @@
   "name": "jsbeeb",
   "description": "Emulate a BBC Micro",
   "repository": "git@github.com:mattgodbolt/jsbeeb.git",
-  "version": "1.18.0",
+  "version": "1.19.1",
   "//engines": "If you change the version of Node, it must also be updated at the top of the Dockerfile.",
   "engines": {
     "node": ">=24.15.0"

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");
@@ -60,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.
@@ -68,15 +80,19 @@ 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);
         });
@@ -260,10 +276,10 @@ export function useBestFilter(canvas, filterClass) {
     return fellBackBecause(canvas, reason);
 }
 
-export function bestCanvas(canvas, filterClass) {
+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;
@@ -275,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/main.js

@@ -374,6 +374,10 @@ let tryGl = true;
 if (parsedQuery.glEnabled !== undefined) {
     tryGl = parsedQuery.glEnabled === "true";
 }
+let lowLatency = true;
+if (parsedQuery.lowLatency !== undefined) {
+    lowLatency = parsedQuery.lowLatency === "true";
+}
 const screenCanvas = document.getElementById("screen");
 
 const errorDialog = document.getElementById("error-dialog");
@@ -516,7 +520,9 @@ function createCanvasForFilter(filterClass) {
     // creating the context, which fixes its initial viewport.
     sizeCanvasFor(filterClass);
 
-    const newCanvas = tryGl ? canvasLib.bestCanvas(screenCanvas, filterClass) : new canvasLib.Canvas(screenCanvas);
+    const newCanvas = tryGl
+        ? canvasLib.bestCanvas(screenCanvas, filterClass, lowLatency)
+        : new canvasLib.Canvas(screenCanvas, lowLatency);
     reportAnyFallback(newCanvas, filterClass);
     return newCanvas;
 }

package/src/snapshot-helpers.js

@@ -139,7 +139,6 @@ export function buildVideoState(ulaControl, ulaPalette, crtcRegs, nulaCollook, c
             wasDbl: false,
             gfx: false,
             flash: false,
-            flashOn: false,
             flashTime: 0,
             heldChar: 0,
             holdChar: false,

package/src/teletext.js

@@ -12,7 +12,7 @@ export class Teletext {
         this.dbl = this.oldDbl = this.secondHalfOfDouble = this.wasDbl = false;
         this.gfx = false;
         this.conceal = false;
-        this.flash = this.flashOn = false;
+        this.flash = false;
         this.flashTime = 0;
         this.heldChar = 0;
         this.holdChar = false;
@@ -175,7 +175,6 @@ export class Teletext {
             gfx: this.gfx,
             conceal: this.conceal,
             flash: this.flash,
-            flashOn: this.flashOn,
             flashTime: this.flashTime,
             heldChar: this.heldChar,
             holdChar: this.holdChar,
@@ -202,7 +201,6 @@ export class Teletext {
         this.gfx = state.gfx;
         this.conceal = state.conceal ?? false;
         this.flash = state.flash;
-        this.flashOn = state.flashOn;
         this.flashTime = state.flashTime;
         this.heldChar = state.heldChar;
         this.holdChar = state.holdChar;
@@ -300,7 +298,6 @@ export class Teletext {
         }
         if (wasGfx && (wasHoldChar || this.holdChar) && this.dbl === this.oldDbl) {
             data = this.heldChar;
-            if (data >= 0x40 && data < 0x60) data = 0x20;
             this.curGlyphs = this.heldGlyphs;
         } else {
             this.heldChar = 0x20;
@@ -333,13 +330,14 @@ export class Teletext {
 
         // 3:1 flash ratio.
         if (++this.flashTime === 64) this.flashTime = 0;
-        // Flashing text starts off in sync with a slow cursor, extinguished
-        // together.  Multiple MODE changes gradually desynchronise the
-        // frame counters.
-        // TODO: this point is being reached a MOS-dependent number of times
-        // before Video.frameCount rises.  The next line achieves initial
-        // sync under MOS 1.20 only.
-        this.flashOn = this.flashTime < 16;
+    }
+
+    // Flashing text starts off in sync with a slow cursor, extinguished together. Multiple MODE
+    // changes gradually desynchronise the frame counters.
+    // TODO: setDEW is reached a MOS-dependent number of times before Video.frameCount rises, so
+    // the initial sync here holds under MOS 1.20 only.
+    get hideFlashing() {
+        return this.flashTime < 16;
     }
 
     setDISPTMG(level) {
@@ -429,7 +427,7 @@ export class Teletext {
         // Conceal (code 24) is "Set At", and a colour code only reveals from the cell after itself.
         if (this.conceal) concealThisCell = true;
 
-        if (concealThisCell || (flashThisCell && this.flashOn) || (this.secondHalfOfDouble && !this.dbl)) {
+        if (concealThisCell || (flashThisCell && this.hideFlashing) || (this.secondHalfOfDouble && !this.dbl)) {
             const backgroundColour = this.colour[(this.bg & 7) << 5];
             for (let i = 0; i < 16; ++i) {
                 buf[offset++] = backgroundColour;

package/src/url-params.js

@@ -41,18 +41,15 @@ export const ParamTypes = {
 export function parseQueryString(queryString, paramTypes = {}) {
     if (!queryString) return {};
 
-    // workaround for shonky python web server
-    const cleanQueryString = queryString.endsWith("/") ? queryString.substring(0, queryString.length - 1) : queryString;
-
     const parsedQuery = {};
 
-    cleanQueryString.split("&").forEach(function (keyval) {
+    queryString.split("&").forEach(function (keyval) {
         if (!keyval) return;
 
         const keyAndVal = keyval.split("=");
         const key = decodeURIComponent(keyAndVal[0]);
         let val = null;
-        if (keyAndVal.length > 1) val = decodeURIComponent(keyAndVal[1]);
+        if (keyAndVal.length > 1) val = decodeURIComponent(keyAndVal.slice(1).join("="));
 
         const paramType = paramTypes[key] || ParamTypes.STRING;
 
@@ -90,12 +87,26 @@ export function parseQueryString(queryString, paramTypes = {}) {
 }
 
 /**
- * Build a URL string from base URL and query parameters
- * @param {string} baseUrl - The base URL (without query string)
- * @param {Object} parsedQuery - Object containing query parameters
- * @param {Object.<string, ParamType>} [paramTypes={}] - Object mapping parameter names to their types
- * @returns {string} The complete URL with query parameters
+ * Characters RFC 3986 allows literally in a query that `encodeURIComponent` escapes anyway. `&`,
+ * `=`, `+`, `#`, `%` and space are left escaped because they delimit something, and `?` because a
+ * URL with a second one in it reads as broken even though the grammar permits it.
  */
+const QueryLiterals = "$,/:;@";
+
+const EscapedQueryLiterals = new RegExp(
+    [...QueryLiterals].map((char) => `%${char.charCodeAt(0).toString(16).toUpperCase()}`).join("|"),
+    "g",
+);
+
+/**
+ * Percent-encode a key or value for a query string, escaping only what delimits something
+ * @param {string} component - The key or value to encode
+ * @returns {string} The encoded component
+ */
+function encodeQueryComponent(component) {
+    return encodeURIComponent(component).replace(EscapedQueryLiterals, decodeURIComponent);
+}
+
 /**
  * Append a parameter to the URL
  * @param {string} url - Current URL
@@ -105,13 +116,20 @@ export function parseQueryString(queryString, paramTypes = {}) {
  * @returns {Object} Updated URL and separator
  */
 function appendParam(url, sep, key, value = undefined) {
-    url += sep + encodeURIComponent(key);
+    url += sep + encodeQueryComponent(key);
     if (value !== undefined) {
-        url += "=" + encodeURIComponent(value);
+        url += "=" + encodeQueryComponent(value);
     }
     return { url, sep: "&" };
 }
 
+/**
+ * Build a URL string from base URL and query parameters
+ * @param {string} baseUrl - The base URL (without query string)
+ * @param {Object} parsedQuery - Object containing query parameters
+ * @param {Object.<string, ParamType>} [paramTypes={}] - Object mapping parameter names to their types
+ * @returns {string} The complete URL with query parameters
+ */
 export function buildUrlFromParams(baseUrl, parsedQuery, paramTypes = {}) {
     let url = baseUrl;
     let sep = "?";

package/src/web/audio-renderer.js

@@ -3,21 +3,26 @@
 const lowPassFilterFreq = sampleRate / 2;
 const RC = 1 / (2 * Math.PI * lowPassFilterFreq);
 
+const InputSampleRate = 4000000.0 / 8;
+const MaxQueuedMs = 250;
+
+const samplesFor = (ms) => (InputSampleRate * ms) / 1000;
+
 class SoundChipProcessor extends AudioWorkletProcessor {
     constructor(...args) {
         super(...args);
 
-        this.inputSampleRate = 4000000.0 / 8;
+        this.inputSampleRate = InputSampleRate;
         this._lastSample = 0;
         this._lastFilteredOutput = 0;
         this.queue = [];
-        this._queueSizeBytes = 0;
+        this._queueSizeSamples = 0;
         this.dropped = 0;
         this.underruns = 0;
         this.targetLatencyMs = 1000 * (1 / 50); // One frame
-        this.startQueueSizeBytes = this.inputSampleRate / this.targetLatencyMs / 2;
+        this.startQueueSizeSamples = samplesFor(this.targetLatencyMs);
         this.running = false;
-        this.maxQueueSizeBytes = this.inputSampleRate * 0.25;
+        this.maxQueueSizeSamples = samplesFor(MaxQueuedMs);
         this.port.onmessage = (event) => {
             // TODO: even better than this, send over register settings/catch up and run the audio work _here_
             this.onBuffer(event.data.time, event.data.buffer);
@@ -47,19 +52,19 @@ class SoundChipProcessor extends AudioWorkletProcessor {
 
     onBuffer(time, buffer) {
         this.queue.push({ offset: 0, time, buffer });
-        this._queueSizeBytes += buffer.length;
+        this._queueSizeSamples += buffer.length;
         this.cleanQueue();
-        if (!this.running && this._queueSizeBytes >= this.startQueueSizeBytes) this.running = true;
+        if (!this.running && this._queueSizeSamples >= this.startQueueSizeSamples) this.running = true;
     }
 
     _shift() {
         const dropped = this.queue.shift();
-        this._queueSizeBytes -= dropped.buffer.length;
+        this._queueSizeSamples -= dropped.buffer.length;
     }
 
     cleanQueue() {
         const maxLatency = this.targetLatencyMs * 2;
-        while (this._queueSizeBytes > this.maxQueueSizeBytes || this._queueAge() > maxLatency) {
+        while (this._queueSizeSamples > this.maxQueueSizeSamples || this._queueAge() > maxLatency) {
             this._shift();
             this.dropped++;
         }

package/tests/test-machine.js

@@ -138,17 +138,13 @@ export class TestMachine {
         throw new Error(`Cursor did not reach state ${on} in time (cursorOnThisFrame=${video.cursorOnThisFrame})`);
     }
 
-    /**
-     * Run until the teletext flash state reaches the desired phase.
-     * @param {boolean} on - true for flash-on (flashing cells blanked), false for flash-off
-     */
-    async runToFlashState(on) {
+    async runUntilFlashHidden() {
         const teletext = this.processor.video.teletext;
         for (let i = 0; i < 100; i++) {
-            if (teletext.flashOn === on) return;
+            if (teletext.hideFlashing) return;
             await this.runFor(40000);
         }
-        throw new Error(`Flash did not reach state ${on} in time (flashOn=${teletext.flashOn})`);
+        throw new Error("Flashing text did not reach its hidden phase in time");
     }
 
     async runUntilVblank() {