@salve-software/react-native-nitro-jsdom 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 salvesoftware
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/NitroJsdom.podspec

@@ -0,0 +1,63 @@
+require "json"
+
+package = JSON.parse(File.read(File.join(__dir__, "package.json")))
+
+Pod::Spec.new do |s|
+  s.name         = "NitroJsdom"
+  s.version      = package["version"]
+  s.summary      = package["description"]
+  s.homepage     = package["homepage"]
+  s.license      = package["license"]
+  s.authors      = package["author"]
+
+  s.platforms    = { :ios => min_ios_version_supported, :visionos => 1.0 }
+  s.source       = { :git => "https://github.com/Salve-Software/react-native-nitro-jsdom.git", :tag => "#{s.version}" }
+
+  s.source_files = [
+    # Implementation (Swift)
+    "ios/**/*.{swift}",
+    # Autolinking/Registration (Objective-C++)
+    "ios/**/*.{m,mm}",
+    # Implementation (C++ objects)
+    "cpp/**/*.{hpp,cpp}",
+    # Third-party: QuickJS
+    "packages/quickjs/quickjs.{c,h}",
+    "packages/quickjs/libregexp.{c,h}",
+    "packages/quickjs/libunicode.{c,h}",
+    "packages/quickjs/cutils.{c,h}",
+    "packages/quickjs/dtoa.{c,h}",
+    "packages/quickjs/*.h",
+    # Third-party: Lexbor (explicit per-directory — omits ports/windows_nt)
+    "packages/lexbor/source/lexbor/core/*.{c,h}",
+    "packages/lexbor/source/lexbor/css/**/*.{c,h}",
+    "packages/lexbor/source/lexbor/dom/**/*.{c,h}",
+    "packages/lexbor/source/lexbor/encoding/*.{c,h}",
+    "packages/lexbor/source/lexbor/html/**/*.{c,h}",
+    "packages/lexbor/source/lexbor/ns/*.{c,h}",
+    "packages/lexbor/source/lexbor/ports/posix/**/*.{c,h}",
+    "packages/lexbor/source/lexbor/punycode/*.{c,h}",
+    "packages/lexbor/source/lexbor/selectors/*.{c,h}",
+    "packages/lexbor/source/lexbor/tag/*.{c,h}",
+    "packages/lexbor/source/lexbor/unicode/*.{c,h}",
+    "packages/lexbor/source/lexbor/url/*.{c,h}",
+    "packages/lexbor/source/lexbor/utils/*.{c,h}",
+  ]
+
+  s.preserve_paths = ["packages/lexbor/**", "packages/quickjs/**"]
+
+  s.pod_target_xcconfig = {
+    'HEADER_SEARCH_PATHS' => '"$(PODS_TARGET_SRCROOT)/packages/lexbor/source"',
+    # QuickJS headers use -iquote so packages/quickjs/VERSION never shadows <version> (C++20)
+    'USER_HEADER_SEARCH_PATHS' => '"$(PODS_TARGET_SRCROOT)/packages/quickjs"',
+    'GCC_PREPROCESSOR_DEFINITIONS' => 'CONFIG_VERSION=\"2025-09-13\"',
+  }
+
+  s.compiler_flags = '-Wno-implicit-fallthrough -Wno-unused-variable -Wno-sign-compare -Wno-shorten-64-to-32'
+
+  load 'nitrogen/generated/ios/NitroJsdom+autolinking.rb'
+  add_nitrogen_files(s)
+
+  s.dependency 'React-jsi'
+  s.dependency 'React-callinvoker'
+  install_modules_dependencies(s)
+end

package/README.md

@@ -0,0 +1,95 @@
+<p align="center">
+  <img src="assets/banner.png" alt="react-native-nitro-jsdom Banner" width="1280" style="border-radius: 20px;">
+</p>
+
+<h1 align="center">react-native-nitro-jsdom</h1>
+
+<p align="center">
+  <strong>A headless HTML/DOM environment for React Native</strong>
+</p>
+
+<p align="center">
+  <img src="https://img.shields.io/npm/v/@salve-software/react-native-nitro-jsdom.svg?style=flat-square" alt="Version">
+  <img src="https://img.shields.io/npm/dm/@salve-software/react-native-nitro-jsdom.svg?style=flat-square" alt="Downloads">
+  <img src="https://img.shields.io/badge/React%20Native-0.76+-61dafb?style=flat-square&logo=react" alt="React Native">
+  <img src="https://img.shields.io/badge/runtime-Node%2018+-339933?style=flat-square&logo=node.js" alt="Node">
+  <img src="https://img.shields.io/badge/license-MIT-green?style=flat-square" alt="License">
+</p>
+
+---
+
+React Native has no native equivalent of [jsdom](https://github.com/jsdom/jsdom). When you need to parse an HTML document, manipulate its DOM, or run arbitrary JavaScript inside it, without rendering anything on screen, your only option today is a `WebView`, a visual component that ties your business logic to the UI layer and drags in a full browser engine just to evaluate a script.
+
+**react-native-nitro-jsdom** solves this by providing a real, isolated HTML + JS sandbox, powered by [Nitro Modules](https://nitro.margelo.com/), that runs entirely off-screen and off the React tree.
+
+```ts
+import { JSDOM } from 'react-native-nitro-jsdom'
+
+const dom = JSDOM.create(`
+  <html>
+    <body>
+      <div id="result">0</div>
+    </body>
+  </html>
+`)
+
+await dom.evaluate(`
+  document.getElementById('result').textContent = String(2 + 2)
+`)
+
+const value = await dom.evaluate(`document.getElementById('result').textContent`)
+// → "4"
+
+dom.dispose()
+```
+
+## Features
+
+- **Headless & off-tree** - no React component, no screen, no UI tree. Parse, mutate, and evaluate HTML entirely off-screen.
+- **Truly isolated runtime** - every `JSDOM.create()` spins up its own QuickJS runtime, not a shared Hermes instance. No leaking globals between sandboxes.
+- **Native HTML parsing** - backed by [Lexbor](https://github.com/lexbor/lexbor), the fastest WHATWG-compliant HTML parser in C99, with zero dependencies.
+- **jsdom-shaped DOM API** - `querySelector`, `textContent`, `dataset`, and more mirror jsdom's DOM shape, though usage differs: everything runs through the async `evaluate()`, not jsdom's synchronous object access.
+- **Synchronous JSI bridge** - powered by Nitro Modules, with direct JSI calls, no bridge, no JSON serialization overhead.
+- **Full memory control** - call `dispose()` to deterministically free the Lexbor document and QuickJS runtime, no waiting on GC.
+
+## Installation
+
+### Requirements
+
+| Component | Requirement |
+|-----------|-------------|
+| React Native | 0.76.0 or higher, with the **New Architecture** (Fabric + TurboModules) enabled |
+| Node.js | 18.0.0 or higher |
+| `react-native-nitro-modules` | Required peer dependency |
+
+```bash
+yarn add react-native-nitro-jsdom react-native-nitro-modules
+```
+
+For iOS, install pods:
+
+```bash
+cd ios && pod install && cd ..
+```
+
+For Android, the package auto-links. Run a Gradle sync if needed.
+
+See the [Compatibility page](https://salve-software.github.io/react-native-nitro-jsdom/docs/compatibility) for platform details (iOS, Android, visionOS) and Expo notes.
+
+## Usage
+
+Full docs, architecture, and API reference: **[salve-software.github.io/react-native-nitro-jsdom](https://salve-software.github.io/react-native-nitro-jsdom)**
+
+## Contributing
+
+We welcome contributions! See [CONTRIBUTING.md](./CONTRIBUTING.md) for setup instructions, branch/commit conventions, and the PR process.
+
+## License
+
+This project is licensed under the MIT License, see [LICENSE](./LICENSE) for details.
+
+---
+
+<p align="center">
+  Made by Salve Software
+</p>

package/android/CMakeLists.txt

@@ -0,0 +1,86 @@
+project(NitroJsdom)
+cmake_minimum_required(VERSION 3.9.0)
+
+find_program(CCACHE_FOUND ccache)
+if(CCACHE_FOUND)
+  set(CMAKE_C_COMPILER_LAUNCHER ccache)
+  set(CMAKE_CXX_COMPILER_LAUNCHER ccache)
+endif()
+
+set (PACKAGE_NAME NitroJsdom)
+set (CMAKE_VERBOSE_MAKEFILE ON)
+set (CMAKE_CXX_STANDARD 20)
+
+# Enable Raw Props parsing in react-native (for Nitro Views)
+add_compile_options(-DRN_SERIALIZABLE_STATE=1)
+
+# ---------------------------------------------------------------------------
+# Third-party: Lexbor
+# ---------------------------------------------------------------------------
+set(LEXBOR_BUILD_SHARED OFF CACHE BOOL "" FORCE)
+set(LEXBOR_BUILD_TESTS   OFF CACHE BOOL "" FORCE)
+add_subdirectory(${CMAKE_SOURCE_DIR}/../packages/lexbor lexbor_build)
+
+# ---------------------------------------------------------------------------
+# Third-party: QuickJS
+# ---------------------------------------------------------------------------
+set(QUICKJS_SOURCES
+  ${CMAKE_SOURCE_DIR}/../packages/quickjs/quickjs.c
+  ${CMAKE_SOURCE_DIR}/../packages/quickjs/libregexp.c
+  ${CMAKE_SOURCE_DIR}/../packages/quickjs/libunicode.c
+  ${CMAKE_SOURCE_DIR}/../packages/quickjs/cutils.c
+  ${CMAKE_SOURCE_DIR}/../packages/quickjs/dtoa.c
+)
+
+set_source_files_properties(${QUICKJS_SOURCES} PROPERTIES
+  COMPILE_FLAGS "-Wno-implicit-fallthrough -Wno-unused-variable -Wno-sign-compare"
+)
+
+# Define C++ library and add all sources
+add_library(${PACKAGE_NAME} SHARED
+  src/main/cpp/cpp-adapter.cpp
+  ../cpp/HybridHtmlSandbox.cpp
+  ../cpp/lexbor/LexborDocument.cpp
+  ../cpp/quickjs/QuickJSRuntime.cpp
+  ../cpp/quickjs/DOMBindings.cpp
+  ../cpp/quickjs/DOMBindingsInternal.cpp
+  ../cpp/quickjs/MutationObservers.cpp
+  ../cpp/quickjs/Storage.cpp
+  ../cpp/quickjs/bindings/ClassListBindings.cpp
+  ../cpp/quickjs/bindings/DatasetBindings.cpp
+  ../cpp/quickjs/bindings/StyleBindings.cpp
+  ../cpp/quickjs/bindings/ElementBindings.cpp
+  ../cpp/quickjs/bindings/DocumentBindings.cpp
+  ../cpp/quickjs/bindings/EventBindings.cpp
+  ../cpp/quickjs/bindings/TimerBindings.cpp
+  ../cpp/quickjs/bindings/WindowBindings.cpp
+  ../cpp/quickjs/bindings/FetchBindings.cpp
+  ${QUICKJS_SOURCES}
+)
+
+target_compile_definitions(${PACKAGE_NAME} PRIVATE CONFIG_VERSION="2025-09-13")
+
+# Add Nitrogen specs :)
+include(${CMAKE_SOURCE_DIR}/../nitrogen/generated/android/NitroJsdom+autolinking.cmake)
+
+# Set up local includes
+include_directories(
+  "src/main/cpp"
+  "../cpp"
+  "${CMAKE_SOURCE_DIR}/../packages/lexbor/source"
+)
+
+# Use -iquote for QuickJS so packages/quickjs/VERSION never shadows <version> (C++20)
+target_compile_options(${PACKAGE_NAME} PRIVATE
+  "-iquote${CMAKE_SOURCE_DIR}/../packages/quickjs"
+)
+
+find_library(LOG_LIB log)
+
+# Link all libraries together
+target_link_libraries(
+  ${PACKAGE_NAME}
+  ${LOG_LIB}
+  android                                   # <-- Android core
+  lexbor_static
+)

package/android/build.gradle

@@ -0,0 +1,148 @@
+buildscript {
+  repositories {
+    google()
+    mavenCentral()
+  }
+
+  dependencies {
+    classpath "com.android.tools.build:gradle:8.8.0"
+  }
+}
+
+def reactNativeArchitectures() {
+  def value = rootProject.getProperties().get("reactNativeArchitectures")
+  return value ? value.split(",") : ["armeabi-v7a", "x86", "x86_64", "arm64-v8a"]
+}
+
+def isNewArchitectureEnabled() {
+  return rootProject.hasProperty("newArchEnabled") && rootProject.getProperty("newArchEnabled") == "true"
+}
+
+apply plugin: "com.android.library"
+apply plugin: 'org.jetbrains.kotlin.android'
+apply from: '../nitrogen/generated/android/NitroJsdom+autolinking.gradle'
+apply from: "./fix-prefab.gradle"
+
+if (isNewArchitectureEnabled()) {
+  apply plugin: "com.facebook.react"
+}
+
+def getExtOrDefault(name) {
+  return rootProject.ext.has(name) ? rootProject.ext.get(name) : project.properties["NitroJsdom_" + name]
+}
+
+def getExtOrIntegerDefault(name) {
+  return rootProject.ext.has(name) ? rootProject.ext.get(name) : (project.properties["NitroJsdom_" + name]).toInteger()
+}
+
+android {
+  namespace "com.nitrojsdom"
+
+  ndkVersion getExtOrDefault("ndkVersion")
+  compileSdkVersion getExtOrIntegerDefault("compileSdkVersion")
+
+  defaultConfig {
+    minSdkVersion getExtOrIntegerDefault("minSdkVersion")
+    targetSdkVersion getExtOrIntegerDefault("targetSdkVersion")
+    buildConfigField "boolean", "IS_NEW_ARCHITECTURE_ENABLED", isNewArchitectureEnabled().toString()
+
+    externalNativeBuild {
+      cmake {
+        cppFlags "-frtti -fexceptions -Wall -Wextra -fstack-protector-all"
+        arguments "-DANDROID_STL=c++_shared", "-DANDROID_SUPPORT_FLEXIBLE_PAGE_SIZES=ON"
+        abiFilters (*reactNativeArchitectures())
+
+        buildTypes {
+          debug {
+            cppFlags "-O1 -g"
+          }
+          release {
+            cppFlags "-O2"
+          }
+        }
+      }
+    }
+  }
+
+  externalNativeBuild {
+    cmake {
+      path "CMakeLists.txt"
+    }
+  }
+
+  packagingOptions {
+    excludes = [
+        "META-INF",
+        "META-INF/**",
+        "**/libc++_shared.so",
+        "**/libfbjni.so",
+        "**/libjsi.so",
+        "**/libfolly_json.so",
+        "**/libfolly_runtime.so",
+        "**/libglog.so",
+        "**/libhermes.so",
+        "**/libhermes-executor-debug.so",
+        "**/libhermes_executor.so",
+        "**/libreactnative.so",
+        "**/libreactnativejni.so",
+        "**/libturbomodulejsijni.so",
+        "**/libreact_nativemodule_core.so",
+        "**/libjscexecutor.so"
+    ]
+  }
+
+  buildFeatures {
+    buildConfig true
+    prefab true
+  }
+
+  buildTypes {
+    release {
+      minifyEnabled false
+    }
+  }
+
+  lintOptions {
+    disable "GradleCompatible"
+  }
+
+  compileOptions {
+    sourceCompatibility JavaVersion.VERSION_1_8
+    targetCompatibility JavaVersion.VERSION_1_8
+  }
+
+  sourceSets {
+    main {
+      if (isNewArchitectureEnabled()) {
+        java.srcDirs += [
+          // React Codegen files
+          "${project.buildDir}/generated/source/codegen/java"
+        ]
+      }
+    }
+  }
+}
+
+repositories {
+  mavenCentral()
+  google()
+}
+
+
+dependencies {
+  // For < 0.71, this will be from the local maven repo
+  // For > 0.71, this will be replaced by `com.facebook.react:react-android:$version` by react gradle plugin
+  //noinspection GradleDynamicVersion
+  implementation "com.facebook.react:react-native:+"
+
+  // Add a dependency on NitroModules
+  implementation project(":react-native-nitro-modules")
+}
+
+if (isNewArchitectureEnabled()) {
+  react {
+    jsRootDir = file("../src/")
+    libraryName = "NitroJsdom"
+    codegenJavaPackageName = "com.nitrojsdom"
+  }
+}

package/android/fix-prefab.gradle

@@ -0,0 +1,51 @@
+tasks.configureEach { task ->
+  // Make sure that we generate our prefab publication file only after having built the native library
+  // so that not a header publication file, but a full configuration publication will be generated, which
+  // will include the .so file
+
+  def prefabConfigurePattern = ~/^prefab(.+)ConfigurePackage$/
+  def matcher = task.name =~ prefabConfigurePattern
+  if (matcher.matches()) {
+    def variantName = matcher[0][1]
+    task.outputs.upToDateWhen { false }
+    task.dependsOn("externalNativeBuild${variantName}")
+  }
+}
+
+afterEvaluate {
+  def abis = reactNativeArchitectures()
+  rootProject.allprojects.each { proj ->
+    if (proj === rootProject) return
+
+    def dependsOnThisLib = proj.configurations.findAll { it.canBeResolved }.any { config ->
+      config.dependencies.any { dep ->
+        dep.group == project.group && dep.name == project.name
+      }
+    }
+    if (!dependsOnThisLib && proj != project) return
+
+    if (!proj.plugins.hasPlugin('com.android.application') && !proj.plugins.hasPlugin('com.android.library')) {
+      return
+    }
+
+    def variants = proj.android.hasProperty('applicationVariants') ? proj.android.applicationVariants : proj.android.libraryVariants
+    // Touch the prefab_config.json files to ensure that in ExternalNativeJsonGenerator.kt we will re-trigger the prefab CLI to
+    // generate a libnameConfig.cmake file that will contain our native library (.so).
+    // See this condition: https://cs.android.com/android-studio/platform/tools/base/+/mirror-goog-studio-main:build-system/gradle-core/src/main/java/com/android/build/gradle/tasks/ExternalNativeJsonGenerator.kt;l=207-219?q=createPrefabBuildSystemGlue
+    variants.all { variant ->
+      def variantName = variant.name
+      abis.each { abi ->
+        def searchDir = new File(proj.projectDir, ".cxx/${variantName}")
+        if (!searchDir.exists()) return
+        def matches = []
+        searchDir.eachDir { randomDir ->
+          def prefabFile = new File(randomDir, "${abi}/prefab_config.json")
+          if (prefabFile.exists()) matches << prefabFile
+        }
+        matches.each { prefabConfig ->
+          prefabConfig.setLastModified(System.currentTimeMillis())
+        }
+      }
+    }
+  }
+}

package/android/gradle.properties

@@ -0,0 +1,5 @@
+NitroJsdom_kotlinVersion=2.1.20
+NitroJsdom_minSdkVersion=23
+NitroJsdom_targetSdkVersion=35
+NitroJsdom_compileSdkVersion=34
+NitroJsdom_ndkVersion=27.1.12297006

package/android/src/main/AndroidManifest.xml

@@ -0,0 +1,2 @@
+<manifest xmlns:android="http://schemas.android.com/apk/res/android">
+</manifest>

package/android/src/main/cpp/cpp-adapter.cpp

@@ -0,0 +1,9 @@
+#include <jni.h>
+#include <fbjni/fbjni.h>
+#include "NitroJsdomOnLoad.hpp"
+
+JNIEXPORT jint JNICALL JNI_OnLoad(JavaVM* vm, void*) {
+  return facebook::jni::initialize(vm, []() {
+    margelo::nitro::nitrojsdom::registerAllNatives();
+  });
+}

package/android/src/main/java/com/nitrojsdom/NitroJsdomPackage.kt

@@ -0,0 +1,20 @@
+package com.nitrojsdom;
+
+import com.facebook.react.bridge.NativeModule;
+import com.facebook.react.bridge.ReactApplicationContext;
+import com.facebook.react.module.model.ReactModuleInfoProvider;
+import com.facebook.react.BaseReactPackage;
+import com.margelo.nitro.nitrojsdom.NitroJsdomOnLoad;
+
+
+public class NitroJsdomPackage : BaseReactPackage() {
+  override fun getModule(name: String, reactContext: ReactApplicationContext): NativeModule? = null
+
+  override fun getReactModuleInfoProvider(): ReactModuleInfoProvider = ReactModuleInfoProvider { emptyMap() }
+
+  companion object {
+    init {
+      NitroJsdomOnLoad.initializeNative();
+    }
+  }
+}

package/cpp/HybridHtmlSandbox.cpp

@@ -0,0 +1,171 @@
+#include "HybridHtmlSandbox.hpp"
+#include <stdexcept>
+#include <variant>
+#include <optional>
+#include <functional>
+#include <vector>
+#include <string>
+#include <cstdio>
+
+namespace margelo::nitro::nitrojsdom {
+
+namespace {
+std::string jsonQuote(const std::string& s) {
+  std::string out = "\"";
+  for (char c : s) {
+    switch (c) {
+      case '"':  out += "\\\""; break;
+      case '\\': out += "\\\\"; break;
+      case '\n': out += "\\n"; break;
+      case '\r': out += "\\r"; break;
+      case '\t': out += "\\t"; break;
+      default:
+        if (static_cast<unsigned char>(c) < 0x20) {
+          char buf[8];
+          snprintf(buf, sizeof(buf), "\\u%04x", c);
+          out += buf;
+        } else {
+          out += c;
+        }
+    }
+  }
+  out += "\"";
+  return out;
+}
+} // namespace
+
+void HybridHtmlSandbox::initialize(const std::string& html, bool runScripts, const std::string& url) {
+  _document = std::make_unique<LexborDocument>();
+  _document->parse(html);
+
+  _runtime = std::make_unique<QuickJSRuntime>();
+  _runtime->initialize(url);
+  _runtime->bindDocument(_document.get());
+
+  if (runScripts) {
+    for (const auto& script : _document->getScriptContents()) {
+      _runtime->evaluate(script);
+    }
+  }
+
+  _initialized = true;
+}
+
+std::shared_ptr<Promise<std::string>> HybridHtmlSandbox::evaluate(const std::string& script) {
+  if (!_initialized) {
+    return Promise<std::string>::rejected(
+      std::make_exception_ptr(std::runtime_error("HtmlSandbox: call initialize() before evaluate()"))
+    );
+  }
+  return Promise<std::string>::async([this, script]() {
+    return _runtime->evaluate(script);
+  });
+}
+
+std::string HybridHtmlSandbox::serialize() {
+  if (!_initialized) return "";
+  return _document->serialize();
+}
+
+void HybridHtmlSandbox::setConsoleCallback(
+    const std::optional<std::variant<nitro::NullType, std::function<void(const std::string& level, const std::vector<std::string>& args)>>>& callback) {
+  if (!_runtime) return;
+
+  if (!callback.has_value()) {
+    // No argument provided — clear the callback
+    _runtime->setConsoleCallback(nullptr);
+    return;
+  }
+
+  const auto& variant = callback.value();
+  if (std::holds_alternative<nitro::NullType>(variant)) {
+    // Explicit null passed — clear the callback
+    _runtime->setConsoleCallback(nullptr);
+  } else {
+    // A real function was provided
+    auto fn = std::get<std::function<void(const std::string&, const std::vector<std::string>&)>>(variant);
+    _runtime->setConsoleCallback(
+      [fn](std::string level, std::vector<std::string> args) {
+        fn(level, args);
+      }
+    );
+  }
+}
+
+void HybridHtmlSandbox::setDialogCallbacks(
+    const std::optional<std::variant<nitro::NullType, std::function<void(const std::string&)>>>& onAlert,
+    const std::optional<std::variant<nitro::NullType, std::function<std::shared_ptr<Promise<bool>>(const std::string&)>>>& onConfirm,
+    const std::optional<std::variant<nitro::NullType, std::function<std::shared_ptr<Promise<std::variant<nitro::NullType, std::string>>>(const std::string&, const std::optional<std::string>&)>>>& onPrompt) {
+  if (!_runtime) return;
+
+  // ── onAlert ──────────────────────────────────────────────────────────────────
+  if (!onAlert.has_value() || std::holds_alternative<nitro::NullType>(onAlert.value())) {
+    _runtime->setAlertCallback(nullptr);
+  } else {
+    auto fn = std::get<std::function<void(const std::string&)>>(onAlert.value());
+    _runtime->setAlertCallback([fn](const std::string& message) {
+      fn(message);
+    });
+  }
+
+  // ── onConfirm ────────────────────────────────────────────────────────────────
+  if (!onConfirm.has_value() || std::holds_alternative<nitro::NullType>(onConfirm.value())) {
+    _runtime->setConfirmCallback(nullptr);
+  } else {
+    auto fn = std::get<std::function<std::shared_ptr<Promise<bool>>(const std::string&)>>(onConfirm.value());
+    _runtime->setConfirmCallback([fn](const std::string& message) -> bool {
+      try {
+        return fn(message)->await().get();
+      } catch (...) {
+        return false;
+      }
+    });
+  }
+
+  // ── onPrompt ─────────────────────────────────────────────────────────────────
+  if (!onPrompt.has_value() || std::holds_alternative<nitro::NullType>(onPrompt.value())) {
+    _runtime->setPromptCallback(nullptr);
+  } else {
+    using RetType = std::variant<nitro::NullType, std::string>;
+    auto fn = std::get<std::function<std::shared_ptr<Promise<RetType>>(const std::string&, const std::optional<std::string>&)>>(onPrompt.value());
+    _runtime->setPromptCallback([fn](const std::string& message, const std::optional<std::string>& defaultValue) -> std::optional<std::string> {
+      try {
+        auto val = fn(message, defaultValue)->await().get();
+        if (std::holds_alternative<std::string>(val)) {
+          return std::get<std::string>(val);
+        }
+        return std::nullopt;
+      } catch (...) {
+        return std::nullopt;
+      }
+    });
+  }
+}
+
+void HybridHtmlSandbox::setFetchCallback(
+    const std::optional<std::variant<nitro::NullType, std::function<std::shared_ptr<Promise<std::shared_ptr<Promise<std::string>>>>(const std::string&, const std::string&, const std::string&, const std::optional<std::string>&)>>>& callback) {
+  if (!_runtime) return;
+
+  if (!callback.has_value() || std::holds_alternative<nitro::NullType>(callback.value())) {
+    _runtime->setFetchCallback(nullptr);
+    return;
+  }
+
+  auto fn = std::get<std::function<std::shared_ptr<Promise<std::shared_ptr<Promise<std::string>>>>(const std::string&, const std::string&, const std::string&, const std::optional<std::string>&)>>(callback.value());
+  _runtime->setFetchCallback(
+    [fn](const std::string& url, const std::string& method, const std::string& headersJson, const std::optional<std::string>& body) -> std::string {
+      try {
+        // Outer await(): dispatches the JS callback call itself onto the JS thread and
+        // waits for it to return — resolves almost immediately with the inner Promise object.
+        // Inner await(): waits for that inner Promise (the real async onFetch() call) to settle.
+        return fn(url, method, headersJson, body)->await().get()->await().get();
+      } catch (const std::exception& e) {
+        return std::string("{\"error\":") + jsonQuote(e.what()) + "}";
+      } catch (...) {
+        return "{\"error\":\"fetch failed\"}";
+      }
+    }
+  );
+}
+
+} // namespace margelo::nitro::nitrojsdom