@gjsify/node-gi 0.26.1 → 0.27.1

package/scripts/win-gi-gyp-flags.mjs

@@ -108,8 +108,7 @@ if (mode === '--includes') {
         // Last resort: locate ffi.h anywhere under the tree and add its dir.
         if (!dirs.some((d) => existsSync(join(d, 'ffi.h')))) {
             const ffiDir =
-                findHeaderDir(join(prefix, 'include'), 'ffi.h') ??
-                findHeaderDir(join(prefix, 'lib'), 'ffi.h');
+                findHeaderDir(join(prefix, 'include'), 'ffi.h') ?? findHeaderDir(join(prefix, 'lib'), 'ffi.h');
             if (ffiDir) dirs.push(ffiDir);
         }
     }
@@ -127,15 +126,7 @@ if (mode === '--includes') {
     //   cairo  the native cairo foreign-struct binding (src/cairo.cc)
     // Pango/GdkPixbuf/Graphene are NOT linked — the conformance programs load their
     // typelibs at RUNTIME (girepository dlopens the DLL by soname), not at link time.
-    const DIRECT_LIBS = [
-        'girepository-2.0',
-        'gio-2.0',
-        'gobject-2.0',
-        'gmodule-2.0',
-        'glib-2.0',
-        'ffi',
-        'cairo',
-    ];
+    const DIRECT_LIBS = ['girepository-2.0', 'gio-2.0', 'gobject-2.0', 'gmodule-2.0', 'glib-2.0', 'ffi', 'cairo'];
     // Locate the import-lib dir: GTK_PREFIX/lib, else pkg-config's -L.
     const searchDirs = [];
     if (process.env.GTK_PREFIX) searchDirs.push(join(process.env.GTK_PREFIX, 'lib'));

package/src/template.cc

@@ -6,10 +6,9 @@
 namespace nodegi {
 
 // Resolve the GTK template API once (C++11 function-local static init is
-// thread-safe; node-gi calls these only on the main thread). dlopen with
-// RTLD_NOLOAD first — requireGi('Gtk','4.0') already dlopened libgtk-4 via the
-// typelib, so this just bumps the refcount; fall back to a plain dlopen so a
-// caller that never required Gtk through the typelib still resolves the symbols.
+// thread-safe; node-gi calls these only on the main thread). How the library
+// handle is obtained — and why the leaf name has to be per-OS — is documented at
+// the dlopen below.
 const GtkTemplateApi* GetGtkTemplateApi() {
   static GtkTemplateApi api = {};
   static bool initialised = false;
@@ -22,8 +21,27 @@ const GtkTemplateApi* GetGtkTemplateApi() {
   // callers warn + no-op / throw a clear "template API unavailable" error.
   return &api;
 #else
-  void* lib = dlopen("libgtk-4.so.1", RTLD_LAZY | RTLD_NOLOAD);
-  if (lib == nullptr) lib = dlopen("libgtk-4.so.1", RTLD_LAZY);
+  // The library's LEAF NAME IS PER-OS, and hardcoding the ELF soname made the
+  // whole composite-template API unavailable on macOS: `libgtk-4.so.1` does not
+  // exist there, so every `registerClass({ Template })` widget failed with
+  // "the libgtk-4 template API is unavailable" on a host with GTK 4 correctly
+  // installed. Invisible until v0.27.0 shipped the first darwin-x64 addon.
+  //
+  // Candidates are the leaf names GTK 4 actually installs, newest ABI first.
+#ifdef __APPLE__
+  static const char* const kGtkLeaves[] = {"libgtk-4.1.dylib", "libgtk-4.dylib"};
+#else
+  static const char* const kGtkLeaves[] = {"libgtk-4.so.1", "libgtk-4.so"};
+#endif
+  void* lib = nullptr;
+  for (const char* leaf : kGtkLeaves) {
+    // RTLD_NOLOAD first — requireGi('Gtk','4.0') already dlopened libgtk-4 via the
+    // typelib, so this only bumps the refcount; the plain dlopen behind it serves a
+    // caller that never required Gtk through the typelib.
+    lib = dlopen(leaf, RTLD_LAZY | RTLD_NOLOAD);
+    if (lib == nullptr) lib = dlopen(leaf, RTLD_LAZY);
+    if (lib != nullptr) break;
+  }
   if (lib == nullptr) return &api;  // api.ok stays false → callers warn + no-op
   api.set_template = reinterpret_cast<decltype(api.set_template)>(
       dlsym(lib, "gtk_widget_class_set_template"));

package/system-gi.d.ts

@@ -0,0 +1,20 @@
+// SPDX-License-Identifier: MIT
+/** Injectable host facts for {@link systemGiLibraryDirs} — the darwin branch is testable from Linux. */
+export interface SystemGiOptions {
+    /** `process.platform` value; defaults to the running process. */
+    platform?: string;
+    /** Environment to read `GI_TYPELIB_PATH` / `PKG_CONFIG_PATH` from; defaults to `process.env`. */
+    env?: NodeJS.ProcessEnv;
+    /** Directory-existence predicate; defaults to a `statSync` probe. */
+    existsDir?: (dir: string) => boolean;
+    /** `pkg-config`'s `.pc` search directories; defaults to {@link pkgConfigSearchDirs}. */
+    searchDirs?: (env: NodeJS.ProcessEnv) => string[];
+}
+/** Split an OS search-path variable, dropping empty segments. */
+export function splitSearchPath(value: string | undefined, separator?: string): string[];
+/** `$PKG_CONFIG_PATH` plus `pkg-config`'s own `pc_path`; memoized, absent pkg-config yields just the env. */
+export function pkgConfigSearchDirs(env: NodeJS.ProcessEnv): string[];
+/** Directories holding the host's system GI shared libraries, most specific first; `[]` off darwin. */
+export function systemGiLibraryDirs(opts?: SystemGiOptions): string[];
+/** Whether a split loader path already covers every wanted directory. */
+export function pathCovers(wanted: readonly string[], current: readonly string[]): boolean;

package/system-gi.js

@@ -0,0 +1,209 @@
+// SPDX-License-Identifier: MIT
+// @gjsify/node-gi/system-gi — WHERE the host's GObject-Introspection stack keeps
+// its shared libraries, so the dynamic loader can find the ones a typelib names
+// by BARE LEAF (`libgtk-4.1.dylib`, `libgdk_pixbuf-2.0.0.dylib`, …).
+//
+// WHY THIS EXISTS — the failure it removes, measured on macOS 15.7.8 / Homebrew
+// /usr/local / Node 24.18.1 / GTK 4.22.4, the first release that shipped a
+// darwin-x64 addon:
+//
+//     GLib-GIRepository-WARNING: Failed to load shared library 'libgtk-4.1.dylib'
+//       referenced by the typelib: dlopen(libgtk-4.1.dylib, 0x0009): tried:
+//       'libgtk-4.1.dylib' (no such file), …, '/usr/lib/libgtk-4.1.dylib' (no such file)
+//     TypeError: Gtk.DrawingArea is not a subclassable GObject type
+//
+// Everything WAS installed: `/usr/local/lib/libgtk-4.1.dylib` exists and
+// `/usr/local/lib/girepository-1.0/Gtk-4.0.typelib` names exactly that leaf. The
+// gap is the LOADER, not the installation — modern dyld does not carry
+// `/usr/local/lib` in its default fallback search path, and a plain `node` has no
+// rpath there (Homebrew's own `gjs` binary does, which is why `--runtime gjs`
+// never showed this and `--runtime node` did). `gi_repository_require` resolves
+// the typelib, `g_module_open('libgtk-4.1.dylib')` then fails, no
+// `gtk_drawing_area_get_type` is ever registered, and the failure surfaces one
+// layer up as "not a subclassable GObject type".
+//
+// The value CANNOT come from `pkg-config --variable=libdir gtk4`. Measured on the
+// same host: that answers `/usr/local/Cellar/gtk4/4.22.4/lib` — a PER-FORMULA
+// directory that fixes GTK and leaves `libgdk_pixbuf-2.0.0.dylib` (a different
+// formula, so a different Cellar libdir) still unresolvable. What works is the
+// directory every keg is symlinked into, `<prefix>/lib`, because it is the UNION.
+// So the question this module answers is "which directories hold the GI stack",
+// never "where is one library".
+//
+// THE RULE — a typelib and the library it names are SIBLINGS by GI's own install
+// layout: `<libdir>/girepository-1.0/Gtk-4.0.typelib` beside
+// `<libdir>/libgtk-4.1.dylib`. A directory holding `girepository-1.0/` therefore
+// IS a GI library directory. That convention is what makes this
+// package-manager-agnostic: it lands on `/usr/local/lib` (Homebrew x64),
+// `/opt/homebrew/lib` (Homebrew arm64), `/opt/local/lib` (MacPorts) or a custom
+// prefix without needing to know that any of them exist.
+//
+// PURE FUNCTION of injected host facts (platform / env / fs / pkg-config), like
+// `hostTarget()` beside it and the CLI's `resolvePrebuildDirName()` — so the
+// darwin branch is unit-testable from a Linux host and the host values are read
+// only at the outermost call site, as defaults.
+import { statSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { basename, dirname, join } from 'node:path';
+
+const require = createRequire(import.meta.url);
+
+/**
+ * Prefixes a macOS GI stack is installed under in practice — probed, never
+ * assumed: each is accepted only when it actually holds a `girepository-1.0/`.
+ *
+ * This is the no-pkg-config safety net, and it is load-bearing rather than
+ * belt-and-braces: `brew install gtk4` installs RUNTIME dependencies only, so a
+ * user running a published showcase routinely has the entire GTK stack and no
+ * `pkg-config` at all (it is a BUILD dependency of those formulae). The
+ * pkg-config source below is the GENERAL mechanism — it is what finds a jhbuild
+ * or otherwise bespoke prefix — but it cannot be the only one.
+ * @type {Record<string, readonly string[]>}
+ */
+const PROBED_GI_LIBDIRS = {
+    darwin: ['/opt/homebrew/lib', '/usr/local/lib', '/opt/local/lib'],
+};
+
+/** The subdir GI installs typelibs into — historically `1.0` even for the girepository-2.0 API. */
+const TYPELIB_SUBDIR = 'girepository-1.0';
+
+/** Memoized `pkg-config` answer: the spawn happens at most once per process. */
+let pkgConfigDirsCache = null;
+
+/**
+ * Split an OS search-path variable, dropping empty segments.
+ * @param {string | undefined} value
+ * @param {string} [separator]
+ * @returns {string[]}
+ */
+export function splitSearchPath(value, separator = ':') {
+    return (value ?? '').split(separator).filter(Boolean);
+}
+
+/**
+ * @param {string} dir
+ * @returns {boolean}
+ */
+function isDirectory(dir) {
+    try {
+        return statSync(dir).isDirectory();
+    } catch {
+        // Any stat failure means the same thing here — ENOENT on an uninstalled
+        // prefix, EACCES on a path this process may not read: not a usable libdir.
+        return false;
+    }
+}
+
+/**
+ * `pkg-config`'s OWN configured `.pc` search path plus `$PKG_CONFIG_PATH`. Every
+ * entry is a `<libdir>/pkgconfig` (or `<datadir>/pkgconfig`) directory, so its
+ * parent is a candidate libdir — which is how a prefix nobody hardcoded is
+ * found. Measured on the reported host: `pc_path` =
+ * `/usr/local/lib/pkgconfig:/usr/local/share/pkgconfig:/usr/lib/pkgconfig:…`,
+ * whose first parent is exactly the `/usr/local/lib` that resolves every leaf.
+ *
+ * `spawnSync` reports a missing executable as `result.error`, not by throwing —
+ * an absent `pkg-config` is expected on a runtime-only GTK install, so it is a
+ * checked return value here and not an exception path.
+ * @param {NodeJS.ProcessEnv} env
+ * @returns {string[]}
+ */
+export function pkgConfigSearchDirs(env) {
+    if (pkgConfigDirsCache) return pkgConfigDirsCache;
+    const dirs = splitSearchPath(env.PKG_CONFIG_PATH);
+    // Lazily required, never imported at module top level: `index.js` deliberately
+    // keeps node:child_process out of non-darwin module graphs because an eager
+    // import tripped a Deno teardown regression on an unrelated conformance file.
+    const { spawnSync } = require('node:child_process');
+    const res = spawnSync('pkg-config', ['--variable=pc_path', 'pkg-config'], {
+        encoding: 'utf8',
+        timeout: 10_000,
+    });
+    if (!res.error && res.status === 0) dirs.push(...splitSearchPath(String(res.stdout).trim()));
+    pkgConfigDirsCache = dirs;
+    return dirs;
+}
+
+/**
+ * Directories holding the host's system GObject-Introspection shared libraries —
+ * most specific first, deduplicated, each verified on disk.
+ *
+ * Three sources, in precedence order:
+ *   1. `GI_TYPELIB_PATH` — the host stating outright where typelibs live; the
+ *      libraries are the sibling `dirname()`. Accepted on directory existence
+ *      alone: an explicit statement is not second-guessed.
+ *   2. `pkg-config`'s `.pc` search path → each `<dir>/pkgconfig`'s parent. The
+ *      general mechanism (any prefix, including a custom one).
+ *   3. {@link PROBED_GI_LIBDIRS} — the standard macOS prefixes, for the common
+ *      case where GTK is installed and pkg-config is not.
+ * Sources 2 and 3 are GUESSES at a prefix, so each must show the
+ * `girepository-1.0/` marker before it is believed.
+ *
+ * Empty off darwin, and that is a statement about LOADERS, not about GI. Linux
+ * resolves these leaves through `ld.so`'s system-wide configured cache
+ * (`/etc/ld.so.conf.d`), which a package install populates — nothing per-process
+ * is needed. dyld is the one loader that neither consults a system-wide config
+ * NOR re-reads its search path after launch, which is why darwin needs a re-exec
+ * and nobody else does.
+ *
+ * win32 is deliberately absent rather than proven unnecessary: `PATH` is the DLL
+ * search path, a Windows GTK distribution puts its `bin` there itself, and
+ * Windows re-reads that path at every `LoadLibrary` — so if a system GTK ever
+ * turns out not to be on it, the repair is an in-process `process.env.PATH`
+ * prepend (the shape `maybePrependGtkRuntimeDllPath()` already uses for the
+ * bundle), never this re-exec. Untested there, and node-gi's win32 GTK support is
+ * Phase 2 regardless.
+ * @param {object} [opts]
+ * @param {string} [opts.platform] defaults to `process.platform`
+ * @param {NodeJS.ProcessEnv} [opts.env] defaults to `process.env`
+ * @param {(dir: string) => boolean} [opts.existsDir] directory predicate (injectable for tests)
+ * @param {(env: NodeJS.ProcessEnv) => string[]} [opts.searchDirs] pkg-config `.pc` dirs (injectable)
+ * @returns {string[]} absolute directories, or `[]` when this platform's loader needs none
+ */
+export function systemGiLibraryDirs({
+    platform = process.platform,
+    env = process.env,
+    existsDir = isDirectory,
+    searchDirs = pkgConfigSearchDirs,
+} = {}) {
+    const probed = PROBED_GI_LIBDIRS[platform];
+    if (!probed) return [];
+
+    /** @type {string[]} */
+    const out = [];
+    const add = (dir) => {
+        if (dir && dir !== '/' && !out.includes(dir)) out.push(dir);
+    };
+
+    // 1. Explicit: the typelib dir's sibling libdir.
+    for (const typelibDir of splitSearchPath(env.GI_TYPELIB_PATH)) {
+        const libDir = dirname(typelibDir);
+        if (existsDir(libDir)) add(libDir);
+    }
+
+    // 2 + 3. Candidate prefixes, believed only on the girepository-1.0 marker.
+    /** @type {string[]} */
+    const candidates = [];
+    for (const pcDir of searchDirs(env)) {
+        if (basename(pcDir) === 'pkgconfig') candidates.push(dirname(pcDir));
+    }
+    candidates.push(...probed);
+    for (const libDir of candidates) {
+        if (existsDir(join(libDir, TYPELIB_SUBDIR))) add(libDir);
+    }
+
+    return out;
+}
+
+/**
+ * Whether `current` (a split `DYLD_FALLBACK_LIBRARY_PATH`) already covers every
+ * directory in `wanted` — the "nothing to do" test that keeps a correctly
+ * launched process (a CI job, or a launcher that exported the variable) from
+ * re-execing at all, and keeps a re-exec'd child from doing it twice.
+ * @param {readonly string[]} wanted
+ * @param {readonly string[]} current
+ * @returns {boolean}
+ */
+export function pathCovers(wanted, current) {
+    return wanted.every((dir) => current.includes(dir));
+}

package/system.d.ts

@@ -30,19 +30,19 @@ export function dumpMemoryInfo(): void;
 
 /** The GJS `System` module object (`import System from 'system'`). */
 export interface SystemModule {
-  exit(code?: number): void;
-  gc(): void;
-  version: number;
-  readonly programArgs: string[];
-  readonly programInvocationName: string;
-  readonly programPath: string | null;
-  addressOf(): string;
-  addressOfGObject(): string;
-  refcount(): number;
-  breakpoint(): void;
-  clearDateCaches(): void;
-  dumpHeap(): void;
-  dumpMemoryInfo(): void;
+    exit(code?: number): void;
+    gc(): void;
+    version: number;
+    readonly programArgs: string[];
+    readonly programInvocationName: string;
+    readonly programPath: string | null;
+    addressOf(): string;
+    addressOfGObject(): string;
+    refcount(): number;
+    breakpoint(): void;
+    clearDateCaches(): void;
+    dumpHeap(): void;
+    dumpMemoryInfo(): void;
 }
 
 declare const System: SystemModule;

package/system.js

@@ -35,14 +35,14 @@
 // module is loaded from `@gjsify/node-gi/globals`, before any bundle body (and
 // therefore before any register side effect) runs.
 const runtimeProcess = (() => {
-  const hostProcess = typeof process !== 'undefined' ? process : undefined;
-  try {
-    const builtin = hostProcess?.getBuiltinModule?.('node:process');
-    if (builtin && typeof builtin.exit === 'function') return builtin;
-  } catch {
-    // getBuiltinModule missing or refusing the specifier — use the captured one.
-  }
-  return hostProcess;
+    const hostProcess = typeof process !== 'undefined' ? process : undefined;
+    try {
+        const builtin = hostProcess?.getBuiltinModule?.('node:process');
+        if (builtin && typeof builtin.exit === 'function') return builtin;
+    } catch {
+        // getBuiltinModule missing or refusing the specifier — use the captured one.
+    }
+    return hostProcess;
 })();
 
 const runtimeExit = typeof runtimeProcess?.exit === 'function' ? runtimeProcess.exit.bind(runtimeProcess) : undefined;
@@ -50,17 +50,17 @@ const runtimeExit = typeof runtimeProcess?.exit === 'function' ? runtimeProcess.
 // `programArgs` mirrors GJS's ARGV: the script arguments, excluding the
 // interpreter (argv[0]) and the script path (argv[1]).
 function readProgramArgs() {
-  return Array.isArray(runtimeProcess?.argv) ? runtimeProcess.argv.slice(2) : [];
+    return Array.isArray(runtimeProcess?.argv) ? runtimeProcess.argv.slice(2) : [];
 }
 
 // `programInvocationName` / `programPath` track the running script — Node's
 // `process.argv[1]`.
 function readProgramInvocationName() {
-  return runtimeProcess?.argv?.[1] || '';
+    return runtimeProcess?.argv?.[1] || '';
 }
 
 function readProgramPath() {
-  return runtimeProcess?.argv?.[1] || null;
+    return runtimeProcess?.argv?.[1] || null;
 }
 
 /**
@@ -74,12 +74,12 @@ function readProgramPath() {
  * `conformance/programs/system-exit-lifetime.conf.mjs`).
  */
 export function exit(code) {
-  if (runtimeExit !== undefined) runtimeExit(code ?? 0);
+    if (runtimeExit !== undefined) runtimeExit(code ?? 0);
 }
 
 /** Trigger a garbage collection if the host exposed `globalThis.gc` (`--expose-gc`). */
 export function gc() {
-  if (typeof globalThis.gc === 'function') globalThis.gc();
+    if (typeof globalThis.gc === 'function') globalThis.gc();
 }
 
 /** The SpiderMonkey/mozjs version number — no equivalent on Node, reported as 0. */
@@ -96,17 +96,17 @@ export const programPath = readProgramPath();
 
 /** Return the address of a JS object as a string. No Node equivalent — stub. */
 export function addressOf() {
-  return '0x0';
+    return '0x0';
 }
 
 /** Return the address of a GObject as a string. No Node equivalent — stub. */
 export function addressOfGObject() {
-  return '0x0';
+    return '0x0';
 }
 
 /** Return the refcount of a GObject. No Node equivalent — stub. */
 export function refcount() {
-  return 0;
+    return 0;
 }
 
 /** Trigger a debugger breakpoint. No-op on Node. */
@@ -128,25 +128,25 @@ export function dumpMemoryInfo() {}
  * track the running script.
  */
 const System = {
-  exit,
-  gc,
-  version,
-  addressOf,
-  addressOfGObject,
-  refcount,
-  breakpoint,
-  clearDateCaches,
-  dumpHeap,
-  dumpMemoryInfo,
-  get programArgs() {
-    return readProgramArgs();
-  },
-  get programInvocationName() {
-    return readProgramInvocationName();
-  },
-  get programPath() {
-    return readProgramPath();
-  },
+    exit,
+    gc,
+    version,
+    addressOf,
+    addressOfGObject,
+    refcount,
+    breakpoint,
+    clearDateCaches,
+    dumpHeap,
+    dumpMemoryInfo,
+    get programArgs() {
+        return readProgramArgs();
+    },
+    get programInvocationName() {
+        return readProgramInvocationName();
+    },
+    get programPath() {
+        return readProgramPath();
+    },
 };
 
 export default System;