@frotzinc/zmachine 0.0.0-stage → 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,21 @@
+# Changelog
+
+All notable changes to `@frotzinc/zmachine`. Versions follow [Semantic Versioning](https://semver.org/). Part of [Frotz, Inc.](https://frotzinc.com).
+
+## [0.1.0] - 2026-11-07
+
+The first release: the interpreter behind frotzplay. (On npm once published.)
+
+### Added
+- **Saves (Phase 2, [docs/12](../../docs/12-frotzplay-phase-2-state.md)):** `@save` and `@restore` stop for the host (`save` with a Quetzal 1.4 file, `restore`), finished with `resume({ saved })` / `resume({ restore })`. Saves are byte-compatible with ZVM's; a bad file is a `bad-save` notice in words and a failed restore. `readQuetzal`/`writeQuetzal` exported. `play()` takes `files`.
+- **Snapshots:** `machine.snapshot()` and `Machine.fromSnapshot(story, snapshot, options)`, the whole machine as plain data.
+- **Conformance:** Czech 0.8 (v3/4/5/8) and Praxix, compiled at test time, pass and match ZVM.
+- `header.standard` (default 1.1).
+
+### Fixed
+- `@print_char 0` prints nothing in any stream (§3.8.2.1); it was written into stream 3.
+- The interpreter (frotzplay Phase 1, [docs/11](../../docs/11-frotzplay-phase-1-interpreter.md)): every opcode of versions 3, 4, 5 and 8, run from `@frotzinc/zcode`'s decoded instructions; the §8 screen model as data; line, character and timed input that suspends the machine; ZVM-compatible seeded random; undo; hooks on writes, calls, returns, branches, prints and input; faults instead of exceptions.
+- `play(story, commands, options)` and the `zmachine-run` command: normalized transcripts, turn by turn.
+- Differential tests against ZVM: every sample, every version built (v3, v4, v5, v8), played through with its walkthrough under two seeds, gives the same transcript; the same header.
+- Opcode tests with a small test assembler: every rule-6 item named and cited; every opcode of every version run (a coverage test).
+- Command scripts: `[timeout]` (a timed read's interval ran out) and `[key x]` (a key for `@read_char`); timed input tested with a compiled Inform 6 fixture.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Christopher Schweda
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,33 @@
-# Temporary Holding Version
+# @frotzinc/zmachine
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A Z-machine interpreter for versions 3, 4, 5 and 8, in TypeScript. It runs decoded instructions one at a time (no `eval`, no JIT, so it runs under a strict Content-Security-Policy), keeps all its state as plain data, and stops whenever it needs input, so the host decides how input arrives. No DOM: it runs in a browser, a Web Worker, or Node. The interpreter behind [frotzplay](../../apps/play).
+
+> **Status: in development** (frotzplay Phase 1). Not yet on npm.
+
+```ts
+import { Machine } from '@frotzinc/zmachine'
+
+const m = Machine.create(storyBytes, { seed: 1 })
+if (!(m instanceof Machine)) throw new Error(m.fault.message)
+
+let stop = m.run(100_000)
+// stop.kind: 'input-line' | 'input-char' | 'budget' (call run again) | 'quit' | 'fault'
+console.log(m.flushText())
+m.resume({ line: 'look' })
+stop = m.run(100_000)
+```
+
+Or from a terminal: `zmachine-run story.z5 script.txt [--seed N]` prints each turn's text. A script is one command per line (`!` starts a comment); `[timeout]` means a timed read's interval ran out, and `[key x]` presses a key for `@read_char` (`[key]` is Return), so a recorded session with its timer events replays exactly.
+
+## Conformance
+
+The Z-Machine Standards Document 1.1, versions 3, 4, 5 and 8, checked against [ZVM](https://github.com/curiousdannii/ifvms.js) (Parchment's engine) on every sample story: the same story, commands and seed give the same transcript. Deliberate choices:
+
+- **Random numbers** follow ZVM, not the Standard's suggested "predictable" mode for small seeds (§2.4.1, a recommendation ZVM doesn't follow either): seeded play draws from a mulberry32 stream where ZVM would use `Math.random`, and `@random -n` switches to ZVM's own xorshift.
+- **Version 6**, sound beyond beeps, and font 3 are not supported.
+
+## Standing on
+
+The [Z-Machine Standards Document](https://inform-fiction.org/zmachine/standards/) (Graham Nelson, Andrew Hunter and contributors); [ZVM / ifvms.js](https://github.com/curiousdannii/ifvms.js) by Dannii Willis, the test oracle, whose xorshift `@random` is copied here with attribution (MIT).
+
+MIT. From [Frotz, Inc.](https://frotzinc.com).

package/bin/run.mjs

@@ -0,0 +1,35 @@
+#!/usr/bin/env node
+/**
+ * Play a story from a command script and print each turn's normalized text:
+ *   zmachine-run story.z5 script.txt [--seed N] [--zvm]
+ * The script is one command per line (or several separated by '.'); '!' lines are comments.
+ * --zvm writes the header exactly as ZVM does (for comparing with it).
+ */
+import { readFileSync } from 'node:fs'
+import { play } from '../dist/index.js'
+
+const args = process.argv.slice(2)
+const flag = name => {
+  const i = args.indexOf(name)
+  return i >= 0 ? args.splice(i, 2)[1] : undefined
+}
+const seed = Number(flag('--seed') ?? 1)
+const zvm = args.includes('--zvm')
+const [storyPath, scriptPath] = args.filter(a => !a.startsWith('--'))
+if (!storyPath) {
+  console.error('usage: zmachine-run story.z5 [script.txt] [--seed N] [--zvm]')
+  process.exit(2)
+}
+const commands = scriptPath
+  ? readFileSync(scriptPath, 'utf8').split('\n').map(l => l.trim()).filter(l => l && !l.startsWith('!')).flatMap(l => l.split('.')).map(c => c.trim().replace(/^>\s*/, '')).filter(Boolean)
+  : []
+const result = play(new Uint8Array(readFileSync(storyPath)), commands, { seed, header: zvm ? { profile: 'zvm' } : {} })
+for (const t of result.turns) {
+  if (t.command) console.log(`> ${t.command}`)
+  console.log(t.output)
+  console.log()
+}
+if (result.stoppedBy && typeof result.stoppedBy === 'object') {
+  console.error(`stopped: ${result.stoppedBy.code}: ${result.stoppedBy.message}`)
+  process.exit(1)
+}

package/dist/fault.d.ts

@@ -0,0 +1,9 @@
+import type { Fault, FaultCode } from './types.js';
+/** Thrown inside the package only; run() turns it into a `fault` stop. Never escapes. */
+export declare class MachineFault extends Error {
+    readonly code: FaultCode;
+    constructor(code: FaultCode, message: string);
+    toFault(pc: number): Fault;
+}
+export declare const fail: (code: FaultCode, message: string) => never;
+export declare const hex: (n: number, width?: number) => string;

package/dist/fault.js

@@ -0,0 +1,16 @@
+/** Thrown inside the package only; run() turns it into a `fault` stop. Never escapes. */
+export class MachineFault extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+    }
+    toFault(pc) {
+        return { code: this.code, message: this.message, pc };
+    }
+}
+export const fail = (code, message) => {
+    throw new MachineFault(code, message);
+};
+export const hex = (n, width = 4) => '0x' + n.toString(16).padStart(width, '0');
+//# sourceMappingURL=fault.js.map

package/dist/fault.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fault.js","sourceRoot":"","sources":["../src/fault.ts"],"names":[],"mappings":"AAEA,yFAAyF;AACzF,MAAM,OAAO,YAAa,SAAQ,KAAK;IAE1B;IADX,YACW,IAAe,EACxB,OAAe;QAEf,KAAK,CAAC,OAAO,CAAC,CAAA;QAHL,SAAI,GAAJ,IAAI,CAAW;IAI1B,CAAC;IAED,OAAO,CAAC,EAAU;QAChB,OAAO,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE,EAAE,EAAE,CAAA;IACvD,CAAC;CACF;AAED,MAAM,CAAC,MAAM,IAAI,GAAG,CAAC,IAAe,EAAE,OAAe,EAAS,EAAE;IAC9D,MAAM,IAAI,YAAY,CAAC,IAAI,EAAE,OAAO,CAAC,CAAA;AACvC,CAAC,CAAA;AAED,MAAM,CAAC,MAAM,GAAG,GAAG,CAAC,CAAS,EAAE,KAAK,GAAG,CAAC,EAAE,EAAE,CAAC,IAAI,GAAG,CAAC,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,KAAK,EAAE,GAAG,CAAC,CAAA"}

package/dist/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * @frotzinc/zmachine: a Z-machine interpreter for versions 3, 4, 5 and 8, in TypeScript. It runs
+ * decoded instructions one at a time (no eval, no JIT), keeps all its state as plain data, and
+ * stops for the host to supply input. No DOM; runs in a browser, a worker, or Node.
+ */
+export { Machine } from './machine.js';
+export { play, type PlayOptions, type PlayResult, type Turn } from './play.js';
+export { normalizeTurn } from './normalize.js';
+export { readQuetzal, writeQuetzal, type QuetzalState } from './quetzal.js';
+export { mulberry32, mulberry32Step, random } from './random.js';
+export type * from './types.js';

package/dist/index.js

@@ -0,0 +1,11 @@
+/**
+ * @frotzinc/zmachine: a Z-machine interpreter for versions 3, 4, 5 and 8, in TypeScript. It runs
+ * decoded instructions one at a time (no eval, no JIT), keeps all its state as plain data, and
+ * stops for the host to supply input. No DOM; runs in a browser, a worker, or Node.
+ */
+export { Machine } from './machine.js';
+export { play } from './play.js';
+export { normalizeTurn } from './normalize.js';
+export { readQuetzal, writeQuetzal } from './quetzal.js';
+export { mulberry32, mulberry32Step, random } from './random.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAA;AACtC,OAAO,EAAE,IAAI,EAAgD,MAAM,WAAW,CAAA;AAC9E,OAAO,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAA;AAC9C,OAAO,EAAE,WAAW,EAAE,YAAY,EAAqB,MAAM,cAAc,CAAA;AAC3E,OAAO,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,EAAE,MAAM,aAAa,CAAA"}

package/dist/machine.d.ts

@@ -0,0 +1,109 @@
+/**
+ * The Z-machine (Standard 1.1, versions 3, 4, 5 and 8): "apply this decoded Instruction to this
+ * state." zcode decodes; this executes, one instruction at a time, and stops for input, quit, a
+ * spent budget, or a fault. No DOM, no eval, no timers: the host drives it (docs/11).
+ *
+ * Section references (§) are to the Z-Machine Standards Document 1.1.
+ */
+import { type Version } from '@frotzinc/zcode';
+import type { Fault, InputValue, MachineOptions, MachineSnapshot, MachineState, StopReason } from './types.js';
+export declare class Machine {
+    readonly state: MachineState;
+    readonly version: Version;
+    private readonly story;
+    private readonly mem;
+    private readonly obj;
+    private readonly screen;
+    private readonly text;
+    private readonly hooks;
+    private readonly options;
+    private readonly cache;
+    private readonly globals;
+    private readonly dictionary;
+    /** Set by an instruction that ends run(): a read, quit. */
+    private stop;
+    /** The instruction being executed (for faults). */
+    private current;
+    private constructor();
+    /** A machine for `story`, or the reason it can't run one. Never throws. */
+    static create(story: Uint8Array, options: MachineOptions): Machine | {
+        fault: Fault;
+    };
+    private textContext;
+    /** What the interpreter writes into the header, at start, restart and restore. */
+    private writeHeader;
+    /** Run until input is needed, the game quits, `budget` instructions have run, or a fault. */
+    run(budget: number): StopReason;
+    /** One instruction. Null when the machine can go on. */
+    step(): StopReason | null;
+    private toFault;
+    private decode;
+    private waiting;
+    /** The most a text buffer takes, and any text already in it (v5+, §15 read). */
+    private lineLimits;
+    /** Give the machine what it's waiting for: a line, a key, or the news that a timed read's interval ran out. */
+    resume(input: InputValue): Fault | null;
+    /** The read an interrupt routine is running for. */
+    private interrupted;
+    private get frame();
+    private push;
+    private pop;
+    private peek;
+    private readVar;
+    private writeVar;
+    /** Indirect variable references (§6.3.4): variable 0 is the top of the stack, read or written in place. */
+    private readVarInPlace;
+    private writeVarInPlace;
+    private unpackRoutine;
+    private unpackString;
+    private callRoutine;
+    private ret;
+    private branch;
+    private store;
+    /** ZSCII codes to the active output streams. */
+    private print;
+    private printString;
+    /** @print_unicode: the character itself on the screen; ZSCII (or '?') into stream 3. */
+    private printUnicode;
+    private printNum;
+    private printObject;
+    /** Lower-window text since the last call: what the Node runner prints for a turn. */
+    flushText(): string;
+    /** v3: the status line, from globals 0–2 (§8.2.2). */
+    private showStatus;
+    private read;
+    private finishLine;
+    private finishChar;
+    /** An interrupt routine for a timed read returned `v` (§10.2.4). */
+    private afterInterrupt;
+    /** The words of a text buffer, looked up in a dictionary, into a parse buffer (§13.6). */
+    private tokenise;
+    private readonly dictionaries;
+    private dictionaryAt;
+    private readDictionary;
+    private storyId;
+    /** The machine as a Quetzal file, with `at` as the save instruction's store or branch byte. */
+    private quetzal;
+    /**
+     * Finish a save or restore whose result is `value` (§15 save/restore): v4+ store it at the store
+     * byte `at`; v3 branch on it from the branch byte(s) at `at`.
+     */
+    private completeSave;
+    /** Restore a Quetzal file; the reason in words when it can't be. */
+    private restoreQuetzal;
+    /** The whole machine as plain data. */
+    snapshot(): MachineSnapshot;
+    /** A machine in exactly the state of `snapshot`, or why it can't be (another story's). */
+    static fromSnapshot(story: Uint8Array, snapshot: MachineSnapshot, options: MachineOptions): Machine | {
+        fault: Fault;
+    };
+    private saveUndo;
+    private restoreUndo;
+    private restart;
+    private verify;
+    private copyTable;
+    private scanTable;
+    private printTable;
+    private execute;
+    private outputStream;
+}