feat: add custom_globals! macro for registering global JS objects

Add custom_globals! macro alongside native_modules! to allow extender
crates to register global JS objects (TextEncoder, TextDecoder,
polyfills, constants) without modifying hyperlight-js-runtime.

- New custom_globals! macro in modules/mod.rs (same #[no_mangle] + extern
- setup_custom_globals() bridge called in JsRuntime::new() after
  built-in globals
- Default empty custom_globals! {} in base runtime main.rs
- Test fixture with globalThis.CUSTOM_GLOBAL_TEST = 42
- 6 new tests: unit e2e + full pipeline (standalone, coexist with
  builtins, combined with native modules)
- Documentation in docs/extending-runtime.md

Author: simongdavies

docs/extending-runtime.md

@@ -207,3 +207,90 @@ Register a single custom native module by name. Typically called via the
 ```rust
 hyperlight_js_runtime::JsRuntime::new(host)
 ```
+
+## Custom Globals
+
+Register global objects (constructors, polyfills, constants) available
+to all JavaScript code without `import`:
+
+```rust
+fn setup_my_globals(ctx: &rquickjs::Ctx<'_>) -> rquickjs::Result<()> {
+    ctx.eval::<(), _>("globalThis.MY_CONSTANT = 42;")?;
+    Ok(())
+}
+
+hyperlight_js_runtime::custom_globals! {
+    setup_my_globals,
+}
+```
+
+Custom globals are set up after built-in globals (console, require, print)
+during `JsRuntime::new()`. Both Rust-implemented classes (via
+`#[rquickjs::class]`) and JavaScript polyfills (via `ctx.eval()`) are
+supported.
+
+### Rust class example
+
+For things like `TextEncoder` / `TextDecoder` where you need a proper
+constructor accessible as `new TextEncoder()`:
+
+```rust
+use rquickjs::{Ctx, class::Trace, JsLifetime, TypedArray};
+
+#[rquickjs::class]
+#[derive(Trace, JsLifetime)]
+pub struct TextEncoder {}
+
+#[rquickjs::methods]
+impl TextEncoder {
+    #[qjs(constructor)]
+    pub fn new() -> Self { TextEncoder {} }
+
+    pub fn encode<'js>(&self, ctx: Ctx<'js>, input: String)
+        -> rquickjs::Result<TypedArray<'js, u8>> {
+        TypedArray::new(ctx, input.into_bytes())
+    }
+}
+
+fn setup_text_encoding(ctx: &rquickjs::Ctx<'_>) -> rquickjs::Result<()> {
+    TextEncoder::register(ctx)?;
+    ctx.globals().set("TextEncoder", TextEncoder::constructor(ctx)?)?;
+    Ok(())
+}
+
+hyperlight_js_runtime::custom_globals! {
+    setup_text_encoding,
+}
+```
+
+### Combined with native modules
+
+Both macros can be used together — the binary just needs to invoke both:
+
+```rust
+hyperlight_js_runtime::native_modules! {
+    "math" => js_math,
+}
+
+hyperlight_js_runtime::custom_globals! {
+    setup_text_encoding,
+}
+```
+
+### `custom_globals!`
+
+```rust
+hyperlight_js_runtime::custom_globals! {
+    setup_fn_a,
+    setup_fn_b,
+}
+```
+
+Generates an `init_custom_globals(ctx)` function that calls each setup
+function in order. Called automatically by `JsRuntime::new()` after
+built-in globals are installed. Each setup function receives `&Ctx` and
+can register constructors, objects, or values on `ctx.globals()`.
+
+**Important:** Every binary that links `hyperlight-js-runtime` must invoke
+this macro (even if empty). The base runtime's `main.rs` already does this
+with `custom_globals! {}` — same pattern as `native_modules!`.

src/hyperlight-js-runtime/src/lib.rs

@@ -103,7 +103,11 @@ impl JsRuntime {
             host_loader.install(&ctx)?;
 
             // Setup the global objects in the context, so they are available to the handler scripts.
-            globals::setup(&ctx).catch(&ctx)
+            globals::setup(&ctx).catch(&ctx)?;
+
+            // Setup custom globals registered by extender crates via custom_globals! macro.
+            // Runs after built-in globals so custom setup can reference console, require, etc.
+            modules::setup_custom_globals(&ctx).catch(&ctx)
         })?;
 
         Ok(Self {

src/hyperlight-js-runtime/src/main.rs

@@ -22,6 +22,11 @@ limitations under the License.
 // See: docs/extending-runtime.md
 hyperlight_js_runtime::native_modules! {}
 
+// Provide the `init_custom_globals` symbol required by JsRuntime::new().
+// The upstream binary has no custom globals so this is empty.
+// Extender binaries list their custom globals setup functions here instead.
+hyperlight_js_runtime::custom_globals! {}
+
 // The hyperlight guest entry point (hyperlight_main, guest_dispatch_function,
 // etc.) is provided by the lib's `guest` module.
 // The binary only needs to provide the native CLI entry point.

src/hyperlight-js-runtime/src/modules/mod.rs

@@ -170,3 +170,84 @@ macro_rules! native_modules {
         }
     };
 }
+
+// ── Custom globals ─────────────────────────────────────────────────────────
+
+/// Call the extender crate's custom globals setup function.
+///
+/// The `init_custom_globals` symbol is generated by the [`custom_globals!`]
+/// macro. We call it once during `JsRuntime::new()`, after the built-in
+/// globals (console, require, print, etc.) have been set up.
+pub fn setup_custom_globals(ctx: &rquickjs::Ctx<'_>) -> rquickjs::Result<()> {
+    unsafe extern "Rust" {
+        fn init_custom_globals(ctx: &rquickjs::Ctx<'_>) -> rquickjs::Result<()>;
+    }
+    // SAFETY: init_custom_globals is generated by the custom_globals! macro.
+    // Every binary that links hyperlight-js-runtime must invoke the macro
+    // (even if empty) to provide this symbol — same pattern as native_modules!.
+    unsafe { init_custom_globals(ctx) }
+}
+
+/// Register custom global setup functions for the JS runtime.
+///
+/// Custom globals are installed after built-in globals (console, require, etc.)
+/// during `JsRuntime::new()`. Each setup function receives the QuickJS `Ctx`
+/// and can register constructors, objects, or values on `ctx.globals()`.
+///
+/// Supports both Rust-implemented globals (via rquickjs class/function
+/// attributes) and JavaScript polyfills (via `ctx.eval()`).
+///
+/// # Example — Rust class
+///
+/// ```rust,ignore
+/// #[rquickjs::class]
+/// #[derive(Trace, JsLifetime)]
+/// pub struct TextEncoder {}
+///
+/// #[rquickjs::methods]
+/// impl TextEncoder {
+///     #[qjs(constructor)]
+///     pub fn new() -> Self { TextEncoder {} }
+///     pub fn encode<'js>(&self, ctx: Ctx<'js>, input: String)
+///         -> rquickjs::Result<TypedArray<'js, u8>> {
+///         TypedArray::new(ctx, input.into_bytes())
+///     }
+/// }
+///
+/// fn setup_text_encoding(ctx: &rquickjs::Ctx<'_>) -> rquickjs::Result<()> {
+///     TextEncoder::register(ctx)?;
+///     ctx.globals().set("TextEncoder", TextEncoder::constructor(ctx)?)?;
+///     Ok(())
+/// }
+///
+/// hyperlight_js_runtime::custom_globals! {
+///     setup_text_encoding,
+/// }
+/// ```
+///
+/// # Example — JavaScript polyfill
+///
+/// ```rust,ignore
+/// fn setup_polyfills(ctx: &rquickjs::Ctx<'_>) -> rquickjs::Result<()> {
+///     ctx.eval::<(), _>(r#"
+///         globalThis.MY_CONSTANT = 42;
+///     "#)?;
+///     Ok(())
+/// }
+///
+/// hyperlight_js_runtime::custom_globals! {
+///     setup_polyfills,
+/// }
+/// ```
+#[macro_export]
+macro_rules! custom_globals {
+    ($($setup_fn:expr),* $(,)?) => {
+        /// Called by the hyperlight runtime to register custom globals
+        /// after built-in globals are set up.
+        #[unsafe(no_mangle)]
+        pub fn init_custom_globals(ctx: &rquickjs::Ctx<'_>) -> rquickjs::Result<()> {
+            $( ($setup_fn)(ctx)?; )*
+            Ok(())
+        }
+    };
+}

src/hyperlight-js-runtime/tests/fixtures/extended_runtime/src/main.rs

@@ -32,6 +32,16 @@ hyperlight_js_runtime::native_modules! {
     "math" => js_math,
 }
 
+// Register custom globals for the extended runtime.
+fn setup_test_global(ctx: &rquickjs::Ctx<'_>) -> rquickjs::Result<()> {
+    ctx.eval::<(), _>("globalThis.CUSTOM_GLOBAL_TEST = 42;")?;
+    Ok(())
+}
+
+hyperlight_js_runtime::custom_globals! {
+    setup_test_global,
+}
+
 // ── Native CLI entry point (for dev/testing) ───────────────────────────────
 
 #[cfg(not(hyperlight))]

src/hyperlight-js-runtime/tests/native_modules.rs

@@ -185,6 +185,18 @@ hyperlight_js_runtime::native_modules! {
     "test_math_macro" => js_test_math,
 }
 
+// ── custom_globals! macro ──────────────────────────────────────────────────
+
+fn setup_test_constant(ctx: &rquickjs::Ctx<'_>) -> rquickjs::Result<()> {
+    ctx.eval::<(), _>("globalThis.TEST_CUSTOM_GLOBAL = 99;")?;
+    Ok(())
+}
+
+// The macro generates init_custom_globals() which calls each setup function
+hyperlight_js_runtime::custom_globals! {
+    setup_test_constant,
+}
+
 #[test]
 fn macro_generated_init_registers_modules() {
     init_native_modules();
@@ -445,3 +457,120 @@ fn full_pipeline_console_log_with_custom_modules() {
     let lines: Vec<&str> = stdout.trim().lines().collect();
     assert_eq!(lines, ["computed: 54", "Handler result: 54"]);
 }
+
+// ── custom_globals! tests ──────────────────────────────────────────────────
+
+#[test]
+fn e2e_custom_globals_are_available_in_handlers() {
+    let mut runtime =
+        hyperlight_js_runtime::JsRuntime::new(NoOpHost).expect("Failed to create JsRuntime");
+
+    let handler_script = r#"
+        export function handler(event) {
+            return TEST_CUSTOM_GLOBAL;
+        }
+    "#;
+
+    runtime
+        .register_handler("globals_handler", handler_script, ".")
+        .expect("Failed to register handler");
+
+    let result = runtime
+        .run_handler("globals_handler".to_string(), "{}".to_string(), false)
+        .expect("Failed to run handler");
+
+    assert_eq!(result, "99");
+}
+
+#[test]
+fn e2e_custom_globals_coexist_with_builtins() {
+    let mut runtime =
+        hyperlight_js_runtime::JsRuntime::new(NoOpHost).expect("Failed to create JsRuntime");
+
+    let handler_script = r#"
+        export function handler(event) {
+            // Built-in console should still work
+            console.log("custom global value: " + TEST_CUSTOM_GLOBAL);
+            return TEST_CUSTOM_GLOBAL;
+        }
+    "#;
+
+    runtime
+        .register_handler("globals_coexist", handler_script, ".")
+        .expect("Failed to register handler");
+
+    let result = runtime
+        .run_handler("globals_coexist".to_string(), "{}".to_string(), false)
+        .expect("Failed to run handler");
+
+    assert_eq!(result, "99");
+}
+
+// ── Full pipeline custom globals tests ─────────────────────────────────────
+
+#[test]
+fn full_pipeline_custom_globals_available() {
+    let binary = &*EXTENDED_RUNTIME_BINARY;
+    let dir = tempfile::tempdir().unwrap();
+
+    std::fs::write(
+        dir.path().join("handler.js"),
+        r#"
+            function handler(event) {
+                return CUSTOM_GLOBAL_TEST;
+            }
+        "#,
+    )
+    .unwrap();
+
+    let output = Command::new(binary)
+        .arg(dir.path().join("handler.js"))
+        .arg("{}")
+        .output()
+        .unwrap();
+
+    assert!(
+        output.status.success(),
+        "Failed:\n{}",
+        String::from_utf8_lossy(&output.stderr)
+    );
+    let stdout = String::from_utf8_lossy(&output.stdout);
+    assert!(
+        stdout.contains("Handler result: 42"),
+        "Expected custom global to be 42, got: {stdout}"
+    );
+}
+
+#[test]
+fn full_pipeline_custom_globals_with_modules() {
+    let binary = &*EXTENDED_RUNTIME_BINARY;
+    let dir = tempfile::tempdir().unwrap();
+
+    std::fs::write(
+        dir.path().join("handler.js"),
+        r#"
+            import { add } from "math";
+            function handler(event) {
+                return add(CUSTOM_GLOBAL_TEST, event.x);
+            }
+        "#,
+    )
+    .unwrap();
+
+    let output = Command::new(binary)
+        .arg(dir.path().join("handler.js"))
+        .arg(r#"{"x":8}"#)
+        .output()
+        .unwrap();
+
+    assert!(
+        output.status.success(),
+        "Failed:\n{}",
+        String::from_utf8_lossy(&output.stderr)
+    );
+    let stdout = String::from_utf8_lossy(&output.stdout);
+    assert!(
+        stdout.contains("Handler result: 50"),
+        "Expected 42 + 8 = 50, got: {stdout}"
+    );
+}