@specy/x86 1.1.0 → 2.0.1

package/README.md

@@ -1,184 +1,118 @@
-# X86 Interpreter
-[![npm](https://img.shields.io/npm/v/@specy/x86.svg)](https://www.npmjs.com/package/@specy/x86)
-
-A TypeScript library for x86 assembly interpretation, simulation, and debugging.
-
-## Overview
+# blink-js
+
+TypeScript wrapper around the [blink](https://github.com/jart/blink) x86-64 emulator, compiled to WebAssembly via Emscripten.
+
+## Usage
+
+```ts
+import { createX86Emulator } from 'blink-js'
+
+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(`
+.intel_syntax noprefix
+.global _start
+.text
+_start:
+  mov rax, 60
+  xor rdi, rdi
+  syscall
+`)
+
+if (result.ok) {
+  await emulator.runUntilBlocked()
+  console.log(emulator.stopReason)
+}
+```
 
-This library provides a JavaScript/TypeScript interface for interpreting and simulating x86 assembly code. It combines three powerful engines:
+`createX86Emulator()` initializes and awaits the wasm module internally; no wasm URL or byte buffer needs to be passed by the caller.
 
-- **[Unicorn.js](https://github.com/AlexAltea/unicorn.js)** - For CPU emulation
-- **[Keystone.js](https://github.com/AlexAltea/keystone.js)** - For assembly
-- **[Capstone.js](https://github.com/AlexAltea/capstone.js)** - For disassembly
+### Compile and run
 
-With this library, you can assemble, execute, and debug x86 instructions, manipulate registers and memory, and analyze program behavior at the instruction level.
+```ts
+// Assemble and link source, returns { ok, errors }
+const result = await emulator.compile(sourceCode)
 
-## Bundle size
-The library has a Gzipped bundle size of around 1.5MB, uncompressed is around 9MB
+// Run until a breakpoint, syscall block, or instruction limit is hit
+await emulator.run(limit, breakpoints)
 
-## Features
+// Convenience wrapper — runs with no limit and no breakpoints
+await emulator.runUntilBlocked()
+```
 
-- **Assembly/Disassembly**: Convert x86 assembly code to machine code and back
-- **Full Simulation**: Execute assembled code with configurable limits and breakpoints
-- **Register Access**: Read and write x86 registers (EAX, EBX, ECX, etc.)
-- **Memory Management**: Allocate, read, and write memory
-- **Debugging Support**: Single-step execution, breakpoints, and state inspection
-- **Flag Monitoring**: Track condition flags (carry, zero, sign, overflow, etc.)
+`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 GNU as.
 
-## Installation
+### Check code without running
 
-```bash
-npm install @specy/x86
+```ts
+// Assembles and links but does not execute; updates the loaded program
+const result = await emulator.checkCode(sourceCode)
 ```
 
-## Basic Usage
+### Read registers and memory
 
-```typescript
-import { X86Interpreter } from '@specy/x86';
+```ts
+const rax = emulator.getRegisterValue('rax')
+const bytes = emulator.readMemoryBytes(address, length)
+```
 
-// Create an interpreter with assembly code
-const code = `
-mov eax, 42
-add ebx, eax
-`;
+### Undo history and call stack
 
-// Create and initialize the interpreter
-const interpreter = X86Interpreter.create(code);
-interpreter.assemble();
-interpreter.initialize();
+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.
 
-// Execute the code
-interpreter.simulate();
+```ts
+const result = await emulator.compile(sourceCode)
+if (!result.ok) throw new Error(result.errors[0]?.error ?? 'Assembly failed')
 
-// Read results
-const eaxValue = interpreter.getRegisterValue(X86Register.EAX);
-const ebxValue = interpreter.getRegisterValue(X86Register.EBX);
+// Keep the last 128 reversible instructions.
+emulator.initialize(128)
 
-console.log(`EAX: ${eaxValue}, EBX: ${ebxValue}`);
+await emulator.step()
+await emulator.step()
 
-// Clean up resources
-interpreter.dispose();
-```
+const [latestStep] = emulator.getUndoHistory(1)
+console.log(latestStep?.pc, latestStep?.mutations)
 
-## Step-by-Step Debugging
-
-```typescript
-// Create and initialize
-const interpreter = X86Interpreter.create(assemblyCode);
-interpreter.assemble();
-interpreter.initialize();
-
-// Execute one instruction at a time
-while (!interpreter.isTerminated()) {
-  const instruction = interpreter.getNextStatement();
-  console.log(`Executing: ${instruction?.text}`);
-  
-  // Show register values
-  const eax = interpreter.getRegisterValue(X86Register.EAX);
-  console.log(`EAX: 0x${eax.toString(16)}`);
-  
-  // Execute one instruction
-  interpreter.step();
+if (emulator.canUndo()) {
+  emulator.undo()
 }
-
-interpreter.dispose();
 ```
 
-## Breakpoint Support
-
-```typescript
-// Set breakpoints at specific addresses
-const breakpoints = [0x1010, 0x1020];
-interpreter.simulateWithBreakpoints(breakpoints);
+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.
 
-// Program execution will pause at each breakpoint
-console.log("Execution paused at breakpoint");
-console.log(`PC: 0x${interpreter.getProgramCounter().toString(16)}`);
+```ts
+for (const step of emulator.getUndoHistory(10)) {
+  console.log(step.pc, step.mutations)
+}
 ```
 
-## Memory Access
-
-```typescript
-// Write bytes to memory
-const bytes = [0x90, 0x90, 0x90]; // NOP instructions
-interpreter.setMemoryBytes(0x2000, bytes);
-
-// Read memory content
-const memoryContent = interpreter.readMemoryBytes(0x2000, 3);
-console.log("Memory content:", memoryContent);
-```
+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.
 
-## Flag Inspection
+```ts
+emulator.initialize(64)
+await emulator.run(20)
 
-```typescript
-// After execution, check condition flags
-const flags = interpreter.getConditionFlags();
-console.log("Zero flag:", flags[X86ConditionFlags.Z]);
-console.log("Carry flag:", flags[X86ConditionFlags.C]);
+const frames = emulator.getCallStack()
+console.log(frames.map((frame) => frame.name))
 ```
 
-## API Reference
-
-### X86Interpreter Class
-
-The main class for x86 assembly interpretation and simulation.
-
-#### Constructor
-
-- `constructor(code: string, assembler: any, interpreter: any, disambler: any)`
-
-#### Static Methods
+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`.
 
-- `create(code: string): X86Interpreter` - Creates a new interpreter instance with the provided assembly code
+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.
 
-#### Methods
+### Events
 
-- `assemble(): void` - Assembles the code and prepares for interpretation
-- `initialize(): void` - Initializes memory and registers for the interpreter
-- `simulate(limit?: number): void` - Simulates the execution of the code
-- `simulateWithBreakpoints(breakpoints: number[], limit?: number): void` - Simulates execution with specified breakpoints
-- `step(): void` - Executes a single instruction
-- `getRegisterValue(register: X86Register): number` - Gets the value of a register
-- `setRegisterValue(register: X86Register, value: number): void` - Sets the value of a register
-- `getStackPointer(): number` - Gets the current stack pointer value
-- `getProgramCounter(): number` - Gets the current program counter value
-- `getRegistersValues(): number[]` - Gets the values of all registers
-- `readMemoryBytes(address: number, length: number): number[]` - Reads bytes from memory
-- `setMemoryBytes(address: number, bytes: number[]): void` - Writes bytes to memory
-- `getNextStatement(): X86Instruction | null` - Gets the next instruction to be executed
-- `isTerminated(): boolean` - Checks if the execution has terminated
-- `getConditionFlags(): Record<X86ConditionFlags, number>` - Gets the current state of all condition flags
-- `getStatementAtAddress(address: number): X86Instruction | null` - Gets the instruction at a specific address
-- `getStatementAtSourceLine(lineIndex: number): X86Instruction | null` - Gets the instruction at a specific source line
-- `getAssembledStatements(): X86Instruction[]` - Gets all disassembled instructions
-- `dispose(): void` - Releases resources used by the interpreter
-
-### Enums
-
-#### X86Register
-
-```typescript
-enum X86Register {
-    EAX = 19,
-    EBX = 21,
-    ECX = 22,
-    ESP = 30,
-    EBP = 20,
-    EDI = 23,
-    ESI = 29,
-    EDX = 24,
-}
+```ts
+emulator.on('stateChange', (state) => { /* ... */ })
+emulator.on('stdout',      (charCode) => { /* ... */ })
+emulator.on('stderr',      (charCode) => { /* ... */ })
+emulator.on('signal',      (signal)   => { /* ... */ })
+emulator.on('inputRequest', ()        => { /* ... */ })
 ```
 
-#### X86ConditionFlags
-
-```typescript
-enum X86ConditionFlags {
-    C = 0, // Carry flag
-    Z = 1, // Zero flag
-    S = 2, // Sign flag
-    O = 3, // Overflow flag
-    P = 4, // Parity flag
-    A = 5, // Auxiliary carry flag
-}
-```
+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.