@emu198x/zx-spectrum 0.3.0 → 0.4.0

package/README.md

@@ -83,3 +83,78 @@ machines, or Spectrum clones.
 The emulator is licensed under the terms in the Emu198x repository. The ROM is
 copyright Amstrad plc and is redistributed under the permission above; it is
 not covered by that licence.
+
+### Running inside a Web Worker
+
+`Spectrum.createHeadless(rom)` and, in a firmware-bundled build,
+`Spectrum.createHeadlessBundled()` create the same 48K machine without a DOM
+canvas. Run `autoload()` and `tick(elapsedMs)` in the worker, then transfer the
+`frameRgba()` buffer and `frameSize()` dimensions to the page for presentation.
+The existing canvas-based constructors remain available.
+
+Boot and turbo tape loading are synchronous operations. Keeping them in a worker
+prevents those operations from blocking editing and other page interactions; it
+does not remove their emulation cost. Keep at most one tick request in flight,
+terminate the previous worker when starting a new run, and pause requests when
+the page is hidden. The caller owns worker lifecycle, frame transfer and audio
+presentation. No snapshot injection or tape-loading shortcut is implied.
+
+## Numbered BASIC listings
+
+The additive `basicTape(source, name)` export converts a numbered ASCII listing
+into a self-starting BASIC TAP. It uses the format crate's `tokenise_listing`
+path and the shared TAP writer, preserving expression text rather than passing
+it through the analysis AST. Line numbers are sorted; duplicate line numbers,
+empty programs, unsupported characters, unterminated strings and out-of-range
+numbers return errors. This is tokenisation, not a BASIC grammar validator:
+the ROM still reports execution and syntax errors when the tape runs.
+
+This route is currently a bounded Code198x browser trial (Meet BASIC greeting
+and Sonar). DEF FN parameter markers, embedded graphics/control codes and broader
+source-notation compatibility remain outside it. The listing and headless worker APIs are available from npm version 0.4.0.
+
+### Direct program execution
+
+On a fresh 48K instance, `runBasic(source)` installs the tokenised listing in
+RAM through the shared native BASIC loader, updates its system variables, and
+types RUN through the ROM. It mounts no tape. `basicTape(source, name)` remains
+the independent download/export path.
+
+`runCode(bytes, origin, entry)` boots the ROM, installs the machine code and a
+small BASIC launcher, then executes CLEAR followed by RANDOMIZE USR. This
+preserves ROM services and a return stack. Code must start at or above 24576,
+fit below 65536, and contain its entry point. Use a fresh instance for each run.
+Both APIs are synchronous: worker hosts keep boot work off the page thread.
+These APIs are available from npm version 0.4.0.
+
+`readMemory(address, length)` reads the current visible address space for lesson
+inspectors. It is read-only and rejects ranges outside the 64 KiB address space.
+This API is available from npm version 0.4.0.
+
+For lesson replay, call `enableScreenWriteTrace(address, length)` on a fresh machine before
+`runCode()`, then read `screenWriteTrace()`. Choose a narrow bitmap range to avoid filling the capture with ROM clearing.
+It returns captured writes within that range
+(including ROM writes) and a `full` flag when the shared 8192-record cap is
+reached. The caller can filter by program PC range. A replay is a recording,
+not live stepping; a full capture must not be presented as complete. These
+APIs are available from npm version 0.4.0.
+
+For the bounded routine lesson, call `enableRoutineTrace(stop)` before
+`runCode()`, then `routineTrace()`. The JSON recording contains actual unconditional
+CALL/RET transitions and bitmap writes in $4000–$47FF, with before/after register
+snapshots. Existing debugger stepping stops at the supplied PC, on leaving the
+program, or after 4096 steps. Check `complete`: only reaching the supplied stop
+address makes it true. The intended stop is the lesson's `hold` label. This is
+bounded teaching instrumentation, not a general instruction trace. It is available
+from npm version 0.4.0.
+
+### Debugger controls
+
+`debugState()` serialises shared debugger CPU state and disassembly/bytes at PC.
+`debugStep()` invokes the existing bounded native step; `debugRunTo(address)`
+runs to an instruction boundary with a fixed 14-million-half-cycle budget and
+returns whether it reached the address. Invalid addresses are rejected. Both
+execution methods deliver queued input first. Suspend normal frame ticks before
+using them; no implicit rendering or real-time playback runs while paused.
+A failed run-to is not a breakpoint hit, and a step at HALT can remain waiting.
+These exports are available from npm version 0.4.0.

package/emu198x_spectrum_web.d.ts

@@ -2,7 +2,7 @@
 /* eslint-disable */
 
 /**
- * A ZX Spectrum attached to a canvas.
+ * A ZX Spectrum with optional canvas presentation.
  */
 export class Spectrum {
     private constructor();
@@ -73,6 +73,61 @@ export class Spectrum {
      * Returns a JavaScript error if the canvas has no 2-D context.
      */
     static createBundled(canvas: HTMLCanvasElement): Promise<Spectrum>;
+    /**
+     * Builds a canvas-free 48K suitable for a Web Worker.
+     *
+     * Use `tick`, `frameSize` and `frameRgba` to run the same machine and
+     * transfer completed frames to a presenter. No DOM object is accessed.
+     *
+     * # Errors
+     *
+     * Returns an error if the supplied firmware cannot build a 48K machine.
+     */
+    static createHeadless(rom: Uint8Array): Spectrum;
+    /**
+     * Builds a canvas-free 48K with the package's bundled ROM.
+     *
+     * # Errors
+     *
+     * Returns an error if the bundled firmware cannot build the machine.
+     */
+    static createHeadlessBundled(): Spectrum;
+    /**
+     * Run to an instruction boundary, bounded to 14 million half-cycles.
+     * Suspend the host frame loop before calling this method.
+     *
+     * # Errors
+     * Rejects invalid addresses and input delivery errors.
+     */
+    debugRunTo(address: number): boolean;
+    /**
+     * Inspect shared debugger registers and disassembly at PC.
+     *
+     * # Errors
+     * Returns an error if state cannot be serialised.
+     */
+    debugState(): string;
+    /**
+     * Use the existing bounded native step; suspend the host frame loop first.
+     *
+     * # Errors
+     * Returns an error if pending input cannot be delivered.
+     */
+    debugStep(): bigint;
+    /**
+     * Enables a bounded debugger recording of CALL nn, RET and bitmap writes,
+     * stopping before the named hold address. Use on a fresh machine.
+     */
+    enableRoutineTrace(stop: number): void;
+    /**
+     * Records writes in a selected bitmap range during the next direct code run.
+     * Call on a fresh machine. Narrow ranges leave room for the program's writes
+     * after the ROM clears the display.
+     *
+     * # Errors
+     * Rejects empty ranges or ranges outside bitmap RAM ($4000..$5800).
+     */
+    enableScreenWriteTrace(address: number, length: number): void;
     /**
      * The machine's picture as RGBA bytes, for a page that wants to present
      * it itself.
@@ -144,6 +199,45 @@ export class Spectrum {
      * Returns a JavaScript error if the machine does not know the path.
      */
     query(path: string): string;
+    /**
+     * Reads visible memory for a lesson's live inspection panel.
+     *
+     * # Errors
+     * Rejects ranges extending beyond the 64 KiB address space.
+     */
+    readMemory(address: number, length: number): Uint8Array;
+    /**
+     * Returns the executed routine events and whether the stop was reached.
+     *
+     * # Errors
+     * Returns a JSON serialisation error if the recording cannot be encoded.
+     */
+    routineTrace(): string;
+    /**
+     * Installs a numbered BASIC listing directly into RAM and asks the ROM
+     * to RUN it. Call on a fresh 48K; no tape is mounted or played.
+     *
+     * # Errors
+     * Returns conversion, boot or editor-prompt errors.
+     */
+    runBasic(source: string): void;
+    /**
+     * Installs machine code in a fresh 48K and calls it through the ROM's
+     * RANDOMIZE USR, with CLEAR reserving its RAM and a valid return stack.
+     *
+     * # Errors
+     * Rejects empty code, overlap with BASIC/system RAM, overflow, entry
+     * outside the code, and ROM boot or prompt failures.
+     */
+    runCode(bytes: Uint8Array, origin: number, entry: number): void;
+    /**
+     * Returns captured writes (including ROM writes) and saturation status.
+     * Consumers can select the program's PC range without inventing a trace.
+     *
+     * # Errors
+     * Returns a serialisation error if the capture cannot be encoded.
+     */
+    screenWriteTrace(): string;
     /**
      * Starts or stops machine audio.
      */
@@ -168,16 +262,32 @@ export class Spectrum {
     tick(elapsed_ms: number): number;
 }
 
+/**
+ * Tokenise source and create an auto-starting BASIC TAP, without a machine.
+ *
+ * # Errors
+ * Returns a JavaScript error for unsupported or malformed listing input.
+ */
+export function basicTape(source: string, name: string): Uint8Array;
+
 export type InitInput = RequestInfo | URL | Response | BufferSource | WebAssembly.Module;
 
 export interface InitOutput {
     readonly memory: WebAssembly.Memory;
     readonly __wbg_spectrum_free: (a: number, b: number) => void;
+    readonly basicTape: (a: number, b: number, c: number, d: number) => [number, number, number, number];
     readonly spectrum_audioDrain: (a: number) => [number, number];
     readonly spectrum_autoload: (a: number, b: number) => [number, number, number];
     readonly spectrum_configureAudio: (a: number, b: number, c: number, d: number) => void;
     readonly spectrum_create: (a: any, b: number, c: number) => any;
     readonly spectrum_createBundled: (a: any) => any;
+    readonly spectrum_createHeadless: (a: number, b: number) => [number, number, number];
+    readonly spectrum_createHeadlessBundled: () => [number, number, number];
+    readonly spectrum_debugRunTo: (a: number, b: number) => [number, number, number];
+    readonly spectrum_debugState: (a: number) => [number, number, number, number];
+    readonly spectrum_debugStep: (a: number) => [bigint, number, number];
+    readonly spectrum_enableRoutineTrace: (a: number, b: number) => void;
+    readonly spectrum_enableScreenWriteTrace: (a: number, b: number, c: number) => [number, number];
     readonly spectrum_frameRgba: (a: number) => [number, number];
     readonly spectrum_frameSize: (a: number) => [number, number];
     readonly spectrum_keyDown: (a: number, b: number, c: number) => number;
@@ -186,6 +296,11 @@ export interface InitOutput {
     readonly spectrum_loadSnapshot: (a: number, b: number, c: number, d: number, e: number) => [number, number];
     readonly spectrum_mediaSlots: (a: number) => [number, number];
     readonly spectrum_query: (a: number, b: number, c: number) => [number, number, number, number];
+    readonly spectrum_readMemory: (a: number, b: number, c: number) => [number, number, number, number];
+    readonly spectrum_routineTrace: (a: number) => [number, number, number, number];
+    readonly spectrum_runBasic: (a: number, b: number, c: number) => [number, number];
+    readonly spectrum_runCode: (a: number, b: number, c: number, d: number, e: number) => [number, number];
+    readonly spectrum_screenWriteTrace: (a: number) => [number, number, number, number];
     readonly spectrum_setAudioEnabled: (a: number, b: number) => void;
     readonly spectrum_tick: (a: number, b: number) => [number, number, number];
     readonly wasm_bindgen_d6cb7d81ec28c0ae___convert__closures_____invoke___wasm_bindgen_d6cb7d81ec28c0ae___JsValue__core_f0fd674eaa06beef___result__Result_____wasm_bindgen_d6cb7d81ec28c0ae___JsError___true_: (a: number, b: number, c: any) => [number, number];
@@ -194,10 +309,10 @@ export interface InitOutput {
     readonly __externref_table_alloc: () => number;
     readonly __wbindgen_externrefs: WebAssembly.Table;
     readonly __wbindgen_destroy_closure: (a: number, b: number) => void;
-    readonly __wbindgen_free: (a: number, b: number, c: number) => void;
-    readonly __externref_table_dealloc: (a: number) => void;
     readonly __wbindgen_malloc: (a: number, b: number) => number;
     readonly __wbindgen_realloc: (a: number, b: number, c: number, d: number) => number;
+    readonly __externref_table_dealloc: (a: number) => void;
+    readonly __wbindgen_free: (a: number, b: number, c: number) => void;
     readonly __externref_drop_slice: (a: number, b: number) => void;
     readonly __wbindgen_start: () => void;
 }

package/emu198x_spectrum_web.js

@@ -1,7 +1,7 @@
 /* @ts-self-types="./emu198x_spectrum_web.d.ts" */
 
 /**
- * A ZX Spectrum attached to a canvas.
+ * A ZX Spectrum with optional canvas presentation.
  */
 export class Spectrum {
     static __wrap(ptr) {
@@ -117,6 +117,121 @@ export class Spectrum {
         const ret = wasm.spectrum_createBundled(canvas);
         return ret;
     }
+    /**
+     * Builds a canvas-free 48K suitable for a Web Worker.
+     *
+     * Use `tick`, `frameSize` and `frameRgba` to run the same machine and
+     * transfer completed frames to a presenter. No DOM object is accessed.
+     *
+     * # Errors
+     *
+     * Returns an error if the supplied firmware cannot build a 48K machine.
+     * @param {Uint8Array} rom
+     * @returns {Spectrum}
+     */
+    static createHeadless(rom) {
+        const ptr0 = passArray8ToWasm0(rom, wasm.__wbindgen_malloc);
+        const len0 = WASM_VECTOR_LEN;
+        const ret = wasm.spectrum_createHeadless(ptr0, len0);
+        if (ret[2]) {
+            throw takeFromExternrefTable0(ret[1]);
+        }
+        return Spectrum.__wrap(ret[0]);
+    }
+    /**
+     * Builds a canvas-free 48K with the package's bundled ROM.
+     *
+     * # Errors
+     *
+     * Returns an error if the bundled firmware cannot build the machine.
+     * @returns {Spectrum}
+     */
+    static createHeadlessBundled() {
+        const ret = wasm.spectrum_createHeadlessBundled();
+        if (ret[2]) {
+            throw takeFromExternrefTable0(ret[1]);
+        }
+        return Spectrum.__wrap(ret[0]);
+    }
+    /**
+     * Run to an instruction boundary, bounded to 14 million half-cycles.
+     * Suspend the host frame loop before calling this method.
+     *
+     * # Errors
+     * Rejects invalid addresses and input delivery errors.
+     * @param {number} address
+     * @returns {boolean}
+     */
+    debugRunTo(address) {
+        const ret = wasm.spectrum_debugRunTo(this.__wbg_ptr, address);
+        if (ret[2]) {
+            throw takeFromExternrefTable0(ret[1]);
+        }
+        return ret[0] !== 0;
+    }
+    /**
+     * Inspect shared debugger registers and disassembly at PC.
+     *
+     * # Errors
+     * Returns an error if state cannot be serialised.
+     * @returns {string}
+     */
+    debugState() {
+        let deferred2_0;
+        let deferred2_1;
+        try {
+            const ret = wasm.spectrum_debugState(this.__wbg_ptr);
+            var ptr1 = ret[0];
+            var len1 = ret[1];
+            if (ret[3]) {
+                ptr1 = 0; len1 = 0;
+                throw takeFromExternrefTable0(ret[2]);
+            }
+            deferred2_0 = ptr1;
+            deferred2_1 = len1;
+            return getStringFromWasm0(ptr1, len1);
+        } finally {
+            wasm.__wbindgen_free(deferred2_0, deferred2_1, 1);
+        }
+    }
+    /**
+     * Use the existing bounded native step; suspend the host frame loop first.
+     *
+     * # Errors
+     * Returns an error if pending input cannot be delivered.
+     * @returns {bigint}
+     */
+    debugStep() {
+        const ret = wasm.spectrum_debugStep(this.__wbg_ptr);
+        if (ret[2]) {
+            throw takeFromExternrefTable0(ret[1]);
+        }
+        return BigInt.asUintN(64, ret[0]);
+    }
+    /**
+     * Enables a bounded debugger recording of CALL nn, RET and bitmap writes,
+     * stopping before the named hold address. Use on a fresh machine.
+     * @param {number} stop
+     */
+    enableRoutineTrace(stop) {
+        wasm.spectrum_enableRoutineTrace(this.__wbg_ptr, stop);
+    }
+    /**
+     * Records writes in a selected bitmap range during the next direct code run.
+     * Call on a fresh machine. Narrow ranges leave room for the program's writes
+     * after the ROM clears the display.
+     *
+     * # Errors
+     * Rejects empty ranges or ranges outside bitmap RAM ($4000..$5800).
+     * @param {number} address
+     * @param {number} length
+     */
+    enableScreenWriteTrace(address, length) {
+        const ret = wasm.spectrum_enableScreenWriteTrace(this.__wbg_ptr, address, length);
+        if (ret[1]) {
+            throw takeFromExternrefTable0(ret[0]);
+        }
+    }
     /**
      * The machine's picture as RGBA bytes, for a page that wants to present
      * it itself.
@@ -268,6 +383,110 @@ export class Spectrum {
             wasm.__wbindgen_free(deferred3_0, deferred3_1, 1);
         }
     }
+    /**
+     * Reads visible memory for a lesson's live inspection panel.
+     *
+     * # Errors
+     * Rejects ranges extending beyond the 64 KiB address space.
+     * @param {number} address
+     * @param {number} length
+     * @returns {Uint8Array}
+     */
+    readMemory(address, length) {
+        const ret = wasm.spectrum_readMemory(this.__wbg_ptr, address, length);
+        if (ret[3]) {
+            throw takeFromExternrefTable0(ret[2]);
+        }
+        var v1 = getArrayU8FromWasm0(ret[0], ret[1]).slice();
+        wasm.__wbindgen_free(ret[0], ret[1] * 1, 1);
+        return v1;
+    }
+    /**
+     * Returns the executed routine events and whether the stop was reached.
+     *
+     * # Errors
+     * Returns a JSON serialisation error if the recording cannot be encoded.
+     * @returns {string}
+     */
+    routineTrace() {
+        let deferred2_0;
+        let deferred2_1;
+        try {
+            const ret = wasm.spectrum_routineTrace(this.__wbg_ptr);
+            var ptr1 = ret[0];
+            var len1 = ret[1];
+            if (ret[3]) {
+                ptr1 = 0; len1 = 0;
+                throw takeFromExternrefTable0(ret[2]);
+            }
+            deferred2_0 = ptr1;
+            deferred2_1 = len1;
+            return getStringFromWasm0(ptr1, len1);
+        } finally {
+            wasm.__wbindgen_free(deferred2_0, deferred2_1, 1);
+        }
+    }
+    /**
+     * Installs a numbered BASIC listing directly into RAM and asks the ROM
+     * to RUN it. Call on a fresh 48K; no tape is mounted or played.
+     *
+     * # Errors
+     * Returns conversion, boot or editor-prompt errors.
+     * @param {string} source
+     */
+    runBasic(source) {
+        const ptr0 = passStringToWasm0(source, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+        const len0 = WASM_VECTOR_LEN;
+        const ret = wasm.spectrum_runBasic(this.__wbg_ptr, ptr0, len0);
+        if (ret[1]) {
+            throw takeFromExternrefTable0(ret[0]);
+        }
+    }
+    /**
+     * Installs machine code in a fresh 48K and calls it through the ROM's
+     * RANDOMIZE USR, with CLEAR reserving its RAM and a valid return stack.
+     *
+     * # Errors
+     * Rejects empty code, overlap with BASIC/system RAM, overflow, entry
+     * outside the code, and ROM boot or prompt failures.
+     * @param {Uint8Array} bytes
+     * @param {number} origin
+     * @param {number} entry
+     */
+    runCode(bytes, origin, entry) {
+        const ptr0 = passArray8ToWasm0(bytes, wasm.__wbindgen_malloc);
+        const len0 = WASM_VECTOR_LEN;
+        const ret = wasm.spectrum_runCode(this.__wbg_ptr, ptr0, len0, origin, entry);
+        if (ret[1]) {
+            throw takeFromExternrefTable0(ret[0]);
+        }
+    }
+    /**
+     * Returns captured writes (including ROM writes) and saturation status.
+     * Consumers can select the program's PC range without inventing a trace.
+     *
+     * # Errors
+     * Returns a serialisation error if the capture cannot be encoded.
+     * @returns {string}
+     */
+    screenWriteTrace() {
+        let deferred2_0;
+        let deferred2_1;
+        try {
+            const ret = wasm.spectrum_screenWriteTrace(this.__wbg_ptr);
+            var ptr1 = ret[0];
+            var len1 = ret[1];
+            if (ret[3]) {
+                ptr1 = 0; len1 = 0;
+                throw takeFromExternrefTable0(ret[2]);
+            }
+            deferred2_0 = ptr1;
+            deferred2_1 = len1;
+            return getStringFromWasm0(ptr1, len1);
+        } finally {
+            wasm.__wbindgen_free(deferred2_0, deferred2_1, 1);
+        }
+    }
     /**
      * Starts or stops machine audio.
      * @param {boolean} enabled
@@ -303,6 +522,29 @@ export class Spectrum {
     }
 }
 if (Symbol.dispose) Spectrum.prototype[Symbol.dispose] = Spectrum.prototype.free;
+
+/**
+ * Tokenise source and create an auto-starting BASIC TAP, without a machine.
+ *
+ * # Errors
+ * Returns a JavaScript error for unsupported or malformed listing input.
+ * @param {string} source
+ * @param {string} name
+ * @returns {Uint8Array}
+ */
+export function basicTape(source, name) {
+    const ptr0 = passStringToWasm0(source, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+    const len0 = WASM_VECTOR_LEN;
+    const ptr1 = passStringToWasm0(name, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+    const len1 = WASM_VECTOR_LEN;
+    const ret = wasm.basicTape(ptr0, len0, ptr1, len1);
+    if (ret[3]) {
+        throw takeFromExternrefTable0(ret[2]);
+    }
+    var v3 = getArrayU8FromWasm0(ret[0], ret[1]).slice();
+    wasm.__wbindgen_free(ret[0], ret[1] * 1, 1);
+    return v3;
+}
 function __wbg_get_imports() {
     const import0 = {
         __proto__: null,
@@ -417,7 +659,7 @@ function __wbg_get_imports() {
             return ret;
         },
         __wbindgen_cast_0000000000000001: function(arg0, arg1) {
-            // Cast intrinsic for `Closure(Closure { owned: true, function: Function { arguments: [Externref], shim_idx: 23, ret: Result(Unit), inner_ret: Some(Result(Unit)) }, mutable: true }) -> Externref`.
+            // Cast intrinsic for `Closure(Closure { owned: true, function: Function { arguments: [Externref], shim_idx: 30, ret: Result(Unit), inner_ret: Some(Result(Unit)) }, mutable: true }) -> Externref`.
             const ret = makeMutClosure(arg0, arg1, wasm_bindgen_d6cb7d81ec28c0ae___convert__closures_____invoke___wasm_bindgen_d6cb7d81ec28c0ae___JsValue__core_f0fd674eaa06beef___result__Result_____wasm_bindgen_d6cb7d81ec28c0ae___JsError___true_);
             return ret;
         },

package/package.json

@@ -2,7 +2,7 @@
   "name": "@emu198x/zx-spectrum",
   "type": "module",
   "description": "ZX Spectrum in the browser, published to npm as @emu198x/zx-spectrum",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "license": "SEE LICENSE IN README.md",
   "repository": {
     "type": "git",