@specy/x86 2.0.5 → 2.2.1

package/dist/index.d.mts

@@ -5,14 +5,290 @@ declare function toResourceUrl(source: string | URL): URL;
 declare function readResourceBytes(source: ResourceSource): Promise<Uint8Array>;
 declare function defaultResourceUrl(relativePath: string, baseUrl: string): URL;
 //#endregion
+//#region src/interface.d.ts
+type StatusRegister = {
+  name: string;
+  value: number;
+  prev: number;
+};
+type DiagnosticSeverity = 'error' | 'warning';
+type MonacoError = {
+  /** Project-relative source path when checking a virtual Project. */file?: string;
+  lineIndex: number;
+  column: number;
+  line: {
+    line: string;
+    line_index: number;
+  };
+  message: string;
+  formatted: string; /** A warning still assembles; only an error stops the build. Absent means error. */
+  severity?: DiagnosticSeverity; /** The assembler's own name for the warning, such as `label-orphan`. */
+  code?: string; /** Help beyond what the assembler said, when this diagnostic has a known explanation. */
+  hint?: string;
+};
+type StackFrame = {
+  name: string;
+  address: bigint;
+  destination: bigint;
+  sp: bigint;
+  line: number;
+  file?: string;
+  color: string;
+};
+type RegisterHex = [hi: string, lo: string];
+declare enum RegisterSize {
+  Byte = 1,
+  Word = 2,
+  Long = 4,
+  Double = 8
+}
+type ExecutionStep = {
+  mutations: MutationOperation[];
+  pc: number;
+  old_ccr: {
+    bits: number;
+  };
+  new_ccr: {
+    bits: number;
+  };
+  line: number;
+  file?: string;
+};
+type MutationOperation = {
+  type: 'WriteRegister';
+  value: {
+    register: string;
+    old: bigint;
+    size: RegisterSize;
+  };
+} | {
+  type: 'WriteMemory';
+  value: {
+    address: bigint;
+    old: bigint;
+    size: RegisterSize;
+  };
+} | {
+  type: 'WriteMemoryBytes';
+  value: {
+    address: bigint;
+    old: number[];
+  };
+} | {
+  type: 'PopCallStack';
+  value: {
+    to: bigint;
+    from: bigint;
+  };
+} | {
+  type: 'PushCallStack';
+  value: {
+    to: bigint;
+    from: bigint;
+  };
+} | {
+  type: 'Other';
+  value: string;
+};
+type EmulatorDecoration = {
+  type: 'below-line';
+  note?: string;
+  belowLine: number;
+  md: string;
+};
+type CompilationError = {
+  type: 'raw';
+  message: string;
+};
+declare enum EmulatorStatus {
+  Terminated = 0,
+  Running = 1,
+  WaitingForInput = 2,
+  NotReady = 3
+}
+type Instruction = {
+  address: bigint;
+  lineNumber: number;
+  file?: string;
+  size?: number;
+  bytes?: Uint8Array;
+  code: string;
+};
+type EmulatorConfig<R extends string> = {
+  systemSize: RegisterSize;
+  registerNames: R[];
+  endianness?: 'little' | 'big';
+  hiddenRegisters?: R[];
+};
+declare abstract class BaseEmulator<T, R extends string, CompileResult = {
+  ok: true;
+} | {
+  ok: false;
+  errors: CompilationError[];
+  report: string;
+}> {
+  protected _registerNames: R[];
+  protected _systemSize: RegisterSize;
+  protected _endianness: 'little' | 'big';
+  constructor(options: EmulatorConfig<R>);
+  getSystemSize(): RegisterSize;
+  getEndianness(): 'little' | 'big';
+  getRegisterNames(): R[];
+  abstract initialize(undoSize: number): void;
+  abstract getCompiledCode(): {
+    decorations: EmulatorDecoration[];
+    code: string;
+  };
+  abstract dispose(): void;
+  abstract stringifyError(error: unknown): string;
+  abstract compile(code: string): Promise<CompileResult>;
+  abstract checkCode(code: string): Promise<MonacoError[]>;
+  abstract undo(): void;
+  abstract canUndo(): boolean;
+  abstract step(): Promise<{
+    terminated: boolean;
+  }>;
+  abstract getStatus(): EmulatorStatus;
+  abstract writeMemoryBytes(address: bigint, data: Uint8Array): void;
+  abstract readMemoryBytes(address: bigint, length: bigint): Uint8Array;
+  abstract getNextInstruction(): Instruction | null;
+  abstract getUndoHistory(max: number): ExecutionStep[];
+  abstract getPc(): bigint;
+  abstract getSp(): bigint;
+  abstract getFlags(): {
+    name: string;
+    value: number;
+    prev?: number;
+  }[];
+  abstract getCallStack(): StackFrame[];
+  abstract getInstructionAt(address: bigint): Instruction | null;
+  abstract getRegisterValues(): bigint[];
+  abstract getRegisterValuesRecord(): Record<R, bigint>;
+  abstract getRegisterValue(register: R, size?: RegisterSize): bigint;
+  abstract setRegisterValue(register: R, value: bigint, size?: RegisterSize): void;
+  abstract hasTerminated(): boolean;
+  abstract run(limit?: number, breakpoints?: Array<number | {
+    path: string;
+    line: number;
+  }>): Promise<EmulatorStatus>;
+}
+//#endregion
+//#region src/callbacks.d.ts
+type MaybePromise<T> = T | PromiseLike<T>;
+declare function observeCallbackResult(result: MaybePromise<void>): void;
+//#endregion
+//#region src/types.d.ts
+declare const X86_REGISTER_NAMES: readonly ["rax", "rbx", "rcx", "rdx", "rsp", "rbp", "rsi", "rdi", "r8", "r9", "r10", "r11", "r12", "r13", "r14", "r15", "rip"];
+type X86RegisterName = (typeof X86_REGISTER_NAMES)[number];
+declare enum BlinkState {
+  NotReady = "NOT_READY",
+  Ready = "READY",
+  Assembling = "ASSEMBLING",
+  Linking = "LINKING",
+  ProgramLoaded = "PROGRAM_LOADED",
+  ProgramRunning = "PROGRAM_RUNNING",
+  ProgramPaused = "PROGRAM_PAUSED",
+  ProgramReadlinePause = "PROGRAM_READLINE_PAUSE",
+  ProgramStopped = "PROGRAM_STOPPED"
+}
+type StopReasonKind = 'exit' | 'signal' | 'input' | 'limit' | 'breakpoint' | 'load-fail';
+type StopReason = {
+  loadFail: boolean;
+  exitCode: number;
+  details: string;
+  kind?: StopReasonKind;
+  address?: bigint;
+  lineNumber?: number;
+  file?: string;
+  executedInstructions?: bigint;
+};
+type X86CompilationDiagnostic = {
+  line: number;
+  error: string; /** Project-relative source path when compiling a virtual Project. */
+  file?: string; /** A warning still assembles; only an error stops the build. */
+  severity: DiagnosticSeverity; /** The assembler's own name for the warning, such as `label-orphan`. */
+  warningClass?: string;
+};
+type X86ProjectFile = string | Uint8Array;
+type X86Project = {
+  entry: string;
+  files: Readonly<Record<string, X86ProjectFile>>;
+};
+type X86SourceLocation = {
+  path: string; /** Zero-based source line. */
+  line: number;
+};
+type X86Breakpoint = number | X86SourceLocation;
+/**
+ * `diagnostics` carries everything the assembler said, warnings included - a
+ * successful build routinely has some, and they are the most useful thing it
+ * produces. `errors` is the subset that stopped the build.
+ */
+type X86CompileResult = {
+  ok: true;
+  report: string;
+  diagnostics: X86CompilationDiagnostic[];
+} | {
+  ok: false;
+  errors: X86CompilationDiagnostic[];
+  report: string;
+  diagnostics: X86CompilationDiagnostic[];
+};
+type X86EmulatorEventMap = {
+  stateChange: {
+    state: BlinkState;
+    oldState: BlinkState;
+  };
+  stdout: number;
+  stderr: number;
+  signal: {
+    signal: number;
+    code: number;
+  };
+  inputRequest: {
+    maxBytes: bigint;
+  };
+};
+type X86EmulatorEventName = keyof X86EmulatorEventMap;
+type X86EmulatorEventHandler<T extends X86EmulatorEventName> = (event: X86EmulatorEventMap[T]) => MaybePromise<void>;
+//#endregion
+//#region src/wasm-assembler.d.ts
+/**
+ * An assembler that runs as its own WebAssembly module rather than as an x86-64
+ * ELF interpreted by blink. Blink costs roughly 1.2s of startup plus 14ms per
+ * line of source for NASM; the same work in its own module takes single-digit
+ * milliseconds, and produces byte-identical output.
+ *
+ * The object file comes back as bytes for the caller to stage wherever the
+ * linker expects it, so the linker can keep running inside blink unchanged.
+ */
+interface WasmAssembler {
+  assemble(project: X86Project): Promise<WasmAssemblyResult>;
+}
+type WasmAssemblyResult = {
+  /** The assembler's exit status: 0 when it wrote an object file. */status: number; /** What it wrote to stdout, verbatim. */
+  stdout: string; /** What it wrote to stderr, verbatim - the diagnostics a parser reads. */
+  stderr: string; /** The object file, or null when the assembly failed. */
+  object: Uint8Array | null;
+};
+//#endregion
 //#region src/assemblers.d.ts
 interface Binary {
   file: ResourceSource;
   commands: string;
 }
 interface DiagnosticLine {
+  file?: string;
   line: number;
   error: string;
+  /** A warning still assembles; only an error stops the build. */
+  severity: DiagnosticSeverity;
+  /**
+   * NASM's own name for the warning, taken from the `[-w+label-orphan]` tag it
+   * appends. It is a stable identifier for the kind of mistake, which is what
+   * an explanation can be keyed on.
+   */
+  warningClass?: string;
 }
 type DiagnosticsParser = (assemblerLogs: string) => DiagnosticLine[];
 interface AssemblerMode {
@@ -21,9 +297,17 @@ interface AssemblerMode {
   description: string;
   diagnosticsParser?: DiagnosticsParser;
   binaries: {
-    assembler: Binary;
+    /**
+     * The assembler as an x86-64 ELF for blink to interpret. Absent when
+     * `wasmAssembler` is set, which runs the assembler as its own module
+     * instead - far faster, but only possible for an assembler written in
+     * portable C. Fasm is written in x86 assembly and has no such build.
+     */
+    assembler?: Binary;
     linker?: Binary;
   };
+  /** Runs outside blink, and takes precedence over `binaries.assembler`. */
+  wasmAssembler?: WasmAssembler;
 }
 declare const assemblers: {
   GNU_trunk: {
@@ -60,15 +344,12 @@ declare const assemblers: {
     description: string;
     diagnosticsParser: typeof nasmDiagnostics;
     binaries: {
-      assembler: {
-        file: URL;
-        commands: string;
-      };
       linker: {
         file: URL;
         commands: string;
       };
     };
+    wasmAssembler: WasmAssembler;
   };
 };
 type AssemblerId = keyof typeof assemblers;
@@ -76,64 +357,16 @@ declare const DEFAULT_ASSEMBLER_ID: AssemblerId;
 declare function nasmDiagnostics(str: string): DiagnosticLine[];
 declare function gnuDiagnostics(str: string): DiagnosticLine[];
 declare function fasmDiagnostics(str: string): DiagnosticLine[];
-//#endregion
-//#region src/callbacks.d.ts
-type MaybePromise<T> = T | PromiseLike<T>;
-declare function observeCallbackResult(result: MaybePromise<void>): void;
-//#endregion
-//#region src/types.d.ts
-declare const X86_REGISTER_NAMES: readonly ["rax", "rbx", "rcx", "rdx", "rsp", "rbp", "rsi", "rdi", "r8", "r9", "r10", "r11", "r12", "r13", "r14", "r15", "rip"];
-type X86RegisterName = (typeof X86_REGISTER_NAMES)[number];
-declare enum BlinkState {
-  NotReady = "NOT_READY",
-  Ready = "READY",
-  Assembling = "ASSEMBLING",
-  Linking = "LINKING",
-  ProgramLoaded = "PROGRAM_LOADED",
-  ProgramRunning = "PROGRAM_RUNNING",
-  ProgramPaused = "PROGRAM_PAUSED",
-  ProgramReadlinePause = "PROGRAM_READLINE_PAUSE",
-  ProgramStopped = "PROGRAM_STOPPED"
-}
-type StopReasonKind = 'exit' | 'signal' | 'input' | 'limit' | 'breakpoint' | 'load-fail';
-type StopReason = {
-  loadFail: boolean;
-  exitCode: number;
-  details: string;
-  kind?: StopReasonKind;
-  address?: bigint;
-  lineNumber?: number;
-  executedInstructions?: bigint;
-};
-type X86CompilationDiagnostic = {
-  line: number;
-  error: string;
-};
-type X86CompileResult = {
-  ok: true;
-  report: string;
-} | {
-  ok: false;
-  errors: X86CompilationDiagnostic[];
-  report: string;
-};
-type X86EmulatorEventMap = {
-  stateChange: {
-    state: BlinkState;
-    oldState: BlinkState;
-  };
-  stdout: number;
-  stderr: number;
-  signal: {
-    signal: number;
-    code: number;
-  };
-  inputRequest: {
-    maxBytes: bigint;
-  };
-};
-type X86EmulatorEventName = keyof X86EmulatorEventMap;
-type X86EmulatorEventHandler<T extends X86EmulatorEventName> = (event: X86EmulatorEventMap[T]) => MaybePromise<void>;
+/**
+ * The one-based column a diagnostic belongs on. NASM reports a line and no
+ * column, but it names the thing it is complaining about: `msg' in "symbol
+ * `msg' not defined", `.data' in a section warning. Finding that name in the
+ * line turns a whole-line squiggle into one under the mistake itself.
+ *
+ * Falls back to the first column, which is what the caller would have used
+ * anyway, so a message that names nothing findable is no worse off.
+ */
+declare function locateDiagnosticColumn(message: string, line: string, warningClass?: string): number;
 //#endregion
 //#region src/wasm-types.d.ts
 type EmscriptenFS = {
@@ -146,6 +379,9 @@ type EmscriptenFS = {
   readFile(path: string, options?: {
     encoding?: 'binary' | 'utf8';
   }): Uint8Array | string;
+  mkdirTree(path: string): void;
+  unlink(path: string): void;
+  chdir(path: string): void;
 };
 type BlinkenlibModuleOptions = {
   noInitialRun?: boolean;
@@ -275,21 +511,62 @@ declare class BlinkRuntime {
   state: BlinkState;
   stopReason: StopReason | null;
   assemblerLogs: string;
-  assemblerErrors: Array<{
-    line: number;
-    error: string;
-  }>;
+  /** The subset of `assemblerDiagnostics` that stopped the build. */
+  assemblerErrors: X86CompilationDiagnostic[];
+  /** Everything the assembler said, warnings included. */
+  assemblerDiagnostics: X86CompilationDiagnostic[];
   private readonly callbacks;
   private readonly scheduler;
   private readonly stateWaiters;
   private readonly stdinBytes;
   private sourceMap;
+  private sourceProject;
+  private assembleOnly;
+  private assembledObject;
   private readonly defaultArgc;
   private readonly defaultArgv;
   private constructor();
   static create(options?: BlinkRuntimeOptions): Promise<BlinkRuntime>;
   setMode(mode: AssemblerMode | AssemblerId): Promise<void>;
   compileAssembly(code: string): Promise<X86CompileResult>;
+  compileProject(project: X86Project): Promise<X86CompileResult>;
+  /**
+   * Assembles without linking, for diagnostics. The linked executable is only
+   * needed to run or debug a program; a caller that just wants to know what is
+   * wrong with the source pays ~450ms for a link it never looks at.
+   *
+   * A mode with a `wasmAssembler` never touches blink here, so checking also
+   * leaves a loaded program - and anything paused in the debugger - alone.
+   */
+  checkProject(project: X86Project): Promise<X86CompileResult>;
+  private checkProjectWithWasmAssembler;
+  private buildProject;
+  /**
+   * The object this build's assembler wrote, for the checks that read it
+   * rather than the assembler's own words. Null when the assembly failed, and
+   * when the assembler writes an executable directly and never produces one.
+   * Read once per build, so a previous build's object can never stand in for
+   * one that was never written.
+   */
+  private takeAssembledObject;
+  /**
+   * Nothing in the toolchain treats a missing entry point as a failure: NASM
+   * has no opinion on it and `ld` only warns, then starts the program at the
+   * top of its text segment, where it runs whatever happens to be first. That
+   * is the least explicable thing a program can do to someone learning, so it
+   * is reported as an error here and the mistake is usually a misspelling.
+   */
+  private entryPointDiagnostics;
+  private assembleInBlink;
+  /**
+   * Assembles outside blink and hands the object file to the linker inside it,
+   * which is where the state machine picks up again as if blink had produced
+   * the object itself.
+   */
+  private assembleWithWasmAssembler;
+  private collectAssemblerDiagnostics;
+  private emitAssemblerOutput;
+  private parseAssemblerDiagnostics;
   loadElf(data: ArrayBuffer | Uint8Array): void;
   starti(): void;
   pauseAtEntry(): void;
@@ -315,8 +592,11 @@ declare class BlinkRuntime {
   getLastStepInfo(): NativeStepInfo;
   resolveSymbol(address: bigint): NativeSymbol | null;
   getSourceLineForAddress(address: bigint): number | null;
+  getSourceLocationForAddress(address: bigint): X86SourceLocation | null;
   getAddressesForSourceLine(lineIndex: number): bigint[];
-  pauseForBreakpoint(address: bigint, lineNumber: number | undefined): void;
+  getAddressesForSourceLocation(location: X86SourceLocation): bigint[];
+  getSourceMappedAddresses(): bigint[];
+  pauseForBreakpoint(address: bigint, location: X86SourceLocation | undefined): void;
   pauseForLimit(address: bigint, executedInstructions: bigint): void;
   resumeAfterStateMutation(): void;
   private startProgram;
@@ -337,160 +617,18 @@ declare class BlinkRuntime {
   private tryReadSourceMap;
 }
 //#endregion
-//#region src/interface.d.ts
-type StatusRegister = {
-  name: string;
-  value: number;
-  prev: number;
-};
-type MonacoError = {
-  lineIndex: number;
-  column: number;
-  line: {
-    line: string;
-    line_index: number;
-  };
-  message: string;
-  formatted: string;
-};
-type StackFrame = {
-  name: string;
-  address: bigint;
-  destination: bigint;
-  sp: bigint;
-  line: number;
-  color: string;
-};
-type RegisterHex = [hi: string, lo: string];
-declare enum RegisterSize {
-  Byte = 1,
-  Word = 2,
-  Long = 4,
-  Double = 8
-}
-type ExecutionStep = {
-  mutations: MutationOperation[];
-  pc: number;
-  old_ccr: {
-    bits: number;
-  };
-  new_ccr: {
-    bits: number;
-  };
-  line: number;
-};
-type MutationOperation = {
-  type: 'WriteRegister';
-  value: {
-    register: string;
-    old: bigint;
-    size: RegisterSize;
-  };
-} | {
-  type: 'WriteMemory';
-  value: {
-    address: bigint;
-    old: bigint;
-    size: RegisterSize;
-  };
-} | {
-  type: 'WriteMemoryBytes';
-  value: {
-    address: bigint;
-    old: number[];
-  };
-} | {
-  type: 'PopCallStack';
-  value: {
-    to: bigint;
-    from: bigint;
-  };
-} | {
-  type: 'PushCallStack';
-  value: {
-    to: bigint;
-    from: bigint;
-  };
-} | {
-  type: 'Other';
-  value: string;
-};
-type EmulatorDecoration = {
-  type: 'below-line';
-  note?: string;
-  belowLine: number;
-  md: string;
-};
-type CompilationError = {
-  type: 'raw';
-  message: string;
-};
-declare enum EmulatorStatus {
-  Terminated = 0,
-  Running = 1,
-  WaitingForInput = 2,
-  NotReady = 3
-}
-type Instruction = {
-  address: bigint;
-  lineNumber: number;
-  code: string;
-};
-type EmulatorConfig<R extends string> = {
-  systemSize: RegisterSize;
-  registerNames: R[];
-  endianness?: 'little' | 'big';
-  hiddenRegisters?: R[];
-};
-declare abstract class BaseEmulator<T, R extends string, CompileResult = {
-  ok: true;
-} | {
-  ok: false;
-  errors: CompilationError[];
-  report: string;
-}> {
-  protected _registerNames: R[];
-  protected _systemSize: RegisterSize;
-  protected _endianness: 'little' | 'big';
-  constructor(options: EmulatorConfig<R>);
-  getSystemSize(): RegisterSize;
-  getEndianness(): 'little' | 'big';
-  getRegisterNames(): R[];
-  abstract initialize(undoSize: number): void;
-  abstract getCompiledCode(): {
-    decorations: EmulatorDecoration[];
-    code: string;
-  };
-  abstract dispose(): void;
-  abstract stringifyError(error: unknown): string;
-  abstract compile(code: string): Promise<CompileResult>;
-  abstract checkCode(code: string): Promise<MonacoError[]>;
-  abstract undo(): void;
-  abstract canUndo(): boolean;
-  abstract step(): Promise<{
-    terminated: boolean;
-  }>;
-  abstract getStatus(): EmulatorStatus;
-  abstract writeMemoryBytes(address: bigint, data: Uint8Array): void;
-  abstract readMemoryBytes(address: bigint, length: bigint): Uint8Array;
-  abstract getNextInstruction(): Instruction | null;
-  abstract getUndoHistory(max: number): ExecutionStep[];
-  abstract getPc(): bigint;
-  abstract getSp(): bigint;
-  abstract getFlags(): {
-    name: string;
-    value: number;
-    prev?: number;
-  }[];
-  abstract getCallStack(): StackFrame[];
-  abstract getInstructionAt(address: bigint): Instruction | null;
-  abstract getRegisterValues(): bigint[];
-  abstract getRegisterValuesRecord(): Record<R, bigint>;
-  abstract getRegisterValue(register: R, size?: RegisterSize): bigint;
-  abstract setRegisterValue(register: R, value: bigint, size?: RegisterSize): void;
-  abstract hasTerminated(): boolean;
-  abstract run(limit?: number, breakpoints?: number[]): Promise<EmulatorStatus>;
-}
+//#region src/project.d.ts
+declare const X86_PROJECT_ROOT = "/__x86_project";
+declare function validateX86Project(project: X86Project): void;
+/**
+ * Writes a Project into the emulator filesystem and selects the Entry directory as NASM's working
+ * directory. NASM consequently owns `%include` and `incbin` resolution, including paths produced by
+ * preprocessor macros.
+ */
+declare function stageX86Project(fs: EmscriptenFS, project: X86Project): void;
+/** Maps a path emitted by NASM or DWARF back to the exact Project path. */
+declare function x86ProjectSourcePath(sourcePath: string | undefined, project: Pick<X86Project, 'entry' | 'files'>): string;
+declare function x86ProjectText(project: X86Project, path: string): string;
 //#endregion
 //#region src/x86-emulator.d.ts
 type X86EmulatorOptions = Omit<BlinkRuntimeOptions, 'callbacks' | 'mode'> & {
@@ -512,6 +650,7 @@ declare class X86Emulator extends BaseEmulator<BlinkRuntime, X86RegisterName, X8
   on<T extends X86EmulatorEventName>(eventName: T, handler: X86EmulatorEventHandler<T>): () => void;
   setMode(mode: AssemblerMode | AssemblerId): Promise<void>;
   compile(code: string): Promise<X86CompileResult>;
+  compileProject(project: X86Project): Promise<X86CompileResult>;
   loadElf(data: ArrayBuffer | Uint8Array): void;
   runUntilBlocked(): Promise<EmulatorStatus>;
   provideInput(line: string): void;
@@ -523,6 +662,12 @@ declare class X86Emulator extends BaseEmulator<BlinkRuntime, X86RegisterName, X8
   dispose(): void;
   stringifyError(error: unknown): string;
   checkCode(code: string): Promise<MonacoError[]>;
+  /**
+   * Diagnostics only: this assembles but does not link, and for an assembler
+   * that runs as its own wasm module it does not touch blink at all, so a
+   * loaded or paused program survives a check.
+   */
+  checkProject(project: X86Project): Promise<MonacoError[]>;
   undo(): void;
   canUndo(): boolean;
   step(): Promise<{
@@ -542,12 +687,14 @@ declare class X86Emulator extends BaseEmulator<BlinkRuntime, X86RegisterName, X8
   }[];
   getCallStack(): StackFrame[];
   getInstructionAt(address: bigint): Instruction | null;
+  /** Every instruction address represented in the linked program's DWARF source map. */
+  getCompiledInstructions(): Instruction[];
   getRegisterValues(): bigint[];
   getRegisterValuesRecord(): Record<X86RegisterName, bigint>;
   getRegisterValue(register: X86RegisterName, size?: RegisterSize): bigint;
   setRegisterValue(register: X86RegisterName, value: bigint, size?: RegisterSize): void;
   hasTerminated(): boolean;
-  run(limit?: number, breakpoints?: number[]): Promise<EmulatorStatus>;
+  run(limit?: number, breakpoints?: X86Breakpoint[]): Promise<EmulatorStatus>;
   private validateRunLimit;
   private resolveBreakpointAddresses;
   private runWithBreakpoints;
@@ -563,5 +710,5 @@ declare class X86Emulator extends BaseEmulator<BlinkRuntime, X86RegisterName, X8
 }
 declare function createX86Emulator(options?: X86EmulatorOptions): Promise<X86Emulator>;
 //#endregion
-export { AssemblerId, AssemblerMode, BaseEmulator, Binary, BlinkRunOptions, BlinkRuntime, BlinkRuntimeCallbacks, BlinkRuntimeOptions, BlinkState, BlinkenlibModule, BlinkenlibModuleOptions, CompilationError, DEFAULT_ASSEMBLER_ID, DiagnosticLine, DiagnosticsParser, DisassemblySnapshot, EmscriptenFS, EmulatorConfig, EmulatorDecoration, EmulatorStatus, ExecutionStep, Instruction, MaybePromise, MemoryReadResult, MemoryWriteResult, MonacoError, MutationOperation, NativeControlFlowKind, NativeInstruction, NativeMemoryWrite, NativeRunControls, NativeRunStop, NativeRunStopKind, NativeStepInfo, NativeSymbol, RegisterHex, RegisterSize, RegisterSnapshot, ResourceSource, StackFrame, StatusRegister, StopReason, StopReasonKind, X86CompilationDiagnostic, X86CompileResult, X86Emulator, X86EmulatorEventHandler, X86EmulatorEventMap, X86EmulatorEventName, X86EmulatorOptions, X86RegisterName, X86_REGISTER_NAMES, assemblers, createX86Emulator, defaultResourceUrl, fasmDiagnostics, gnuDiagnostics, isNodeRuntime, nasmDiagnostics, observeCallbackResult, readResourceBytes, toResourceUrl };
+export { AssemblerId, AssemblerMode, BaseEmulator, Binary, BlinkRunOptions, BlinkRuntime, BlinkRuntimeCallbacks, BlinkRuntimeOptions, BlinkState, BlinkenlibModule, BlinkenlibModuleOptions, CompilationError, DEFAULT_ASSEMBLER_ID, DiagnosticLine, DiagnosticSeverity, DiagnosticsParser, DisassemblySnapshot, EmscriptenFS, EmulatorConfig, EmulatorDecoration, EmulatorStatus, ExecutionStep, Instruction, MaybePromise, MemoryReadResult, MemoryWriteResult, MonacoError, MutationOperation, NativeControlFlowKind, NativeInstruction, NativeMemoryWrite, NativeRunControls, NativeRunStop, NativeRunStopKind, NativeStepInfo, NativeSymbol, RegisterHex, RegisterSize, RegisterSnapshot, ResourceSource, StackFrame, StatusRegister, StopReason, StopReasonKind, X86Breakpoint, X86CompilationDiagnostic, X86CompileResult, X86Emulator, X86EmulatorEventHandler, X86EmulatorEventMap, X86EmulatorEventName, X86EmulatorOptions, X86Project, X86ProjectFile, X86RegisterName, X86SourceLocation, X86_PROJECT_ROOT, X86_REGISTER_NAMES, assemblers, createX86Emulator, defaultResourceUrl, fasmDiagnostics, gnuDiagnostics, isNodeRuntime, locateDiagnosticColumn, nasmDiagnostics, observeCallbackResult, readResourceBytes, stageX86Project, toResourceUrl, validateX86Project, x86ProjectSourcePath, x86ProjectText };
 //# sourceMappingURL=index.d.mts.map