jsbeeb 1.14.0 → 1.15.0

package/README.md

@@ -11,6 +11,7 @@ different peripherals.
 ## Table of Contents
 
 - [Keyboard Mappings](#keyboard-mappings)
+- [Remapping Keys](#remapping-keys)
 - [Emulator Shortcuts](#emulator-shortcuts)
 - [Save State and Rewind](#save-state-and-rewind)
 - [Getting Set Up to Run Locally](#getting-set-up-to-run-locally)
@@ -36,6 +37,65 @@ The BBC had a somewhat different-looking keyboard to a modern PC, and so it's us
 To play right now, visit [https://bbc.xania.org/](https://bbc.xania.org/). To load the default disc image (Elite in this
 case), press shift-F12 (which is shift-Break on the BBC).
 
+### Remapping Keys
+
+Plenty of games use keys that are awkward on a modern keyboard: `COPY` (which is `End`, or `fn`+`→` on a Mac), or
+`CAPS LOCK` (which on a Mac toggles rather than acting as a key you hold down). Any host key can be made to press any
+BBC key by adding a `KEY.` parameter to the URL:
+
+```
+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)
+
+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)
+
+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)
+
+The **host key** names are jsbeeb's names for the keys on your own keyboard. Most are what you'd expect, but note:
+
+- `ENTER` (the BBC's `RETURN` key is called `ENTER` on the host side)
+- `K0` to `K9` for the number keys, `NUMPAD0` to `NUMPAD9` for the keypad
+- `SHIFT_LEFT` / `SHIFT_RIGHT`, `CTRL_LEFT` / `CTRL_RIGHT`, `ALT_LEFT` / `ALT_RIGHT` to distinguish the two of each
+- `BACK_QUOTE`, `APOSTROPHE`, `SEMICOLON`, `MINUS`, `EQUALS`, `HASH`, `BACKSLASH`, `LEFT_SQUARE_BRACKET`,
+  `RIGHT_SQUARE_BRACKET` for punctuation
+
+The **BBC key** names are:
+
+```
+RETURN COPY DELETE ESCAPE TAB SPACE SHIFT SHIFTLOCK CAPSLOCK CTRL
+LEFT RIGHT UP DOWN
+A-Z, K0-K9 (the number keys), F0-F9 (the red function keys)
+SEMICOLON_PLUS MINUS COMMA PERIOD SLASH AT COLON_STAR HAT_TILDE
+UNDERSCORE_POUND PIPE_BACKSLASH LEFT_SQUARE_BRACKET RIGHT_SQUARE_BRACKET
+
+(and, on the Master's numeric keypad only)
+NUMPAD0-NUMPAD9 NUMPADPLUS NUMPADMINUS NUMPADSLASH NUMPADASTERISK NUMPADCOMMA
+NUMPADHASH NUMPADENTER NUMPAD_DELETE NUMPAD_DECIMAL_POINT
+```
+
+Some things to know:
+
+- Names are case-insensitive, and a remapped key ignores the `SHIFT` state, so `KEY.ENTER=COPY` presses `COPY` whether
+  or not shift is held.
+- Remapping replaces what that host key normally does; in the Space Invaders example above, `Enter` no longer presses
+  `RETURN`.
+- The remapping is applied on top of whichever keyboard layout is selected, and survives changing layout or model.
+- If a name isn't recognised the mapping is skipped, and the emulator says so on startup, naming the parameter that
+  was at fault.
+- On the Atom, use the Atom's own key names (`LOCK`, `UP_DOWN`, `LEFT_RIGHT` and so on) rather than the BBC's.
+
+The definitive lists are `keyCodes` (host) and `BBC` (BBC micro) in [`src/utils.js`](src/utils.js), and `ATOM` in
+[`src/utils_atom.js`](src/utils_atom.js).
+
 ### Emulator Shortcuts
 
 | Shortcut       | Action                          |
@@ -63,6 +123,35 @@ jsbeeb supports both USB/Bluetooth gamepads and mouse-based analogue joystick em
 - X-axis: Left = 65535, Right = 0
 - Y-axis: Up = 65535, Down = 0
 
+A gamepad presses BBC keys, and which key each control presses can be changed from the URL in the same way as
+[remapping the keyboard](#remapping-keys):
+
+```
+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)
+
+The gamepad control names are:
+
+- `FIRE` — every button at once, which is usually what you want for a one-button game
+- `UP` `DOWN` `LEFT` `RIGHT` — both analogue sticks at once, plus one face button each (`UP` is also `A`, `DOWN` is
+  `X`, `LEFT` is `Y`, `RIGHT` is `B`)
+- `UP1` `DOWN1` `LEFT1` `RIGHT1` — the left stick only; `UP2` `DOWN2` … — the right stick only; `UP3` `DOWN3` … — the
+  face buttons only
+- `A` `B` `X` `Y` `START` `BACK` `LB` `RB` `LT` `RT` — individual buttons, by their Xbox 360 names
+- `FIRE1` `FIRE2` — clicking the left and right sticks
+
+The BBC key names are the same as for the keyboard, and digits may be written either way round: `GP.A=1` and `GP.A=K1`
+both press `1`. Unlike `KEY.`, gamepad mappings are BBC-only: there's no Atom equivalent. The D-pad's default mapping
+can't currently be changed.
+
+The older `LEFT=`, `RIGHT=`, `UP=`, `DOWN=` and `FIRE=` parameters (no `GP.` prefix) still work and mean the same
+thing.
+
 ## Getting Set Up to Run Locally
 
 ### Prerequisites
@@ -157,6 +246,8 @@ sudo rpm -i out/dist/jsbeeb-1.0.1.x86_64.rpm
 - `disc1=sth:ZZZ` - loads disc ZZZ from the Stairway to Hell archive
 - `tape=XXX` - loads tape XXX (from the `tapes/` directory)
 - `tape=sth:ZZZ` - loads tape ZZZ from the Stairway to Hell archive
+- `KEY.X=Y` - makes host key `X` press BBC key `Y`, e.g. `KEY.ENTER=COPY`. See
+  [Remapping Keys](#remapping-keys).
 - `patch=P` - applies a memory patch `P`. See below.
 - `loadBasic=X` - loads 'X' (a resource on the webserver) as text, tokenises it and puts it in `PAGE` as if you'd typed
   it in to the emulator
@@ -170,6 +261,9 @@ sudo rpm -i out/dist/jsbeeb-1.0.1.x86_64.rpm
 - `cpuMultiplier=X` speeds up the CPU by a factor of `X` relative to the peripherals: video, sound and the VIAs keep
   running at their real-world rates. May be fractional or below one to slow the CPU down. NB disc loads become
   unreliable with a too-slow CPU, and running too fast might cause the browser to hang.
+- `tubeCpuMultiplier=X` overclocks the second processor by a factor of `X`, which may be fractional. `1`, the default,
+  runs it at the real part's own clock: 3MHz for the 6502 second processor a BBC B takes, 4MHz for the 65C102 Turbo
+  board a Master takes. Below about 2.2MHz the MOS's unhandshaken tube transfers lose data.
 - `sbLeft` / `sbRight` / `sbBottom` - a URL to place left of, right of, or below the cub monitor. The left and right
   should be around 648 high and the bottom image should be around 896 wide. Left and right wider than 300 will run into
   problems on smaller screens; bottom taller than 100 or so similarly.

package/package.json

@@ -7,7 +7,7 @@
   "name": "jsbeeb",
   "description": "Emulate a BBC Micro",
   "repository": "git@github.com:mattgodbolt/jsbeeb.git",
-  "version": "1.14.0",
+  "version": "1.15.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"

package/src/6502.js

@@ -15,9 +15,6 @@ import { AtomMMC2 } from "./mmc.js";
 
 const signExtend = utils.signExtend;
 
-// Speed of the second processor relative to the host, as fitted to a Master Turbo.
-export const DefaultTubeCpuMultiplier = 2;
-
 function _set(byte, mask, set) {
     return (byte & ~mask) | (set ? mask : 0);
 }
@@ -410,10 +407,13 @@ class Base6502 {
 }
 
 class Tube6502 extends Base6502 {
-    constructor(model, cpu, { cpuMultiplier = DefaultTubeCpuMultiplier } = {}) {
+    constructor(model, cpu, { cpuMultiplier = 1 } = {}) {
         super(model, { cycleAccurate: false });
 
+        if (!(cpuMultiplier > 0)) throw new Error(`Tube CPU multiplier must be positive, got ${cpuMultiplier}`);
+
         this.cycles = 0;
+        this.cyclesPerHostCycle = model.clockMhz / cpu.model.clockMhz;
         this.cpuMultiplier = cpuMultiplier;
         this.romPaged = true;
         this.memory = new Uint8Array(65536);
@@ -479,7 +479,7 @@ class Tube6502 extends Base6502 {
     }
 
     execute(cycles) {
-        this.cycles += (cycles * this.cpuMultiplier) | 0;
+        this.cycles += cycles * this.cyclesPerHostCycle * this.cpuMultiplier;
         if (this.cycles < 3) return;
         while (this.cycles > 0) {
             const opcode = this.readmem(this.pc);
@@ -670,6 +670,7 @@ export class Cpu6502 extends Base6502 {
         this.hasTube = !!this.config.tube;
         this.hasMusic5000 = !!this.config.hasMusic5000;
         this.hasTeletextAdaptor = !!this.config.hasTeletextAdaptor;
+        this.teletextAdaptor = this.hasTeletextAdaptor ? new TeletextAdaptor(this) : null;
         this.tube = this.hasTube
             ? new Tube6502(this.config.tube, this, { cpuMultiplier: this.config.tubeCpuMultiplier })
             : new FakeTube();
@@ -697,7 +698,7 @@ export class Cpu6502 extends Base6502 {
             getGamepads: this.config.getGamepads,
         });
         this.uservia = new via.UserVia(this, this.scheduler, this.model.isMaster, this.config.userPort);
-        this.acia = new Acia(this, this.soundChip.toneGenerator, this.scheduler, this.touchScreen, this.relayNoise);
+        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.soundChip.setScheduler(this.scheduler);
@@ -1361,7 +1362,6 @@ export class Cpu6502 extends Base6502 {
         this.adconverter.reset();
 
         this.touchScreen = new TouchScreen(this.scheduler);
-        if (this.hasTeletextAdaptor) this.teletextAdaptor = new TeletextAdaptor(this);
         if (this.econet) this.filestore = new Filestore(this, this.econet);
     }
 
@@ -1422,8 +1422,7 @@ export class Cpu6502 extends Base6502 {
     buildPolltime() {
         const nop = (_cycles) => {};
         const tubeStuff = this.hasTube ? (cycles) => this.tube.execute(cycles) : nop;
-        // The adaptor itself does not exist until reset() runs, so branch on the fitting, not the object.
-        const teletextStuff = this.hasTeletextAdaptor ? (cycles) => this.teletextAdaptor.polltime(cycles) : nop;
+        const teletextStuff = this.teletextAdaptor ? (cycles) => this.teletextAdaptor.polltime(cycles) : nop;
         const musicStuff = this.music5000 ? (cycles) => this.music5000.polltime(cycles) : nop;
         const econetStuff = this.econet
             ? (cycles) => {

package/src/acia.js

@@ -5,10 +5,10 @@
 // http://www.classiccmp.org/dunfield/r/6850.pdf
 
 export class Acia {
-    constructor(cpu, toneGen, scheduler, rs423Handler, relayNoise) {
+    constructor(cpu, toneGen, scheduler, relayNoise) {
         this.cpu = cpu;
         this.toneGen = toneGen;
-        this.rs423Handler = rs423Handler;
+        this.rs423Handler = null;
         this.relayNoise = relayNoise;
 
         this.sr = 0x00;
@@ -22,17 +22,27 @@ export class Acia {
         this.hadDcdHigh = false;
         this.serialReceiveRate = 0;
         this.serialReceiveCyclesPerByte = 0;
+        this.serialTransmitRate = 0;
+        this.serialTransmitCyclesPerByte = 0;
 
         this.setSerialReceive(19200);
+        this.setSerialTransmit(19200);
         this.txCompleteTask = scheduler.newTask(() => {
             this.sr |= 0x02; // set the TDRE
+            this.updateIrq();
         });
         this.runTapeTask = scheduler.newTask(() => this.runTape());
         this.runRs423Task = scheduler.newTask(() => this.runRs423());
     }
 
+    // MC6850: the transmit interrupt is selected by CR6:CR5 = 01 and follows
+    // TDRE, which a high CTS inhibits.
+    txIrq() {
+        return (this.cr & 0x60) === 0x20 && (this.sr & 0x0a) === 0x02;
+    }
+
     updateIrq() {
-        if (this.sr & this.cr & 0x80) {
+        if (this.sr & this.cr & 0x80 || this.txIrq()) {
             this.cpu.interrupt |= 0x04;
         } else {
             this.cpu.interrupt &= ~0x04;
@@ -77,6 +87,7 @@ export class Acia {
             return this.dr;
         } else {
             let result = (this.sr & 0x7f) | (this.sr & this.cr & 0x80);
+            if (this.txIrq()) result |= 0x80;
             // MC6850: "A low CTS indicates that there is a Clear-to-Send
             // from the modem. In the high state, the Transmit Data Register
             // Empty bit is inhibited".
@@ -100,10 +111,7 @@ export class Acia {
     write(addr, val) {
         if (addr & 1) {
             this.sr &= ~0x02;
-            // It's not clear how long this can take; it's when the shift register is loaded.
-            // That could be straight away if not already tx-ing, but as we don't really tx,
-            // be conservative here.
-            this.txCompleteTask.reschedule(2000);
+            this.txCompleteTask.reschedule(this.serialTransmitCyclesPerByte);
             this.updateIrq();
             if (this.rs423Selected && this.rs423Handler) this.rs423Handler.onTransmit(val);
         } else {
@@ -114,6 +122,8 @@ export class Acia {
             } else {
                 this.cr = val;
                 this.setSerialReceive(this.serialReceiveRate);
+                this.setSerialTransmit(this.serialTransmitRate);
+                this.updateIrq();
             }
         }
     }
@@ -212,7 +222,7 @@ export class Acia {
             tapeDcdLineLevel: this.tapeDcdLineLevel,
             hadDcdHigh: this.hadDcdHigh,
             serialReceiveRate: this.serialReceiveRate,
-            serialReceiveCyclesPerByte: this.serialReceiveCyclesPerByte,
+            serialTransmitRate: this.serialTransmitRate,
             txCompleteTaskOffset: this.txCompleteTask.scheduled()
                 ? this.txCompleteTask.expireEpoch - scheduler.epoch
                 : null,
@@ -230,8 +240,10 @@ export class Acia {
         this.tapeCarrierCount = state.tapeCarrierCount;
         this.tapeDcdLineLevel = state.tapeDcdLineLevel;
         this.hadDcdHigh = state.hadDcdHigh;
-        this.serialReceiveRate = state.serialReceiveRate;
-        this.serialReceiveCyclesPerByte = state.serialReceiveCyclesPerByte;
+        // The byte times are derived from the rates and the restored word format, not saved.
+        this.setSerialReceive(state.serialReceiveRate);
+        // Snapshots predating transmit timing have no saved rate.
+        this.setSerialTransmit(state.serialTransmitRate ?? 19200);
         this.updateIrq();
 
         this.txCompleteTask.cancel();
@@ -294,7 +306,8 @@ export class Acia {
                 parityBits = 1;
                 break;
         }
-        return wordLength + stopBits + parityBits;
+        const startBits = 1;
+        return startBits + wordLength + stopBits + parityBits;
     }
 
     rts() {
@@ -307,6 +320,11 @@ export class Acia {
         this.serialReceiveCyclesPerByte = this.secondsToCycles(this.numBitsPerByte() / rate);
     }
 
+    setSerialTransmit(rate) {
+        this.serialTransmitRate = rate;
+        this.serialTransmitCyclesPerByte = this.secondsToCycles(this.numBitsPerByte() / rate);
+    }
+
     runTape() {
         if (this.tape) this.runTapeTask.reschedule(this.tape.poll(this));
     }

package/src/config.js

@@ -1,7 +1,14 @@
 "use strict";
-import { allModels, findModel } from "./models.js";
+import { allModels, findModel, tubeModelFor } from "./models.js";
 import { getFilterForMode } from "./canvas.js";
 
+const round = (value) => Number(value.toFixed(2));
+
+/** @returns {string} the speed a multiplier gives this machine's co-processor, e.g. "1.6x (4.8MHz)". */
+export function tubeCpuSpeedLabel(multiplier, model) {
+    return `${round(multiplier)}x (${round(multiplier * tubeModelFor(model).clockMhz)}MHz)`;
+}
+
 /**
  * The sideways ROMs the optional fittings need, in the order they claim banks.
  *
@@ -100,6 +107,7 @@ export class Config extends EventTarget {
             if (!link) return;
             this.changed.model = link.dataset.target;
             this.setDropdownText(link.textContent);
+            this.showTubeCpuMultiplier(this.tubeCpuMultiplier, findModel(link.dataset.target));
             this.showRestartPending();
         });
 
@@ -113,8 +121,8 @@ export class Config extends EventTarget {
         }
 
         document.getElementById("tubeCpuMultiplier").addEventListener("input", () => {
-            const val = parseInt(document.getElementById("tubeCpuMultiplier").value, 10);
-            document.getElementById("tubeCpuMultiplierValue").textContent = val;
+            const val = parseFloat(document.getElementById("tubeCpuMultiplier").value);
+            this.showTubeCpuMultiplier(val);
             this.changed.tubeCpuMultiplier = val;
         });
 
@@ -193,7 +201,11 @@ export class Config extends EventTarget {
     setTubeCpuMultiplier(value) {
         this.tubeCpuMultiplier = value;
         document.getElementById("tubeCpuMultiplier").value = value;
-        document.getElementById("tubeCpuMultiplierValue").textContent = value;
+        this.showTubeCpuMultiplier(value);
+    }
+
+    showTubeCpuMultiplier(value, model = this.model) {
+        document.getElementById("tubeCpuMultiplierValue").textContent = tubeCpuSpeedLabel(value, model);
     }
 
     setDropdownText(modelName) {

package/src/disc.js

@@ -672,11 +672,56 @@ export function loadAdf(disc, data, isDsd) {
     return disc;
 }
 
+/** Why a sector will not fit in an SSD or DSD image, or null if it will. */
+function sectorShortfall(sector, trackNum) {
+    if (sector.hasDataCrcError || sector.hasHeaderCrcError) return "with a CRC error";
+    // A header whose data mark never arrives leaves the sector with nothing to write.
+    if (!sector.sectorData) return "with no data";
+    if (sector.sectorNumber >= SsdFormat.sectorsPerTrack)
+        return `numbered past the ${SsdFormat.sectorsPerTrack} a track holds`;
+    if (sector.sectorData.length !== SsdFormat.sectorSize) return `not ${SsdFormat.sectorSize} bytes`;
+    if (trackNum >= SsdFormat.tracksPerDisc) return `past track ${SsdFormat.tracksPerDisc}`;
+    return null;
+}
+
+/**
+ * SSD and DSD images hold sector contents and nothing else, so anything a DFS sector could not
+ * have held is lost. Copy protection usually shows up as one of these.
+ *
+ * @returns {string[]} what `disc` holds that an SSD or DSD cannot, worst first
+ * @param {Disc} disc
+ */
+export function ssdOrDsdShortfalls(disc) {
+    const counts = new Map();
+    for (let trackNum = 0; trackNum < disc.tracksUsed; ++trackNum) {
+        for (const upper of disc.isDoubleSided ? [false, true] : [false]) {
+            for (const sector of disc.getTrack(upper, trackNum).findSectors()) {
+                const shortfall = sectorShortfall(sector, trackNum);
+                if (shortfall) counts.set(shortfall, (counts.get(shortfall) ?? 0) + 1);
+            }
+        }
+    }
+    return [...counts]
+        .sort(([, a], [, b]) => b - a)
+        .map(([shortfall, count]) => `${count} sector${count === 1 ? "" : "s"} ${shortfall}`);
+}
+
 /**
  * @returns {Uint8Array}
  * @param {Disc} disc
+ * @param {object} [options]
+ * @param {boolean} [options.force] save what fits instead of refusing a disc that will not fit
+ * @throws if the disc holds anything an SSD or DSD cannot, and `force` is not set
  */
-export function toSsdOrDsd(disc) {
+export function toSsdOrDsd(disc, { force = false } = {}) {
+    if (!force) {
+        const shortfalls = ssdOrDsdShortfalls(disc);
+        if (shortfalls.length)
+            throw new Error(
+                `This disc cannot be saved as SSD or DSD: it has ${shortfalls.join(", ")}. ` +
+                    `Save it as HFE to keep everything.`,
+            );
+    }
     const numSides = disc.isDoubleSided ? 2 : 1;
     const result = new Uint8Array(
         numSides * SsdFormat.tracksPerDisc * SsdFormat.sectorsPerTrack * SsdFormat.sectorSize,
@@ -686,11 +731,8 @@ export function toSsdOrDsd(disc) {
         for (let side = 0; side < numSides; ++side) {
             const trackObj = disc.getTrack(side === 1, trackNum);
             for (const sector of trackObj.findSectors()) {
+                if (sectorShortfall(sector, trackNum)) continue;
                 const sectorOffset = offset + sector.sectorNumber * SsdFormat.sectorSize;
-                if (sector.hasDataCrcError || sector.hasHeaderCrcError) {
-                    console.log(`Skipping sector ${sector.description} with bad CRC`);
-                    continue;
-                }
                 for (let x = 0; x < SsdFormat.sectorSize; ++x) result[sectorOffset + x] = sector.sectorData[x];
             }
             offset += SsdFormat.sectorsPerTrack * SsdFormat.sectorSize;

package/src/dom-utils.js

@@ -30,3 +30,19 @@ export function fadeOut(el, duration = 400) {
         if (el.style.opacity === "0") el.style.display = "none";
     }, duration);
 }
+
+// Safari fetches the blob a task or more after the click, so the URL must outlive it.
+// 40s matches FileSaver.js.
+const BlobUrlLifetimeMs = 40000;
+
+/** Save a blob to the user's downloads under the given file name. */
+export function downloadBlob(blob, fileName) {
+    const url = URL.createObjectURL(blob);
+    const a = document.createElement("a");
+    a.href = url;
+    a.download = fileName;
+    document.body.appendChild(a);
+    a.click();
+    a.remove();
+    setTimeout(() => URL.revokeObjectURL(url), BlobUrlLifetimeMs);
+}

package/src/fake6502.js

@@ -3,7 +3,7 @@
 
 import { FakeVideo } from "./video.js";
 import { FakeSoundChip } from "./soundchip.js";
-import { TEST_6502, TEST_65C02, TEST_65C12, TubeModel } from "./models.js";
+import { TEST_6502, TEST_65C02, TEST_65C12, tubeModelFor } from "./models.js";
 import { FakeDdNoise } from "./ddnoise.js";
 import { FakeRelayNoise } from "./relaynoise.js";
 import { Cpu6502, AtomCpu6502 } from "./6502.js";
@@ -30,7 +30,7 @@ export function fake6502(model, opts) {
         cmos: new Cmos(),
         cycleAccurate: opts.cycleAccurate,
         config: {
-            tube: opts.tube ? TubeModel : null,
+            tube: opts.tube ? tubeModelFor(model) : null,
             tubeCpuMultiplier: opts.tubeCpuMultiplier,
             cpuMultiplier: opts.cpuMultiplier,
             hasTeletextAdaptor: opts.hasTeletextAdaptor,

package/src/gamepads.js

@@ -39,16 +39,21 @@ export class GamePad {
          this.gamepadAxisMapping[3][-1] = BBC.COLON_STAR; // up
          this.gamepadAxisMapping[3][1] = BBC.SLASH;      // down
          */
+    /**
+     * Maps a gamepad button or stick direction to a BBC key.
+     * @param {string} gamepadKey - the gamepad control, eg `FIRE2`
+     * @param {string} bbcKey - the BBC key to press, eg `RETURN`
+     * @returns {?string} a description of the problem, or null if the mapping was applied
+     */
     remap(gamepadKey, bbcKey) {
         // convert "1" into "K1"
-        if ("0123456789".indexOf(bbcKey) > 0) {
+        if (bbcKey.length === 1 && bbcKey >= "0" && bbcKey <= "9") {
             bbcKey = "K" + bbcKey;
         }
 
         const mappedBbcKey = BBC[bbcKey];
         if (!mappedBbcKey) {
-            console.log("unknown BBC key: " + bbcKey);
-            return;
+            return `unknown BBC key "${bbcKey}".`;
         }
 
         switch (gamepadKey) {
@@ -152,8 +157,10 @@ export class GamePad {
                 this.gamepadMapping[6] = mappedBbcKey;
                 break;
             default:
-                console.log("unknown gamepad key: " + gamepadKey);
+                return `unknown gamepad control "${gamepadKey}".`;
         }
+
+        return null;
     }
 
     update(sysvia) {

package/src/main.js

@@ -7,7 +7,7 @@ import "./jsbeeb.css";
 import * as utils from "./utils.js";
 import { FakeVideo, Video } from "./video.js";
 import { Debugger } from "./web/debug.js";
-import { Cpu6502, AtomCpu6502, DefaultTubeCpuMultiplier } from "./6502.js";
+import { Cpu6502, AtomCpu6502 } from "./6502.js";
 import * as utils_atom from "./utils_atom.js";
 import { LoadSD } from "./mmc.js";
 import { Cmos } from "./cmos.js";
@@ -19,7 +19,7 @@ import { GoogleDriveLoader } from "./google-drive.js";
 import * as tokeniser from "./basic-tokenise.js";
 import * as canvasLib from "./canvas.js";
 import { Config } from "./config.js";
-import { TubeModel } from "./models.js";
+import { tubeModelFor } from "./models.js";
 import { initialise as electron } from "./app/electron.js";
 import { AudioHandler } from "./web/audio-handler.js";
 import { Econet } from "./econet.js";
@@ -44,6 +44,7 @@ import { isBemSnapshot, parseBemSnapshot } from "./bem-snapshot.js";
 import { isUefSnapshot, parseUefSnapshot } from "./uef-snapshot.js";
 import { RewindBuffer } from "./rewind.js";
 import { RewindUI } from "./rewind-ui.js";
+import { downloadBlob } from "./dom-utils.js";
 import {
     buildUrlFromParams,
     guessModelFromHostname,
@@ -51,7 +52,7 @@ import {
     parseMediaParams,
     parseQueryString,
     processAutobootParams,
-    processKeyboardParams,
+    processInputParams,
 } from "./url-params.js";
 
 let processor;
@@ -138,7 +139,7 @@ const paramTypes = {
     audiofilterfreq: ParamTypes.FLOAT,
     audiofilterq: ParamTypes.FLOAT,
     cpuMultiplier: ParamTypes.FLOAT,
-    tubeCpuMultiplier: ParamTypes.INT,
+    tubeCpuMultiplier: ParamTypes.FLOAT,
     microphoneChannel: ParamTypes.INT,
 
     // String parameters (these are the default but listed for clarity)
@@ -176,9 +177,6 @@ const { discImage: queryDiscImage, secondDiscImage: querySecondDisc, mmcImage }
 if (queryDiscImage) discImage = queryDiscImage;
 if (querySecondDisc) secondDiscImage = querySecondDisc;
 
-// Process keyboard mappings
-parsedQuery = processKeyboardParams(parsedQuery, BBC, keyCodes, utils.userKeymap, gamepad);
-
 // Handle specific query parameters
 if (Array.isArray(parsedQuery.rom)) {
     parsedQuery.rom.forEach((romPath) => {
@@ -284,7 +282,7 @@ config.mapLegacyModels(parsedQuery);
 
 config.setModel(parsedQuery.model || guessModelFromHostname(window.location.hostname));
 config.setKeyLayout(keyLayout);
-config.setTubeCpuMultiplier(parsedQuery.tubeCpuMultiplier || DefaultTubeCpuMultiplier);
+config.setTubeCpuMultiplier(parsedQuery.tubeCpuMultiplier || 1);
 config.setMicrophoneChannel(parsedQuery.microphoneChannel);
 config.setCheckboxes({
     coProcessor: !!parsedQuery.coProcessor,
@@ -299,13 +297,22 @@ config.setDisplayMode(displayMode);
 
 model = config.model;
 
+// Must come after we know the model, to validate names against those of the hardware.
+const keyMappingWarnings = processInputParams(
+    parsedQuery,
+    model.isAtom ? utils_atom.ATOM : BBC,
+    keyCodes,
+    utils.userKeymap,
+    gamepad,
+);
+
 // Depends on the config.setX calls above having applied the URL parameters.
 const emulationConfig = {
     keyLayout,
     cpuMultiplier,
     tubeCpuMultiplier: config.tubeCpuMultiplier,
     videoCyclesBatch: parsedQuery.videoCyclesBatch,
-    tube: config.coProcessor ? TubeModel : null,
+    tube: config.coProcessor ? tubeModelFor(config.model) : null,
     hasMusic5000: config.hasMusic5000,
     hasTeletextAdaptor: config.hasTeletextAdaptor,
     // ROM order determines sideways bank allocation, and the fittings' ROMs claim banks
@@ -345,7 +352,7 @@ sbBind(document.querySelector(".sidebar.bottom"), parsedQuery.sbBottom, function
 });
 
 if (cpuMultiplier !== 1) console.log(`CPU multiplier set to ${cpuMultiplier}`);
-const cpuSpeed = model.isAtom ? 1 * 1000 * 1000 : 2 * 1000 * 1000;
+const cpuSpeed = model.clockMhz * 1000 * 1000;
 const clocksPerSecond = (cpuMultiplier * cpuSpeed) | 0;
 const MaxCyclesPerFrame = clocksPerSecond / 10;
 
@@ -374,6 +381,10 @@ function showError(context, error) {
     errorDialogModal.show();
 }
 
+if (keyMappingWarnings.length) {
+    showError("applying the key mappings in the URL", keyMappingWarnings.join(" "));
+}
+
 function createCanvasForFilter(filterClass) {
     const newCanvas = tryGl ? canvasLib.bestCanvas(screenCanvas, filterClass) : new canvasLib.Canvas(screenCanvas);
 
@@ -471,18 +482,8 @@ function replaceOrAddExtension(name, newExt) {
  * @param {string} extension - The file extension to use
  */
 function downloadDriveData(data, name, extension) {
-    const a = document.createElement("a");
-    document.body.appendChild(a);
-    a.style = "display: none";
-
-    const fileName = replaceOrAddExtension(name, extension);
     const blob = new Blob([data], { type: "application/octet-stream" });
-    const url = window.URL.createObjectURL(blob);
-
-    a.href = url;
-    a.download = fileName;
-    a.click();
-    window.URL.revokeObjectURL(url);
+    downloadBlob(blob, replaceOrAddExtension(name, extension));
 }
 
 async function loadHTMLFile(file) {
@@ -667,6 +668,8 @@ processor = new CpuClass(model, {
     econet,
 });
 
+processor.teletextAdaptor?.addEventListener("showError", (e) => showError(e.detail.context, e.detail.error));
+
 // Create input sources
 const gamepadSource = new GamepadSource(emulationConfig.getGamepads);
 // Create MicrophoneInput but don't enable by default
@@ -681,18 +684,16 @@ const mouseJoystickSource = new MouseJoystickSource(screenCanvas);
 /**
  * Attach an RS-423 composite handler to the ACIA that combines the touchscreen
  * (which sends position data to the BBC) with the speech output (which speaks
- * text the BBC sends out).  Call this once after processor.initialise() and
- * again whenever speechOutput.enabled changes.
+ * text the BBC sends out).
  */
 function setupRs423Handler() {
-    const touchScreen = processor.touchScreen;
     processor.acia.setRs423Handler({
         onTransmit(val) {
-            touchScreen.onTransmit(val);
+            processor.touchScreen.onTransmit(val);
             speechOutput.onTransmit(val);
         },
         tryReceive(rts) {
-            return touchScreen.tryReceive(rts);
+            return processor.touchScreen.tryReceive(rts);
         },
     });
 }
@@ -1445,7 +1446,12 @@ document.querySelector("#google-drive form").addEventListener("submit", async fu
     let data;
     if (document.querySelector("#google-drive .create-from-existing").checked) {
         const discType = disc.guessDiscTypeFromName(name);
-        data = discType.saver(processor.fdc.drives[0].disc);
+        try {
+            data = discType.saver(processor.fdc.drives[0].disc);
+        } catch (e) {
+            loadingFinished(`Create failed: ${e.message}`);
+            return;
+        }
         name = replaceOrAddExtension(name, discType.extension);
         console.log(`Saving existing disc: ${name}`);
     } else {
@@ -1474,11 +1480,15 @@ document.querySelector("#google-drive form").addEventListener("submit", async fu
 
 document.getElementById("download-drive-link").addEventListener("click", function () {
     const disc = processor.fdc.drives[0].disc;
-    const data = toSsdOrDsd(disc);
-    const name = disc.name;
-    const extension = disc.isDoubleSided ? ".dsd" : ".ssd";
-
-    downloadDriveData(data, name, extension);
+    const save = (options) =>
+        downloadDriveData(toSsdOrDsd(disc, options), disc.name, disc.isDoubleSided ? ".dsd" : ".ssd");
+    try {
+        save();
+    } catch (e) {
+        areYouSure(`${e.message} Save anyway, losing what will not fit?`, "Save anyway", "Cancel", () =>
+            save({ force: true }),
+        );
+    }
 });
 
 document.getElementById("download-drive-hfe-link").addEventListener("click", function () {
@@ -1539,13 +1549,8 @@ document.getElementById("save-state").addEventListener("click", async function (
         const snapshot = createSnapshot(processor, model, Object.keys(media).length > 0 ? media : undefined);
         const json = snapshotToJSON(snapshot);
         const blob = await compressBlob(new Blob([json]));
-        const url = URL.createObjectURL(blob);
         const timestamp = new Date().toISOString().replace(/[:.]/g, "-");
-        const a = document.createElement("a");
-        a.href = url;
-        a.download = `jsbeeb-${model.name}-${timestamp}.json.gz`;
-        a.click();
-        URL.revokeObjectURL(url);
+        downloadBlob(blob, `jsbeeb-${model.name}-${timestamp}.json.gz`);
     } catch (e) {
         showError("saving state", e);
     }

package/src/models.js

@@ -19,10 +19,12 @@ const CpuModel = Object.freeze({
  * to any number of machines without one session's settings leaking into the next.
  */
 class Model {
-    constructor({ name, synonyms, os, cpuModel, isMaster, isAtom, swram, fdc, cmosOverride, banks } = {}) {
+    constructor({ name, synonyms, os, cpuModel, isMaster, isAtom, swram, fdc, cmosOverride, banks, clockMhz } = {}) {
+        if (!(clockMhz > 0)) throw new Error(`Model ${name} has no clock speed`);
         this.name = name;
         this.synonyms = synonyms;
         this.os = os;
+        this.clockMhz = clockMhz;
         this.banks = banks;
         this._cpuModel = cpuModel;
         this.isMaster = isMaster;
@@ -72,6 +74,7 @@ function atomModel({ name, synonyms, os, banks }) {
         os,
         cpuModel: CpuModel.MOS6502,
         isMaster: false,
+        clockMhz: 1,
         isAtom: true,
         swram: beebSwram,
         fdc: NoiseAwareIntelFdc,
@@ -124,6 +127,7 @@ export const allModels = [
         os: ["os.rom", "BASIC.ROM", "b/DFS-1.2.rom"],
         cpuModel: CpuModel.MOS6502,
         isMaster: false,
+        clockMhz: 2,
         swram: beebSwram,
         fdc: NoiseAwareIntelFdc,
     }),
@@ -133,6 +137,7 @@ export const allModels = [
         os: ["os.rom", "BASIC.ROM", "b/DFS-0.9.rom"],
         cpuModel: CpuModel.MOS6502,
         isMaster: false,
+        clockMhz: 2,
         swram: beebSwram,
         fdc: NoiseAwareIntelFdc,
     }),
@@ -142,6 +147,7 @@ export const allModels = [
         os: ["os.rom", "BASIC.ROM", "b1770/dfs1770.rom", "b1770/zADFS.ROM"],
         cpuModel: CpuModel.MOS6502,
         isMaster: false,
+        clockMhz: 2,
         swram: beebSwram,
         fdc: NoiseAwareWdFdc,
     }),
@@ -152,6 +158,7 @@ export const allModels = [
         os: ["os.rom", "BASIC.ROM", "b1770/zADFS.ROM", "b1770/dfs1770.rom"],
         cpuModel: CpuModel.MOS6502,
         isMaster: false,
+        clockMhz: 2,
         swram: beebSwram,
         fdc: NoiseAwareWdFdc,
     }),
@@ -161,6 +168,7 @@ export const allModels = [
         os: ["master/mos3.20"],
         cpuModel: CpuModel.CMOS65C12,
         isMaster: true,
+        clockMhz: 2,
         swram: masterSwram,
         fdc: NoiseAwareWdFdc,
         cmosOverride: pickDfs,
@@ -171,6 +179,7 @@ export const allModels = [
         os: ["master/mos3.20"],
         cpuModel: CpuModel.CMOS65C12,
         isMaster: true,
+        clockMhz: 2,
         swram: masterSwram,
         fdc: NoiseAwareWdFdc,
         cmosOverride: pickAdfs,
@@ -181,6 +190,7 @@ export const allModels = [
         os: ["master/mos3.20"],
         cpuModel: CpuModel.CMOS65C12,
         isMaster: true,
+        clockMhz: 2,
         swram: masterSwram,
         fdc: NoiseAwareWdFdc,
         cmosOverride: pickAnfs,
@@ -210,13 +220,24 @@ export const allModels = [
         synonyms: ["Atom-DOS"],
         os: ["atom/Atom_Kernel.rom", "atom/Atom_DOS.rom", "atom/Atom_FloatingPoint.rom", "atom/Atom_Basic.rom"],
     }),
-    // Although this can not be explicitly selected as a model, it is required by the configuration builder later
+    // Neither can be selected as a model: they are fitted to one, by the configuration builder later.
     new Model({
         name: "Tube65C02",
         synonyms: [],
         os: ["tube/6502Tube.rom"],
+        // TODO(#746): the external second processor was an NMOS 6502A.
         cpuModel: CpuModel.CMOS65C02,
         isMaster: false,
+        clockMhz: 3,
+    }),
+    new Model({
+        name: "Tube65C102",
+        synonyms: [],
+        os: ["tube/65C102Tube.rom"],
+        // TODO(#746): Acorn's 65C102 has no Rockwell bit instructions.
+        cpuModel: CpuModel.CMOS65C02,
+        isMaster: false,
+        clockMhz: 4,
     }),
 ];
 
@@ -236,6 +257,7 @@ export const TEST_6502 = new Model({
     name: "TEST",
     synonyms: ["TEST"],
     os: [],
+    clockMhz: 2,
     cpuModel: CpuModel.MOS6502,
     isMaster: false,
     swram: beebSwram,
@@ -246,6 +268,7 @@ export const TEST_65C02 = new Model({
     name: "TEST",
     synonyms: ["TEST"],
     os: [],
+    clockMhz: 2,
     cpuModel: CpuModel.CMOS65C02,
     isMaster: false,
     swram: masterSwram,
@@ -256,6 +279,7 @@ export const TEST_65C12 = new Model({
     name: "TEST",
     synonyms: ["TEST"],
     os: [],
+    clockMhz: 2,
     cpuModel: CpuModel.CMOS65C12,
     isMaster: false,
     swram: masterSwram,
@@ -265,6 +289,7 @@ TEST_65C12.isTest = true;
 
 export const basicOnly = new Model({
     name: "Basic only",
+    clockMhz: 2,
     synonyms: ["Basic only"],
     os: ["master/mos3.20"],
     cpuModel: CpuModel.CMOS65C12,
@@ -274,11 +299,18 @@ export const basicOnly = new Model({
 });
 
 /**
- * The only second processor jsbeeb emulates. Machine-building code passes this as the
- * emulation config's `tube`, so that 6502.js needn't import this module and close an
- * import cycle via the FDC modules.
+ * The second processors jsbeeb emulates: the external 3MHz box, and the Master Turbo's
+ * internal 4MHz board. Machine-building code passes one of these as the emulation config's
+ * `tube`, so that 6502.js needn't import this module and close an import cycle via the FDC
+ * modules.
  */
 export const TubeModel = findModel("Tube65C02");
+export const TurboTubeModel = findModel("Tube65C102");
+
+/** @returns {Model} the second processor sold for this machine: the Turbo board for a Master. */
+export function tubeModelFor(model) {
+    return model.isMaster ? TurboTubeModel : TubeModel;
+}
 
 // After the isTest assignments above, so those still apply.
 for (const model of [...allModels, TEST_6502, TEST_65C02, TEST_65C12, basicOnly]) {

package/src/serial.js

@@ -20,6 +20,7 @@ export class Serial {
         this.transmitRate = val & 0x07;
         this.receiveRate = (val >>> 3) & 0x07;
         this.acia.setSerialReceive(table[this.receiveRate]);
+        this.acia.setSerialTransmit(table[this.transmitRate]);
         this.acia.setMotor(!!(val & 0x80));
         this.acia.selectRs423(!!(val & 0x40));
     }

package/src/snapshot-helpers.js

@@ -25,7 +25,7 @@ export const DefaultAcia = {
     tapeDcdLineLevel: false,
     hadDcdHigh: false,
     serialReceiveRate: 19200,
-    serialReceiveCyclesPerByte: 0,
+    serialTransmitRate: 19200,
     txCompleteTaskOffset: null,
     runTapeTaskOffset: null,
     runRs423TaskOffset: null,

package/src/teletext_adaptor.js

@@ -34,9 +34,20 @@ Status register:
 
 */
 
-export class TeletextAdaptor {
+/**
+ * Emulates the Acorn teletext adaptor. Dispatches a `showError` CustomEvent, carrying
+ * `context` and `error` in its detail, when a channel's stream cannot be loaded.
+ */
+export class TeletextAdaptor extends EventTarget {
     constructor(cpu) {
+        super();
         this.cpu = cpu;
+        // Not cleared by a reset, so a fetch still in flight across one is recognised as stale.
+        this.streamRequest = 0;
+        this.clearState();
+    }
+
+    clearState() {
         this.teletextStatus = 0x0f; /* low nibble comes from LK4-7 and mystery links which are left floating */
         this.teletextInts = false;
         this.teletextEnable = false;
@@ -45,26 +56,40 @@ export class TeletextAdaptor {
         this.totalFrames = 0;
         this.rowPtr = 0x00;
         this.colPtr = 0x00;
-        this.frameBuffer = new Array(16).fill(0).map(() => new Array(64).fill(0));
         this.streamData = null;
         this.pollCount = 0;
+        this.frameBuffer = new Array(16).fill(0).map(() => new Array(64).fill(0));
+        // Only a register access clears our IRQ, so an interrupt latched before the reset would hang the machine.
+        this.cpu.interrupt &= ~(1 << TELETEXT_IRQ);
     }
 
     reset(hard) {
-        if (hard) {
-            console.log("Teletext adaptor: initialisation");
-            this.loadChannelStream(this.channel);
-        }
+        if (!hard) return;
+        this.clearState();
+        this.loadChannelStream(this.channel);
     }
 
-    loadChannelStream(channel) {
+    async loadChannelStream(channel) {
         console.log("Teletext adaptor: switching to channel " + channel);
-        const teletextRef = this;
-        utils.loadData("teletext/txt" + channel + ".dat").then(function (data) {
-            teletextRef.streamData = data;
-            teletextRef.totalFrames = data.length / TELETEXT_FRAME_SIZE;
-            teletextRef.currentFrame = 0;
-        });
+        const request = ++this.streamRequest;
+        let data;
+        try {
+            data = await utils.loadData(`teletext/txt${channel}.dat`);
+        } catch (error) {
+            if (request !== this.streamRequest) return;
+            console.error(`Teletext adaptor: failed to load channel ${channel}`, error);
+            this.dispatchEvent(
+                new CustomEvent("showError", {
+                    detail: { context: `loading teletext channel ${channel}`, error },
+                }),
+            );
+            return;
+        }
+        // Fetches can resolve out of order; only the newest request may apply its data.
+        if (request !== this.streamRequest) return;
+        this.streamData = data;
+        this.totalFrames = Math.floor(data.length / TELETEXT_FRAME_SIZE);
+        this.currentFrame = 0;
     }
 
     read(addr) {

package/src/url-params.js

@@ -161,52 +161,56 @@ export function buildUrlFromParams(baseUrl, parsedQuery, paramTypes = {}) {
 }
 
 /**
- * Process keyboard mapping parameters from query string
+ * Process keyboard and gamepad mapping parameters from query string
  * @param {Object} parsedQuery - The parsed query parameters
- * @param {Object} BBC - BBC key constants
+ * @param {Object} machineKeys - Emulated machine's key constants (`BBC`, or `ATOM` for the Atom)
  * @param {Object} keyCodes - Key code constants
  * @param {Array} userKeymap - Array to store user key mappings
  * @param {Object} gamepad - Gamepad object for handling mapping
- * @returns {Object} Updated query parameters
+ * @returns {string[]} descriptions of any mappings that were skipped, for showing to the user
  */
-export function processKeyboardParams(parsedQuery, BBC, keyCodes, userKeymap, gamepad) {
+export function processInputParams(parsedQuery, machineKeys, keyCodes, userKeymap, gamepad) {
+    const warnings = [];
+
     Object.entries(parsedQuery).forEach(([key, val]) => {
         if (!val) return;
 
-        // eg KEY.CAPSLOCK=CTRL
+        // `KEY.<host key>=<machine key>`, eg `KEY.CAPSLOCK=CTRL`. Host names come from
+        // `keyCodes`, so the BBC's RETURN is ENTER here; both lists are in the README.
         if (key.toUpperCase().indexOf("KEY.") === 0) {
-            const bbcKey = val.toUpperCase();
+            const machineKey = val.toUpperCase();
+            const nativeKey = key.substring(4).toUpperCase(); // remove KEY.
 
-            if (BBC[bbcKey]) {
-                const nativeKey = key.substring(4).toUpperCase(); // remove KEY.
-                if (keyCodes[nativeKey]) {
-                    console.log("mapping " + nativeKey + " to " + bbcKey);
-                    userKeymap.push({ native: nativeKey, bbc: bbcKey });
-                } else {
-                    console.log("unknown key: " + nativeKey);
-                }
+            if (!machineKeys[machineKey]) {
+                warnings.push(`${key}=${val}: "${machineKey}" is not a key on the emulated machine.`);
+            } else if (!keyCodes[nativeKey]) {
+                warnings.push(`${key}=${val}: "${nativeKey}" is not a key on your keyboard.`);
             } else {
-                console.log("unknown BBC key: " + val);
+                console.log("mapping " + nativeKey + " to " + machineKey);
+                userKeymap.push({ native: nativeKey, key: machineKey });
             }
         } else if (key.indexOf("GP.") === 0) {
             // gamepad mapping
             // eg ?GP.FIRE2=RETURN
             const gamepadKey = key.substring(3).toUpperCase(); // remove GP. prefix
-            gamepad.remap(gamepadKey, val.toUpperCase());
+            const problem = gamepad.remap(gamepadKey, val.toUpperCase());
+            if (problem) warnings.push(`${key}=${val}: ${problem}`);
         } else {
             switch (key) {
                 case "LEFT":
                 case "RIGHT":
                 case "UP":
                 case "DOWN":
-                case "FIRE":
-                    gamepad.remap(key, val.toUpperCase());
+                case "FIRE": {
+                    const problem = gamepad.remap(key, val.toUpperCase());
+                    if (problem) warnings.push(`${key}=${val}: ${problem}`);
                     break;
+                }
             }
         }
     });
 
-    return parsedQuery;
+    return warnings;
 }
 
 /**

package/src/utils.js

@@ -657,6 +657,12 @@ export function getKeyMap(keyLayout) {
         keys2[shiftDown][s] = colRow;
     }
 
+    // Overriding a default is the point here, so unlike `map` this doesn't warn about the clash.
+    function remap(s, colRow) {
+        keys2[true][s] = colRow;
+        keys2[false][s] = colRow;
+    }
+
     // shiftDown undefined -> map both
     function map(s, colRow, shiftDown) {
         if ((!s && s !== 0) || !colRow) {
@@ -935,11 +941,10 @@ export function getKeyMap(keyLayout) {
     // eg Master Dunjunz needs # Del 3 , * Enter
     // https://web.archive.org/web/20080305042238/http://bbc.nvg.org/doc/games/Dunjunz-docs.txt
 
-    // user keymapping
-    // do last (to override defaults)
-    while (userKeymap.length > 0) {
-        const mapping = userKeymap.pop();
-        map(keyCodes[mapping.native], BBC[mapping.bbc]);
+    // `KEY.` URL parameters, applied last so they win. Not consumed: this map is rebuilt on
+    // layout and model changes, and the user's mapping has to survive that.
+    for (const mapping of userKeymap) {
+        remap(keyCodes[mapping.native], BBC[mapping.key]);
     }
 
     return keys2;

package/src/utils_atom.js

@@ -249,6 +249,12 @@ export function getKeyMapAtom(keyLayout) {
         keys2[shiftDown][s] = colRow;
     }
 
+    // Overriding a default is the point here, so unlike `map` this doesn't warn about the clash.
+    function remap(s, colRow) {
+        keys2[true][s] = colRow;
+        keys2[false][s] = colRow;
+    }
+
     // shiftDown undefined -> map both
     function map(s, colRow, shiftDown) {
         if ((!s && s !== 0) || !colRow) {
@@ -477,11 +483,9 @@ export function getKeyMapAtom(keyLayout) {
         // Z - M normal
     }
 
-    // user keymapping
-    // do last (to override defaults)
-    while (userKeymap.length > 0) {
-        const mapping = userKeymap.pop();
-        map(keyCodes[mapping.native], ATOM[mapping.atom]);
+    // `KEY.` URL parameters, applied last so they win. See the equivalent in `getKeyMap`.
+    for (const mapping of userKeymap) {
+        remap(keyCodes[mapping.native], ATOM[mapping.key]);
     }
 
     return keys2;