@gjsify/node-gi 0.58.0 → 0.59.1

package/index.js

@@ -5,203 +5,19 @@
 // a native package's JS entry is a loader, not a tsc artifact, and the repo
 // ignores `lib/`. The addon is Node-API (ABI-stable), so the same binary loads on
 // Node, Bun and Deno; runtime-specific behaviour is gated off RUNTIME below.
-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,
-} from './gtk-runtime.js';
-import { activateNativePrebuilds } from './native-prebuilds.js';
-
-// 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 require = createRequire(import.meta.url);
-const here = packageRoot;
+import { RUNTIME, loadNativeHost } from '#host';
 
 /**
- * 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'}
+ * Which JS runtime we are on. Detection — and why each runtime gets the main-loop
+ * treatment it gets — lives at the detection site, behind `#host`.
+ * @type {'bun' | 'deno' | 'gjs' | 'node' | 'nativescript'}
  */
-export const RUNTIME =
-    typeof globalThis.imports !== 'undefined' && typeof globalThis.print === 'function'
-        ? 'gjs'
-        : typeof globalThis.Bun !== 'undefined'
-          ? 'bun'
-          : typeof globalThis.Deno !== 'undefined'
-            ? 'deno'
-            : 'node';
+export { RUNTIME };
 
 /** Whether we are on Node.js (the only runtime with the libuv main-loop bridge). */
 export const isNodeRuntime = RUNTIME === '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.',
-    );
-}
-
-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.
-    }
-}
+const native = loadNativeHost();
 
 // Straight re-exports of the native engine surface. Each contract — arguments,
 // ownership, the OUT/INOUT return-tuple convention, the keep-alive rules of the

package/nativescript.webpack.js

@@ -0,0 +1,16 @@
+// SPDX-License-Identifier: MIT
+// @nativescript/webpack plugin hook (it discovers this exact file name in every dependency
+// and `require()`s it). Adds the `nativescript` export condition so package.json `imports`
+// (`#host`) resolves to host.nativescript.js; webpack's `target('node')` would otherwise
+// pick the Node host.
+//
+// This package is `"type": "module"`, so the file is ESM: the `module.exports` export name
+// is what `require()` of an ES module hands back as the CommonJS export (Node >= 22.12).
+function hook(webpack) {
+    webpack.chainWebpack((config) => {
+        // `...` keeps webpack's own defaults (import/require/node/default, per request kind).
+        config.resolve.set('conditionNames', ['nativescript', '...']);
+    });
+}
+
+export { hook as 'module.exports' };

package/overrides/byte-array.js

@@ -42,6 +42,23 @@ const ENCODE_LABELS = new Map([
     ['utf16le', 'utf16le'],
 ]);
 
+// Buffer.from(string, 'latin1' | 'ascii' | 'utf16le') for hosts without Buffer: latin1 and
+// ascii keep the low byte of each UTF-16 code unit, utf16le writes each unit little-endian.
+function encodeWithoutBuffer(string, bufferEncoding) {
+    if (bufferEncoding === 'utf16le') {
+        const out = new Uint8Array(string.length * 2);
+        for (let i = 0; i < string.length; i++) {
+            const c = string.charCodeAt(i);
+            out[2 * i] = c & 0xff;
+            out[2 * i + 1] = c >> 8;
+        }
+        return out;
+    }
+    const out = new Uint8Array(string.length);
+    for (let i = 0; i < string.length; i++) out[i] = string.charCodeAt(i) & 0xff;
+    return out;
+}
+
 function isUtf8Label(encoding) {
     const label = String(encoding).toLowerCase();
     return label === 'utf-8' || label === 'utf8';
@@ -95,8 +112,13 @@ export function createByteArray(requireGi) {
         } else {
             const bufferEncoding = ENCODE_LABELS.get(String(encoding).toLowerCase());
             if (!bufferEncoding) throw new Error(`Unsupported encoding for fromString(): ${encoding}`);
-            const buf = Buffer.from(string, bufferEncoding);
-            encoded = new Uint8Array(buf.buffer, buf.byteOffset, buf.byteLength);
+            // NativeScript has no Buffer; encodeWithoutBuffer yields the same bytes.
+            if (typeof Buffer === 'function') {
+                const buf = Buffer.from(string, bufferEncoding);
+                encoded = new Uint8Array(buf.buffer, buf.byteOffset, buf.byteLength);
+            } else {
+                encoded = encodeWithoutBuffer(string, bufferEncoding);
+            }
         }
         const data = zeroTerminated(encoded);
         // Copy into a fresh plain Uint8Array (gjs returns a standalone buffer, and

package/package.json

@@ -1,17 +1,24 @@
 {
   "name": "@gjsify/node-gi",
-  "version": "0.58.0",
+  "version": "0.59.1",
   "description": "GObject-Introspection runtime for Node.js — load gi:// namespaces (GLib/GObject/Gio/…) with GJS-compatible semantics. Vendored + rewritten from node-gtk under MIT.",
   "type": "module",
   "license": "MIT",
   "gypfile": true,
   "main": "./index.js",
   "types": "./index.d.ts",
+  "imports": {
+    "#host": {
+      "nativescript": "./host.nativescript.js",
+      "default": "./host.node.js"
+    }
+  },
   "exports": {
     ".": {
       "types": "./index.d.ts",
       "default": "./index.js"
     },
+    "./package.json": "./package.json",
     "./gi": {
       "types": "./gi.d.ts",
       "default": "./gi.js"
@@ -39,6 +46,9 @@
   },
   "files": [
     "index.js",
+    "host.node.js",
+    "host.nativescript.js",
+    "nativescript.webpack.js",
     "index.d.ts",
     "gi.js",
     "gi.d.ts",
@@ -86,6 +96,7 @@
     "install": "node scripts/install.mjs",
     "build": "node-gyp rebuild",
     "build:native": "node-gyp rebuild",
+    "build:android": "node scripts/build-android.mjs",
     "build:prebuild": "node-gyp rebuild && node scripts/stage-prebuild.mjs",
     "rebuild": "node-gyp rebuild",
     "clean": "node-gyp clean",

package/src/addon.cc

@@ -64,6 +64,13 @@ static Napi::Object Init(Napi::Env env, Napi::Object exports) {
   // Without it the process stays in the C locale, where GNU gettext refuses to
   // translate; the block in private.cc records what that cost.
   NodeGiInitProcessLocale();
+  // Also before any GLib call: on Android, point GLib's messages at logcat. Without
+  // it every g_warning explaining a failed GI/GTK call is written to a stderr that
+  // goes to /dev/null (android-log.cc).
+  InitAndroidLog(env, exports);
+  // Only the export; the bring-up itself runs when the host asks for it, since it
+  // dlopens the whole GTK stack (android-gdk.cc).
+  InitAndroidGdk(env, exports);
   // The owner env + its JS/main thread are captured lazily at the first wrap
   // (EnsureDrainAsync) — NOT here, since Init runs once PER env and a per-env
   // overwrite would mis-identify the main thread under worker_threads. The cleanup

package/src/android-gdk.cc

@@ -0,0 +1,291 @@
+// SPDX-License-Identifier: MIT
+// Android only: bring GDK's Android backend up without GTK's RuntimeApplication.
+//
+// GDK's Android backend is initialized by gdk_android_initialize(env, classloader,
+// context) — the only exported entry point into it; everything else it needs
+// (gdk_android_set_latest_activity in particular) is hidden. GTK ships one caller:
+// JNI_OnLoad in libgtk-4.so, which runs when something calls
+// System.loadLibrary("gtk-4") and which passes NULL for the context, plus
+// RuntimeApplication.startRuntime(), which passes the android.app.Application — and
+// also spawns GTK's own thread and dlopens an application library with a main().
+//
+// A JS host cannot use either. It is not the Application (NativeScript is), so
+// startRuntime is out; and the NULL context from JNI_OnLoad is not enough: gtk_init
+// calls Context.getSystemService() on it and the process dies with
+// "JNI DETECTED ERROR IN APPLICATION: can't call ... getSystemService ... on null
+// object". GIRepository's own dlopen of libgtk-4.so does not run JNI_OnLoad at all.
+//
+// So node-gi calls gdk_android_initialize itself, with the context the host names:
+// the same (Application, app classloader) pair startRuntime uses, and nothing else of
+// it. GTK's comment on that call — "This is *really* questionable, as thiz isn't
+// actually an activity. I've updated the code to handle this case" — is the upstream
+// licence for an Application here: it carries gtk_init over until a real
+// ToplevelActivity reports itself through GdkContext._set_latest_activity().
+//
+// Opt-in, never automatic: dlopening libgtk-4.so pulls in the whole GTK stack, and a
+// host that only wants GLib must not pay for it. See __NODE_GI_ANDROID_GDK in
+// host.nativescript.js.
+
+#include "common.h"
+
+#ifdef __ANDROID__
+
+#include <dlfcn.h>
+#include <jni.h>
+
+#include <mutex>
+#include <string>
+
+// Both set by JNI_OnLoad at the bottom of this file; file-static so both ends see them.
+// The bootstrap class name is the only thing that travels the other way: JNI_OnLoad needs
+// it to find the app's classloader, and only the host knows what the app called it.
+static JavaVM* g_vm = nullptr;
+static jobject g_app_loader = nullptr;
+static std::string g_bootstrap_class;
+
+namespace nodegi {
+
+namespace {
+
+// Describe-and-clear: the exception text is the whole diagnosis, and leaving it pending
+// turns the next JNI call into an abort.
+bool Failed(JNIEnv* env) {
+  if (env->ExceptionCheck() == JNI_FALSE) return false;
+  env->ExceptionDescribe();
+  env->ExceptionClear();
+  return true;
+}
+
+// App classes are invisible to FindClass from here: with no Java frame below the Node-API
+// call, ART resolves against the system classloader, which does not know com.tns.* — the
+// same reason a one-argument Class.forName() fails on this thread. Hence the loader
+// JNI_OnLoad cached, with the thread's context loader and plain FindClass behind it for a
+// host whose classes the system loader does have.
+jclass LoadAppClass(JNIEnv* env, const std::string& jni_name) {
+  std::string dotted = jni_name;
+  for (char& c : dotted)
+    if (c == '/') c = '.';
+
+  jobject loader = g_app_loader;
+  if (loader == nullptr) {
+    jclass thread_class = env->FindClass("java/lang/Thread");
+    jmethodID current =
+        env->GetStaticMethodID(thread_class, "currentThread", "()Ljava/lang/Thread;");
+    jobject thread = env->CallStaticObjectMethod(thread_class, current);
+    if (Failed(env) || thread == nullptr) return nullptr;
+    jmethodID get_loader = env->GetMethodID(thread_class, "getContextClassLoader",
+                                            "()Ljava/lang/ClassLoader;");
+    loader = env->CallObjectMethod(thread, get_loader);
+    if (Failed(env) || loader == nullptr)
+      return static_cast<jclass>(env->FindClass(jni_name.c_str()));
+  }
+
+  jclass loader_class = env->FindClass("java/lang/ClassLoader");
+  jmethodID load_class = env->GetMethodID(loader_class, "loadClass",
+                                          "(Ljava/lang/String;)Ljava/lang/Class;");
+  jstring name = env->NewStringUTF(dotted.c_str());
+  auto found = static_cast<jclass>(env->CallObjectMethod(loader, load_class, name));
+  if (Failed(env) || found == nullptr)
+    return static_cast<jclass>(env->FindClass(jni_name.c_str()));
+  return found;
+}
+
+// androidHasJavaVm() -> boolean
+//
+// Whether JNI_OnLoad has run, i.e. whether the addon has a JavaVM and the app's
+// classloader. Both arrive together and neither can be obtained any other way, so this
+// one answer covers both — the host asks before and after the bootstrap load.
+Napi::Value AndroidHasJavaVm(const Napi::CallbackInfo& info) {
+  return Napi::Boolean::New(info.Env(), g_vm != nullptr);
+}
+
+// androidRegisterJniBootstrap(jniClassName) -> undefined
+//
+// Names the class the host is about to initialize to trigger JNI_OnLoad, in JNI form
+// ('dev/example/JniBootstrap'). JNI_OnLoad looks it up to reach the app's classloader:
+// during a load that ART performs, FindClass resolves against the classloader of the
+// class that called System.loadLibrary, which is the one moment app classes are visible
+// to this library. Must therefore be called BEFORE that load.
+Napi::Value AndroidRegisterJniBootstrap(const Napi::CallbackInfo& info) {
+  Napi::Env env = info.Env();
+  if (info.Length() < 1 || !info[0].IsString()) {
+    Napi::TypeError::New(env, "androidRegisterJniBootstrap(jniClassName): a string is required")
+        .ThrowAsJavaScriptException();
+    return env.Undefined();
+  }
+  g_bootstrap_class = info[0].As<Napi::String>().Utf8Value();
+  return env.Undefined();
+}
+
+bool g_initialized = false;
+// Both JS threads of a NativeScript app share this library — the UI thread and a Worker,
+// and in the stage-5 spike both import node-gi — so the one-time guard needs a lock of its
+// own: gdk_android_initialize has none, and a second run leaks another set of global refs
+// and re-registers every native.
+std::mutex g_init_mutex;
+
+// androidInitGdk(contextClass, contextMethod, contextSignature) -> boolean
+//
+// contextClass/contextMethod name a static method returning the android.content.Context
+// to hand GDK, in JNI form — e.g. ('com/tns/NativeScriptApplication', 'getInstance',
+// '()Landroid/app/Application;'). The host names it because only the host knows how to
+// reach its Application without @hide APIs (android.app.ActivityThread is one).
+// Idempotent, per process rather than per thread — see g_init_mutex.
+Napi::Value AndroidInitGdk(const Napi::CallbackInfo& info) {
+  Napi::Env napi_env = info.Env();
+  std::lock_guard<std::mutex> guard(g_init_mutex);
+  if (g_initialized) return Napi::Boolean::New(napi_env, true);
+
+  if (info.Length() < 3 || !info[0].IsString() || !info[1].IsString() || !info[2].IsString()) {
+    Napi::TypeError::New(napi_env,
+                         "androidInitGdk(contextClass, contextMethod, contextSignature): "
+                         "three strings in JNI form are required")
+        .ThrowAsJavaScriptException();
+    return napi_env.Undefined();
+  }
+  std::string class_name = info[0].As<Napi::String>().Utf8Value();
+  std::string method_name = info[1].As<Napi::String>().Utf8Value();
+  std::string signature = info[2].As<Napi::String>().Utf8Value();
+
+  if (g_vm == nullptr) {
+    Napi::Error::New(napi_env,
+                     "androidInitGdk: no JavaVM — this addon's JNI_OnLoad never ran. "
+                     "Initialize an app class that calls System.loadLibrary(\"node_gi\") "
+                     "first; a dlopen of the library does not run it.")
+        .ThrowAsJavaScriptException();
+    return napi_env.Undefined();
+  }
+
+  // A thread this call attaches has to be detached again: ART aborts a thread that exits
+  // while still attached ("Native thread exiting without having called
+  // DetachCurrentThread"). Safe because gdk_android_initialize keeps the JavaVM and global
+  // refs, never a JNIEnv, and GDK reattaches per call through its own thread-env guard.
+  JNIEnv* env = nullptr;
+  bool attached = false;
+  if (g_vm->GetEnv(reinterpret_cast<void**>(&env), JNI_VERSION_1_6) == JNI_EDETACHED) {
+    if (g_vm->AttachCurrentThread(&env, nullptr) == JNI_OK)
+      attached = true;
+    else
+      env = nullptr;
+  }
+  if (env == nullptr) {
+    Napi::Error::New(napi_env, "androidInitGdk: could not attach this thread to the JavaVM")
+        .ThrowAsJavaScriptException();
+    return napi_env.Undefined();
+  }
+
+  // gdk_android_initialize keeps global refs to both arguments, so a local frame is
+  // enough and nothing here outlives it.
+  env->PushLocalFrame(16);
+  std::string error;
+  do {
+    jclass provider = LoadAppClass(env, class_name);
+    if (Failed(env) || provider == nullptr) {
+      error = "androidInitGdk: no class " + class_name + " on this thread's classloader";
+      break;
+    }
+    jmethodID getter = env->GetStaticMethodID(provider, method_name.c_str(), signature.c_str());
+    if (Failed(env) || getter == nullptr) {
+      error = "androidInitGdk: " + class_name + " has no static " + method_name + signature;
+      break;
+    }
+    jobject context = env->CallStaticObjectMethod(provider, getter);
+    if (Failed(env) || context == nullptr) {
+      error = "androidInitGdk: " + class_name + "." + method_name + "() returned no Context";
+      break;
+    }
+
+    // The classloader GDK resolves org.gtk.android.* with has to be the one that holds
+    // them: the loader of the app's own classes, which is the context's.
+    jclass class_class = env->FindClass("java/lang/Class");
+    jmethodID get_loader = env->GetMethodID(class_class, "getClassLoader",
+                                            "()Ljava/lang/ClassLoader;");
+    jobject loader = env->CallObjectMethod(env->GetObjectClass(context), get_loader);
+    if (Failed(env) || loader == nullptr) {
+      error = "androidInitGdk: the Context's class has no classloader";
+      break;
+    }
+
+    // RTLD_GLOBAL: the backend resolves GDK symbols out of this handle later, and
+    // GIRepository may have loaded libgtk-4.so locally already.
+    void* gtk = dlopen("libgtk-4.so", RTLD_NOW | RTLD_GLOBAL);
+    if (gtk == nullptr) {
+      error = std::string("androidInitGdk: dlopen(libgtk-4.so) failed: ") + dlerror();
+      break;
+    }
+    using InitFn = int (*)(JNIEnv*, jobject, jobject);
+    auto initialize = reinterpret_cast<InitFn>(dlsym(gtk, "gdk_android_initialize"));
+    if (initialize == nullptr) {
+      error = "androidInitGdk: libgtk-4.so exports no gdk_android_initialize "
+              "(GTK built without the Android backend?)";
+      break;
+    }
+    if (initialize(env, loader, context) == 0) {
+      error = "androidInitGdk: gdk_android_initialize() refused — see the GTK log";
+      break;
+    }
+    g_initialized = true;
+  } while (false);
+  env->PopLocalFrame(nullptr);
+  if (attached) g_vm->DetachCurrentThread();
+
+  if (!g_initialized) {
+    Napi::Error::New(napi_env, error).ThrowAsJavaScriptException();
+    return napi_env.Undefined();
+  }
+  return Napi::Boolean::New(napi_env, true);
+}
+
+}  // namespace
+
+void InitAndroidGdk(Napi::Env env, Napi::Object exports) {
+  exports.Set("androidHasJavaVm", Napi::Function::New(env, AndroidHasJavaVm));
+  exports.Set("androidRegisterJniBootstrap",
+              Napi::Function::New(env, AndroidRegisterJniBootstrap));
+  exports.Set("androidInitGdk", Napi::Function::New(env, AndroidInitGdk));
+}
+
+}  // namespace nodegi
+
+// Runs when ART loads this library on behalf of a class — not on the dlopen that the JS
+// runtime does. Two things are available here and nowhere else: the JavaVM, and a
+// FindClass that resolves against the app's classloader rather than the system one.
+extern "C" JNIEXPORT jint JNICALL JNI_OnLoad(JavaVM* vm, void* /*reserved*/) {
+  g_vm = vm;
+  if (g_bootstrap_class.empty()) return JNI_VERSION_1_6;
+
+  JNIEnv* env = nullptr;
+  if (vm->GetEnv(reinterpret_cast<void**>(&env), JNI_VERSION_1_6) != JNI_OK || env == nullptr)
+    return JNI_VERSION_1_6;
+
+  env->PushLocalFrame(4);
+  jclass bootstrap = env->FindClass(g_bootstrap_class.c_str());
+  if (!nodegi::Failed(env) && bootstrap != nullptr) {
+    jmethodID get_loader = env->GetMethodID(env->GetObjectClass(bootstrap), "getClassLoader",
+                                            "()Ljava/lang/ClassLoader;");
+    jobject loader = env->CallObjectMethod(bootstrap, get_loader);
+    if (!nodegi::Failed(env) && loader != nullptr) g_app_loader = env->NewGlobalRef(loader);
+  }
+  env->PopLocalFrame(nullptr);
+  return JNI_VERSION_1_6;
+}
+
+#else
+
+namespace nodegi {
+
+// Off Android there is no JavaVM and no Android GDK backend to initialize; the exports
+// stay so a host can ask without branching on the platform first.
+static Napi::Value AndroidFalse(const Napi::CallbackInfo& info) {
+  return Napi::Boolean::New(info.Env(), false);
+}
+
+void InitAndroidGdk(Napi::Env env, Napi::Object exports) {
+  exports.Set("androidHasJavaVm", Napi::Function::New(env, AndroidFalse));
+  exports.Set("androidRegisterJniBootstrap", Napi::Function::New(env, AndroidFalse));
+  exports.Set("androidInitGdk", Napi::Function::New(env, AndroidFalse));
+}
+
+}  // namespace nodegi
+
+#endif