jsbeeb 1.13.1 → 1.15.0

package/src/bem-snapshot.js

@@ -255,7 +255,145 @@ function readString(data, pos) {
     return str;
 }
 
-function parseBemV3(buffer) {
+// b-em writes the tube ULA as a raw struct dump. Version 2 is all single-byte fields, so it has
+// no padding and can be read directly; version 1 used native ints and is not supported here.
+const BemTubeUlaVersion = 2;
+const BemTubeUlaOffsets = {
+    ph1: 0,
+    ph2: 24,
+    ph3: 25,
+    ph4: 27,
+    hp1: 29, // phl (byte 28) is a latch jsbeeb does not model
+    hp2: 30,
+    hp3: 31,
+    hp4: 33,
+    hstat: 35, // hpl (byte 34) likewise unmodelled
+    pstat: 39,
+    r1stat: 43,
+    ph1head: 45, // ph1tail (byte 44) matters only to b-em, which appends there
+    ph1count: 46,
+    ph3pos: 47,
+    hp3pos: 48,
+};
+const BemTubeUlaSize = 49;
+const BemPh1Size = 24;
+// 9 bytes of registers, then RAM, then ROM.
+const BemTubeRegisterBytes = 9;
+const BemTubeRamSize = 65536;
+// b-em's other co-processors are different CPUs, and its "6502 Turbo" has 16MB of RAM.
+const BemSupportedTubes = ["6502 Internal", "6502 External"];
+
+/**
+ * Convert b-em's tube sections into jsbeeb tube state.
+ * @param {object} sections - parsed v3 sections
+ * @param {string|null} tubeName - co-processor name from the model section
+ * @returns {Promise<object|null>} jsbeeb tube state, or null if no usable co-processor
+ */
+async function parseBemTube(sections, tubeName) {
+    // b-em names the model's co-processor even when it failed to start one, so naming a tube but
+    // carrying no state for it is valid. Carrying only one of the two sections is not.
+    if (!sections["T"] && !sections["P"]) return null;
+    if (!sections["T"] || !sections["P"]) {
+        throw new Error("Truncated b-em snapshot: it holds only one of the two co-processor sections");
+    }
+    // b-em only writes these sections for a co-processor it started, which it always names.
+    if (!tubeName) {
+        throw new Error("Corrupt b-em snapshot: it holds co-processor state but names no co-processor");
+    }
+    if (!BemSupportedTubes.includes(tubeName)) {
+        throw new Error(
+            `Unsupported b-em co-processor "${tubeName}": jsbeeb only emulates the 64K 65C02 second processor`,
+        );
+    }
+
+    const ulaSection = sections["T"].data;
+    if (ulaSection[0] !== BemTubeUlaVersion) {
+        throw new Error(`Unsupported b-em tube ULA state version ${ulaSection[0]}`);
+    }
+    if (ulaSection.length < 2 + BemTubeUlaSize) {
+        throw new Error(
+            `Truncated b-em tube ULA state: expected ${2 + BemTubeUlaSize} bytes, got ${ulaSection.length}`,
+        );
+    }
+    const romPaged = !!ulaSection[1];
+    const ula = ulaSection.slice(2, 2 + BemTubeUlaSize);
+    const at = (field) => ula[BemTubeUlaOffsets[field]];
+
+    // b-em keeps the R1 FIFO as a circular buffer; jsbeeb shifts its contents down on read, so
+    // the bytes have to be linearised into the order jsbeeb expects to read them.
+    const ph1Count = at("ph1count");
+    const ph1Head = at("ph1head");
+    // Out-of-range counts would restore a FIFO jsbeeb's own reads could never have produced.
+    if (ph1Count > BemPh1Size || ph1Head >= BemPh1Size || at("ph3pos") > 2 || at("hp3pos") > 2) {
+        throw new Error("Corrupt b-em tube ULA state: FIFO counts out of range");
+    }
+    const ph1 = new Uint8Array(BemPh1Size);
+    for (let i = 0; i < ph1Count; i++) {
+        ph1[i] = ula[BemTubeUlaOffsets.ph1 + ((ph1Head + i) % BemPh1Size)];
+    }
+
+    // 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 romBytes = parasite.length - BemTubeRegisterBytes - BemTubeRamSize;
+    if (romBytes < 0 || romBytes > BemTubeRamSize) {
+        throw new Error(
+            `Unsupported b-em co-processor: expected ${BemTubeRamSize} bytes of parasite RAM, ` +
+                `but the state section holds ${parasite.length - BemTubeRegisterBytes}`,
+        );
+    }
+
+    return {
+        a: parasite[2],
+        x: parasite[3],
+        y: parasite[4],
+        p: parasite[5] | 0x30,
+        s: parasite[6],
+        pc: parasite[7] | (parasite[8] << 8),
+        // b-em's oldnmi is the NMI level as of the parasite's last instruction, so it may lag the
+        // line its ULA state implies. b-em's skipint has no jsbeeb equivalent and is dropped.
+        nmiLevel: !!parasite[1],
+        nmiEdge: false,
+        takeInt: false,
+        cycles: 0,
+        romPaged,
+        memory: parasite.slice(BemTubeRegisterBytes, BemTubeRegisterBytes + BemTubeRamSize),
+        // The parasite ROM is loaded from file at boot, so b-em's copy is not needed.
+        ula: {
+            internalStatusRegister: at("r1stat"),
+            hostStatus: ula.slice(BemTubeUlaOffsets.hstat, BemTubeUlaOffsets.hstat + 4),
+            parasiteStatus: ula.slice(BemTubeUlaOffsets.pstat, BemTubeUlaOffsets.pstat + 4),
+            parasiteToHostData: [
+                ph1,
+                Uint8Array.of(at("ph2")),
+                ula.slice(BemTubeUlaOffsets.ph3, BemTubeUlaOffsets.ph3 + 2),
+                Uint8Array.of(at("ph4")),
+            ],
+            hostToParasiteData: [
+                Uint8Array.of(at("hp1")),
+                Uint8Array.of(at("hp2")),
+                ula.slice(BemTubeUlaOffsets.hp3, BemTubeUlaOffsets.hp3 + 2),
+                Uint8Array.of(at("hp4")),
+            ],
+            parasiteToHostFifoByteCount1: ph1Count,
+            parasiteToHostFifoByteCount3: at("ph3pos"),
+            hostToParasiteFifoByteCount3: at("hp3pos"),
+        },
+    };
+}
+
+/**
+ * Read the co-processor name from b-em's model section, if one was fitted.
+ * @returns {string|null}
+ */
+function readBemTubeName(data, pos) {
+    for (let i = 0; i < 4; i++) readString(data, pos); // os, cmos, rom setup, fdc names
+    pos.offset += 6; // model flag bytes
+    const fitted = data[pos.offset++];
+    return fitted ? readString(data, pos) : null;
+}
+
+async function parseBemV3(buffer) {
     const bytes = new Uint8Array(buffer);
     let offset = 8; // Skip "BEMSNAP3" signature
 
@@ -281,11 +419,13 @@ function parseBemV3(buffer) {
     // Parse model section to determine jsbeeb model name.
     // Use jsbeeb synonyms (from models.js) so findModel() resolves them.
     let modelName = "B";
+    let tubeName = null;
     if (sections["m"]) {
         const pos = { offset: 0 };
         const data = sections["m"].data;
         readVar(data, pos); // curmodel index (skip)
         const name = readString(data, pos);
+        tubeName = readBemTubeName(data, pos);
         if (name.includes("Master")) {
             if (name.includes("ADFS")) modelName = "MasterADFS";
             else if (name.includes("ANFS")) modelName = "MasterANFS";
@@ -311,23 +451,21 @@ function parseBemV3(buffer) {
     if (memSection) {
         // Memory is zlib-compressed; decompression is async.
         // Decompressed layout: 2 bytes (fe30, fe34) + 64KB RAM + 256KB ROM
-        return decompress(memSection.data, "deflate").then((memData) => {
-            cpuState.fe30 = memData[0];
-            cpuState.fe34 = memData[1];
-            const ramStart = 2;
-            const ramSize = 64 * 1024;
-            ram.set(memData.slice(ramStart, ramStart + ramSize));
-            const romStart = ramStart + ramSize;
-            if (memData.length > romStart) {
-                roms = memData.slice(romStart, romStart + 262144);
-            }
-            return finishV3Parse(modelName, cpuState, ram, roms, sections);
-        });
+        const memData = await decompress(memSection.data, "deflate");
+        cpuState.fe30 = memData[0];
+        cpuState.fe34 = memData[1];
+        const ramStart = 2;
+        const ramSize = 64 * 1024;
+        ram.set(memData.slice(ramStart, ramStart + ramSize));
+        const romStart = ramStart + ramSize;
+        if (memData.length > romStart) {
+            roms = memData.slice(romStart, romStart + 262144);
+        }
     }
-    return finishV3Parse(modelName, cpuState, ram, roms, sections);
+    return finishV3Parse(modelName, cpuState, ram, roms, sections, await parseBemTube(sections, tubeName));
 }
 
-function finishV3Parse(modelName, cpuState, ram, roms, sections) {
+function finishV3Parse(modelName, cpuState, ram, roms, sections, tube) {
     // Parse system VIA
     let sysvia = convertViaState(
         {
@@ -466,5 +604,6 @@ function finishV3Parse(modelName, cpuState, ram, roms, sections) {
         uservia,
         buildVideoState(ulaControl, ulaPalette, crtcRegs, nulaCollook, crtcCounters),
         soundChip,
+        tube,
     );
 }

package/src/config.js

@@ -1,31 +1,93 @@
 "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.
+ *
+ * @param {{model: object, hasEconet: boolean, hasMusic5000: boolean, hasTeletextAdaptor: boolean}} settings
+ * @returns {string[]}
+ */
+export function fittedRoms({ model, hasEconet, hasMusic5000, hasTeletextAdaptor }) {
+    return [
+        ...(hasEconet && model.isMaster ? ["master/anfs-4.25.rom"] : []),
+        ...(hasMusic5000 ? ["ample.rom"] : []),
+        ...(hasTeletextAdaptor ? ["ats-3.0.rom"] : []),
+    ];
+}
+
+/** The settings the dialog presents as checkboxes. `enables` names a control only usable while ticked. */
+export const CheckboxSettings = [
+    { id: "65c02", field: "coProcessor", restartRequired: true, enables: "tubeCpuMultiplier" },
+    { id: "hasTeletextAdaptor", field: "hasTeletextAdaptor", restartRequired: true },
+    { id: "hasEconet", field: "hasEconet", restartRequired: true },
+    { id: "hasMusic5000", field: "hasMusic5000", restartRequired: true },
+    { id: "mouseJoystickEnabled", field: "mouseJoystickEnabled" },
+    { id: "speechOutput", field: "speechOutput" },
+];
+
+/** The model is not a checkbox, but changing it needs a restart just the same. */
+const RestartRequiredFields = [
+    "model",
+    ...CheckboxSettings.filter((setting) => setting.restartRequired).map((setting) => setting.field),
+];
+
+/** @returns {boolean} whether any of the changed settings only take effect on a freshly built machine. */
+export function needsRestart(changed) {
+    return RestartRequiredFields.some((field) => field in changed);
+}
+
+/** @returns {boolean} whether the saved settings differ from those the running machine was built with. */
+export function restartPending(settings, running) {
+    return RestartRequiredFields.some((field) => settings[field] !== running[field]);
+}
+
 export class Config extends EventTarget {
-    constructor(onChange, onClose) {
+    /**
+     * @param {function(object)} onChange called as soon as a setting the emulator can follow live changes
+     * @param {function(object)} onClose called with the settings to apply and persist
+     * @param {function()} onRestartRequired called after the settings have been saved, when some of them
+     *     will only take effect once the machine is rebuilt
+     */
+    constructor(onChange, onClose, onRestartRequired) {
         super();
         this.onChange = onChange;
         this.onClose = onClose;
+        this.onRestartRequired = onRestartRequired;
         this.changed = {};
         this.model = null;
-        this.coProcessor = null;
+        for (const { field } of CheckboxSettings) this[field] = false;
+        this.runningSettings = null;
         const configuration = document.getElementById("configuration");
         configuration.addEventListener("show.bs.modal", () => {
             this.changed = {};
+            // The startup settings are pushed in after construction, so what the running machine was
+            // built with is only knowable from the first time the dialog is opened.
+            if (!this.runningSettings) this.runningSettings = this.proposedSettings();
             this.setDropdownText(this.model.name);
-            this.set65c02(this.model.tube);
             this.setTubeCpuMultiplier(this.tubeCpuMultiplier);
-            this.setTeletext(this.model.hasTeletextAdaptor);
-            this.setMusic5000(this.model.hasMusic5000);
-            this.setEconet(this.model.hasEconet);
+            this.setCheckboxes(this);
+            this.showRestartPending();
         });
 
         configuration.addEventListener("hide.bs.modal", () => {
-            this.onClose(this.changed);
-            if (Object.keys(this.changed).length > 0) {
-                this.dispatchEvent(new CustomEvent("settings-changed", { detail: this.changed }));
-            }
+            const changed = this.changed;
+            // Not setModel: that also renames the machine in the title bar, which has not changed yet.
+            if (changed.model !== undefined) this.model = findModel(changed.model);
+            this.setCheckboxes(changed);
+            this.onClose(changed);
+            if (Object.keys(changed).length === 0) return;
+            this.dispatchEvent(new CustomEvent("settings-changed", { detail: changed }));
+            // changed records which controls were touched, so a value in it can be what is already running.
+            if (needsRestart(changed) && restartPending(this.proposedSettings(), this.runningSettings))
+                this.onRestartRequired();
         });
 
         const modelMenu = document.querySelector(".model-menu");
@@ -45,31 +107,25 @@ 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();
         });
 
-        document.getElementById("65c02").addEventListener("click", () => {
-            this.changed.coProcessor = document.getElementById("65c02").checked;
-            document.getElementById("tubeCpuMultiplier").disabled = !document.getElementById("65c02").checked;
-        });
+        for (const { id, field, enables } of CheckboxSettings) {
+            document.getElementById(id).addEventListener("click", () => {
+                const checked = document.getElementById(id).checked;
+                this.changed[field] = checked;
+                if (enables) document.getElementById(enables).disabled = !checked;
+                this.showRestartPending();
+            });
+        }
 
         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;
         });
 
-        document.getElementById("hasTeletextAdaptor").addEventListener("click", () => {
-            this.changed.hasTeletextAdaptor = document.getElementById("hasTeletextAdaptor").checked;
-        });
-
-        document.getElementById("hasEconet").addEventListener("click", () => {
-            this.changed.hasEconet = document.getElementById("hasEconet").checked;
-        });
-
-        document.getElementById("hasMusic5000").addEventListener("click", () => {
-            this.changed.hasMusic5000 = document.getElementById("hasMusic5000").checked;
-        });
-
         for (const link of document.querySelectorAll(".keyboard-menu a")) {
             link.addEventListener("click", (e) => {
                 const keyLayout = e.target.dataset.target;
@@ -87,14 +143,6 @@ export class Config extends EventTarget {
             });
         }
 
-        document.getElementById("mouseJoystickEnabled").addEventListener("click", () => {
-            this.changed.mouseJoystickEnabled = document.getElementById("mouseJoystickEnabled").checked;
-        });
-
-        document.getElementById("speechOutput").addEventListener("click", () => {
-            this.changed.speechOutput = document.getElementById("speechOutput").checked;
-        });
-
         for (const option of document.querySelectorAll(".display-mode-option")) {
             option.addEventListener("click", (e) => {
                 const mode = e.target.dataset.mode;
@@ -105,17 +153,34 @@ export class Config extends EventTarget {
         }
     }
 
-    setMicrophoneChannel(channel) {
-        const text = channel !== undefined ? `Channel ${channel}` : "Disabled";
-        for (const el of document.querySelectorAll(".mic-channel-text")) el.textContent = text;
+    /**
+     * The restart-required settings as they would be saved if the dialog were closed now, in the form the
+     * menu and the URL use: the model by synonym rather than resolved, the fittings as booleans.
+     */
+    proposedSettings() {
+        const saved = (field) => (field === "model" ? this.model.synonyms[0] : this[field]);
+        return Object.fromEntries(RestartRequiredFields.map((field) => [field, this.changed[field] ?? saved(field)]));
     }
 
-    setMouseJoystickEnabled(enabled) {
-        document.getElementById("mouseJoystickEnabled").checked = !!enabled;
+    showRestartPending() {
+        const pending = restartPending(this.proposedSettings(), this.runningSettings);
+        document.getElementById("restart-pending").classList.toggle("d-none", !pending);
     }
 
-    setSpeechOutput(enabled) {
-        document.getElementById("speechOutput").checked = !!enabled;
+    /** Ticks the boxes named in `values` and adopts them, leaving any the object does not mention alone. */
+    setCheckboxes(values) {
+        for (const { id, field, enables } of CheckboxSettings) {
+            if (values[field] === undefined) continue;
+            const checked = !!values[field];
+            document.getElementById(id).checked = checked;
+            this[field] = checked;
+            if (enables) document.getElementById(enables).disabled = !checked;
+        }
+    }
+
+    setMicrophoneChannel(channel) {
+        const text = channel !== undefined ? `Channel ${channel}` : "Disabled";
+        for (const el of document.querySelectorAll(".mic-channel-text")) el.textContent = text;
     }
 
     setDisplayMode(mode) {
@@ -133,41 +198,14 @@ export class Config extends EventTarget {
         for (const el of document.querySelectorAll(".keyboard-layout")) el.textContent = text;
     }
 
-    set65c02(enabled) {
-        enabled = !!enabled;
-        document.getElementById("65c02").checked = enabled;
-        this.model.tube = enabled ? findModel("Tube65c02") : null;
-        document.getElementById("tubeCpuMultiplier").disabled = !enabled;
-    }
-
     setTubeCpuMultiplier(value) {
         this.tubeCpuMultiplier = value;
         document.getElementById("tubeCpuMultiplier").value = value;
-        document.getElementById("tubeCpuMultiplierValue").textContent = value;
-    }
-
-    setEconet(enabled) {
-        enabled = !!enabled;
-        document.getElementById("hasEconet").checked = enabled;
-        this.model.hasEconet = enabled;
-
-        if (enabled && this.model.isMaster) {
-            this.addRemoveROM("master/anfs-4.25.rom", true);
-        }
+        this.showTubeCpuMultiplier(value);
     }
 
-    setMusic5000(enabled) {
-        enabled = !!enabled;
-        document.getElementById("hasMusic5000").checked = enabled;
-        this.model.hasMusic5000 = enabled;
-        this.addRemoveROM("ample.rom", enabled);
-    }
-
-    setTeletext(enabled) {
-        enabled = !!enabled;
-        document.getElementById("hasTeletextAdaptor").checked = enabled;
-        this.model.hasTeletextAdaptor = enabled;
-        this.addRemoveROM("ats-3.0.rom", enabled);
+    showTubeCpuMultiplier(value, model = this.model) {
+        document.getElementById("tubeCpuMultiplierValue").textContent = tubeCpuSpeedLabel(value, model);
     }
 
     setDropdownText(modelName) {
@@ -175,15 +213,8 @@ export class Config extends EventTarget {
         if (el) el.textContent = modelName;
     }
 
-    addRemoveROM(romName, required) {
-        if (required && !this.model.os.includes(romName)) {
-            this.model.os.push(romName);
-        } else {
-            let pos = this.model.os.indexOf(romName);
-            if (pos !== -1) {
-                this.model.os.splice(pos, 1);
-            }
-        }
+    get extraRoms() {
+        return fittedRoms(this);
     }
 
     mapLegacyModels(parsedQuery) {

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 { findModel, TEST_6502, TEST_65C02, TEST_65C12 } 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";
@@ -19,7 +19,6 @@ const dbgr = {
 export function fake6502(model, opts) {
     opts = opts || {};
     model = model || TEST_6502;
-    if (opts.tube) model.tube = findModel("Tube65c02");
     const CpuClass = model.isAtom ? AtomCpu6502 : Cpu6502;
     return new CpuClass(model, {
         dbgr,
@@ -30,6 +29,12 @@ export function fake6502(model, opts) {
         music5000: new FakeMusic5000(),
         cmos: new Cmos(),
         cycleAccurate: opts.cycleAccurate,
+        config: {
+            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/keyboard.js

@@ -341,8 +341,9 @@ export class Keyboard extends EventTarget {
         if (this.isPasting) this.cancelPaste();
 
         this.keyInterface.disableKeyboard();
-        this._pasteClocksPerMs =
-            Math.floor(this.processor.cpuMultiplier * this.processor.peripheralCyclesPerSecond) / 1000;
+        // The paste task lives on the processor's scheduler, which is polled with peripheral
+        // cycles, so paste delays stay in real time whatever the CPU multiplier is.
+        this._pasteClocksPerMs = this.processor.peripheralCyclesPerSecond / 1000;
 
         if (checkCapsAndShiftLocks) {
             let toggleKey = null;

package/src/machine-session.js

@@ -30,6 +30,9 @@ export class MachineSession {
      * @param {string} modelName - e.g. "B-DFS1.2", "Master"
      * @param {Object} [opts]
      * @param {string} [opts.discImage] - path to an .ssd or .dsd disc image to load on boot
+     * @param {boolean} [opts.tube] - attach a 65C02 second processor (Tube co-processor)
+     * @param {number} [opts.cpuMultiplier] - run the CPU this many times faster than the peripherals
+     * @param {boolean} [opts.hasTeletextAdaptor] - fit the Acorn teletext adaptor
      */
     constructor(modelName = "B-DFS1.2", opts = {}) {
         this.modelName = modelName;
@@ -65,8 +68,14 @@ export class MachineSession {
         // toneGenerator); FakeSoundChip provides compatible no-op stubs for headless mode.
         this._soundChip = modelObj.isAtom ? new FakeSoundChip() : new InstrumentedSoundChip();
 
-        // TestMachine forwards opts.video and opts.soundChip to fake6502
-        this._machine = new TestMachine(modelName, { video: this._video, soundChip: this._soundChip });
+        // TestMachine forwards these to fake6502
+        this._machine = new TestMachine(modelName, {
+            video: this._video,
+            soundChip: this._soundChip,
+            tube: opts.tube,
+            cpuMultiplier: opts.cpuMultiplier,
+            hasTeletextAdaptor: opts.hasTeletextAdaptor,
+        });
 
         // Accumulated VDU text output — drained by callers
         this._pendingOutput = [];