@gjsify/node-gi 0.58.0 → 0.59.1

package/binding.gyp

@@ -4,6 +4,8 @@
       "target_name": "node_gi",
       "sources": [
         "src/addon.cc",
+        "src/android-gdk.cc",
+        "src/android-log.cc",
         "src/cairo.cc",
         "src/calls.cc",
         "src/class.cc",

package/gettext.js

@@ -54,7 +54,7 @@ let announcedStaleAddon = false;
 function noLocaleBinders(fn) {
     if (!announcedStaleAddon) {
         announcedStaleAddon = true;
-        process.emitWarning(
+        globalThis.process?.emitWarning?.(
             `@gjsify/node-gi: the loaded native addon predates the gettext binders, so ` +
                 `${fn}() cannot take effect and messages stay untranslated. Rebuild the addon ` +
                 `(npm run rebuild) or update @gjsify/node-gi.`,
@@ -190,7 +190,7 @@ export function bindtextdomainCodeset(_domainName, _codeset) {
  */
 export const LocaleCategory = haveLocaleBinders
     ? native.localeCategories()
-    : (FALLBACK_CATEGORIES[process.platform] ?? FALLBACK_CATEGORIES.linux);
+    : (FALLBACK_CATEGORIES[globalThis.process?.platform] ?? FALLBACK_CATEGORIES.linux);
 
 /**
  * The GJS `Gettext` module as a default export — the object shape

package/gi.js

@@ -7,20 +7,11 @@
 // Reference: gjs/modules/esm/gi.js for the require shape; node-gtk (romgrk, MIT) for the
 // binding lineage. Hand-authored JS — the package ships no build step.
 import * as native from './index.js';
-// From node:timers, not the globals, for two reasons: setImmediate is a Node/Bun global
-// but Deno only exposes it here; and a GJS source running through the bridge routinely
-// replaces the global timers with GLib-backed ones (`@gjsify/node-globals/register`
-// swaps them for `GLib.timeout_add`), which deadlocks the pump — the timer meant to
-// dispatch GLib sources would itself be a GLib source nobody dispatches.
-import { setImmediate, setInterval, clearInterval } from 'node:timers';
-// Same reasoning for `process`: `globalThis.process` may be the `@gjsify/process`
-// polyfill, whose EventEmitter never emits the runtime's 'beforeExit', so the
-// loop-liveness hooks below would silently never fire.
-import runtimeProcess from 'node:process';
+// Timers, `process` and the windowing env record come from the host seam (host.node.js
+// explains why they are the runtime's own, not the globals; host.nativescript.js is the
+// NativeScript Android variant).
+import { setImmediate, setInterval, clearInterval, runtimeProcess, windowingEnvWrites } from '#host';
 import { createGioDBus } from './overrides/gio-dbus.js';
-// The windowing loader's record of what it wrote into process.env. Read here and not there
-// because replaying it needs a GLib (mirrorWindowingEnvIntoCrt below).
-import { windowingEnvWrites } from './gtk-runtime.js';
 
 // The raw native GObject handle on a wrapped instance, so it can be unwrapped again
 // when passed back into the engine as a GI argument.
@@ -1082,6 +1073,11 @@ function syncPumpKeepAlive() {
     pumpHoldsRuntime = hold;
 }
 
+/** Hosts whose own loop already dispatches GLib, so the portable timer pump must not arm. */
+function hostPumpsItself() {
+    return native.isNodeRuntime || native.RUNTIME === 'gjs' || native.RUNTIME === 'nativescript';
+}
+
 /**
  * Start co-pumping the default GLib main context from a runtime timer (Bun/Deno).
  * No-op on Node, where the libuv↔GLib bridge already co-pumps. Reference-counted;
@@ -1097,7 +1093,7 @@ export function startMainContextPump() {
     // Node: the libuv↔GLib bridge already co-pumps. GJS: the host loop IS
     // GLib's default main context — a JS-timer pump would only iterate the
     // context recursively from within its own dispatch.
-    if (native.isNodeRuntime || native.RUNTIME === 'gjs') return () => {};
+    if (hostPumpsItself()) return () => {};
     pumpRefCount++;
     if (pumpTimer === null) {
         if (pendingView === null) pendingView = native.makePumpPendingCount();
@@ -1122,7 +1118,7 @@ export function startMainContextPump() {
 
 /** Decrement the main-context pump reference count; clears the timer at zero. */
 export function stopMainContextPump() {
-    if (native.isNodeRuntime || native.RUNTIME === 'gjs' || pumpRefCount === 0) return;
+    if (hostPumpsItself() || pumpRefCount === 0) return;
     pumpRefCount--;
     if (pumpRefCount === 0 && pumpTimer !== null) {
         clearInterval(pumpTimer);
@@ -2794,6 +2790,10 @@ export function requireGi(namespace, version) {
             // ready and re-arm — if GLib still has scheduled work, the armed (ref'd)
             // uv timer revives the loop; otherwise the process exits normally.
             runtimeProcess.on('beforeExit', () => native.pumpKick());
+        } else if (native.RUNTIME === 'nativescript') {
+            // The native ALooper pump owns GLib dispatch on Android: no beforeExit kick
+            // (the Looper never runs empty) and no portable timer pump.
+            native.startMainLoop();
         } else if (native.RUNTIME !== 'gjs') {
             // Bun/Deno: no libuv to hook, so the portable timer pump IS the auto-pump.
             // Armed HERE, not left to the caller, so that `bun bundle.mjs` /

package/host.nativescript.js

@@ -0,0 +1,186 @@
+// SPDX-License-Identifier: MIT
+// @gjsify/node-gi — the NativeScript (Android) host, selected by the `nativescript`
+// condition on `#host` (see nativescript.webpack.js, which adds the condition to
+// @nativescript/webpack's resolver). NativeScript's V8 is a Node-API host WITHOUT Node's
+// module system: no node:fs/module/path/process/timers, no prebuild tree, no re-exec.
+// This file is the whole difference — gi.js and index.js import the same names from
+// `#host` on every runtime.
+//
+// Configuration (globals, set before the first import — this package must not hard-import
+// @nativescript/core):
+//   __NODE_GI_APP_DIR       app-private writable dir (default: the files dir, derived from
+//                           com.tns.NativeScriptApplication). HOME / XDG_{DATA,CONFIG,CACHE}_HOME and
+//                           XDG_RUNTIME_DIR are pointed below it, via android.system.Os.setenv
+//                           (a libc setenv) before the addon — and so GLib — is loaded: GLib caches
+//                           these dirs on first use, a later GLib.setenv would be too late.
+//   __NODE_GI_TYPELIB_PATH  directory holding the *.typelib files (the app bundles them, e.g.
+//                           `knownFolders.currentApp().path + '/girepository-1.0'`); prepended to
+//                           the GIRepository search path. Default: `<app dir>/app/girepository-1.0`.
+//   __NODE_GI_SYSTEM_DIR    root of the bundled GNOME system prefix, holding `share/` and `etc/`
+//                           as GTK's own Android runtime lays them out (XDG_DATA_DIRS=<root>/share,
+//                           XDG_CONFIG_DIRS=<root>/etc, plus FONTCONFIG_PATH=<root>/etc/fonts since
+//                           fontconfig's compiled-in /etc/fonts is Android's own and holds no
+//                           fonts.conf). Unset ⇒ nothing is written and GLib keeps its /usr/…
+//                           defaults, which exist on no Android device: a host that bundles its
+//                           own GSettings schemas, icon themes or GTK resources must set it.
+//                           GTK does the same from startRuntime() via g_set_user_dirs(), which is
+//                           not introspectable — see refs/gtk/gdk/android/gdkandroidruntime.c.
+//   __NODE_GI_ANDROID_GDK   truthy ⇒ bring GDK's Android backend up while loading the addon:
+//                           gdk_android_initialize(env, app classloader, Application), the pair
+//                           GTK's RuntimeApplication.startRuntime() passes. Needed before the
+//                           first Gtk call and NOT done by anything else — GIRepository dlopens
+//                           libgtk-4.so, which (unlike System.loadLibrary) never runs its
+//                           JNI_OnLoad, and that JNI_OnLoad passes a NULL context anyway, on
+//                           which gtk_init's Context.getSystemService() aborts the process.
+//                           Unset ⇒ libgtk-4.so is not loaded here at all, which is what a
+//                           GLib-only host wants (src/android-gdk.cc).
+//   __NODE_GI_ANDROID_JNI_BOOTSTRAP
+//                           required by the above: the fully-qualified name of a class in
+//                           the APK whose static initializer calls
+//                           System.loadLibrary("node_gi"). Nothing else runs this addon's
+//                           JNI_OnLoad, and without that there is no JavaVM to reach GDK
+//                           with — see ensureJavaVm().
+
+/** @type {'nativescript'} */
+export const RUNTIME = 'nativescript';
+
+// Timers from the global scope: NativeScript has no node:timers, and there is no
+// GLib-backed replacement to avoid here. setImmediate is not a V8 builtin.
+export const setImmediate =
+    typeof globalThis.setImmediate === 'function'
+        ? globalThis.setImmediate.bind(globalThis)
+        : (fn, ...args) => globalThis.setTimeout(fn, 0, ...args);
+export const setInterval = globalThis.setInterval.bind(globalThis);
+export const clearInterval = globalThis.clearInterval.bind(globalThis);
+
+// The only `process` surface gi.js reads is on('beforeExit'), and NativeScript has no such
+// event: its loop is the Android main Looper, which never "runs empty". The stand-in
+// swallows registrations (nothing needs re-arming — the native ALooper pump owns GLib
+// dispatch). exit() is the honest Android answer: end this process.
+const env = {};
+export const runtimeProcess = {
+    env,
+    platform: 'android',
+    argv: [],
+    on() {
+        return runtimeProcess;
+    },
+    once() {
+        return runtimeProcess;
+    },
+    exit(code = 0) {
+        const proc = globalThis.android?.os?.Process;
+        if (proc) proc.killProcess(proc.myPid());
+        throw new Error(`@gjsify/node-gi: process.exit(${code}) is unavailable outside Android`);
+    },
+};
+
+// No bundled-GTK windowing loader on Android: nothing was written, nothing to replay.
+export function windowingEnvWrites() {
+    return [];
+}
+
+// NativeScript's runtime class hands out the Application without @nativescript/core
+// (android.app.ActivityThread is a hidden API and absent from the metadata).
+function deriveAppDir() {
+    try {
+        return globalThis.com?.tns?.NativeScriptApplication?.getInstance()?.getFilesDir()?.getPath() ?? null;
+    } catch {
+        // NativeScript surfaces a Java exception as a JS one, and getFilesDir() raises
+        // before the Application is fully constructed. No dir is not a failure here: it
+        // means the host sets __NODE_GI_APP_DIR itself, or keeps GLib's defaults.
+        return null;
+    }
+}
+
+function setNativeEnv(name, value) {
+    env[name] = value;
+    globalThis.android?.system?.Os?.setenv(name, value, true);
+}
+
+function appDirectory() {
+    const set = globalThis.__NODE_GI_APP_DIR;
+    if (typeof set === 'string' && set !== '') return set;
+    return deriveAppDir();
+}
+
+// The addon needs a JavaVM to hand GDK a JNIEnv, and a native library gets one only from
+// its own JNI_OnLoad — which ART runs when it loads the library on behalf of a class.
+// NativeScript's `system_lib://` is a plain dlopen: the library is mapped and its
+// Node-API exports work, but ART never saw it, so JNI_OnLoad did not run.
+//
+// Loading it a second time from Java does run it, and costs nothing — same soname in the
+// same linker namespace is the same handle, not a second copy. The catch is where the
+// load is issued from, because ART resolves the library against the *calling class's*
+// classloader:
+//
+//   java.lang.System.loadLibrary('node_gi') straight from JS fails with "library
+//   libnode_gi.so not found": the call arrives through JNI with no Java frame below it,
+//   so the caller is the system classloader, whose search path is /system/lib* only.
+//   System.load() with the absolute path from ApplicationInfo.nativeLibraryDir does not
+//   throw but leaves the VM unset — measured on API 36.
+//
+// So the load has to come from a class in the APK: __NODE_GI_ANDROID_JNI_BOOTSTRAP names
+// one whose static initializer calls System.loadLibrary("node_gi"), and initializing it
+// through Class.forName runs that block under the app's own classloader. Registering the
+// name with the addon first is what lets its JNI_OnLoad cache that classloader, the only
+// moment app classes are visible to it.
+function ensureJavaVm(native) {
+    if (typeof native.androidHasJavaVm !== 'function' || native.androidHasJavaVm()) return;
+    const bootstrap = globalThis.__NODE_GI_ANDROID_JNI_BOOTSTRAP;
+    if (typeof bootstrap !== 'string' || bootstrap === '') {
+        throw new Error(
+            '@gjsify/node-gi: __NODE_GI_ANDROID_GDK needs __NODE_GI_ANDROID_JNI_BOOTSTRAP — ' +
+                'the name of an app class whose static initializer calls ' +
+                'System.loadLibrary("node_gi"). Only such a class can run this addon\'s ' +
+                'JNI_OnLoad, and without it there is no JavaVM to initialize GDK with.',
+        );
+    }
+    native.androidRegisterJniBootstrap(bootstrap.replace(/\./g, '/'));
+    const loader = globalThis.com?.tns?.NativeScriptApplication?.getInstance()?.getClassLoader();
+    globalThis.java?.lang?.Class?.forName(bootstrap, true, loader);
+}
+
+function configureEnvironment() {
+    const systemDir = globalThis.__NODE_GI_SYSTEM_DIR;
+    if (typeof systemDir === 'string' && systemDir !== '') {
+        setNativeEnv('XDG_DATA_DIRS', `${systemDir}/share`);
+        setNativeEnv('XDG_CONFIG_DIRS', `${systemDir}/etc`);
+        setNativeEnv('FONTCONFIG_PATH', `${systemDir}/etc/fonts`);
+    }
+    const appDir = appDirectory();
+    if (appDir === null) return;
+    setNativeEnv('HOME', appDir);
+    setNativeEnv('XDG_DATA_HOME', `${appDir}/.local/share`);
+    setNativeEnv('XDG_CONFIG_HOME', `${appDir}/.config`);
+    setNativeEnv('XDG_CACHE_HOME', `${appDir}/.cache`);
+    setNativeEnv('XDG_RUNTIME_DIR', `${appDir}/.run`);
+}
+
+/**
+ * Load the addon from the APK's native libs and point GI at the app's typelibs.
+ * @returns {Record<string, any>} the native engine
+ */
+export function loadNativeHost() {
+    configureEnvironment();
+    // webpack rewrites __non_webpack_require__ to the runtime's own `require`.
+    const load = typeof __non_webpack_require__ === 'function' ? __non_webpack_require__ : null;
+    if (load === null) {
+        throw new Error(
+            '@gjsify/node-gi: the NativeScript host needs __non_webpack_require__ ' +
+                '(bundle with @nativescript/webpack, which adds the `nativescript` resolve condition).',
+        );
+    }
+    const native = load('system_lib://libnode_gi.so');
+    const appDir = appDirectory();
+    // `app/` is where NativeScript extracts the bundled assets under the files dir.
+    const typelibs = globalThis.__NODE_GI_TYPELIB_PATH ?? (appDir === null ? null : `${appDir}/app/girepository-1.0`);
+    if (typeof typelibs === 'string' && typelibs !== '') native.prependSearchPath(typelibs);
+    // The addon names the Context provider rather than guessing: on NativeScript that is
+    // the runtime's own Application holder, the same one deriveAppDir() reads.
+    if (globalThis.__NODE_GI_ANDROID_GDK && typeof native.androidInitGdk === 'function') {
+        ensureJavaVm(native);
+        native.androidInitGdk('com/tns/NativeScriptApplication', 'getInstance', '()Landroid/app/Application;');
+    }
+    return native;
+}

package/host.node.js

@@ -0,0 +1,224 @@
+// SPDX-License-Identifier: MIT
+// @gjsify/node-gi — the Node/Bun/Deno/GJS host seam (package.json `imports` → `#host`).
+//
+// Everything in the package that touches a Node builtin or needs the runtime's module
+// system lives behind this one specifier, so a host without them (NativeScript on
+// Android — see host.nativescript.js) swaps ONE file via the `nativescript` condition
+// instead of every importer carrying its own guard. This variant is what index.js and
+// gi.js did inline before the seam existed; behaviour on Node/Bun/Deno/GJS is unchanged.
+import { createRequire } from 'node:module';
+import { existsSync } from 'node:fs';
+import { hostTarget, nativeCandidates, packageRoot } from './native-paths.js';
+import { describeAddonLoadFailure } from './load-diagnostics.js';
+import {
+    activateBundledGtkRuntime,
+    activateBundledOpenGL,
+    activateGiLibraryPath,
+    maybePrependGtkRuntimeDllPath,
+    maybeReexecForGtkRuntime,
+    maybeWireGtkWindowingEnv,
+    windowingEnvWrites,
+} from './gtk-runtime.js';
+import { activateNativePrebuilds } from './native-prebuilds.js';
+// From node:timers, not the globals, for two reasons: setImmediate is a Node/Bun global
+// but Deno only exposes it here; and a GJS source running through the bridge routinely
+// replaces the global timers with GLib-backed ones (`@gjsify/node-globals/register`
+// swaps them for `GLib.timeout_add`), which deadlocks the pump — the timer meant to
+// dispatch GLib sources would itself be a GLib source nobody dispatches.
+import { setImmediate, setInterval, clearInterval } from 'node:timers';
+// Same reasoning for `process`: `globalThis.process` may be the `@gjsify/process`
+// polyfill, whose EventEmitter never emits the runtime's 'beforeExit', so the
+// loop-liveness hooks in gi.js would silently never fire.
+import runtimeProcess from 'node:process';
+
+export { setImmediate, setInterval, clearInterval, runtimeProcess, windowingEnvWrites };
+
+const require = createRequire(import.meta.url);
+const here = packageRoot;
+
+/**
+ * Which JS runtime we are on. The addon loads on all four: Node/Bun/Deno implement
+ * Node-API natively, GJS hosts it through the `@gjsify/napi` shim. The libuv main-loop
+ * bridge (startMainLoop) is Node-only — Deno exports no libuv symbols and Bun panics on
+ * uv_backend_fd — so Bun/Deno use gi.js's portable GLib-iteration pump, and GJS needs
+ * neither (its host loop already IS GLib's default main context). Detection order is
+ * load-bearing: GJS first via `imports` + `print` (no other runtime defines both), then
+ * Bun/Deno, which both expose a `process` shim.
+ * @type {'bun' | 'deno' | 'gjs' | 'node'}
+ */
+export const RUNTIME =
+    typeof globalThis.imports !== 'undefined' && typeof globalThis.print === 'function'
+        ? 'gjs'
+        : typeof globalThis.Bun !== 'undefined'
+          ? 'bun'
+          : typeof globalThis.Deno !== 'undefined'
+            ? 'deno'
+            : 'node';
+
+// GJS host mode: `GjsifyNapi.init()` installs the loader as
+// `globalThis.__gjsifyNapiLoadAddon` and re-installs it if another consumer (the
+// @gjsify/napi L1) already captured + deleted it. Needs the GjsifyNapi typelib
+// resolvable via GI_TYPELIB_PATH/LD_LIBRARY_PATH.
+function gjsLoadAddon(path) {
+    let load = globalThis.__gjsifyNapiLoadAddon;
+    if (typeof load !== 'function') {
+        const GjsifyNapi = globalThis.imports?.gi?.GjsifyNapi;
+        if (!GjsifyNapi || !GjsifyNapi.init()) {
+            throw new Error(
+                '@gjsify/node-gi: GJS host mode needs the @gjsify/napi shim — the GjsifyNapi ' +
+                    'typelib is not loadable (point GI_TYPELIB_PATH and LD_LIBRARY_PATH at its prebuild).',
+            );
+        }
+        load = globalThis.__gjsifyNapiLoadAddon;
+        if (typeof load !== 'function') {
+            throw new Error('@gjsify/node-gi: GjsifyNapi.init() did not install the addon loader.');
+        }
+        // Capture-then-delete, the same no-side-channel discipline as the L1.
+        delete globalThis.__gjsifyNapiLoadAddon;
+    }
+    return load(path);
+}
+
+function loadNative() {
+    for (const candidate of nativeCandidates()) {
+        if (existsSync(candidate)) {
+            try {
+                return RUNTIME === 'gjs' ? gjsLoadAddon(candidate) : require(candidate);
+            } catch (err) {
+                // The addon FILE is here and still would not load — on win32/darwin
+                // that means a missing GTK dependency closure, but the raw error
+                // names only the .node, in the OS's language, about a file that
+                // plainly exists (#1063: `Das angegebene Modul wurde nicht
+                // gefunden.` on a present node_gi.node; #994: a missing load-time
+                // library surfacing as "Unsupported type void, deriving from
+                // fundamental void"). The cause is knowable here, so say it.
+                throw new Error(describeAddonLoadFailure(candidate, err), { cause: err });
+            }
+        }
+    }
+    throw new Error(
+        `@gjsify/node-gi: native addon not found for ${RUNTIME} on ${hostTarget()}. ` +
+            `Expected a prebuild at prebuilds/${hostTarget()}/node_gi.node or a local build. ` +
+            'Run `node-gyp rebuild` in ' +
+            here +
+            ' (requires a C++ toolchain and the girepository-2.0 / glib-2.0 development headers), ' +
+            'or install a package build that ships a prebuild for your platform. ' +
+            'Under a bundled GJS app (import.meta anchors at the bundle), set NODE_GI_NATIVE to the addon path.',
+    );
+}
+
+/** Whether we are on Node.js (the only runtime with the libuv main-loop bridge). */
+const isNodeRuntime = RUNTIME === 'node';
+
+/**
+ * Load the addon and run every activation that must precede the first namespace.
+ * @returns {Record<string, any>} the native engine
+ */
+export function loadNativeHost() {
+    // macOS bundled GTK: dyld reads DYLD_FALLBACK_LIBRARY_PATH only at launch, and GI
+    // needs it to g_module_open typelib backers (get_type / Pango / Gdk / Graphene) by
+    // leaf soname — so the re-exec must happen BEFORE the addon's GTK closure is
+    // dlopen'd. Never returns when it re-execs.
+    maybeReexecForGtkRuntime();
+
+    // Windows bundled GTK: Windows re-reads the DLL search path at every LoadLibrary
+    // (unlike dyld's launch-time capture), so mutating process.env.PATH in-process
+    // before the require() below covers both the static DLL imports and the runtime
+    // g_module_open of typelib backers — no re-exec needed.
+    maybePrependGtkRuntimeDllPath();
+
+    // Windows/macOS full-windowing GTK: point GSETTINGS_SCHEMA_DIR / GDK_PIXBUF_MODULE_FILE /
+    // XDG_DATA_DIRS / FONTCONFIG_* at the data a real GTK window needs, and PANGOCAIRO_BACKEND
+    // at the one backend that reads any of the font half. Strict no-op for the display-free
+    // bundle, which therefore loads byte-unchanged. On win32 these writes reach the Win32
+    // environment block ONLY — gi.js replays them into the C runtime's copy on the first
+    // requireGi(), which is the environment pango's and fontconfig's getenv() read.
+    maybeWireGtkWindowingEnv();
+    const native = loadNative();
+
+    // Activate a relocated GTK/GI runtime bundle (@gjsify/gtk-runtime-<os>-<arch> or a
+    // staged prebuilds/<os>-<arch>/gtk/) BEFORE any namespace is required: it prepends the
+    // bundle's typelib dir to the GIRepository search path env-free, so gi:// namespaces
+    // load with no Homebrew/system GTK. Darwin + win32 only; without a bundle the addon
+    // uses the host GTK as before.
+    try {
+        activateBundledGtkRuntime(native);
+    } catch {
+        // Never fatal: a missing/partial bundle just leaves the host GTK in charge.
+    }
+
+    // win32: decide whether the bundle's Mesa opengl32.dll or the host's OpenGL serves GTK, and
+    // preload the bundled one when it wins. Here because gtk-4-1.dll imports OPENGL32 statically,
+    // so it must happen before any namespace loads GTK. Reports rather than throws.
+    activateBundledOpenGL(native);
+
+    // Every OTHER staged prebuild typelib (@gjsify/webkit-native and its kin): same
+    // env-free treatment, so a namespace whose typelib is installed in node_modules
+    // resolves under a plain `node app.mjs` and not only under `gjsify run`. Deliberately
+    // AFTER the GTK activation — that one owns the bundle-vs-host policy (ADR 0023) and
+    // this one skips gtk-runtime-* for exactly that reason.
+    try {
+        activateNativePrebuilds(native);
+    } catch {
+        // Same contract as the calls around it: a failed discovery leaves the search
+        // path untouched, and the caller gets GI's own "typelib not found".
+    }
+
+    // And where the LIBRARIES those typelibs name actually live. Separate from the
+    // call above because it is not about a bundle: it applies to whichever GTK the
+    // policy chose, and it is the only loader repair bun and deno get on macOS —
+    // the re-exec above is Node-shaped and skips them.
+    try {
+        activateGiLibraryPath(native);
+    } catch {
+        // Same contract as above: never fatal.
+    }
+
+    // Cross-runtime microtask checkpoint (Bun/Deno only). Node's napi_make_callback runs
+    // the nextTick + microtask checkpoint when its callback scope closes, so promise
+    // continuations queued by a loop-dispatched GLib→JS callback drain at the callback
+    // boundary even while a blocking GLib.MainLoop.run()/Gio.Application.run() owns the
+    // thread; GJS gets the same from SpiderMonkey draining the promise-job queue when the
+    // last JS frame exits. Bun and Deno checkpoint NOWHERE there (Deno's
+    // napi_make_callback is a plain Function::Call), and with their event loop paused for
+    // the blocking run's lifetime the queue never drained: an async DBus method handler
+    // never sent its reply and the client timed out, while sync handlers worked. So
+    // register the runtime's own drain primitive; the loop-dispatched trampolines
+    // (src/signals.cc / calls.cc / class.cc) invoke it after each OUTERMOST callback
+    // returns (NodeGiMaybeDrainMicrotasks).
+    if (!isNodeRuntime && RUNTIME !== 'gjs') {
+        try {
+            let drain = null;
+            if (RUNTIME === 'bun') {
+                // JSC: drains the VM's microtask queue; callable mid-stack by design
+                // (Bun's own processTicksAndRejections calls it from JS).
+                ({ drainMicrotasks: drain } = require('bun:jsc'));
+            } else if (typeof globalThis.Deno?.internal === 'symbol') {
+                // V8: the checkpoint needs BOTH queues. core.runMicrotasks is only
+                // Isolate::PerformMicrotaskCheckpoint, while Deno's node-compat
+                // process.nextTick queue is a SEPARATE deno_core queue that only the
+                // runtime's own event loop drains — and that loop is paused for the whole
+                // lifetime of a blocking run(). node:stream delivers 'end' via nextTick
+                // (endReadableNT), so a microtask-only drain got body chunks but never the
+                // end: every asset load hung at readyState 3 forever on Deno while the SAME
+                // bundle settled on Bun, whose nextTick rides JSC's microtask queue.
+                // core.runNextTicks covers both queues in one call, like node's
+                // task_queues.js. Regression: test/blocking-run-checkpoint.test.mjs.
+                const core = globalThis.Deno[globalThis.Deno.internal]?.core;
+                if (typeof core?.runNextTicks === 'function') {
+                    drain = () => core.runNextTicks();
+                } else if (typeof core?.runMicrotasks === 'function') {
+                    // Older deno_core without runNextTicks: promise continuations
+                    // settle, nextTick consumers like node:stream 'end' still starve.
+                    drain = () => core.runMicrotasks();
+                }
+            }
+            if (typeof drain === 'function') native.setMicrotaskDrain(drain);
+        } catch {
+            // Unregistered ⇒ promise continuations drain only when the runtime's own loop
+            // runs (startMainContextPump), so async DBus replies inside a BLOCKING run stay
+            // unavailable. Never fatal — the sync surface is unaffected.
+        }
+    }
+    return native;
+}