@celox-sim/celox 0.1.29 → 0.1.31

package/dist/wasm-bridge.d.ts

@@ -0,0 +1,62 @@
+/**
+ * WASM bridge for running simulation via browser WebAssembly.
+ *
+ * When the NAPI addon is compiled for wasm32 (no JIT backend), the
+ * NativeSimulatorHandle exposes `combWasmBytes()` and `eventWasmBytes(name)`
+ * instead of `tick()` / `evalComb()`.  This bridge instantiates those WASM
+ * modules and presents a handle that is compatible with the existing
+ * Simulator / DUT code.
+ *
+ * @module
+ */
+import type { NativeSimulatorHandle } from "./types.js";
+/**
+ * Handle shape returned by a wasm32-compiled NativeSimulatorHandle.
+ * Extends the standard metadata getters with WASM bytecode accessors.
+ */
+export interface RawWasmSimulatorHandle {
+    readonly layoutJson: string;
+    readonly eventsJson: string;
+    readonly hierarchyJson: string;
+    readonly warningsJson: string;
+    readonly stableSize: number;
+    readonly totalSize: number;
+    combWasmBytes(): Uint8Array | number[];
+    eventWasmBytes(name: string): Uint8Array | number[];
+    dispose(): void;
+}
+/**
+ * Detect if a handle was produced by a wasm32-compiled addon.
+ *
+ * WASM handles expose `combWasmBytes()` instead of `tick()`.
+ */
+export declare function isWasmHandle(handle: unknown): handle is RawWasmSimulatorHandle;
+/** Result of creating a WASM simulator bridge. */
+export interface WasmBridgeResult {
+    /** Handle compatible with the existing Simulator code. */
+    handle: NativeSimulatorHandle;
+    /** The raw shared memory as a Uint8Array (backed by WebAssembly.Memory). */
+    sharedMemory: Uint8Array;
+}
+/**
+ * Create a NativeSimulatorHandle-compatible wrapper from a wasm32-compiled
+ * NAPI handle.
+ *
+ * 1. Reads metadata (layout, events, sizes) from the raw handle.
+ * 2. Creates a WebAssembly.Memory large enough for the simulation state.
+ * 3. Synchronously compiles and instantiates the combinational and event
+ *    WASM modules, importing the shared memory.
+ * 4. Returns a handle whose `tick()` / `evalComb()` drive the WASM instances.
+ *
+ * @returns A bridge result with the wrapped handle and shared memory view.
+ */
+export declare function createWasmSimulatorBridge(raw: RawWasmSimulatorHandle): WasmBridgeResult;
+/**
+ * Asynchronous version of `createWasmSimulatorBridge` that uses
+ * `WebAssembly.compile()` + `WebAssembly.instantiate()`.
+ *
+ * Preferred for large modules in browsers where synchronous compilation
+ * may be rejected.
+ */
+export declare function createWasmSimulatorBridgeAsync(raw: RawWasmSimulatorHandle): Promise<WasmBridgeResult>;
+//# sourceMappingURL=wasm-bridge.d.ts.map

package/dist/wasm-bridge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"wasm-bridge.d.ts","sourceRoot":"","sources":["../src/wasm-bridge.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAC;AAmCxD;;;GAGG;AACH,MAAM,WAAW,sBAAsB;IACtC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,aAAa,IAAI,UAAU,GAAG,MAAM,EAAE,CAAC;IACvC,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,UAAU,GAAG,MAAM,EAAE,CAAC;IACpD,OAAO,IAAI,IAAI,CAAC;CAChB;AAMD;;;;GAIG;AACH,wBAAgB,YAAY,CAC3B,MAAM,EAAE,OAAO,GACb,MAAM,IAAI,sBAAsB,CAOlC;AAMD,kDAAkD;AAClD,MAAM,WAAW,gBAAgB;IAChC,0DAA0D;IAC1D,MAAM,EAAE,qBAAqB,CAAC;IAC9B,4EAA4E;IAC5E,YAAY,EAAE,UAAU,CAAC;CACzB;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,yBAAyB,CACxC,GAAG,EAAE,sBAAsB,GACzB,gBAAgB,CAqDlB;AAED;;;;;;GAMG;AACH,wBAAsB,8BAA8B,CACnD,GAAG,EAAE,sBAAsB,GACzB,OAAO,CAAC,gBAAgB,CAAC,CAsD3B"}

package/dist/wasm-bridge.js

@@ -0,0 +1,140 @@
+/**
+ * WASM bridge for running simulation via browser WebAssembly.
+ *
+ * When the NAPI addon is compiled for wasm32 (no JIT backend), the
+ * NativeSimulatorHandle exposes `combWasmBytes()` and `eventWasmBytes(name)`
+ * instead of `tick()` / `evalComb()`.  This bridge instantiates those WASM
+ * modules and presents a handle that is compatible with the existing
+ * Simulator / DUT code.
+ *
+ * @module
+ */
+// ---------------------------------------------------------------------------
+// Detection
+// ---------------------------------------------------------------------------
+/**
+ * Detect if a handle was produced by a wasm32-compiled addon.
+ *
+ * WASM handles expose `combWasmBytes()` instead of `tick()`.
+ */
+export function isWasmHandle(handle) {
+    return (typeof handle === "object" &&
+        handle !== null &&
+        typeof handle.combWasmBytes === "function" &&
+        typeof handle.tick !== "function");
+}
+/**
+ * Create a NativeSimulatorHandle-compatible wrapper from a wasm32-compiled
+ * NAPI handle.
+ *
+ * 1. Reads metadata (layout, events, sizes) from the raw handle.
+ * 2. Creates a WebAssembly.Memory large enough for the simulation state.
+ * 3. Synchronously compiles and instantiates the combinational and event
+ *    WASM modules, importing the shared memory.
+ * 4. Returns a handle whose `tick()` / `evalComb()` drive the WASM instances.
+ *
+ * @returns A bridge result with the wrapped handle and shared memory view.
+ */
+export function createWasmSimulatorBridge(raw) {
+    const totalSize = raw.totalSize;
+    const stableSize = raw.stableSize;
+    // Create shared WebAssembly.Memory
+    const pages = Math.max(1, Math.ceil(totalSize / 65536));
+    const memory = new WebAssembly.Memory({ initial: pages });
+    // Compile and instantiate comb WASM module (synchronous)
+    const combBytes = new Uint8Array(raw.combWasmBytes());
+    const combModule = new WebAssembly.Module(combBytes);
+    const combInstance = new WebAssembly.Instance(combModule, {
+        env: { memory },
+    });
+    // Parse events and instantiate per-event WASM modules
+    const events = JSON.parse(raw.eventsJson);
+    const eventInstances = new Map();
+    for (const [name, id] of Object.entries(events)) {
+        const bytes = new Uint8Array(raw.eventWasmBytes(name));
+        const mod = new WebAssembly.Module(bytes);
+        const inst = new WebAssembly.Instance(mod, { env: { memory } });
+        eventInstances.set(id, inst);
+    }
+    const sharedMemory = new Uint8Array(memory.buffer, 0, stableSize);
+    const handle = {
+        tick(eventId) {
+            // eval_comb → eval_apply_ff → eval_comb
+            combInstance.exports.run();
+            const evInst = eventInstances.get(eventId);
+            if (evInst)
+                evInst.exports.run();
+            combInstance.exports.run();
+        },
+        tickN(eventId, count) {
+            for (let i = 0; i < count; i++) {
+                this.tick(eventId);
+            }
+        },
+        evalComb() {
+            combInstance.exports.run();
+        },
+        dump(_timestamp) {
+            // No VCD support in browser WASM mode
+        },
+        dispose() {
+            raw.dispose();
+        },
+    };
+    return { handle, sharedMemory };
+}
+/**
+ * Asynchronous version of `createWasmSimulatorBridge` that uses
+ * `WebAssembly.compile()` + `WebAssembly.instantiate()`.
+ *
+ * Preferred for large modules in browsers where synchronous compilation
+ * may be rejected.
+ */
+export async function createWasmSimulatorBridgeAsync(raw) {
+    const totalSize = raw.totalSize;
+    const stableSize = raw.stableSize;
+    const pages = Math.max(1, Math.ceil(totalSize / 65536));
+    const memory = new WebAssembly.Memory({ initial: pages });
+    // Compile comb module
+    const combBytes = new Uint8Array(raw.combWasmBytes());
+    const combModule = await WebAssembly.compile(combBytes);
+    const combInstance = await WebAssembly.instantiate(combModule, {
+        env: { memory },
+    });
+    // Parse events and compile per-event modules
+    const events = JSON.parse(raw.eventsJson);
+    const eventInstances = new Map();
+    const eventEntries = Object.entries(events);
+    await Promise.all(eventEntries.map(async ([name, id]) => {
+        const bytes = new Uint8Array(raw.eventWasmBytes(name));
+        const mod = await WebAssembly.compile(bytes);
+        const inst = await WebAssembly.instantiate(mod, { env: { memory } });
+        eventInstances.set(id, inst);
+    }));
+    const sharedMemory = new Uint8Array(memory.buffer, 0, stableSize);
+    const handle = {
+        tick(eventId) {
+            combInstance.exports.run();
+            const evInst = eventInstances.get(eventId);
+            if (evInst)
+                evInst.exports.run();
+            combInstance.exports.run();
+        },
+        tickN(eventId, count) {
+            for (let i = 0; i < count; i++) {
+                this.tick(eventId);
+            }
+        },
+        evalComb() {
+            combInstance.exports.run();
+        },
+        dump(_timestamp) {
+            // No VCD support in browser WASM mode
+        },
+        dispose() {
+            raw.dispose();
+        },
+    };
+    return { handle, sharedMemory };
+}
+//# sourceMappingURL=wasm-bridge.js.map

package/dist/wasm-bridge.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@celox-sim/celox",
-  "version": "0.1.29",
+  "version": "0.1.31",
   "description": "TypeScript runtime for Celox HDL simulation",
   "type": "module",
   "main": "./dist/index.js",
@@ -29,7 +29,7 @@
   },
   "license": "MIT",
   "dependencies": {
-    "@celox-sim/celox-napi": "0.1.29"
+    "@celox-sim/celox-napi": "0.1.31"
   },
   "peerDependencies": {
     "vitest": ">=1.0.0"

package/src/e2e.test.ts

@@ -14,6 +14,7 @@ import { readFourState } from "./dut.js";
 import {
 	createSimulatorBridge,
 	loadNativeAddon,
+	type NapiTestResult,
 	parseNapiLayout,
 	parseSignalPath,
 	type RawNapiAddon,
@@ -561,8 +562,8 @@ module InitTest (
 		view.setUint8(sigA.offset, 0);
 		view.setUint8(sigA.offset + sigA.byteSize, 0);
 
-		// b = X (value=0, mask=1)
-		view.setUint8(sigB.offset, 0);
+		// b = X (value=1, mask=1) — X encoding: v=1, m=1
+		view.setUint8(sigB.offset, 1);
 		view.setUint8(sigB.offset + sigB.byteSize, 1);
 
 		raw.evalComb();
@@ -572,9 +573,9 @@ module InitTest (
 		expect(vAnd).toBe(0n);
 		expect(mAnd).toBe(0n);
 
-		// 0 | X = X (mask should be 1)
+		// 0 | X = X (value=1, mask=1 in X encoding)
 		const [vOr, mOr] = readFourState(buf, sigYOr);
-		expect(vOr).toBe(0n);
+		expect(vOr).toBe(1n);
 		expect(mOr).toBe(1n);
 	});
 
@@ -598,8 +599,8 @@ module InitTest (
 		view.setUint8(sigA.offset, 1);
 		view.setUint8(sigA.offset + sigA.byteSize, 0);
 
-		// b = X (value=0, mask=1)
-		view.setUint8(sigB.offset, 0);
+		// b = X (value=1, mask=1) — X encoding: v=1, m=1
+		view.setUint8(sigB.offset, 1);
 		view.setUint8(sigB.offset + sigB.byteSize, 1);
 
 		raw.evalComb();
@@ -1889,6 +1890,36 @@ describe("E2E: celox.toml test sources", () => {
 		expect(err.steps).toBe(5);
 		sim.dispose();
 	});
+
+	test("exclude patterns filter out matching files", () => {
+		// The fixture has test_veryl/Excluded.veryl with invalid syntax,
+		// but celox.toml excludes it via `exclude = ["test_veryl/Excluded.veryl"]`.
+		// If exclude works, fromProject succeeds (the broken file is skipped).
+		// If exclude is broken, the parse error will cause an exception.
+		const sim = Simulator.fromProject<{
+			rst: bigint;
+			d: bigint;
+			readonly q: bigint;
+		}>(CELOX_TOML_PROJECT, "Reg");
+		sim.dut.rst = 1n;
+		sim.dut.d = 42n;
+		sim.tick();
+		expect(sim.dut.q).toBe(42n);
+		sim.dispose();
+	});
+
+	test("genTs excludes files matching exclude patterns", () => {
+		const addon = loadNativeAddon();
+		const json = addon.genTs(CELOX_TOML_PROJECT);
+		const output = JSON.parse(json) as {
+			modules: Array<{ moduleName: string }>;
+		};
+		const names = output.modules.map((m) => m.moduleName);
+		expect(names).toContain("Adder");
+		expect(names).toContain("Reg");
+		// Excluded.veryl is excluded by the glob pattern
+		expect(names).not.toContain("Excluded");
+	});
 });
 
 // ---------------------------------------------------------------------------
@@ -2657,3 +2688,95 @@ describe("E2E: non-byte-aligned unpacked array port", () => {
 		sim.dispose();
 	});
 });
+
+// ---------------------------------------------------------------------------
+// Native testbench (run_test / run_test_detailed)
+// ---------------------------------------------------------------------------
+
+const TB_COUNTER_SOURCE = `
+module Counter_tb (
+    clk: input  clock    ,
+    rst: input  reset    ,
+    cnt: output logic<32>,
+) {
+    always_ff {
+        if_reset {
+            cnt = 0;
+        } else {
+            cnt += 1;
+        }
+    }
+}
+`;
+
+const TB_PASS_SOURCE = `
+${TB_COUNTER_SOURCE}
+#[test(t)]
+module CounterTbPass {
+    inst clk: $tb::clock_gen;
+    inst rst: $tb::reset_gen;
+    var cnt: logic<32>;
+    inst dut: Counter_tb (clk, rst, cnt);
+    initial {
+        rst.assert(clk);
+        clk.next  (10);
+        $assert   (cnt == 32'd10);
+        $finish   ();
+    }
+}
+`;
+
+const TB_FAIL_SOURCE = `
+${TB_COUNTER_SOURCE}
+#[test(t)]
+module CounterTbFail {
+    inst clk: $tb::clock_gen;
+    inst rst: $tb::reset_gen;
+    var cnt: logic<32>;
+    inst dut: Counter_tb (clk, rst, cnt);
+    initial {
+        rst.assert(clk);
+        clk.next  (5);
+        $assert   (cnt == 32'd99);
+        $assert   (cnt == 32'd5);
+        $finish   ();
+    }
+}
+`;
+
+describe("E2E: native testbench (runTest)", () => {
+	const addon = loadNativeAddon();
+
+	test("passing testbench returns passed=true with all assertions passed", () => {
+		const result: NapiTestResult = addon.runTest(
+			[{ content: TB_PASS_SOURCE, path: "test.veryl" }],
+			"CounterTbPass",
+		);
+		expect(result.passed).toBe(true);
+		expect(result.assertions.length).toBe(1);
+		expect(result.assertions[0]!.passed).toBe(true);
+	});
+
+	test("failing testbench returns passed=false and collects all assertions", () => {
+		const result: NapiTestResult = addon.runTest(
+			[{ content: TB_FAIL_SOURCE, path: "test.veryl" }],
+			"CounterTbFail",
+		);
+		expect(result.passed).toBe(false);
+		// Both assertions are collected (not stopped at first failure)
+		expect(result.assertions.length).toBe(2);
+		expect(result.assertions[0]!.passed).toBe(false);
+		expect(result.assertions[1]!.passed).toBe(true);
+	});
+
+	test("assertion results include source location", () => {
+		const result: NapiTestResult = addon.runTest(
+			[{ content: TB_PASS_SOURCE, path: "test.veryl" }],
+			"CounterTbPass",
+		);
+		const a = result.assertions[0]!;
+		expect(a.file).toBeDefined();
+		expect(a.line).toBeGreaterThan(0);
+		expect(a.column).toBeGreaterThan(0);
+	});
+});

package/src/index.ts

@@ -66,5 +66,17 @@ export {
 	Z,
 } from "./types.js";
 
+// WASM bridge for browser simulation
+/** @internal */
+export type {
+	RawWasmSimulatorHandle,
+	WasmBridgeResult,
+} from "./wasm-bridge.js";
+export {
+	createWasmSimulatorBridge,
+	createWasmSimulatorBridgeAsync,
+	isWasmHandle,
+} from "./wasm-bridge.js";
+
 // NAPI bridge (backward compat — re-exports from napi-helpers)
 // Consumers that import from "./napi-bridge.js" still work.

package/src/napi-helpers.ts

@@ -22,6 +22,7 @@ import type {
 	SourceFile,
 	TrueLoopSpec,
 } from "./types.js";
+import { createWasmSimulatorBridge, isWasmHandle } from "./wasm-bridge.js";
 
 // ---------------------------------------------------------------------------
 // Raw NAPI handle shapes (what the .node addon actually exports)
@@ -34,11 +35,15 @@ export interface RawNapiSimulatorHandle {
 	readonly warningsJson: string;
 	readonly stableSize: number;
 	readonly totalSize: number;
-	tick(eventId: number): void;
-	tickN(eventId: number, count: number): void;
-	evalComb(): void;
-	dump(timestamp: number): void;
-	sharedMemory(): Uint8Array;
+	// Native (JIT) methods — present when built for native target
+	tick?(eventId: number): void;
+	tickN?(eventId: number, count: number): void;
+	evalComb?(): void;
+	dump?(timestamp: number): void;
+	sharedMemory?(): Uint8Array;
+	// WASM methods — present when built for wasm32 target
+	combWasmBytes?(): Uint8Array | number[];
+	eventWasmBytes?(name: string): Uint8Array | number[];
 	dispose(): void;
 }
 
@@ -98,11 +103,14 @@ export interface NapiOptimizeOptions {
 	inlineCommitForwarding?: boolean;
 	eliminateDeadWorkingStores?: boolean;
 	reschedule?: boolean;
+	coalesceStores?: boolean;
 }
 
 export interface NapiOptions {
 	fourState?: boolean;
 	vcd?: string;
+	optLevel?: string;
+	passOverrides?: string[];
 	optimize?: boolean;
 	optimizeOptions?: NapiOptimizeOptions;
 	craneliftOptLevel?: string;
@@ -123,6 +131,19 @@ export interface NapiSourceFile {
 	path: string;
 }
 
+export interface NapiAssertionResult {
+	passed: boolean;
+	message?: string;
+	file?: string;
+	line?: number;
+	column?: number;
+}
+
+export interface NapiTestResult {
+	passed: boolean;
+	assertions: NapiAssertionResult[];
+}
+
 export interface RawNapiAddon {
 	NativeSimulatorHandle: {
 		new (
@@ -150,6 +171,16 @@ export interface RawNapiAddon {
 	};
 	genTs(projectPath: string): string;
 	clearJitCache(): void;
+	runTest(
+		sources: NapiSourceFile[],
+		top: string,
+		options?: NapiOptions,
+	): NapiTestResult;
+	runTestFromProject(
+		projectPath: string,
+		top: string,
+		options?: NapiOptions,
+	): NapiTestResult;
 }
 
 // ---------------------------------------------------------------------------
@@ -248,6 +279,18 @@ export function buildNapiOpts(
 		napiOpts.vcd = options.vcd;
 		hasOpt = true;
 	}
+	if (options.optLevel) {
+		napiOpts.optLevel = options.optLevel;
+		hasOpt = true;
+	}
+	if (options.passOverrides && options.passOverrides.length > 0) {
+		// Convert camelCase pass names to snake_case for NAPI
+		napiOpts.passOverrides = options.passOverrides.map((s) => {
+			// Pass through +/- prefix and sir: prefix as-is; the Rust side parses them.
+			return s;
+		});
+		hasOpt = true;
+	}
 	if (options.optimize != null) {
 		napiOpts.optimize = options.optimize;
 		hasOpt = true;
@@ -331,6 +374,7 @@ export function buildNapiOpts(
 		if (oo.eliminateDeadWorkingStores != null)
 			napiOo.eliminateDeadWorkingStores = oo.eliminateDeadWorkingStores;
 		if (oo.reschedule != null) napiOo.reschedule = oo.reschedule;
+		if (oo.coalesceStores != null) napiOo.coalesceStores = oo.coalesceStores;
 		napiOpts.optimizeOptions = napiOo;
 		hasOpt = true;
 	}
@@ -523,6 +567,19 @@ export function parseHierarchyLayout(
 	events: Record<string, number>,
 ): HierarchyNode {
 	const raw: RawHierarchyNode = JSON.parse(json);
+
+	// WASM-compiled addon may return an empty object `{}` for hierarchy.
+	// Treat it as an empty hierarchy node.
+	if (!raw.signals && !raw.module_name) {
+		return {
+			moduleName: "",
+			signals: {},
+			forDut: {},
+			ports: {},
+			children: {},
+		};
+	}
+
 	return convertHierarchyNode(raw, events);
 }
 
@@ -603,16 +660,16 @@ export function wrapDirectSimulatorHandle(
 ): NativeSimulatorHandle {
 	return {
 		tick(eventId: number): void {
-			raw.tick(eventId);
+			raw.tick!(eventId);
 		},
 		tickN(eventId: number, count: number): void {
-			raw.tickN(eventId, count);
+			raw.tickN!(eventId, count);
 		},
 		evalComb(): void {
-			raw.evalComb();
+			raw.evalComb!();
 		},
 		dump(timestamp: number): void {
-			raw.dump(timestamp);
+			raw.dump!(timestamp);
 		},
 		dispose(): void {
 			raw.dispose();
@@ -705,8 +762,17 @@ export function createSimulatorBridge(addon: RawNapiAddon): NativeCreateFn {
 		const events: Record<string, number> = JSON.parse(raw.eventsJson);
 		const hierarchy = parseHierarchyLayout(raw.hierarchyJson, events);
 
-		const buf = raw.sharedMemory().buffer;
-		const handle = wrapDirectSimulatorHandle(raw);
+		// Detect WASM-compiled addon and use the bridge
+		let buf: ArrayBuffer | SharedArrayBuffer;
+		let handle: NativeSimulatorHandle;
+		if (isWasmHandle(raw)) {
+			const bridge = createWasmSimulatorBridge(raw);
+			buf = bridge.sharedMemory.buffer;
+			handle = bridge.handle;
+		} else {
+			buf = raw.sharedMemory!().buffer;
+			handle = wrapDirectSimulatorHandle(raw);
+		}
 
 		const warnings: string[] = JSON.parse(raw.warningsJson ?? "[]");
 
@@ -726,6 +792,14 @@ export function createSimulationBridge(
 		moduleName: string,
 		options: SimulatorOptions,
 	): CreateResult<NativeSimulationHandle> => {
+		// WASM addon does not export NativeSimulationHandle
+		if (!addon.NativeSimulationHandle) {
+			throw new Error(
+				"Simulation is not supported in WASM mode. " +
+					"The WASM-compiled addon only supports event-based Simulator, not time-based Simulation.",
+			);
+		}
+
 		const napiOpts = buildNapiOpts(options);
 		const napiSources = sources.map((s) => ({
 			content: s.content,

package/src/simulation.ts

@@ -25,6 +25,7 @@ import type {
 	SourceFile,
 } from "./types.js";
 import { SimulationTimeoutError } from "./types.js";
+import { isWasmHandle } from "./wasm-bridge.js";
 
 /**
  * Placeholder for the NAPI binding's `createSimulation()`.
@@ -190,12 +191,31 @@ export class Simulation<P = Record<string, unknown>> {
 	): Simulation<P> {
 		const addon = loadNativeAddon(options?.nativeAddonPath);
 		const napiOpts = buildNapiOpts(options);
+		// WASM addon does not support time-based Simulation (no NativeSimulationHandle).
+		// Check before attempting to construct the handle.
+		if (!addon.NativeSimulationHandle) {
+			throw new Error(
+				"Simulation is not supported in WASM mode. " +
+					"The WASM-compiled addon only supports event-based Simulator, not time-based Simulation. " +
+					"Use Simulator.fromSource() instead.",
+			);
+		}
+
 		const raw = new addon.NativeSimulationHandle(
 			[{ content: source, path: "" }],
 			top,
 			napiOpts,
 		);
 
+		if (isWasmHandle(raw)) {
+			raw.dispose();
+			throw new Error(
+				"Simulation is not supported in WASM mode. " +
+					"The WASM-compiled addon only supports event-based Simulator, not time-based Simulation. " +
+					"Use Simulator.fromSource() instead.",
+			);
+		}
+
 		const layout = parseNapiLayout(raw.layoutJson);
 		const events: Record<string, number> = JSON.parse(raw.eventsJson);
 		const rawHierarchy = parseHierarchyLayout(raw.hierarchyJson, events);
@@ -251,12 +271,31 @@ export class Simulation<P = Record<string, unknown>> {
 	): Simulation<P> {
 		const addon = loadNativeAddon(options?.nativeAddonPath);
 		const napiOpts = buildNapiOpts(options);
+
+		// WASM addon does not support time-based Simulation (no NativeSimulationHandle).
+		if (!addon.NativeSimulationHandle) {
+			throw new Error(
+				"Simulation is not supported in WASM mode. " +
+					"The WASM-compiled addon only supports event-based Simulator, not time-based Simulation. " +
+					"Use Simulator.fromProject() instead.",
+			);
+		}
+
 		const raw = addon.NativeSimulationHandle.fromProject(
 			projectPath,
 			top,
 			napiOpts,
 		);
 
+		if (isWasmHandle(raw)) {
+			raw.dispose();
+			throw new Error(
+				"Simulation is not supported in WASM mode. " +
+					"The WASM-compiled addon only supports event-based Simulator, not time-based Simulation. " +
+					"Use Simulator.fromProject() instead.",
+			);
+		}
+
 		const layout = parseNapiLayout(raw.layoutJson);
 		const events: Record<string, number> = JSON.parse(raw.eventsJson);
 		const rawHierarchy = parseHierarchyLayout(raw.hierarchyJson, events);