Project Fusor

The Experimental JavaScript Engine — a safe, pure-Rust implementation of ECMAScript with ES2025 semantics. Runtime semantics and the differential-test profile are pinned and documented in docs/UPSTREAM.md.

Important

This is an in-progress engine, not yet a complete JavaScript implementation or a drop-in replacement for its pinned reference. Unsupported behavior is intended to fail closed.

Scope

• Pure Rust engine core: no C/C++ source, bindgen output, or C compiler in the build or runtime path. The optional N-API adapter is the isolated foreign-ABI boundary.
• Runtime semantics follow a single pinned reference implementation, which is a differential-test oracle only — never linked, compiled, or shipped. See docs/UPSTREAM.md and docs/PORTING.md.
• Only whole-function, typed, graph-verified bytecode may execute. Raw and serialized bytecode, and direct eval, remain fail closed.
• The core crates forbid unsafe; changes must preserve observable behavior under differential tests.

Current profile

The implemented, tested subset includes ordinary functions and closures; bindings and TDZ; control flow, exceptions, and try/catch/finally; ordinary objects and accessors; arrays, synchronous iterators, array spread, and for-of; operators and coercion; and the initial Boolean, Number, String, Symbol, Function, Array, and Error families.

Key gaps remain: direct eval and with; residual class/compiler semantics; modules; the selected Annex B compatibility subset; multi-agent Atomics and immutable ArrayBuffer; and the public embedding/tooling surface. See docs/PORTING.md for the authoritative checklist and compatibility boundaries.

Workspace

Crate	Responsibility
fusor-diagnostics	Sources, spans, diagnostics, and source maps
fusor-frontend	Oxc parsing and owned frontend records
fusor-bytecode	Instructions, verifier, codec, and debug data
fusor-compiler	Oxc lowering to verified bytecode
fusor-runtime	Values, heap, realms, VM, and built-ins
fusor	Ergonomic host facade; plus the fusor CLI bin (module runner, ESM REPL, node: builtins, DevTools CDP server — the former fusor-cli/fusor-cdp crates, merged 2026-08-14)

Architecture and trust-boundary details are in docs/ARCHITECTURE.md and docs/BYTECODE_VERIFIER.md. See docs/UPSTREAM.md for the pinned reference and docs/DEPENDENCIES.md for dependency policy.

DevTools

fusor exposes one loopback-only Chrome DevTools Protocol target when started with --inspect (default port 9229):

fusor repl --inspect
fusor run --inspect=9230 entry.mjs
fusor run --script --inspect-brk app.js

The supported Runtime/Debugger protocol profile and its known limits are documented in docs/DEVTOOLS.md.

Development

Use the current stable Rust toolchain (the workspace pins its minimum version). Run the normal local gates from the repository root:

cargo fmt --all --check
cargo clippy --workspace --all-targets --all-features -- -D warnings
cargo test --workspace
cargo doc --workspace --no-deps

For a changed compatibility area, run its matching differential corpus against the pinned upstream oracle, for example:

cargo xtask parser-differential \\
  --oracle /path/to/pinned-qjs
cargo xtask dynamic-function-differential \\
  --oracle /path/to/pinned-qjsc

The parser corpus is a closed ledger: it fails when a pinned grammar production has no accepted fixture, when a diagnostic the front end can raise has no fixture, or when the oracle's message stops matching the pinned text. Additional corpora cover Number radix conversion, control flow, Function.prototype.apply/bind, iterators, call spread, and Errors. Those manifests are expanding compatibility gates, not claims of exhaustive coverage.

License

MIT. The engine's own notice is in LICENSE; the upstream reference's original copyright and permission notice are retained in LICENSE-quickjs.