@gjsify/node-gi 0.26.1 → 0.27.1

package/globals.d.ts

@@ -6,38 +6,38 @@ import type { GettextModule } from './gettext.js';
 
 /** The legacy GJS `imports` object (a minimal Node-backed subset). */
 export interface GjsImports {
-  /** `imports.gi.<Ns>` resolves a namespace; `imports.gi.versions.<Ns>` pins a version. */
-  gi: {
-    versions: Record<string, string | undefined>;
-    [namespace: string]: unknown;
-  };
-  /** `imports.system` — the `@gjsify/node-gi/system` module (process identity + lifecycle). */
-  system: SystemModule;
-  /** `imports.gettext` — the `@gjsify/node-gi/gettext` module (no-translation passthrough). */
-  gettext: GettextModule;
-  /** `imports.byteArray` — the legacy GJS byte-array module (GJS semantics: zero-terminated, fatal decode). */
-  byteArray: {
-    ByteArray: new (arg?: number | Uint8Array) => {
-      length: number;
-      toString(encoding?: string): string;
-      toGBytes(): unknown;
+    /** `imports.gi.<Ns>` resolves a namespace; `imports.gi.versions.<Ns>` pins a version. */
+    gi: {
+        versions: Record<string, string | undefined>;
+        [namespace: string]: unknown;
     };
-    fromArray(array: Iterable<number>): unknown;
-    fromGBytes(bytes: unknown): Uint8Array;
-    fromString(string: string, encoding?: string): Uint8Array;
-    toGBytes(array: Uint8Array): unknown;
-    toString(byteArray: Uint8Array, encoding?: string): string;
-  };
-  versions: Record<string, unknown>;
+    /** `imports.system` — the `@gjsify/node-gi/system` module (process identity + lifecycle). */
+    system: SystemModule;
+    /** `imports.gettext` — the `@gjsify/node-gi/gettext` module (no-translation passthrough). */
+    gettext: GettextModule;
+    /** `imports.byteArray` — the legacy GJS byte-array module (GJS semantics: zero-terminated, fatal decode). */
+    byteArray: {
+        ByteArray: new (arg?: number | Uint8Array) => {
+            length: number;
+            toString(encoding?: string): string;
+            toGBytes(): unknown;
+        };
+        fromArray(array: Iterable<number>): unknown;
+        fromGBytes(bytes: unknown): Uint8Array;
+        fromString(string: string, encoding?: string): Uint8Array;
+        toGBytes(array: Uint8Array): unknown;
+        toString(byteArray: Uint8Array, encoding?: string): string;
+    };
+    versions: Record<string, unknown>;
 }
 
 declare global {
-  var print: (...args: unknown[]) => void;
-  var printerr: (...args: unknown[]) => void;
-  var log: (...args: unknown[]) => void;
-  var logError: (error: unknown, prefix?: string) => void;
-  var ARGV: string[];
-  var imports: GjsImports;
+    var print: (...args: unknown[]) => void;
+    var printerr: (...args: unknown[]) => void;
+    var log: (...args: unknown[]) => void;
+    var logError: (error: unknown, prefix?: string) => void;
+    var ARGV: string[];
+    var imports: GjsImports;
 }
 
 /** Install the GJS ambient globals on `globalThis` (idempotent). */

package/globals.js

@@ -29,7 +29,7 @@ import { createPackage } from './overrides/package.js';
 // GJS stringifies each argument with String() and joins with a space (no
 // util.inspect object formatting) — match that for fidelity.
 function gjsFormat(args) {
-  return args.map((a) => String(a)).join(' ');
+    return args.map((a) => String(a)).join(' ');
 }
 
 /**
@@ -37,112 +37,118 @@ function gjsFormat(args) {
  * only defined if absent, so it never clobbers a host that already provides it).
  */
 export function installGjsGlobals() {
-  const g = globalThis;
+    const g = globalThis;
 
-  if (typeof g.print === 'undefined') {
-    g.print = (...args) => console.log(gjsFormat(args));
-  }
-  if (typeof g.printerr === 'undefined') {
-    g.printerr = (...args) => console.error(gjsFormat(args));
-  }
-  if (typeof g.log === 'undefined') {
-    // GJS `log` writes to the GLib structured log (stderr/journal).
-    g.log = (...args) => console.error(gjsFormat(args));
-  }
-  if (typeof g.logError === 'undefined') {
-    g.logError = (error, prefix) => {
-      const head = prefix ? `${prefix}: ` : '';
-      const body = error && error.stack ? error.stack : String(error);
-      console.error(head + body);
-    };
-  }
-  if (typeof g.ARGV === 'undefined') {
-    // GJS ARGV excludes the interpreter + the script path (Node's argv[0]+[1]).
-    g.ARGV = (typeof process !== 'undefined' && Array.isArray(process.argv))
-      ? process.argv.slice(2)
-      : [];
-  }
+    if (typeof g.print === 'undefined') {
+        g.print = (...args) => console.log(gjsFormat(args));
+    }
+    if (typeof g.printerr === 'undefined') {
+        g.printerr = (...args) => console.error(gjsFormat(args));
+    }
+    if (typeof g.log === 'undefined') {
+        // GJS `log` writes to the GLib structured log (stderr/journal).
+        g.log = (...args) => console.error(gjsFormat(args));
+    }
+    if (typeof g.logError === 'undefined') {
+        g.logError = (error, prefix) => {
+            const head = prefix ? `${prefix}: ` : '';
+            const body = error && error.stack ? error.stack : String(error);
+            console.error(head + body);
+        };
+    }
+    if (typeof g.ARGV === 'undefined') {
+        // GJS ARGV excludes the interpreter + the script path (Node's argv[0]+[1]).
+        g.ARGV = typeof process !== 'undefined' && Array.isArray(process.argv) ? process.argv.slice(2) : [];
+    }
 
-  if (typeof g.imports === 'undefined') {
-    g.imports = makeImports();
-  }
+    if (typeof g.imports === 'undefined') {
+        g.imports = makeImports();
+    }
 
-  return g.imports;
+    return g.imports;
 }
 
 // Build the legacy `imports` object. `imports.gi.<Ns>` resolves a namespace via
 // the node-gi backend, honouring a version pinned in `imports.gi.versions.<Ns>`
 // (which GJS code sets before the first access).
 function makeImports() {
-  const giVersions = Object.create(null);
-  const giCache = new Map();
-  const gi = new Proxy(
-    { versions: giVersions },
-    {
-      get(target, name) {
-        if (name === 'versions') return giVersions;
-        if (typeof name !== 'string') return target[name];
-        if (giCache.has(name)) return giCache.get(name);
-        const ns = requireGi(name, giVersions[name]);
-        giCache.set(name, ns);
-        return ns;
-      },
-      has(_target, name) {
-        return name === 'versions' || typeof name === 'string';
-      },
-    },
-  );
+    const giVersions = Object.create(null);
+    const giCache = new Map();
+    const gi = new Proxy(
+        { versions: giVersions },
+        {
+            get(target, name) {
+                if (name === 'versions') return giVersions;
+                if (typeof name !== 'string') return target[name];
+                if (giCache.has(name)) return giCache.get(name);
+                const ns = requireGi(name, giVersions[name]);
+                giCache.set(name, ns);
+                return ns;
+            },
+            has(_target, name) {
+                return name === 'versions' || typeof name === 'string';
+            },
+        },
+    );
 
-  // `imports.system` + `imports.gettext` + `imports.cairo` are the standalone
-  // module objects (`./system.js` / `./gettext.js` / `./cairo.js`) — the single
-  // source of truth for those surfaces, shared with the bare `system` / `gettext` /
-  // `cairo` specifiers on Node.
-  //
-  // `imports.signals` is the pure-JS Signals mixin (`addSignalMethods` + the
-  // `_connect`/`_disconnect`/`_emit`/… primitives), the SAME module the DBus proxy
-  // surface uses. `imports.mainloop` (a lazy getter — it needs GLib, and a source
-  // that never touches the main loop should not pull GLib in) is the thin
-  // GLib.MainLoop convenience layer.
-  const { addSignalMethods, _connect, _connectAfter, _disconnect, _emit, _signalHandlerIsConnected, _disconnectAll } =
-    signalsModule;
-  const imports = {
-    gi,
-    system,
-    gettext,
-    cairo,
-    // `imports.byteArray` — the legacy GJS byte-array module
-    // (fromGBytes/toGBytes/fromString/toString/fromArray/ByteArray), the seam
-    // `@gjsify/utils`' gbytesToUint8Array/cli() read subprocess output through.
-    // GLib is only pulled in lazily (toGBytes), so seeding it here is free.
-    byteArray: createByteArray(requireGi),
-    signals: { addSignalMethods, _connect, _connectAfter, _disconnect, _emit, _signalHandlerIsConnected, _disconnectAll },
-    // GJS's `imports.searchPath` — `imports.package.init` unshifts the app's
-    // moduledir onto it. Inert on node-gi (ESM + gi://), but present + safe so
-    // source that reads/mutates it doesn't throw.
-    searchPath: [],
-    versions: Object.create(null),
-  };
-  let mainloop;
-  Object.defineProperty(imports, 'mainloop', {
-    get() {
-      if (mainloop === undefined) mainloop = createMainloop(requireGi('GLib', '2.0'));
-      return mainloop;
-    },
-    enumerable: true,
-    configurable: true,
-  });
-  // `imports.package` — the GJS application bootstrap (pkg.init/initGettext/
-  // initFormat). Lazy like `mainloop`: a bundle that never calls it pulls no GLib.
-  let pkg;
-  Object.defineProperty(imports, 'package', {
-    get() {
-      if (pkg === undefined) pkg = createPackage({ requireGi, gettext, imports });
-      return pkg;
-    },
-    enumerable: true,
-    configurable: true,
-  });
-  return imports;
+    // `imports.system` + `imports.gettext` + `imports.cairo` are the standalone
+    // module objects (`./system.js` / `./gettext.js` / `./cairo.js`) — the single
+    // source of truth for those surfaces, shared with the bare `system` / `gettext` /
+    // `cairo` specifiers on Node.
+    //
+    // `imports.signals` is the pure-JS Signals mixin (`addSignalMethods` + the
+    // `_connect`/`_disconnect`/`_emit`/… primitives), the SAME module the DBus proxy
+    // surface uses. `imports.mainloop` (a lazy getter — it needs GLib, and a source
+    // that never touches the main loop should not pull GLib in) is the thin
+    // GLib.MainLoop convenience layer.
+    const { addSignalMethods, _connect, _connectAfter, _disconnect, _emit, _signalHandlerIsConnected, _disconnectAll } =
+        signalsModule;
+    const imports = {
+        gi,
+        system,
+        gettext,
+        cairo,
+        // `imports.byteArray` — the legacy GJS byte-array module
+        // (fromGBytes/toGBytes/fromString/toString/fromArray/ByteArray), the seam
+        // `@gjsify/utils`' gbytesToUint8Array/cli() read subprocess output through.
+        // GLib is only pulled in lazily (toGBytes), so seeding it here is free.
+        byteArray: createByteArray(requireGi),
+        signals: {
+            addSignalMethods,
+            _connect,
+            _connectAfter,
+            _disconnect,
+            _emit,
+            _signalHandlerIsConnected,
+            _disconnectAll,
+        },
+        // GJS's `imports.searchPath` — `imports.package.init` unshifts the app's
+        // moduledir onto it. Inert on node-gi (ESM + gi://), but present + safe so
+        // source that reads/mutates it doesn't throw.
+        searchPath: [],
+        versions: Object.create(null),
+    };
+    let mainloop;
+    Object.defineProperty(imports, 'mainloop', {
+        get() {
+            if (mainloop === undefined) mainloop = createMainloop(requireGi('GLib', '2.0'));
+            return mainloop;
+        },
+        enumerable: true,
+        configurable: true,
+    });
+    // `imports.package` — the GJS application bootstrap (pkg.init/initGettext/
+    // initFormat). Lazy like `mainloop`: a bundle that never calls it pulls no GLib.
+    let pkg;
+    Object.defineProperty(imports, 'package', {
+        get() {
+            if (pkg === undefined) pkg = createPackage({ requireGi, gettext, imports });
+            return pkg;
+        },
+        enumerable: true,
+        configurable: true,
+    });
+    return imports;
 }
 
 // Side effect on import: seed the globals.

package/gtk-runtime.js

@@ -1,14 +1,17 @@
 // SPDX-License-Identifier: MIT
 // @gjsify/node-gi/gtk-runtime — locate + activate a batteries-included, relocated
 // GTK/GObject-Introspection runtime bundle so gi:// namespaces load with NO system
-// or Homebrew GTK (Phase 2 of cross-platform node-gi). Today only darwin-arm64
-// ships such a bundle (@gjsify/gtk-runtime-darwin-arm64); this is a no-op on every
-// other platform, and harmless when no bundle is present (the addon then uses the
-// host's GTK exactly as before).
+// or Homebrew GTK (Phase 2 of cross-platform node-gi). Bundles ship for darwin-arm64,
+// darwin-x64 and win32-x64 (@gjsify/gtk-runtime-<platform>-<arch>); NOTHING below
+// keys on a specific target — the tag is derived from the running process, so a new
+// bundle is found by the mechanism that found the first. This is a no-op on every
+// platform without a bundle, and harmless when no bundle is present (the addon then
+// uses the host's GTK exactly as before).
 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';
 
 // NB: node:child_process is intentionally NOT imported at module top level. It is
 // pulled in lazily (via `require` below) ONLY on the darwin re-exec path — importing
@@ -61,19 +64,36 @@ export function resolveGtkRuntimeBundle() {
 }
 
 /**
- * Make the bundled GTK runtime genuinely env-free by RE-EXECING this process once
- * with `DYLD_FALLBACK_LIBRARY_PATH` (+ `GI_TYPELIB_PATH`) pointed at the bundle.
+ * Make GTK genuinely env-free on macOS by RE-EXECING this process once with
+ * `DYLD_FALLBACK_LIBRARY_PATH` pointing at the dylibs a typelib names by bare
+ * leaf — the BUNDLED runtime when one ships, otherwise the HOST's system GI stack
+ * (`systemGiLibraryDirs()`; Homebrew at either prefix, MacPorts, custom).
  *
  * Why a re-exec and not just `process.env` mutation: on macOS, dyld captures
  * `DYLD_FALLBACK_LIBRARY_PATH` at PROCESS LAUNCH, so setting it from JS never
- * affects the running dyld. It is load-bearing beyond the addon's own link
- * closure: GObject-Introspection resolves a type's `get_type()` (e.g. for
- * `registerClass` subclassing) — and the Pango/Gdk/Graphene backers — via
+ * affects the running dyld. Measured on macOS 15.7.8 / Node 24.18.1 — mutating
+ * `process.env` before the first `requireGi('Gtk','4.0')` reproduces the failure
+ * verbatim. It is load-bearing beyond the addon's own link closure:
+ * GObject-Introspection resolves a type's `get_type()` (e.g. for `registerClass`
+ * subclassing) — and the Pango/Gdk/Graphene/GdkPixbuf backers — via
  * `g_module_open(<leaf soname>)`, and dyld will NOT satisfy a bare-leaf dlopen
- * from an `@loader_path`-loaded image. Re-launching with the fallback set (exactly
- * what the Homebrew-based CI leg does) resolves every such leaf lookup from the
- * bundle. Guarded by a sentinel env var so it fires AT MOST ONCE; a no-op unless
- * darwin + a bundle is present + the fallback does not already cover it.
+ * from an `@loader_path`-loaded image, nor from a prefix absent from its default
+ * fallback path. Re-launching with the fallback set (exactly what the
+ * Homebrew-based CI legs export by hand) resolves every such leaf lookup.
+ *
+ * ONE re-exec path for both sources, on purpose. The BUNDLE still wins whenever
+ * one is installed and its behaviour here is byte-unchanged (its libDir alone,
+ * plus the bundle's `GI_TYPELIB_PATH`) — #920 reverted making a bundle a
+ * dependency of this package precisely because an installed bundle silently beats
+ * the GTK the addon was built against, so the system branch is reached ONLY when
+ * `resolveGtkRuntimeBundle()` finds nothing and it never touches typelib
+ * resolution (the host's typelibs are already found; only the loader is blind).
+ *
+ * Sentinel-guarded so it fires AT MOST ONCE, and skipped entirely when the
+ * launching environment already covers the directories — so a CI job or a
+ * launcher that exported the variable pays nothing, and the re-exec'd child never
+ * re-execs again. A host with no GI stack under any probed or pkg-config-reported
+ * prefix yields no directories and is left byte-unchanged.
  *
  * MUST be called at module top-level BEFORE the native addon (and thus its GTK
  * dependency closure) is dlopen'd — the re-exec then loads everything correctly.
@@ -88,23 +108,45 @@ export function maybeReexecForGtkRuntime() {
     // their DYLD path for non-addon-linked backers is a documented follow-up), so the
     // darwin path can never spawn a malformed re-exec under a non-Node runtime.
     if (typeof globalThis.Bun !== 'undefined' || typeof globalThis.Deno !== 'undefined') return;
+    // GJS host mode (@gjsify/napi loads this addon inside gjs): the process is
+    // `gjs`, so process.execPath/execArgv describe an interpreter that cannot be
+    // re-launched with a Node argv — and `createRequire` there is
+    // @gjsify/module's polyfill, which rejects synchronous BUILTIN loads, so even
+    // REACHING the child_process require below would throw during module init.
+    // Nothing needs the repair anyway: gjs itself resolves these leaves (its
+    // binary carries the rpath this whole module exists to compensate for).
+    // Same probe index.js uses for RUNTIME — as with the Bun/Deno pair above, the
+    // check has to live here too because this runs before that const is defined.
+    if (typeof globalThis.imports !== 'undefined' && typeof globalThis.print === 'function') return;
     if (process.env[REEXEC_SENTINEL]) return; // already re-exec'd — the child path
+
+    // A bundle, when installed, is the whole answer and stays the ONLY entry (see
+    // the #920 note above). Without one, the host's own GI libdirs are the answer.
     const bundle = resolveGtkRuntimeBundle();
-    if (!bundle) return; // strict no-op when no bundle is present
+    const libDirs = bundle ? [bundle.libDir] : systemGiLibraryDirs();
+    if (libDirs.length === 0) return; // no bundle and no host GI stack — nothing to point at
 
     const curDyld = process.env.DYLD_FALLBACK_LIBRARY_PATH ?? '';
-    if (curDyld.split(':').filter(Boolean).includes(bundle.libDir)) return; // already covered
+    const curDyldDirs = splitSearchPath(curDyld);
+    if (pathCovers(libDirs, curDyldDirs)) return; // the launch env already covers it
 
-    // Lazily load node:child_process ONLY here (darwin + bundle present + not yet
-    // covered) — see the top-of-file note; keeps it out of non-darwin module graphs.
+    // Lazily load node:child_process ONLY here (darwin + something to point at +
+    // not yet covered) — see the top-of-file note; keeps it out of non-darwin
+    // module graphs.
     const { spawnSync } = require('node:child_process');
     const curTypelib = process.env.GI_TYPELIB_PATH ?? '';
     const env = {
         ...process.env,
         [REEXEC_SENTINEL]: '1',
-        DYLD_FALLBACK_LIBRARY_PATH: curDyld ? `${bundle.libDir}:${curDyld}` : `${bundle.libDir}:/usr/lib`,
-        GI_TYPELIB_PATH: curTypelib ? `${bundle.typelibDir}:${curTypelib}` : bundle.typelibDir,
+        // 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(':'),
     };
+    // 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.
+    if (bundle) {
+        env.GI_TYPELIB_PATH = curTypelib ? `${bundle.typelibDir}:${curTypelib}` : bundle.typelibDir;
+    }
     // Reproduce this exact invocation (node flags + argv) with the augmented env.
     const res = spawnSync(process.execPath, [...process.execArgv, ...process.argv.slice(1)], {
         stdio: 'inherit',
@@ -244,7 +286,9 @@ 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`;
+            process.env.DYLD_FALLBACK_LIBRARY_PATH = existing
+                ? `${bundle.libDir}:${existing}`
+                : `${bundle.libDir}:/usr/lib`;
         }
     }