jsbeeb 1.3.3 → 1.5.0

package/package.json

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

package/src/6502.js

@@ -101,12 +101,12 @@ class Flags {
 }
 
 class Base6502 {
-    constructor(model) {
+    constructor(model, { cycleAccurate = true } = {}) {
         this.model = model;
         this.a = this.x = this.y = this.s = 0;
         this.p = new Flags();
         this.pc = 0;
-        this.opcodes = model.opcodesFactory(this);
+        this.opcodes = model.opcodesFactory(this, { cycleAccurate });
         this.disassembler = this.opcodes.disassembler;
         this.forceTracing = false;
         this.runner = this.opcodes.runInstruction;
@@ -405,9 +405,10 @@ class Base6502 {
 
 class Tube6502 extends Base6502 {
     constructor(model, cpu) {
-        super(model);
+        super(model, { cycleAccurate: false });
 
         this.cycles = 0;
+        this.cpuMultiplier = 2;
         this.romPaged = true;
         this.memory = new Uint8Array(65536);
         this.rom = new Uint8Array(4096);
@@ -468,7 +469,7 @@ class Tube6502 extends Base6502 {
     }
 
     execute(cycles) {
-        this.cycles += cycles * 2;
+        this.cycles += (cycles * this.cpuMultiplier) | 0;
         if (this.cycles < 3) return;
         while (this.cycles > 0) {
             const opcode = this.readmem(this.pc);
@@ -570,19 +571,22 @@ function is1MHzAccess(addr) {
 }
 
 export class Cpu6502 extends Base6502 {
-    constructor(model, dbgr, video_, soundChip_, ddNoise_, music5000_, cmos, config, econet_) {
-        super(model);
+    constructor(
+        model,
+        { dbgr, video, soundChip, ddNoise, music5000, cmos, config, econet, cycleAccurate = true } = {},
+    ) {
+        super(model, { cycleAccurate });
         this.config = fixUpConfig(config);
         this.debugFlags = this.config.debugFlags;
         this.cmos = cmos;
         this.debugger = dbgr;
 
-        this.video = video_;
+        this.video = video;
         this.crtc = this.video.crtc;
         this.ula = this.video.ula;
-        this.soundChip = soundChip_;
-        this.music5000 = music5000_;
-        this.ddNoise = ddNoise_;
+        this.soundChip = soundChip;
+        this.music5000 = music5000;
+        this.ddNoise = ddNoise;
         this.memStatOffsetByIFetchBank = 0;
         this.memStatOffset = 0;
         this.memStat = new Uint8Array(512);
@@ -602,8 +606,11 @@ export class Cpu6502 extends Base6502 {
         this.videoCyclesBatch = this.config.videoCyclesBatch | 0;
         this.peripheralCyclesPerSecond = 2 * 1000 * 1000;
         this.tube = model.tube ? new Tube6502(model.tube, this) : new FakeTube();
+        if (model.tube && this.config.tubeCpuMultiplier) {
+            this.tube.cpuMultiplier = this.config.tubeCpuMultiplier;
+        }
         this.music5000PageSel = 0;
-        this.econet = econet_;
+        this.econet = econet;
 
         this.peripheralCycles = 0;
         this.videoCycles = 0;
@@ -616,16 +623,14 @@ export class Cpu6502 extends Base6502 {
         this.debugWrite = new DebugHook(this, "_debugWrite");
 
         this.scheduler = new Scheduler();
-        this.sysvia = new via.SysVia(
-            this,
-            this.scheduler,
-            this.video,
-            this.soundChip,
-            this.cmos,
-            this.model.isMaster,
-            this.config.keyLayout,
-            this.config.getGamepads,
-        );
+        this.sysvia = new via.SysVia(this, this.scheduler, {
+            video: this.video,
+            soundChip: this.soundChip,
+            cmos: this.cmos,
+            isMaster: this.model.isMaster,
+            initialLayout: this.config.keyLayout,
+            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.serial = new Serial(this.acia);

package/src/6502.opcodes.js

@@ -41,8 +41,9 @@ function push(reg) {
 }
 
 class InstructionGen {
-    constructor(is65c12) {
+    constructor(is65c12, cycleAccurate = true) {
         this.is65c12 = is65c12;
+        this.cycleAccurate = cycleAccurate;
         this.ops = {};
         this.cycle = 0;
     }
@@ -106,6 +107,10 @@ class InstructionGen {
     }
 
     spuriousOp(addr, reg) {
+        if (!this.cycleAccurate) {
+            this.cycle++;
+            return;
+        }
         if (this.is65c12) {
             this.readOp(addr, "", true);
         } else {
@@ -122,7 +127,7 @@ class InstructionGen {
                 toSkip++;
                 continue;
             }
-            if (toSkip && this.ops[i].exact) {
+            if (this.cycleAccurate && toSkip && this.ops[i].exact) {
                 if (this.ops[i].addr) {
                     out.push(`cpu.polltimeAddr(${toSkip}, ${this.ops[i].addr});`);
                 } else {
@@ -134,7 +139,7 @@ class InstructionGen {
             toSkip++;
         }
         if (toSkip) {
-            if (this.ops[this.cycle] && this.ops[this.cycle].addr) {
+            if (this.cycleAccurate && this.ops[this.cycle] && this.ops[this.cycle].addr) {
                 out.push(`cpu.polltimeAddr(${toSkip}, ${this.ops[this.cycle].addr});`);
             } else {
                 out.push(`cpu.polltime(${toSkip});`);
@@ -145,17 +150,17 @@ class InstructionGen {
     }
 
     split(condition) {
-        return new SplitInstruction(this, condition, this.is65c12);
+        return new SplitInstruction(this, condition, this.is65c12, this.cycleAccurate);
     }
 }
 
 class SplitInstruction {
-    constructor(preamble, condition, is65c12) {
+    constructor(preamble, condition, is65c12, cycleAccurate = true) {
         this.preamble = preamble;
         this.condition = condition;
-        this.ifTrue = new InstructionGen(is65c12);
+        this.ifTrue = new InstructionGen(is65c12, cycleAccurate);
         this.ifTrue.tick(preamble.cycle);
-        this.ifFalse = new InstructionGen(is65c12);
+        this.ifFalse = new InstructionGen(is65c12, cycleAccurate);
         this.ifFalse.tick(preamble.cycle);
 
         ["append", "prepend", "readOp", "writeOp", "spuriousOp"].forEach((op) => {
@@ -1052,7 +1057,7 @@ class Disassemble6502 {
     }
 }
 
-function makeCpuFunctions(cpu, opcodes, is65c12) {
+function makeCpuFunctions(cpu, opcodes, is65c12, cycleAccurate = true) {
     function getInstruction(opcodeString, needsReg) {
         const split = opcodeString.split(" ");
         const opcode = split[0];
@@ -1060,7 +1065,7 @@ function makeCpuFunctions(cpu, opcodes, is65c12) {
         const op = getOp(opcode, arg);
         if (!op) return null;
 
-        let ig = new InstructionGen(is65c12);
+        let ig = new InstructionGen(is65c12, cycleAccurate);
         if (needsReg) ig.append("let REG = 0|0;");
 
         switch (arg) {
@@ -1398,14 +1403,14 @@ ${indent}`)
     };
 }
 
-export function Cpu6502(cpu) {
-    return makeCpuFunctions(cpu, opcodes6502, false);
+export function Cpu6502(cpu, { cycleAccurate = true } = {}) {
+    return makeCpuFunctions(cpu, opcodes6502, false, cycleAccurate);
 }
 
-export function Cpu65c12(cpu) {
-    return makeCpuFunctions(cpu, opcodes65c12, true);
+export function Cpu65c12(cpu, { cycleAccurate = true } = {}) {
+    return makeCpuFunctions(cpu, opcodes65c12, true, cycleAccurate);
 }
 
-export function Cpu65c02(cpu) {
-    return makeCpuFunctions(cpu, opcodes65c02, true);
+export function Cpu65c02(cpu, { cycleAccurate = true } = {}) {
+    return makeCpuFunctions(cpu, opcodes65c02, true, cycleAccurate);
 }

package/src/acia.js

@@ -118,20 +118,34 @@ export class Acia {
     selectRs423(selected) {
         this.rs423Selected = !!selected;
         if (this.rs423Selected) {
-            // RS423 selected.
-            // CTS is always high, meaning not Clear To Send. This is
-            // because we don't yet emulate anything on the "other end",
-            // so there is nothing to pull CTS low.
-            this.sr |= 0x08;
+            // When a handler is present it acts as the remote device and is
+            // always ready to receive, so CTS is low (active = clear to send).
+            // Without a handler there is nothing on the other end and CTS
+            // stays high, which inhibits TDRE so the OS output buffer drains
+            // silently rather than hanging.
+            if (this.rs423Handler) {
+                this.sr &= ~0x08; // CTS low — clear to send
+            } else {
+                this.sr |= 0x08; // CTS high — not connected
+            }
         } else {
-            // Cassette selected.
-            // CTS is always low, meaning actually Clear To Send.
+            // Cassette selected — CTS is always low (clear to send).
             this.sr &= ~0x08;
         }
         this.dcdLineUpdated();
         this.runRs423Task.ensureScheduled(this.rs423Selected, this.serialReceiveCyclesPerByte);
     }
 
+    /**
+     * Attach or detach an RS-423 peripheral handler at runtime.
+     * The handler must implement onTransmit(byte) and tryReceive(rts).
+     * If RS-423 is already selected, the CTS line is updated immediately.
+     */
+    setRs423Handler(handler) {
+        this.rs423Handler = handler;
+        if (this.rs423Selected) this.selectRs423(true);
+    }
+
     dcdLineUpdated() {
         // AUG: "It will always be low when the RS423 interface is selected".
         const level = this.rs423Selected ? false : this.tapeDcdLineLevel;

package/src/bbc-palette.js

@@ -0,0 +1,24 @@
+"use strict";
+
+// The 16 standard BBC Micro colours in ABGR format (0xffBBGGRR, little-endian canvas RGBA).
+// Colours 0-7 are the primary palette; 8-15 duplicate them as the default solid/non-flash set.
+// Imported by both video.js (NulaDefaultPalette) and teletext.js (BbcDefaultCollook) to avoid
+// circular imports between those two modules.
+export const BbcDefaultPalette = new Uint32Array([
+    0xff000000, // 0: black
+    0xff0000ff, // 1: red
+    0xff00ff00, // 2: green
+    0xff00ffff, // 3: yellow
+    0xffff0000, // 4: blue
+    0xffff00ff, // 5: magenta
+    0xffffff00, // 6: cyan
+    0xffffffff, // 7: white
+    0xff000000, // 8: black (solid duplicate)
+    0xff0000ff, // 9: red
+    0xff00ff00, // 10: green
+    0xff00ffff, // 11: yellow
+    0xffff0000, // 12: blue
+    0xffff00ff, // 13: magenta
+    0xffffff00, // 14: cyan
+    0xffffffff, // 15: white
+]);

package/src/cmos.js

@@ -1,8 +1,17 @@
 "use strict";
 
+// CMOS layout: bytes 0-13 are RTC internal registers; bytes 14-63 are the 50
+// bytes of user storage.  Storage byte 11 (= CMOS address 25 = 0x19) holds
+// the BBC Master DFS configuration byte whose bits [1:0] are the WD1770 step
+// rate (*CONFIGURE FDRIVE):  0=6ms  1=12ms  2=20ms  3=30ms.
+// The correct default is FDRIVE 0 (6ms, value 0xc8).  The previous default
+// 0xca had bits[1:0]=0b10 (20ms), which caused disc-streaming demos such as
+// STNICC-beeb to hang on the Master 128 because the WD1770 seek overran the
+// vsync window.  Confirmed by @tom-seddon (b2 emulator):
+// https://github.com/mattgodbolt/jsbeeb/issues/576
 const defaultCmos = [
     0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0xfe, 0x00, 0xeb, 0x00,
-    0xc9, 0xff, 0xff, 0x12, 0x00, 0x17, 0xca, 0x1e, 0x05, 0x00, 0x35, 0xa6, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+    0xc9, 0xff, 0xff, 0x12, 0x00, 0x17, 0xc8, 0x1e, 0x05, 0x00, 0x35, 0xa6, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
     0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
 ];
 
@@ -22,6 +31,8 @@ function fromBcd(value) {
     return parseInt(value.toString(16), 10);
 }
 
+export { defaultCmos };
+
 export class Cmos {
     constructor(persistence, cmosOverride, econet) {
         this.store = persistence ? persistence.load() : null;

package/src/config.js

@@ -17,6 +17,7 @@ export class Config extends EventEmitter {
             this.changed = {};
             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);
@@ -36,6 +37,13 @@ export class Config extends EventEmitter {
 
         $("#65c02").on("click", () => {
             this.changed.coProcessor = $("#65c02").prop("checked");
+            $("#tubeCpuMultiplier").prop("disabled", !$("#65c02").prop("checked"));
+        });
+
+        $("#tubeCpuMultiplier").on("input", () => {
+            const val = parseInt($("#tubeCpuMultiplier").val(), 10);
+            $("#tubeCpuMultiplierValue").text(val);
+            this.changed.tubeCpuMultiplier = val;
         });
 
         $("#hasTeletextAdaptor").on("click", () => {
@@ -67,6 +75,10 @@ export class Config extends EventEmitter {
             this.changed.mouseJoystickEnabled = $("#mouseJoystickEnabled").prop("checked");
         });
 
+        $("#speechOutput").on("click", () => {
+            this.changed.speechOutput = $("#speechOutput").prop("checked");
+        });
+
         $(".display-mode-option").on("click", (e) => {
             const mode = $(e.target).data("mode");
             this.changed.displayMode = mode;
@@ -87,6 +99,10 @@ export class Config extends EventEmitter {
         $("#mouseJoystickEnabled").prop("checked", !!enabled);
     }
 
+    setSpeechOutput(enabled) {
+        $("#speechOutput").prop("checked", !!enabled);
+    }
+
     setDisplayMode(mode) {
         const config = getFilterForMode(mode).getDisplayConfig();
         $(".display-mode-text").text(config.name);
@@ -105,6 +121,13 @@ export class Config extends EventEmitter {
         enabled = !!enabled;
         $("#65c02").prop("checked", enabled);
         this.model.tube = enabled ? findModel("Tube65c02") : null;
+        $("#tubeCpuMultiplier").prop("disabled", !enabled);
+    }
+
+    setTubeCpuMultiplier(value) {
+        this.tubeCpuMultiplier = value;
+        $("#tubeCpuMultiplier").val(value);
+        $("#tubeCpuMultiplierValue").text(value);
     }
 
     setEconet(enabled) {

package/src/fake6502.js

@@ -17,10 +17,17 @@ const dbgr = {
 
 export function fake6502(model, opts) {
     opts = opts || {};
-    const video = opts.video || fakeVideo;
     model = model || TEST_6502;
     if (opts.tube) model.tube = findModel("Tube65c02");
-    return new Cpu6502(model, dbgr, video, soundChip, new FakeDdNoise(), new FakeMusic5000(), new Cmos());
+    return new Cpu6502(model, {
+        dbgr,
+        video: opts.video || fakeVideo,
+        soundChip: opts.soundChip || soundChip,
+        ddNoise: new FakeDdNoise(),
+        music5000: new FakeMusic5000(),
+        cmos: new Cmos(),
+        cycleAccurate: opts.cycleAccurate,
+    });
 }
 
 export function fake65C02() {

package/src/fdc.js

@@ -13,16 +13,17 @@ export function load(name) {
  */
 export class DiscType {
     /**
-     * Create a new disc type
-     * @param {string} extension - File extension for this disc type (e.g. ".ssd", ".hfe")
-     * @param {function(Disc, Uint8Array, function?): Disc} loader - Function to load this disc type
-     * @param {function(Disc): Uint8Array} saver - Function to save this disc type
-     * @param {function(Uint8Array, string): void|null} nameSetter - Function to set the name/label in the disc image
-     * @param {boolean} isDoubleSided - Whether the disc format is double-sided
-     * @param {boolean} isDoubleDensity - Whether the disc format is double density
-     * @param {number|undefined} byteSize - The size in bytes of this disc format, or undefined if variable
+     * Create a new disc type.
+     * @param {Object} [options] - Configuration options for this disc type.
+     * @param {string} options.extension - File extension for this disc type (e.g. ".ssd", ".hfe").
+     * @param {function(Disc, Uint8Array, function?): Disc} options.loader - Function to load this disc type.
+     * @param {function(Disc): Uint8Array} options.saver - Function to save this disc type.
+     * @param {function(Uint8Array, string): void|null} [options.nameSetter] - Function to set the name/label in the disc image, or null if not supported.
+     * @param {boolean} [options.isDoubleSided] - Whether the disc format is double-sided.
+     * @param {boolean} [options.isDoubleDensity] - Whether the disc format is double density.
+     * @param {number|undefined} [options.byteSize] - The size in bytes of this disc format, or undefined if variable.
      */
-    constructor(extension, loader, saver, nameSetter, isDoubleSided, isDoubleDensity, byteSize) {
+    constructor({ extension, loader, saver, nameSetter, isDoubleSided, isDoubleDensity, byteSize } = {}) {
         this._extension = extension;
         this._loader = loader;
         this._saver = saver;
@@ -128,69 +129,65 @@ function setDfsDiscName(data, name) {
 }
 
 // HFE disc type - variable size
-const hfeDiscType = new DiscType(
-    ".hfe",
-    loadHfe,
-    toHfe,
-    null, // no name setter function yet
-    true, // double-sided
-    true, // double density
-    undefined, // variable size
-);
+const hfeDiscType = new DiscType({
+    extension: ".hfe",
+    loader: loadHfe,
+    saver: toHfe,
+    isDoubleSided: true,
+    isDoubleDensity: true,
+});
 
 // ADFS (Large) discs are double density, double sided
-const adlDiscType = new DiscType(
-    ".adl",
-    (disc, data, _onChange) => {
+const adlDiscType = new DiscType({
+    extension: ".adl",
+    loader: (disc, data, _onChange) => {
         // TODO handle onChange
         return loadAdf(disc, data, true);
     },
-    (_data) => {
+    saver: (_data) => {
         throw new Error("ADL unsupported");
     },
-    null, // no name setter function yet
-    true, // double-sided
-    true, // double density
-    AdfsLargeByteSize,
-);
+    isDoubleSided: true,
+    isDoubleDensity: true,
+    byteSize: AdfsLargeByteSize,
+});
 
 // ADFS (Small) discs are standard ADFS (non-double) density, single sided
-const adfDiscType = new DiscType(
-    ".adf",
-    (disc, data, _onChange) => {
+const adfDiscType = new DiscType({
+    extension: ".adf",
+    loader: (disc, data, _onChange) => {
         // TODO handle onChange
         return loadAdf(disc, data, false);
     },
-    (_data) => {
+    saver: (_data) => {
         throw new Error("ADF unsupported");
     },
-    null, // no name setter function yet
-    false, // single-sided
-    true, // double density
-    AdfsSmallByteSize,
-);
+    isDoubleSided: false,
+    isDoubleDensity: true,
+    byteSize: AdfsSmallByteSize,
+});
 
 // DSD (Double-sided disc)
-const dsdDiscType = new DiscType(
-    ".dsd",
-    (disc, data, onChange) => loadSsd(disc, data, true, onChange),
-    toSsdOrDsd,
-    setDfsDiscName, // supports setting catalogue name
-    true, // double-sided
-    false, // standard density
-    DsdByteSize,
-);
+const dsdDiscType = new DiscType({
+    extension: ".dsd",
+    loader: (disc, data, onChange) => loadSsd(disc, data, true, onChange),
+    saver: toSsdOrDsd,
+    nameSetter: setDfsDiscName,
+    isDoubleSided: true,
+    isDoubleDensity: false,
+    byteSize: DsdByteSize,
+});
 
 // SSD (Single-sided disc)
-const ssdDiscType = new DiscType(
-    ".ssd",
-    (disc, data, onChange) => loadSsd(disc, data, false, onChange),
-    toSsdOrDsd,
-    setDfsDiscName, // supports setting catalogue name
-    false, // single-sided
-    false, // standard density
-    SsdByteSize,
-);
+const ssdDiscType = new DiscType({
+    extension: ".ssd",
+    loader: (disc, data, onChange) => loadSsd(disc, data, false, onChange),
+    saver: toSsdOrDsd,
+    nameSetter: setDfsDiscName,
+    isDoubleSided: false,
+    isDoubleDensity: false,
+    byteSize: SsdByteSize,
+});
 /**
  * Determine the disc type based on the file name extension
  * @param {string} name - The file name with extension

package/src/keyboard.js

@@ -214,14 +214,17 @@ export class Keyboard extends EventEmitter {
         const isSpecialHandled = this._handleSpecialKeys(code);
         if (isSpecialHandled) return;
 
-        // Always pass the key to the BBC Micro (unless it was a special key)
-        this.processor.sysvia.keyDown(code, evt.shiftKey);
-
-        // Check for registered handlers
+        // Check for registered handlers first; if one fires, don't also send to the BBC.
+        // This lets Alt+key and Ctrl+key handlers cleanly own their keys without the
+        // underlying key leaking through to the emulated machine.
         const handler = this._findKeyHandler(code, evt.altKey, evt.ctrlKey);
         if (handler) {
             handler.handler(true, code);
+            return;
         }
+
+        // No handler claimed the key — pass it to the BBC Micro.
+        this.processor.sysvia.keyDown(code, evt.shiftKey);
     }
 
     /**

package/src/machine-session.js

@@ -9,6 +9,7 @@ import { readFileSync } from "fs";
 import { fileURLToPath } from "url";
 import path from "path";
 import { TestMachine } from "../tests/test-machine.js";
+import { InstrumentedSoundChip } from "./soundchip.js";
 
 // Resolve the jsbeeb package root from our own location (src/machine-session.js
 // → go up one level).  Passed to setNodeBasePath() so the ROM loader resolves
@@ -27,9 +28,12 @@ const FB_HEIGHT = 625;
 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
      */
-    constructor(modelName = "B-DFS1.2") {
+    constructor(modelName = "B-DFS1.2", opts = {}) {
         this.modelName = modelName;
+        this._opts = opts;
 
         // Raw RGBA framebuffer — the Video chip renders into _fb32 (cleared each frame).
         // _completeFb8 is a snapshot taken at paint time (the equivalent of the browser canvas)
@@ -50,8 +54,11 @@ export class MachineSession {
             this._completeFb8.set(this._fb8);
         });
 
-        // TestMachine forwards opts.video to fake6502, which uses it instead of FakeVideo
-        this._machine = new TestMachine(modelName, { video: this._video });
+        // Use a real (instrumented) sound chip so we can read registers and capture writes
+        this._soundChip = new InstrumentedSoundChip();
+
+        // TestMachine forwards opts.video and opts.soundChip to fake6502
+        this._machine = new TestMachine(modelName, { video: this._video, soundChip: this._soundChip });
 
         // Accumulated VDU text output — drained by callers
         this._pendingOutput = [];
@@ -61,6 +68,9 @@ export class MachineSession {
     async initialise() {
         setNodeBasePath(_jsbeebRoot);
         await this._machine.initialise();
+        if (this._opts.discImage) {
+            this.loadDisc(this._opts.discImage);
+        }
         this._installCaptureHook();
     }
 
@@ -201,6 +211,30 @@ export class MachineSession {
         });
     }
 
+    /**
+     * Press a key (by browser keyCode).
+     * Use utils.keyCodes for named keys, or ASCII charCode for letters/digits.
+     */
+    keyDown(keyCode, shiftDown = false) {
+        this._machine.processor.sysvia.keyDown(keyCode, shiftDown);
+    }
+
+    /**
+     * Release a key (by browser keyCode).
+     */
+    keyUp(keyCode) {
+        this._machine.processor.sysvia.keyUp(keyCode);
+    }
+
+    /**
+     * Reset the machine.
+     * @param {boolean} [hard=true] - true for power-on reset, false for soft reset
+     */
+    reset(hard = true) {
+        this._machine.processor.reset(hard);
+        this._pendingOutput = [];
+    }
+
     /** Tokenise BBC BASIC source and write it into PAGE */
     async loadBasic(source) {
         await this._machine.loadBasic(source);