@specy/x86 2.0.5 → 2.2.1

package/LICENSE.md

@@ -0,0 +1,39 @@
+ISC License
+
+Copyright 2022 Justine Alexandra Roberts Tunney
+Copyright 2024 Alberto Ventafridda
+Copyright 2026 Specy
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
+REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
+AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
+INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
+LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
+OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
+PERFORMANCE OF THIS SOFTWARE.
+
+---
+
+The three notices above are all carried by this package. The wrapper is the
+work of Specy; `dist/index.mjs` inlines blink compiled to WebAssembly, which
+is the work of Justine Tunney (https://github.com/jart/blink) as extended by
+Alberto Ventafridda's libblink target. All three are under the ISC license
+above.
+
+## Bundled binaries
+
+`dist/assets/assemblers` holds static x86-64 executables that the emulator
+runs as guest programs. They are separate works under their own licenses,
+which the ISC license above does not cover:
+
+- `nasm.3.00.elf` - NASM 3.00, 2-clause BSD.
+  https://www.nasm.us
+- `gnu-as.2.43.50.elf`, `gnu-ld.2.43.50.elf` - GNU Binutils 2.43.50, GPL-3.0
+  or later. https://sourceware.org/binutils
+- `fasm.1.73.32.elf` - flat assembler 1.73.32, Copyright (c) 1999-2022 Tomasz
+  Grysztar, under its own permissive license.
+  https://flatassembler.net

package/README.md

@@ -1,117 +1,117 @@
-# @specy/x86
-
-TypeScript wrapper around the [blink](https://github.com/jart/blink) x86-64 emulator, compiled to WebAssembly via Emscripten.
-
-## Usage
-
-```ts
-import { createX86Emulator } from '@specy/x86'
-
-const emulator = await createX86Emulator({
-  callbacks: {
-    stdout: (charCode) => process.stdout.write(String.fromCharCode(charCode)),
-    stderr: (charCode) => process.stderr.write(String.fromCharCode(charCode)),
-  },
-})
-
-const result = await emulator.compile(`
-global _start
-section .text
-_start:
-  mov rax, 60
-  xor rdi, rdi
-  syscall
-`)
-
-if (result.ok) {
-  await emulator.runUntilBlocked()
-  console.log(emulator.stopReason)
-}
-```
-
-`createX86Emulator()` initializes and awaits the wasm module internally; no wasm URL or byte buffer needs to be passed by the caller. NASM is the default assembler; pass `mode: 'GNU_trunk'` to use GNU as instead.
-
-### Compile and run
-
-```ts
-// Assemble and link source, returns { ok, errors }
-const result = await emulator.compile(sourceCode)
-
-// Run until a breakpoint, syscall block, or instruction limit is hit
-await emulator.run(limit, breakpoints)
-
-// Convenience wrapper — runs with no limit and no breakpoints
-await emulator.runUntilBlocked()
-```
-
-`run(limit, breakpoints)` accepts an optional maximum instruction count and an array of 0-based source-line breakpoint indices. Breakpoints are resolved to native instruction addresses using the DWARF line information emitted by the assembler.
-
-### Check code without running
-
-```ts
-// Assembles and links but does not execute; updates the loaded program
-const result = await emulator.checkCode(sourceCode)
-```
-
-### Read registers and memory
-
-```ts
-const rax = emulator.getRegisterValue('rax')
-const bytes = emulator.readMemoryBytes(address, length)
-```
-
-### Undo history and call stack
-
-Undo recording is opt-in. Call `initialize(undoSize)` after loading or compiling a program and before execution. `undoSize` is the maximum number of reversible instructions kept in history; internally this is a fixed-size circular buffer, so older entries are discarded when the buffer fills.
-
-```ts
-const result = await emulator.compile(sourceCode)
-if (!result.ok) throw new Error(result.errors[0]?.error ?? 'Assembly failed')
-
-// Keep the last 128 reversible instructions.
-emulator.initialize(128)
-
-await emulator.step()
-await emulator.step()
-
-const [latestStep] = emulator.getUndoHistory(1)
-console.log(latestStep?.pc, latestStep?.mutations)
-
-if (emulator.canUndo()) {
-  emulator.undo()
-}
-```
-
-History entries include register writes, memory writes, flag changes, and call-stack mutations. `getUndoHistory(max)` returns the newest entries first, as `ExecutionStep[]`, which is useful for instruction-history UIs.
-
-```ts
-for (const step of emulator.getUndoHistory(10)) {
-  console.log(step.pc, step.mutations)
-}
-```
-
-The call stack is tracked while history recording is enabled. Calls push frames and returns pop them; undo restores the previous call-stack snapshot along with registers, flags, PC, SP, and captured memory bytes.
-
-```ts
-emulator.initialize(64)
-await emulator.run(20)
-
-const frames = emulator.getCallStack()
-console.log(frames.map((frame) => frame.name))
-```
-
-When history is enabled, `run()` uses traced stepping so each executed instruction can be undone. If history is disabled with `initialize(0)` or by never calling `initialize`, normal fast execution remains available and `canUndo()` returns `false`.
-
-Very large or truncated memory writes may not be reversible. In that case `canUndo()` returns `false` for the latest step, and calling `undo()` throws instead of restoring a partial state.
-
-### Events
-
-```ts
-emulator.on('stateChange', (state) => { /* ... */ })
-emulator.on('stdout',      (charCode) => { /* ... */ })
-emulator.on('stderr',      (charCode) => { /* ... */ })
-emulator.on('signal',      (signal)   => { /* ... */ })
-emulator.on('inputRequest', ()        => { /* ... */ })
-```
-
-Callbacks passed to `createX86Emulator()` and handlers registered with `on()` may return either `void` or `Promise<void>`. Async callbacks are observed but not awaited by the emulator, so UI work can be scheduled without blocking execution. `stdin` remains synchronous because it is called directly by Emscripten's filesystem; for non-blocking UI input, listen for `inputRequest` and call `provideInput()` when the user submits text.
+# @specy/x86
+
+TypeScript wrapper around the [blink](https://github.com/jart/blink) x86-64 emulator, compiled to WebAssembly via Emscripten.
+
+## Usage
+
+```ts
+import { createX86Emulator } from '@specy/x86'
+
+const emulator = await createX86Emulator({
+  callbacks: {
+    stdout: (charCode) => process.stdout.write(String.fromCharCode(charCode)),
+    stderr: (charCode) => process.stderr.write(String.fromCharCode(charCode)),
+  },
+})
+
+const result = await emulator.compile(`
+global _start
+section .text
+_start:
+  mov rax, 60
+  xor rdi, rdi
+  syscall
+`)
+
+if (result.ok) {
+  await emulator.runUntilBlocked()
+  console.log(emulator.stopReason)
+}
+```
+
+`createX86Emulator()` initializes and awaits the wasm module internally; no wasm URL or byte buffer needs to be passed by the caller. NASM is the default assembler; pass `mode: 'GNU_trunk'` to use GNU as instead.
+
+### Compile and run
+
+```ts
+// Assemble and link source, returns { ok, errors }
+const result = await emulator.compile(sourceCode)
+
+// Run until a breakpoint, syscall block, or instruction limit is hit
+await emulator.run(limit, breakpoints)
+
+// Convenience wrapper — runs with no limit and no breakpoints
+await emulator.runUntilBlocked()
+```
+
+`run(limit, breakpoints)` accepts an optional maximum instruction count and an array of 0-based source-line breakpoint indices. Breakpoints are resolved to native instruction addresses using the DWARF line information emitted by the assembler.
+
+### Check code without running
+
+```ts
+// Assembles and links but does not execute; updates the loaded program
+const result = await emulator.checkCode(sourceCode)
+```
+
+### Read registers and memory
+
+```ts
+const rax = emulator.getRegisterValue('rax')
+const bytes = emulator.readMemoryBytes(address, length)
+```
+
+### Undo history and call stack
+
+Undo recording is opt-in. Call `initialize(undoSize)` after loading or compiling a program and before execution. `undoSize` is the maximum number of reversible instructions kept in history; internally this is a fixed-size circular buffer, so older entries are discarded when the buffer fills.
+
+```ts
+const result = await emulator.compile(sourceCode)
+if (!result.ok) throw new Error(result.errors[0]?.error ?? 'Assembly failed')
+
+// Keep the last 128 reversible instructions.
+emulator.initialize(128)
+
+await emulator.step()
+await emulator.step()
+
+const [latestStep] = emulator.getUndoHistory(1)
+console.log(latestStep?.pc, latestStep?.mutations)
+
+if (emulator.canUndo()) {
+  emulator.undo()
+}
+```
+
+History entries include register writes, memory writes, flag changes, and call-stack mutations. `getUndoHistory(max)` returns the newest entries first, as `ExecutionStep[]`, which is useful for instruction-history UIs.
+
+```ts
+for (const step of emulator.getUndoHistory(10)) {
+  console.log(step.pc, step.mutations)
+}
+```
+
+The call stack is tracked while history recording is enabled. Calls push frames and returns pop them; undo restores the previous call-stack snapshot along with registers, flags, PC, SP, and captured memory bytes.
+
+```ts
+emulator.initialize(64)
+await emulator.run(20)
+
+const frames = emulator.getCallStack()
+console.log(frames.map((frame) => frame.name))
+```
+
+When history is enabled, `run()` uses traced stepping so each executed instruction can be undone. If history is disabled with `initialize(0)` or by never calling `initialize`, normal fast execution remains available and `canUndo()` returns `false`.
+
+Very large or truncated memory writes may not be reversible. In that case `canUndo()` returns `false` for the latest step, and calling `undo()` throws instead of restoring a partial state.
+
+### Events
+
+```ts
+emulator.on('stateChange', (state) => { /* ... */ })
+emulator.on('stdout',      (charCode) => { /* ... */ })
+emulator.on('stderr',      (charCode) => { /* ... */ })
+emulator.on('signal',      (signal)   => { /* ... */ })
+emulator.on('inputRequest', ()        => { /* ... */ })
+```
+
+Callbacks passed to `createX86Emulator()` and handlers registered with `on()` may return either `void` or `Promise<void>`. Async callbacks are observed but not awaited by the emulator, so UI work can be scheduled without blocking execution. `stdin` remains synchronous because it is called directly by Emscripten's filesystem; for non-blocking UI input, listen for `inputRequest` and call `provideInput()` when the user submits text.