@joezilla/8sim 0.10.0

package/dist/machine/MachineRunner.js

@@ -0,0 +1,102 @@
+import { SystemClock } from '../clock/SystemClock.js';
+/** Steps executed per tick in 'max' mode. */
+const MAX_SPEED_BATCH = 40_000;
+/** Longest uninterrupted wall-time slice while catching up (keeps I/O live). */
+const MAX_SLICE_MS = 20;
+/** Behind by more than this → forfeit the lost time instead of sprinting. */
+const RESYNC_BEHIND_MS = 250;
+/**
+ * Drives a CPU's step() loop at a configurable real-time speed.
+ *
+ * Throttled mode runs the CPU in ~1 ms slices of simulated time and compares
+ * simulated progress against wall time (absolute accounting via SystemClock,
+ * so timer jitter self-corrects): ahead → sleep the difference; behind → keep
+ * stepping up to MAX_SLICE_MS per tick, then yield so host I/O stays
+ * responsive. Host stalls beyond RESYNC_BEHIND_MS are forfeited rather than
+ * replayed at full speed.
+ */
+export class MachineRunner {
+    cpu;
+    hz;
+    clock;
+    schedule;
+    onError;
+    now;
+    running = false;
+    startedAt = 0;
+    cyclesAtStart = 0n;
+    constructor(cpu, options = {}) {
+        this.cpu = cpu;
+        this.hz = options.hz ?? 2_000_000;
+        this.now = options.now ?? (() => performance.now());
+        this.clock = new SystemClock(typeof this.hz === 'number' ? this.hz : 2_000_000, this.now);
+        this.schedule = options.schedule ?? ((fn, ms) => setTimeout(fn, ms));
+        this.onError = options.onError ?? ((err) => { console.error('[MachineRunner]', err); });
+    }
+    get targetHz() {
+        return this.hz;
+    }
+    /** Measured average speed in Hz since start() — for status displays. */
+    get effectiveHz() {
+        const wallSec = (this.now() - this.startedAt) / 1000;
+        if (!this.running || wallSec <= 0)
+            return 0;
+        return Number(this.clock.getElapsedCycles() - this.cyclesAtStart) / wallSec;
+    }
+    get isRunning() {
+        return this.running;
+    }
+    /** Total simulated T-states executed across the runner's lifetime. */
+    get elapsedCycles() {
+        return this.clock.getElapsedCycles();
+    }
+    start() {
+        if (this.running)
+            return;
+        this.running = true;
+        this.startedAt = this.now();
+        this.cyclesAtStart = this.clock.getElapsedCycles();
+        this.clock.resync();
+        this.schedule(this.tick, 0);
+    }
+    stop() {
+        this.running = false;
+    }
+    /** Change speed while running; pacing restarts from this moment. */
+    setHz(hz) {
+        this.hz = hz;
+        // Re-baseline either way: entering throttled mode after a 'max' stint
+        // would otherwise see the simulation absurdly far ahead and sleep for it.
+        this.clock.setHz(typeof hz === 'number' ? hz : this.clock.targetHz);
+    }
+    tick = () => {
+        if (!this.running)
+            return;
+        try {
+            if (this.hz === 'max') {
+                for (let i = 0; i < MAX_SPEED_BATCH; i++)
+                    this.clock.addCycles(this.cpu.step());
+                this.schedule(this.tick, 0);
+                return;
+            }
+            // Host stalled (GC, suspended tab): forfeit the lost time.
+            if (this.clock.getAheadMs() < -RESYNC_BEHIND_MS)
+                this.clock.resync();
+            const chunk = Math.max(1, Math.floor(this.hz / 1000)); // ~1 ms of simulated time
+            const sliceStart = this.now();
+            do {
+                let cycles = 0;
+                while (cycles < chunk)
+                    cycles += this.cpu.step();
+                this.clock.addCycles(cycles);
+            } while (this.clock.getAheadMs() < 0 && this.now() - sliceStart < MAX_SLICE_MS);
+            const aheadMs = this.clock.getAheadMs();
+            this.schedule(this.tick, aheadMs > 1 ? Math.floor(aheadMs) : 0);
+        }
+        catch (err) {
+            this.running = false;
+            this.onError(err);
+        }
+    };
+}
+//# sourceMappingURL=MachineRunner.js.map

package/dist/machine/MachineRunner.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"MachineRunner.js","sourceRoot":"","sources":["../../src/machine/MachineRunner.ts"],"names":[],"mappings":"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"}

package/dist/machine/MachineSpec.d.ts

@@ -0,0 +1,80 @@
+import type { IInterruptController } from '../interfaces/IInterruptController.js';
+import type { IS100Card } from '../interfaces/IS100Card.js';
+import type { ICpu } from '../interfaces/ICpu.js';
+import type { Bus } from '../bus/Bus.js';
+import type { MachineRunner } from './MachineRunner.js';
+/**
+ * Normative declarative description of a machine (AD-1). `buildMachine(spec)`
+ * turns this into a running Bus+CPU+cards deterministically. Kept 8sim-native
+ * and minimal: the rich, portable "Machine Profile" (catalog, identity,
+ * versioning) lives in fdcplus-web; the MachineSpec is only what the engine
+ * needs to construct a machine.
+ *
+ * Per AD-2 the engine is code-loading-agnostic: a card entry carries an
+ * ALREADY-LOADED `factory` (a live function), never a bundle reference — 8sim
+ * never imports anything.
+ */
+/** Closed CPU enum — no silent default. */
+export type CpuKind = 'i8080' | 'z80';
+/** Target clock: a frequency in Hz, or unthrottled. */
+export type Clock = {
+    hz: number;
+} | 'max';
+/** A typed memory region. `mmio` is reserved for forward-compat; cards provide
+ * memory-mapped I/O via MemoryMappedIOAdapter at attach time, so buildMachine
+ * supports `ram` and `rom` and rejects `mmio` in this build. */
+export interface MemoryRegionSpec {
+    id: string;
+    base: number;
+    size: number;
+    kind: 'ram' | 'rom' | 'mmio';
+    image?: Uint8Array;
+}
+/** Instance-scoped dependencies injected into a card factory (AD-5). 8sim
+ * supplies `pic` and `log`; the caller (fdcplus-web) supplies the FDC channel
+ * and anything else through `services`. Dumb cards ignore it. */
+export interface CardContext {
+    pic: IInterruptController;
+    log: (message: string) => void;
+    services: Record<string, unknown>;
+}
+/** An already-loaded card factory (AD-2). */
+export type CardFactory = (id: string, config: Record<string, unknown>, ctx: CardContext) => IS100Card;
+export interface CardSpec {
+    id: string;
+    factory: CardFactory;
+    config?: Record<string, unknown>;
+    /** Declared bus resources, used for define-time collision rejection (AD-1).
+     * The engine's IoSpace is last-writer-wins and the PIC has no ownership, so
+     * buildMachine asserts these are collision-free rather than trusting silence. */
+    claims?: {
+        ports?: number[];
+        irq?: number | null;
+    };
+}
+export interface MachineSpec {
+    cpuKind: CpuKind;
+    clock: Clock;
+    /** Program counter at power-on (e.g. 0xFF00 for CDBL). Construction is data,
+     * not an imperative `cpu.pc = …` step. */
+    resetVector: number;
+    /** Memory regions; attached in array order (overlaps are rejected). */
+    memory: MemoryRegionSpec[];
+    /** Cards in slot order; attached after memory, before the CPU runs. */
+    cards: CardSpec[];
+}
+/** The runnable handle buildMachine returns. */
+export interface Machine {
+    cpu: ICpu;
+    bus: Bus;
+    pic: IInterruptController;
+    cards: IS100Card[];
+    runner: MachineRunner;
+    spec: MachineSpec;
+}
+/** Thrown when a MachineSpec is invalid or would build an inconsistent machine.
+ * Plain Error subclass — 8sim stays zero-dep and browser-portable. */
+export declare class MachineSpecError extends Error {
+    constructor(message: string);
+}
+//# sourceMappingURL=MachineSpec.d.ts.map

package/dist/machine/MachineSpec.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"MachineSpec.d.ts","sourceRoot":"","sources":["../../src/machine/MachineSpec.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,uCAAuC,CAAC;AAClF,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,4BAA4B,CAAC;AAC5D,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,uBAAuB,CAAC;AAClD,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,eAAe,CAAC;AACzC,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAExD;;;;;;;;;;GAUG;AAEH,2CAA2C;AAC3C,MAAM,MAAM,OAAO,GAAG,OAAO,GAAG,KAAK,CAAC;AAEtC,uDAAuD;AACvD,MAAM,MAAM,KAAK,GAAG;IAAE,EAAE,EAAE,MAAM,CAAA;CAAE,GAAG,KAAK,CAAC;AAE3C;;gEAEgE;AAChE,MAAM,WAAW,gBAAgB;IAC/B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,KAAK,GAAG,KAAK,GAAG,MAAM,CAAC;IAC7B,KAAK,CAAC,EAAE,UAAU,CAAC;CACpB;AAED;;iEAEiE;AACjE,MAAM,WAAW,WAAW;IAC1B,GAAG,EAAE,oBAAoB,CAAC;IAC1B,GAAG,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;IAC/B,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACnC;AAED,6CAA6C;AAC7C,MAAM,MAAM,WAAW,GAAG,CACxB,EAAE,EAAE,MAAM,EACV,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/B,GAAG,EAAE,WAAW,KACb,SAAS,CAAC;AAEf,MAAM,WAAW,QAAQ;IACvB,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,EAAE,WAAW,CAAC;IACrB,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACjC;;qFAEiF;IACjF,MAAM,CAAC,EAAE;QACP,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;QACjB,GAAG,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;KACrB,CAAC;CACH;AAED,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,OAAO,CAAC;IACjB,KAAK,EAAE,KAAK,CAAC;IACb;8CAC0C;IAC1C,WAAW,EAAE,MAAM,CAAC;IACpB,uEAAuE;IACvE,MAAM,EAAE,gBAAgB,EAAE,CAAC;IAC3B,uEAAuE;IACvE,KAAK,EAAE,QAAQ,EAAE,CAAC;CACnB;AAED,gDAAgD;AAChD,MAAM,WAAW,OAAO;IACtB,GAAG,EAAE,IAAI,CAAC;IACV,GAAG,EAAE,GAAG,CAAC;IACT,GAAG,EAAE,oBAAoB,CAAC;IAC1B,KAAK,EAAE,SAAS,EAAE,CAAC;IACnB,MAAM,EAAE,aAAa,CAAC;IACtB,IAAI,EAAE,WAAW,CAAC;CACnB;AAED;sEACsE;AACtE,qBAAa,gBAAiB,SAAQ,KAAK;gBAC7B,OAAO,EAAE,MAAM;CAI5B"}

package/dist/machine/MachineSpec.js

@@ -0,0 +1,9 @@
+/** Thrown when a MachineSpec is invalid or would build an inconsistent machine.
+ * Plain Error subclass — 8sim stays zero-dep and browser-portable. */
+export class MachineSpecError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'MachineSpecError';
+    }
+}
+//# sourceMappingURL=MachineSpec.js.map

package/dist/machine/MachineSpec.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"MachineSpec.js","sourceRoot":"","sources":["../../src/machine/MachineSpec.ts"],"names":[],"mappings":"AAsFA;sEACsE;AACtE,MAAM,OAAO,gBAAiB,SAAQ,KAAK;IACzC,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,kBAAkB,CAAC;IACjC,CAAC;CACF"}

package/dist/machine/buildMachine.d.ts

@@ -0,0 +1,19 @@
+import { type MachineSpec, type Machine } from './MachineSpec.js';
+export interface BuildOptions {
+    /** Per-machine logger injected into each card's CardContext. */
+    log?: (message: string) => void;
+    /** Caller-supplied instance-scoped services (e.g. the FDC channel a disk
+     * controller card pulls from `ctx.services`). */
+    services?: Record<string, unknown>;
+}
+/**
+ * Validate a MachineSpec and build a runnable machine (AD-1, AD-2).
+ *
+ * Construction order is pinned: memory regions (array order) → cards (slot
+ * order) → CPU. All collisions are rejected here — the Bus is first-region-wins
+ * and IoSpace is last-writer-wins, so a silently-overlapping spec would produce
+ * a wrong machine. `buildMachine` never loads code: each card entry carries an
+ * already-loaded factory.
+ */
+export declare function buildMachine(spec: MachineSpec, opts?: BuildOptions): Machine;
+//# sourceMappingURL=buildMachine.d.ts.map

package/dist/machine/buildMachine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"buildMachine.d.ts","sourceRoot":"","sources":["../../src/machine/buildMachine.ts"],"names":[],"mappings":"AAQA,OAAO,EAEL,KAAK,WAAW,EAChB,KAAK,OAAO,EAGb,MAAM,kBAAkB,CAAC;AAE1B,MAAM,WAAW,YAAY;IAC3B,gEAAgE;IAChE,GAAG,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;IAChC;qDACiD;IACjD,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC;AAKD;;;;;;;;GAQG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,WAAW,EAAE,IAAI,GAAE,YAAiB,GAAG,OAAO,CA8ChF"}

package/dist/machine/buildMachine.js

@@ -0,0 +1,122 @@
+import { Bus } from '../bus/Bus.js';
+import { Ram } from '../memory/Ram.js';
+import { Rom } from '../memory/Rom.js';
+import { InterruptController } from '../interrupt/InterruptController.js';
+import { Cpu8080 } from '../cpu/Cpu8080.js';
+import { CpuZ80 } from '../cpu/z80/CpuZ80.js';
+import { MachineRunner } from './MachineRunner.js';
+import { MachineSpecError, } from './MachineSpec.js';
+const inU16 = (n) => Number.isInteger(n) && n >= 0 && n <= 0xffff;
+const regionEnd = (r) => r.base + r.size - 1;
+/**
+ * Validate a MachineSpec and build a runnable machine (AD-1, AD-2).
+ *
+ * Construction order is pinned: memory regions (array order) → cards (slot
+ * order) → CPU. All collisions are rejected here — the Bus is first-region-wins
+ * and IoSpace is last-writer-wins, so a silently-overlapping spec would produce
+ * a wrong machine. `buildMachine` never loads code: each card entry carries an
+ * already-loaded factory.
+ */
+export function buildMachine(spec, opts = {}) {
+    validate(spec);
+    const pic = new InterruptController();
+    const bus = new Bus(pic);
+    // 1) Memory regions, in array order.
+    for (const region of spec.memory) {
+        if (region.kind === 'rom') {
+            bus.attachMemory(new Rom(region.id, region.base, region.image));
+        }
+        else {
+            // ram
+            const ram = new Ram(region.id, region.base, region.size);
+            if (region.image) {
+                for (let i = 0; i < region.image.length; i++)
+                    ram.write(i, region.image[i]);
+            }
+            bus.attachMemory(ram);
+        }
+    }
+    // 2) Cards, in slot order. Each factory is already loaded (AD-2).
+    // NOTE (forward-compat gap): a card may attach its own memory (a
+    // memory-mapped I/O card via MemoryMappedIOAdapter) through `attach(bus)`,
+    // which bypasses the declarative memory-region overlap check above. No seed
+    // card does this today; when memory-mapped cards land, their regions must be
+    // declared and validated too (tracked with the deferred `mmio` region kind).
+    const ctx = {
+        pic,
+        log: opts.log ?? (() => { }),
+        services: opts.services ?? {},
+    };
+    const cards = [];
+    for (const card of spec.cards) {
+        const built = card.factory(card.id, card.config ?? {}, ctx);
+        built.attach(bus);
+        cards.push(built);
+    }
+    // 3) CPU last; power-on PC comes from the spec, not an imperative step.
+    const cpu = spec.cpuKind === 'z80' ? new CpuZ80(bus, pic) : new Cpu8080(bus, pic);
+    cpu.reset();
+    cpu.pc = spec.resetVector;
+    const runner = new MachineRunner(cpu, { hz: spec.clock === 'max' ? 'max' : spec.clock.hz });
+    return { cpu, bus, pic, cards, runner, spec };
+}
+function validate(spec) {
+    if (spec.cpuKind !== 'i8080' && spec.cpuKind !== 'z80') {
+        throw new MachineSpecError(`cpuKind must be "i8080" or "z80", got ${JSON.stringify(spec.cpuKind)}`);
+    }
+    if (spec.clock !== 'max' && !(typeof spec.clock === 'object' && spec.clock.hz > 0)) {
+        throw new MachineSpecError(`clock must be "max" or { hz: >0 }, got ${JSON.stringify(spec.clock)}`);
+    }
+    if (!inU16(spec.resetVector)) {
+        throw new MachineSpecError(`resetVector must be an integer in 0x0000..0xFFFF, got ${spec.resetVector}`);
+    }
+    // Memory regions: shape + bounds.
+    for (const r of spec.memory) {
+        if (r.kind === 'mmio') {
+            throw new MachineSpecError(`memory region "${r.id}": kind "mmio" is not supported by buildMachine (memory-mapped I/O is provided by cards)`);
+        }
+        if (!inU16(r.base) || !Number.isInteger(r.size) || r.size < 1 || r.base + r.size > 0x10000) {
+            throw new MachineSpecError(`memory region "${r.id}": invalid base/size (base=${r.base}, size=${r.size}); must fit within 0x0000..0xFFFF`);
+        }
+        if (r.kind === 'rom' && (!r.image || r.image.length !== r.size)) {
+            throw new MachineSpecError(`memory region "${r.id}": rom requires an image whose length (${r.image?.length ?? 0}) equals size (${r.size})`);
+        }
+        if (r.kind === 'ram' && r.image && r.image.length > r.size) {
+            throw new MachineSpecError(`memory region "${r.id}": ram image length (${r.image.length}) exceeds size (${r.size})`);
+        }
+    }
+    // Memory overlaps: sort a copy by base, check neighbours.
+    const sorted = [...spec.memory].sort((a, b) => a.base - b.base);
+    for (let i = 0; i + 1 < sorted.length; i++) {
+        const a = sorted[i];
+        const b = sorted[i + 1];
+        if (regionEnd(a) >= b.base) {
+            throw new MachineSpecError(`memory regions overlap: "${a.id}" (0x${a.base.toString(16)}-0x${regionEnd(a).toString(16)}) and ` +
+                `"${b.id}" (0x${b.base.toString(16)}-0x${regionEnd(b).toString(16)})`);
+        }
+    }
+    // I/O port collisions across card claims.
+    const portOwner = new Map();
+    for (const card of spec.cards) {
+        for (const port of card.claims?.ports ?? []) {
+            const prev = portOwner.get(port & 0xff);
+            if (prev !== undefined) {
+                throw new MachineSpecError(`I/O port 0x${(port & 0xff).toString(16)} claimed by both "${prev}" and "${card.id}"`);
+            }
+            portOwner.set(port & 0xff, card.id);
+        }
+    }
+    // IRQ line collisions across card claims.
+    const irqOwner = new Map();
+    for (const card of spec.cards) {
+        const irq = card.claims?.irq;
+        if (irq === undefined || irq === null)
+            continue;
+        const prev = irqOwner.get(irq);
+        if (prev !== undefined) {
+            throw new MachineSpecError(`IRQ line ${irq} claimed by both "${prev}" and "${card.id}"`);
+        }
+        irqOwner.set(irq, card.id);
+    }
+}
+//# sourceMappingURL=buildMachine.js.map

package/dist/machine/buildMachine.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"buildMachine.js","sourceRoot":"","sources":["../../src/machine/buildMachine.ts"],"names":[],"mappings":"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"}

package/dist/memory/MemoryMappedIOAdapter.d.ts

@@ -0,0 +1,14 @@
+import type { IMemory } from '../interfaces/IMemory.js';
+import type { IIODevice } from '../interfaces/IIODevice.js';
+export declare class MemoryMappedIOAdapter implements IMemory {
+    readonly id: string;
+    readonly baseAddress: number;
+    readonly size: number;
+    readonly readOnly = false;
+    private device;
+    constructor(baseAddress: number, size: number, device: IIODevice);
+    read(offset: number): number;
+    write(offset: number, value: number): void;
+    reset(): void;
+}
+//# sourceMappingURL=MemoryMappedIOAdapter.d.ts.map

package/dist/memory/MemoryMappedIOAdapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"MemoryMappedIOAdapter.d.ts","sourceRoot":"","sources":["../../src/memory/MemoryMappedIOAdapter.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,0BAA0B,CAAC;AACxD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,4BAA4B,CAAC;AAE5D,qBAAa,qBAAsB,YAAW,OAAO;IACnD,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,QAAQ,SAAS;IAC1B,OAAO,CAAC,MAAM,CAAY;gBAEd,WAAW,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS;IAOhE,IAAI,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM;IAI5B,KAAK,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI;IAI1C,KAAK,IAAI,IAAI;CAGd"}

package/dist/memory/MemoryMappedIOAdapter.js

@@ -0,0 +1,23 @@
+export class MemoryMappedIOAdapter {
+    id;
+    baseAddress;
+    size;
+    readOnly = false;
+    device;
+    constructor(baseAddress, size, device) {
+        this.id = `mmio:${device.id}`;
+        this.baseAddress = baseAddress & 0xffff;
+        this.size = size;
+        this.device = device;
+    }
+    read(offset) {
+        return this.device.ioRead(offset);
+    }
+    write(offset, value) {
+        this.device.ioWrite(offset, value);
+    }
+    reset() {
+        this.device.reset();
+    }
+}
+//# sourceMappingURL=MemoryMappedIOAdapter.js.map

package/dist/memory/MemoryMappedIOAdapter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"MemoryMappedIOAdapter.js","sourceRoot":"","sources":["../../src/memory/MemoryMappedIOAdapter.ts"],"names":[],"mappings":"AAGA,MAAM,OAAO,qBAAqB;IACvB,EAAE,CAAS;IACX,WAAW,CAAS;IACpB,IAAI,CAAS;IACb,QAAQ,GAAG,KAAK,CAAC;IAClB,MAAM,CAAY;IAE1B,YAAY,WAAmB,EAAE,IAAY,EAAE,MAAiB;QAC9D,IAAI,CAAC,EAAE,GAAG,QAAQ,MAAM,CAAC,EAAE,EAAE,CAAC;QAC9B,IAAI,CAAC,WAAW,GAAG,WAAW,GAAG,MAAM,CAAC;QACxC,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;IACvB,CAAC;IAED,IAAI,CAAC,MAAc;QACjB,OAAO,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;IACpC,CAAC;IAED,KAAK,CAAC,MAAc,EAAE,KAAa;QACjC,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;IACrC,CAAC;IAED,KAAK;QACH,IAAI,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC;IACtB,CAAC;CACF"}

package/dist/memory/Ram.d.ts

@@ -0,0 +1,17 @@
+import type { IMemory } from '../interfaces/IMemory.js';
+export declare class Ram implements IMemory {
+    readonly id: string;
+    readonly baseAddress: number;
+    readonly size: number;
+    readonly readOnly = false;
+    private data;
+    constructor(id: string, baseAddress: number, size: number);
+    read(offset: number): number;
+    write(offset: number, value: number): void;
+    reset(): void;
+    /** Load bytes into RAM starting at offset */
+    load(data: Uint8Array, offset?: number): void;
+    /** Direct access for testing */
+    getBytes(): Uint8Array;
+}
+//# sourceMappingURL=Ram.d.ts.map

package/dist/memory/Ram.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Ram.d.ts","sourceRoot":"","sources":["../../src/memory/Ram.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,0BAA0B,CAAC;AAGxD,qBAAa,GAAI,YAAW,OAAO;IACjC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,QAAQ,SAAS;IAC1B,OAAO,CAAC,IAAI,CAAa;gBAEb,EAAE,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM;IAOzD,IAAI,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM;IAK5B,KAAK,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI;IAK1C,KAAK,IAAI,IAAI;IAIb,6CAA6C;IAC7C,IAAI,CAAC,IAAI,EAAE,UAAU,EAAE,MAAM,SAAI,GAAG,IAAI;IAIxC,gCAAgC;IAChC,QAAQ,IAAI,UAAU;CAGvB"}

package/dist/memory/Ram.js

@@ -0,0 +1,36 @@
+import { u8 } from '../util/bits.js';
+export class Ram {
+    id;
+    baseAddress;
+    size;
+    readOnly = false;
+    data;
+    constructor(id, baseAddress, size) {
+        this.id = id;
+        this.baseAddress = baseAddress & 0xffff;
+        this.size = size;
+        this.data = new Uint8Array(size);
+    }
+    read(offset) {
+        if (offset < 0 || offset >= this.size)
+            return 0xff;
+        return this.data[offset] ?? 0xff;
+    }
+    write(offset, value) {
+        if (offset < 0 || offset >= this.size)
+            return;
+        this.data[offset] = u8(value);
+    }
+    reset() {
+        this.data.fill(0);
+    }
+    /** Load bytes into RAM starting at offset */
+    load(data, offset = 0) {
+        this.data.set(data, offset);
+    }
+    /** Direct access for testing */
+    getBytes() {
+        return this.data;
+    }
+}
+//# sourceMappingURL=Ram.js.map

package/dist/memory/Ram.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Ram.js","sourceRoot":"","sources":["../../src/memory/Ram.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,EAAE,EAAE,MAAM,iBAAiB,CAAC;AAErC,MAAM,OAAO,GAAG;IACL,EAAE,CAAS;IACX,WAAW,CAAS;IACpB,IAAI,CAAS;IACb,QAAQ,GAAG,KAAK,CAAC;IAClB,IAAI,CAAa;IAEzB,YAAY,EAAU,EAAE,WAAmB,EAAE,IAAY;QACvD,IAAI,CAAC,EAAE,GAAG,EAAE,CAAC;QACb,IAAI,CAAC,WAAW,GAAG,WAAW,GAAG,MAAM,CAAC;QACxC,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,IAAI,GAAG,IAAI,UAAU,CAAC,IAAI,CAAC,CAAC;IACnC,CAAC;IAED,IAAI,CAAC,MAAc;QACjB,IAAI,MAAM,GAAG,CAAC,IAAI,MAAM,IAAI,IAAI,CAAC,IAAI;YAAE,OAAO,IAAI,CAAC;QACnD,OAAO,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,IAAI,CAAC;IACnC,CAAC;IAED,KAAK,CAAC,MAAc,EAAE,KAAa;QACjC,IAAI,MAAM,GAAG,CAAC,IAAI,MAAM,IAAI,IAAI,CAAC,IAAI;YAAE,OAAO;QAC9C,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,GAAG,EAAE,CAAC,KAAK,CAAC,CAAC;IAChC,CAAC;IAED,KAAK;QACH,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IACpB,CAAC;IAED,6CAA6C;IAC7C,IAAI,CAAC,IAAgB,EAAE,MAAM,GAAG,CAAC;QAC/B,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;IAC9B,CAAC;IAED,gCAAgC;IAChC,QAAQ;QACN,OAAO,IAAI,CAAC,IAAI,CAAC;IACnB,CAAC;CACF"}

package/dist/memory/Rom.d.ts

@@ -0,0 +1,13 @@
+import type { IMemory } from '../interfaces/IMemory.js';
+export declare class Rom implements IMemory {
+    readonly id: string;
+    readonly baseAddress: number;
+    readonly size: number;
+    readonly readOnly = true;
+    private data;
+    constructor(id: string, baseAddress: number, data: Uint8Array);
+    read(offset: number): number;
+    write(_offset: number, _value: number): void;
+    reset(): void;
+}
+//# sourceMappingURL=Rom.d.ts.map

package/dist/memory/Rom.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Rom.d.ts","sourceRoot":"","sources":["../../src/memory/Rom.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,0BAA0B,CAAC;AAExD,qBAAa,GAAI,YAAW,OAAO;IACjC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,QAAQ,QAAQ;IACzB,OAAO,CAAC,IAAI,CAAa;gBAEb,EAAE,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,IAAI,EAAE,UAAU;IAO7D,IAAI,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM;IAK5B,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI;IAI5C,KAAK,IAAI,IAAI;CAGd"}

package/dist/memory/Rom.js

@@ -0,0 +1,25 @@
+export class Rom {
+    id;
+    baseAddress;
+    size;
+    readOnly = true;
+    data;
+    constructor(id, baseAddress, data) {
+        this.id = id;
+        this.baseAddress = baseAddress & 0xffff;
+        this.size = data.length;
+        this.data = new Uint8Array(data);
+    }
+    read(offset) {
+        if (offset < 0 || offset >= this.size)
+            return 0xff;
+        return this.data[offset] ?? 0xff;
+    }
+    write(_offset, _value) {
+        // ROM is read-only; writes silently ignored
+    }
+    reset() {
+        // ROM content is immutable
+    }
+}
+//# sourceMappingURL=Rom.js.map

package/dist/memory/Rom.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Rom.js","sourceRoot":"","sources":["../../src/memory/Rom.ts"],"names":[],"mappings":"AAEA,MAAM,OAAO,GAAG;IACL,EAAE,CAAS;IACX,WAAW,CAAS;IACpB,IAAI,CAAS;IACb,QAAQ,GAAG,IAAI,CAAC;IACjB,IAAI,CAAa;IAEzB,YAAY,EAAU,EAAE,WAAmB,EAAE,IAAgB;QAC3D,IAAI,CAAC,EAAE,GAAG,EAAE,CAAC;QACb,IAAI,CAAC,WAAW,GAAG,WAAW,GAAG,MAAM,CAAC;QACxC,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC,MAAM,CAAC;QACxB,IAAI,CAAC,IAAI,GAAG,IAAI,UAAU,CAAC,IAAI,CAAC,CAAC;IACnC,CAAC;IAED,IAAI,CAAC,MAAc;QACjB,IAAI,MAAM,GAAG,CAAC,IAAI,MAAM,IAAI,IAAI,CAAC,IAAI;YAAE,OAAO,IAAI,CAAC;QACnD,OAAO,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,IAAI,CAAC;IACnC,CAAC;IAED,KAAK,CAAC,OAAe,EAAE,MAAc;QACnC,4CAA4C;IAC9C,CAAC;IAED,KAAK;QACH,2BAA2B;IAC7B,CAAC;CACF"}

package/dist/util/bits.d.ts

@@ -0,0 +1,11 @@
+export declare function u8(v: number): number;
+export declare function u16(v: number): number;
+export declare function signBit(v: number): boolean;
+export declare function zeroFlag(v: number): boolean;
+export declare function parityFlag(v: number): boolean;
+export declare function auxCarryAdd(a: number, b: number, carry?: number): boolean;
+export declare function auxCarrySub(a: number, b: number, borrow?: number): boolean;
+export declare function toWord(hi: number, lo: number): number;
+export declare function hi(w: number): number;
+export declare function lo(w: number): number;
+//# sourceMappingURL=bits.d.ts.map

package/dist/util/bits.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bits.d.ts","sourceRoot":"","sources":["../../src/util/bits.ts"],"names":[],"mappings":"AAAA,wBAAgB,EAAE,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAEpC;AAED,wBAAgB,GAAG,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAErC;AAED,wBAAgB,OAAO,CAAC,CAAC,EAAE,MAAM,GAAG,OAAO,CAE1C;AAED,wBAAgB,QAAQ,CAAC,CAAC,EAAE,MAAM,GAAG,OAAO,CAE3C;AAED,wBAAgB,UAAU,CAAC,CAAC,EAAE,MAAM,GAAG,OAAO,CAM7C;AAED,wBAAgB,WAAW,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,KAAK,SAAI,GAAG,OAAO,CAEpE;AAED,wBAAgB,WAAW,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,MAAM,SAAI,GAAG,OAAO,CAErE;AAED,wBAAgB,MAAM,CAAC,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,MAAM,CAErD;AAED,wBAAgB,EAAE,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAEpC;AAED,wBAAgB,EAAE,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAEpC"}

package/dist/util/bits.js

@@ -0,0 +1,35 @@
+export function u8(v) {
+    return v & 0xff;
+}
+export function u16(v) {
+    return v & 0xffff;
+}
+export function signBit(v) {
+    return (v & 0x80) !== 0;
+}
+export function zeroFlag(v) {
+    return (v & 0xff) === 0;
+}
+export function parityFlag(v) {
+    let x = v & 0xff;
+    x ^= x >> 4;
+    x ^= x >> 2;
+    x ^= x >> 1;
+    return (x & 1) === 0;
+}
+export function auxCarryAdd(a, b, carry = 0) {
+    return ((a & 0xf) + (b & 0xf) + carry) > 0xf;
+}
+export function auxCarrySub(a, b, borrow = 0) {
+    return ((a & 0xf) - (b & 0xf) - borrow) < 0;
+}
+export function toWord(hi, lo) {
+    return ((hi & 0xff) << 8) | (lo & 0xff);
+}
+export function hi(w) {
+    return (w >> 8) & 0xff;
+}
+export function lo(w) {
+    return w & 0xff;
+}
+//# sourceMappingURL=bits.js.map

package/dist/util/bits.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bits.js","sourceRoot":"","sources":["../../src/util/bits.ts"],"names":[],"mappings":"AAAA,MAAM,UAAU,EAAE,CAAC,CAAS;IAC1B,OAAO,CAAC,GAAG,IAAI,CAAC;AAClB,CAAC;AAED,MAAM,UAAU,GAAG,CAAC,CAAS;IAC3B,OAAO,CAAC,GAAG,MAAM,CAAC;AACpB,CAAC;AAED,MAAM,UAAU,OAAO,CAAC,CAAS;IAC/B,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC;AAC1B,CAAC;AAED,MAAM,UAAU,QAAQ,CAAC,CAAS;IAChC,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC;AAC1B,CAAC;AAED,MAAM,UAAU,UAAU,CAAC,CAAS;IAClC,IAAI,CAAC,GAAG,CAAC,GAAG,IAAI,CAAC;IACjB,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACZ,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACZ,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACZ,OAAO,CAAC,CAAC,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC;AACvB,CAAC;AAED,MAAM,UAAU,WAAW,CAAC,CAAS,EAAE,CAAS,EAAE,KAAK,GAAG,CAAC;IACzD,OAAO,CAAC,CAAC,CAAC,GAAG,GAAG,CAAC,GAAG,CAAC,CAAC,GAAG,GAAG,CAAC,GAAG,KAAK,CAAC,GAAG,GAAG,CAAC;AAC/C,CAAC;AAED,MAAM,UAAU,WAAW,CAAC,CAAS,EAAE,CAAS,EAAE,MAAM,GAAG,CAAC;IAC1D,OAAO,CAAC,CAAC,CAAC,GAAG,GAAG,CAAC,GAAG,CAAC,CAAC,GAAG,GAAG,CAAC,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC;AAC9C,CAAC;AAED,MAAM,UAAU,MAAM,CAAC,EAAU,EAAE,EAAU;IAC3C,OAAO,CAAC,CAAC,EAAE,GAAG,IAAI,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,EAAE,GAAG,IAAI,CAAC,CAAC;AAC1C,CAAC;AAED,MAAM,UAAU,EAAE,CAAC,CAAS;IAC1B,OAAO,CAAC,CAAC,IAAI,CAAC,CAAC,GAAG,IAAI,CAAC;AACzB,CAAC;AAED,MAAM,UAAU,EAAE,CAAC,CAAS;IAC1B,OAAO,CAAC,GAAG,IAAI,CAAC;AAClB,CAAC"}

package/dist/util/hostConsole.d.ts

@@ -0,0 +1,2 @@
+export declare function writeHostStdout(text: string): void;
+//# sourceMappingURL=hostConsole.d.ts.map

package/dist/util/hostConsole.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hostConsole.d.ts","sourceRoot":"","sources":["../../src/util/hostConsole.ts"],"names":[],"mappings":"AAOA,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAElD"}

package/dist/util/hostConsole.js

@@ -0,0 +1,4 @@
+export function writeHostStdout(text) {
+    globalThis.process?.stdout?.write(text);
+}
+//# sourceMappingURL=hostConsole.js.map

package/dist/util/hostConsole.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hostConsole.js","sourceRoot":"","sources":["../../src/util/hostConsole.ts"],"names":[],"mappings":"AAOA,MAAM,UAAU,eAAe,CAAC,IAAY;IACzC,UAAwC,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,IAAI,CAAC,CAAC;AACzE,CAAC"}