feat: allow extending hyperlight-js-runtime with custom native modules

[simongdavies]

Resolves #48

Overview

Adds an extension system that lets downstream crates add custom native modules, custom globals, and override built-in modules — without forking the runtime.

Architecture

Three macros, one init sequence:

JsRuntime::new()
  ├─ Step 1: globals::setup()         — install built-in globals (console, print, require)
  │                                      console + print are writable at this stage
  ├─ Step 2: custom_globals!(...)     — extender adds/extends globals (e.g. console.warn)
  ├─ Step 3: globals::freeze()        — Object.freeze(console), lock print
  └─ Module loader ready              — custom modules take priority over built-ins

native_modules! — Custom native modules

Register Rust-implemented modules that guest JS can import:

hyperlight_js_runtime::native_modules! {
    "math" => js_math,
    "io"   => js_custom_io,   // overrides built-in io
}

• Custom modules take priority over built-ins with the same name
• io, crypto, console can be overridden
• require cannot be overridden (panics — it's core infrastructure)
• Lazy initialization via #[no_mangle] + extern "Rust" linkage

custom_globals! — Custom global objects

Register global objects (constructors, polyfills, constants) without import:

fn setup_text_encoding(ctx: &rquickjs::Ctx<'_>) -> rquickjs::Result<()> {
    ctx.globals().set("TextEncoder", TextEncoder::constructor(ctx)?)?;
    Ok(())
}

hyperlight_js_runtime::custom_globals! {
    setup_text_encoding,
}

• Runs after built-in globals, before freeze
• Can extend console (add warn, error, info, debug)
• Both Rust classes (#[rquickjs::class]) and JS polyfills (ctx.eval()) supported

Globals freeze

After custom_globals! runs, built-in globals are locked down:

• console → Object.freeze() (no new properties, no modifications)
• print → non-writable, non-configurable
• require → already non-configurable from setup via Property::from()

Handler code cannot tamper with any of these.

Runtime as a library

hyperlight-js-runtime now exposes a [lib] target. Extender crates depend on it and provide a binary that links everything together. The HYPERLIGHT_JS_RUNTIME_PATH build-time env var tells hyperlight-js to embed the custom binary.

Guest infrastructure (entry point, host function dispatch, libc stubs) moved from src/main/ to src/guest/ and is provided by the lib — no copying needed.

Key changes

File	Change
src/hyperlight-js-runtime/src/modules/mod.rs	NativeModuleLoader, register_native_module, native_modules!, custom_globals!, setup_custom_globals()
src/hyperlight-js-runtime/src/lib.rs	3-step init: setup → custom_globals → freeze
src/hyperlight-js-runtime/src/globals/console.rs	Console as extensible Object (not frozen module namespace)
src/hyperlight-js-runtime/src/globals/print.rs	Print as writable global (frozen after custom_globals)
src/hyperlight-js-runtime/src/globals/freeze.rs	New — freezes console + print after custom_globals
src/hyperlight-js-runtime/src/globals/mod.rs	Added freeze() public function
src/hyperlight-js-runtime/src/main.rs	Empty native_modules! {} + custom_globals! {}
src/hyperlight-js-runtime/src/guest/	Moved from src/main/hyperlight.rs — lib-provided guest infra
src/hyperlight-js/build.rs	HYPERLIGHT_JS_RUNTIME_PATH support
docs/extending-runtime.md	Full guide: quick start, native CLI testing, API reference, custom globals

Tests

• 22 unit tests in tests/native_modules.rs: loader resolution, custom modules, built-in override, require protection, custom_globals! macro, console extensions, freeze behaviour
• 6 full-pipeline E2E tests: build fixture binary → run handler.js → verify output (custom modules, builtins + custom together, console.log, custom globals, globals + modules combined)
• 3 host-side integration tests in src/hyperlight-js/tests/native_modules.rs: HYPERLIGHT_JS_RUNTIME_PATH embedding
• Fixture crates: native_math (shared lib) + extended_runtime (binary with custom modules + globals)