@emu198x/zx-spectrum 0.2.0 → 0.3.0

package/emu198x_spectrum_web.d.ts

@@ -118,10 +118,32 @@ export class Spectrum {
      * parse.
      */
     loadSnapshot(bytes: Uint8Array, format: string): void;
+    mediaSlots(): string[];
     /**
      * The machine's media slots, for a page that wants to name one.
+     * Asks the machine a question, and hands back the answer as JSON.
+     *
+     * The same query surface the headless session and the MCP server use, so
+     * a page sees what a script sees rather than a browser-only subset. The
+     * paths a Spectrum answers include `cpu.pc`, `cpu.halted`, `cpu.iff1`,
+     * `cpu.instructions_retired`, `screen.text.lines`, `tape.playing` and
+     * `boot.detected`.
+     *
+     * This is what lets a lesson say *why* a machine stopped rather than
+     * offering a reset and moving on: a program that ran past its own last
+     * instruction has a `cpu.pc` outside the bytes it was assembled into, and
+     * one that halted with interrupts disabled is `cpu.halted` with
+     * `cpu.iff1` false. Both are mistakes a unit is teaching against.
+     *
+     * JSON rather than a native value: the answers are already JSON inside
+     * the query layer, and a page parses one string more cheaply than this
+     * crate grows a serialisation dependency.
+     *
+     * # Errors
+     *
+     * Returns a JavaScript error if the machine does not know the path.
      */
-    mediaSlots(): string[];
+    query(path: string): string;
     /**
      * Starts or stops machine audio.
      */
@@ -163,6 +185,7 @@ export interface InitOutput {
     readonly spectrum_load: (a: number, b: number, c: number, d: number, e: number, f: number, g: number) => [number, number];
     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_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];

package/emu198x_spectrum_web.js

@@ -214,7 +214,6 @@ export class Spectrum {
         }
     }
     /**
-     * The machine's media slots, for a page that wants to name one.
      * @returns {string[]}
      */
     mediaSlots() {
@@ -223,6 +222,52 @@ export class Spectrum {
         wasm.__wbindgen_free(ret[0], ret[1] * 4, 4);
         return v1;
     }
+    /**
+     * The machine's media slots, for a page that wants to name one.
+     * Asks the machine a question, and hands back the answer as JSON.
+     *
+     * The same query surface the headless session and the MCP server use, so
+     * a page sees what a script sees rather than a browser-only subset. The
+     * paths a Spectrum answers include `cpu.pc`, `cpu.halted`, `cpu.iff1`,
+     * `cpu.instructions_retired`, `screen.text.lines`, `tape.playing` and
+     * `boot.detected`.
+     *
+     * This is what lets a lesson say *why* a machine stopped rather than
+     * offering a reset and moving on: a program that ran past its own last
+     * instruction has a `cpu.pc` outside the bytes it was assembled into, and
+     * one that halted with interrupts disabled is `cpu.halted` with
+     * `cpu.iff1` false. Both are mistakes a unit is teaching against.
+     *
+     * JSON rather than a native value: the answers are already JSON inside
+     * the query layer, and a page parses one string more cheaply than this
+     * crate grows a serialisation dependency.
+     *
+     * # Errors
+     *
+     * Returns a JavaScript error if the machine does not know the path.
+     * @param {string} path
+     * @returns {string}
+     */
+    query(path) {
+        let deferred3_0;
+        let deferred3_1;
+        try {
+            const ptr0 = passStringToWasm0(path, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+            const len0 = WASM_VECTOR_LEN;
+            const ret = wasm.spectrum_query(this.__wbg_ptr, ptr0, len0);
+            var ptr2 = ret[0];
+            var len2 = ret[1];
+            if (ret[3]) {
+                ptr2 = 0; len2 = 0;
+                throw takeFromExternrefTable0(ret[2]);
+            }
+            deferred3_0 = ptr2;
+            deferred3_1 = len2;
+            return getStringFromWasm0(ptr2, len2);
+        } finally {
+            wasm.__wbindgen_free(deferred3_0, deferred3_1, 1);
+        }
+    }
     /**
      * Starts or stops machine audio.
      * @param {boolean} enabled
@@ -372,7 +417,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: 21, ret: Result(Unit), inner_ret: Some(Result(Unit)) }, mutable: true }) -> Externref`.
+            // 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`.
             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.2.0",
+  "version": "0.3.0",
   "license": "SEE LICENSE IN README.md",
   "repository": {
     "type": "git",