@gjsify/node-gi 0.59.0 → 0.60.0

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.d.ts

@@ -138,6 +138,16 @@ export interface GObjectNamespace extends GiNamespace {
      */
     registerClass(klass: Function): Function;
     registerClass(meta: RegisterClassMeta, klass: Function): Function;
+    /**
+     * Static-field key for {@link RegisterClassMeta.GTypeName} — gjs's meta FIELD form,
+     * `Klass[GObject.GTypeName] = 'X'` instead of a meta object. A meta object passed to
+     * `registerClass` still wins over the field.
+     */
+    GTypeName: symbol;
+    /** Static-field key for {@link RegisterClassMeta.Properties} (the field form of the meta). */
+    properties: symbol;
+    /** Static-field key for {@link RegisterClassMeta.Signals} (the field form of the meta). */
+    signals: symbol;
     ParamSpec: ParamSpecFactories;
     /**
      * The FULL introspected `GParamFlags` bitfield (READABLE/WRITABLE/READWRITE/

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.
@@ -818,6 +809,12 @@ function handlerIdsForFunc(handle, fn) {
 // routing keys on the leaf so construction is correct at any depth.
 const registeredClasses = new Map();
 
+// A registered class's prototype → the kebab names of the CUSTOM GObject properties
+// it declared, plus every registered ancestor's. Keyed by the prototype because that
+// is what an instance carries (USER_PROTO), and the set trap is the only consumer:
+// see the equal-value guard in wrapInstance.
+const customPropertiesByProto = new WeakMap();
+
 // GTypeName → registered JS class, the reverse of registeredClasses. The engine's
 // NodeGiConstructor hands runCtorForCObject (below) the C-created instance's GType
 // NAME (g_type_name), which this resolves back to the class to Reflect.construct.
@@ -1082,6 +1079,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 +1099,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 +1124,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);
@@ -1313,6 +1315,33 @@ function wrapInstance(handle, userProto) {
     const target = { [HANDLE]: handle };
     const proto = userProto ?? protoForInstance(handle);
     if (proto !== undefined) linkInstanceProto(target, proto);
+    // Which CUSTOM properties of this instance have a value yet — the thing GJS's
+    // generated accessors track with the PRESENCE of their private field, and what its
+    // setter's equal-value guard actually compares against (`value !== this[privateName]`,
+    // refs/gjs/modules/core/_common.js). Not the ParamSpec default: on gjs 1.88.1 a fresh
+    // object's `o.p = <default>` DOES notify (the field holds `undefined`), while the same
+    // assignment after a READ does not — the getter installs the default into the field
+    // first (`if (!(privateName in this)) this[privateName] = defaultValue`) — and nor
+    // does it after `new K({p: <default>})`, since the construct value went through the
+    // setter. Three behaviours, one state: has the value been materialised.
+    //
+    // Seeded lazily from what the ENGINE has stored (`storedPropertyNames` — construct
+    // values included), then extended by every read and write through this wrapper. A set
+    // from C on a property no JS code has touched is the one gap, and it falls back to
+    // notifying — what node-gi did before the guard existed. Same for an addon too old to
+    // export storedPropertyNames (the cross-version pairing of the shipped-closure legs,
+    // see runJsPropertySetter): the guard then only narrows, never widens.
+    let materialised;
+    const materialise = (name) => {
+        if (materialised === undefined) {
+            materialised = new Set(
+                typeof native.storedPropertyNames === 'function' ? native.storedPropertyNames(handle) : [],
+            );
+        }
+        const had = materialised.has(name);
+        materialised.add(name);
+        return had;
+    };
     const proxy = new Proxy(target, {
         get(t, prop) {
             if (prop === HANDLE) return handle;
@@ -1404,6 +1433,14 @@ function wrapInstance(handle, userProto) {
             if (shim !== undefined) return (...args) => shim(handle, args);
             const propName = toKebab(prop);
             if (native.hasProperty(handle, propName)) {
+                // A READ materialises a custom property's value, exactly as GJS's generated
+                // getter writes the default into its private field on first look-up — which
+                // is what makes a LATER assignment of that same default silent. See the
+                // equal-value guard in the set trap.
+                const up = t[USER_PROTO];
+                if (up !== undefined && customPropertiesByProto.get(up)?.has(propName) === true) {
+                    materialise(propName);
+                }
                 return wrapReturn(native.getProperty(handle, propName));
             }
             // LAST resort before treating an unknown name as a GI method: an INHERITED
@@ -1448,6 +1485,29 @@ function wrapInstance(handle, userProto) {
                 }
                 const propName = toKebab(prop);
                 if (native.hasProperty(handle, propName)) {
+                    // Equal-value guard, GJS's `_generateAccessors` setter verbatim:
+                    // `if (value !== this[privateName]) { …; this.notify(name) }`
+                    // (refs/gjs/modules/core/_common.js). GJS puts it in the accessor it
+                    // GENERATES for a declared property, so it covers exactly the custom
+                    // properties with no accessor of the class's own — the branch above
+                    // already took every class-declared accessor, and `set_property`
+                    // bypasses the accessor and so keeps notifying unconditionally on both
+                    // runtimes (measured on gjs 1.88.1: assignment [1,1,2], set_property
+                    // [1,2,3]). node-gi installs no generated accessors (the engine store
+                    // IS the backing store, see findPropertySetter), so without this the
+                    // store's unconditional g_object_notify_by_pspec made every assignment
+                    // notify — [1,2,3] where gjs gives [1,1,2], and the three spellings of
+                    // a dashed name notified once EACH instead of sharing one.
+                    //
+                    // Only once the value is MATERIALISED (see `materialise`): an unset
+                    // property's private field is `undefined` on gjs, never the ParamSpec
+                    // default, so the first assignment notifies even when it equals the
+                    // default. The dash spelling is the key, since toKebab canonicalises
+                    // all three spellings onto it.
+                    const custom = up !== undefined && customPropertiesByProto.get(up)?.has(propName) === true;
+                    if (custom && materialise(propName)) {
+                        if (wrapReturn(native.getProperty(handle, propName)) === value) return true;
+                    }
                     native.setProperty(handle, propName, unwrapArg(value));
                     return true;
                 }
@@ -1699,10 +1759,17 @@ function makeClass(namespace, typeName) {
                     handle = native.constructType(reg.typeHandle, props ? unwrapProps(props) : {});
                 }
                 const instance = wrapInstance(handle, nt.prototype);
-                assignTemplateChildren(instance, handle, reg);
                 // Route construct-time property values through the class's JS setters now
                 // that USER_PROTO is attached — before the user ctor body runs (GJS order).
+                //
+                // BEFORE the template children, because that is the order GJS produces: a
+                // construct property's setter runs inside g_object_new, where the template
+                // is not yet built, so it sees `this._child === undefined`; the children
+                // appear only once construction returns. Binding them first made a setter
+                // observe a child GJS cannot have handed it yet, so a class that guards on
+                // `if (this._child)` took the wrong branch on node-gi and only on node-gi.
                 flushPropertiesToJsSetters(instance, handle, reg);
+                assignTemplateChildren(instance, handle, reg);
                 return instance;
             }
             // `nt` is a subclass of this introspected GObject class but was NEVER passed to
@@ -2353,6 +2420,19 @@ function collectVfuncs(klass) {
  * @param {Function} [maybeClass]
  * @returns {Function} the same `klass` (now registered)
  */
+// GJS's meta FIELD form: a class may declare its meta as static symbol fields
+// (`Klass[GObject.GTypeName] = 'X'`) instead of passing a meta object, and GJS treats
+// the symbols as the real source — `registerClass(meta, klass)` only copies meta onto
+// them and reads them back (refs/gjs/modules/core/_common.js). The descriptions match
+// GJS's so a stringified symbol reads the same in both runtimes.
+//
+// GObject.interfaces / GObject.interface requires are deliberately absent: registerClass
+// implements no interfaces in EITHER form yet, and a symbol that is accepted and then
+// ignored promises more than the object form delivers.
+const GTypeNameSymbol = Symbol('GType name');
+const propertiesSymbol = Symbol('GObject properties');
+const signalsSymbol = Symbol('GObject signals');
+
 function registerClass(metaOrClass, maybeClass) {
     let meta;
     let klass;
@@ -2367,6 +2447,17 @@ function registerClass(metaOrClass, maybeClass) {
         throw new TypeError('GObject.registerClass: expected a class to register');
     }
 
+    // Fold in whatever the class declared as symbol fields, with the meta OBJECT winning
+    // — the same precedence GJS gets from copying meta onto the symbols before reading
+    // them. Until the symbols existed on the namespace, `{[G.GTypeName]: 'X'}` wrote a
+    // literal "undefined" key and the whole declaration vanished without a word: the
+    // GTypeName fell back to the class name and the signals were never registered.
+    const fieldMeta = {};
+    if (klass[GTypeNameSymbol] !== undefined) fieldMeta.GTypeName = klass[GTypeNameSymbol];
+    if (klass[propertiesSymbol] !== undefined) fieldMeta.Properties = klass[propertiesSymbol];
+    if (klass[signalsSymbol] !== undefined) fieldMeta.Signals = klass[signalsSymbol];
+    meta = { ...fieldMeta, ...meta };
+
     const parent = findParentGType(klass);
     if (parent === undefined) {
         throw new TypeError(
@@ -2460,6 +2551,18 @@ function registerClass(metaOrClass, maybeClass) {
         internalChildren: internalChildren.length > 0 ? internalChildren : undefined,
         constructPropertyNames: constructPropertyNames.length > 0 ? constructPropertyNames : undefined,
     });
+    // Which properties the equal-value guard owns: the ones DECLARED here, union the
+    // registered parent's (a G2 subclass inherits its parent's custom properties and
+    // the guard must follow them down). Introspected properties are deliberately
+    // absent — their C setter decides whether an equal value notifies, and guarding
+    // them here would answer for it.
+    const inheritedCustom = registeredClasses.get(Object.getPrototypeOf(klass))?.customProperties;
+    const customProperties = new Set(inheritedCustom);
+    for (const p of properties) {
+        if (typeof p.name === 'string') customProperties.add(p.name);
+    }
+    registeredClasses.get(klass).customProperties = customProperties;
+    customPropertiesByProto.set(klass.prototype, customProperties);
     // Reverse index for runCtorForCObject: the engine identifies a C-created instance
     // by its GType name (= gtypeName, what native.registerClass registered).
     classesByGType.set(gtypeName, klass);
@@ -2555,6 +2658,9 @@ function signalEmitByName(object, ...nameAndArgs) {
 // makeClass). Merged enums are cached so identity is stable.
 const OVERLAY_NAMES = new Set([
     'registerClass',
+    'GTypeName',
+    'properties',
+    'signals',
     'ParamSpec',
     'ParamFlags',
     'SignalFlags',
@@ -2621,6 +2727,9 @@ function decorateGObjectNamespace(baseNs) {
         if (cache.has(prop)) return cache.get(prop);
         let value;
         if (prop === 'registerClass') value = registerClass;
+        else if (prop === 'GTypeName') value = GTypeNameSymbol;
+        else if (prop === 'properties') value = propertiesSymbol;
+        else if (prop === 'signals') value = signalsSymbol;
         else if (prop === 'ParamSpec') value = ParamSpec;
         else if (prop === 'ParamFlags') value = mergeFlags(baseNs.ParamFlags, ParamFlags);
         else if (prop === 'SignalFlags') value = mergeFlags(baseNs.SignalFlags, SignalFlags);
@@ -2794,6 +2903,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,242 @@
+// 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`);
+}
+
+/**
+ * The names under which NativeScript's own module loader can be reached from the GLOBAL scope,
+ * in the order a bundle may offer them. `system_lib://` is the runtime's scheme, so whichever
+ * of these answers, it is the same loader underneath.
+ *
+ *   * `require` — the loader the runtime installs globally. A CommonJS bundle also has a
+ *     module-scoped `require`, but that one is the BUNDLER's; reading the global by name is
+ *     what keeps the two apart, and it is why this list is read off a scope object rather
+ *     than written as bare identifiers.
+ *   * `__nativeRequire` — the same loader under the name the runtime uses internally
+ *     (measured in @nativescript/android 9.1's libNativeScript.so, beside `ns:module`'s
+ *     `createRequire`). It is the fallback for a runtime that stops exposing `require`
+ *     globally, which an ESM-only bundle would otherwise have no way to reach.
+ */
+const RUNTIME_REQUIRE_GLOBALS = ['require', '__nativeRequire'];
+
+/**
+ * Pick the function that can load `system_lib://libnode_gi.so`.
+ *
+ * WHY THIS IS A CHAIN AND NOT webpack's ONE NAME. `__non_webpack_require__` only exists
+ * because webpack REWRITES that free identifier to the runtime's require; under
+ * @nativescript/vite (Rolldown, ESM output) nothing rewrites it, so the old single check made
+ * every non-webpack NativeScript bundle fail at the first `requireGi` with a message telling
+ * the app to switch bundlers — which is not a fix available to a vite app.
+ *
+ * ORDER MATTERS. webpack's rewrite wins first: in a webpack bundle the module-scoped `require`
+ * is webpack's own and would resolve `system_lib://…` against the bundle graph instead of the
+ * runtime. Only after that do the runtime's global names get a turn.
+ *
+ * Pure on purpose — `scope` is an argument so the chain is testable without a device
+ * (`test/host-nativescript.test.mjs`).
+ *
+ * @param {Record<string, unknown>} scope the global object to read the runtime names off
+ * @param {unknown} webpackRequire webpack's rewritten `__non_webpack_require__`, if any
+ * @returns {{ load: ((id: string) => any) | null, via: string | null }}
+ */
+export function resolveNativeRequire(scope, webpackRequire) {
+    if (typeof webpackRequire === 'function') {
+        return { load: /** @type {(id: string) => any} */ (webpackRequire), via: '__non_webpack_require__' };
+    }
+    for (const name of RUNTIME_REQUIRE_GLOBALS) {
+        const candidate = scope?.[name];
+        if (typeof candidate === 'function') {
+            return { load: /** @type {(id: string) => any} */ (candidate), via: name };
+        }
+    }
+    return { load: null, via: null };
+}
+
+/**
+ * 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();
+    // The bare identifier is what webpack rewrites; everything else is read off the global
+    // scope inside resolveNativeRequire.
+    const { load } = resolveNativeRequire(
+        globalThis,
+        typeof __non_webpack_require__ === 'function' ? __non_webpack_require__ : undefined,
+    );
+    if (load === null) {
+        throw new Error(
+            '@gjsify/node-gi: the NativeScript host found no module loader to pass ' +
+                "'system_lib://libnode_gi.so' to. It looked for __non_webpack_require__ (webpack " +
+                `rewrites it) and then for ${RUNTIME_REQUIRE_GLOBALS.map((n) => `globalThis.${n}`).join(' and ')}` +
+                " — the names NativeScript's own loader answers to. None of them is a function, which " +
+                'means this is not a NativeScript runtime, or its loader moved.',
+        );
+    }
+    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;
+}