Documentation / Engine choice

Phase 2 JavaScriptCore acquisition#

Superseded on 2026-08-13 by spikes/s8. Blitsen hosts QuickJS-ng, statically linked, under the MIT licence. The reasoning below is kept because it is still the record of why JavaScriptCore was chosen and what it cost — and because the constraint that decided it, LGPL forcing a dynamically replaceable library, is exactly the constraint the replacement removes. What is no longer true: the pinned WebKit revision, the six-target engine build matrix, BLITSEN_JSC_LIBRARY, and the patched JSLoadAndEvaluateModuleFromSource that a stock system JavaScriptCore does not have. The JavaScriptCore host itself is gone: crates/ blitsen-jsc and the javascriptcore feature that selected it were removed once nothing shipped them, so nothing in this document describes code that still exists. It was last buildable at commit 531b3c7.

Decision date: 2026-08-10 Decision: build a pinned Bun WebKit revision in Blitsen's release matrix, own the small Rust ABI layer, and dynamically load the resulting JavaScriptCore library in production.

This settles issue #84. It chooses where the engine artifacts and patches come from; it does not import Bun's runtime. Bun remains the build tool in Phase 2, while Blitsen supplies module loading, scheduling, web APIs, and the DOM bridge.

Decision matrix#

Sources checked for this decision:

• WebKit's ports documentation identifies JSCOnly and explains that WebKit has no cross-platform binary releases.
• WebKit's Windows build documentation shows the separate native Windows toolchain and prerequisites.
• wasmerio/rusty_jsc and its sys/build.rs define its wrapper and platform linkage.
• kevincaicedo/rust-jsc documents its supported targets, static archive download, and patched WebKit requirement.
• The pinned Bun WebKit autobuild is the artifact lineage already measured by S0.

Artifact and ABI contract#

1. Release CI builds on each target OS. Linux artifacts are produced for x64 and arm64, macOS for x64 and arm64, and Windows for x64 and arm64. A target is not advertised until its native smoke test passes.
2. The WebKit revision, Blitsen patch revision, compiler image, artifact checksum, required notices, and source offer are recorded together. An engine update is an explicit reviewed change.
3. The shipped runtime opens the JSC shared library at process start. BLITSEN_JSC_LIBRARY may point at an ABI-compatible replacement; packaging and signing must not disable that override.
4. crates/blitsen-jsc owns only the symbols Blitsen uses. Higher bridge crates continue to see the engine-neutral JsEngine trait. No Bun API enters that crate.
5. The JavaScript context remains process-lived until the teardown assertion recorded by S0 is understood. Blitsen still unloads nothing while JSC values are live.

The current acquisition smoke test dynamically loads a compatible host library and evaluates a script through the public C API:

BLITSEN_JSC_LIBRARY=/path/to/libJavaScriptCore.so \
  cargo run -p blitsen-jsc --example evaluate -- "6 * 7"

On Linux development machines, the loader also probes installed JavaScriptCoreGTK 6.0 and 4.1 libraries. Those fallbacks are for development only; exported applications carry the pinned Blitsen engine artifact.

Module loader contract#

The public JavaScriptCore C API has no module loader hook, and neither does the GLib API — checked against libjavascriptcoregtk-6.0.so.1, whose only evaluation entry points are JSEvaluateScript, JSScriptEvaluate and the three jsc_context_evaluate* functions. A bare context's dynamic import() rejects with "Could not import the module". Blitsen's pinned build therefore exports one additional symbol, and crates/blitsen-jsc loads it optionally:

// Points the context's module loader at two ordinary JavaScript functions.
//   resolve(referrerUrl, specifier) -> url
//   fetch(url) -> source
JS_EXPORT void JSGlobalContextSetModuleLoaderFunctions(
    JSGlobalContextRef context, JSObjectRef resolve, JSObjectRef fetch);

JavaScript functions rather than C callbacks, deliberately: the loader already works in JSValues, it keeps this side of the ABI to a single symbol, and it leaves every policy decision — what a specifier means, what the application is allowed to reach — on the host side, in MODULES.md. JSLoadAndEvaluateModuleFromSource supplies the entry point for the document's own <script type="module">.

JavaScriptCore::supports_modules reports whether both symbols are present, and blitsen-runtime --engine-report prints it. Without them the runtime still runs an application whose scripts are classic and fails at the first import with a message naming the missing symbol, rather than opening a blank window.

Embedded engine progress#

crates/blitsen-jsc now implements every method in the engine-neutral JsEngine trait over a dynamically resolved C API. The host conformance test exercises values and coercion, properties and globals, arrays and typed arrays, Rust callbacks, native classes and instance data, weak references, script exceptions, and Promise microtask checkpoints against a real shared JSC library.

The audit found no Bun or Node-API access in blitsen-core, blitsen-js, blitsen-dom, blitsen-blitz, or blitsen-platform. The Phase 1 DOM installer and browser bootstrap remain in blitsen-node; Phase 2 needs an equivalent adapter, but that code has not escaped into either engine-neutral trait.

Both dependent boundaries are now closed on the host side.

• Runtime services (#87). blitsen-host::runtime_services installs what a bare context lacks: a timer queue the outer loop can ask for its next deadline, queueMicrotask over the engine's own job queue, performance, reportError, DOMException, and a console — the last one replacing JSC's, which belongs to the Web Inspector and silently discards every call when no debugger is attached. I/O needed nothing new: fetch, WebSocket and audio decoding already run on the shared tokio pool and rejoin the main thread at one point in the frame, on both hosts.
• Modules (#86). Resolution, source and reload eviction are implemented and tested against both a directory and an appended bundle. Linking needs the engine hook above.

The audit of structural constraint 1 found one Bun assumption that had escaped the trait: the document-reload path cleared Bun's require cache through process.getBuiltinModule("module") unconditionally. It now clears whichever module cache the host has, and a host with none is not an error. Nothing else in blitsen-host names a JavaScript engine.

The global context and its library intentionally remain process-lived. S0 found that releasing the pinned Bun context without Bun's host initialization asserts during atom-table teardown; unloading the shared library while that context exists would be invalid for the same reason.