@gjsify/node-gi 0.37.0 → 0.38.0

package/gtk-runtime.d.ts

@@ -14,4 +14,12 @@ export function maybePrependGtkRuntimeDllPath(): void;
 /** Windows: wire the env for a full-windowing bundle's runtime data — GSettings schemas, gdk-pixbuf loaders, icon themes, fontconfig (no-op off win32 / for a display-free bundle). */
 export function maybeWireGtkWindowingEnv(): void;
 /** Activate the bundled GTK runtime for the native engine, if one is present. */
-export function activateBundledGtkRuntime(native: { prependSearchPath: (p: string) => void }): GtkRuntimeBundle | null;
+export function activateBundledGtkRuntime(native: {
+    prependSearchPath: (p: string) => void;
+    prependLibraryPath?: (p: string) => void;
+}): GtkRuntimeBundle | null;
+
+/** Prepend GI's shared-library search path for the GTK the policy chose. */
+export function activateGiLibraryPath(native: { prependLibraryPath?: (p: string) => void }): string[];
+/** TEST-ONLY: allow the activation to run again. */
+export function resetGiLibraryPathForTests(): void;

package/gtk-runtime.js

@@ -11,7 +11,7 @@ import { createRequire } from 'node:module';
 import { fileURLToPath } from 'node:url';
 import { dirname, join } from 'node:path';
 import { existsSync } from 'node:fs';
-import { pathCovers, splitSearchPath, systemGiLibraryDirs } from './system-gi.js';
+import { composeDyldFallback, pathCovers, splitSearchPath, systemGiLibraryDirs } from './system-gi.js';
 import { nativeCandidates, prebuildAddonPath } from './native-paths.js';
 
 // NB: node:child_process is intentionally NOT imported at module top level. It is
@@ -309,9 +309,11 @@ export function maybeReexecForGtkRuntime() {
     const env = {
         ...process.env,
         [REEXEC_SENTINEL]: '1',
-        // Our dirs first, then whatever the host asked for — falling back to
-        // dyld's own default tail so setting the variable never REMOVES /usr/lib.
-        DYLD_FALLBACK_LIBRARY_PATH: [...libDirs, ...(curDyldDirs.length > 0 ? curDyldDirs : ['/usr/lib'])].join(':'),
+        // Our dirs first, then whatever the host asked for, then dyld's own
+        // default list — setting the variable REPLACES that list, so carrying
+        // it is what keeps the re-exec'd child from searching LESS than the
+        // process that spawned it.
+        DYLD_FALLBACK_LIBRARY_PATH: composeDyldFallback(libDirs),
     };
     // Only a bundle relocates typelibs; a host GI stack's are already on GI's own
     // search path, so the system branch deliberately leaves GI_TYPELIB_PATH alone.
@@ -457,6 +459,57 @@ function gstScannerLeaf() {
     return process.platform === 'win32' ? 'gst-plugin-scanner.exe' : 'gst-plugin-scanner';
 }
 
+let libraryPathActivated = false;
+
+/**
+ * Tell GI where the shared libraries its typelibs name by BARE LEAF actually are
+ * — for whichever GTK the policy chose, and WITHOUT an environment variable.
+ *
+ * THE GAP THIS CLOSES. A typelib records its backer as `libgtk-4.1.dylib`, and on
+ * macOS neither a relocated bundle's `lib` dir nor Homebrew's `/usr/local/lib` is
+ * on dyld's search path. Node papers over it in {@link maybeReexecForGtkRuntime}
+ * by re-execing with `DYLD_FALLBACK_LIBRARY_PATH` set — a Node-shaped re-exec, so
+ * it returns early on bun and deno, which got NO loader repair and died at the
+ * first widget behind three errors that all point elsewhere (`GtkWidget is not
+ * registered…`, `Adw.Application has no property 'application-id'`, `Gtk.GLArea is
+ * not a subclassable GObject type`). Measured on the macOS 15.7.9 x86_64 VM.
+ *
+ * `gi_repository_prepend_library_path()` is GI's own answer, so nothing is
+ * captured at process launch: identical on node, bun and deno, no re-exec, and the
+ * environment is left alone. The env paths elsewhere in this module stay — they
+ * still cover a dylib pulled in by ANOTHER dylib's link closure, which never
+ * passes through GI.
+ *
+ * The dirs come from `gtkSource()`, not a second opinion: the bundle's `libDir`
+ * for `bundle`, `systemGiLibraryDirs()` for `system` — the pair the re-exec
+ * composes. Mixing them is the two-copies hazard #920 records. Idempotent, and
+ * never fatal: an addon predating the binding changes nothing.
+ * @param {{ prependLibraryPath?: (p: string) => void }} native the loaded addon
+ * @returns {string[]} the directories handed to GI (empty when there was nothing to add)
+ */
+export function activateGiLibraryPath(native) {
+    if (libraryPathActivated) return [];
+    libraryPathActivated = true;
+    if (typeof native?.prependLibraryPath !== 'function') return [];
+
+    const source = gtkSource();
+    const dirs =
+        source === 'bundle' ? [resolveGtkRuntimeBundle()?.libDir] : source === 'system' ? systemGiLibraryDirs() : [];
+    const applied = [];
+    // LAST wins with a prepend, so walking in reverse leaves the array's own
+    // order intact in GI's search path.
+    for (const dir of dirs.filter(Boolean).reverse()) {
+        native.prependLibraryPath(dir);
+        applied.unshift(dir);
+    }
+    return applied;
+}
+
+/** TEST-ONLY: allow a spec to run the activation again. */
+export function resetGiLibraryPathForTests() {
+    libraryPathActivated = false;
+}
+
 let activated = null; // memoize: the activation result (idempotent)
 
 /**
@@ -502,9 +555,10 @@ export function activateBundledGtkRuntime(native) {
     } else {
         const existing = process.env.DYLD_FALLBACK_LIBRARY_PATH;
         if (!existing || !existing.split(':').includes(bundle.libDir)) {
-            process.env.DYLD_FALLBACK_LIBRARY_PATH = existing
-                ? `${bundle.libDir}:${existing}`
-                : `${bundle.libDir}:/usr/lib`;
+            // Same composition as the re-exec above: the bundle's libdir first,
+            // then the inherited value, then dyld's default list — which this
+            // variable REPLACES rather than extends.
+            process.env.DYLD_FALLBACK_LIBRARY_PATH = composeDyldFallback([bundle.libDir]);
         }
     }
 

package/index.d.ts

@@ -65,6 +65,8 @@ export function setErrorBuilder(
 
 /** Prepend a directory to the GIRepository typelib search path. */
 export function prependSearchPath(path: string): void;
+/** Prepend a directory GI searches for the SHARED LIBRARY a typelib names. */
+export function prependLibraryPath(path: string): void;
 
 /**
  * Invoke a namespace-level GObject-Introspection function (not an instance
@@ -519,6 +521,7 @@ declare const native: {
     getErrorDomain: typeof getErrorDomain;
     setErrorBuilder: typeof setErrorBuilder;
     prependSearchPath: typeof prependSearchPath;
+    prependLibraryPath: typeof prependLibraryPath;
     callFunction: typeof callFunction;
     callMethod: typeof callMethod;
     hasMethod: typeof hasMethod;

package/index.js

@@ -11,6 +11,7 @@ import { hostTarget, nativeCandidates, packageRoot } from './native-paths.js';
 import { describeAddonLoadFailure } from './load-diagnostics.js';
 import {
     activateBundledGtkRuntime,
+    activateGiLibraryPath,
     maybePrependGtkRuntimeDllPath,
     maybeReexecForGtkRuntime,
     maybeWireGtkWindowingEnv,
@@ -123,6 +124,16 @@ try {
     // Never fatal: a missing/partial bundle just leaves the host GTK in charge.
 }
 
+// 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
@@ -182,6 +193,7 @@ export const getEnumValues = native.getEnumValues;
 export const getErrorDomain = native.getErrorDomain;
 export const setErrorBuilder = native.setErrorBuilder;
 export const prependSearchPath = native.prependSearchPath;
+export const prependLibraryPath = native.prependLibraryPath;
 export const callFunction = native.callFunction;
 export const callMethod = native.callMethod;
 export const hasMethod = native.hasMethod;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gjsify/node-gi",
-  "version": "0.37.0",
+  "version": "0.38.0",
   "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",

package/src/addon.cc

@@ -74,6 +74,7 @@ static Napi::Object Init(Napi::Env env, Napi::Object exports) {
   exports.Set("getErrorDomain", Napi::Function::New(env, GetErrorDomain));
   exports.Set("setErrorBuilder", Napi::Function::New(env, SetErrorBuilder));
   exports.Set("prependSearchPath", Napi::Function::New(env, PrependSearchPath));
+  exports.Set("prependLibraryPath", Napi::Function::New(env, PrependLibraryPath));
   exports.Set("callFunction", Napi::Function::New(env, CallFunction));
   exports.Set("callMethod", Napi::Function::New(env, CallMethod));
   exports.Set("hasMethod", Napi::Function::New(env, HasMethod));

package/src/common.h

@@ -550,6 +550,7 @@ Napi::Value GetEnumValues(const Napi::CallbackInfo& info);
 Napi::Value GetErrorDomain(const Napi::CallbackInfo& info);
 Napi::Value SetErrorBuilder(const Napi::CallbackInfo& info);
 Napi::Value PrependSearchPath(const Napi::CallbackInfo& info);
+Napi::Value PrependLibraryPath(const Napi::CallbackInfo& info);
 
 // calls.cc
 Napi::Value CallFunction(const Napi::CallbackInfo& info);

package/src/repo.cc

@@ -295,4 +295,30 @@ Napi::Value PrependSearchPath(const Napi::CallbackInfo& info) {
   return env.Undefined();
 }
 
+// prependLibraryPath(path: string) -> void
+// The LIBRARY twin of PrependSearchPath: where GI looks for the shared object a
+// typelib names, as opposed to where it looks for the typelib itself.
+//
+// Native rather than `requireGi('GIRepository').…` because the bundled runtime
+// ships GIRepository 3.0, whose `Repository` this bridge exposes neither as
+// constructible nor with a `get_default()` static — measured, both throw. The C
+// entry point has no such gap and reuses the same `DupDefaultRepository()` handle.
+//
+// It is the env-free repair for a typelib backer named by BARE LEAF: no variable,
+// no re-exec, identical on node, bun and deno. See `gtk-runtime.js`
+// (`activateGiLibraryPath`) for the incident.
+Napi::Value PrependLibraryPath(const Napi::CallbackInfo& info) {
+  Napi::Env env = info.Env();
+  if (info.Length() < 1 || !info[0].IsString()) {
+    Napi::TypeError::New(env, "prependLibraryPath(path: string)")
+        .ThrowAsJavaScriptException();
+    return env.Undefined();
+  }
+  std::string path = info[0].As<Napi::String>().Utf8Value();
+  GIRepository* repo = DupDefaultRepository();
+  gi_repository_prepend_library_path(repo, path.c_str());
+  g_object_unref(repo);
+  return env.Undefined();
+}
+
 }  // namespace nodegi

package/system-gi.js

@@ -227,3 +227,43 @@ export function systemGiLibraryDirs({
 export function pathCovers(wanted, current) {
     return wanted.every((dir) => current.includes(dir));
 }
+
+/**
+ * dyld's OWN default fallback list, verbatim from `dyld(1)`:
+ * `$HOME/lib:/usr/local/lib:/lib:/usr/lib`.
+ *
+ * Load-bearing because `DYLD_FALLBACK_LIBRARY_PATH` REPLACES this list rather
+ * than extending it, so a composition that omits part of it hands the child a
+ * SMALLER search path than the same child would have had with the variable
+ * unset. MEASURED, and it cost a whole platform: both writers used to append a
+ * bare `/usr/lib`, dropping `/usr/local/lib` — where every Homebrew GTK library
+ * lives on Intel macOS — so every `gjsify` gjs command on such a Mac died in
+ * `dlopen(libsoup-3.0.0.dylib)` before it had downloaded anything (the CLI's own
+ * fetcher goes through Soup), and so did the Node-free bootstrap the Getting
+ * Started page prints. The tell that it was OURS: plain
+ * `gjs -c 'imports.gi.Soup'` loads fine with no DYLD variable set.
+ * @param {Record<string, string | undefined>} [env]
+ * @returns {string[]}
+ */
+export function dyldDefaultFallbackDirs(env = process.env) {
+    const home = env['HOME'];
+    return [...(home ? [`${home}/lib`] : []), '/usr/local/lib', '/lib', '/usr/lib'];
+}
+
+/**
+ * Compose a `DYLD_FALLBACK_LIBRARY_PATH` value: `wanted`, then the launching
+ * environment's own value, then {@link dyldDefaultFallbackDirs} —
+ * unconditionally, because the target is a CHILD (a re-exec, or a spawned gjs)
+ * and it must never search less than one launched without gjsify. Deduplicated:
+ * `systemGiLibraryDirs()` can legitimately yield a directory the tail also
+ * names, and a repeat costs the loader a second stat on every miss. First
+ * occurrence wins everywhere, so dropping later repeats preserves behaviour.
+ * @param {readonly string[]} wanted
+ * @param {Record<string, string | undefined>} [env]
+ * @returns {string}
+ */
+export function composeDyldFallback(wanted, env = process.env) {
+    return [
+        ...new Set([...wanted, ...splitSearchPath(env['DYLD_FALLBACK_LIBRARY_PATH']), ...dyldDefaultFallbackDirs(env)]),
+    ].join(':');
+}