@specy/risc-v 2.0.1 → 3.0.0

package/README.md

@@ -9,22 +9,33 @@ It is part of a family of javascript assembly interpreters/simulators:
 
 ## Usage 
 
-First, create an instance of the simulator with the `RISCV.makeRiscvFromSource` function.
+First, create an instance of the simulator with `makeRiscVFromFiles`. Supply a virtual source tree and the path of its entry file. Relative `.include` paths resolve from the file containing the directive, while paths beginning with `/` resolve from the virtual root.
 
 Before running the simulator, you must assemble and initialize it. You can then step through the program, simulate with breakpoints, or simulate with a limit.
 
 ⚠️**WARNING**⚠️ You must have only one instance of the simulator at a time. Memory, registers, and other state may be shared or behave unpredictably with multiple instances.
 
 ```typescript
-import {RISCV, JsRiscV, RegisterName, BackStepAction} from '@specy/risc-v';
-const sourceCode = `
-    li t0, 5          # Load immediate value 5 into register t0
-    li t1, 7          # Load immediate value 7 into register t1
-    add t2, t0, t1    # Add t0 and t1, store result in t2
-`;
+import {RISCV, makeRiscVFromFiles, JsRiscV, RegisterName, BackStepAction} from '@specy/risc-v';
+
+const files = {
+  'src/main.asm': `
+    .include "lib/math.asm"
+    .text
+    .globl main
+  main:
+    add_values(t2, 5, 7)
+  `,
+  'src/lib/math.asm': `
+    .macro add_values(%result, %left, %right)
+      li %result, %left
+      addi %result, %result, %right
+    .end_macro
+  `,
+} as const;
 
 // RISCV.setIs64Bit(true); // Set to 64-bit mode if needed
-const riscvSimulator: JsRiscV = RISCV.makeRiscVFromSource(sourceCode);
+const riscvSimulator: JsRiscV = makeRiscVFromFiles(files, 'src/main.asm');
 
 riscvSimulator.assemble();
 riscvSimulator.initialize(true); // Start at 'main'
@@ -102,16 +113,62 @@ Synchronous handlers never yield to the event loop: the simulation runs straight
 returned promise settles on a microtask. Overlapping calls are queued and run one after another,
 never concurrently.
 
+Program time is a handler too, so a run can be given a clock of its own: `sleep` answers syscall 32
+and `time` answers syscall 30. A live run resolves `sleep` on a timer and returns `Date.now()` from
+`time`; a scripted run can settle `sleep` immediately, advance a virtual clock by the requested
+milliseconds and return that clock instead, which keeps elapsed-time output reproducible.
+
+## Memory observers
+
+A memory-mapped device - a framebuffer, a keyboard register - is modelled by observing the memory
+the program reads and writes:
+
+```ts
+// Every write in a framebuffer: (address, length, value), with the width of the store in bytes.
+const frame = riscvSimulator.addMemoryWriteObserver(0x10010000, 0x10012ffc, (address, length, value) => {
+    screen.markDirty(address)
+})
+
+// One memory-mapped register: reads and writes, either of which may be null.
+const receiver = riscvSimulator.addMemoryAccessObserver(
+    0xffff0004,
+    () => keyboard.consumeCharacter(),
+    null
+)
+
+riscvSimulator.removeMemoryObserver(frame)
+riscvSimulator.removeMemoryObservers()
+```
+
+*   Addresses must be word-aligned, `endAddress` is inclusive and covers its whole word, and a range
+    may not cross `0x80000000`; a registration that breaks any of these throws. Either form of a
+    high address is accepted: `0xffff0000` and `0xffff0000 | 0` name the same word.
+*   Handlers are given signed 32 bit integers, as the guest holds them: the register at
+    `0xffff000c` arrives as `-65524`, and a pixel word with its high bit set arrives negative.
+    Apply `>>> 0` wherever the unsigned form is wanted.
+*   Handlers run synchronously inside the instruction that caused the access, so they must be cheap
+    and must not write back into their own range. A returned promise is ignored, unlike an IO
+    handler's.
+*   An observer is notified *after* the access, with the value the program read or stored. A
+    register whose value is consumed by reading it must therefore be reloaded from the handler,
+    with `setPeripheralWord`, for the next read.
+*   Observers live on the simulator's memory, which assembling and initializing only clear the
+    contents of, so a registration survives `assemble()` and `initialize()` and - like a registered
+    IO handler - is shared by every `JsRiscV` instance. Notifications start once a program has been
+    assembled.
+*   `undo()` restores memory through the same stores, so an observed range reports the restored
+    values as ordinary writes and a device that follows notifications alone stays in step.
+
 ## API
 
 ### `RISCV` Static Class
 
 Provides static methods to initialize and create simulator instances.
 
-* `RISCV.makeRiscvFromSource(source: string): JsRiscv`
-  Creates a new `JsRiscv` instance from RISC-V assembly source code. This also initializes the underlying RISC-V simulation environment if it hasn't been already.
+* `makeRiscVFromFiles(files: RISCVSourceSet, entryFile: string): JsRiscV`
+  Creates a simulator from a snapshot of a virtual source tree and its entry file. Source paths are canonical, root-relative POSIX paths. The factory is also available as `RISCV.makeRiscVFromFiles` and initializes the simulation environment when needed.
 * `RISCV.initializeRISCV(): void`
-  Initializes the core RISC-V simulation environment. Called internally by `makeRiscvFromSource`, but can be called explicitly if needed.
+  Initializes the core RISC-V simulation environment. Called internally by `makeRiscVFromFiles`, but can be called explicitly if needed.
 * `RISCV.getInstructionSet(): JsInstruction[]`
   Returns an array of objects, each describing a supported RISC-V instruction (name, example, description, tokens).
 * `RISCV.setIs64Bit(is64Bit: boolean): void`
@@ -145,15 +202,20 @@ This interface provides methods to control and interact with a RISC-V simulator
 * `getConditionFlags(): number[]`: Gets the 8 condition flags (if applicable, typically related to floating-point or custom extensions).
 * `registerHandler<T extends HandlerName>(name: T, handler: (...args: HandlerMap[T]['in']) => HandlerMap[T]['out'] | Promise<HandlerMap[T]['out']>): void`: Registers a handler function for a specific event (e.g., syscalls). See `HandlerName`, `HandlerMap` and [IO handlers](#io-handlers) for details.
 * `getUndoStack(): JsBackStep[]`: Returns the undo stack, an array of `JsBackStep` objects representing simulation history.
-* `readMemoryBytes(address: number, length: number): number[]`: Reads `length` bytes from memory starting at `address`. Returns an array of byte values.
-* `setMemoryBytes(address: number, bytes: number[]): void`: Writes an array of `bytes` to memory starting at `address`.
-* `getCurrentStatementIndex(): number`: Returns the index of the current instruction in the list of assembled program statements.
+* `readMemoryBytes(address: number, length: number): number[]`: Reads `length` bytes from memory starting at `address`. Returns an array of byte values. Notifies no memory observer: inspecting memory from the host is not the program reading it.
+* `setMemoryBytes(address: number, bytes: number[]): void`: Writes an array of `bytes` to memory starting at `address`, the way the program does: write observers are notified and, while undo is enabled, an undo step is recorded per byte.
+* `setPeripheralWord(address: number, value: number): void`: Writes one word-aligned word as a peripheral would, notifying no observer and recording no undo step. See [memory observers](#memory-observers).
+* `addMemoryWriteObserver(startAddress: number, endAddress: number, handler): number`: Observes every write in an address range. See [memory observers](#memory-observers).
+* `addMemoryAccessObserver(address: number, onRead, onWrite): number`: Observes reads and writes of one word. See [memory observers](#memory-observers).
+* `removeMemoryObserver(handle: number): void`: Removes one registration.
+* `removeMemoryObservers(): void`: Removes every registration.
+* `countMemoryObservers(): number`: The number of live registrations.
 * `getNextStatement(): JsProgramStatement | null`: Returns the next `JsProgramStatement` to be executed, or `null` if at the end.
 * `getStatementAtAddress(address: number): JsProgramStatement | null`: Gets the program statement at the given memory `address`.
-* `getStatementAtSourceLine(line: number): JsProgramStatement | null`: Gets the program statement corresponding to the original source `line` number.
-* `getCompiledStatements(): JsProgramStatement[]`: Returns an array of all assembled program statements.
-* `getParsedStatements(): JsInstructionToken[]`: Returns an array of tokens from the initial parsing stage.
-* `getTokenizedLines(): RiscvTokenizedLine[]`: Returns an array of lines, each with its source string and corresponding tokens.
+* `getStatementsAtSourceLocation(sourcePath: string, sourceLine: number): JsProgramStatement[]`: Returns every machine statement generated from an original one-based source location, in address order. Pseudo-instructions and macro calls can produce multiple results.
+* `getCompiledStatements(): JsProgramStatement[]`: Returns all machine statements after a successful assembly.
+* `getParsedStatements(): JsProgramStatement[]`: Returns the parsed statements before pseudo-instruction expansion.
+* `getTokenizedLines(): RiscvTokenizedLine[]`: Returns the expanded source stream with each line's path, one-based line number, original source, processed source, and tokens. It is available after tokenization succeeds, including when a later assembly stage fails.
 * `getCallStack(): JsRiscvStackFrame[]`: Returns the current call stack as an array of stack frame objects.
 * `getLabelAtAddress(address: number): string | null`: Returns the label name at the given memory `address`, or `null` if no label exists there.
 
@@ -165,6 +227,8 @@ This interface provides methods to control and interact with a RISC-V simulator
 #### Types
 
 * `RegisterName`: Union type for RISC-V register names (e.g., `'ra'`, `'sp'`, `'a0'`, `'t0'`, etc.).
+* `RISCVSourceSet`: A read-only mapping from canonical virtual source paths to source strings.
+* `RISCVSourceLocation`: A source path and one-based source line.
 * `HandlerName`: Union type of all possible handler names (keys of `HandlerMap`).
 * `HandlerMap`: An object type mapping `HandlerName`s to their expected input argument types (`in`) and return type (`out`). This defines the signature for syscall/event handlers.
 * `HandlerMapFns`: An object type where keys are `HandlerName`s and values are the corresponding handler functions.
@@ -172,10 +236,10 @@ This interface provides methods to control and interact with a RISC-V simulator
 * `ConfirmResult`: Enum for confirm dialog results (`YES`, `NO`, `CANCEL`).
 * `BackStepAction`: Enum representing types of actions that can be undone (e.g., `MEMORY_RESTORE_WORD`, `REGISTER_RESTORE`).
 * `JsBackStep`: Interface representing an entry in the undo stack, detailing the action, parameters, and PC value.
-* `JsProgramStatement`: Interface representing an assembled instruction, including source line, address, binary/machine/assembly representations.
-* `JsInstructionToken`: Interface representing a token from the assembly source (value, type, source position).
+* `JsProgramStatement`: Interface representing an assembled instruction, including its source path, source line, address, binary/machine/assembly representations, and full original source line.
+* `JsInstructionToken`: Interface representing a token from the assembly source (value, type, and one-based source column).
 * `JsInstruction`: Interface describing a RISC-V instruction (name, example, description, token patterns).
-* `RiscvTokenizedLine`: An object containing the original line string and its parsed `JsInstructionToken`s.
-* `RISCVAssembleError`: Interface describing an assembly error (message, line/column, warning status, etc.).
+* `RiscvTokenizedLine`: An object containing source identity, original and processed line strings, and parsed `JsInstructionToken`s.
+* `RISCVAssembleError`: Interface describing an assembly diagnostic with its source path, one-based line and column, warning status, and structured macro expansion trace.
 * `RISCVAssembleResult`: Interface for the result of `assemble()`, containing a report string, list of `RISCVAssembleError`s, and a `hasErrors` boolean.
-* `JsRiscvStackFrame`: Interface describing a frame on the call stack (PC, target address, SP, FP, register snapshot).
+* `JsRiscvStackFrame`: Interface describing a frame on the call stack (PC, target address, SP, FP, register snapshot).

package/dist/index.d.mts

@@ -1,7 +1,6 @@
 type JsInstructionToken = {
-    sourceLine: number;
+    /** One-based column in the processed source line. */
     sourceColumn: number;
-    originalSourceLine: number;
     value: string;
     type: string;
 };
@@ -119,10 +118,23 @@ type HandlerMap = {
         in: [l: string];
         out: void;
     };
+    /**
+     * Syscall 32: the program asks to be suspended for this many milliseconds. Return a promise
+     * that settles when the wait is over to suspend the simulation without blocking the host.
+     */
     sleep: {
         in: [milliseconds: number];
         out: void;
     };
+    /**
+     * Syscall 30: the program time in milliseconds, split by the syscall into a0 (low word) and
+     * a1 (high word). Answer with `Date.now()` for a live run, or with a virtual clock for a
+     * scripted one, so that elapsed-time output stays reproducible.
+     */
+    time: {
+        in: [];
+        out: number;
+    };
     stdIn: {
         in: [buffer: number[], length: number];
         out: void;
@@ -136,6 +148,27 @@ type HandlerMap = {
         out: void;
     };
 };
+/**
+ * Notified after a write anywhere in an observed address range.
+ *
+ * `length` is the width of the access in bytes (4, 2 or 1) and `value` is what the program stored,
+ * so a byte or halfword store reports only the bytes it touched; a peripheral that mirrors whole
+ * words should re-read the containing word with `readMemoryBytes` rather than trust `value`.
+ *
+ * Both `address` and `value` are signed 32 bit integers, as the guest holds them: the register at
+ * `0xffff000c` arrives as `-65524`, and a pixel word with its high bit set arrives negative too.
+ * Apply `>>> 0` wherever the unsigned form is wanted.
+ */
+type MemoryWriteObserver = (address: number, length: number, value: number) => void;
+/**
+ * Notified after a read or a write of one observed word, with the same signed 32 bit numbers as
+ * `MemoryWriteObserver`. `value` is the value the program read or stored; on a read it is what
+ * memory held *before* the observer ran, so a register whose value is consumed by reading it must
+ * be reloaded from the handler for the next read.
+ */
+type MemoryAccessObserver = (address: number, value: number) => void;
+/** Identifies one registration, for `removeMemoryObserver`. */
+type MemoryObserverHandle = number;
 type JsInstruction = {
     name: string;
     example: string;
@@ -144,16 +177,30 @@ type JsInstruction = {
     getIsRv64Only: () => boolean;
 };
 type RiscvTokenizedLine = {
-    line: string;
+    sourcePath: string;
+    /** One-based line in `sourcePath`. */
+    sourceLine: number;
+    /** Exact line supplied in the source set. */
+    source: string;
+    /** Line after assembler substitutions such as `.eqv`. */
+    processedSource: string;
     tokens: JsInstructionToken[];
 };
+type RISCVSourceLocation = {
+    sourcePath: string;
+    /** One-based line in `sourcePath`. */
+    sourceLine: number;
+};
+type RISCVSourceSet = Readonly<Record<string, string>>;
 type RISCVAssembleError = {
     isWarning: boolean;
     message: string;
-    macroExpansionHistory: string;
-    filename: string;
-    lineNumber: number;
-    columnNumber: number;
+    macroExpansionTrace: RISCVSourceLocation[];
+    sourcePath: string;
+    /** One-based line in `sourcePath`. */
+    sourceLine: number;
+    /** One-based column in `sourcePath`. Zero only for diagnostics without a source location. */
+    sourceColumn: number;
 };
 type RISCVAssembleResult = {
     report: string;
@@ -164,7 +211,7 @@ type RISCVAssembleResult = {
     hasWarnings: boolean;
 };
 declare class RISCV {
-    static makeRiscVFromSource: typeof makeRiscVfromSource;
+    static makeRiscVFromFiles: typeof makeRiscVFromFiles;
     static initializeRISCV: typeof initializeRISCV;
     static getInstructionSet(): JsInstruction[];
     static setIs64Bit(is64Bit: boolean): void;
@@ -196,9 +243,9 @@ type JsRiscVStackFrame = {
  * Represents a statement in the assembled program.
  */
 interface JsProgramStatement {
-    /**
-     * The line number in the original source code.
-     */
+    /** Canonical path of the original source file. */
+    readonly sourcePath: string;
+    /** The one-based line number in the original source file. */
     readonly sourceLine: number;
     /**
      * The memory address of the instruction.
@@ -348,11 +395,8 @@ interface JsRiscV {
      * @param address
      */
     getStatementAtAddress(address: number): JsProgramStatement;
-    /**
-     * Gets the statement at the given source line.
-     * @param line
-     */
-    getStatementAtSourceLine(line: number): JsProgramStatement;
+    /** Gets every machine statement generated from an original source location. */
+    getStatementsAtSourceLocation(sourcePath: string, sourceLine: number): JsProgramStatement[];
     getTokenizedLines(): RiscvTokenizedLine[];
     /**
      * Checks if the simulation can be undone.
@@ -369,7 +413,7 @@ interface JsRiscV {
      * @returns An array of `JsProgramStatement` objects representing the compiled program.
      */
     getCompiledStatements(): JsProgramStatement[];
-    getParsedStatements(): JsInstructionToken[];
+    getParsedStatements(): JsProgramStatement[];
     /**
      * Gets the label at the given address.
      * @param address The memory address.
@@ -459,6 +503,9 @@ interface JsRiscV {
     getUndoStack(): JsBackStep[];
     /**
      * Reads a sequence of bytes from memory.
+     *
+     * Reading through this method notifies no memory observer: inspecting memory from the host is
+     * not the program reading it, so a memory viewer never drives a memory-mapped register.
      * @param address The starting memory address.
      * @param length The number of bytes to read.
      * @returns An array of bytes read from memory.
@@ -466,15 +513,63 @@ interface JsRiscV {
     readMemoryBytes(address: number, length: number): number[];
     /**
      * Writes a sequence of bytes to memory.
+     *
+     * Unlike `readMemoryBytes`, this writes the way the program does: it notifies write observers
+     * and, while undo is enabled, records an undo step per byte. Use `setPeripheralWord` for a
+     * device keeping its own register up to date.
      * @param address The starting memory address.
      * @param bytes An array of bytes to write to memory.
      */
     setMemoryBytes(address: number, bytes: number[]): void;
     /**
-     * Gets the index of the current statement in the assembled program.
-     * @returns The index of the current statement.
+     * Writes one word as a peripheral would: no observer is notified and no undo step is recorded,
+     * because the write is not the program acting. This is how a device model refreshes a
+     * memory-mapped register - a ready bit, a pending character - without feeding its own observer
+     * or consuming undo history.
+     * @param address The word address, which must be word-aligned. Either form of a high address
+     * is accepted: `0xffff0000` and `0xffff0000 | 0` name the same word.
+     * @param value The 32 bit value to store, raw, without byte-order adjustment.
+     */
+    setPeripheralWord(address: number, value: number): void;
+    /**
+     * Observes every write in an address range, the shape a framebuffer wants.
+     *
+     * Both addresses must be word-aligned, `endAddress` is inclusive and covers its whole word, and
+     * the range may not cross 0x80000000 (split it in two registrations instead); a range that
+     * breaks any of these throws. Either form of a high address is accepted: `0xffff0000` and
+     * `0xffff0000 | 0` name the same word. The handler runs synchronously inside the storing instruction, so
+     * it must be cheap and must not write back into its own range; a returned promise is ignored.
+     *
+     * Observers live on the simulator's memory, which assembling and initializing only clear the
+     * contents of, so a registration survives `assemble()` and `initialize()`. For the same reason
+     * it is shared by every `JsRiscV` instance: register once per page, or remove the previous
+     * registration before registering again for a newly built program.
+     *
+     * Notifications only start once a program has been assembled, and undo notifies too: restoring
+     * memory during `undo()` goes through the same stores, so an observed range reports the
+     * restored values as ordinary writes.
+     * @returns A handle for `removeMemoryObserver`.
+     */
+    addMemoryWriteObserver(startAddress: number, endAddress: number, handler: MemoryWriteObserver): MemoryObserverHandle;
+    /**
+     * Observes reads and writes of a single word, the shape a memory-mapped register wants. The
+     * address must be word-aligned. Pass `null` for a direction you do not care about. The same
+     * lifetime and synchronous-handler rules as `addMemoryWriteObserver` apply.
+     * @returns A handle for `removeMemoryObserver`.
+     */
+    addMemoryAccessObserver(address: number, onRead: MemoryAccessObserver | null, onWrite: MemoryAccessObserver | null): MemoryObserverHandle;
+    /**
+     * Removes one registration. An unknown handle is ignored.
+     */
+    removeMemoryObserver(handle: MemoryObserverHandle): void;
+    /**
+     * Removes every registration.
+     */
+    removeMemoryObservers(): void;
+    /**
+     * The number of live registrations, across every `JsRiscV` instance.
      */
-    getCurrentStatementIndex(): number;
+    countMemoryObservers(): number;
     /**
      * Gets the next statement to be executed.
      * @returns The next `JsProgramStatement`.
@@ -493,15 +588,19 @@ interface JsRiscV {
     terminated: boolean;
 }
 /**
- * Creates a new RISCV simulator from the given source code.
- * @param source The source code to assemble.
+ * Creates a RISC-V simulator from a virtual source tree and its entry file.
+ *
+ * Source paths are canonical, root-relative, case-sensitive POSIX paths. The source set is
+ * snapshotted by this call; only the entry file and files reached through `.include` are assembled.
+ * @param files Source text keyed by canonical source path.
+ * @param entryFile Canonical path of the file from which include expansion starts.
  * @returns A new `JsRiscV` object.
  */
-declare function makeRiscVfromSource(source: string): JsRiscV;
+declare function makeRiscVFromFiles(files: RISCVSourceSet, entryFile: string): JsRiscV;
 /**
  * Initializes the RISCV simulator.
  */
 declare function initializeRISCV(): void;
 declare function bigintToHighLow(value: bigint): [high: number, low: number];
 
-export { BackStepAction, ConfirmResult, DialogType, type HandlerMap, type HandlerMapFns, type JsBackStep, type JsInstruction, type JsInstructionToken, type JsProgramStatement, type JsRiscV, type JsRiscVStackFrame, RISCV, type RISCVAssembleError, type RISCVAssembleResult, RISCVRegisters, RISCV_REGISTERS, type RegisterName, type RiscvTokenizedLine, StopReason, bigintToHighLow, registerHandlers, unimplementedHandler };
+export { BackStepAction, ConfirmResult, DialogType, type HandlerMap, type HandlerMapFns, type JsBackStep, type JsInstruction, type JsInstructionToken, type JsProgramStatement, type JsRiscV, type JsRiscVStackFrame, type MemoryAccessObserver, type MemoryObserverHandle, type MemoryWriteObserver, RISCV, type RISCVAssembleError, type RISCVAssembleResult, RISCVRegisters, type RISCVSourceLocation, type RISCVSourceSet, RISCV_REGISTERS, type RegisterName, type RiscvTokenizedLine, StopReason, bigintToHighLow, makeRiscVFromFiles, registerHandlers, unimplementedHandler };

package/dist/index.d.ts

@@ -1,7 +1,6 @@
 type JsInstructionToken = {
-    sourceLine: number;
+    /** One-based column in the processed source line. */
     sourceColumn: number;
-    originalSourceLine: number;
     value: string;
     type: string;
 };
@@ -119,10 +118,23 @@ type HandlerMap = {
         in: [l: string];
         out: void;
     };
+    /**
+     * Syscall 32: the program asks to be suspended for this many milliseconds. Return a promise
+     * that settles when the wait is over to suspend the simulation without blocking the host.
+     */
     sleep: {
         in: [milliseconds: number];
         out: void;
     };
+    /**
+     * Syscall 30: the program time in milliseconds, split by the syscall into a0 (low word) and
+     * a1 (high word). Answer with `Date.now()` for a live run, or with a virtual clock for a
+     * scripted one, so that elapsed-time output stays reproducible.
+     */
+    time: {
+        in: [];
+        out: number;
+    };
     stdIn: {
         in: [buffer: number[], length: number];
         out: void;
@@ -136,6 +148,27 @@ type HandlerMap = {
         out: void;
     };
 };
+/**
+ * Notified after a write anywhere in an observed address range.
+ *
+ * `length` is the width of the access in bytes (4, 2 or 1) and `value` is what the program stored,
+ * so a byte or halfword store reports only the bytes it touched; a peripheral that mirrors whole
+ * words should re-read the containing word with `readMemoryBytes` rather than trust `value`.
+ *
+ * Both `address` and `value` are signed 32 bit integers, as the guest holds them: the register at
+ * `0xffff000c` arrives as `-65524`, and a pixel word with its high bit set arrives negative too.
+ * Apply `>>> 0` wherever the unsigned form is wanted.
+ */
+type MemoryWriteObserver = (address: number, length: number, value: number) => void;
+/**
+ * Notified after a read or a write of one observed word, with the same signed 32 bit numbers as
+ * `MemoryWriteObserver`. `value` is the value the program read or stored; on a read it is what
+ * memory held *before* the observer ran, so a register whose value is consumed by reading it must
+ * be reloaded from the handler for the next read.
+ */
+type MemoryAccessObserver = (address: number, value: number) => void;
+/** Identifies one registration, for `removeMemoryObserver`. */
+type MemoryObserverHandle = number;
 type JsInstruction = {
     name: string;
     example: string;
@@ -144,16 +177,30 @@ type JsInstruction = {
     getIsRv64Only: () => boolean;
 };
 type RiscvTokenizedLine = {
-    line: string;
+    sourcePath: string;
+    /** One-based line in `sourcePath`. */
+    sourceLine: number;
+    /** Exact line supplied in the source set. */
+    source: string;
+    /** Line after assembler substitutions such as `.eqv`. */
+    processedSource: string;
     tokens: JsInstructionToken[];
 };
+type RISCVSourceLocation = {
+    sourcePath: string;
+    /** One-based line in `sourcePath`. */
+    sourceLine: number;
+};
+type RISCVSourceSet = Readonly<Record<string, string>>;
 type RISCVAssembleError = {
     isWarning: boolean;
     message: string;
-    macroExpansionHistory: string;
-    filename: string;
-    lineNumber: number;
-    columnNumber: number;
+    macroExpansionTrace: RISCVSourceLocation[];
+    sourcePath: string;
+    /** One-based line in `sourcePath`. */
+    sourceLine: number;
+    /** One-based column in `sourcePath`. Zero only for diagnostics without a source location. */
+    sourceColumn: number;
 };
 type RISCVAssembleResult = {
     report: string;
@@ -164,7 +211,7 @@ type RISCVAssembleResult = {
     hasWarnings: boolean;
 };
 declare class RISCV {
-    static makeRiscVFromSource: typeof makeRiscVfromSource;
+    static makeRiscVFromFiles: typeof makeRiscVFromFiles;
     static initializeRISCV: typeof initializeRISCV;
     static getInstructionSet(): JsInstruction[];
     static setIs64Bit(is64Bit: boolean): void;
@@ -196,9 +243,9 @@ type JsRiscVStackFrame = {
  * Represents a statement in the assembled program.
  */
 interface JsProgramStatement {
-    /**
-     * The line number in the original source code.
-     */
+    /** Canonical path of the original source file. */
+    readonly sourcePath: string;
+    /** The one-based line number in the original source file. */
     readonly sourceLine: number;
     /**
      * The memory address of the instruction.
@@ -348,11 +395,8 @@ interface JsRiscV {
      * @param address
      */
     getStatementAtAddress(address: number): JsProgramStatement;
-    /**
-     * Gets the statement at the given source line.
-     * @param line
-     */
-    getStatementAtSourceLine(line: number): JsProgramStatement;
+    /** Gets every machine statement generated from an original source location. */
+    getStatementsAtSourceLocation(sourcePath: string, sourceLine: number): JsProgramStatement[];
     getTokenizedLines(): RiscvTokenizedLine[];
     /**
      * Checks if the simulation can be undone.
@@ -369,7 +413,7 @@ interface JsRiscV {
      * @returns An array of `JsProgramStatement` objects representing the compiled program.
      */
     getCompiledStatements(): JsProgramStatement[];
-    getParsedStatements(): JsInstructionToken[];
+    getParsedStatements(): JsProgramStatement[];
     /**
      * Gets the label at the given address.
      * @param address The memory address.
@@ -459,6 +503,9 @@ interface JsRiscV {
     getUndoStack(): JsBackStep[];
     /**
      * Reads a sequence of bytes from memory.
+     *
+     * Reading through this method notifies no memory observer: inspecting memory from the host is
+     * not the program reading it, so a memory viewer never drives a memory-mapped register.
      * @param address The starting memory address.
      * @param length The number of bytes to read.
      * @returns An array of bytes read from memory.
@@ -466,15 +513,63 @@ interface JsRiscV {
     readMemoryBytes(address: number, length: number): number[];
     /**
      * Writes a sequence of bytes to memory.
+     *
+     * Unlike `readMemoryBytes`, this writes the way the program does: it notifies write observers
+     * and, while undo is enabled, records an undo step per byte. Use `setPeripheralWord` for a
+     * device keeping its own register up to date.
      * @param address The starting memory address.
      * @param bytes An array of bytes to write to memory.
      */
     setMemoryBytes(address: number, bytes: number[]): void;
     /**
-     * Gets the index of the current statement in the assembled program.
-     * @returns The index of the current statement.
+     * Writes one word as a peripheral would: no observer is notified and no undo step is recorded,
+     * because the write is not the program acting. This is how a device model refreshes a
+     * memory-mapped register - a ready bit, a pending character - without feeding its own observer
+     * or consuming undo history.
+     * @param address The word address, which must be word-aligned. Either form of a high address
+     * is accepted: `0xffff0000` and `0xffff0000 | 0` name the same word.
+     * @param value The 32 bit value to store, raw, without byte-order adjustment.
+     */
+    setPeripheralWord(address: number, value: number): void;
+    /**
+     * Observes every write in an address range, the shape a framebuffer wants.
+     *
+     * Both addresses must be word-aligned, `endAddress` is inclusive and covers its whole word, and
+     * the range may not cross 0x80000000 (split it in two registrations instead); a range that
+     * breaks any of these throws. Either form of a high address is accepted: `0xffff0000` and
+     * `0xffff0000 | 0` name the same word. The handler runs synchronously inside the storing instruction, so
+     * it must be cheap and must not write back into its own range; a returned promise is ignored.
+     *
+     * Observers live on the simulator's memory, which assembling and initializing only clear the
+     * contents of, so a registration survives `assemble()` and `initialize()`. For the same reason
+     * it is shared by every `JsRiscV` instance: register once per page, or remove the previous
+     * registration before registering again for a newly built program.
+     *
+     * Notifications only start once a program has been assembled, and undo notifies too: restoring
+     * memory during `undo()` goes through the same stores, so an observed range reports the
+     * restored values as ordinary writes.
+     * @returns A handle for `removeMemoryObserver`.
+     */
+    addMemoryWriteObserver(startAddress: number, endAddress: number, handler: MemoryWriteObserver): MemoryObserverHandle;
+    /**
+     * Observes reads and writes of a single word, the shape a memory-mapped register wants. The
+     * address must be word-aligned. Pass `null` for a direction you do not care about. The same
+     * lifetime and synchronous-handler rules as `addMemoryWriteObserver` apply.
+     * @returns A handle for `removeMemoryObserver`.
+     */
+    addMemoryAccessObserver(address: number, onRead: MemoryAccessObserver | null, onWrite: MemoryAccessObserver | null): MemoryObserverHandle;
+    /**
+     * Removes one registration. An unknown handle is ignored.
+     */
+    removeMemoryObserver(handle: MemoryObserverHandle): void;
+    /**
+     * Removes every registration.
+     */
+    removeMemoryObservers(): void;
+    /**
+     * The number of live registrations, across every `JsRiscV` instance.
      */
-    getCurrentStatementIndex(): number;
+    countMemoryObservers(): number;
     /**
      * Gets the next statement to be executed.
      * @returns The next `JsProgramStatement`.
@@ -493,15 +588,19 @@ interface JsRiscV {
     terminated: boolean;
 }
 /**
- * Creates a new RISCV simulator from the given source code.
- * @param source The source code to assemble.
+ * Creates a RISC-V simulator from a virtual source tree and its entry file.
+ *
+ * Source paths are canonical, root-relative, case-sensitive POSIX paths. The source set is
+ * snapshotted by this call; only the entry file and files reached through `.include` are assembled.
+ * @param files Source text keyed by canonical source path.
+ * @param entryFile Canonical path of the file from which include expansion starts.
  * @returns A new `JsRiscV` object.
  */
-declare function makeRiscVfromSource(source: string): JsRiscV;
+declare function makeRiscVFromFiles(files: RISCVSourceSet, entryFile: string): JsRiscV;
 /**
  * Initializes the RISCV simulator.
  */
 declare function initializeRISCV(): void;
 declare function bigintToHighLow(value: bigint): [high: number, low: number];
 
-export { BackStepAction, ConfirmResult, DialogType, type HandlerMap, type HandlerMapFns, type JsBackStep, type JsInstruction, type JsInstructionToken, type JsProgramStatement, type JsRiscV, type JsRiscVStackFrame, RISCV, type RISCVAssembleError, type RISCVAssembleResult, RISCVRegisters, RISCV_REGISTERS, type RegisterName, type RiscvTokenizedLine, StopReason, bigintToHighLow, registerHandlers, unimplementedHandler };
+export { BackStepAction, ConfirmResult, DialogType, type HandlerMap, type HandlerMapFns, type JsBackStep, type JsInstruction, type JsInstructionToken, type JsProgramStatement, type JsRiscV, type JsRiscVStackFrame, type MemoryAccessObserver, type MemoryObserverHandle, type MemoryWriteObserver, RISCV, type RISCVAssembleError, type RISCVAssembleResult, RISCVRegisters, type RISCVSourceLocation, type RISCVSourceSet, RISCV_REGISTERS, type RegisterName, type RiscvTokenizedLine, StopReason, bigintToHighLow, makeRiscVFromFiles, registerHandlers, unimplementedHandler };