@crossbind/core-embind-napi 0.0.0-bootstrap.0 → 2.0.0-beta.63

package/README.md

@@ -1,6 +1,48 @@
 # @crossbind/core-embind-napi
+**crossbind Node-API host**  
+Runs the crossbind embind runtime inside a native Node.js addon, so the bindings that serve
+WebAssembly and React Native also build `.node` addons for Node.js and Electron.
 
-This version, 0.0.0-bootstrap.0, holds no code. npm lets a trusted publisher be configured only for a
-package that exists, so it reserves the name for the crossbind release workflow.
+<a href="https://www.npmjs.com/package/@crossbind/core-embind-napi">
+    <img alt="NPM version" src="https://img.shields.io/npm/v/@crossbind/core-embind-napi/beta?style=for-the-badge" />
+</a>
+<a href="https://github.com/crossbind/crossbind/blob/main/LICENSE">
+    <img alt="License" src="https://img.shields.io/github/license/crossbind/crossbind?style=for-the-badge" />
+</a>
 
-Install the real package: `npm install @crossbind/core-embind-napi@beta`. Source: https://github.com/crossbind/crossbind
+## Use
+
+Add it next to `crossbind` and build the addons of this machine's platform, or of every desktop
+platform:
+
+```bash
+pnpm add -D crossbind@beta @crossbind/core-embind-napi@beta
+pnpm crossbind build -p host -e node -b release
+pnpm crossbind build -p darwin,linux,linuxmusl,win32 -e node -b release
+```
+
+`dist/` then holds one addon per platform and architecture (e.g. `<name>.darwin-arm64.node`,
+`<name>.linux-x64.node`, `<name>.win32-x64.node`) and the loader that picks one at runtime:
+
+```js
+const initNative = require('./dist/<name>.native.cjs');
+
+const { Native } = await initNative();
+```
+
+crossbind resolves this package from your project; you never import it yourself. See the
+[Node.js integration guide](https://github.com/crossbind/crossbind/blob/main/docs/playbooks/integration/nodejs.md#native-addon-node-api) for
+requirements, Electron and current limits (no `worker_threads` yet).
+
+## Contents
+
+- `cpp/` — the addon's CMake project and its Node-API entry point.
+- `js/loader.js` — the loader crossbind bundles into `dist/<name>.native.cjs`.
+- `js/addonPlatform.js` — tells glibc and musl Linux apart, so the loader picks the `linux` or `linuxmusl` addon.
+- `js/unpackedPath.js` — points a packaged Electron app's addon at the data its asar archive keeps unpacked.
+- `third_party/node-api-jsi/` — Microsoft's JSI implementation over Node-API (MIT), vendored at a
+  pinned commit; provenance and local patches are in its README.
+
+## License
+
+MIT

package/cpp/CMakeLists.txt

@@ -0,0 +1,76 @@
+cmake_minimum_required(VERSION 3.28)
+project(crossbind_node_addon CXX)
+
+# crossbind configures this project for one Node-API addon: the embind runtime and its Node-API
+# host compile here, the project's own code arrives as prebuilt archives in CROSSBIND_LINK_ARGS.
+
+set(CMAKE_CXX_STANDARD 20)
+set(CMAKE_CXX_STANDARD_REQUIRED ON)
+
+set(NODE_API_JSI "${CMAKE_CURRENT_SOURCE_DIR}/../third_party/node-api-jsi")
+
+if(WIN32)
+    set(NODE_API_LOADER "${NODE_API_JSI}/src/ApiLoaders/NodeApi_win.cpp")
+else()
+    set(NODE_API_LOADER "${NODE_API_JSI}/src/ApiLoaders/NodeApi_posix.cpp")
+endif()
+
+add_library(addon MODULE
+    src/node_api_module.cpp
+    "${NODE_API_JSI}/src/NodeApiJsiRuntime.cpp"
+    "${NODE_API_JSI}/src/ApiLoaders/NodeApi.cpp"
+    "${NODE_API_LOADER}"
+    "${NODE_API_JSI}/src/ApiLoaders/JSRuntimeApi.cpp"
+    "${NODE_API_JSI}/jsi/jsi/jsi.cpp"
+    "${CROSSBIND_JSI_ROOT}/cpp/src/emscripten/bind.cpp"
+    ${CROSSBIND_EXTRA_SOURCES})
+
+set_target_properties(addon PROPERTIES PREFIX "" SUFFIX "" OUTPUT_NAME "${CROSSBIND_ADDON_FILE}")
+
+target_include_directories(addon PRIVATE
+    "${NODE_API_JSI}/src"
+    "${NODE_API_JSI}/node-api"
+    "${NODE_API_JSI}/jsi"
+    "${CROSSBIND_JSI_ROOT}/cpp/src")
+
+target_link_libraries(addon PRIVATE ${CROSSBIND_LINK_ARGS})
+# A force-loaded archive reaches the link as a linker flag, which CMake does not track: without
+# this, a rebuilt bridge archive would leave the previous addon in place.
+set_property(TARGET addon APPEND PROPERTY LINK_DEPENDS ${CROSSBIND_LINK_DEPENDS})
+
+# glibc 2.28 keeps threads and dlopen in libraries of their own. The archives' symbols stay private
+# to the addon: node exports its own OpenSSL and zlib, and an exported copy here would trade calls
+# with them.
+if(CMAKE_SYSTEM_NAME STREQUAL "Linux")
+    find_package(Threads REQUIRED)
+    target_link_libraries(addon PRIVATE Threads::Threads ${CMAKE_DL_LIBS})
+    target_link_options(addon PRIVATE "LINKER:--exclude-libs,ALL")
+    file(GLOB MUSL_LIBC "${CMAKE_SYSROOT}/lib/ld-musl-*.so.1")
+    add_custom_command(TARGET addon POST_BUILD
+        COMMAND "${CMAKE_COMMAND}" "-DNM=${CMAKE_NM}" "-DADDON=$<TARGET_FILE:addon>"
+            "-DUNVERSIONED_LIBRARIES=${MUSL_LIBC}"
+            -P "${CMAKE_CURRENT_SOURCE_DIR}/check-undefined.cmake"
+        VERBATIM)
+endif()
+
+# The C++ runtime, its unwinder and winpthreads go into the addon; the CRT stays the system's UCRT.
+# node-api-jsi's pooled values call the sized operator delete, which clang leaves off for MinGW.
+if(MINGW)
+    target_compile_options(addon PRIVATE -fsized-deallocation)
+    target_link_options(addon PRIVATE -static)
+endif()
+
+# Node-API symbols resolve against the node (or Electron) process that loads the addon. Everything
+# else must resolve at link time, so a stale or missing archive fails the build instead of the load.
+if(APPLE)
+    file(STRINGS "${NODE_API_JSI}/src/ApiLoaders/NodeApi.inc" NODE_API_FUNCS REGEX "^NODE_API_FUNC\\(")
+    foreach(line IN LISTS NODE_API_FUNCS)
+        string(REGEX REPLACE "^NODE_API_FUNC\\(([A-Za-z0-9_]+)\\).*" "\\1" func "${line}")
+        target_link_options(addon PRIVATE "LINKER:-U,_${func}")
+    endforeach()
+    # Only Node-API's entry points leave the addon: dyld merges exported weak definitions across the
+    # images of a process, so two addons would share inline state such as embind's registration guards.
+    target_link_options(addon PRIVATE
+        "LINKER:-exported_symbol,_napi_register_module_v1"
+        "LINKER:-exported_symbol,_node_api_module_get_api_version_v1")
+endif()

package/cpp/check-undefined.cmake

@@ -0,0 +1,38 @@
+# A Linux shared object may leave symbols undefined, and the loader binds functions lazily: an addon
+# that misses an archive loads, then dies at its first call into the missing code. Every undefined
+# symbol has to be a Node-API function or carry the version of a system library that defines it.
+# musl versions nothing, so a name its C library (UNVERSIONED_LIBRARIES) defines passes as it is.
+set(defined)
+foreach(library IN LISTS UNVERSIONED_LIBRARIES)
+    execute_process(
+        COMMAND "${NM}" -D --defined-only "${library}"
+        OUTPUT_VARIABLE exports
+        COMMAND_ERROR_IS_FATAL ANY)
+    string(REPLACE "\n" ";" export_lines "${exports}")
+    foreach(export_line IN LISTS export_lines)
+        if(export_line MATCHES " ([^ ]+)$")
+            list(APPEND defined "${CMAKE_MATCH_1}")
+        endif()
+    endforeach()
+endforeach()
+execute_process(
+    COMMAND "${NM}" -D --undefined-only "${ADDON}"
+    OUTPUT_VARIABLE listing
+    COMMAND_ERROR_IS_FATAL ANY)
+string(REPLACE "\n" ";" lines "${listing}")
+set(unresolved)
+foreach(line IN LISTS lines)
+    if(NOT line MATCHES "^ *U ([^@ ]+)$")
+        continue()
+    endif()
+    # A failed MATCHES clears CMAKE_MATCH_1, so the name is kept before the next one.
+    set(symbol "${CMAKE_MATCH_1}")
+    list(FIND defined "${symbol}" index)
+    if(NOT symbol MATCHES "^(napi|node_api)_" AND index EQUAL -1)
+        list(APPEND unresolved "${symbol}")
+    endif()
+endforeach()
+if(unresolved)
+    list(JOIN unresolved ", " names)
+    message(FATAL_ERROR "crossbind: ${ADDON} leaves symbols no archive defines: ${names}")
+endif()

package/cpp/src/node_api_module.cpp

@@ -0,0 +1,157 @@
+// Node-API host for the embind runtime in @crossbind/core-embind-jsi. The environment whose start()
+// runs first gets a JSI runtime; embind-jsi keeps one current runtime per process, so until runtimes
+// are kept per environment a second one (a worker thread) is refused rather than left to race it.
+#include <node_api.h>
+
+#ifdef _WIN32
+#ifndef WIN32_LEAN_AND_MEAN
+#define WIN32_LEAN_AND_MEAN
+#endif
+#ifndef NOMINMAX
+#define NOMINMAX
+#endif
+#include <windows.h>
+#endif
+
+#include <atomic>
+#include <cstring>
+#include <memory>
+#include <string>
+
+#include <ApiLoaders/JSRuntimeApi.h>
+#include <NodeApiJsiRuntime.h>
+#include <emscripten/bind.h>
+
+namespace {
+
+using Microsoft::NodeApiJsi::FuncPtr;
+using Microsoft::NodeApiJsi::IFuncResolver;
+using Microsoft::NodeApiJsi::JSRuntimeApi;
+
+// node-api-jsi reaches Node-API through a function table; each entry points at the symbol this
+// addon already imports from the host process. On Windows the entries are looked up in the
+// executable instead: node.exe and Electron both export Node-API, so the addon imports nothing from
+// either and needs no import library. jsr_* engine extensions stay null on purpose: JSRuntimeApi
+// falls back to its defaults for them.
+struct ProcessResolver : IFuncResolver {
+    FuncPtr getFuncPtr(const char *funcName) override {
+#ifdef _WIN32
+        return reinterpret_cast<FuncPtr>(GetProcAddress(GetModuleHandleW(nullptr), funcName));
+#else
+#define NODE_API_FUNC(func) \
+    if (std::strcmp(funcName, #func) == 0) return reinterpret_cast<FuncPtr>(&func);
+#include <ApiLoaders/NodeApi.inc>
+        return nullptr;
+#endif
+    }
+};
+
+// The Node-API calls this file makes itself resolve the same way. They look the function up on each
+// call rather than through a JSRuntimeApi, whose entries resolve against the current runtime's table,
+// and there is none while the module initializes.
+ProcessResolver processResolver;
+#define NODE_API(func) reinterpret_cast<decltype(&::func)>(processResolver.getFuncPtr(#func))
+
+struct EnvState {
+    napi_env env = nullptr;
+    ProcessResolver resolver;
+    JSRuntimeApi api{&resolver};
+    std::unique_ptr<facebook::jsi::Runtime> runtime;
+};
+
+std::atomic<napi_env> owner{nullptr};
+
+// Native values can outlive the runtime they point into (thread-local ones are destroyed inside
+// exit()); with no current runtime their release becomes a no-op instead of a call into a dead one.
+void forgetRuntime(EnvState *state) {
+    if (state == nullptr) {
+        return;
+    }
+    if (emscripten::jsRuntime == state->runtime.get()) {
+        emscripten::jsRuntime = nullptr;
+    }
+    napi_env finished = state->env;
+    owner.compare_exchange_strong(finished, nullptr);
+}
+
+std::string readString(napi_env env, napi_value value) {
+    size_t length = 0;
+    NODE_API(napi_get_value_string_utf8)(env, value, nullptr, 0, &length);
+    std::string result(length, '\0');
+    NODE_API(napi_get_value_string_utf8)(env, value, result.data(), length + 1, &length);
+    return result;
+}
+
+// start(dataPath, scope) registers every EMSCRIPTEN_BINDINGS block of the addon into this
+// environment's embind runtime, so embind.js must already be loaded. scope is the object that
+// runtime keeps its state on, which this addon's global() returns. A second call in the same
+// environment is a no-op: registering twice fails with "Cannot register public name ... twice".
+napi_value Start(napi_env env, napi_callback_info info) {
+    void *existing = nullptr;
+    NODE_API(napi_get_instance_data)(env, &existing);
+    if (existing != nullptr) {
+        return nullptr;
+    }
+    // The same environment may retry after a start that failed before it took ownership.
+    napi_env current = nullptr;
+    if (!owner.compare_exchange_strong(current, env) && current != env) {
+        NODE_API(napi_throw_error)(env, nullptr,
+            "crossbind: the native addon already runs in another Node environment; "
+            "worker_threads are not supported yet");
+        return nullptr;
+    }
+
+    size_t argc = 2;
+    napi_value argv[2];
+    NODE_API(napi_get_cb_info)(env, info, &argc, argv, nullptr, nullptr);
+    const std::string dataPath = argc > 0 ? readString(env, argv[0]) : std::string();
+    napi_valuetype scopeType = napi_undefined;
+    if (argc > 1) NODE_API(napi_typeof)(env, argv[1], &scopeType);
+    napi_value scope = scopeType == napi_object ? argv[1] : nullptr;
+
+    // An exception must not unwind through Node-API, which would end the process.
+    try {
+        auto state = std::make_unique<EnvState>();
+        state->env = env;
+        JSRuntimeApi::setCurrent(&state->api);
+        state->runtime = Microsoft::NodeApiJsi::makeNodeApiJsiRuntime(env, &state->api, [] {}, scope);
+        // The environment owns it before any binding registers: registered functions point into it,
+        // so it has to outlive a registration that fails halfway.
+        EnvState *owned = state.release();
+        NODE_API(napi_set_instance_data)(
+            env, owned,
+            [](napi_env, void *data, void *) {
+                auto *finished = static_cast<EnvState *>(data);
+                forgetRuntime(finished);
+                delete finished;
+            },
+            nullptr);
+        emscripten::internal::_embind_initialize_bindings(*owned->runtime, dataPath);
+    } catch (const std::exception &error) {
+        NODE_API(napi_throw_error)(env, nullptr, error.what());
+    } catch (...) {
+        NODE_API(napi_throw_error)(env, nullptr, "crossbind: the native module failed to start");
+    }
+    return nullptr;
+}
+
+// stop() runs from the environment's 'exit' event: no JS runs here afterwards, and process.exit()
+// skips the teardown that would otherwise release the instance data.
+napi_value Stop(napi_env env, napi_callback_info) {
+    void *data = nullptr;
+    NODE_API(napi_get_instance_data)(env, &data);
+    forgetRuntime(static_cast<EnvState *>(data));
+    return nullptr;
+}
+
+}  // namespace
+
+NAPI_MODULE_INIT() {
+    napi_value start;
+    NODE_API(napi_create_function)(env, "start", NAPI_AUTO_LENGTH, Start, nullptr, &start);
+    NODE_API(napi_set_named_property)(env, exports, "start", start);
+    napi_value stop;
+    NODE_API(napi_create_function)(env, "stop", NAPI_AUTO_LENGTH, Stop, nullptr, &stop);
+    NODE_API(napi_set_named_property)(env, exports, "stop", stop);
+    return exports;
+}

package/js/addonLocation.js

@@ -0,0 +1,13 @@
+import path from 'node:path';
+
+// A project's own build leaves the addon beside the loader. A package that publishes one addon per
+// platform ships it in <package>-<platform>-<arch>, an optional dependency whose main is the addon.
+export default function addonLocation({ dir, fileName, packageName, exists, resolve }) {
+    const beside = path.join(dir, fileName);
+    if (exists(beside) || !packageName) return beside;
+    try {
+        return resolve(packageName);
+    } catch {
+        return beside;
+    }
+}

package/js/addonPlatform.js

@@ -0,0 +1,19 @@
+// The platform part of an addon file name. Node reports musl and glibc systems alike as 'linux'; a
+// process linked against glibc names that glibc in its report header, a musl one does not.
+export default function addonPlatform(platform = process.platform, readReport = processReport) {
+    if (platform !== 'linux') return platform;
+    const header = readReport()?.header;
+    return !header || header.glibcVersionRuntime ? 'linux' : 'linuxmusl';
+}
+
+function processReport() {
+    if (!process.report) return undefined;
+    // Only the header is read; the network section can stall on DNS lookups.
+    const { excludeNetwork } = process.report;
+    process.report.excludeNetwork = true;
+    try {
+        return process.report.getReport();
+    } finally {
+        process.report.excludeNetwork = excludeNetwork;
+    }
+}

package/js/loader.js

@@ -0,0 +1,97 @@
+// Entry of the per-project loader crossbind bundles next to the native addons
+// (dist/<name>.native.cjs). It keeps the wasm build's initNative() contract, so the same app code
+// runs on either build.
+import fs from 'node:fs';
+import { createRequire } from 'node:module';
+import path from 'node:path';
+import Module, { crossbindScope } from '@crossbind/core-embind-jsi';
+import systemConfig from 'crossbind/systemConfig';
+import addonPlatform from './addonPlatform.js';
+import addonLocation from './addonLocation.js';
+import missingAddonRemedy from './missingAddon.js';
+import stopOnExit from './stopOnExit.js';
+import unpackedPath from './unpackedPath.js';
+
+const platform = addonPlatform();
+const fill = (pattern) => pattern.replace('{platform}', platform).replace('{arch}', process.arch);
+const addonPackage = systemConfig.paths.addonPackage ? fill(systemConfig.paths.addonPackage) : null;
+
+function addonFile(config) {
+    return config.addonPath ?? addonLocation({
+        dir: __dirname,
+        fileName: fill(systemConfig.paths.addon),
+        packageName: addonPackage,
+        exists: fs.existsSync,
+        resolve: createRequire(__filename).resolve,
+    });
+}
+
+function loadAddon(file) {
+    const addon = { exports: {} };
+    try {
+        process.dlopen(addon, file);
+    } catch (error) {
+        throw new Error(`crossbind: cannot load ${file} - ${fs.existsSync(file) ? error.message : missingAddonRemedy({ platform, arch: process.arch, addonPackage, published: Object.keys(systemConfig.env) })}.`, { cause: error });
+    }
+    return addon.exports;
+}
+
+function setEnv(dataPath, runtimeEnv = {}) {
+    const fillDataPath = (value) => String(value).replace('_CROSSBIND_DATA_PATH_', dataPath);
+    // Build-time values are keyed by addon: a target-scoped value must not leak from one arch's
+    // build into another's. They never replace a variable the process already has; values passed to
+    // initNative() do, as in the wasm runtime, even after a package entry booted the addon.
+    Object.entries(systemConfig.env[`${platform}-${process.arch}`] ?? {}).forEach(([key, value]) => {
+        Module.Crossbind.setEnv(key, fillDataPath(value), false);
+    });
+    Object.entries(runtimeEnv).forEach(([key, value]) => {
+        Module.Crossbind.setEnv(key, fillDataPath(value), true);
+    });
+}
+
+let addon = null;
+let addonDataPath = null;
+
+function boot(config) {
+    // Loaded and started once per process: Node cannot unload an addon, and a second dlopen gets a
+    // fresh environment whose start() would register every binding twice.
+    if (!addon) {
+        addonDataPath = config.dataPath ?? unpackedPath(path.join(__dirname, 'data'));
+        const loaded = loadAddon(addonFile(config));
+        // The embind runtime this bundle carries keeps its state on crossbindScope (crossbind's utils/scopedEmbind.js).
+        loaded.start(addonDataPath, crossbindScope);
+        // Native values released after this (thread-local ones die inside exit()) must not call
+        // back into the runtime.
+        stopOnExit(() => loaded.stop());
+        addon = loaded;
+    } else if (config.dataPath && config.dataPath !== addonDataPath) {
+        throw new Error(`crossbind: the addon started with its data at ${addonDataPath}; a process cannot move it to ${config.dataPath}.`);
+    }
+    setEnv(addonDataPath, config.env);
+    return Module;
+}
+
+let booted = null;
+
+export default function initNative(config = {}) {
+    if (!booted) {
+        try {
+            booted = Promise.resolve(boot(config));
+        } catch (error) {
+            // Not remembered: a later call retries, for example once the addon is built.
+            return Promise.reject(error);
+        }
+    }
+    return booted;
+}
+
+// Loading an addon is synchronous, so a package entry boots it on require.
+initNative.sync = function sync(config = {}) {
+    return boot(config);
+};
+
+// The wasm runtime's contract: forget the booted module so the next call boots again. Native state
+// cannot be reset (Node cannot unload an addon), so that call resolves the same module.
+initNative.terminate = function terminate() {
+    booted = null;
+};

package/js/missingAddon.js

@@ -0,0 +1,9 @@
+// What a process without its addon is told: install the addon package npm left out, learn that the package
+// publishes none for this machine, or build the addon an app makes itself. published lists the
+// <platform>-<arch> of every addon the package ships.
+export default function missingAddonRemedy({ platform, arch, addonPackage, published }) {
+    const target = `${platform}-${arch}`;
+    if (!addonPackage) return `build it with \`crossbind build -p ${platform} -a ${arch}\``;
+    if (!published.includes(target)) return `this package publishes no addon for ${target}, only for ${published.join(', ')}`;
+    return `install ${addonPackage}, which npm leaves out with --omit=optional; addons exist for ${published.join(', ')}`;
+}

package/js/stopOnExit.js

@@ -0,0 +1,15 @@
+// Every package bundles a loader of its own, and Node warns at an eleventh 'exit' listener, so the addons share one,
+// found by a registered symbol. Each boot moves it to the end of the list: the stops then run after every handler
+// registered so far, as a listener added at that boot would, since a call into an addon after its stop crashes.
+const ADDON_STOPS = Symbol.for('crossbind.addonStops.v1');
+
+export default function stopOnExit(stop, proc = process) {
+    if (!proc[ADDON_STOPS]) {
+        const stops = [];
+        proc[ADDON_STOPS] = { stops, onExit: () => stops.forEach((stopAddon) => stopAddon()) };
+    }
+    const { stops, onExit } = proc[ADDON_STOPS];
+    stops.push(stop);
+    proc.removeListener('exit', onExit);
+    proc.on('exit', onExit);
+}

package/js/unpackedPath.js

@@ -0,0 +1,5 @@
+// Native code cannot read inside an Electron asar archive, so a packaged app keeps what an addon
+// reads in <archive>.asar.unpacked beside it.
+export default function unpackedPath(file, isElectron = Boolean(process.versions.electron)) {
+    return isElectron ? file.replace(/\.asar(?=[\\/]|$)/, '.asar.unpacked') : file;
+}

package/package.json

@@ -1,7 +1,30 @@
 {
-    "name": "@crossbind/core-embind-napi",
-    "version": "0.0.0-bootstrap.0",
-    "description": "Placeholder that let npm trust the crossbind release workflow; install @crossbind/core-embind-napi@beta.",
-    "license": "MIT",
-    "repository": "https://github.com/crossbind/crossbind.git"
-}
+  "name": "@crossbind/core-embind-napi",
+  "version": "2.0.0-beta.63",
+  "description": "Node-API host for the crossbind embind runtime: native Node.js addons from the same C++ and Rust bindings.",
+  "homepage": "https://github.com/crossbind/crossbind/tree/main/core/embind-napi#readme",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/crossbind/crossbind.git"
+  },
+  "license": "MIT",
+  "files": [
+    "cpp",
+    "js",
+    "third_party"
+  ],
+  "dependencies": {
+    "@crossbind/core-embind-jsi": "^2.0.0-beta.63"
+  },
+  "keywords": [
+    "embind",
+    "node-api",
+    "napi",
+    "addon",
+    "bind",
+    "c++",
+    "rust",
+    "node",
+    "electron"
+  ]
+}

package/third_party/node-api-jsi/LICENSE

@@ -0,0 +1,21 @@
+    MIT License
+
+    Copyright (c) Microsoft Corporation.
+
+    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/third_party/node-api-jsi/README.md

@@ -0,0 +1,59 @@
+# node-api-jsi (vendored)
+
+A JSI (`facebook::jsi`) implementation on top of Node-API. It lets the embind runtime in
+`@crossbind/core-embind-jsi` run inside a Node.js addon unchanged.
+
+- Upstream: https://github.com/microsoft/node-api-jsi
+- Commit: `4b8a4a59c4e1b7b988b809dedffd89a7662aa785` (upstream publishes no releases)
+- Archive: `https://codeload.github.com/microsoft/node-api-jsi/tar.gz/4b8a4a5`,
+  sha256 `701dfaac5b281b9b67986611ba612d6fe253c434f65459c877b24debf41d3c43`
+- License: MIT, see `LICENSE`
+
+Only the files the addon compiles are kept: `src/NodeApiJsiRuntime.*`, the `src/ApiLoaders`
+Node-API and JSRuntime loaders, `jsi/jsi/{jsi.h,jsi-inl.h,jsi.cpp,instrumentation.h}` and the
+`node-api` headers. `jsi.h` falls back to `JSI_VERSION` 21 when no compile definition sets it, so
+no `jsi-version.h` is needed.
+
+## Local patches
+
+- `src/NodeApiJsiRuntime.cpp` includes `<atomic>` and `<utility>`, which GCC and Clang do not
+  pull in transitively.
+- `jsiHostFunctionCallback` is declared `NAPI_CDECL` instead of `__cdecl`, so the calling
+  convention only applies where Node-API defines one (Windows).
+- `createStringFromAscii`, `createStringFromUtf8`, `createBigIntFromInt64`,
+  `createBigIntFromUint64`, `bigintIsInt64`, `bigintIsUint64`, `truncate`, `utf8(const String&)`
+  and `call` skip their own `NodeApiScope` while a pointer value scope is open and has taken fewer
+  than `MaxUsesPerOpenScope` (64) such calls. Upstream wraps every primitive they return in an
+  object behind a `napi_ref` when that scope closes and reads it back on use; a string-returning
+  call went from about 370 to 120 ns and a `const char*` argument, seven emval round trips, from
+  4.2 to 1.3 µs. The cap keeps a loop inside one call bounded: without it, a million callbacks
+  from one call raised peak memory from 96 to 649 MB. `getProperty`, `instanceOf`,
+  `isArrayBuffer`, `size` and `data` of an `ArrayBuffer`, and `callAsConstructor` skip it the same
+  way: reading a typed array from C++ opened a Node-API handle scope (a heap allocation in Node)
+  for each of these, and a Rust `&[u8]` argument went from 1.16 to 0.94 µs.
+- `NodeApiPendingDeletions` keeps an atomic flag, so `deletePointerValues` takes its mutex only
+  when something waits for deletion (about 10 to 20 ns off every call).
+- `NodeApiRefCountedPointerValue::decRefCount` marks a value released on the JS thread while it
+  is still on the value stack and has no `napi_ref` for the stack to delete, which is all the
+  pending deletion would do, and skips the recursive mutex it takes twice. embind reads every
+  `this` pointer and string argument through such a clone: a four-double method call went from
+  384 to 362 ns and a `std::string` argument from 211 to 179 ns.
+- `JsiValueViewArgs` constructs each argument in place and destroys only those, instead of
+  building `MaxStackArgCount` `jsi::Value`s, move-assigning into them and destroying all of them
+  out of line on every call: 369 to 347 ns for the same method call.
+- `NodeApiJsiRuntime` answers `castInterface` for `crossbind::IDirectReads`
+  (`core/embind-jsi/cpp/src/crossbind/direct_reads.h`). `typedArrayElements` makes one
+  `napi_get_typedarray_info` call where reading the view's `buffer`, `byteOffset` and `length`
+  through the object API took about 440 ns, most of a Rust `xxh32` call on 32 bytes, which went
+  from 591 to 87 ns. `bigIntToUint64` and `bigIntToInt64` read a BigInt argument without cloning
+  it into a heap pointer value first; embind-jsi reads `this` and its other 64-bit values through
+  them, and a method call such as `vector.size()` went from 61 to 51 ns.
+- `NodeApiRefCountedPointerValue` takes its memory from a per-thread list of up to 64 blocks
+  instead of malloc: most live for one host call, a string, BigInt or `this` read or made during
+  it. A string return went from 75 to 69 ns and a string argument from 95 to 84 ns; together with
+  the direct BigInt read, a Rust `xxh64` call on 32 bytes with a BigInt seed and result went from
+  141 to 110 ns. A million callbacks in one call peak at the same 70 MB.
+- `makeNodeApiJsiRuntime` takes an optional object that `global()` returns in place of the
+  global object. Each addon's loader bundles its own embind runtime, which keeps its `Module` and
+  the functions the addon calls by name on such an object, so addons of several packages run in
+  one process. The runtime's own lookups (`Error`, `Proxy`, `Symbol`) still use the global object.